@intentius/chant 0.124.32 → 0.124.33

package/dist/workspace/ci-green.js

@@ -56,7 +56,10 @@ 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";
@@ -79,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");
@@ -101,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. */
@@ -117,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");
@@ -398,22 +418,31 @@ export async function ciTick(req) {
     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, green.signedSince);
+    // 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,
     });
@@ -427,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);
@@ -442,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$/;
 /**
@@ -589,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);
@@ -605,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 ───────────────────────────────────────────────────────────────
@@ -616,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
@@ -637,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)
@@ -657,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;
@@ -722,6 +1000,7 @@ export async function ciList(req) {
         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, green.signedSince) : undefined;
+        const records = readCiRecords(top);
         const out = [];
         for (const c of commits) {
             const g = tags.green.get(c.sha);
@@ -747,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 };
@@ -757,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}`];
@@ -764,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.",

package/dist/workspace/ci-list.schema.json

@@ -284,9 +284,10 @@
                         "pass",
                         "fail",
                         "pending",
+                        "unbuilt",
                         "unrecorded"
                       ],
-                      "description": "pass and fail come from the tags (a green tag records the phases that passed, a revoked tag the one that failed) or, for an undecided commit, from the forge under --forge, or from the signed Op runs on the local chant/lifecycle when the source is chant runs (#4044). pending is such a read with runs still going or not yet reported. unrecorded means no tag holds the result and nothing was read."
+                      "description": "pass and fail come from the tags (a green tag records the phases that passed, a revoked tag the one that failed) or, for an undecided commit, from the forge under --forge, or from the signed Op runs on the local chant/lifecycle when the source is chant runs (#4044). pending is such a read with runs still going or not yet reported. unbuilt (#4169, chant 0.124.33 and newer) is such a read whose runs were cancelled. unrecorded means no tag holds the result and nothing was read."
                     },
                     "runs": {
                       "type": "array",
@@ -406,6 +407,39 @@
                   }
                 ]
               },
+              "record": {
+                "description": "Added within contract version 1 by #4169, written by chant 0.124.33 and newer. What the commit's _ci/<sha>.json record on the local chant/lifecycle says, the tick's last word on it, or null when it has none. state is green, red, unbuilt or pending. reason, coveredBy and culprit come from the required phases: why a phase is unbuilt or still pending (cancelled, superseded, retrying, requested, request-unserved or aged-out), the newer commit whose run covers a superseded phase, and the commit a bisect found broke a phase. Each is absent when no phase has one.",
+                "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 commit's ci tags that do not count for want of a valid statement signed by a runner key. A tag on any commit that is not a strict first-parent ancestor of ci.green.signedSince needs one; empty when signedSince is not set. state, green and revoked count only the tags that are not ignored.",

package/dist/workspace/ci-run-index.d.ts

@@ -38,7 +38,7 @@ export declare const CI_RUN_INDEX_KEY = "runs/index.json";
 export declare const CI_RUN_INDEX_LIMIT = 200;
 /** One job the runner ran. */
 export interface CiRunIndexEntry {
-    job: "plan" | "apply";
+    job: "plan" | "apply" | "record";
     /** The pull request, or null when the job found none. */
     pr: number | null;
     commit: string;

package/dist/workspace/ci-run-index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ci-run-index.d.ts","sourceRoot":"","sources":["../../src/workspace/ci-run-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGtD,OAAO,EAAwC,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAG3H,eAAO,MAAM,sBAAsB,0FAA0F,CAAC;AAC9H,eAAO,MAAM,qBAAqB,IAAI,CAAC;AACvC,6CAA6C;AAC7C,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAC7C,qDAAqD;AACrD,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAClD,8DAA8D;AAC9D,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACtB,yDAAyD;IACzD,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,IAAI,GAAG,MAAM,CAAC;IACtB,qEAAqE;IACrE,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,8FAA8F;IAC9F,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,SAAS,CAAC;IACrB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,sBAAsB,CAAC;IACvC,QAAQ,EAAE,OAAO,qBAAqB,CAAC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,IAAI,EAAE,eAAe,EAAE,CAAC;CACzB;AAID,2GAA2G;AAC3G,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAc7G;AAED,qGAAqG;AACrG,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,eAAe,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,EAAE,CAEtH;AAKD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACtC,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,eAAe,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,SAAS,CAAC;CACjB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuChB;AAED,gHAAgH;AAChH,wBAAsB,cAAc,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,GAAE,SAA6B,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAQzH;AAED,uEAAuE;AACvE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAS1D;AAID,iEAAiE;AACjE,wBAAsB,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAepE"}
+{"version":3,"file":"ci-run-index.d.ts","sourceRoot":"","sources":["../../src/workspace/ci-run-index.ts"],"names":[],"mappings":"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"}

package/dist/workspace/ci-run-index.schema.json

@@ -23,7 +23,7 @@
       "if": { "properties": { "status": { "const": "fail" } } },
       "then": { "required": ["failure"], "properties": { "failure": { "type": "object" } } },
       "properties": {
-        "job": { "enum": ["plan", "apply"] },
+        "job": { "enum": ["plan", "apply", "record"], "description": "record (#4168, chant 0.124.33 and newer): the merge record job." },
         "pr": { "type": ["integer", "null"], "minimum": 1, "description": "The pull or merge request number: the one the job's report names, else --pr. null when neither has one." },
         "commit": { "type": "string", "pattern": "^[0-9a-f]{40,64}$", "description": "The full commit the job ran at." },
         "status": { "enum": ["ok", "fail"] },