@intentius/chant 0.124.5 → 0.124.7

package/src/op/activities/forge-pull-request.ts

@@ -0,0 +1,98 @@
+/**
+ * Where chant's own pull-request paths open their pull request (#3798).
+ *
+ * `reconcilePr`'s `pull-request` mode, `lexiconUpgrade`, rollback and
+ * `proposeWorkspaceUpgrade` open a pull request with `gh pr`. `gh pr create`,
+ * `view`, `edit` and `list` speak GitHub's GraphQL API, which Forgejo does not
+ * serve, so #3780's `GH_HOST` sends them to the right Forgejo instance only
+ * for them to fail there. GitLab has no `gh` at all. On those two forges each
+ * path opens, finds and edits its pull request over REST through
+ * `../../pr-forge.ts` instead. GitHub, and a run outside any CI job, keep
+ * `gh` and the operator's own `gh auth login`.
+ *
+ * The forge and its token come from the CI job's environment
+ * ({@link forgeTargetFromEnv}). The repository is the one the checkout's
+ * remote names, when that remote is on the job's forge, so a path working in
+ * another checkout than the job's own still opens its pull request there.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { detectForge, forgeClient, forgeTargetFromEnv, type ForgeFetch, type PrForge, type PullRequest, type PullRequestSpec } from "../../pr-forge";
+import { remoteHost } from "./gh-host";
+
+const execFileAsync = promisify(execFile);
+
+type Env = Record<string, string | undefined>;
+
+/** The repository path a git remote URL names: `owner/name`, or `group/sub/name` on GitLab. */
+export function remoteRepoPath(url: string | undefined): string | undefined {
+  const u = url?.trim();
+  if (!u) return undefined;
+  const scp = /^[^@/\s]+@[^:/\s]+:(?!\/)(.+)$/.exec(u);
+  let path: string;
+  if (scp) path = scp[1]!;
+  else {
+    try {
+      path = new URL(u).pathname;
+    } catch {
+      return undefined;
+    }
+  }
+  const out = path.replace(/^\/+/, "").replace(/\/+$/, "").replace(/\.git$/, "");
+  return out.includes("/") ? out : undefined;
+}
+
+export interface PullRequestForgeOptions {
+  /** A checkout whose remote names the repository. Default: the job's repository. */
+  cwd?: string;
+  /** The remote in `cwd`. Default `origin`. */
+  remote?: string;
+  fetch?: ForgeFetch;
+  /** Reads a remote's URL. Default `git remote get-url`. For tests. */
+  remoteUrl?: (cwd: string, remote: string) => Promise<string | undefined>;
+}
+
+const gitRemoteUrl = async (cwd: string, remote: string): Promise<string | undefined> => {
+  try {
+    return (await execFileAsync("git", ["remote", "get-url", remote], { cwd })).stdout.trim();
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * The REST client a pull request is opened through, or undefined when `gh`
+ * serves: on GitHub, and outside a CI job. A Forgejo or GitLab job that lacks
+ * a token or a repository throws `ForgeEnvironmentError` naming it, where
+ * `gh pr` would have failed on GraphQL.
+ */
+export async function restPullRequestForge(env: Env = process.env, opts: PullRequestForgeOptions = {}): Promise<PrForge | undefined> {
+  const kind = detectForge(env);
+  if (kind !== "forgejo" && kind !== "gitlab") return undefined;
+  const target = forgeTargetFromEnv(env, { kind });
+  if (opts.cwd) {
+    const url = await (opts.remoteUrl ?? gitRemoteUrl)(opts.cwd, opts.remote ?? "origin");
+    const path = remoteRepoPath(url);
+    if (path && remoteHost(url) === target.host) target.repo = path;
+  }
+  return forgeClient(target, opts.fetch);
+}
+
+/** What {@link upsertPullRequest} did. */
+export interface UpsertedPullRequest {
+  action: "opened" | "updated" | "unchanged";
+  pr: PullRequest;
+}
+
+/**
+ * Open a pull request for `spec.head`, or bring the open one's title and
+ * body in line with `spec`. An open one already current is left alone.
+ */
+export async function upsertPullRequest(forge: PrForge, spec: PullRequestSpec): Promise<UpsertedPullRequest> {
+  const open = await forge.findPullRequest(spec.head);
+  if (!open) return { action: "opened", pr: await forge.openPullRequest(spec) };
+  if (open.title === spec.title && open.body.trim() === spec.body.trim()) return { action: "unchanged", pr: open };
+  const edited = await forge.editPullRequest(open.number, { title: spec.title, body: spec.body });
+  return { action: "updated", pr: edited ?? { ...open, title: spec.title, body: spec.body } };
+}

package/src/op/activities/lexicon-upgrade.test.ts

@@ -739,3 +739,61 @@ describe("a lexicon with several pins (#3288)", () => {
     expect(upgradePrTitle("sql", "17.11", "17.12", "postgres-17")).toBe("feat(sql): upgrade postgres-17 17.11 to 17.12");
   });
 });
+
+// ── Forgejo and GitLab open the PR over REST (#3798) ──────────────────
+
+describe("lexiconUpgrade pull request over REST", () => {
+  const pin = {
+    file: "src/pin.ts",
+    pattern: /V = "(.+)"/,
+    replace: (v: string) => `V = "${v}"`,
+    upstream: { owner: "o", repo: "r", kind: "releases" as const },
+  };
+
+  function fakeForge(open?: { number: number; url: string; body: string }) {
+    const calls: string[] = [];
+    const forge = {
+      findPullRequest: vi.fn(async (head: string) => (calls.push(`find ${head}`), open ? { ...open, title: "t", head } : undefined)),
+      openPullRequest: vi.fn(async (spec: { head: string; base?: string }) => (calls.push(`open ${spec.head} -> ${spec.base}`), { number: 5, url: "https://forge/pulls/5", title: "t", body: "b", head: spec.head })),
+      editPullRequest: vi.fn(async (n: number) => (calls.push(`edit ${n}`), undefined)),
+      addLabels: vi.fn(async (n: number, labels: readonly string[]) => void calls.push(`label ${n} ${labels.join(",")}`)),
+    };
+    return { forge: forge as unknown as import("../../pr-forge").PrForge, calls };
+  }
+
+  async function run(forge: import("../../pr-forge").PrForge) {
+    const { gh, calls } = recordingGh();
+    const dir = join(tmpdir(), `chant-3798-${process.pid}`);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "package.json"), JSON.stringify({ version: "0.1.0" }));
+    const r = await lexiconUpgrade({
+      lexicon: "k3s",
+      lexiconDir: dir,
+      mode: "pull-request",
+      _loadPin: async () => pin,
+      _checkPinned: vi.fn(async () => pinnedResult()),
+      _applyBump: vi.fn(async () => ({ filePath: "/x/src/pin.ts" })),
+      _bumpPackageVersion: vi.fn(),
+      _gh: gh,
+      _forge: forge,
+    });
+    return { r, ghCalls: calls };
+  }
+
+  test("opens the pull request and labels it through the forge, with no gh pr call", async () => {
+    const { forge, calls } = fakeForge();
+    const { r, ghCalls } = await run(forge);
+    expect(r.prUrl).toBe("https://forge/pulls/5");
+    expect(calls.filter((c) => c.startsWith("open"))).toEqual([`open ${upgradeBranchName("k3s")} -> main`]);
+    expect(calls.some((c) => c.startsWith("label"))).toBe(r.semverLabel !== undefined && r.semverLabel !== null);
+    expect(ghCalls.filter((c) => c.startsWith("gh "))).toEqual([]);
+  });
+
+  test("edits the open pull request in place of opening another", async () => {
+    const { forge, calls } = fakeForge({ number: 9, url: "https://forge/pulls/9", body: "old" });
+    const { r } = await run(forge);
+    expect(r.prUrl).toBe("https://forge/pulls/9");
+    expect(calls).toContain("edit 9");
+    expect(calls.some((c) => c.startsWith("open"))).toBe(false);
+  });
+});

