@intentius/chant 0.123.0 → 0.124.1

package/src/op/op-waves.test.ts

@@ -3,7 +3,18 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { assertOpWavesSpec, opWaveJobs, opWaveShare, type OpWavesSpec } from "./op-waves";
-import { recordOpWaveHeadPlans, runOpWave, type OpWaveExec, type OpWaveRunsFile, type OpWaveShowAtBase } from "./op-waves-run";
+import {
+  opWaveHooksAtBase,
+  readOpWaveHooksFile,
+  recordOpWaveHeadPlans,
+  runOpWave,
+  runOpWaveApplyHooks,
+  type OpWaveDecision,
+  type OpWaveExec,
+  type OpWaveHooksFile,
+  type OpWaveRunsFile,
+  type OpWaveShowAtBase,
+} from "./op-waves-run";
 import { memoryGateLedgerPort } from "./gate";
 import { waveSetDigest } from "../gated-waves";
 
@@ -473,3 +484,182 @@ describe("spent approvals (#3784)", () => {
     h.done();
   });
 });
+
+describe("apply-stage hooks run by the apply, under its lock (#3804)", () => {
+  const digest = (n: string) => `sha256:${n.repeat(64)}`;
+  const spec: OpWavesSpec = {
+    name: "migrations",
+    op: "migrate",
+    plan: ["tool", "plan", "{target}", "{plan}"],
+    apply: ["tool", "apply", "{target}", "{plan}"],
+    hooks: { apply: { runBy: "apply" }, before: { plan: [{ name: "lint", command: ["hook", "lint"] }] } },
+    waves: [
+      {
+        name: "prod",
+        runs: [{ target: "t1" }],
+        gate: "never",
+        hooks: {
+          before: { apply: [{ name: "lag", command: ["hook", "lag", "{target}"], perRun: true, onFailure: "approve" }] },
+          after: { apply: [{ name: "smoke", command: ["hook", "smoke", "{wave}"] }] },
+        },
+      },
+    ],
+  };
+
+  /**
+   * A job whose apply command is a product that takes its lock and runs the
+   * hooks it was handed, as SQL Yodeler's apply would. `obey: false` is an
+   * apply that ignores the hooks file.
+   */
+  function harness(atBase: OpWavesSpec | null, opts: { fails?: string[]; obey?: boolean } = {}) {
+    const cwd = mkdtempSync(join(tmpdir(), "op-waves-by-apply-"));
+    const calls: string[] = [];
+    const files: OpWaveHooksFile[] = [];
+    const inner: OpWaveExec = (argv) => {
+      calls.push(`  ${argv.join(" ")}`);
+      return (opts.fails ?? []).some((f) => argv.join(" ").startsWith(f)) ? 1 : 0;
+    };
+    const exec: OpWaveExec = (argv, dir, env) => {
+      calls.push(argv.join(" "));
+      if (argv[1] === "plan") writeFileSync(join(dir, argv[3]!), JSON.stringify({ planDigest: digest("1") }));
+      if (argv[1] === "apply") {
+        const file = readOpWaveHooksFile(env?.CHANT_HOOKS, dir)!;
+        files.push(file);
+        if (opts.obey === false) return 0;
+        calls.push("  lock");
+        const before = runOpWaveApplyHooks(file, "before-apply", { cwd: dir, exec: inner, log: () => {} });
+        if (!before.proceed) return before.held.length > 0 ? 3 : 4;
+        calls.push("  migrate");
+        const after = runOpWaveApplyHooks(file, "after-apply", { cwd: dir, exec: inner, log: () => {} });
+        return after.proceed ? 0 : 1;
+      }
+      return (opts.fails ?? []).some((f) => argv.join(" ").startsWith(f)) ? 1 : 0;
+    };
+    const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: atBase === null ? null : JSON.stringify(atBase) });
+    const record = () => JSON.parse(readFileSync(join(cwd, ".chant/op-waves/migrations/wave-1.json"), "utf-8")) as OpWaveDecision;
+    return { cwd, calls, files, exec, show, record, done: () => rmSync(cwd, { recursive: true, force: true }) };
+  }
+  const set = waveSetDigest([{ member: "t1", planDigest: digest("1") }]);
+
+  test("the spec checks hooks.apply.runBy and keeps the rest as it was", () => {
+    const base = { name: "w", op: "o", plan: ["p", "{plan}"], waves: [{ name: "dev", runs: [{ target: "a" }] }] };
+    expect(() => assertOpWavesSpec({ ...base, hooks: { apply: { runBy: "apply" } } })).not.toThrow();
+    expect(() => assertOpWavesSpec({ ...base, hooks: { apply: { runBy: "later" } } } as unknown as OpWavesSpec)).toThrow(/hooks.apply.runBy is "later"/);
+    expect(() => assertOpWavesSpec({ ...base, hooks: { apply: [{ command: ["x"] }] } } as unknown as OpWavesSpec)).toThrow(/hooks.apply must be/);
+  });
+
+  test("chant hands the apply-stage hooks to the apply, which runs them under its lock; the outcomes come back", async () => {
+    const h = harness(spec);
+    const result = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() });
+    expect(result).toMatchObject({ exitCode: 0, applied: ["t1"], decision: { applyHooksRunBy: "apply" } });
+    expect(h.calls).toEqual([
+      "hook lint",
+      "tool plan t1 .chant/op-waves/migrations/wave-1/t1.plan.json",
+      "tool apply t1 .chant/op-waves/migrations/wave-1/t1.plan.json",
+      "  lock",
+      "  hook lag t1",
+      "  migrate",
+      "  hook smoke prod",
+    ]);
+    // The apply sees the outcomes of the hooks chant ran before it, and the hooks it runs itself.
+    expect(h.files[0]).toMatchObject({ runBy: "apply", approved: false, digest: set, outcomes: [{ moment: "before-plan", name: "lint", outcome: "passed" }] });
+    expect(Object.keys(h.files[0]!.hooks)).toEqual(["before-apply", "after-apply"]);
+    expect(result.hooks.map((o) => `${o.moment} ${o.name} ${o.outcome}`)).toEqual(["before-plan lint passed", "before-apply lag passed", "after-apply smoke passed"]);
+    expect(h.record().outcomes).toHaveLength(3);
+    h.done();
+  });
+
+  test("a hold inside the apply applies nothing and waits; with an approval of the digest the apply is called again and goes on", async () => {
+    const h = harness(spec, { fails: ["hook lag"] });
+    const waiting = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() });
+    expect(waiting).toMatchObject({ exitCode: 3, applied: [], decision: { status: "waiting", heldBy: ["before-apply hook lag (t1)"] } });
+    expect(h.calls).not.toContain("  migrate");
+    h.done();
+
+    const again = harness(spec, { fails: ["hook lag"] });
+    const gates = memoryGateLedgerPort({ resolutions: [{ version: 1, op: "migrations", gate: "migrations-wave-1", resolvedBy: "alice", timestamp: "2026-10-10T00:00:00Z", planDigest: set }] });
+    const applied = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: again.cwd, exec: again.exec, show: again.show, gates });
+    expect(applied).toMatchObject({ exitCode: 0, applied: ["t1"], decision: { status: "approved", approvedBy: "alice" } });
+    expect(again.calls.filter((c) => c === "  lock")).toHaveLength(2);
+    expect(again.calls.filter((c) => c === "  migrate")).toHaveLength(1);
+    // The second call knows the approval stands, and which hook held the wave.
+    expect(again.files[1]).toMatchObject({ approved: true, heldBy: ["before-apply hook lag (t1)"] });
+    expect(applied.hooks.filter((o) => o.name === "lag").map((o) => o.outcome)).toEqual(["held", "held"]);
+    again.done();
+  });
+
+  test("an after-apply failure inside the apply counts the run applied and fails the wave", async () => {
+    const h = harness(spec, { fails: ["hook smoke"] });
+    const result = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() });
+    expect(result).toMatchObject({ exitCode: 1, applied: ["t1"], failed: [] });
+    expect(result.hooks.at(-1)).toMatchObject({ moment: "after-apply", name: "smoke", outcome: "failed" });
+    h.done();
+  });
+
+  test("an apply that ignores the hooks it was handed fails the wave", async () => {
+    const h = harness(spec, { obey: false });
+    const logs: string[] = [];
+    const result = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort(), log: (l) => logs.push(l) });
+    expect(result).toMatchObject({ exitCode: 1, applied: ["t1"] });
+    expect(logs.join("\n")).toMatch(/without running its before-apply and after-apply hooks/);
+    h.done();
+  });
+
+  test("runBy is read at base: a change that sets it still has chant run the hooks, and the apply gets its outcomes", async () => {
+    const atBase: OpWavesSpec = { ...spec, hooks: { before: spec.hooks!.before } };
+    const h = harness(atBase);
+    const result = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort(), log: () => {} });
+    expect(result.exitCode).toBe(0);
+    expect(h.calls.slice(0, 4)).toEqual(["hook lint", "tool plan t1 .chant/op-waves/migrations/wave-1/t1.plan.json", "hook lag t1", "tool apply t1 .chant/op-waves/migrations/wave-1/t1.plan.json"]);
+    expect(h.files[0]).toMatchObject({ runBy: "chant", hooks: {} });
+    expect(h.files[0]!.outcomes.map((o) => o.name)).toEqual(["lint", "lag"]);
+    h.done();
+  });
+
+  test("an apply that skips both moments for an empty run exits the wave ok, and the skip is recorded (#3811)", async () => {
+    const h = harness(spec);
+    const exec: OpWaveExec = (argv, dir, env) => {
+      if (argv[1] === "plan") writeFileSync(join(dir, argv[3]!), JSON.stringify({ planDigest: digest("1") }));
+      if (argv[1] === "apply") {
+        const file = readOpWaveHooksFile(env?.CHANT_HOOKS, dir)!;
+        runOpWaveApplyHooks(file, "before-apply", { cwd: dir, skip: "nothing to apply", log: () => {} });
+        runOpWaveApplyHooks(file, "after-apply", { cwd: dir, skip: "nothing to apply", log: () => {} });
+      }
+      return 0;
+    };
+    const result = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec, show: h.show, gates: memoryGateLedgerPort(), log: () => {} });
+    expect(result).toMatchObject({ exitCode: 0, applied: ["t1"] });
+    const skipped = [
+      { moment: "before-apply", name: "skip", exit: 0, outcome: "skipped", reason: "nothing to apply" },
+      { moment: "after-apply", name: "skip", exit: 0, outcome: "skipped", reason: "nothing to apply" },
+    ];
+    expect(result.hooks.filter((o) => o.outcome === "skipped")).toEqual(skipped);
+    expect(h.record().outcomes).toEqual(expect.arrayContaining(skipped));
+    h.done();
+  });
+
+  test("a skip with no reason is refused", () => {
+    const h = harness(spec);
+    writeFileSync(join(h.cwd, "waves.json"), JSON.stringify(spec));
+    const file = opWaveHooksAtBase({ specFile: "waves.json", wave: "prod", cwd: h.cwd, show: h.show });
+    expect(() => runOpWaveApplyHooks(file, "before-apply", { cwd: h.cwd, skip: "  ", log: () => {} })).toThrow(/needs a reason/);
+    h.done();
+  });
+
+  test("an apply outside the waves reads the same hooks at base and runs them itself; a hold stops it", () => {
+    const h = harness(spec);
+    writeFileSync(join(h.cwd, "waves.json"), JSON.stringify({ ...spec, hooks: undefined, waves: [{ ...spec.waves[0]!, hooks: undefined }] }));
+    const file = opWaveHooksAtBase({ specFile: "waves.json", wave: "prod", cwd: h.cwd, show: h.show, base: "HEAD^1" });
+    expect(file).toMatchObject({ opWaves: "migrations", wave: "prod", number: 1, approved: false, runBy: "apply", runs: [{ target: "t1", op: "migrate" }] });
+    expect(Object.keys(file.hooks)).toEqual(["before-plan", "before-apply", "after-apply"]);
+    const ran: string[] = [];
+    const exec: OpWaveExec = (argv) => (ran.push(argv.join(" ")), argv[1] === "lag" ? 1 : 0);
+    const before = runOpWaveApplyHooks(file, "before-apply", { cwd: h.cwd, exec, log: () => {} });
+    expect(before).toMatchObject({ proceed: false, held: ["before-apply hook lag (t1)"], outcomes: [{ name: "lag", target: "t1", exit: 1, outcome: "held" }] });
+    expect(runOpWaveApplyHooks(file, "after-plan", { cwd: h.cwd, exec, log: () => {} })).toMatchObject({ proceed: true, outcomes: [] });
+    expect(ran).toEqual(["hook lag t1"]);
+    const absent = opWaveHooksAtBase({ specFile: "waves.json", wave: "prod", cwd: h.cwd, show: () => ({ sha: "c".repeat(40), text: null }) });
+    expect(absent.hooks).toEqual({});
+    h.done();
+  });
+});

