@intentius/chant 0.124.27 → 0.124.28

package/dist/workspace/ci-green.js

@@ -27,11 +27,41 @@
  *
  * The forge is asked only for check runs (`./ci-green-forge.ts`). The tags
  * are fetched from and pushed to the remote with git.
+ *
+ * Signed tags (#4031): when `ci.green.signedSince` names a commit, a tag on
+ * any commit that is not a strict first-parent ancestor of it counts only
+ * when its annotation carries a statement signed by a runner key (`./trust/ci-tag-statement.ts`). Every
+ * reader here, and the release cut, ignores a tag without a valid one and
+ * reports it. A tick given a runner key signs the tags it makes. Without
+ * `signedSince` every tag counts, as before.
+ *
+ * Chant runs as the source (#4044): with `ci.green.source: "runs"` (or
+ * `--source runs`) the tick reads chant's own Op runs from the run ledger on
+ * `chant/lifecycle` in place of the forge's check runs, so a project whose
+ * 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.
  */
+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 { signOpRunRecord, verifyOpRunStatement } from "./trust/op-run-statement.js";
 import { gitTop } from "./tree.js";
 import { locateWorkspace } from "./which-chant.js";
+import { gitRevisionSource } from "./record-source.js";
+import { emptyPolicy, readTrustPolicy } from "./trust/policy.js";
+import { loadRunnerKey } from "./trust/dsse.js";
+import { signCiTagRecord, verifyCiTagStatement, CI_TAG_SIGNER_ROLE } from "./trust/ci-tag-statement.js";
+/** The environment variable a tick (#4031) and `chant run` (#4044) read a runner key from, as PEM, when `--key` is not given. */
+export const RUNNER_KEY_ENV = "CHANT_RUNNER_KEY";
 export const CI_GREEN_TAG_PREFIX = "ci/green/";
 export const CI_REVOKED_TAG_PREFIX = "ci/revoked/";
 export const CI_LAST_GREEN_CONTRACT_VERSION = 1;
@@ -80,7 +110,7 @@ export function evaluatePhase(phase, latest) {
         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) });
+            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 } : {}) });
         }
     }
     const verdict = runs.some((r) => r.verdict === "fail")
@@ -108,23 +138,36 @@ export function windowMs(window) {
         throw new Error(`ci.green.window must be a number of minutes, hours or days, such as 24h, not ${JSON.stringify(window)}`);
     return Number(m[1]) * { m: 60000, h: 3600000, d: 86400000 }[m[2]];
 }
