@intentius/chant 0.124.29 → 0.124.30

package/src/components/wave-plan.ts

@@ -135,3 +135,33 @@ export async function readComponentOutputs(
   }
   return found;
 }
+
+/**
+ * Read the deployed outputs of each of `names` that `outputs` holds nothing
+ * for yet (#4104), through {@link readComponentOutputs}, and add them to
+ * `outputs`. A name that is not among `components`, or whose steps cannot
+ * say, is left out, so its dependents' references stay unresolved. Returns,
+ * per component read, the names of the outputs the read gave, sorted.
+ *
+ * `components` must be the whole graph, not the selection: the dependency a
+ * selected member reads is often one the change did not select.
+ */
+export async function readDeployedOutputs(
+  names: readonly string[],
+  components: ReadonlyMap<string, DriverComponent>,
+  registry: CapabilityRegistry,
+  ctxOf: (component: string) => DeployContext,
+  outputs: Record<string, Record<string, unknown>>,
+): Promise<Record<string, string[]>> {
+  const read: Record<string, string[]> = {};
+  for (const name of names) {
+    if (name in outputs || name in read) continue;
+    const component = components.get(name);
+    if (!component) continue;
+    const found = await readComponentOutputs(component, registry, ctxOf(name), outputs);
+    if (!found) continue;
+    outputs[name] = found;
+    read[name] = Object.keys(found).sort();
+  }
+  return read;
+}

package/src/lifecycle/release-ledger.ts

@@ -47,16 +47,22 @@ export interface RunOrigin {
    * Which id space minted `runId`: `github` (a GitHub Actions run id — also
    * the spelling Forgejo Actions uses, since it implements the same env
    * contract; `url` disambiguates the actual host), `gitlab` (a CI pipeline
-   * id), `op` (an orchestrator/Op run id), or `local` (minted on the machine
-   * that ran the deploy, resolvable nowhere).
+   * id), `op` (an orchestrator/Op run id), `local` (minted on the machine
+   * that ran the deploy, resolvable nowhere), or `chant` (a job the chant
+   * runner ran, `chant ci run`, #4094, named by its Op run id). `chant` was
+   * added within contract 1 by {@link RUN_ORIGIN_CHANT_FLOOR}, so a reader
+   * that switches on `forge` keeps a case for a value it does not know.
    */
-  forge: "github" | "gitlab" | "op" | "local";
+  forge: "github" | "gitlab" | "op" | "local" | "chant";
   /** Repo/project slug on the forge (`GITHUB_REPOSITORY` / `CI_PROJECT_PATH`), when the environment named one. */
   repo?: string;
   /** Resolved link to the run, when the environment provided enough to build one. */
   url?: string;
 }
 
+/** The first chant that writes `runOrigin.forge: "chant"`, for a job `chant ci run` ran (#4094). */
+export const RUN_ORIGIN_CHANT_FLOOR = "0.124.30";
+
 /**
  * The gate resolution that admitted a deploy (#4020): the gate's address in the
  * gate ledger (`_gates/<op>.jsonl`, `op` and `gate`) and when the resolution

package/src/lifecycle/run-ledger.ts

@@ -38,7 +38,7 @@ import { randomUUID } from "node:crypto";
 import { sortedJsonReplacer } from "../utils";
 import type { OpConfig } from "../op/types";
 import type { StepRecord } from "../op/local-executor";
-import type { OpRunRecord, OpRunRecordInput, OpRunPhaseRecord, OpRunStepRecord } from "../op/runtime";
+import { opRunFailureOf, type OpRunRecord, type OpRunRecordInput, type OpRunPhaseRecord, type OpRunStepRecord } from "../op/runtime";
 import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
 
 /** Prefix folding the per-op run ledgers into one flat name under `<env>/`. See the module doc. */
@@ -215,6 +215,12 @@ export async function readRunLedger(
         malformed++;
         continue;
       }
+      // A `failure` (#4094) that is not one is dropped and the line kept, as a gate line's wrong-typed `gitSha` is.
+      if ("failure" in parsed) {
+        const failure = opRunFailureOf(parsed.failure);
+        if (failure) parsed.failure = failure;
+        else delete parsed.failure;
+      }
       records.push(parsed as OpRunRecord);
     } catch {
       malformed++;

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

@@ -54,6 +54,7 @@ export const shellCmdContract = activityContract(
     cmd: z.string(),
     env: z.record(z.string(), z.string()).optional(),
     cwd: z.string().optional(),
+    inheritEnv: z.boolean().optional(),
     okExit: z.array(z.number()).optional(),
     gatedExit: z.number().optional(),
     gate: z.strictObject({ op: z.string(), gate: z.string() }).optional(),

package/src/op/activities/shell.ts

@@ -13,6 +13,12 @@ export interface ShellCmdArgs {
   env?: Record<string, string>;
   /** Working directory. Default: process.cwd(). */
   cwd?: string;
+  /**
+   * Whether the command sees this process's environment. Default true. With
+   * false it sees `env` alone, plus the in-flight record's variable, so a job
+   * the chant runner runs (`chant ci run`, #4094) gets a clean environment.
+   */
+  inheritEnv?: boolean;
   /**
    * Exit codes that count as success. Default `[0]`.
    *
@@ -129,7 +135,7 @@ export async function shellCmd(args: ShellCmdArgs, signal?: AbortSignal): Promis
       cwd: args.cwd,
       // In a run that keeps an in-flight record, CHANT_RUN_ACTIVITY names the
       // file the command appends activity lines to (../run-live.ts).
-      env: { ...process.env, ...liveRunEnv(), ...args.env },
+      env: { ...(args.inheritEnv === false ? {} : process.env), ...liveRunEnv(), ...args.env },
       maxBuffer: MAX_STDOUT_BYTES,
       signal,
     });

package/src/op/local-executor.ts

@@ -56,7 +56,7 @@ import { LiveRun, currentLiveRun, withLiveRun } from "./run-live";
 import { runEnvOf } from "../lifecycle/run-ledger";
 import { resolveCommitSha } from "../lifecycle/commit-sha";
 import { resolveCiRun, type RunOrigin } from "../lifecycle/release-ledger";
-import { runEventsOfStepRecord, type RunEventRuntime, type RunEventSkipReason } from "../run-event";
+import { runEventsOfStepRecord, type RunEventKind, type RunEventRuntime, type RunEventSkipReason } from "../run-event";
 import { openRunEventStore, teeLines } from "../run-event-store";
 import { openRunEventStream, runEventRunOf, type RunEventSink, type RunEventStream } from "../run-event-stream";
 import { describePlanDigest, samePlanDigest } from "../lifecycle/plan-digest";
@@ -1300,6 +1300,24 @@ export interface RunOpOptions {
    * turn and `local` otherwise. Omitted, nothing is written.
    */
   runEvents?: { write: (line: string) => void; runtime?: RunEventRuntime; runOrigin?: RunOrigin };
+  /**
+   * What ran the Op, when a runner says so itself (#4094): `chant ci run`
+   * runs a pull-request job as an Op and passes `kind: "pipeline"`,
+   * `runtime: "ci"` and `runOrigin: { forge: "chant" }`. The run's events
+   * carry all three, kept on this host as well as written to
+   * {@link runEvents}, and the run record carries `runOrigin` in place of
+   * the CI run the environment names. Omitted, the run is an `op` run named
+   * as described on {@link runEvents}.
+   */
+  runner?: { kind: RunEventKind; runtime: RunEventRuntime; runOrigin: RunOrigin };
+  /**
+   * Says why a failed run failed (#4094), given the run's step records once
+   * it has settled `fail`. What it returns is stored on the record as
+   * `failure`, before the record is signed, and carried on the `run-settle`
+   * event. `chant ci run` reads the job's pull-request report here, while
+   * the checkout it ran in still exists.
+   */
+  describeFailure?: (records: readonly StepRecord[]) => OpRunRecord["failure"];
   /**
    * Append the run's {@link OpRunRecord} to the run ledger
    * (`../lifecycle/run-ledger.ts`) when the run settles (#2118). Opt-in on
@@ -1464,7 +1482,7 @@ async function runOpInTurn(
   const stream = eventsWrite
     ? openRunEventStream(
         runEventRunOf({
-          kind: "op",
+          kind: options.runner?.kind ?? "op",
           name: config.name,
           runId,
           ...(commit ? { gitSha: commit } : {}),
@@ -1472,6 +1490,7 @@ async function runOpInTurn(
           steward: options.steward !== undefined,
           ...(options.runEvents?.runtime ? { runtime: options.runEvents.runtime } : {}),
           ...(options.runEvents?.runOrigin ? { runOrigin: options.runEvents.runOrigin } : {}),
+          ...(options.runner ? { runtime: options.runner.runtime, runOrigin: options.runner.runOrigin } : {}),
         }),
         eventsWrite,
       )
@@ -1612,9 +1631,13 @@ async function runOpInTurn(
       ...(options.steward ? { steward: options.steward } : {}),
       ...(resumed ? { resumed } : {}),
       ...(commit ? { gitSha: commit } : {}),
-      ...(ciRun ? { runOrigin: ciRun.runOrigin } : {}),
+      ...(options.runner ? { runOrigin: options.runner.runOrigin } : ciRun ? { runOrigin: ciRun.runOrigin } : {}),
       phaseDurations,
     });
+    if (status === "fail" && options.describeFailure) {
+      const failure = options.describeFailure(settled);
+      if (failure) input.failure = failure;
+    }
     let record: OpRunRecord = { version: 1, ...input, id: runId };
     if (options.signRecord) {
       try {
@@ -1627,7 +1650,7 @@ async function runOpInTurn(
     }
     // The stream settles as the run does, with the first failing step's error.
     const firstError = status === "fail" ? settled.find((r) => r.status === "fail")?.error : undefined;
-    stream?.settle(status === "fail" ? "failed" : status, firstError);
+    stream?.settle(status === "fail" ? "failed" : status, firstError, input.failure);
     if (!options.ledger) return record;
     try {
       return (await appendRunRecord(input, options.ledger)).record;

package/src/op/runtime.ts

@@ -183,6 +183,48 @@ export interface OpRunRecord {
    * written before 0.124.28.
    */
   statement?: { payloadType: string; payload: string; signatures: { keyid: string; sig: string }[] };
+  /**
+   * Why a failed run failed (#4094), for a reader that acts on it without
+   * reading the log: a short `code`, a one-line `reason`, the phase that
+   * failed and the exit code of the command that failed. `chant ci run`
+   * writes it on every failed job, from the job's pull-request report when
+   * it wrote one (`not-a-reviewer`, `plan-failed`, `failed` and the other
+   * refusals and statuses), else `command-failed`, `setup-failed` or
+   * `build-failed`. Optional within contract 1, written by chant
+   * {@link OP_RUN_FAILURE_FLOOR} and newer; absent on a run that passed and
+   * on a run nothing explained.
+   */
+  failure?: OpRunFailureReason;
+}
+
+/** Why a run failed, on {@link OpRunRecord.failure} and on the run's `run-settle` event (#4094). */
+export interface OpRunFailureReason {
+  /** A short code: a pull-request report's refusal or status, or `command-failed`, `setup-failed`, `build-failed`. */
+  code: string;
+  /** One line a person reads. */
+  reason: string;
+  /** The phase that failed, when one did. */
+  phase?: string;
+  /** The exit code of the command that failed, when it exited with one. */
+  exitCode?: number;
+}
+
+/** The first chant that writes {@link OpRunRecord.failure} and `failure` on `run-settle` (#4094). */
+export const OP_RUN_FAILURE_FLOOR = "0.124.30";
+
+/** `value` as an {@link OpRunFailureReason}, or undefined when it is not one, so a reader drops a malformed field and keeps the record. */
+export function opRunFailureOf(value: unknown): OpRunFailureReason | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  const v = value as Record<string, unknown>;
+  if (typeof v.code !== "string" || v.code === "" || typeof v.reason !== "string") return undefined;
+  if (v.phase !== undefined && typeof v.phase !== "string") return undefined;
+  if (v.exitCode !== undefined && !Number.isInteger(v.exitCode)) return undefined;
+  return {
+    code: v.code,
+    reason: v.reason,
+    ...(typeof v.phase === "string" ? { phase: v.phase } : {}),
+    ...(typeof v.exitCode === "number" ? { exitCode: v.exitCode } : {}),
+  };
 }
 
 /** An {@link OpRunRecord} before the ledger stamps its version and mints an id. */

package/src/pr-forge.test.ts

@@ -782,6 +782,31 @@ describe("pull requests over REST (#3798)", () => {
     expect((calls[1].body as { target_branch: string }).target_branch).toBe("main");
   });
 
+  test("openPullRequests lists the heads into a base and marks forks; branchHead reads a branch's commit (#4095)", async () => {
+    const f = fakeFetch({
+      "GET /api/v1/repos/acme/infra/pulls": [
+        { number: 12, head: { ref: "x", sha: "c".repeat(40), repo: { full_name: "mallory/infra" } }, base: { ref: "main", sha: "b".repeat(40) }, user: { login: "mallory" } },
+        { number: 4, head: { ref: "y", sha: "d".repeat(40), repo: { full_name: "acme/infra" } }, base: { ref: "main", sha: "b".repeat(40) }, user: { login: "driver" } },
+        { number: 5, head: { ref: "z", sha: "e".repeat(40) }, base: { ref: "release" } },
+      ],
+      "GET /api/v1/repos/acme/infra/branches/main": { name: "main", commit: { id: "f".repeat(40) } },
+    });
+    const forge = forgejoForge({ ...fjOpts, fetch: f.fetch });
+    expect(await forge.openPullRequests!("main")).toEqual([
+      { number: 4, head: "y", headSha: "d".repeat(40), base: "main", baseSha: "b".repeat(40), author: "driver", fork: false },
+      { number: 12, head: "x", headSha: "c".repeat(40), base: "main", baseSha: "b".repeat(40), author: "mallory", fork: true },
+    ]);
+    expect(f.calls[0].url).toBe("https://forge.example/api/v1/repos/acme/infra/pulls?state=open&limit=50&page=1");
+    expect(await forge.branchHead!("main")).toBe("f".repeat(40));
+    expect(await forge.branchHead!("gone")).toBeUndefined();
+
+    const g = fakeFetch({ "GET /repos/acme/infra/pulls": [], "GET /repos/acme/infra/branches/main": { commit: { sha: SHA } } });
+    const github = githubForge({ ...gh, fetch: g.fetch });
+    expect(await github.openPullRequests!("main")).toEqual([]);
+    expect(g.calls[0].url).toBe("https://api.github.com/repos/acme/infra/pulls?state=open&base=main&per_page=100&page=1");
+    expect(await github.branchHead!("main")).toBe(SHA);
+  });
+
   test("findPullRequest takes the oldest open one from this repository, not a fork's", async () => {
     const f = fakeFetch({
       "GET /api/v1/repos/acme/infra/pulls": [

package/src/pr-forge.ts

@@ -212,6 +212,23 @@ export interface PullRequest {
   base?: string;
 }
 
+/** An open pull request as `chant ci serve` polls it (#4095). */
+export interface OpenPullRequest {
+  number: number;
+  /** Its head branch. */
+  head: string;
+  /** The commit its head branch points at. */
+  headSha: string;
+  /** The branch it merges into. */
+  base: string;
+  /** The base branch's commit as the forge last measured the pull request against it. */
+  baseSha?: string;
+  /** Who opened it. */
+  author?: string;
+  /** Its head branch lives in another repository, a fork. */
+  fork: boolean;
+}
+
 /** What {@link PrForge.mergePullRequest} merges, and how. */
 export interface MergeOptions {
   /** The head commit the caller reviewed. The merge happens only while the pull request's head is still this commit. */
@@ -339,6 +356,13 @@ export interface PrForge {
    * still throw.
    */
   mergePullRequest(pr: number, opts: MergeOptions): Promise<MergeResult>;
+  /**
+   * GitHub and Forgejo (#4095): every open pull request into `base`, with
+   * its head commit, oldest first. `chant ci serve` polls it.
+   */
+  openPullRequests?(base: string): Promise<OpenPullRequest[]>;
+  /** GitHub and Forgejo (#4095): the commit `branch` points at, or undefined when there is no such branch. */
+  branchHead?(branch: string): Promise<string | undefined>;
 }
 
 /** A GitHub or Forgejo client. */
@@ -667,6 +691,44 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
       const open = listed.filter((p) => fromHere(p, head));
       return open.map(pull).filter((p): p is PullRequest => p !== undefined).sort((a, b) => a.number - b.number)[0];
     },
+    async openPullRequests(base) {
+      // GitHub filters by base server-side; Forgejo's list is matched here.
+      const query = kind === "github" ? `?state=open&base=${encodeURIComponent(base)}` : "?state=open";
+      let listed: unknown[];
+      try {
+        listed = await api.list(`${repo}/pulls${query}`, pageParams, pageSize);
+      } catch (err) {
+        // Forgejo answers 404 while it counts the repository as empty, as findPullRequest notes.
+        if (kind !== "forgejo" || !(err instanceof ForgeApiError) || err.status !== 404) throw err;
+        await api.call("GET", repo);
+        return [];
+      }
+      const out: OpenPullRequest[] = [];
+      for (const v of listed) {
+        if (!isObject(v) || !isObject(v.head) || !isObject(v.base)) continue;
+        const number = num(v.number);
+        const head = str(v.head.ref);
+        const headSha = str(v.head.sha);
+        const into = str(v.base.ref);
+        if (number === undefined || !head || !headSha || into !== base) continue;
+        const baseSha = str(v.base.sha);
+        const author = isObject(v.user) ? str(v.user.login) : undefined;
+        out.push({ number, head, headSha, base: into, ...(baseSha ? { baseSha } : {}), ...(author ? { author } : {}), fork: !fromHere(v, head) });
+      }
+      return out.sort((a, b) => a.number - b.number);
+    },
+    async branchHead(branch) {
+      let b: unknown;
+      try {
+        b = await api.call("GET", `${repo}/branches/${branch.split("/").map(encodeURIComponent).join("/")}`);
+      } catch (err) {
+        if (err instanceof ForgeApiError && err.status === 404) return undefined;
+        throw err;
+      }
+      // GitHub names the commit `sha`, Forgejo `id`.
+      const commit = isObject(b) && isObject(b.commit) ? b.commit : undefined;
+      return commit ? str(commit.sha) ?? str(commit.id) : undefined;
+    },
     async editPullRequest(pr, change) {
       return pull(await api.call("PATCH", `${repo}/pulls/${pr}`, { ...(change.title !== undefined ? { title: change.title } : {}), ...(change.body !== undefined ? { body: change.body } : {}) }));
     },

package/src/pr-loop.test.ts

@@ -13,6 +13,7 @@ import { composeChangeSet, type ChangeSetPart } from "./change-set";
 import {
   describePlanChanged,
   memberCounts,
+  PR_REPORT_DEPLOYED_OUTPUTS_FLOOR,
   PR_REPORT_SCHEMA_ID,
   prApproveCommand,
   prNoteMarker,
@@ -109,6 +110,9 @@ const resumedReport: PrReport = {
   resumed: { applied: ["a"] },
 };
 
+/** A plan whose members read `net` and `a` from the deployed estate (#4104). */
+const deployedReport: PrReport = { ...planReport, deployedOutputs: { a: ["id"], net: ["cidr"], dns: [] } };
+
 describe("the pr-report schema", () => {
   test("is a valid schema and names this module's id", () => {
     expect(validSchema(schema)).toBe(true);
@@ -116,7 +120,7 @@ describe("the pr-report schema", () => {
   });
 
   test("every stage's report validates, and its change set validates against the change-set schema", () => {
-    for (const report of [planReport, refusedReport, appliedReport, resumedReport]) {
+    for (const report of [planReport, refusedReport, appliedReport, resumedReport, deployedReport]) {
       expectValid(report);
       expectValidChangeSet(report.changeSet);
       expect(report.changeSet.digest).toBe(report.digest);
@@ -158,6 +162,14 @@ describe("the note", () => {
     expect(renderPrNote(appliedReport)).not.toContain("Resumed");
   });
 
+  test("a plan that read dependencies from the deployed estate names each and its outputs (#4104)", () => {
+    const note = renderPrNote(deployedReport);
+    expect(note).toContain("Planned against outputs read from the deployed estate: `a` (`id`); `net` (`cidr`); `dns` (none yet).");
+    expect(renderPrNote(planReport)).not.toContain("deployed estate");
+    expect(PR_REPORT_DEPLOYED_OUTPUTS_FLOOR).toBe("0.124.30");
+    expect(schema.required).not.toContain("deployedOutputs");
+  });
+
   test("a small limit leaves the summary out rather than cutting the table", () => {
     const note = renderPrNote(planReport, { limit: 800 });
     expect(note).toContain("| `app` |");

package/src/pr-loop.ts

@@ -46,6 +46,9 @@ export const PR_REPORT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace
 /** The read-contract version the report follows. */
 export const PR_REPORT_CONTRACT = 1;
 
+/** The first chant whose report can carry `deployedOutputs` (#4104). */
+export const PR_REPORT_DEPLOYED_OUTPUTS_FLOOR = "0.124.30";
+
 /** The gate a pull request's apply waits on, unless the pipeline names another. */
 export const PR_APPLY_GATE = "pr-apply";
 
@@ -183,6 +186,14 @@ export interface PrReport {
    * the rest under the same approval and did not run them again.
    */
   resumed?: { applied: string[] };
+  /**
+   * Per dependency a member was planned against, the names of the outputs
+   * read from the deployed estate (#4104), sorted. A dependency outside the
+   * change is here too. Seeded outputs (`--seed-outputs`, a resume record)
+   * are not. Absent when nothing was read. Added within contract 1 by chant
+   * {@link PR_REPORT_DEPLOYED_OUTPUTS_FLOOR}.
+   */
+  deployedOutputs?: Record<string, string[]>;
   approval: PrApproval;
   /** Component names: which changed, which run because they depend on one, and what the change touched that no component deploys. */
   selection: {
@@ -324,6 +335,11 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
   if (report.selection.unclaimed.length > 0) {
     out.push("", `Changed, and deployed by no component: ${report.selection.unclaimed.map(code).join(", ")}.`);
   }
+  const deployed = Object.entries(report.deployedOutputs ?? {});
+  if (deployed.length > 0) {
+    const each = deployed.map(([dep, names]) => `${code(dep)} (${names.length > 0 ? names.map(code).join(", ") : "none yet"})`);
+    out.push("", `Planned against outputs read from the deployed estate: ${each.join("; ")}.`);
+  }
   if (report.status !== "nothing") {
     out.push("", `Plan digest: ${code(report.digest)}`, "", ...approvalLines(report, options.approver ?? "<you>"));
   }

package/src/run-event-stream.ts

@@ -26,6 +26,7 @@ import {
   type RunEventRun,
   type RunEventRuntime,
   type RunEventSettleStatus,
+  type RunEventFailure,
 } from "./run-event";
 
 /** Where an emitter hands a run's events, before the writer stamps them. */
@@ -174,7 +175,7 @@ export interface RunEventStream {
    */
   nested: RunEventSink;
   /** End the stream with `run-settle`, unless it has ended. */
-  settle(status: RunEventSettleStatus, error?: string): void;
+  settle(status: RunEventSettleStatus, error?: string, failure?: RunEventFailure): void;
   /** Whether `run-settle` has been written. */
   readonly settled: boolean;
 }
@@ -219,9 +220,9 @@ export function openRunEventStream(
     nested: (body) => {
       if (body.type !== "run-start" && body.type !== "run-settle") emit(body);
     },
-    settle(status, error) {
+    settle(status, error, failure) {
       if (settled) return;
-      emit({ type: "run-settle", status, durationMs: null, ...(error !== undefined ? { error } : {}) });
+      emit({ type: "run-settle", status, durationMs: null, ...(error !== undefined ? { error } : {}), ...(failure ? { failure } : {}) });
     },
     get settled() {
       return settled;

package/src/run-event.ts

@@ -105,8 +105,25 @@ export interface RunEventRunSettle {
   status: RunEventSettleStatus;
   durationMs: number | null;
   error?: string;
+  /**
+   * Why a failed run failed, as its run record's `failure` says (#4094):
+   * `chant ci run` writes it on a failed job. Optional, added within
+   * contract 1 by chant {@link RUN_EVENT_FAILURE_FLOOR}.
+   */
+  failure?: RunEventFailure;
 }
 
+/** Why a run failed: a short code, a line for a person, the phase and the exit code when known (#4094). */
+export interface RunEventFailure {
+  code: string;
+  reason: string;
+  phase?: string;
+  exitCode?: number;
+}
+
+/** The first chant that writes `failure` on `run-settle` (#4094). */
+export const RUN_EVENT_FAILURE_FLOOR = "0.124.30";
+
 export interface RunEventWaveStart {
   type: "wave-start";
   /** 1-based, into `run-start`'s `waves`. */

package/src/workspace/ci-green-forge.ts

@@ -37,6 +37,8 @@ export interface CheckRun {
    * time in milliseconds, which orders a re-run after the run it replaced.
    */
   opRun?: OpRunRef;
+  /** For a failed Op run, its record's `failure.code` (#4094), which a revoke note names. Absent otherwise. */
+  failureCode?: string;
 }
 
 /** The Op run a {@link CheckRun} stands for (#4044). */

package/src/workspace/ci-green.ts

@@ -117,6 +117,8 @@ export interface RunVerdict {
   verdict: Verdict;
   /** The Op run this is, when the source is chant runs (#4044). */
   opRun?: OpRunRef;
+  /** Why the Op run failed, its record's `failure.code` (#4094), when it says. */
+  failureCode?: string;
 }
 
 export interface PhaseVerdict {
@@ -144,7 +146,7 @@ export function evaluatePhase(phase: CiPhase, latest: readonly CheckRun[]): Phas
     if (matched.length === 0) unmatched.push(pattern);
     for (const r of matched) {
       if (runs.some((x) => x.name === r.name)) continue;
-      runs.push({ name: r.name, id: r.id, status: r.status, conclusion: r.conclusion, url: r.url, verdict: runVerdict(phase, r), ...(r.opRun ? { opRun: r.opRun } : {}) });
+      runs.push({ name: r.name, id: r.id, status: r.status, conclusion: r.conclusion, url: r.url, verdict: runVerdict(phase, r), ...(r.opRun ? { opRun: r.opRun } : {}), ...(r.failureCode ? { failureCode: r.failureCode } : {}) });
     }
   }
   const verdict: Verdict = runs.some((r) => r.verdict === "fail")
@@ -263,7 +265,8 @@ export function greenAnnotation(green: CiGreen, sha: string, verdict: CommitVerd
 /** The annotation of a revoked tag: the phase and the run that failed, and the time, signed when `signer` is given (#4031). */
 export function revokedAnnotation(green: CiGreen, sha: string, failure: NonNullable<CommitVerdict["failure"]>, at: Date, signer?: CiTagSigner): string {
   const record: CiTagRecord = { schema: 1, tag: "revoked", commit: sha, branch: green.branch, at: iso(at), ...sourceField(green), phase: failure.phase, run: runRecord(failure.run) };
-  return `ci: phase ${failure.phase} failed in ${failure.run.name} (${failure.run.conclusion ?? failure.run.status})\n\n${recordJson(record, signer)}\n`;
+  const code = failure.run.failureCode ? `, ${failure.run.failureCode}` : "";
+  return `ci: phase ${failure.phase} failed in ${failure.run.name} (${failure.run.conclusion ?? failure.run.status}${code})\n\n${recordJson(record, signer)}\n`;
 }
 
 /**
@@ -627,6 +630,7 @@ export function opRunCheckRun(record: OpRunRecord, signer: string): CheckRun {
     completedAt: settled ? record.ended : null,
     url: record.runOrigin?.url ?? null,
     opRun: { id: record.id, env: record.env, signer, statement: record.statement! },
+    ...(record.status === "fail" && record.failure ? { failureCode: record.failure.code } : {}),
   };
 }