package/src/op/op-waves.ts

@@ -107,10 +107,22 @@ export type OpWaveHookMoment = "before-plan" | "after-plan" | "before-apply" | "
 
 export const OP_WAVE_HOOK_MOMENTS: readonly OpWaveHookMoment[] = ["before-plan", "after-plan", "before-apply", "after-apply"];
 
+/**
+ * Who runs the `before.apply` and `after.apply` hooks (#3804). `chant`: the
+ * wave job, around the apply command. `apply`: the apply command itself,
+ * under its own lock, through `runOpWaveApplyHooks` and the file named by
+ * `CHANT_HOOKS`; it writes the outcomes back to `CHANT_HOOKS_RESULT`.
+ */
+export type OpWaveApplyHooksRunner = "chant" | "apply";
+
+export const OP_WAVE_APPLY_HOOKS_RUNNERS: readonly OpWaveApplyHooksRunner[] = ["chant", "apply"];
+
 /** Stage hooks (#3762), read from the spec at the base commit like the gate policy. */
 export interface OpWaveHooks {
   before?: { plan?: OpWaveHook[]; apply?: OpWaveHook[] };
   after?: { plan?: OpWaveHook[]; apply?: OpWaveHook[] };
+  /** Who runs the apply-stage hooks (#3804). Default `{ runBy: "chant" }`. A wave's own setting wins over the spec's. */
+  apply?: { runBy?: OpWaveApplyHooksRunner };
 }
 
 /** One Op run in a wave: an Op applied to one target (an environment, a database, a tenant). */