-const runRecord = (r) => ({ name: r.name, id: r.id, conclusion: r.conclusion, url: r.url });
-/** The annotation of a green tag: a subject line, then the record as JSON. */
-export function greenAnnotation(green, sha, verdict, at) {
+/**
+ * A run as a tag's record holds it. An Op run (#4044) has no forge id; it
+ * 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: 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" } : {});
+/** The record as JSON, with the statement that signs it when a signer is given (#4031). */
+function recordJson(record, signer) {
+    return JSON.stringify(signer ? { ...record, statement: signCiTagRecord(record, signer) } : record, null, 2);
+}
+/** The annotation of a green tag: a subject line, then the record as JSON, signed when `signer` is given (#4031). */
+export function greenAnnotation(green, sha, verdict, at, signer) {
     const record = {
         schema: 1,
         tag: "green",
         commit: sha,
         branch: green.branch,
         at: iso(at),
+        ...sourceField(green),
         phases: Object.fromEntries(verdict.phases.map((p) => [p.phase, p.runs.map(runRecord)])),
     };
-    return `ci: every required phase passed (${green.require.join(", ")})\n\n${JSON.stringify(record, null, 2)}\n`;
+    return `ci: every required phase passed (${green.require.join(", ")})\n\n${recordJson(record, signer)}\n`;
 }
-/** The annotation of a revoked tag: the phase and the run that failed, and the time. */
-export function revokedAnnotation(green, sha, failure, at) {
-    const record = { schema: 1, tag: "revoked", commit: sha, branch: green.branch, at: iso(at), 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${JSON.stringify(record, null, 2)}\n`;
+/** 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, sha, failure, at, signer) {
+    const record = { 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`;
 }
 /**
  * Decide what a tick does, without touching git: a commit with no green tag
@@ -137,18 +180,22 @@ export async function planTick(input) {
     for (const c of input.commits) {
         const before = input.revokedTags.has(c.sha) ? "revoked" : input.greenTags.has(c.sha) ? "green" : "none";
         if (before === "revoked") {
-            out.push({ ...c, before, made: null });
+            const ignored = input.ignored?.get(c.sha);
+            out.push({ ...c, before, made: null, ...(ignored && ignored.length > 0 ? { ignored: [...ignored] } : {}) });
             continue;
         }
         const verdict = evaluateCommit(input.green, await input.checkRuns(c.sha));
         let made = null;
         if (before === "none" && verdict.verdict === "pass") {
-            made = { tag: `${CI_GREEN_TAG_PREFIX}${c.sha}`, message: greenAnnotation(input.green, c.sha, verdict, input.now) };
+            made = { tag: `${CI_GREEN_TAG_PREFIX}${c.sha}`, message: greenAnnotation(input.green, c.sha, verdict, input.now, input.signer) };
         }
         else if (before === "green" && verdict.verdict === "fail") {
-            made = { tag: `${CI_REVOKED_TAG_PREFIX}${c.sha}`, message: revokedAnnotation(input.green, c.sha, verdict.failure, input.now) };
+            made = { tag: `${CI_REVOKED_TAG_PREFIX}${c.sha}`, message: revokedAnnotation(input.green, c.sha, verdict.failure, input.now, input.signer) };
         }
-        out.push({ ...c, before, verdict, made });
+        const ignored = input.ignored?.get(c.sha);
+        // A tag is never moved or deleted by chant, so an ignored tag holding the name stops the tick making it.
+        const blocked = made !== null && ignored?.some((t) => t.tag === made.tag) ? made.tag : undefined;
+        out.push({ ...c, before, verdict, made: blocked ? null : made, ...(ignored && ignored.length > 0 ? { ignored: [...ignored] } : {}), ...(blocked ? { blocked } : {}) });
     }
     return out;
 }
@@ -169,19 +216,91 @@ function tryGit(top, args) {
         return null;
     }
 }
-/** The ci tags in the repository: the commits with a green tag, and those with a revoked one. */
-export function readCiTags(top) {
-    const green = new Map();
-    const revoked = new Set();
-    const lines = git(top, ["for-each-ref", "--format=%(refname:lstrip=2)%09%(taggerdate:iso-strict)", `refs/tags/${CI_GREEN_TAG_PREFIX}`, `refs/tags/${CI_REVOKED_TAG_PREFIX}`]);
-    for (const line of lines.split("\n").filter(Boolean)) {
-        const [tag, date] = line.split("\t");
-        if (tag.startsWith(CI_GREEN_TAG_PREFIX))
-            green.set(tag.slice(CI_GREEN_TAG_PREFIX.length), date ?? "");
+/** Every ci tag in the repository, read from local refs. */
+function readCiTagRefs(top) {
+    const out = [];
+    const format = "%(refname:lstrip=2)%00%(objecttype)%00%(objectname)%00%(*objectname)%00%(taggerdate:iso-strict)%00%(contents)%01";
+    const raw = git(top, ["for-each-ref", `--format=${format}`, `refs/tags/${CI_GREEN_TAG_PREFIX}`, `refs/tags/${CI_REVOKED_TAG_PREFIX}`]);
+    for (const entry of raw.split("\u0001")) {
+        const [tag, type, object, peeled, date, contents] = entry.replace(/^\n/, "").split("\u0000");
+        if (!tag)
+            continue;
+        const annotated = type === "tag";
+        let record = null;
+        // A lightweight tag has no tagger date, and its "contents" are the commit's message.
+        if (annotated && date && contents && contents.includes("{")) {
+            try {
+                const parsed = JSON.parse(contents.slice(contents.indexOf("{")));
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                    record = parsed;
+            }
+            catch {
+                record = null;
+            }
+        }
+        const green = tag.startsWith(CI_GREEN_TAG_PREFIX);
+        out.push({
+            kind: green ? "green" : "revoked",
+            sha: tag.slice((green ? CI_GREEN_TAG_PREFIX : CI_REVOKED_TAG_PREFIX).length),
+            tag,
+            tagged: date || null,
+            record,
+            target: (annotated ? peeled : object) ?? "",
+        });
+    }
+    return out;
+}
+/**
+ * The commits whose tags count unsigned under `signedSince` (#4031): its
+ * strict first-parent ancestors, the history the green branch had before the
+ * first commit whose tags must be signed. Position in history is something a
+ * committer can't set, unlike a commit's or a tag's date (ws-069 d). Throws
+ * `declaration-invalid` when `signedSince` names no commit here.
+ */
+export function unsignedHistory(top, signedSince) {
+    if (tryGit(top, ["rev-parse", "--verify", "--quiet", `${signedSince}^{commit}`]) === null) {
+        throw new WorkspaceReadError("declaration-invalid", `ci.green.signedSince names ${signedSince}, which is not a commit in this repository; it must be the full sha of the first commit on the green branch whose tags must be signed (fetch the branch if it is newer than this clone)`);
+    }
+    return new Set(git(top, ["rev-list", "--first-parent", `${signedSince}^@`]).split("\n").filter(Boolean));
+}
+/**
+ * Read the ci tags and judge each one (#4031). Without `signedSince` in
+ * `green` every tag counts, as before. With it, a tag on a strict
+ * first-parent ancestor of `signedSince` counts unsigned, and any other tag
+ * counts only when it points at the commit its name gives and its annotation
+ * carries a statement a runner key at `base` signed for that commit, tag and
+ * branch. The runner keys and roles are read from `.chant/trust.json` at
+ * `base`, the commit the caller reads the branch at. Throws
+ * `declaration-invalid` when `signedSince` names no commit here.
+ */
+export function readCiTags(top, green = null, base = null) {
+    const out = { green: new Map(), revoked: new Map(), ignored: new Map() };
+    const before = green?.signedSince ? unsignedHistory(top, green.signedSince) : null;
+    let policy;
+    const policyAtBase = () => (policy ?? (policy = base ? readTrustPolicy(gitRevisionSource(top, base), base) : emptyPolicy(null)));
+    for (const t of readCiTagRefs(top)) {
+        const counted = (signer) => (t.kind === "green" ? out.green : out.revoked).set(t.sha, { tagged: t.tagged, record: t.record, signer });
+        if (before === null) {
+            counted(null);
+            continue;
+        }
+        const ignore = (status, reason) => out.ignored.set(t.sha, [...(out.ignored.get(t.sha) ?? []), { tag: t.tag, status, reason }]);
+        if (t.target !== t.sha) {
+            ignore("mismatch", `${t.tag} points at ${t.target.slice(0, 12) || "nothing"}, not at the commit its name gives`);
+            continue;
+        }
+        if (before.has(t.sha)) {
+            counted(null);
+            continue;
+        }
+        const p = policyAtBase();
+        const v = verifyCiTagStatement(t.record, { sha: t.sha, kind: t.kind, branch: green.branch }, p.runners, p.roles);
+        if (v.status === "signed")
+            counted(v.signer);
         else
-            revoked.add(tag.slice(CI_REVOKED_TAG_PREFIX.length));
+            ignore(v.status, `${v.reason}; ci.green.signedSince is ${green.signedSince}, so a tag on a commit that is not a strict first-parent ancestor of it needs one`);
     }
-    return { green, revoked };
+    return out;
 }
 /** The declaration's `ci.green`, read where `cwd` is, and the git top. */
 function readGreen(cwd) {
@@ -195,13 +314,44 @@ function readGreen(cwd) {
         throw new WorkspaceReadError("not-a-git-repository", "the ci tags are git tags, and this directory is not in a git repository");
     return { green, top, workspace: { name: declaration.name, root: located.root, file: declaration.file } };
 }
+/**
+ * The signer a runner key makes (#4031): the principal `.chant/trust.json`
+ * at `base` lists the key for, who must hold the `runner` role. Throws when
+ * the key is not one, so a tick never makes a tag its readers would ignore.
+ */
+export function ciTagSigner(top, base, pem, what = "the tags it signed") {
+    let loaded;
+    try {
+        loaded = loadRunnerKey(pem);
+    }
+    catch (err) {
+        throw new Error(`the runner key is not an Ed25519 private key in PEM: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const policy = readTrustPolicy(gitRevisionSource(top, base), base);
+    const at = `.chant/trust.json at ${base.slice(0, 12)}`;
+    if (policy.signers.some((s) => s.key === loaded.publicKey)) {
+        throw new Error(`the runner key is a signer's key in ${policy.signersPath}; ci tags and runs are signed by a CI identity's key, never by a person's`);
+    }
+    const listed = policy.runners.find((r) => r.key === loaded.publicKey);
+    if (!listed)
+        throw new Error(`${at} lists no runner with this key, so ${what} would be ignored. Add it under "runners" first:\n  ${loaded.publicKey}`);
+    const holds = (policy.roles[CI_TAG_SIGNER_ROLE] ?? []).some((p) => p.normalize("NFKC").trim().toLowerCase() === listed.principal.normalize("NFKC").trim().toLowerCase());
+    if (!holds)
+        throw new Error(`${listed.principal} holds no ${CI_TAG_SIGNER_ROLE} role in ${at}, so ${what} would be ignored. Grant it: "roles": { "${CI_TAG_SIGNER_ROLE}": ["${listed.principal}"] }`);
+    return { principal: listed.principal, key: loaded.key, publicKey: loaded.publicKey };
+}
 /**
  * One tick: fetch the branch and the ci tags from the remote (pruning a ci
  * tag deleted there by hand), judge the first-parent commits within the
  * window, make the tags that are due and push them, never forced.
  */
 export async function ciTick(req) {
-    const { green, top } = readGreen(req.cwd);
+    const read = readGreen(req.cwd);
+    const top = read.top;
+    const green = { ...read.green, source: req.source ?? read.green.source };
+    const forge = green.source === "checks" ? (typeof req.forge === "function" ? req.forge() : req.forge) : undefined;
+    if (green.source === "checks" && !forge)
+        throw new Error("ci.green.source is checks, so the tick reads check runs and needs a forge");
     const remote = req.remote ?? "origin";
     const now = req.now ?? new Date();
     const tracking = `refs/remotes/${remote}/${green.branch}`;
@@ -221,15 +371,45 @@ export async function ciTick(req) {
         .map((line) => line.split(" "))
         .filter(([, ct]) => Number(ct) >= cutoff)
         .map(([sha, ct]) => ({ sha, committed: iso(new Date(Number(ct) * 1000)) }));
-    const tags = readCiTags(top);
+    const base = git(top, ["rev-parse", `${tracking}^{commit}`]);
+    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);
+    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);
+    }
     const planned = await planTick({
         green,
         commits,
         greenTags: new Set(tags.green.keys()),
-        revokedTags: tags.revoked,
-        checkRuns: (sha) => req.forge.checkRuns(sha),
+        revokedTags: new Set(tags.revoked.keys()),
+        ignored: tags.ignored,
+        checkRuns: async (sha) => (runs ? runs.checkRuns(sha) : forge.checkRuns(sha)),
         now,
+        signer,
     });
+    if (links)
+        for (const c of planned)
+            c.work = links.get(c.sha);
+    if (runs) {
+        for (const c of planned) {
+            const ignored = runs.ignored.get(c.sha);
+            if (ignored && ignored.length > 0)
+                c.ignoredRuns = ignored;
+        }
+    }
     const due = planned.filter((c) => c.made !== null);
     if (!req.dryRun && due.length > 0) {
         const ident = taggerConfig(top);
@@ -245,7 +425,72 @@ 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) };
+    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 RUN_LEDGER_FILE = /^runs__(.+)\.jsonl$/;
+/**
+ * An Op run as a check run (#4044): `ok` passes and `fail` fails once the
+ * run has settled; a run stopped at a gate or a decision point is still
+ * going. The id is the run's end time in milliseconds, so the latest run of
+ * an Op is its latest attempt.
+ */
+export function opRunCheckRun(record, signer) {
+    const settled = record.status === "ok" || record.status === "fail";
+    const ended = Date.parse(record.ended);
+    return {
+        id: Number.isFinite(ended) ? ended : 0,
+        name: record.op,
+        status: settled ? "completed" : record.status,
+        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 },
+    };
+}
+/**
+ * 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.
+ */
+export async function readOpRunSource(cwd, top, base) {
+    const policy = readTrustPolicy(gitRevisionSource(top, base), base);
+    const byCommit = new Map();
+    const ignored = new Map();
+    for (const env of await listLedgerTrees({ cwd })) {
+        for (const file of await listFilesInDir(env, { cwd })) {
+            const op = RUN_LEDGER_FILE.exec(file)?.[1];
+            if (!op)
+                continue;
+            const { records } = await readRunLedger(env, op, { cwd });
+            for (const record of records) {
+                if (!record.gitSha)
+                    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 }]);
+            }
+        }
+    }
+    return { checkRuns: (sha) => byCommit.get(sha) ?? [], ignored };
+}
+/**
+ * What `chant run <op> --key` signs a run's record with (#4044): the runner
+ * key `.chant/trust.json` at the checkout's `HEAD` lists for a principal
+ * holding the `runner` role. Throws when the key is not one, or `cwd` is in
+ * no git checkout.
+ */
+export function opRunSigner(cwd, pem) {
+    const top = gitTop(cwd);
+    if (!top)
+        throw new Error("a run is signed against .chant/trust.json at HEAD, and this directory is not in a git repository");
+    const head = tryGit(top, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"]);
+    if (head === null)
+        throw new Error("a run is signed against .chant/trust.json at HEAD, and this repository has no commit yet");
+    const signer = ciTagSigner(top, head, pem, "the runs it signed");
+    return (record) => signOpRunRecord(record, signer);
 }
 /**
  * Why the remote refused a tag push, when chant can tell. GitHub refuses a
@@ -272,11 +517,41 @@ function stderrOf(err) {
     const e = err;
     return String(e.stderr ?? e.message ?? err).trim();
 }
+/**
+ * Whether each commit names its work item (#4029), judged against the work
+ * records at `ref`. Undefined when the workspace declares no work kind or
+ * they can't be read: then no commit has a link state to report.
+ */
+async function commitLinks(cwd, top, ref, shas) {
+    if (shas.length === 0)
+        return undefined;
+    try {
+        const index = await readWorkIndex(cwd, top, ref);
+        if (!index)
+            return undefined;
+        return judgeCommits(top, shas, index, mergeCommits(top, shas));
+    }
+    catch {
+        // A tag and a green list stand without the link, which only explains a commit.
+        return undefined;
+    }
+}
+/** Why a commit's work item is unknown, for the text of `ci tick` and `ci list`; undefined for a commit that names one. */
+export function whyWorkUnknown(work) {
+    if (!work)
+        return undefined;
+    if (work.state === "unlinked")
+        return "no Chant-Record or Chant-Lease trailer names a work item";
+    if (work.state === "wrong")
+        return `the work item named is not there: ${work.problems.map((p) => `${p.trailer} (${p.message})`).join("; ")}`;
+    return undefined;
+}
 /** The text `chant ci tick` prints. */
 export function formatTick(r, dryRun = false) {
-    const lines = [`${r.branch}, commits within ${r.window}: ${r.commits.length}`];
+    const lines = [`${r.branch}, commits within ${r.window}${r.source === "runs" ? ", judged from chant runs" : ""}: ${r.commits.length}`];
     for (const c of r.commits) {
         const short = c.sha.slice(0, 12);
+        const before = lines.length;
         if (c.made) {
             lines.push(`  ${short}  ${dryRun ? "would make" : "made"} ${c.made.tag.slice(0, c.made.tag.lastIndexOf("/"))}${c.verdict?.failure ? `: phase ${c.verdict.failure.phase}, ${c.verdict.failure.run.name} ${c.verdict.failure.run.conclusion}` : ""}`);
         }
@@ -289,9 +564,29 @@ export function formatTick(r, dryRun = false) {
             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(", ")}`;
             lines.push(`  ${short}  ${what}`);
         }
+        const why = whyWorkUnknown(c.work);
+        if (why)
+            lines[before] += `; why unknown: ${why}`;
+        for (const t of c.ignored ?? [])
+            lines.push(`      ignored ${t.tag} (${t.status}): ${t.reason}`);
+        for (const r of c.ignoredRuns ?? [])
+            lines.push(`      ignored run ${r.run} of ${r.op} in ${r.env} (${r.status}): ${r.reason}`);
+        if (c.blocked)
+            lines.push(`      did not make ${c.blocked}: an ignored tag holds the name. Delete it to let the tick tag the commit: git push origin :refs/tags/${c.blocked}`);
     }
+    if (r.signer && r.made.length > 0)
+        lines.push(`signed as ${r.signer}`);
     return lines.join("\n");
 }
+// ── last-green ───────────────────────────────────────────────────────────────
+/** The ref a reader walks: the remote-tracking branch when there is one, else the local branch. */
+function branchRefOf(top, green, remote = "origin") {
+    const candidates = [`refs/remotes/${remote}/${green.branch}`, `refs/heads/${green.branch}`];
+    const ref = candidates.find((r) => tryGit(top, ["rev-parse", "--verify", "--quiet", `${r}^{commit}`]) !== null);
+    if (!ref)
+        throw new CiGreenError("ci-branch-unknown", `this repository has neither ${candidates.join(" nor ")}`);
+    return ref;
+}
 /**
  * `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
@@ -301,21 +596,28 @@ export function lastGreen(req) {
     const head = { $schema: CI_LAST_GREEN_SCHEMA_ID, contract: CI_LAST_GREEN_CONTRACT_VERSION, chant: readerVersion() };
     try {
         const { green, top, workspace } = readGreen(req.cwd);
-        const candidates = [`refs/remotes/${req.remote ?? "origin"}/${green.branch}`, `refs/heads/${green.branch}`];
-        const ref = candidates.find((r) => tryGit(top, ["rev-parse", "--verify", "--quiet", `${r}^{commit}`]) !== null);
-        if (!ref)
-            throw new CiGreenError("ci-branch-unknown", `this repository has neither ${candidates.join(" nor ")}`);
-        const tags = readCiTags(top);
+        const branchRef = branchRefOf(top, green, req.remote);
+        let ref = branchRef;
+        if (req.from !== undefined) {
+            if (req.from.startsWith("-") || tryGit(top, ["rev-parse", "--verify", "--quiet", `${req.from}^{commit}`]) === null) {
+                throw new WorkspaceReadError("revision-unknown", `--from ${req.from} names no commit in this repository`);
+            }
+            ref = req.from;
+        }
+        // The runner keys are read where the branch is, whichever commit the walk starts from.
+        const tags = readCiTags(top, green, git(top, ["rev-parse", `${branchRef}^{commit}`]));
         let commit = null;
-        if (tags.green.size > 0) {
+        const ignored = [];
+        if (tags.green.size > 0 || tags.ignored.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))
                     continue;
-                commit = { sha, tag: `${CI_GREEN_TAG_PREFIX}${sha}`, tagged: tags.green.get(sha) || null, committed: git(top, ["show", "-s", "--format=%cI", sha]) };
+                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 };
+        return { ...head, workspace, branch: green.branch, ref, commit, ignored };
     }
     catch (err) {
         if (err instanceof CiGreenError || err instanceof WorkspaceReadError)
@@ -323,3 +625,112 @@ export function lastGreen(req) {
         throw err;
     }
 }
+// ── 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";
+const asRun = (r) => {
+    if (!r || typeof r !== "object")
+        return null;
+    const o = 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 } } : {};
+    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 };
+};
+/** A judged run as `ci list` shows it. */
+const listRun = (r) => ({ name: r.name, id: r.opRun ? null : r.id, conclusion: r.conclusion, url: r.url, ...(r.opRun ? { opRun: { id: r.opRun.id, env: r.opRun.env, signer: r.opRun.signer } } : {}) });
+/** What the green tag's annotation recorded for a phase: its runs, all of which passed when the tag was made. */
+function recordedPhase(green, phase) {
+    const runs = green?.record?.phases?.[phase];
+    if (!Array.isArray(runs))
+        return { phase, result: "unrecorded", runs: [] };
+    return { phase, result: "pass", runs: runs.map(asRun).filter((r) => r !== null) };
+}
+/**
+ * `chant ci list`: the branch's first-parent commits within the window, each
+ * with its state from the ci tags and each required phase's result. Tags
+ * give the green and revoked results offline; only undecided commits need
+ * the forge, and only when a `forge` is given. It never fetches.
+ */
+export async function ciList(req) {
+    const head = { $schema: CI_LIST_SCHEMA_ID, contract: CI_LIST_CONTRACT_VERSION, chant: readerVersion() };
+    try {
+        const { green, top, workspace } = readGreen(req.cwd);
+        const ref = branchRefOf(top, green, req.remote);
+        const logArgs = ["log", "--first-parent", "--format=%H %ct"];
+        let cutoff = 0;
+        if (req.since !== undefined) {
+            if (tryGit(top, ["rev-parse", "--verify", "--quiet", `${req.since}^{commit}`]) === null)
+                throw new WorkspaceReadError("revision-unknown", `--since ${req.since} names no commit in this repository`);
+            logArgs.push(`${req.since}..${ref}`);
+        }
+        else {
+            cutoff = Math.floor(((req.now ?? new Date()).getTime() - windowMs(green.window)) / 1000);
+            logArgs.push(`--max-age=${cutoff}`, ref);
+        }
+        let commits = git(top, logArgs)
+            .split("\n")
+            .filter(Boolean)
+            .map((line) => line.split(" "))
+            .filter(([, ct]) => Number(ct) >= cutoff)
+            .map(([sha, ct]) => ({ sha, committed: iso(new Date(Number(ct) * 1000)) }));
+        if (req.limit !== undefined)
+            commits = commits.slice(0, req.limit);
+        const links = await commitLinks(req.cwd, top, ref, commits.map((c) => c.sha));
+        const base = git(top, ["rev-parse", `${ref}^{commit}`]);
+        const tags = readCiTags(top, green, base);
+        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 out = [];
+        for (const c of commits) {
+            const g = tags.green.get(c.sha);
+            const r = tags.revoked.get(c.sha);
+            const state = r ? "revoked" : g ? "green" : "undecided";
+            let phases = green.require.map((name) => recordedPhase(g, name));
+            let revoked = null;
+            if (r) {
+                const phase = typeof r.record?.phase === "string" ? r.record.phase : null;
+                const run = asRun(r.record?.run);
+                revoked = { tag: `${CI_REVOKED_TAG_PREFIX}${c.sha}`, tagged: r.tagged, phase, run, signer: r.signer };
+                phases = phases.map((p) => (p.phase === phase ? { phase: p.phase, result: "fail", runs: run ? [run] : [] } : p));
+            }
+            else if (!g && (runs || req.forge)) {
+                const verdict = evaluateCommit(green, runs ? runs.checkRuns(c.sha) : await req.forge.checkRuns(c.sha));
+                phases = verdict.phases.map((p) => ({ phase: p.phase, result: p.verdict, runs: p.runs.map(listRun) }));
+            }
+            out.push({
+                ...c,
+                state,
+                green: g ? { tag: `${CI_GREEN_TAG_PREFIX}${c.sha}`, tagged: g.tagged, signer: g.signer } : null,
+                revoked,
+                phases,
+                work: links?.get(c.sha) ?? null,
+                ignored: tags.ignored.get(c.sha) ?? [],
+                ...(runs ? { ignoredRuns: runs.ignored.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 };
+    }
+    catch (err) {
+        if (err instanceof CiGreenError || err instanceof WorkspaceReadError)
+            return { ...head, error: { code: err.code, message: err instanceof WorkspaceReadError ? err.describe() : err.message } };
+        throw err;
+    }
+}
+/** 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}`];
+    for (const c of doc.commits) {
+        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}` : ""}`);
+        for (const t of c.ignored)
+            lines.push(`      ignored ${t.tag} (${t.status}): ${t.reason}`);
+        for (const r of c.ignoredRuns ?? [])
+            lines.push(`      ignored run ${r.run} of ${r.op} in ${r.env} (${r.status}): ${r.reason}`);
+    }
+    return lines.join("\n");
+}