package/src/op/activities/lexicon-upgrade.ts

@@ -31,6 +31,8 @@ import type { UpgradeCheckResult, LexiconId, UpstreamPin } from "../../codegen/p
 import type { RollingUpgradeResult, RollingLexicon } from "../../codegen/rolling-upgrade";
 import { bumpForSeverity, bumpPackageJsonVersion } from "../../codegen/version-bump";
 import { ghHostEnv } from "./gh-host";
+import { restPullRequestForge } from "./forge-pull-request";
+import type { PrForge } from "../../pr-forge";
 import { postOrUpdateGithubIssue } from "./reconcile";
 
 export { bumpPackageJsonVersion };
@@ -99,6 +101,12 @@ export interface LexiconUpgradeArgs {
    * Defaults to bumpPackageJsonVersion.
    */
   _bumpPackageVersion?: BumpPackageVersionFn;
+  /**
+   * The REST client the pull request is found, opened and labelled through,
+   * or null for `gh`. Default: one on a Forgejo or GitLab job, `gh`
+   * elsewhere (#3798). For tests.
+   */
+  _forge?: PrForge | null;
 }
 
 export interface LexiconUpgradeResult {
@@ -416,7 +424,8 @@ async function postLexiconIssue(
  * Check whether an open PR exists for the given branch.
  * Returns the PR URL, or null if none.
  */
-async function openPrUrl(branch: string, gh: GhRunner): Promise<string | null> {
+async function openPrUrl(branch: string, gh: GhRunner, forge?: PrForge): Promise<string | null> {
+  if (forge) return (await forge.findPullRequest(branch))?.url ?? null;
   try {
     const { stdout } = await gh(
       `gh pr view ${shellQuote(branch)} --json url,state --jq 'select(.state=="OPEN") | .url'`,
@@ -432,7 +441,8 @@ async function openPrUrl(branch: string, gh: GhRunner): Promise<string | null> {
  * Read the body of the open PR for `branch`, if any.
  * Returns null when there is no open PR or gh is unavailable.
  */
-async function currentPrBody(branch: string, gh: GhRunner): Promise<string | null> {
+async function currentPrBody(branch: string, gh: GhRunner, forge?: PrForge): Promise<string | null> {
+  if (forge) return (await forge.findPullRequest(branch))?.body.trim() || null;
   try {
     const { stdout } = await gh(
       `gh pr view ${shellQuote(branch)} --json body,state --jq 'select(.state=="OPEN") | .body'`,
@@ -750,9 +760,12 @@ export async function lexiconUpgrade(args: LexiconUpgradeArgs): Promise<LexiconU
 
   // Idempotency check: if the open PR already has this summary, nothing changed.
   // Compare trimmed — gh/git round-trips can alter trailing whitespace.
-  const existingPrBody = await currentPrBody(branch, gh);
+  // `gh pr` speaks GraphQL, which Forgejo does not serve: a Forgejo or
+  // GitLab job finds, opens and labels the pull request over REST (#3798).
+  const forge = args._forge !== undefined ? (args._forge ?? undefined) : await restPullRequestForge(process.env);
+  const existingPrBody = await currentPrBody(branch, gh, forge);
   if (existingPrBody !== null && existingPrBody.trim() === summary.trim()) {
-    const existingUrl = await openPrUrl(branch, gh);
+    const existingUrl = await openPrUrl(branch, gh, forge);
     return {
       lexicon,
       mode,
@@ -825,10 +838,23 @@ export async function lexiconUpgrade(args: LexiconUpgradeArgs): Promise<LexiconU
     });
 
     // Open or update the PR.
-    const existingUrl = await openPrUrl(branch, gh);
     let prUrl: string;
-
-    if (existingUrl) {
+    const open = forge ? await forge.findPullRequest(branch) : undefined;
+    const existingUrl = forge ? null : await openPrUrl(branch, gh);
+
+    if (forge) {
+      let pr = open;
+      if (pr) {
+        const edited = await forge.editPullRequest(pr.number, { title, body: summary });
+        prUrl = edited?.url ?? pr.url ?? "";
+      } else {
+        pr = await forge.openPullRequest({ head: branch, base: "main", title, body: summary });
+        prUrl = pr.url ?? "";
+      }
+      // Best-effort, as below. Forgejo adds only a label the repository
+      // already has; GitHub and GitLab make one.
+      if (semverLabel) await forge.addLabels(pr.number, [semverLabel]).catch(() => {/* best-effort */});
+    } else if (existingUrl) {
       await gh(`gh pr edit ${shellQuote(branch)} --title ${shellQuote(title)} --body ${shellQuote(summary)}`);
       prUrl = existingUrl;
     } else {
@@ -838,7 +864,7 @@ export async function lexiconUpgrade(args: LexiconUpgradeArgs): Promise<LexiconU
       prUrl = stdout.trim();
     }
 
-    if (semverLabel) {
+    if (semverLabel && !forge) {
       await ensureLabelOnPr(branch, semverLabel, gh);
     }
 

package/src/op/activities/propose-upgrade.ts

@@ -27,6 +27,8 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import type { StagedUpgrade } from "../../workspace/lineage-upgrade";
 import { ghHostEnv } from "./gh-host";
+import { restPullRequestForge, upsertPullRequest } from "./forge-pull-request";
+import type { PrForge } from "../../pr-forge";
 
 const execFileAsync = promisify(execFile);
 
@@ -52,6 +54,11 @@ export interface ProposeWorkspaceUpgradeArgs {
   cwd?: string;
   /** Replaces the git and gh child processes. For tests. */
   _run?: CommandRunner;
+  /**
+   * The REST client the pull request is opened through, or null for `gh`.
+   * Default: one on a Forgejo or GitLab job, `gh` elsewhere (#3798). For tests.
+   */
+  _forge?: PrForge | null;
   /** Replaces build and lint in the worktree. For tests. */
   _runChant?: import("../../workspace/lineage-upgrade").ChantRunner;
 }
@@ -198,6 +205,12 @@ export async function proposeWorkspaceUpgrade(args: ProposeWorkspaceUpgradeArgs)
     if (!hasRemote) throw new Error(`proposeWorkspaceUpgrade: no remote "${remote}" to open a pull request on`);
 
     const text = body(staged, lines);
+    // `gh pr` speaks GraphQL, which Forgejo does not serve (#3798).
+    const forge = args._forge !== undefined ? args._forge : await restPullRequestForge(process.env, { cwd: staged.repo, remote });
+    if (forge) {
+      result.prUrl = (await upsertPullRequest(forge, { head: branch, base: base!, title, body: text })).pr.url;
+      return result;
+    }
     const existing = (await run("gh", ["pr", "list", "--head", branch, "--state", "open", "--json", "url", "--jq", ".[0].url // empty"], staged.repo)).trim();
     if (existing) {
       await run("gh", ["pr", "edit", existing, "--title", title, "--body", text], staged.repo);

package/src/op/activities/reconcile.ts

@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
 import { ForgeApiError, forgejoForge, githubForge, type ForgeFetch, type GithubShapedForge } from "../../pr-forge";
 import { ghHostEnv } from "./gh-host";
+import { restPullRequestForge } from "./forge-pull-request";
 
 const execAsync = promisify(exec);
 
@@ -1363,8 +1364,15 @@ export async function reconcilePr(args: ReconcilePrArgs, signal?: AbortSignal):
   await execAsync(`git add ${shellQuote(output)}`, { signal });
   await execAsync(`git commit -m ${shellQuote(title)}`, { signal });
   await execAsync(`git push -u origin ${shellQuote(branch)}`, { signal });
-  // `gh pr create` names no host, so on GitHub Enterprise Server or Forgejo
-  // it is told the job's own (#3780). See `./gh-host.ts`.
+  // `gh pr` speaks GraphQL, which Forgejo does not serve, and GitLab has no
+  // `gh`: a Forgejo or GitLab job opens the pull request over REST (#3798).
+  const forge = await restPullRequestForge(process.env, { fetch: (url, init) => globalThis.fetch(url, { ...init, ...(signal ? { signal } : {}) }) });
+  if (forge) {
+    const pr = await forge.openPullRequest({ head: branch, title, body: summary });
+    return { mode, branch, summary, entries, prUrl: pr.url ?? "" };
+  }
+  // `gh pr create` names no host, so on GitHub Enterprise Server it is told
+  // the job's own (#3780). See `./gh-host.ts`.
   const { stdout } = await execAsync(
     `gh pr create --title ${shellQuote(title)} --body ${shellQuote(summary)} --head ${shellQuote(branch)}`,
     { signal, env: await ghHostEnv(process.env) },

package/src/op/gate-point-ci.e2e.test.ts

@@ -20,6 +20,7 @@ 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 { runWorkspaceRecords } from "../workspace/records-cli";
 import type { CommandContext } from "../cli/registry";
 import { ApplyOp } from "./composites/apply-op";
 import { memoryGateLedgerPort } from "./gate";
@@ -71,7 +72,7 @@ function clone(name: string): string {
 }
 
 /** `chant workspace points <argv>` through the command's handler, in `cwd`. Returns the document it prints. */
-async function points(cwd: string, args: Record<string, unknown>): Promise<Record<string, unknown> & { error?: { code: string } }> {
+async function points(cwd: string, args: Record<string, unknown>, handler = runWorkspacePoints): Promise<Record<string, unknown> & { error?: { code: string } }> {
   const printed: string[] = [];
   const log = vi.spyOn(console, "log").mockImplementation((line: unknown) => {
     printed.push(String(line));
@@ -79,7 +80,7 @@ async function points(cwd: string, args: Record<string, unknown>): Promise<Recor
   const was = process.cwd();
   process.chdir(cwd);
   try {
-    await runWorkspacePoints({ args, plugins: [], serializers: [] } as unknown as CommandContext);
+    await handler({ args, plugins: [], serializers: [] } as unknown as CommandContext);
   } finally {
     process.chdir(was);
     log.mockRestore();
@@ -169,3 +170,39 @@ describe("a gate's question outlives the CI job that asked it (#3815)", () => {
     expect(answersIn(tree)).toHaveLength(1);
   });
 });
+
+describe("chant workspace records lists the answers held on chant/lifecycle (#3833)", () => {
+  type Rec = { id: string; path: string; state: string; data: { answer?: unknown }; ledger?: string | null; worktree?: string };
+  const answerRecords = (set: Record<string, unknown>): Rec[] => {
+    const kinds = set.kinds as { kind: { name: string }; records: Rec[] }[];
+    return kinds.find((k) => k.kind.name === "answer")!.records;
+  };
+
+  test("an answer asked and answered on the ledger is listed with the id, state and answer points shows", async () => {
+    vi.stubEnv("CI", "");
+    const op = config("records-apply", { name: "prod-apply", store: "ledger" });
+    const first = await run(op, clone("records-job"));
+    expect(first.status).toBe("waiting");
+    const id = first.point!.id;
+    expect(await points(clone("records-person"), { extraPositional: "answer", extraPositional2: id, answer: "yes", bys: ["alice"] })).toMatchObject({ written: true });
+
+    // A clone that never held chant/lifecycle: records fetches it, as points answer does.
+    const reader = clone("records-reader");
+    const listed = answerRecords(await points(reader, { json: true }, runWorkspaceRecords)).find((r) => r.id === id);
+    expect(listed).toMatchObject({ id, state: "answered", data: { answer: true }, ledger: expect.stringContaining("chant/lifecycle:") });
+    expect(listed!.worktree).toBeUndefined();
+
+    const doc = (await points(reader, { json: true })) as { questions: { id: string; state: string; answer: unknown; ledger: string | null; path: string }[] };
+    const question = doc.questions.find((q) => q.id === id)!;
+    expect({ id: listed!.id, state: listed!.state, answer: listed!.data.answer, ledger: listed!.ledger, path: listed!.path }).toEqual({
+      id: question.id,
+      state: question.state,
+      answer: question.answer,
+      ledger: question.ledger,
+      path: question.path,
+    });
+
+    // The checkout doesn't hold it: --uncommitted leaves it out, and the text output says where it is.
+    expect(answerRecords(await points(reader, { json: true, uncommitted: true }, runWorkspaceRecords)).map((r) => r.id)).not.toContain(id);
+  });
+});

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

@@ -0,0 +1,203 @@
+/**
+ * #3835: an answered decision point resumes the job waiting on it. A gate
+ * that asks a point writes its resolution only when the run asks again, so
+ * `chant run resume` used to see no approval and leave the job stopped. Now a
+ * pending fact that cites a question is resumable once the question has an
+ * answer the gate passes on, and `points answer --resume` resumes right after
+ * the answer.
+ *
+ * Clones of one bare remote stand for the CI job's checkout, the person's
+ * clone the answer comes from, the scheduled resume job's checkout and the
+ * resumed job's. The gate ledger is the real one on `chant/lifecycle`, so the
+ * pending fact, the question and its answer all travel through the remote.
+ * The forge is a stubbed `fetch` that answers as GitHub does for a failed run.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
+import { cleanScratch, workspace } from "../workspace/__fixtures__/decide-workspace";
+import { runWorkspacePoints } from "../workspace/points-cli";
+import { runResumeCommand } from "../cli/handlers/gate-resume";
+import type { CommandContext } from "../cli/registry";
+import { readGateLedger } from "../lifecycle/gate-ledger";
+import { pointGateResumable } from "../point-decision";
+import { ApplyOp } from "./composites/apply-op";
+import { gitGateLedgerPort } from "./gate";
+import type { GatePoint } from "./gate-point";
+import { runOpLocally } from "./local-executor";
+import type { ActivityFn } from "./activity-registry";
+import type { OpConfig } from "./types";
+
+const PLAN = `jcs1-sha256:${"6".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: 1 }],
+    },
+  },
+};
+
+const GITHUB = { GITHUB_ACTIONS: "true", GITHUB_REPOSITORY: "acme/infra", GITHUB_RUN_ID: "42", GITHUB_RUN_ATTEMPT: "1", GITHUB_API_URL: "https://api.github.test" };
+
+const applied: string[] = [];
+const activities = new Map<string, ActivityFn>([
+  ["chantBuild", async () => ({ ok: true })],
+  ["lifecycleDiff", async () => ({ planDigest: PLAN, drifted: true })],
+  ["nativeApply", async () => {
+    applied.push(PLAN);
+    return { ok: true };
+  }],
+]);
+
+const config = (name: string, point: GatePoint): OpConfig =>
+  (ApplyOp({ name, env: "prod", target: "kubectl", gate: { gate: "approve-apply", point } }).op as unknown as { props: OpConfig }).props;
+
+let home: string;
+let remote: string;
+let n = 0;
+
+function clone(): string {
+  const dir = join(home, `clone-${++n}`);
+  execFileSync("git", ["clone", "-q", remote, dir], { stdio: "ignore" });
+  return dir;
+}
+
+/** A wave's run in `cwd`, on the real gate ledger. */
+const run = (op: OpConfig, cwd: string) => runOpLocally(op, activities, {}, undefined, { gates: gitGateLedgerPort({ cwd }), cwd, now: new Date().toISOString() });
+
+/** Run a command handler in `cwd`; returns what it printed on standard output, parsed, and its exit code. */
+async function inDir<T>(cwd: string, handler: (ctx: CommandContext) => Promise<number>, args: Record<string, unknown>): Promise<{ code: number; doc: T }> {
+  const printed: string[] = [];
+  const log = vi.spyOn(console, "log").mockImplementation((line: unknown) => {
+    printed.push(String(line));
+  });
+  const err = vi.spyOn(console, "error").mockImplementation(() => undefined);
+  const was = process.cwd();
+  process.chdir(cwd);
+  try {
+    const code = await handler({ args, plugins: [], serializers: [] } as unknown as CommandContext);
+    return { code, doc: JSON.parse(printed.join("\n")) as T };
+  } finally {
+    process.chdir(was);
+    log.mockRestore();
+    err.mockRestore();
+  }
+}
+
+/** The forge: a GitHub run that ended in failure (the job exited 3 at the gate). Records each call. */
+let calls: string[];
+function stubForge(): void {
+  calls = [];
+  vi.stubGlobal("fetch", async (url: string, init: { method: string }) => {
+    calls.push(`${init.method} ${new URL(url).pathname}`);
+    const body = init.method === "GET" ? JSON.stringify({ status: "completed", conclusion: "failure", run_attempt: 1 }) : "";
+    return { ok: true, status: 200, text: async () => body };
+  });
+}
+
+type Report = { op: string; gate: string; status: string; message: string; approvedBy?: string };
+
+/** The job waits at the gate in CI; returns the question's id. */
+async function waitInCi(op: OpConfig): Promise<string> {
+  for (const [k, v] of Object.entries(GITHUB)) vi.stubEnv(k, v);
+  const first = await run(op, clone());
+  expect(first.status).toBe("waiting");
+  for (const k of Object.keys(GITHUB)) vi.stubEnv(k, "");
+  return first.point!.id;
+}
+
+const answer = (id: string, value: string, extra: Record<string, unknown> = {}) =>
+  inDir<Record<string, unknown>>(clone(), runWorkspacePoints, { extraPositional: "answer", extraPositional2: id, answer: value, bys: ["alice"], ...extra });
+
+beforeAll(() => {
+  home = realpathSync(mkdtempSync(join(tmpdir(), "chant-gate-point-resume-")));
+  const root = workspace(POINTS);
+  remote = join(home, "remote.git");
+  execFileSync("git", ["clone", "-q", "--bare", root, remote], { stdio: "ignore" });
+});
+
+beforeEach(() => {
+  vi.stubEnv("CI", "");
+  vi.stubEnv("GITHUB_TOKEN", "t");
+  stubForge();
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.unstubAllGlobals();
+});
+
+afterAll(() => {
+  cleanScratch();
+  rmSync(home, { recursive: true, force: true });
+});
+
+describe("an answered decision point resumes the wave waiting on it (#3835)", () => {
+  test("the wave waits on its point; the point is answered; chant run resume resumes it, and the resumed run passes", async () => {
+    const op = config("resume-apply", { name: "prod-apply", store: "ledger" });
+    const id = await waitInCi(op);
+
+    // Before the answer, nothing is resumed.
+    const before = await inDir<{ reports: Report[] }>(clone(), runResumeCommand, { op: "resume-apply", json: true });
+    expect(before.doc.reports).toEqual([expect.objectContaining({ gate: "approve-apply", status: "not-approved", message: expect.stringContaining("not answered yet") })]);
+    expect(calls).toEqual([]);
+
+    expect((await answer(id, "yes")).doc).toMatchObject({ written: true, question: { state: "answered", answer: true } });
+
+    // The scheduled resume job, in its own checkout.
+    const resumed = await inDir<{ reports: Report[] }>(clone(), runResumeCommand, { op: "resume-apply", json: true });
+    expect(resumed.code).toBe(0);
+    expect(resumed.doc.reports).toEqual([expect.objectContaining({ gate: "approve-apply", status: "resumed", approvedBy: "alice" })]);
+    expect(calls).toEqual(["GET /repos/acme/infra/actions/runs/42", "POST /repos/acme/infra/actions/runs/42/rerun-failed-jobs"]);
+
+    // The resumed job asks again, finds the answer, writes the resolution that cites it, and applies.
+    const job = clone();
+    const next = await run(op, job);
+    expect(next.status).toBe("ok");
+    expect(applied).toContain(PLAN);
+    const ledger = await readGateLedger("resume-apply", { cwd: job });
+    expect(ledger.resolutions).toEqual([expect.objectContaining({ gate: "approve-apply", resolvedBy: "alice", answer: expect.objectContaining({ id, answer: true }) })]);
+  }, 120_000);
+
+  test("an answer that does not pass the gate resumes nothing", async () => {
+    const op = config("refuse-apply", { name: "prod-apply", store: "ledger" });
+    const id = await waitInCi(op);
+    await answer(id, "no");
+
+    const resumed = await inDir<{ reports: Report[] }>(clone(), runResumeCommand, { op: "refuse-apply", json: true });
+    expect(resumed.code).toBe(0);
+    expect(resumed.doc.reports).toEqual([expect.objectContaining({ status: "not-approved", message: expect.stringContaining("passes only on true") })]);
+    expect(calls).toEqual([]);
+  }, 120_000);
+
+  test("a gate's own pass list is on the pending fact: an answer it names resumes, others don't", async () => {
+    const op = config("pass-apply", { name: "prod-apply", store: "ledger", pass: [false] });
+    const id = await waitInCi(op);
+    const { pending } = await gitGateLedgerPort({ cwd: clone() }).read("pass-apply");
+    expect(pending[0]!.answer).toMatchObject({ id, pass: [false] });
+    expect(pending[0]!.resume).toMatchObject({ forge: "github", run: "42" });
+
+    const answered = { id, state: "answered" as const, answeredBy: ["alice"], answeredOn: null };
+    expect(pointGateResumable(pending[0]!, { ...answered, answer: false })).toMatchObject({ resumable: true, answeredBy: "alice" });
+    expect(pointGateResumable(pending[0]!, { ...answered, answer: true })).toMatchObject({ resumable: false, why: "refused" });
+    expect(pointGateResumable(pending[0]!, { ...answered, state: "escalated", answer: null })).toMatchObject({ resumable: false, why: "open" });
+    expect(pointGateResumable(pending[0]!, undefined)).toMatchObject({ resumable: false, why: "unknown" });
+  }, 120_000);
+
+  test("points answer --resume resumes the job waiting at the gate the question names", async () => {
+    const op = config("answer-resume-apply", { name: "prod-apply", store: "ledger" });
+    const id = await waitInCi(op);
+
+    const answered = await answer(id, "yes", { resumeRun: true });
+    expect(answered.code).toBe(0);
+    expect(answered.doc).toMatchObject({ written: true, question: { state: "answered", subject: "gate:answer-resume-apply/approve-apply" } });
+    expect(calls).toEqual(["GET /repos/acme/infra/actions/runs/42", "POST /repos/acme/infra/actions/runs/42/rerun-failed-jobs"]);
+  }, 120_000);
+});

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

@@ -32,7 +32,10 @@ import type { GatePointAsker } from "../point-decision";
 // The decision itself bundles without the workspace (#3816): `@intentius/chant/point-decision`.
 export {
   evaluatePointGate,
+  pointGateResumable,
   type GatePointAsker,
+  type PointQuestionState,
+  type PointResumeCheck,
   type GatePointQuestion,
   type GatePointRequest,
   type PointGateCheck,

package/src/op/gate-point.ts

@@ -141,3 +141,14 @@ export function gatePointInputs(point: string, declared: readonly string[], fact
 export function gateSubject(op: string, gate: string, env?: string | null): string {
   return `gate:${op}/${gate}${env ? `@${env}` : ""}`;
 }
+
+/** The gate a {@link gateSubject} names, or undefined for a subject that names none (#3835). */
+export function parseGateSubject(subject: string | null | undefined): { op: string; gate: string; env?: string } | undefined {
+  if (!subject || !subject.startsWith("gate:")) return undefined;
+  const rest = subject.slice("gate:".length);
+  const at = rest.lastIndexOf("@");
+  const named = at > 0 ? rest.slice(0, at) : rest;
+  const slash = named.indexOf("/");
+  if (slash <= 0 || slash === named.length - 1) return undefined;
+  return { op: named.slice(0, slash), gate: named.slice(slash + 1), ...(at > 0 ? { env: rest.slice(at + 1) } : {}) };
+}