@@ -367,7 +379,17 @@ export function assertOpWaveHooks(where: string, hooks: OpWaveHooks | undefined)
     throw new Error(`${where}: \`hooks\` must be { "before"?: { "plan"?, "apply"? }, "after"?: { "plan"?, "apply"? } }.`);
   }
   for (const [side, stages] of Object.entries(hooks as Record<string, unknown>)) {
-    if (side !== "before" && side !== "after") throw new Error(`${where}: hooks.${side} is not a moment; use hooks.before or hooks.after.`);
+    if (side === "apply") {
+      const runBy = (stages as { runBy?: unknown } | null)?.runBy;
+      if (stages === null || typeof stages !== "object" || Array.isArray(stages) || Object.keys(stages).some((key) => key !== "runBy")) {
+        throw new Error(`${where}: hooks.apply must be { "runBy"?: "chant" | "apply" }.`);
+      }
+      if (runBy !== undefined && !OP_WAVE_APPLY_HOOKS_RUNNERS.includes(runBy as OpWaveApplyHooksRunner)) {
+        throw new Error(`${where}: hooks.apply.runBy is ${JSON.stringify(runBy)}; use ${OP_WAVE_APPLY_HOOKS_RUNNERS.map((r) => `"${r}"`).join(" or ")}.`);
+      }
+      continue;
+    }
+    if (side !== "before" && side !== "after") throw new Error(`${where}: hooks.${side} is not a moment; use hooks.before or hooks.after (or hooks.apply.runBy).`);
     if (stages === null || typeof stages !== "object" || Array.isArray(stages)) throw new Error(`${where}: hooks.${side} must be { "plan"?: [...], "apply"?: [...] }.`);
     for (const [stage, list] of Object.entries(stages as Record<string, unknown>)) {
       const at = `hooks.${side}.${stage}`;
@@ -405,6 +427,12 @@ export function opWaveHooksAt(spec: Pick<OpWavesSpec, "hooks" | "waves">, name:
   return Object.fromEntries(OP_WAVE_HOOK_MOMENTS.map((m) => [m, [...at(spec.hooks, m), ...at(wave?.hooks, m)]])) as Record<OpWaveHookMoment, OpWaveHook[]>;
 }
 
+/** Who runs wave `name`'s apply-stage hooks (#3804): the wave's `hooks.apply.runBy`, else the spec's, else `chant`. */
+export function opWaveApplyHooksRunBy(spec: Pick<OpWavesSpec, "hooks" | "waves">, name: string): OpWaveApplyHooksRunner {
+  const wave = spec.waves.find((w) => w.name === name);
+  return wave?.hooks?.apply?.runBy ?? spec.hooks?.apply?.runBy ?? "chant";
+}
+
 /**
  * The runs share `share` (1-based) of `shares` applies: the wave's runs sorted
  * by target, cut into contiguous slices whose sizes differ by at most one.

package/src/pr-forge.test.ts

@@ -361,6 +361,52 @@ describe("upsertComment (#3759)", () => {
   });
 });
 
+describe("findComment (#3802)", () => {
+  const gh = { apiBase: "https://api.github.com", repo: "acme/infra", token: "t0k" };
+
+  test("reads back the comment upsertComment would update, author honoured, oldest first", async () => {
+    const { fetch, calls } = fakeFetch({
+      "GET /repos/acme/infra/issues/12/comments": [
+        { id: 1, body: "<!-- y -->\nsubject: planted", user: { login: "mallory" } },
+        { id: 5, body: "<!-- y -->\nsubject: newer", user: { login: "yodel-bot" }, html_url: "https://h/5" },
+        { id: 3, body: "<!-- y -->\nsubject: abc", user: { login: "Yodel-Bot" }, html_url: "https://h/3" },
+      ],
+    });
+    const forge = githubForge({ ...gh, fetch });
+    expect(await forge.findComment(12, "<!-- y -->", { author: "yodel-bot" })).toEqual({ id: 3, body: "<!-- y -->\nsubject: abc", url: "https://h/3" });
+    expect((await forge.findComment(12, "<!-- y -->"))?.id).toBe(1);
+    expect(await forge.findComment(12, "<!-- other -->")).toBeUndefined();
+    expect(calls.every((c) => c.method === "GET")).toBe(true);
+  });
+
+  test("Forgejo pages with limit, and anywhere finds a marker inside the body", async () => {
+    const { fetch, calls } = fakeFetch({
+      "GET /api/v1/repos/acme/infra/issues/4/comments": [{ id: 7, body: "plan\n<!-- y -->", user: { login: "bot" }, html_url: "https://cb/7" }],
+    });
+    const forge = forgejoForge({ ...gh, apiBase: "https://codeberg.org/api/v1", host: "codeberg.org", fetch });
+    expect(await forge.findComment(4, "<!-- y -->", { match: "anywhere" })).toEqual({ id: 7, body: "plan\n<!-- y -->", url: "https://cb/7" });
+    expect(await forge.findComment(4, "<!-- y -->")).toBeUndefined();
+    expect(new URL(calls[0].url).searchParams.get("limit")).toBe("50");
+  });
+
+  test("GitLab skips system notes and reads the note without a URL", async () => {
+    const { fetch } = fakeFetch({
+      "GET /api/v4/projects/42/merge_requests/5/notes": [
+        { id: 30, body: "<!-- y -->\nsys", system: true },
+        { id: 31, body: "<!-- y -->\nmine", author: { username: "bot" } },
+      ],
+    });
+    const forge = gitlabForge({ apiBase: "https://gitlab.example.com/api/v4", project: "42", token: "glpat", fetch });
+    expect(await forge.findComment(5, "<!-- y -->", { author: "bot" })).toEqual({ id: 31, body: "<!-- y -->\nmine" });
+  });
+
+  test("an empty marker is refused", async () => {
+    const { fetch, calls } = fakeFetch({});
+    await expect(githubForge({ ...gh, fetch }).findComment(12, "")).rejects.toThrow(/needs a marker/);
+    expect(calls).toEqual([]);
+  });
+});
+
 describe("trackIssue (#3759)", () => {
   const gh = { apiBase: "https://api.github.com", repo: "acme/infra", token: "t0k" };
   const open = [
@@ -408,6 +454,27 @@ describe("trackIssue (#3759)", () => {
     expect(await githubForge({ ...gh, fetch: none.fetch }).trackIssue("<!-- d -->", { title: "t", body: "<!-- d -->\nb" })).toEqual({ action: "opened", number: 10, url: "https://h/issues/10" });
   });
 
+  test("sameWhen counts a body that differs only in run-specific text as unchanged (#3802)", async () => {
+    const issues = [{ number: 8, title: "Drift: prod", body: "<!-- d -->\nfingerprint f1\nrun 100", html_url: "https://h/issues/8" }];
+    const next = { title: "Drift: prod", body: "<!-- d -->\nfingerprint f1\nrun 101" };
+    const same = fakeFetch({ "GET /repos/acme/infra/issues": issues });
+    expect(await githubForge({ ...gh, fetch: same.fetch }).trackIssue("<!-- d -->", next, { sameWhen: "fingerprint f1" })).toEqual({
+      action: "unchanged",
+      number: 8,
+      url: "https://h/issues/8",
+    });
+    expect(same.calls.map((c) => c.method)).toEqual(["GET"]);
+    const strip = (b: string) => b.replace(/\nrun \d+/, "");
+    const fn = fakeFetch({ "GET /repos/acme/infra/issues": issues });
+    expect(
+      (await githubForge({ ...gh, fetch: fn.fetch }).trackIssue("<!-- d -->", next, { sameWhen: (o, f) => o.title === f.title && strip(o.body) === strip(f.body) })).action,
+    ).toBe("unchanged");
+    const retitled = fakeFetch({ "GET /repos/acme/infra/issues": issues, "PATCH /repos/acme/infra/issues/8": { number: 8 } });
+    expect((await githubForge({ ...gh, fetch: retitled.fetch }).trackIssue("<!-- d -->", { ...next, title: "Drift: prod (2)" }, { sameWhen: "fingerprint f1" })).action).toBe("updated");
+    const moved = fakeFetch({ "GET /repos/acme/infra/issues": issues, "PATCH /repos/acme/infra/issues/8": { number: 8 } });
+    expect((await githubForge({ ...gh, fetch: moved.fetch }).trackIssue("<!-- d -->", { ...next, body: "<!-- d -->\nfingerprint f2" }, { sameWhen: "fingerprint f2" })).action).toBe("updated");
+  });
+
   test("GitLab searches open issues by description, writes description, and closes with a note", async () => {
     const issues = [{ iid: 3, title: "Drift", description: "<!-- d -->\nold", web_url: "https://gl/i/3" }];
     const { fetch, calls } = fakeFetch({
@@ -522,6 +589,14 @@ describe("forgeTargetFromEnv (#3759)", () => {
     expect(calls[0].headers["PRIVATE-TOKEN"]).toBeUndefined();
   });
 
+  test("the default token order: CHANT_GITHUB_TOKEN on GitHub, FORGEJO_TOKEN before GITHUB_TOKEN on Forgejo (#3802)", () => {
+    const base = { GITHUB_REPOSITORY: "a/b", GITHUB_SERVER_URL: "https://codeberg.org" };
+    expect(forgeTargetFromEnv({ GITHUB_ACTIONS: "true", ...base, CHANT_FORGEJO_TOKEN: "fj", GITHUB_TOKEN: "gh" }).tokenSource).toBe("GITHUB_TOKEN");
+    expect(forgeTargetFromEnv({ GITHUB_ACTIONS: "true", ...base, CHANT_GITHUB_TOKEN: "c", GH_TOKEN: "g" }).tokenSource).toBe("CHANT_GITHUB_TOKEN");
+    expect(forgeTargetFromEnv({ FORGEJO_ACTIONS: "true", ...base, FORGEJO_TOKEN: "f", GITHUB_TOKEN: "g" }).tokenSource).toBe("FORGEJO_TOKEN");
+    expect(forgeTargetFromEnv({ FORGEJO_ACTIONS: "true", ...base, CHANT_FORGEJO_TOKEN: "c", FORGEJO_TOKEN: "f" }).tokenSource).toBe("CHANT_FORGEJO_TOKEN");
+  });
+
   test("says every missing piece, and when the forge is unknown", () => {
     let err: unknown;
     try {
@@ -533,7 +608,7 @@ describe("forgeTargetFromEnv (#3759)", () => {
     expect((err as ForgeEnvironmentError).missing).toEqual([
       "GITHUB_REPOSITORY",
       "a pull request (a pull_request event, or refs/pull/<n>/ in GITHUB_REF)",
-      "a token (CHANT_FORGEJO_TOKEN, GH_TOKEN, GITHUB_TOKEN)",
+      "a token (CHANT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN)",
     ]);
     expect(() => forgeTargetFromEnv({})).toThrow(/forge is not known/);
   });

package/src/pr-forge.ts

@@ -76,6 +76,15 @@ export interface CommentResult {
   url?: string;
 }
 
+/** A comment or note {@link PrForge.findComment} read back. */
+export interface FoundComment {
+  /** The comment's or note's id. */
+  id: number;
+  body: string;
+  /** Its web URL, when the forge's answer carries one (GitHub and Forgejo do; a GitLab note does not). */
+  url?: string;
+}
+
 /** A finding to keep in a tracking issue. `body` carries the marker. */
 export interface IssueFinding {
   title: string;
@@ -92,6 +101,15 @@ export interface TrackIssueOptions extends MarkerMatch {
   closeOnClear?: boolean;
   /** Posted on the issue before it is closed. */
   clearComment?: string;
+  /**
+   * When the open issue counts as already current, in place of an equal
+   * title and body, for a body that names something that changes on every
+   * run (the run's URL, a timestamp). A string: unchanged when the titles
+   * are equal and the open issue's body carries it, such as the finding's
+   * fingerprint. A function: unchanged when it returns true for the open
+   * issue and the finding. An unchanged issue is not edited.
+   */
+  sameWhen?: string | ((open: IssueFinding, finding: IssueFinding) => boolean);
 }
 
 /** What {@link PrForge.trackIssue} did. */
@@ -129,6 +147,14 @@ export interface PrForge {
    * comment's web URL. The pull-request loop's form.
    */
   upsertNote(pr: number, marker: string, body: string): Promise<string | undefined>;
+  /**
+   * The comment on pull request `pr` (the note on merge request `pr`) that
+   * {@link upsertComment} would update for `marker`: the oldest one that
+   * {@link MarkerMatch} finds, `author` honoured, so a pull request's author
+   * cannot plant one. Undefined when there is none. Every page is read, and
+   * GitLab's system notes are skipped.
+   */
+  findComment(pr: number, marker: string, opts?: MarkerMatch): Promise<FoundComment | undefined>;
   setStatus(sha: string, status: ForgeStatus): Promise<void>;
   /**
    * Keep one OPEN tracking issue for `marker` in line with `finding`: open
@@ -250,9 +276,15 @@ function checkMarker(what: string, marker: string, body: string, match: MarkerMa
   }
 }
 
+/** The oldest comment on `pr` that `opts` takes for the caller's own. */
+async function ownComment(t: Threads, pr: number, marker: string, opts: MarkerMatch): Promise<Thread | undefined> {
+  if (!marker) throw new Error("the comment needs a marker to be found");
+  return (await t.comments(pr)).filter(ownedBy(marker, opts)).sort((a, b) => a.id - b.id)[0];
+}
+
 async function upsertCommentWith(t: Threads, pr: number, marker: string, body: string, opts: MarkerMatch, check: boolean): Promise<CommentResult> {
   if (check) checkMarker("comment", marker, body, opts.match);
-  const mine = (await t.comments(pr)).filter(ownedBy(marker, opts)).sort((a, b) => a.id - b.id)[0];
+  const mine = await ownComment(t, pr, marker, opts);
   if (!mine) {
     const made = await t.addComment(pr, body);
     return { action: "created", id: made?.id ?? 0, ...(made?.url ? { url: made.url } : {}) };
@@ -274,14 +306,24 @@ async function trackIssueWith(t: Threads, marker: string, finding: IssueFinding
     return { action: "closed", ...at(mine) };
   }
   if (!mine) return { action: "opened", ...at(await t.openIssue(finding.title, finding.body)) };
-  if (mine.body === finding.body && mine.title === finding.title) return { action: "unchanged", ...at(mine) };
+  if (sameIssue({ title: mine.title ?? "", body: mine.body }, finding, opts.sameWhen)) return { action: "unchanged", ...at(mine) };
   const edited = await t.editIssue(mine.id, finding.title, finding.body);
   return { action: "updated", ...at(mine), ...(edited?.url ? { url: edited.url } : {}) };
 }
 
+function sameIssue(open: IssueFinding, finding: IssueFinding, sameWhen: TrackIssueOptions["sameWhen"]): boolean {
+  if (typeof sameWhen === "function") return sameWhen(open, finding);
+  if (open.title !== finding.title) return false;
+  return typeof sameWhen === "string" && sameWhen !== "" ? open.body.includes(sameWhen) : open.body === finding.body;
+}
+
 /** The recipes every client shares, over its own {@link Threads}. */
-function threadCalls(t: Threads): Pick<PrForge, "upsertComment" | "upsertNote" | "trackIssue" | "upsertIssue"> {
+function threadCalls(t: Threads): Pick<PrForge, "upsertComment" | "upsertNote" | "findComment" | "trackIssue" | "upsertIssue"> {
   return {
+    async findComment(pr, marker, opts = {}) {
+      const c = await ownComment(t, pr, marker, opts);
+      return c ? { id: c.id, body: c.body, ...(c.url ? { url: c.url } : {}) } : undefined;
+    },
     upsertComment: (pr, marker, body, opts = {}) => upsertCommentWith(t, pr, marker, body, opts, true),
     upsertNote: async (pr, marker, body) => (await upsertCommentWith(t, pr, marker, body, {}, false)).url,
     trackIssue: (marker, finding, opts = {}) => trackIssueWith(t, marker, finding, opts, true),
@@ -647,13 +689,15 @@ export interface ForgeTargetOptions {
 }
 
 /**
- * The token order guide/ops documents for the finding modes (#2291, #2256):
- * a chant-specific variable first, for posting to an instance other than the
- * one the job runs on, then what the job already carries.
+ * The token order {@link forgeTargetFromEnv} reads, as guide/ops documents
+ * it: a chant-specific variable first, for posting to an instance other than
+ * the one the job runs on, then what the job already carries (#3802). A
+ * Forgejo job reads `FORGEJO_TOKEN` before the `GITHUB_*` names, and the
+ * GitHub row has its own chant variable rather than the Forgejo one.
  */
 export const FORGE_TOKEN_ORDER: Record<ForgeKind, readonly string[]> = {
-  github: ["CHANT_FORGEJO_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"],
-  forgejo: ["CHANT_FORGEJO_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"],
+  github: ["CHANT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"],
+  forgejo: ["CHANT_FORGEJO_TOKEN", "FORGEJO_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"],
   gitlab: ["CHANT_GITLAB_TOKEN", "GITLAB_TOKEN", "CI_JOB_TOKEN"],
 };
 

package/src/workspace/conformance/__fixture__/decisions/decision.kind.mjs

@@ -4,7 +4,7 @@
 //
 // A copy of docs/design/decisions/decision.kind.mjs in the chant repo, with
 // decision.schema.json beside it, so a workspace made from this one reads its
-// decisions without the chant repo. chant's test/reference-workspace.test.ts fails
+// decisions without the chant repo. chant's test/reference-workspace.e2e.test.ts fails
 // when this kind's data or the schema drifts from chant's.
 export const recordKind = {
   name: "decision",

package/src/workspace/conformance/__fixtures__/reference-broker.ts

@@ -8,7 +8,7 @@
  *
  * It is a test fixture and the package does not export it: chant never runs
  * a broker or listens on a port (ws-052, ws-086), so it lives under
- * `__fixtures__`, which test/no-listener.test.ts leaves out like a test file.
+ * `__fixtures__`, which test/no-listener.e2e.test.ts leaves out like a test file.
  * `startReferenceBroker(env)` has the shape of the suite's `start`.
  */
 

package/src/workspace/conformance/broker.ts

@@ -187,7 +187,7 @@ export type BrokerHttpHandler = (req: IncomingMessage, res: ServerResponse) => v
 /**
  * How the suite serves its upstreams: serve `handler` on a loopback port and
  * return its URL and how to stop it. The caller passes it because chant
- * itself never listens on a port (ws-052, ws-086, test/no-listener.test.ts);
+ * itself never listens on a port (ws-052, ws-086, test/no-listener.e2e.test.ts);
  * the test that runs the suite does.
  */
 export type BrokerListen = (handler: BrokerHttpHandler) => Promise<{ url: string; close(): Promise<void> | void }>;

package/src/workspace/records-write.e2e.test.ts

@@ -3,7 +3,7 @@
  * line: standard input, exit codes and the refusal document, from the CLI a
  * user runs. Each test spawns the CLI several times, which put them near 20s
  * on CI, over the unit shards' per-test budget, so they run in the test-e2e
- * job (#2817). The commands' own behaviour is covered in records-write.test.ts.
+ * job (#2817). The commands' own behaviour is covered in records-write-commands.e2e.test.ts.
  */
 
 import { execFileSync } from "node:child_process";