@intentius/chant 0.124.14 → 0.124.15

package/src/lifecycle/gate-audit.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "vitest";
-import { deriveGateAudit, gateLedgerLines, gateLedgerLinesFromLog, readGateAuditLedgers, isOverrideGate } from "./gate-audit";
+import { readGateAuditDecisions, deriveGateAudit, gateLedgerLines, gateLedgerLinesFromLog, readGateAuditLedgers, isOverrideGate } from "./gate-audit";
 import { memoryGateLedgerPort } from "../op/gate";
 
 const D1 = "jcs1-sha256:" + "a".repeat(64);
@@ -12,6 +12,15 @@ const resolution = (o: Record<string, unknown> = {}) =>
 const ledger = (op: string, ...texts: string[]) => ({ op, lines: texts.map((text) => ({ text })) });
 
 describe("lifecycle/gate-audit", () => {
+  test("a hold's heldBy and approvalMode are surfaced (#3886, #3887)", () => {
+    const { entries } = deriveGateAudit({ ledgers: [ledger("tf-apply", pending({ approvalMode: "sealed", heldBy: { hook: "migrate", moment: "before-apply", target: "vpc" } }))] });
+    expect(entries[0]).toMatchObject({ approvalMode: "sealed", heldBy: { hook: "migrate", moment: "before-apply", target: "vpc" } });
+    expect(entries[0]!.detail).toEqual({});
+    const bad = deriveGateAudit({ ledgers: [ledger("tf-apply", pending({ approvalMode: "x", heldBy: { hook: 1 } }))] });
+    expect(bad.entries[0]!.heldBy).toBeUndefined();
+    expect(bad.entries[0]!.approvalMode).toBeUndefined();
+  });
+
   test("a pending fact's wave is surfaced (#3839)", () => {
     const { entries } = deriveGateAudit({ ledgers: [ledger("tf-apply", pending({ wave: { number: 2, name: "prod", op: "tg" } }))] });
     expect(entries[0]).toMatchObject({ wave: { number: 2, name: "prod", op: "tg" } });
@@ -179,4 +188,49 @@ describe("lifecycle/gate-audit", () => {
     expect(fromPort.entries.map((e) => e.kind)).toEqual(["approval-requested", "approved"]);
     expect(fromPort.entries.map((e) => e.at)).toEqual(fromText.entries.map((e) => e.at));
   });
+
+  describe("op-wave decision records (#3810)", () => {
+    const outcomes = [
+      { moment: "before-plan", name: "lint", exit: 0, outcome: "passed" },
+      { moment: "after-plan", name: "cost", target: "prod", exit: 2, outcome: "held" },
+      { moment: "before-apply", name: "backup", exit: 1, outcome: "failed" },
+      { moment: "after-apply", name: "skip", exit: 0, outcome: "skipped", reason: "nothing applied" },
+    ];
+    const record = { wave: 1, name: "prod", op: "tf-apply", gate: "wave-1", digest: D1, heldBy: ["cost"], outcomes };
+
+    test("each outcome becomes a hook entry linked to the approval and the apply", () => {
+      const { entries, gaps } = deriveGateAudit({
+        ledgers: [ledger("tf-apply", pending(), resolution())],
+        applies: [{ ref: "reports/1", at: "2026-10-01T12:00:00.000Z", gate: "wave-1", digest: D1 }],
+        decisions: [{ ref: "wave-1.json", at: "2026-10-01T12:05:00.000Z", record }],
+      });
+      expect(gaps).toEqual([]);
+      const hooks = entries.filter((e) => e.kind === "hook");
+      expect(hooks.map((h) => h.hook?.outcome)).toEqual(["passed", "held", "failed", "skipped"]);
+      expect(hooks[1]!.hook).toMatchObject({ moment: "after-plan", name: "cost", target: "prod", exit: 2 });
+      expect(hooks[3]!.hook?.reason).toBe("nothing applied");
+      const approved = entries.find((e) => e.kind === "approved")!;
+      const applied = entries.find((e) => e.kind === "applied")!;
+      for (const h of hooks) expect(h).toMatchObject({ under: approved.id, applied: applied.id, gate: "wave-1", digest: D1, wave: { number: 1, name: "prod" } });
+      expect(new Set(hooks.map((h) => h.id)).size).toBe(4);
+    });
+
+    test("text input, no approval on file, and a malformed record", () => {
+      const { entries, gaps } = deriveGateAudit({
+        ledgers: [],
+        decisions: [{ ref: "a.json", at: "2026-10-01T12:00:00.000Z", text: JSON.stringify(record) }, { ref: "b.json", at: "2026-10-01T12:00:00.000Z", text: "nope" }],
+      });
+      expect(entries.filter((e) => e.kind === "hook")).toHaveLength(4);
+      expect(entries[0]).not.toHaveProperty("under");
+      expect(gaps.map((g) => g.kind)).toEqual(["malformed-line"]);
+    });
+
+    test("readGateAuditDecisions reads the json files under a directory", async () => {
+      const files: Record<string, string> = { "w1.json": JSON.stringify(record), "notes.txt": "x" };
+      const port = { list: async () => Object.keys(files), read: async (_d: string, f: string) => files[f] ?? null };
+      const got = await readGateAuditDecisions(port, "_wave-decisions/tf", "2026-10-01T12:00:00.000Z");
+      expect(got.map((d) => d.ref)).toEqual(["_wave-decisions/tf/w1.json"]);
+      expect(deriveGateAudit({ ledgers: [], decisions: got }).entries).toHaveLength(4);
+    });
+  });
 });

package/src/lifecycle/gate-audit.ts

@@ -21,6 +21,7 @@
  * | `revoked`            | a resolution a commit removed from the file (`subject` says which) |
  * | `applied`            | an apply the caller passes in, with the approval it ran under    |
  * | `override-spent`     | an override an apply the caller passes in cites                  |
+ * | `hook`               | a hook outcome in an op-wave decision record the caller passes in |
  *
  * An override gate is, by default, any gate of the op `policy-override`
  * (terragucci writes one gate per root) or named `override-<rule>` (SQL
@@ -79,6 +80,8 @@ import { canonicalJson } from "../effect-receipt";
 import { contentDigest } from "../content-digest";
 import { samePlanDigest } from "./plan-digest";
 import type { GateLedgerPort } from "../op/gate";
+import type { LedgerReadPort } from "./ledger-port";
+import type { GateApprovalSource } from "../op/op-waves";
 
 export const GATE_AUDIT_KINDS = [
   "approval-requested",
@@ -88,6 +91,7 @@ export const GATE_AUDIT_KINDS = [
   "revoked",
   "applied",
   "override-spent",
+  "hook",
 ] as const;
 export type GateAuditKind = (typeof GATE_AUDIT_KINDS)[number];
 
@@ -155,7 +159,7 @@ export interface GateAuditSource {
   commit?: string;
   /** The commit that added the line, or for a revocation removed it, when the line came from history. */
   author?: GateLedgerCommit;
-  change: "added" | "removed" | "apply";
+  change: "added" | "removed" | "apply" | "decision";
 }
 
 export interface GateAuditEntry {
@@ -193,8 +197,16 @@ export interface GateAuditEntry {
   description?: string;
   /** Pending facts an op wave wrote for a policy denial or a hold (#3839): the wave they belong to. */
   wave?: { number: number; name: string; op?: string };
+  /** Pending facts of a hold (#3886): the hook that holds the wave. */
+  heldBy?: { hook: string; moment: string; target?: string };
+  /** Pending facts of an op wave (#3861): the approval mode the wave asked under. */
+  approvalMode?: GateApprovalSource;
   /** Overrides: the rules the denial named (from the denial line when there is one). */
   rules?: string[];
+  /** A hook entry: the hook's moment, name, run, how it came out, and why a moment was skipped (#3810). */
+  hook?: { moment: string; name: string; target?: string; outcome: "passed" | "failed" | "held" | "skipped"; exit: number; reason?: string };
+  /** A hook entry: the applied entry of the same wave and digest, if the caller passed that apply in. */
+  applied?: string;
   /** A revoked entry: what was revoked. */
   subject?: "approval" | "override";
   /** An applied entry: the approval entry it ran under, if one is held. An override-spent entry: the override entry. */
@@ -212,6 +224,35 @@ export interface GateAuditGap {
   detail: string;
 }
 
+/**
+ * An op-wave decision record (`.chant/op-waves/<name>/wave-<k>.json`, written
+ * by `chant run wave`), as far as the audit reads it: the wave's gate and
+ * digest, and the `outcomes` of its hooks (#3804, #3811, #3847). Typed
+ * structurally so this file imports nothing from `../op/`.
+ */
+export interface WaveDecisionRecord {
+  wave: number;
+  name: string;
+  op: string;
+  gate: string;
+  digest?: string;
+  heldBy?: string[];
+  heldOn?: unknown;
+  outcomes?: ReadonlyArray<{ moment: string; name: string; target?: string; exit: number; outcome: string; reason?: string }>;
+}
+
+/**
+ * A decision record the caller passes in. The record carries no time and no
+ * place, so `ref` (a file path, an artifact, a row) and `at` (when it was
+ * written) come from the caller. Give the parsed `record`, or its `text`.
+ */
+export interface GateAuditDecision {
+  ref: string;
+  at: string;
+  record?: unknown;
+  text?: string;
+}
+
 export interface GateAuditOptions {
   /** Whether a gate is an override gate. Default: op `policy-override`, or a gate named `override-...`. */
   isOverride?: (op: string, gate: string) => boolean;
@@ -228,6 +269,8 @@ export interface GateAuditOptions {
 export interface GateAuditInput extends GateAuditOptions {
   ledgers: readonly GateAuditLedger[];
   applies?: readonly GateAuditApply[];
+  /** Op-wave decision records: each hook outcome in them becomes a `hook` entry linked to the wave's approval and apply (#3810). */
+  decisions?: readonly GateAuditDecision[];
 }
 
 export const POLICY_OVERRIDE_OP = "policy-override";
@@ -241,13 +284,18 @@ type Row = Record<string, unknown>;
 
 const KNOWN = new Set([
   "version", "kind", "op", "gate", "resolvedBy", "relayedBy", "timestamp", "note", "url", "planDigest", "environment",
-  "approver", "seal", "review", "runId", "expiresAt", "description", "wave", "rules", "pr", "head", "reviewers",
+  "approver", "seal", "review", "runId", "expiresAt", "description", "wave", "heldBy", "approvalMode", "rules", "pr", "head", "reviewers",
 ]);
 
 const waveOf = (v: unknown): { number: number; name: string; op?: string } | undefined => {
   const w = v as { number?: unknown; name?: unknown; op?: unknown } | null;
   return w && typeof w === "object" && typeof w.number === "number" && typeof w.name === "string" ? { number: w.number, name: w.name, ...(typeof w.op === "string" ? { op: w.op } : {}) } : undefined;
 };
+const heldByOf = (v: unknown): { hook: string; moment: string; target?: string } | undefined => {
+  const h = v as { hook?: unknown; moment?: unknown; target?: unknown } | null;
+  return h && typeof h === "object" && typeof h.hook === "string" && typeof h.moment === "string" ? { hook: h.hook, moment: h.moment, ...(typeof h.target === "string" ? { target: h.target } : {}) } : undefined;
+};
+const modeOf = (v: unknown): GateApprovalSource | undefined => (v === "ledger" || v === "pr-review" || v === "sealed" ? v : undefined);
 const str = (v: unknown): string | undefined => (typeof v === "string" && v !== "" ? v : undefined);
 const strings = (v: unknown): string[] | undefined => (Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : undefined);
 const time = (iso: string): number => Date.parse(iso) || 0;
@@ -302,6 +350,23 @@ interface Seen {
 /** Whether two digests, either absent, can be the same plan: absent matches anything, as an old line records none. */
 const compatible = (a: string | undefined, b: string | undefined): boolean => a === undefined || b === undefined || samePlanDigest(a, b);
 
+function decisionOf(d: GateAuditDecision): WaveDecisionRecord | undefined {
+  let v: unknown = d.record;
+  if (v === undefined && d.text !== undefined) {
+    try {
+      v = JSON.parse(d.text);
+    } catch {
+      return undefined;
+    }
+  }
+  const r = v as Row | null;
+  if (!r || typeof r !== "object" || typeof r.wave !== "number" || typeof r.name !== "string" || typeof r.op !== "string" || typeof r.gate !== "string") return undefined;
+  const outcomes = Array.isArray(r.outcomes)
+    ? r.outcomes.filter((o): o is NonNullable<WaveDecisionRecord["outcomes"]>[number] => !!o && typeof o === "object" && typeof (o as Row).moment === "string" && typeof (o as Row).name === "string" && typeof (o as Row).exit === "number" && typeof (o as Row).outcome === "string")
+    : undefined;
+  return { wave: r.wave, name: r.name, op: r.op, gate: r.gate, ...(str(r.digest) ? { digest: str(r.digest) } : {}), ...(strings(r.heldBy) ? { heldBy: strings(r.heldBy) } : {}), ...(r.heldOn !== undefined ? { heldOn: r.heldOn } : {}), ...(outcomes ? { outcomes } : {}) };
+}
+
 /** The entries `input` adds up to, oldest first, and the gaps they show. */
 export function deriveGateAudit(input: GateAuditInput): { entries: GateAuditEntry[]; gaps: GateAuditGap[] } {
   const isOverride = input.isOverride ?? isOverrideGate;
@@ -359,7 +424,7 @@ export function deriveGateAudit(input: GateAuditInput): { entries: GateAuditEntr
           ...base,
           kind: override ? "override-requested" : "approval-requested",
           at: String(r.timestamp),
-          ...drop({ runId: str(r.runId), expiresAt: str(r.expiresAt), description: str(r.description), url: str(r.url), rules: strings(r.rules), wave: waveOf(r.wave) }),
+          ...drop({ runId: str(r.runId), expiresAt: str(r.expiresAt), description: str(r.description), url: str(r.url), rules: strings(r.rules), wave: waveOf(r.wave), heldBy: heldByOf(r.heldBy), approvalMode: modeOf(r.approvalMode) }),
           detail: extra,
         }));
         continue;
@@ -450,6 +515,35 @@ export function deriveGateAudit(input: GateAuditInput): { entries: GateAuditEntr
     }
   }
 
+  for (const d of input.decisions ?? []) {
+    const rec = decisionOf(d);
+    if (!rec) {
+      gaps.push({ kind: "malformed-line", detail: `${d.ref} is not an op-wave decision record` });
+      continue;
+    }
+    const approval = rec.digest === undefined ? undefined : entries
+      .filter((e) => e.kind === "approved" && e.gate === rec.gate && e.op === rec.op && e.digest !== undefined && samePlanDigest(e.digest, rec.digest!))
+      .sort((x, y) => time(y.at) - time(x.at))[0];
+    const applied = rec.digest === undefined ? undefined : entries.find((e) => e.kind === "applied" && e.gate === rec.gate && e.digest !== undefined && samePlanDigest(e.digest, rec.digest!));
+    for (const [i, o] of (rec.outcomes ?? []).entries()) {
+      if (o.outcome !== "passed" && o.outcome !== "failed" && o.outcome !== "held" && o.outcome !== "skipped") continue;
+      entries.push(keyed({
+        id: idOf("hook", d.ref, d.at, i, o),
+        kind: "hook",
+        at: d.at,
+        gate: rec.gate,
+        op: rec.op,
+        ...(rec.digest ? { digest: rec.digest } : {}),
+        ...(approval ? { under: approval.id } : {}),
+        ...(applied ? { applied: applied.id } : {}),
+        hook: { moment: o.moment, name: o.name, ...(o.target ? { target: o.target } : {}), outcome: o.outcome, exit: o.exit, ...(o.reason ? { reason: o.reason } : {}) },
+        wave: { number: rec.wave, name: rec.name, op: rec.op },
+        detail: drop({ heldBy: rec.heldBy?.length ? rec.heldBy : undefined, heldOn: o.outcome === "held" ? rec.heldOn : undefined }),
+        source: { path: d.ref, op: rec.op, change: "decision" },
+      }));
+    }
+  }
+
   entries.sort((x, y) => time(x.at) - time(y.at));
   return { entries, gaps };
 }
@@ -510,3 +604,22 @@ export async function readGateAuditLedgers(port: Pick<GateLedgerPort, "read">, o
   }
   return out;
 }
+
+/**
+ * The thin reader for decision records kept on the ledger branch: every
+ * `.json` file directly under `dir` (such as a product's `_wave-decisions/<name>`),
+ * as input for {@link GateAuditInput.decisions}. A decision record holds no
+ * time, so `at` stamps them all: when the product collected them. Where the
+ * records live is the product's business; chant writes them to
+ * `.chant/op-waves/<name>/wave-<k>.json` in the job, and a product that
+ * collects them elsewhere passes them in directly.
+ */
+export async function readGateAuditDecisions(port: Pick<LedgerReadPort, "read" | "list">, dir: string, at: string): Promise<GateAuditDecision[]> {
+  const out: GateAuditDecision[] = [];
+  for (const file of (await port.list(dir)).sort()) {
+    if (!file.endsWith(".json")) continue;
+    const text = await port.read(dir, file);
+    if (text !== null) out.push({ ref: `${dir}/${file}`, at, text });
+  }
+  return out;
+}

package/src/lifecycle/gate-ledger.test.ts

@@ -6,7 +6,7 @@ import { join } from "node:path";
 import {
   appendGateResolution, appendPendingGate, readGateResolutions, readGateLedger,
   latestResolutionSince, latestPendingGate, isPendingGateExpired,
-  resolveApprovalUrl, isApprovalUrl, latestResolutionForPlan,
+  resolveApprovalUrl, isApprovalUrl, latestResolutionForPlan, parseGateLedger,
   type PendingGateRecord, type GateResolutionRecord,
 } from "./gate-ledger";
 import { readBlobFromPath, writeBlobToPath } from "./git";
@@ -484,3 +484,22 @@ describe("gate ledger newline termination (#3849)", () => {
     });
   });
 });
+
+describe("pending fact wave and heldBy (#3886, #3887)", () => {
+  const line = (o: Record<string, unknown>) =>
+    JSON.stringify({ version: 1, kind: "pending", op: "tg", gate: "g", timestamp: "2026-10-01T00:00:00Z", expiresAt: "2026-10-02T00:00:00Z", ...o });
+  test("the reader types wave, heldBy and approvalMode", () => {
+    const { pending } = parseGateLedger(line({ approvalMode: "pr-review", wave: { number: 2, name: "prod", op: "tg" }, heldBy: { hook: "migrate", moment: "before-apply", target: "vpc" } }));
+    const p: PendingGateRecord = pending[0]!;
+    expect(p.wave).toEqual({ number: 2, name: "prod", op: "tg" });
+    expect(p.heldBy).toEqual({ hook: "migrate", moment: "before-apply", target: "vpc" });
+    expect(p.approvalMode).toBe("pr-review");
+  });
+  test("a wave or heldBy of the wrong shape is dropped, the line is kept", () => {
+    const { pending, malformed } = parseGateLedger(line({ wave: { number: "2" }, heldBy: "migrate" }));
+    expect(malformed).toBe(0);
+    expect(pending).toHaveLength(1);
+    expect(pending[0]!.wave).toBeUndefined();
+    expect(pending[0]!.heldBy).toBeUndefined();
+  });
+});

package/src/lifecycle/gate-ledger.ts

@@ -228,6 +228,21 @@ export type GateResolutionInput = Omit<GateResolutionRecord, "version" | "kind">
  * ledger by a line a minute. Once `expiresAt` passes, the fact is stale and
  * the next run records a fresh one.
  */
+export interface PendingGateWave {
+  number: number;
+  name: string;
+  /** The Op waves spec's name. */
+  op?: string;
+}
+
+/** The hook that holds a wave on a gate (#3886): which hook asked, at which moment, and for which run. */
+export interface PendingGateHeldBy {
+  hook: string;
+  moment: string;
+  /** The run, for a `perRun` hook. */
+  target?: string;
+}
+
 export interface PendingGateRecord {
   /** Schema version, so an incompatible future shape is detected before being misread. */
   version: 1;
@@ -296,6 +311,17 @@ export interface PendingGateRecord {
    * than inferring it from config. Not the quorum block in `approval`.
    */
   approvalMode?: GateApprovalSource;
+  /**
+   * The Op wave this gate belongs to (#3839): a hold on another gate or a
+   * policy denial. Absent on a gate that is not a wave's.
+   */
+  wave?: PendingGateWave;
+  /**
+   * The hook that holds the wave on this gate (#3886), on a hold only: its
+   * name, the moment it ran at and its run. A reader names the holder from it
+   * rather than from `description`, which the hook writes.
+   */
+  heldBy?: PendingGateHeldBy;
   /**
    * The open question this gate waits on, on a gate that asks a decision
    * point (#3170). It is answered with `chant workspace points answer <id>`,
@@ -449,7 +475,13 @@ export function parseGateLedger(
           malformed++;
           continue;
         }
-        pending.push(parsed as PendingGateRecord);
+        // #3887: a `wave` or `heldBy` of the wrong shape is dropped, so a reader can trust the type.
+        const rec = parsed as PendingGateRecord;
+        const w = (parsed as { wave?: unknown }).wave as Partial<PendingGateWave> | null | undefined;
+        if (w !== undefined && !(w && typeof w === "object" && typeof w.number === "number" && typeof w.name === "string")) delete rec.wave;
+        const h = (parsed as { heldBy?: unknown }).heldBy as Partial<PendingGateHeldBy> | null | undefined;
+        if (h !== undefined && !(h && typeof h === "object" && typeof h.hook === "string" && typeof h.moment === "string")) delete rec.heldBy;
+        pending.push(rec);
         continue;
       }
       if (typeof parsed.resolvedBy !== "string") {

package/src/op/activities/activity-contracts.ts

@@ -271,7 +271,7 @@ export const lifecyclePlanChangeSetContract = activityContract(
 
 export const readChangeSetPartContract = activityContract(
   "readChangeSetPart",
-  z.strictObject({ member: z.string(), planner: z.enum(["chant", "warden"]), file: z.string(), lexicon: z.string().optional() }),
+  z.strictObject({ member: z.string(), planner: z.enum(["chant", "warden", "sql"]), file: z.string(), lexicon: z.string().optional() }),
   z.object({ part: changeSetPart }),
 );
 

package/src/op/activities/change-set.ts

@@ -25,6 +25,7 @@ import { promisify } from "node:util";
 import {
   composeChangeSet as compose,
   lifecyclePlanPart,
+  readChangeSetPartFile,
   reconcilePlanPart,
   type ChangeSetDocument,
   type ChangeSetPart,
@@ -87,8 +88,12 @@ export async function lifecyclePlanChangeSet(args: LifecyclePlanChangeSetArgs, s
 
 export interface ReadChangeSetPartArgs {
   member: string;
-  /** Which planner wrote the file: `chant` (`lifecycle plan --json`) or `warden` (its reconcile change sets). */
-  planner: "chant" | "warden";
+  /**
+   * Which planner wrote the file: `chant` (`lifecycle plan --json`), `warden`
+   * (its reconcile change sets), or `sql` (a part the sql lexicon's
+   * `change-set` adapters produced, written as JSON).
+   */
+  planner: "chant" | "warden" | "sql";
   /** The plan file, relative to the current directory. */
   file: string;
   /** The lexicon the entries belong to, when the plan does not say. */
@@ -98,7 +103,8 @@ export interface ReadChangeSetPartArgs {
 /**
  * A plan another step or job wrote to a file, as a member's part. A warden
  * plan is the reconcile `ChangeSet` (`@intentius/chant/reconcile`), or an
- * array of them, one per cycle and org.
+ * array of them, one per cycle and org. A sql plan is already a part
+ * (`@intentius/chant-lexicon-sql/change-set`), renamed to `member` here.
  */
 export async function readChangeSetPart(args: ReadChangeSetPartArgs): Promise<ChangeSetPartResult> {
   const plan: unknown = JSON.parse(readFileSync(resolve(args.file), "utf-8"));
@@ -108,6 +114,8 @@ export async function readChangeSetPart(args: ReadChangeSetPartArgs): Promise<Ch
       return { part: lifecyclePlanPart({ member: args.member, plan: plan as LifecycleChangeSet, ...lexicon }) };
     case "warden":
       return { part: reconcilePlanPart({ member: args.member, plan: plan as ReconcileChangeSet | ReconcileChangeSet[], ...lexicon }) };
+    case "sql":
+      return { part: readChangeSetPartFile(plan, "sql", args.member, args.lexicon) };
     default:
       throw new Error(`readChangeSetPart: no adapter for planner ${String(args.planner)}; terraform-family plans come from terraformPlan's changeSet`);
   }

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

@@ -317,6 +317,8 @@ describe("lexiconUpgrade issue mode", () => {
 
     vi.stubEnv("GITHUB_REPOSITORY", "acme/infra");
     vi.stubEnv("GITHUB_API_URL", "");
+    // A Forgejo run, since CHANT_FORGEJO_TOKEN is only read there (#3807).
+    vi.stubEnv("FORGEJO_ACTIONS", "true");
     // The cross-instance case (#2320): a Forgejo token that must outrank the
     // job's own `github.token`, on the path that used to forward neither.
     vi.stubEnv("CHANT_FORGEJO_TOKEN", "forgejo-cross-instance");

package/src/op/activities/reconcile.test.ts

@@ -21,6 +21,7 @@ import {
   ghCredentialEnv,
   githubShapedForgeFrom,
 } from "./reconcile";
+import { FORGE_TOKEN_ORDER } from "../../pr-forge";
 
 // ── The `gh` stub (chant #2291) ──────────────────────────────────────────────
 //
@@ -338,12 +339,46 @@ describe("commentTokenFrom (#2291)", () => {
     expect(commentTokenFrom({ GITHUB_TOKEN: "ghs_y" })).toEqual({ value: "ghs_y", source: "GITHUB_TOKEN" });
   });
 
-  test("CHANT_FORGEJO_TOKEN wins over both, for the cross-instance case", () => {
+  test("on Forgejo CHANT_FORGEJO_TOKEN wins, then FORGEJO_TOKEN, then GH_TOKEN, then GITHUB_TOKEN", () => {
+    const base = { FORGEJO_ACTIONS: "true" };
+    const all = { CHANT_FORGEJO_TOKEN: "a", FORGEJO_TOKEN: "b", GH_TOKEN: "c", GITHUB_TOKEN: "d" };
+    expect(commentTokenFrom({ ...base, ...all })?.source).toBe("CHANT_FORGEJO_TOKEN");
+    expect(commentTokenFrom({ ...base, FORGEJO_TOKEN: "b", GH_TOKEN: "c", GITHUB_TOKEN: "d" })?.source).toBe("FORGEJO_TOKEN");
+    expect(commentTokenFrom({ ...base, GH_TOKEN: "c", GITHUB_TOKEN: "d" })?.source).toBe("GH_TOKEN");
+  });
+
+  test("a /api/v1 API base is Forgejo even without FORGEJO_ACTIONS", () => {
     expect(
-      commentTokenFrom({ CHANT_FORGEJO_TOKEN: "a", GH_TOKEN: "b", GITHUB_TOKEN: "c" })?.source,
+      commentTokenFrom({ GITHUB_API_URL: "https://f.example/api/v1", CHANT_FORGEJO_TOKEN: "a", GH_TOKEN: "b" })?.source,
     ).toBe("CHANT_FORGEJO_TOKEN");
   });
 
+  test("on GitHub CHANT_GITHUB_TOKEN wins, then GH_TOKEN, then GITHUB_TOKEN (#3807)", () => {
+    const base = { GITHUB_ACTIONS: "true" };
+    expect(commentTokenFrom({ ...base, CHANT_GITHUB_TOKEN: "a", GH_TOKEN: "b", GITHUB_TOKEN: "c" })?.source).toBe("CHANT_GITHUB_TOKEN");
+    expect(commentTokenFrom({ ...base, GH_TOKEN: "b", GITHUB_TOKEN: "c" })?.source).toBe("GH_TOKEN");
+  });
+
+  test("on GitHub CHANT_FORGEJO_TOKEN and FORGEJO_TOKEN are not read (#3807)", () => {
+    expect(
+      commentTokenFrom({ GITHUB_ACTIONS: "true", CHANT_FORGEJO_TOKEN: "a", FORGEJO_TOKEN: "b", GH_TOKEN: "c" }),
+    ).toEqual({ value: "c", source: "GH_TOKEN" });
+    expect(commentTokenFrom({ GITHUB_ACTIONS: "true", CHANT_FORGEJO_TOKEN: "a" })).toBeUndefined();
+  });
+
+  test("agrees with FORGE_TOKEN_ORDER for each forge", () => {
+    for (const [kind, env] of [
+      ["github", { GITHUB_ACTIONS: "true" }],
+      ["forgejo", { FORGEJO_ACTIONS: "true" }],
+    ] as const) {
+      for (const name of FORGE_TOKEN_ORDER[kind]) {
+        const rest = FORGE_TOKEN_ORDER[kind].slice(FORGE_TOKEN_ORDER[kind].indexOf(name));
+        const vars = Object.fromEntries(rest.map((n) => [n, `v-${n}`]));
+        expect(commentTokenFrom({ ...env, ...vars })?.source).toBe(name);
+      }
+    }
+  });
+
   test("no token at all is undefined rather than an empty value", () => {
     expect(commentTokenFrom({})).toBeUndefined();
     expect(commentTokenFrom({ GH_TOKEN: "", GITHUB_TOKEN: "" })).toBeUndefined();
@@ -469,6 +504,31 @@ describe("reconcilePr comment mode posts through the forge client (#2291, #3757)
     }
   });
 
+  test("on a GitHub run CHANT_FORGEJO_TOKEN is ignored and GH_TOKEN is sent (#3807)", async () => {
+    stubPrEnv("https://api.github.com");
+    vi.stubEnv("GITHUB_ACTIONS", "true");
+    vi.stubEnv("CHANT_FORGEJO_TOKEN", "forgejo-token-set-on-github");
+    try {
+      await reconcilePr({ env: "app", mode: "comment", body: "the plan" });
+      expect(forgeCalls.length).toBeGreaterThan(0);
+      for (const call of forgeCalls) expect(call.authorization).toBe("Bearer forgejo-actions-token");
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+
+  test("on a GitHub run CHANT_GITHUB_TOKEN outranks GH_TOKEN (#3807)", async () => {
+    stubPrEnv("https://api.github.com");
+    vi.stubEnv("GITHUB_ACTIONS", "true");
+    vi.stubEnv("CHANT_GITHUB_TOKEN", "other-github-token");
+    try {
+      await reconcilePr({ env: "app", mode: "comment", body: "the plan" });
+      for (const call of forgeCalls) expect(call.authorization).toBe("Bearer other-github-token");
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+
   test("FORGEJO_ACTIONS marks a Forgejo run whatever its API base looks like", async () => {
     stubPrEnv("https://code.example/api/forgejo");
     vi.stubEnv("FORGEJO_ACTIONS", "true");

package/src/op/activities/reconcile.ts

@@ -1,7 +1,15 @@
 import { exec } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
-import { ForgeApiError, forgejoForge, githubForge, type ForgeFetch, type GithubShapedForge } from "../../pr-forge";
+import {
+  detectForge,
+  FORGE_TOKEN_ORDER,
+  ForgeApiError,
+  forgejoForge,
+  githubForge,
+  type ForgeFetch,
+  type GithubShapedForge,
+} from "../../pr-forge";
 import { ghHostEnv } from "./gh-host";
 import { restPullRequestForge } from "./forge-pull-request";
 
@@ -49,9 +57,11 @@ const execAsync = promisify(exec);
  * of opening a second one.
  *
  * Both modes resolve the GitHub/Forgejo credential the same way, through
- * {@link commentTokenFrom}: `CHANT_FORGEJO_TOKEN`, then `GH_TOKEN`, then
- * `GITHUB_TOKEN` (chant #2320), refusing by name before any call when none
- * is set ({@link noCommentTokenMessage}, {@link noIssueTokenMessage}).
+ * {@link commentTokenFrom}, in pr-forge's `FORGE_TOKEN_ORDER` for the forge the
+ * run is on (chant #2320, #3807): `CHANT_GITHUB_TOKEN`, `GH_TOKEN`,
+ * `GITHUB_TOKEN` on GitHub; `CHANT_FORGEJO_TOKEN`, `FORGEJO_TOKEN`,
+ * `GH_TOKEN`, `GITHUB_TOKEN` on Forgejo. It refuses by name before any call
+ * when none is set ({@link noCommentTokenMessage}, {@link noIssueTokenMessage}).
  *
  * Until #3757 these two modes shelled to `gh api`. That reached Forgejo only
  * after two fixes: a full URL, because `gh` resolves a relative path against
@@ -451,24 +461,38 @@ export interface CommentToken {
   source: string;
 }
 
+/**
+ * Which GitHub-shaped forge a run is on: Forgejo when `detectForge` says so
+ * (`FORGEJO_ACTIONS`/`GITEA_ACTIONS`, or a `GITHUB_API_URL` ending in
+ * `/api/v1`), or when the API base ends in `/api/v1`, which is how a step
+ * posting to some other Forgejo instance names it. GitHub serves `/api/v3`
+ * or `api.github.com`, never `/api/v1`. Anything else is GitHub.
+ */
+export function githubShapedKindFrom(env: Record<string, string | undefined>): "github" | "forgejo" {
+  if (detectForge(env) === "forgejo") return "forgejo";
+  return /\/api\/v1$/.test(githubApiBaseFrom(env)) ? "forgejo" : "github";
+}
+
 /**
  * Resolve the token the `comment` and `issue` modes post with on GitHub and
- * Forgejo, most specific first (chant #2291). The generated workflow sets
- * `GH_TOKEN` and `GITHUB_TOKEN` to `${{ github.token }}` for every
- * non-`report` finding mode — on
- * Forgejo the same way as on GitHub, and the real-instance read confirmed
- * `github.token` is populated there and good for a 200 read and a 201 write,
- * authored as `forgejo-actions`. So the common case needs nothing set beyond
- * what the generator already emits.
+ * Forgejo (chant #2291), in pr-forge's `FORGE_TOKEN_ORDER` for the forge the
+ * run is on (#3807), so this and `forgeTargetFromEnv` cannot drift apart.
+ * GitHub reads `CHANT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN`; Forgejo reads
+ * `CHANT_FORGEJO_TOKEN`, `FORGEJO_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN`. The
+ * generated workflow sets `GH_TOKEN` and `GITHUB_TOKEN` to
+ * `${{ github.token }}` for every non-`report` finding mode, on Forgejo the
+ * same way as on GitHub, so the common case needs nothing set beyond what the
+ * generator already emits.
  *
- * `CHANT_FORGEJO_TOKEN` is checked first for the case that ambient token
- * cannot cover: a run posting to a Forgejo instance other than the one the
- * job executes on, where `github.token`'s scope stops at its own instance.
- * A run with none of the three is refused by name before any call, in place
- * of the forge's own opaque 401.
+ * The chant-specific variable comes first for the case that ambient token
+ * cannot cover: a run posting to an instance other than the one the job
+ * executes on, where `github.token`'s scope stops at its own instance.
+ * `CHANT_FORGEJO_TOKEN` is no longer read on a GitHub run. A run with none of
+ * the names is refused by name before any call, in place of the forge's own
+ * opaque 401.
  */
 export function commentTokenFrom(env: Record<string, string | undefined>): CommentToken | undefined {
-  for (const source of ["CHANT_FORGEJO_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"]) {
+  for (const source of FORGE_TOKEN_ORDER[githubShapedKindFrom(env)]) {
     const value = env[source]?.trim();
     if (value) return { value, source };
   }
@@ -543,8 +567,8 @@ export function noCommentTokenMessage(repo: string, number: number): string {
   return (
     `reconcilePr mode "comment" has pull request ${repo}#${number} to post its finding on and no token to ` +
     "post it with. GH_TOKEN or GITHUB_TOKEN, set from github.token, already covers this on a GitHub Actions " +
-    "or Forgejo Actions run — set CHANT_FORGEJO_TOKEN to post against a different instance than the one the " +
-    "job runs on. CHANT_FORGEJO_TOKEN is read first where the two must differ."
+    "or Forgejo Actions run — set CHANT_GITHUB_TOKEN (GitHub) or CHANT_FORGEJO_TOKEN (Forgejo) to post " +
+    "against a different instance than the one the job runs on. It is read first where the two must differ."
   );
 }
 
@@ -553,8 +577,8 @@ export function noIssueTokenMessage(repo: string): string {
   return (
     `reconcilePr mode "issue" has repository ${repo} to open or edit its finding in and no token to do it ` +
     "with. GH_TOKEN or GITHUB_TOKEN, set from github.token, already covers this on a GitHub Actions or " +
-    "Forgejo Actions run — set CHANT_FORGEJO_TOKEN to post against a different instance than the one the " +
-    "job runs on. CHANT_FORGEJO_TOKEN is read first where the two must differ."
+    "Forgejo Actions run — set CHANT_GITHUB_TOKEN (GitHub) or CHANT_FORGEJO_TOKEN (Forgejo) to post " +
+    "against a different instance than the one the job runs on. It is read first where the two must differ."
   );
 }
 
@@ -582,7 +606,7 @@ export function githubShapedForgeFrom(
   signal?: AbortSignal,
 ): GithubShapedForge {
   const apiBase = githubApiBaseFrom(env);
-  const forgejo = env.FORGEJO_ACTIONS === "true" || env.GITEA_ACTIONS === "true" || /\/api\/v1$/.test(apiBase);
+  const forgejo = githubShapedKindFrom(env) === "forgejo";
   // Read at call time, so a test that stubs the global sees its stub.
   const fetchImpl: ForgeFetch = (url, init) => globalThis.fetch(url, { ...init, ...(signal ? { signal } : {}) });
   const opts = { apiBase, repo, token: token.value, fetch: fetchImpl };

package/src/op/builders.ts

@@ -428,7 +428,7 @@ export const lifecyclePlanChangeSet = (args: WithStepRefs<LifecyclePlanChangeSet
   return activity("lifecyclePlanChangeSet", rest, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
 };
 
-/** A member's change-set part from a plan file a chant or warden run wrote (#3181). Its `part` feeds {@link composeChangeSet}. */
+/** A member's change-set part from a plan file a chant, warden or sql run wrote (#3181, #3767). Its `part` feeds {@link composeChangeSet}. */
 export const readChangeSetPart = (args: WithStepRefs<ReadChangeSetPartArgs> & StepOpts): NamedActivityStep => {
   const { args: rest, profile, id } = takeProfileAndId(args as Record<string, unknown>);
   return activity("readChangeSetPart", rest, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });