@intentius/chant 0.124.31 → 0.124.33

package/dist/workspace/ci-green.js

@@ -41,18 +41,25 @@
  * pipelines run as chant Ops, such as one on GitLab or Forgejo, gets green
  * and revoked tags with no forge check runs. A phase's patterns then match
  * Op names, a run counts for the commit its record names as `gitSha`, and
- * the latest run of each Op decides, by its end time. A run counts only when
- * its record carries a statement signed by a runner key whose principal
- * holds the `runner` role at base (`./trust/op-run-statement.ts`); the tick
- * ignores and reports any other, so it neither greens nor revokes a commit.
- * A tick from runs signs every tag it makes, and each run in the tag's
- * record names the Op run's id and carries its statement.
+ * the latest run of each Op decides, by its end time. Signing is opt-in
+ * (#4156): an unsigned run counts, with no signer, and a run whose statement
+ * a runner key holding the `runner` role at base signed counts with that
+ * signer (`./trust/op-run-statement.ts`). A run whose statement is there and
+ * does not verify is ignored and reported, so it neither greens nor revokes
+ * a commit. With `ci.green.signedSince`, an unsigned run counts only on a
+ * strict first-parent ancestor of that commit, as an unsigned tag does. A
+ * tick given a runner key signs the tags it makes, and each run in the
+ * tag's record names the Op run's id and carries its statement when it has
+ * one.
  */
 import { judgeCommits, mergeCommits, readWorkIndex } from "./commit-links.js";
 import { execFileSync } from "node:child_process";
 import { readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError } from "./declaration.js";
 import { readRunLedger } from "../lifecycle/run-ledger.js";
-import { fetchLifecycleStatus, listFilesInDir, listLedgerTrees } from "../lifecycle/git.js";
+import { fetchLifecycleStatus, listFilesInDir, listLedgerTrees, pushLifecycleStatus, writeLedgerFiles } from "../lifecycle/git.js";
+import { ledgerRecordingOff } from "../lifecycle/no-record.js";
+import { agedOut, buildRequestAnnotation, CI_BUILD_TAG_PREFIX, planBuilds, readBuildRequests, readCiRecords, recordOf, recordPath, requestedBuild, sameRecord } from "./ci-builds.js";
+import { dispatchableWorkflows, readWorkflowSources } from "./ci-green-workflow.js";
 import { signOpRunRecord, verifyOpRunStatement } from "./trust/op-run-statement.js";
 import { gitTop } from "./tree.js";
 import { locateWorkspace } from "./which-chant.js";
@@ -75,6 +82,8 @@ export class CiGreenError extends Error {
         this.name = "CiGreenError";
     }
 }
+/** Conclusions that say a run was stopped, or never started, rather than that it failed (#4169). */
+const UNBUILT_CONCLUSIONS = new Set(["cancelled", "stale"]);
 /** Whether a check run's name matches a pattern: the whole name, `*` standing for any run of characters. */
 export function matchesCheckRun(pattern, name) {
     const re = new RegExp(`^${pattern.split("*").map((p) => p.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`, "s");
@@ -97,6 +106,8 @@ function runVerdict(phase, r) {
         return "pass";
     if (r.conclusion === "skipped")
         return phase.skipped === "pass" ? "pass" : "fail";
+    if (r.conclusion !== null && UNBUILT_CONCLUSIONS.has(r.conclusion))
+        return "unbuilt";
     return "fail";
 }
 /** Judge one phase against a commit's latest attempts. */
@@ -113,21 +124,34 @@ export function evaluatePhase(phase, latest) {
             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 = runs.some((r) => r.verdict === "fail")
-        ? "fail"
-        : runs.some((r) => r.verdict === "pending") || unmatched.length > 0
-            ? "pending"
-            : "pass";
-    return { phase: phase.name, verdict, runs, unmatched };
+    return { phase: phase.name, ...phaseVerdictOf(runs, unmatched), runs, unmatched };
+}
+/** A phase's verdict from its runs: a failure wins, then a run still going or a pattern no run matches, then a cancelled run. */
+export function phaseVerdictOf(runs, unmatched) {
+    if (runs.some((r) => r.verdict === "fail"))
+        return { verdict: "fail" };
+    if (runs.some((r) => r.verdict === "pending") || unmatched.length > 0)
+        return { verdict: "pending" };
+    if (runs.some((r) => r.verdict === "unbuilt"))
+        return { verdict: "unbuilt", reason: "cancelled" };
+    return { verdict: "pass" };
 }
 /** Judge a commit: it fails when a required phase fails, and passes when every one passes. */
 export function evaluateCommit(green, runs) {
     const latest = latestAttempts(runs);
-    const phases = green.require.map((name) => evaluatePhase(green.phases.find((p) => p.name === name), latest));
+    return commitVerdictOf(green.require.map((name) => evaluatePhase(green.phases.find((p) => p.name === name), latest)));
+}
+/**
+ * A commit's verdict from its required phases: it fails when one fails, is
+ * pending while one is, is unbuilt when one is unbuilt (#4169), and passes
+ * when every one passes.
+ */
+export function commitVerdictOf(phases) {
     const failed = phases.find((p) => p.verdict === "fail");
     if (failed)
         return { verdict: "fail", phases, failure: { phase: failed.phase, run: failed.runs.find((r) => r.verdict === "fail") } };
-    return { verdict: phases.some((p) => p.verdict === "pending") ? "pending" : "pass", phases, failure: null };
+    const verdict = phases.some((p) => p.verdict === "pending") ? "pending" : phases.some((p) => p.verdict === "unbuilt") ? "unbuilt" : "pass";
+    return { verdict, phases, failure: null };
 }
 /** A time as an annotation and a tick report write it: UTC, to the second. */
 const iso = (d) => d.toISOString().replace(/\.\d{3}Z$/, "Z");
@@ -143,7 +167,7 @@ export function windowMs(window) {
  * names the Op run's id, env and signer, and carries the run's statement.
  */
 const runRecord = (r) => r.opRun
-    ? { name: r.name, id: null, conclusion: r.conclusion, url: r.url, opRun: { id: r.opRun.id, env: r.opRun.env, signer: r.opRun.signer, statement: r.opRun.statement } }
+    ? { name: r.name, id: null, conclusion: r.conclusion, url: r.url, opRun: { id: r.opRun.id, env: r.opRun.env, signer: r.opRun.signer, ...(r.opRun.statement ? { statement: r.opRun.statement } : {}) } }
     : { name: r.name, id: r.id, conclusion: r.conclusion, url: r.url };
 /** `source: "runs"` on a record made from chant runs (#4044); nothing for check runs, so their records read as before. */
 const sourceField = (green) => (green.source === "runs" ? { source: "runs" } : {});
@@ -303,6 +327,21 @@ export function readCiTags(top, green = null, base = null) {
     }
     return out;
 }
+/**
+ * Whether the workspace at `cwd` requires signed runs (#4156): its
+ * `ci.green.signedSince`, or null when it sets none, declares no
+ * `ci.green`, or has no declaration chant can read. Signing is opt-in, so
+ * only this makes `ci serve` refuse to start without a trusted runner key
+ * and `ci run` and `chant run` warn about a run they leave unsigned.
+ */
+export function signedRunsRequired(cwd) {
+    try {
+        return readDeclaration(locateWorkspace(cwd).tree).ci?.green?.signedSince ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 /** The declaration's `ci.green`, read where `cwd` is, and the git top. */
 function readGreen(cwd) {
     const located = locateWorkspace(cwd);
@@ -376,28 +415,34 @@ export async function ciTick(req) {
     if (green.signedSince && req.runnerKey === undefined && !req.dryRun) {
         throw new Error(`ci.green.signedSince is ${green.signedSince}, so every tag the tick makes needs a statement signed by a runner key, and none was given: pass --key <runner key.pem> or set CHANT_RUNNER_KEY`);
     }
-    if (green.source === "runs" && req.runnerKey === undefined && !req.dryRun) {
-        throw new Error("the tick reads chant runs (source runs), and every tag it makes from them is signed by a runner key, and none was given: pass --key <runner key.pem> or set CHANT_RUNNER_KEY");
-    }
     const signer = req.runnerKey !== undefined ? ciTagSigner(top, base, req.runnerKey) : undefined;
     const links = await commitLinks(req.cwd, top, tracking, commits.map((c) => c.sha));
     const tags = readCiTags(top, green, base);
+    const warnings = [];
     let runs;
-    if (green.source === "runs") {
-        // The runs live on chant/lifecycle, which a CI checkout may not have yet.
-        const fetched = await fetchLifecycleStatus({ cwd: top });
-        if (fetched.status === "diverged" || fetched.status === "unreachable") {
-            throw new Error(`could not fetch chant/lifecycle, where the Op runs are recorded, from ${fetched.remote}: ${fetched.status === "diverged" ? "the local branch and the remote's have diverged" : fetched.stderr}`);
-        }
-        runs = await readOpRunSource(req.cwd, top, base);
+    // The runs and the records (#4169) live on chant/lifecycle, which a CI checkout may not have yet.
+    const fetched = await fetchLifecycleStatus({ cwd: top });
+    const ledgerOk = fetched.status !== "diverged" && fetched.status !== "unreachable";
+    if (!ledgerOk) {
+        const why = `could not fetch chant/lifecycle from ${fetched.remote}: ${fetched.status === "diverged" ? "the local branch and the remote's have diverged" : fetched.stderr}`;
+        if (green.source === "runs")
+            throw new Error(why.replace("chant/lifecycle", "chant/lifecycle, where the Op runs are recorded,"));
+        warnings.push(`${why}; no _ci records were read or written`);
     }
+    if (green.source === "runs")
+        runs = await readOpRunSource(req.cwd, top, base, green.signedSince);
+    const runsBy = new Map();
     const planned = await planTick({
         green,
         commits,
         greenTags: new Set(tags.green.keys()),
         revokedTags: new Set(tags.revoked.keys()),
         ignored: tags.ignored,
-        checkRuns: async (sha) => (runs ? runs.checkRuns(sha) : forge.checkRuns(sha)),
+        checkRuns: async (sha) => {
+            const got = runs ? runs.checkRuns(sha) : await forge.checkRuns(sha);
+            runsBy.set(sha, got);
+            return got;
+        },
         now,
         signer,
     });
@@ -411,6 +456,10 @@ export async function ciTick(req) {
                 c.ignoredRuns = ignored;
         }
     }
+    const records = ledgerOk ? readCiRecords(top) : new Map();
+    const requests = readBuildRequests(top);
+    const retryVia = green.source === "runs" ? "request" : forge?.rerun ? "forge" : null;
+    const builds = planBuilds({ green, commits: planned, runs: runsBy, requests, records, now, retryVia });
     const due = planned.filter((c) => c.made !== null);
     if (!req.dryRun && due.length > 0) {
         const ident = taggerConfig(top);
@@ -426,7 +475,217 @@ export async function ciTick(req) {
             throw new Error(`could not push ${due.map((c) => c.made.tag).join(", ")} to ${remote}: ${cause ? `${cause}\n` : ""}${stderr}`);
         }
     }
-    return { branch: green.branch, window: green.window, ref: tracking, commits: planned, made: due.map((c) => c.made.tag), signer: signer?.principal ?? null, source: green.source };
+    const retried = builds.retries.map((r) => ({ sha: r.sha, run: r.run.name }));
+    let recorded = [];
+    if (!req.dryRun) {
+        const asked = await askForBuilds({ top, remote, green, forge, builds, requests, records, planned, warnings });
+        recorded = ledgerOk && !ledgerRecordingOff() ? await writeRecords({ top, green, planned, records, builds, requests: asked.live, dispatched: asked.dispatched, now, warnings }) : [];
+    }
+    return {
+        branch: green.branch,
+        window: green.window,
+        ref: tracking,
+        commits: planned,
+        made: due.map((c) => c.made.tag),
+        requested: builds.requests,
+        retried,
+        recorded,
+        warnings,
+        signer: signer?.principal ?? null,
+        source: green.source,
+    };
+}
+/**
+ * Make what the plan asks for (#4169): push each new request tag and start
+ * the workflows holding its phases at it on GitHub, start any older request
+ * no tick has started yet, run the failed jobs again, and delete the tags of
+ * requests that are done. Each step that fails is a warning, never the
+ * tick's failure: the green tags are already pushed.
+ */
+async function askForBuilds(input) {
+    const { top, remote, green, forge, builds, warnings } = input;
+    const live = new Map(input.requests);
+    for (const tag of builds.resolved)
+        live.delete(tag.slice(CI_BUILD_TAG_PREFIX.length));
+    if (builds.requests.length > 0) {
+        const ident = taggerConfig(top);
+        const made = [];
+        for (const r of builds.requests) {
+            if (tryGit(top, [...ident, "tag", "-a", "-m", buildRequestAnnotation(r), r.tag, r.commit]) === null)
+                warnings.push(`could not make ${r.tag}`);
+            else
+                made.push(r);
+        }
+        if (made.length > 0) {
+            try {
+                git(top, ["push", "--quiet", remote, ...made.map((r) => `refs/tags/${r.tag}`)]);
+                for (const r of made)
+                    live.set(r.commit, r);
+            }
+            catch (err) {
+                for (const r of made)
+                    tryGit(top, ["tag", "-d", r.tag]);
+                const stderr = stderrOf(err);
+                warnings.push(`could not push ${made.map((r) => r.tag).join(", ")} to ${remote}: ${pushRefusalCause(stderr) ?? stderr}`);
+            }
+        }
+    }
+    const dispatched = new Set();
+    if (green.source === "checks" && forge?.dispatch) {
+        const sources = readWorkflowSources(top, "");
+        for (const r of live.values()) {
+            if (input.records.get(r.commit)?.request?.dispatched && input.records.get(r.commit)?.request?.tag === r.tag)
+                continue;
+            // A run already going at the commit was started for it, by the tick before or by `ci run --at`.
+            const c = input.planned.find((x) => x.sha === r.commit);
+            if (c?.verdict?.phases.some((p) => r.phases.includes(p.phase) && p.runs.some((x) => x.status !== "completed"))) {
+                dispatched.add(r.commit);
+                continue;
+            }
+            const { dispatchable, without } = dispatchableWorkflows(green, r.phases, sources);
+            for (const w of without)
+                warnings.push(`${w} holds a run of ${r.phases.join(", ")} and has no workflow_dispatch trigger, so ${r.tag} can't start it; regenerate it with chant ci workflow`);
+            let ok = dispatchable.length > 0;
+            for (const w of dispatchable) {
+                try {
+                    await forge.dispatch(w, r.tag);
+                }
+                catch (err) {
+                    ok = false;
+                    warnings.push(`could not start ${w} at ${r.tag}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            if (ok)
+                dispatched.add(r.commit);
+        }
+    }
+    if (forge?.rerun) {
+        for (const r of builds.retries) {
+            try {
+                await forge.rerun(r.run);
+            }
+            catch (err) {
+                warnings.push(`could not run ${r.run.name} at ${r.sha.slice(0, 12)} again, so its failure counts once the retry's hour is up: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    if (builds.resolved.length > 0) {
+        for (const tag of builds.resolved)
+            tryGit(top, ["tag", "-d", tag]);
+        if (tryGit(top, ["push", "--quiet", remote, ...builds.resolved.map((t) => `:refs/tags/${t}`)]) === null) {
+            warnings.push(`could not delete ${builds.resolved.join(", ")} on ${remote}; a done request asks for nothing, so they can stay`);
+        }
+    }
+    return { live, dispatched };
+}
+/**
+ * Write each judged commit's record, and rewrite a record whose commit left
+ * the window still pending as unbuilt (#4169), in one commit on
+ * `chant/lifecycle`, and push it. Only records whose content changed are
+ * written. A push another writer beat is tried once more on the new tip.
+ */
+async function writeRecords(input) {
+    const { top, green, planned, records, builds, requests, now, warnings } = input;
+    const writes = [];
+    const inWindow = new Set(planned.map((c) => c.sha));
+    for (const c of planned) {
+        const previous = records.get(c.sha);
+        let record = recordOf({ green, commit: c, previous, retries: builds.retries, requests, now });
+        if (record.request) {
+            const started = input.dispatched.has(c.sha) || (previous?.request?.tag === record.request.tag && previous.request.dispatched === true);
+            if (started)
+                record = { ...record, request: { ...record.request, dispatched: true } };
+        }
+        if (!sameRecord(previous, record))
+            writes.push({ path: recordPath(c.sha), content: `${JSON.stringify(record, null, 2)}\n` });
+    }
+    for (const [sha, r] of records) {
+        if (inWindow.has(sha) || r.state !== "pending")
+            continue;
+        writes.push({ path: recordPath(sha), content: `${JSON.stringify(agedOut(r, now), null, 2)}\n` });
+    }
+    if (writes.length === 0)
+        return [];
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            await writeLedgerFiles(writes, `ci: ${writes.length} commit record${writes.length === 1 ? "" : "s"}`, { cwd: top });
+        }
+        catch (err) {
+            warnings.push(`could not write the _ci records: ${err instanceof Error ? err.message : String(err)}`);
+            return [];
+        }
+        const pushed = await pushLifecycleStatus({ cwd: top });
+        if (pushed.status === "pushed" || pushed.status === "no-remote" || pushed.status === "not-recorded")
+            return writes.map((w) => w.path);
+        if (pushed.status !== "stale" || attempt === 1) {
+            warnings.push(`could not push the _ci records: ${pushed.stderr}`);
+            return [];
+        }
+        // Another writer pushed first: drop this commit, follow the remote, and write again on its tip.
+        tryGit(top, ["update-ref", "refs/heads/chant/lifecycle", "refs/heads/chant/lifecycle^"]);
+        const again = await fetchLifecycleStatus({ cwd: top });
+        if (again.status === "diverged" || again.status === "unreachable") {
+            warnings.push(`could not push the _ci records: chant/lifecycle moved on the remote and could not be fetched again`);
+            return [];
+        }
+    }
+    return [];
+}
+/**
+ * `chant ci run --at <sha>`: ask for every required phase to be built at a
+ * commit of the branch, by pushing `ci/build/<sha>`. Given a forge that can
+ * start workflows, and with the source check runs, it starts the workflows
+ * holding the phases at the tag now; otherwise the next tick does, or `ci
+ * serve --build-command` for chant runs. Once the phases pass, the tick tags
+ * the commit green like any other, so it can be cut.
+ */
+export async function requestBuild(req) {
+    const read = readGreen(req.cwd);
+    const { green, top } = read;
+    const remote = req.remote ?? "origin";
+    const tracking = `refs/remotes/${remote}/${green.branch}`;
+    try {
+        git(top, ["fetch", "--quiet", "--no-tags", remote, `+refs/heads/${green.branch}:${tracking}`, `+refs/tags/${CI_BUILD_TAG_PREFIX}*:refs/tags/${CI_BUILD_TAG_PREFIX}*`]);
+    }
+    catch (err) {
+        throw new Error(`could not fetch ${green.branch} and the build requests from ${remote}: ${stderrOf(err)}`);
+    }
+    if (req.at.startsWith("-") || tryGit(top, ["rev-parse", "--verify", "--quiet", `${req.at}^{commit}`]) === null)
+        throw new WorkspaceReadError("revision-unknown", `--at ${req.at} names no commit in this repository`);
+    const sha = git(top, ["rev-parse", `${req.at}^{commit}`]);
+    const onBranch = git(top, ["rev-list", "--first-parent", tracking]).split("\n").includes(sha);
+    if (!onBranch)
+        throw new Error(`${sha.slice(0, 12)} is not a first-parent commit of ${remote}/${green.branch}, and only those are judged green`);
+    const existing = readBuildRequests(top).get(sha);
+    const request = existing ?? requestedBuild(green, sha, green.require, req.now ?? new Date());
+    const warnings = [];
+    if (!existing) {
+        git(top, [...taggerConfig(top), "tag", "-a", "-m", buildRequestAnnotation(request), request.tag, sha]);
+        try {
+            git(top, ["push", "--quiet", remote, `refs/tags/${request.tag}`]);
+        }
+        catch (err) {
+            tryGit(top, ["tag", "-d", request.tag]);
+            const stderr = stderrOf(err);
+            throw new Error(`could not push ${request.tag} to ${remote}: ${pushRefusalCause(stderr) ?? stderr}`);
+        }
+    }
+    const dispatched = [];
+    if (green.source === "checks" && req.forge?.dispatch) {
+        const { dispatchable, without } = dispatchableWorkflows(green, request.phases, readWorkflowSources(top, ""));
+        for (const w of without)
+            warnings.push(`${w} holds a run of a required phase and has no workflow_dispatch trigger, so it can't be started at ${request.tag}`);
+        for (const w of dispatchable) {
+            try {
+                await req.forge.dispatch(w, request.tag);
+                dispatched.push(w);
+            }
+            catch (err) {
+                warnings.push(`could not start ${w} at ${request.tag}: ${err instanceof Error ? err.message : String(err)}; the next tick tries again`);
+            }
+        }
+    }
+    return { request, existed: existing !== undefined, dispatched, warnings };
 }
 const RUN_LEDGER_FILE = /^runs__(.+)\.jsonl$/;
 /**
@@ -445,18 +704,23 @@ export function opRunCheckRun(record, signer) {
         conclusion: settled ? (record.status === "ok" ? "success" : "failure") : null,
         completedAt: settled ? record.ended : null,
         url: record.runOrigin?.url ?? null,
-        opRun: { id: record.id, env: record.env, signer, statement: record.statement },
+        opRun: { id: record.id, env: record.env, signer, ...(signer !== null && record.statement ? { statement: record.statement } : {}) },
         ...(record.status === "fail" && record.failure ? { failureCode: record.failure.code } : {}),
     };
 }
 /**
  * Judge every Op run record that names a commit against `.chant/trust.json`
  * at `base` (#4044), from the run ledger the project at `cwd` writes to. A
- * record with a valid statement becomes a check run on its `gitSha`; any
- * other is kept as an ignored run. Reads local refs only.
+ * record with a valid statement becomes a check run on its `gitSha` with
+ * its signer, and an unsigned one becomes a check run with signer null
+ * (#4156). A record whose statement does not verify is kept as an ignored
+ * run. With `signedSince` (`ci.green.signedSince`) an unsigned record counts
+ * only on a strict first-parent ancestor of that commit, and is ignored
+ * elsewhere. Reads local refs only.
  */
-export async function readOpRunSource(cwd, top, base) {
+export async function readOpRunSource(cwd, top, base, signedSince = null) {
     const policy = readTrustPolicy(gitRevisionSource(top, base), base);
+    const before = signedSince ? unsignedHistory(top, signedSince) : null;
     const byCommit = new Map();
     const ignored = new Map();
     for (const env of await listLedgerTrees({ cwd })) {
@@ -468,11 +732,17 @@ export async function readOpRunSource(cwd, top, base) {
             for (const record of records) {
                 if (!record.gitSha)
                     continue;
+                // #4161: a job `ci run --local` ran stays on the machine that ran it, and is never CI's verdict.
+                if (record.runOrigin?.forge === "local")
+                    continue;
                 const v = verifyOpRunStatement(record, policy.runners, policy.roles);
-                if (v.status === "signed")
-                    byCommit.set(record.gitSha, [...(byCommit.get(record.gitSha) ?? []), opRunCheckRun(record, v.signer)]);
-                else
-                    ignored.set(record.gitSha, [...(ignored.get(record.gitSha) ?? []), { run: record.id, op: record.op, env: record.env, status: v.status, reason: v.reason }]);
+                const counts = v.status === "signed" || (v.status === "unsigned" && (before === null || before.has(record.gitSha)));
+                if (counts)
+                    byCommit.set(record.gitSha, [...(byCommit.get(record.gitSha) ?? []), opRunCheckRun(record, v.status === "signed" ? v.signer : null)]);
+                else {
+                    const reason = v.status === "unsigned" ? `${v.reason}; ci.green.signedSince is ${signedSince}, so a run on a commit that is not a strict first-parent ancestor of it needs one` : v.reason;
+                    ignored.set(record.gitSha, [...(ignored.get(record.gitSha) ?? []), { run: record.id, op: record.op, env: record.env, status: v.status, reason }]);
+                }
             }
         }
     }
@@ -562,8 +832,17 @@ export function formatTick(r, dryRun = false) {
         }
         else {
             const v = c.verdict;
-            const waiting = v.phases.filter((p) => p.verdict === "pending").map((p) => p.phase);
-            const what = c.before === "green" ? "green" : v.verdict === "fail" ? `failed: phase ${v.failure.phase}, ${v.failure.run.name} ${v.failure.run.conclusion}` : `undecided: ${waiting.join(", ")}`;
+            const why = (p) => `${p.phase}${p.reason ? ` (${p.reason}${p.coveredBy ? `, covered by ${p.coveredBy.slice(0, 12)}` : ""})` : ""}`;
+            const waiting = v.phases.filter((p) => p.verdict === "pending").map(why);
+            const unbuilt = v.phases.filter((p) => p.verdict === "unbuilt").map(why);
+            const culprit = v.phases.find((p) => p.culprit)?.culprit;
+            const what = c.before === "green"
+                ? "green"
+                : v.verdict === "fail"
+                    ? `failed: phase ${v.failure.phase}, ${v.failure.run.name} ${v.failure.run.conclusion}${culprit ? `; culprit ${culprit.slice(0, 12)}` : ""}`
+                    : v.verdict === "unbuilt"
+                        ? `unbuilt: ${unbuilt.join(", ")}`
+                        : `undecided: ${waiting.join(", ")}`;
             lines.push(`  ${short}  ${what}`);
         }
         const why = whyWorkUnknown(c.work);
@@ -578,6 +857,14 @@ export function formatTick(r, dryRun = false) {
     }
     if (r.signer && r.made.length > 0)
         lines.push(`signed as ${r.signer}`);
+    for (const q of r.requested)
+        lines.push(`${dryRun ? "would ask" : "asked"} for ${q.phases.join(", ")} at ${q.commit.slice(0, 12)} (${q.reason}): ${q.tag}`);
+    for (const x of r.retried)
+        lines.push(`${dryRun ? "would run" : "ran"} ${x.run} at ${x.sha.slice(0, 12)} again`);
+    if (r.recorded.length > 0)
+        lines.push(`recorded ${r.recorded.length} commit${r.recorded.length === 1 ? "" : "s"} on chant/lifecycle`);
+    for (const w of r.warnings)
+        lines.push(`warning: ${w}`);
     return lines.join("\n");
 }
 // ── last-green ───────────────────────────────────────────────────────────────
@@ -589,6 +876,8 @@ function branchRefOf(top, green, remote = "origin") {
         throw new CiGreenError("ci-branch-unknown", `this repository has neither ${candidates.join(" nor ")}`);
     return ref;
 }
+/** How many commits above the green one `ci last-green` reports with their records. */
+export const LAST_GREEN_NEWER = 50;
 /**
  * `chant ci last-green`: the newest first-parent commit of the branch with a
  * green tag and no revoked tag. It reads local refs and tags and never
@@ -610,16 +899,21 @@ export function lastGreen(req) {
         const tags = readCiTags(top, green, git(top, ["rev-parse", `${branchRef}^{commit}`]));
         let commit = null;
         const ignored = [];
-        if (tags.green.size > 0 || tags.ignored.size > 0) {
+        const newer = [];
+        const records = readCiRecords(top);
+        if (tags.green.size > 0 || tags.ignored.size > 0 || records.size > 0) {
             for (const sha of git(top, ["rev-list", "--first-parent", ref]).split("\n")) {
                 ignored.push(...(tags.ignored.get(sha) ?? []));
-                if (!tags.green.has(sha) || tags.revoked.has(sha))
+                if (!tags.green.has(sha) || tags.revoked.has(sha)) {
+                    if (newer.length < LAST_GREEN_NEWER)
+                        newer.push({ sha, record: recordSummary(green, records.get(sha)) });
                     continue;
+                }
                 commit = { sha, tag: `${CI_GREEN_TAG_PREFIX}${sha}`, tagged: tags.green.get(sha).tagged, committed: git(top, ["show", "-s", "--format=%cI", sha]) };
                 break;
             }
         }
-        return { ...head, workspace, branch: green.branch, ref, commit, ignored };
+        return { ...head, workspace, branch: green.branch, ref, commit, ignored, newer: commit ? newer : [] };
     }
     catch (err) {
         if (err instanceof CiGreenError || err instanceof WorkspaceReadError)
@@ -630,6 +924,17 @@ export function lastGreen(req) {
 // ── list ─────────────────────────────────────────────────────────────────────
 export const CI_LIST_CONTRACT_VERSION = 1;
 export const CI_LIST_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/ci-list/v1/ci-list.schema.json";
+/** The summary of a record, from its required phases in `require` order. */
+export function recordSummary(green, r) {
+    if (!r)
+        return null;
+    const phases = green.require.map((name) => r.phases[name]).filter((p) => p !== undefined);
+    const first = (k) => phases.find((p) => p[k] !== undefined)?.[k];
+    const reason = first("reason");
+    const coveredBy = first("coveredBy");
+    const culprit = first("culprit");
+    return { state: r.state, ...(reason ? { reason } : {}), ...(coveredBy ? { coveredBy } : {}), ...(culprit ? { culprit } : {}) };
+}
 const asRun = (r) => {
     if (!r || typeof r !== "object")
         return null;
@@ -637,7 +942,8 @@ const asRun = (r) => {
     if (typeof o.name !== "string")
         return null;
     const op = o.opRun;
-    const opRun = op && typeof op === "object" && typeof op.id === "string" && typeof op.env === "string" && typeof op.signer === "string" ? { opRun: { id: op.id, env: op.env, signer: op.signer } } : {};
+    const signer = op && typeof op === "object" ? (typeof op.signer === "string" ? op.signer : op.signer === null ? null : undefined) : undefined;
+    const opRun = op && typeof op === "object" && typeof op.id === "string" && typeof op.env === "string" && signer !== undefined ? { opRun: { id: op.id, env: op.env, signer } } : {};
     return { name: o.name, id: typeof o.id === "number" ? o.id : null, conclusion: typeof o.conclusion === "string" ? o.conclusion : null, url: typeof o.url === "string" ? o.url : null, ...opRun };
 };
 /**
@@ -693,7 +999,8 @@ export async function ciList(req) {
         const source = req.source ?? green.source;
         if (source === "runs" && req.forge)
             throw new Error("--forge reads check runs, and the source is chant runs (ci.green.source or --source runs); drop one");
-        const runs = source === "runs" ? await readOpRunSource(req.cwd, top, base) : undefined;
+        const runs = source === "runs" ? await readOpRunSource(req.cwd, top, base, green.signedSince) : undefined;
+        const records = readCiRecords(top);
         const out = [];
         for (const c of commits) {
             const g = tags.green.get(c.sha);
@@ -719,6 +1026,7 @@ export async function ciList(req) {
                 work: links?.get(c.sha) ?? null,
                 ignored: tags.ignored.get(c.sha) ?? [],
                 ...(runs ? { ignoredRuns: runs.ignored.get(c.sha) ?? [] } : {}),
+                record: recordSummary(green, records.get(c.sha)),
             });
         }
         return { ...head, workspace, branch: green.branch, ref, window: req.since === undefined ? green.window : null, since: req.since ?? null, require: [...green.require], commits: out };
@@ -729,6 +1037,11 @@ export async function ciList(req) {
         throw err;
     }
 }
+/** A record summary in words, for `ci list` and the tick. */
+export function describeRecord(r) {
+    const parts = [r.state, ...(r.reason ? [r.reason] : []), ...(r.coveredBy ? [`covered by ${r.coveredBy.slice(0, 12)}`] : []), ...(r.culprit ? [`culprit ${r.culprit.slice(0, 12)}`] : [])];
+    return parts.join(", ");
+}
 /** The text `chant ci list` prints: one line per commit. */
 export function formatList(doc) {
     const lines = [`${doc.branch}, ${doc.since ? `commits after ${doc.since}` : `commits within ${doc.window}`}: ${doc.commits.length}`];
@@ -736,6 +1049,8 @@ export function formatList(doc) {
         const phases = c.phases.map((p) => `${p.phase}=${p.result}`).join(" ");
         const why = whyWorkUnknown(c.work);
         lines.push(`  ${c.sha.slice(0, 12)}  ${c.state.padEnd(9)}  ${phases}${why ? `; why unknown: ${why}` : ""}`);
+        if (c.record && c.state === "undecided")
+            lines.push(`      recorded ${describeRecord(c.record)}`);
         for (const t of c.ignored)
             lines.push(`      ignored ${t.tag} (${t.status}): ${t.reason}`);
         for (const r of c.ignoredRuns ?? [])

package/dist/workspace/ci-last-green.schema.json

@@ -104,6 +104,55 @@
             }
           ]
         },
+        "newer": {
+          "type": "array",
+          "description": "Added within contract version 1 by #4169, written by chant 0.124.33 and newer. The first-parent commits walked past, newest first and above the one found, each with what its _ci/<sha>.json record on the local chant/lifecycle says (null when it has none), so a reader can say why the newest commits are not green. At most 50.",
+          "items": {
+            "type": "object",
+            "required": [
+              "sha",
+              "record"
+            ],
+            "properties": {
+              "sha": {
+                "type": "string",
+                "pattern": "^[0-9a-f]{40,64}$"
+              },
+              "record": {
+                "oneOf": [
+                  {
+                    "type": "null"
+                  },
+                  {
+                    "type": "object",
+                    "required": [
+                      "state"
+                    ],
+                    "properties": {
+                      "state": {
+                        "enum": [
+                          "green",
+                          "red",
+                          "unbuilt",
+                          "pending"
+                        ]
+                      },
+                      "reason": {
+                        "type": "string"
+                      },
+                      "coveredBy": {
+                        "type": "string"
+                      },
+                      "culprit": {
+                        "type": "string"
+                      }
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        },
         "ignored": {
           "type": "array",
           "description": "Added within contract version 1 by #4031, written by chant 0.124.28 and newer. The tags on the commits walked, newest first and down to the one found, that do not count for want of a valid statement. Empty when ci.green.signedSince is not set.",