@codyswann/lisa 4.26.0 → 4.26.2

package/typescript/copy-overwrite/scripts/check-nightly-e2e-health.mjs

@@ -28,9 +28,24 @@
  * it stays red, closed when a complete green run lands.
  *
  * They are separate because filing is reporting, not verdict. Issue writes live
- * behind `apiWrite`, reachable only from `runReport`; the gate path cannot reach
- * them, and the gate's reusable workflow requests no `issues:` scope. An Issues
- * API that is down must never be able to redden a required check.
+ * behind `apiWrite`, reachable only from `applyIssuePlan`, which only
+ * `--report-issues` reaches; the gate path cannot reach them, and the gate's
+ * reusable workflow requests no `issues:` scope. An Issues API that is down must
+ * never be able to redden a required check.
+ *
+ * ## `--report-issues` publishes BEST EFFORT, and the summary is the report
+ *
+ * The tracking issue is a convenience; the verdict is the product. So the
+ * reporting half resolves the verdict, writes it to `$GITHUB_STEP_SUMMARY`
+ * FIRST, and only then attempts to publish — with the publish's outcome
+ * absorbed into a `::warning::` that cannot change the job's result. A report
+ * channel must not die because its optional publishing destination is
+ * unavailable, which is precisely what a repository that switched GitHub Issues
+ * off measured: three attempts at `POST /repos/{o}/{r}/issues`, HTTP 410, exit 1
+ * — a dead publisher reported as a dead reporter (§10.4).
+ *
+ * Its exit code therefore answers "is the suite green", and nothing else. See
+ * §10.4 for the full three-outcome contract.
  *
  * Zero dependencies and no install step, on purpose: a gate that sits on every
  * pull request has to be cheap enough to stay uncontroversial, and a gate that
@@ -96,6 +111,42 @@
  * label, because manufacturing a bypass surface in a repository that never
  * adopted §6 is a new hole rather than a closed one.
  *
+ * ## The newest run is not the newest CONCLUSIVE run (contract 1.8.0, rows 41-42)
+ *
+ * Measured on 2026-08-29 in a consuming repository: two runs of the same native
+ * suite, seven seconds apart. The first concluded `success` with all eight jobs
+ * green — the whole suite executed. The second concluded `cancelled` with one
+ * cancelled preflight job and nothing else, because the suite's `concurrency`
+ * group keeps only ONE pending run and displaces the rest. The second run tested
+ * nothing, but it was the newest completed run, so the gate scored it and
+ * reported `⚪ UNKNOWN [cancelled]` over a suite that had genuinely passed. The
+ * gate is a required check, so that blocked every merge for three hours.
+ *
+ * Refusing to score a cancellation green stays exactly as it was (rows 6-8).
+ * The defect is one layer upstream: SELECTION. `observe` now walks candidates
+ * newest-first and stops at the first that produced evidence.
+ *
+ * "Produced evidence" is decided from the run's JOBS, not from a status
+ * allowlist, because `cancelled` is overloaded across at least three causes —
+ * a duplicate displaced by the concurrency group (tested nothing), a job killed
+ * at its own `timeout-minutes` ceiling (tested most of the suite), and an
+ * operator cancel (anywhere in between) — and only the first may ever be walked
+ * past. See `runProducedEvidence`.
+ *
+ * Bounded twice over: the walk stops at the first run with evidence, and it
+ * never leaves the arm's own freshness window. Without the second bound a stale
+ * green could hold the gate open indefinitely, which is the opposite failure and
+ * a worse one. When nothing conclusive is found inside the window it falls back
+ * to the newest run, so `stale_run` / `indecisive_conclusion` / `no_run` still
+ * fire and the gate still blocks. That fallback is what makes this change unable
+ * to invent a pass: it may only ever promote an older FRESH, CONCLUSIVE run over
+ * a run that tested nothing.
+ *
+ * And it SAYS SO. The original failure was silent — a real verdict was replaced
+ * with no trace — so every finding carries a `selection` record naming the run
+ * that was scored and every run walked past with the reason. A gate that quietly
+ * changes which run it scores is the same class of defect one layer down.
+ *
  * ## Inherited from three implementations, with one path closed
  *
  * `DECISIVE_CONCLUSIONS` comes from acmeorgb's `check-nightly-e2e.mjs` and is
@@ -118,7 +169,7 @@ import { invokedAsScript } from "./lib/invoked-as-script.mjs";
  * rather than running a contract neither half agrees on. See §8 of
  * `docs/nightly-e2e-gate.md` for what counts as major / minor / patch.
  */
-export const NIGHTLY_E2E_CONTRACT_VERSION = "1.7.0";
+export const NIGHTLY_E2E_CONTRACT_VERSION = "1.9.0";
 
 /**
  * The conclusions that constitute a verdict about the code.
@@ -152,6 +203,19 @@ export const GREEN_CONCLUSION = "success";
  */
 export const COUNTED_EVENTS = Object.freeze(["schedule", "workflow_dispatch"]);
 
+/**
+ * How many completed runs per event the selection walk (rows 41-42) may read.
+ *
+ * Bounded on purpose. The walk exists to step over runs that tested nothing, and
+ * every candidate it examines costs a job read on the merge-gate path; an
+ * unbounded walk would turn a long chain of displaced duplicates into an
+ * unbounded number of requests. Ten is ample — the measured displacement chain
+ * that motivated this was two runs, seven seconds apart — and in the ordinary
+ * case where the newest run is conclusive the walk still reads exactly one run's
+ * jobs, the same as before. The freshness window bounds it a second time.
+ */
+export const RUN_CANDIDATE_PAGE_SIZE = 10;
+
 /** Suite states. `unknown` is "no readable verdict", which is not a pass. */
 export const SUITE_STATES = Object.freeze({
   pass: "pass",
@@ -814,6 +878,67 @@ export function stateForConclusion(conclusion) {
   return SUITE_STATES.unknown;
 }
 
+/**
+ * Whether a run produced EVIDENCE about the code — rows 41-42's discriminator.
+ *
+ * This decides only whether a run is worth SCORING, never what its verdict is.
+ * A run with evidence goes to `assessSuite` and is judged there exactly as
+ * before; a run without evidence is stepped over so the next-older candidate can
+ * be judged instead.
+ *
+ * Evidence is read from the run's JOBS rather than from a status allowlist,
+ * because `cancelled` is overloaded across at least three distinct causes — a
+ * duplicate displaced by the suite's `concurrency` group (tested nothing), a job
+ * killed at its own `timeout-minutes` ceiling (tested most of the suite), and an
+ * operator cancel (anywhere in between). A status-only rule cannot tell them
+ * apart, and only the first may ever be walked past.
+ *
+ * Four cases, and three of them answer "scoreable":
+ *
+ * 1. A DECISIVE run conclusion is evidence whatever it says — including
+ *    `failure`. Nothing here may skip over a red run to find an older green.
+ * 2. An indecisive conclusion whose jobs contain at least one decisive outcome
+ *    is PARTIAL evidence. Scoreable, and it will block, because a suite killed
+ *    part-way through reached no verdict. Deliberately not skipped: walking past
+ *    it to an older green would RELAX the gate, which is the failure mode a fix
+ *    here must not introduce.
+ * 3. An UNREAD job list — empty, or a list that would not load, whether it
+ *    failed on the first page or part-way through — is scoreable. Fail-closed:
+ *    a completed run always has at least one job, so an empty list is an unread
+ *    one, and "we could not check" is never grounds to skip a run. A PARTIAL
+ *    read belongs here rather than in case 4 for exactly the same reason: 100
+ *    indecisive jobs and an unreadable page 2 do not show that the run tested
+ *    nothing, and skipping it would hide a failure on the page that would not
+ *    load behind an older green.
+ * 4. An indecisive conclusion whose job list was read IN FULL and holds no
+ *    decisive outcome tested nothing. This is the only case that is skipped.
+ *
+ * @param {object} run - An Actions run
+ * @param {ReadonlyArray<object>|null|undefined} jobs - That run's jobs, as read
+ * @param {boolean} [complete] - Whether that job list was read to its end; a partial read is never grounds to skip
+ * @returns {boolean} True when the run is worth scoring
+ */
+export function runProducedEvidence(run, jobs, complete = true) {
+  if (DECISIVE_CONCLUSIONS.has(run?.conclusion)) return true;
+  if (!Array.isArray(jobs) || jobs.length === 0) return true;
+  if (complete !== true) return true;
+  return jobs.some(job => DECISIVE_CONCLUSIONS.has(job?.conclusion));
+}
+
+/**
+ * Counts how many of a run's jobs reached a verdict.
+ *
+ * Carried onto the `selection` record so the report can say "0 of 1 job(s)
+ * reached a verdict" rather than the unfalsifiable "it tested nothing".
+ *
+ * @param {ReadonlyArray<object>|null|undefined} jobs - A run's jobs
+ * @returns {number} How many carry a decisive conclusion
+ */
+export function countDecisiveJobs(jobs) {
+  if (!Array.isArray(jobs)) return 0;
+  return jobs.filter(job => DECISIVE_CONCLUSIONS.has(job?.conclusion)).length;
+}
+
 /**
  * Reads the scope markers a run published, from its artifact NAMES.
  *
@@ -969,7 +1094,16 @@ export function assessSuiteScope(suite, scope) {
  * @returns {{label: string, state: string, reason: string, conclusion: string|null, url: string|null, createdAt: string|null, event: string|null}} The finding
  */
 export function assessSuite(suite, observation, context) {
-  const base = { label: suite.label, workflow: suite.workflow };
+  // Rows 41-42. Attached to EVERY return path, because the defect being fixed
+  // was a gate silently changing which run it scored — a selection nobody can
+  // see is the same class of defect one layer down. Attached only when the
+  // observation carried one, so a caller that never went through `observe`
+  // produces byte-identical findings.
+  const base = {
+    label: suite.label,
+    workflow: suite.workflow,
+    ...(observation.selection ? { selection: observation.selection } : {}),
+  };
   const blank = { conclusion: null, url: null, createdAt: null, event: null };
   // An observation with no `scope` at all is the same fact as an artifacts list
   // that would not load — "nobody asked" and "the answer did not come back" are
@@ -993,6 +1127,27 @@ export function assessSuite(suite, observation, context) {
    * @returns {object} The finding
    */
   const green = (seen, reason) => {
+    // Row 26's rule, applied to the half of it a job list cannot show you.
+    // Every green below is argued from the jobs that were READ, so a list the
+    // walk could not finish reading cannot support one: a `success` run whose
+    // page 2 would not load looks, from page 1, exactly like a `success` run
+    // with nothing behind it — and the failing shard hides on the page that
+    // 404'd. The empty-list case already landed on `incomplete_run` for this
+    // reason; a PARTIAL read is the same "we could not check", and it must not
+    // render as "it is fine" either.
+    //
+    // Placed inside `green` on purpose, so it can only ever turn a PASS into
+    // `unknown`. A decisive run or job conclusion returns before reaching here,
+    // which keeps `failure` conclusive and unswallowable — an unreadable page
+    // is never allowed to soften a red into an inconclusive.
+    if (observation.jobsComplete === false) {
+      return {
+        ...base,
+        ...seen,
+        state: SUITE_STATES.unknown,
+        reason: INCOMPLETE_EVIDENCE_REASON,
+      };
+    }
     const disqualifier = assessSuiteScope(suite, scope);
     if (disqualifier) {
       return {
@@ -1544,14 +1699,15 @@ const REASON_TEXT = Object.freeze({
     "the workflow file this gate watches does not exist any more. Someone renamed or deleted the suite out from under the gate — fix the `suites` table or restore the workflow.",
   no_run: "no completed run on this branch at all.",
   stale_run: "no completed run inside the freshness window.",
-  wrong_branch: "the newest run is on a different branch.",
-  stale_sha: "the newest run is for a different commit than the one required.",
+  wrong_branch: "the run this gate scored is on a different branch.",
+  stale_sha:
+    "the run this gate scored is for a different commit than the one required.",
   indecisive_conclusion:
-    "the newest run reached no verdict about the code (cancelled / skipped / neutral). That is not a green — cancelling a run must never be a one-click way to clear a merge gate.",
+    "the run this gate scored reached no verdict about the code (cancelled / skipped / neutral). That is not a green — cancelling a run must never be a one-click way to clear a merge gate. The `↳` line beneath names the run that was scored and every run walked past for having tested nothing, so a displaced duplicate is no longer mistaken for last night's verdict.",
   job_not_found:
     "the run completed without ever producing the job this gate reads. The job was renamed, which silently disarms the gate.",
   pattern_matched_nothing:
-    "the job pattern matched zero jobs in the newest run. Zero matches is the signature of a renamed job.",
+    "the job pattern matched zero jobs in the run this gate scored. Zero matches is the signature of a renamed job.",
   [INCOMPLETE_EVIDENCE_REASON]:
     "the run reported `success`, but it did not run everything: at least one job was skipped, failed under `continue-on-error`, or could not be read. A run that skipped part of itself did not gather the evidence its green claims — a suite re-run for one platform only is not a verdict about the other one. Re-run the suite WITHOUT narrowing it.",
   [FILTERED_RUN_REASON]:
@@ -1610,6 +1766,53 @@ export function formatFinding(finding) {
   return `${marker} ${finding.label} — ${verdictWord}${conclusion}${when} — ${detail}${scopeDetail}${link}${grace}`;
 }
 
+/**
+ * Renders which run a finding was scored on, and every run walked past.
+ *
+ * Rows 41-42, and it prints on EVERY finding that has a selection — greens
+ * included. The defect this closes was silent: a run that tested nothing
+ * replaced the verdict of a run that tested everything, with no trace, and three
+ * hours went into debugging a suite that was fine. A gate that quietly changes
+ * which run it scores is the same defect one layer down, so the selection is not
+ * conditional on anything having gone wrong.
+ *
+ * A scored run that reached NO verdict also names its cause, from the job
+ * counts the walk already read. `cancelled` is overloaded across a displaced
+ * duplicate, a job killed at its own `timeout-minutes` ceiling, and an operator
+ * cancel; "0 of 1 job(s) reached a verdict" and "7 of 8" are different enough
+ * that a reader can tell "it never started" from "it ran out of time" without
+ * opening the run. That costs nothing — the counts come from jobs already
+ * fetched, and no workflow job configuration is read to produce them.
+ *
+ * A DECISIVE conclusion gets no such suffix. `success` and `failure` already say
+ * what happened, and appending job arithmetic to every green is noise.
+ *
+ * @param {object|null|undefined} selection - The finding's selection record
+ * @returns {string|null} One trailing line, or null when there is nothing to say
+ */
+export function formatSelection(selection) {
+  if (!selection) return null;
+  const conclusion = selection.conclusion ?? null;
+  const counted =
+    !DECISIVE_CONCLUSIONS.has(conclusion) &&
+    typeof selection.decisiveJobs === "number" &&
+    typeof selection.totalJobs === "number";
+  const cause = counted
+    ? ` — ${selection.decisiveJobs} of ${selection.totalJobs} job(s) reached a verdict, so it ${selection.decisiveJobs === 0 ? "tested nothing" : "ran but did not finish"}`
+    : "";
+  const scored = `↳ scored run ${selection.runId ?? "?"} (${conclusion ?? "no conclusion"}${cause}, ${selection.createdAt ?? "unknown time"})`;
+  const fallback = selection.fellBack
+    ? " (no conclusive run in the freshness window — fell back to the newest)"
+    : "";
+  const skipped = (selection.skipped ?? [])
+    .map(
+      entry =>
+        `${entry.runId ?? "?"} [${entry.conclusion ?? "no conclusion"} — ${entry.decisiveJobs} of ${entry.totalJobs} job(s) reached a verdict, so it tested nothing]`
+    )
+    .join(", ");
+  return `${scored}${fallback}${skipped ? `; skipped ${skipped}` : ""}`;
+}
+
 /**
  * Renders the full report.
  *
@@ -1619,7 +1822,13 @@ export function formatFinding(finding) {
  */
 export function formatReport(verdict, context) {
   const lines = ["## 🌙 Nightly E2E Health", ""];
-  lines.push(...verdict.findings.map(finding => `- ${formatFinding(finding)}`));
+  lines.push(
+    ...verdict.findings.flatMap(finding => {
+      const line = `- ${formatFinding(finding)}`;
+      const selection = formatSelection(finding.selection);
+      return selection === null ? [line] : [line, `  - ${selection}`];
+    })
+  );
   lines.push("");
 
   // A limit the caller asked for and did not get must be visible, or the gate
@@ -2084,7 +2293,11 @@ function issueBody(finding, context) {
     `| Workflow | \`${finding.workflow ?? "—"}\` |`,
     `| Branch | \`${context.branch}\` |`,
     `| Blocks merges | ${blockingCell} |`,
-    `| Newest run | ${finding.conclusion ?? "—"}${finding.createdAt ? ` at ${finding.createdAt}` : ""}${finding.event ? ` via \`${finding.event}\`` : ""} |`,
+    // "Scored", not "Newest": since the selection walk landed, the run this
+    // row describes is the newest CONCLUSIVE one, which may be older than the
+    // newest candidate. Labelling it "Newest" would reintroduce the exact
+    // confusion the walk exists to remove.
+    `| Scored run | ${finding.conclusion ?? "—"}${finding.createdAt ? ` at ${finding.createdAt}` : ""}${finding.event ? ` via \`${finding.event}\`` : ""} |`,
     `| Why it is not green | ${detail || finding.reason} |`,
     `| Last checked | ${context.now.toISOString()} |`,
     "",
@@ -2278,11 +2491,42 @@ function bypassLabelSummary(context) {
 }
 
 /**
- * Renders the reporting outcome for the job log and summary.
+ * Renders the VERDICT — which suites are green and which are not.
+ *
+ * Written to the job summary before any publishing is attempted (§10.4), which
+ * is the whole reason it is a separate renderer from `formatIssueReport`: this
+ * one describes the suites and needs nothing from the Issues API, so it survives
+ * an Issues API that is switched off, throttled or forbidden.
+ *
+ * @param {ReadonlyArray<object>} findings - Output of `assessSuite`, per suite
+ * @param {{branch: string}} context - Reporting context
+ * @returns {string} Markdown
+ */
+export function formatVerdictReport(findings, context) {
+  const red = findings.filter(finding => finding.state === SUITE_STATES.fail);
+  const lines = [
+    red.length > 0
+      ? `## 🔴 Nightly E2E verdict — ${red.length} suite(s) not green`
+      : "## 🌙 Nightly E2E verdict",
+    "",
+    `Branch: \`${context.branch}\``,
+    "",
+    ...findings.map(finding => `- ${formatFinding(finding)}`),
+    "",
+    // Said here, on the surface the verdict lands on, rather than only in the
+    // contract: the next reader of a run whose publish warned needs to know
+    // that they are already looking at the report.
+    "**This section is the report.** Publishing it to a GitHub tracking issue is a best-effort side-effect recorded below; a publish that fails leaves this verdict untouched and does not change this job's result.",
+    "",
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * The publishing half of the job summary — what happened to the issues.
  *
  * @param {ReadonlyArray<object>} results - Output of `applyIssuePlan`
- * @param {{branch: string, requiredness?: object, gateContext?: string,
- *   bypassLabel?: string, bypassLabelState?: object}} context - Reporting context
+ * @param {object} context - `{branch, requiredness, gateContext, bypassLabel, bypassLabelState, publishFailure}`
  * @returns {string} Markdown
  */
 export function formatIssueReport(results, context) {
@@ -2310,6 +2554,17 @@ export function formatIssueReport(results, context) {
     "",
     ...bypassLabelSummary(context),
   ];
+  // The publish died outright rather than per-suite. Said on the summary as
+  // well as in the annotation, because the annotation scrolls off a busy run
+  // page and this section is where a reader goes looking for it.
+  if (context.publishFailure) {
+    lines.push(
+      `- ⚠️ **Nothing was published** — ${context.publishFailure}`,
+      "",
+      "The verdict above is unaffected: it was written before publishing was attempted, and this job's result reflects the SUITE, not the publish.",
+      ""
+    );
+  }
   for (const result of results) {
     const where = result.issues.length
       ? ` (#${result.issues.join(", #")})`
@@ -2328,7 +2583,7 @@ export function formatIssueReport(results, context) {
   }
   lines.push(
     "",
-    "This job REPORTS; it does not gate. Nothing here can block a pull request — the merge gate is a separate workflow that never writes.",
+    "This job REPORTS; it does not gate. Nothing here can block a pull request — the merge gate is a separate workflow that never writes. This job's own result answers whether the SUITE is green, never whether publishing worked: a tracking issue that could not be written is a ⚠️ above, not a failure.",
     ""
   );
   return `${lines.join("\n")}\n`;
@@ -2449,29 +2704,37 @@ export async function apiGet(api, path, wait = sleep) {
 }
 
 /**
- * Newest completed run of one workflow on one branch for one event.
+ * The newest completed runs of one workflow on one branch for one event.
+ *
+ * Reads a bounded PAGE rather than a single run, which is rows 41-42's whole
+ * mechanism. `per_page: "1"` made "the newest run" and "the newest run that
+ * tested anything" the same query; they are not, and a displaced duplicate that
+ * executed nothing is routinely the newer of the two.
  *
  * @param {object} api - API coordinates
  * @param {string} file - Workflow file name
  * @param {string} branch - Branch to read
  * @param {string} event - Run event
  * @param {(ms: number) => Promise<void>} [wait] - Injectable sleep
- * @returns {Promise<{run: object|null, missing: boolean}>} The newest run, or a 404 marker
+ * @returns {Promise<{runs: ReadonlyArray<object>, missing: boolean}>} The candidates, or a 404 marker
  */
-export async function fetchNewestRun(api, file, branch, event, wait) {
+export async function fetchRunCandidates(api, file, branch, event, wait) {
   const query = new URLSearchParams({
     branch,
     status: "completed",
     event,
-    per_page: "1",
+    per_page: String(RUN_CANDIDATE_PAGE_SIZE),
   });
   const result = await apiGet(
     api,
     `/repos/${api.repo}/actions/workflows/${encodeURIComponent(file)}/runs?${query}`,
     wait
   );
-  if (result === null) return { run: null, missing: true };
-  return { run: result.body.workflow_runs?.[0] ?? null, missing: false };
+  if (result === null) return { runs: Object.freeze([]), missing: true };
+  return {
+    runs: Object.freeze(result.body.workflow_runs ?? []),
+    missing: false,
+  };
 }
 
 /**
@@ -2482,10 +2745,18 @@ export async function fetchNewestRun(api, file, branch, event, wait) {
  * Hitting the page cap while still unread is raised rather than silently
  * truncated.
  *
+ * `complete` says whether the walk reached the end of the list, and it is the
+ * half a caller cannot reconstruct from the jobs alone. A list cut short by a
+ * mid-walk 404 is indistinguishable, by inspection, from a short list that was
+ * read in full — and the two must not be treated alike: 100 indecisive jobs
+ * followed by an unreadable page 2 is *not* proof that the run tested nothing,
+ * because the failing shard may be on the page that would not load. Callers
+ * that decide anything from the ABSENCE of a job outcome must consult it.
+ *
  * @param {object} api - API coordinates
  * @param {number|string} runId - The run
  * @param {(ms: number) => Promise<void>} [wait] - Injectable sleep
- * @returns {Promise<ReadonlyArray<object>>} All jobs
+ * @returns {Promise<{jobs: ReadonlyArray<object>, complete: boolean}>} All jobs read, and whether the list was read to its end
  */
 export async function fetchAllJobs(api, runId, wait) {
   const jobs = [];
@@ -2496,13 +2767,15 @@ export async function fetchAllJobs(api, runId, wait) {
       wait
     );
     // A 404 means the run's job list stopped being readable mid-walk. Return
-    // what was read; falling through to the page-cap throw below would blame a
-    // pagination limit that had nothing to do with it AND discard every job
-    // already collected.
-    if (result === null) return Object.freeze(jobs);
+    // what was read, flagged INCOMPLETE; falling through to the page-cap throw
+    // below would blame a pagination limit that had nothing to do with it AND
+    // discard every job already collected.
+    if (result === null)
+      return Object.freeze({ jobs: Object.freeze(jobs), complete: false });
     const batch = result.body.jobs ?? [];
     jobs.push(...batch);
-    if (batch.length < 100) return Object.freeze(jobs);
+    if (batch.length < 100)
+      return Object.freeze({ jobs: Object.freeze(jobs), complete: true });
   }
   throw new GateApiError(
     `Run ${runId} reports more jobs than \`api_max_pages\` (${api.maxPages}) allows this gate to read. A truncated job list can hide the failing shard, so this is RED rather than a partial read.`
@@ -2759,58 +3032,139 @@ export async function fetchRunArtifacts(api, runId, wait) {
   return null;
 }
 
+/**
+ * Selects the run one suite will be scored on, and records what it walked past.
+ *
+ * Rows 41-42. Candidates arrive newest-first; the walk stops at the first that
+ * produced evidence (`runProducedEvidence`) and never leaves the arm's own
+ * freshness window. Both bounds are load-bearing. Without the first the gate
+ * would keep reading runs it has no reason to; without the second a stale green
+ * could hold the gate open indefinitely, which is the opposite failure and a
+ * worse one.
+ *
+ * When nothing conclusive is found inside the window it falls back to the NEWEST
+ * candidate — the run the gate scored before this walk existed — so `stale_run`,
+ * `indecisive_conclusion` and the rest still fire and the gate still blocks.
+ * That fallback is what makes selection unable to invent a pass: it may only
+ * ever promote an older fresh, conclusive run over a run that tested nothing.
+ *
+ * @param {object} api - API coordinates
+ * @param {ReadonlyArray<object>} candidates - Completed runs, newest first
+ * @param {number} freshnessHours - This arm's freshness window
+ * @param {Date} now - Evaluation instant
+ * @param {(ms: number) => Promise<void>} [wait] - Injectable sleep
+ * @returns {Promise<{run: object, jobs: ReadonlyArray<object>, jobsComplete: boolean, selection: object}>} The scored run, its jobs, whether that job list was read to its end, and the audit
+ */
+async function selectScoredRun(api, candidates, freshnessHours, now, wait) {
+  const jobsById = new Map();
+  const walkedPast = [];
+  let chosen = null;
+  for (const candidate of candidates) {
+    if (!isFresh(candidate, freshnessHours, now)) break;
+    const read = await fetchAllJobs(api, candidate.id, wait);
+    const { jobs, complete } = read;
+    jobsById.set(candidate.id, read);
+    if (runProducedEvidence(candidate, jobs, complete)) {
+      chosen = candidate;
+      break;
+    }
+    walkedPast.push({
+      runId: candidate.id ?? null,
+      conclusion: candidate.conclusion ?? null,
+      createdAt: candidate.created_at ?? null,
+      decisiveJobs: countDecisiveJobs(jobs),
+      totalJobs: jobs.length,
+    });
+  }
+  const run = chosen ?? candidates[0];
+  const read = jobsById.get(run.id) ?? (await fetchAllJobs(api, run.id, wait));
+  const { jobs, complete: jobsComplete } = read;
+  // A run cannot be both scored and skipped. When the walk falls back onto a
+  // candidate it had already stepped over — the single-candidate case — the
+  // honest report is "this was scored because nothing better existed", not a
+  // line contradicting itself.
+  const skipped = walkedPast.filter(entry => entry.runId !== run.id);
+  return {
+    run,
+    jobs,
+    jobsComplete,
+    selection: Object.freeze({
+      runId: run.id ?? null,
+      conclusion: run.conclusion ?? null,
+      createdAt: run.created_at ?? null,
+      // Carried for the SCORED run too, not only the skipped ones, so an
+      // inconclusive verdict can name its cause. See `formatSelection`.
+      decisiveJobs: countDecisiveJobs(jobs),
+      totalJobs: jobs.length,
+      fellBack: chosen === null && walkedPast.length > 0,
+      skipped: Object.freeze(skipped.map(entry => Object.freeze(entry))),
+    }),
+  };
+}
+
 /**
  * Observes every suite.
  *
  * @param {object} api - API coordinates
  * @param {ReadonlyArray<object>} suites - Validated suites
  * @param {string} branch - Branch to read
+ * @param {{freshnessHours: number, now: Date}} context - Evaluation context, bounding the selection walk
  * @param {(ms: number) => Promise<void>} [wait] - Injectable sleep
  * @returns {Promise<ReadonlyArray<object>>} One observation per suite
  */
-export async function observe(api, suites, branch, wait) {
+export async function observe(api, suites, branch, context, wait) {
   return await Promise.all(
     suites.map(async suite => {
       const perEvent = await Promise.all(
         COUNTED_EVENTS.map(event =>
-          fetchNewestRun(api, suite.workflow, branch, event, wait)
+          fetchRunCandidates(api, suite.workflow, branch, event, wait)
         )
       );
       if (perEvent.every(result => result.missing)) {
         return { workflowMissing: true, run: null, jobs: [] };
       }
-      // Newest by created_at, so a fresh dispatch supersedes an older failed
-      // schedule. ISO-8601 UTC compares correctly as strings.
-      const run = perEvent
-        .map(result => result.run)
+      // Newest FIRST by created_at, so a fresh dispatch supersedes an older
+      // failed schedule. ISO-8601 UTC compares correctly as strings.
+      const candidates = perEvent
+        .flatMap(result => result.runs)
         .filter(
           candidate => candidate && typeof candidate.created_at === "string"
         )
-        .reduce(
-          (newest, candidate) =>
-            newest === null || candidate.created_at > newest.created_at
-              ? candidate
-              : newest,
-          null
+        // Equal timestamps compare 0 rather than falling through to -1, which
+        // would make the sort unstable and let two runs created in the same
+        // second swap places between reads of the same history.
+        .sort((left, right) =>
+          left.created_at === right.created_at
+            ? 0
+            : left.created_at < right.created_at
+              ? 1
+              : -1
         );
       // Jobs are read for EVERY match mode, `run` included. A run-scoped suite
       // needs them to prove the run was complete (row 26) — a `success` run
       // that skipped half its jobs is not evidence about the half it skipped.
-      if (!run) {
-        return { workflowMissing: false, run, jobs: [] };
+      if (candidates.length === 0) {
+        return { workflowMissing: false, run: null, jobs: [] };
       }
+      const { run, jobs, jobsComplete, selection } = await selectScoredRun(
+        api,
+        candidates,
+        suite.freshness_hours ?? context.freshnessHours,
+        context.now,
+        wait
+      );
       // Artifacts are read for every suite, not only the ones declaring
       // `min_flows`: a run that recorded ITSELF as filtered disqualifies with no
       // declaration at all (row 36), and a gate that only looked when asked to
-      // would miss exactly the repos that have not adopted the field yet.
-      const [jobs, artifacts] = await Promise.all([
-        fetchAllJobs(api, run.id, wait),
-        fetchRunArtifacts(api, run.id, wait),
-      ]);
+      // would miss exactly the repos that have not adopted the field yet. Read
+      // for the SCORED run, which is the run every other row also judges.
+      const artifacts = await fetchRunArtifacts(api, run.id, wait);
       return {
         workflowMissing: false,
         run,
         jobs,
+        jobsComplete,
+        selection,
         scope: readSuiteScope(artifacts),
       };
     })
@@ -3426,6 +3780,7 @@ export async function runGate(env, wait) {
     settings.api,
     settings.suites,
     settings.branch,
+    { freshnessHours: settings.freshnessHours, now },
     wait
   );
   const findings = settings.suites.map((suite, index) => {
@@ -3496,7 +3851,7 @@ export async function runGate(env, wait) {
 }
 
 /**
- * Runs the REPORTING half: files, refreshes and closes the tracking issues.
+ * The READ half of reporting: everything up to, and not including, the writes.
  *
  * Reads exactly what the gate reads and assesses it with exactly the same
  * classifier, so the issue and the merge gate can never disagree about whether a
@@ -3509,17 +3864,22 @@ export async function runGate(env, wait) {
  * ONE pull request, it does not make the nightly green, and the tracking issue
  * stays open until a green run lands.
  *
+ * Split from the writes so the CLI can surface the verdict BEFORE publishing it
+ * (§10.4). Everything here is a `GET`; the first write in the reporting path is
+ * `applyIssuePlan`.
+ *
  * @param {NodeJS.ProcessEnv} env - The environment
  * @param {(ms: number) => Promise<void>} [wait] - Injectable sleep
- * @returns {Promise<object>} Findings, plan and per-suite results
+ * @returns {Promise<object>} Findings, requiredness, label state, plan, settings
  */
-export async function runReport(env, wait) {
+export async function planReport(env, wait) {
   const settings = resolveSettings(env);
   const now = new Date();
   const observations = await observe(
     settings.api,
     settings.suites,
     settings.branch,
+    { freshnessHours: settings.freshnessHours, now },
     wait
   );
   const findings = settings.suites.map((suite, index) => {
@@ -3568,36 +3928,99 @@ export async function runReport(env, wait) {
     bypassLabelState,
     pinIssues: settings.pinIssues,
   };
+  return { findings, requiredness, bypassLabelState, context, settings };
+}
+
+/**
+ * The PUBLISH half: read the open tracking issues, plan, and write.
+ *
+ * The read of the existing issues lives on THIS side of the split, not with the
+ * verdict, and that placement is the point. Listing open issues is the Issues
+ * API — the same API that can be switched off, throttled or forbidden — so a
+ * verdict that depended on it would still die with its publisher, which is the
+ * whole defect (§10.4). Everything the verdict needs comes from Actions run
+ * history instead.
+ *
+ * @param {object} planned - Output of `planReport`
+ * @param {(ms: number) => Promise<void>} [wait] - Injectable sleep
+ * @returns {Promise<{plan: ReadonlyArray<object>, results: ReadonlyArray<object>}>} Plan and outcomes
+ */
+export async function publishReport(planned, wait) {
+  const { settings, findings, context } = planned;
   const plan = planIssueActions(
     findings,
     await fetchTrackingIssues(settings.api, settings.issueLabel, wait),
     context
   );
-  return {
-    findings,
-    requiredness,
-    bypassLabelState,
-    plan,
-    results: await applyIssuePlan(settings.api, plan, wait),
-    settings,
-  };
+  return { plan, results: await applyIssuePlan(settings.api, plan, wait) };
+}
+
+/**
+ * Plan, then publish. The whole report in one call.
+ *
+ * Kept as the single-call entry point it has always been — every existing
+ * caller and every §10 test reads the same five fields back. `reportIssues`
+ * deliberately does NOT use it: the CLI has to get the verdict onto the job
+ * summary between the two halves, and has to survive the second half failing,
+ * neither of which a combined call can express (§10.4).
+ *
+ * @param {Record<string, string|undefined>} env - Process environment
+ * @param {(ms: number) => Promise<void>} [wait] - Injectable sleep
+ * @returns {Promise<object>} `{findings, requiredness, bypassLabelState, plan, results, settings}`
+ */
+export async function runReport(env, wait) {
+  const planned = await planReport(env, wait);
+  const { context: _context, ...verdict } = planned;
+  return { ...verdict, ...(await publishReport(planned, wait)) };
+}
+
+/**
+ * Whether a suite is red in the sense §10.4's exit code needs.
+ *
+ * `fail` AND complete evidence — the same pair `planIssueActions` requires
+ * before it will file anything, asked here of the FINDING so the exit code needs
+ * nothing from the Issues API. A `fail` that row 30 routed to
+ * `evidence_incomplete` decided nothing there and decides nothing here either,
+ * or the job would go red about a run whose own report says it proved nothing.
+ *
+ * @param {object} finding - A finding
+ * @returns {boolean} True when the suite genuinely failed
+ */
+function isGenuinelyRed(finding) {
+  return finding.state === SUITE_STATES.fail && isCompleteEvidence(finding);
 }
 
 /**
  * The reporting entry point, as the scheduled workflow invokes it.
  *
- * Its exit code answers "did REPORTING work", never "is the suite green". A red
- * nightly reported correctly is a SUCCESSFUL report — conflating the two would
- * hand operators a second red check that means something different from the
- * first one.
+ * Three outcomes, three deliberately different exit codes (§10.4):
+ *
+ *   1. **No verdict could be resolved** — configuration, a schema refusal, an
+ *      unreadable run history → EXIT 1. Nothing was reported, and "we could not
+ *      check" must never render as "it is fine".
+ *   2. **Verdict resolved, publishing failed** → EXIT 0 + `::warning::`. The
+ *      tracking issue is a convenience; the verdict is the product, and it is
+ *      already on the job summary by the time publishing is attempted. A report
+ *      channel must not die because its optional publishing destination is
+ *      unavailable — measured as HTTP 410 on `POST /repos/{o}/{r}/issues` for a
+ *      repository that switched Issues off.
+ *   3. **The SUITE itself is red** → EXIT 1 + `::error::` per red suite.
+ *
+ * Case 3 is why case 2 is safe to absorb. Without it this entry point would have
+ * no failing path left at all once publishing stopped reddening it, and a job
+ * that cannot go red is a job whose green means nothing.
  *
  * @param {boolean} asJson - Emit the machine record instead of prose
  * @returns {Promise<void>} Resolves once the report is written
  */
-async function reportIssues(asJson) {
-  let outcome;
+export async function reportIssues(asJson) {
+  // ---------------------------------------------------------------------
+  // 1. Resolve the verdict. Read-only, and the one path that still exits 1
+  //    for a reporting failure — because it produced no report at all.
+  // ---------------------------------------------------------------------
+  let planned;
   try {
-    outcome = await runReport(process.env);
+    planned = await planReport(process.env);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     process.stderr.write(
@@ -3607,16 +4030,51 @@ async function reportIssues(asJson) {
     process.exitCode = 1;
     return;
   }
-  const { settings, ...machine } = outcome;
+  const { settings, context: _context, ...verdict } = planned;
+
+  // ---------------------------------------------------------------------
+  // 2. Surface the verdict, BEFORE anything can go wrong publishing it.
+  //    Making publishing non-fatal on its own would trade a false red for a
+  //    silent gap — the same defect pointing the other way. The step summary
+  //    is a channel that exists whether or not GitHub Issues do.
+  // ---------------------------------------------------------------------
+  if (!asJson) {
+    const verdictReport = formatVerdictReport(verdict.findings, {
+      branch: settings.branch,
+    });
+    process.stdout.write(verdictReport);
+    await appendSummary(verdictReport);
+  }
+
+  // ---------------------------------------------------------------------
+  // 3. Publish — best effort, and nothing it does reaches the exit code.
+  // ---------------------------------------------------------------------
+  // `applyIssuePlan` already records a per-suite write failure rather than
+  // throwing (row 31). This catch is for everything around it — most concretely
+  // the LIST of open issues, which is the same Issues API the writes use and can
+  // therefore be off, throttled or forbidden in exactly the same way.
+  let plan = [];
+  let results = [];
+  let publishFailure = null;
+  try {
+    ({ plan, results } = await publishReport(planned));
+  } catch (error) {
+    publishFailure = error instanceof Error ? error.message : String(error);
+    process.stderr.write(
+      `::warning title=Nightly E2E tracking issues not published::${publishFailure.split("\n")[0]} — the verdict for this run is in the job summary, and this job's result reflects the SUITE, not the publish.\n`
+    );
+  }
+  const machine = { ...verdict, plan, results, publishFailure };
   if (asJson) {
     process.stdout.write(`${JSON.stringify(machine, null, 2)}\n`);
   } else {
-    const report = formatIssueReport(machine.results, {
+    const report = formatIssueReport(results, {
       branch: settings.branch,
-      requiredness: machine.requiredness,
+      requiredness: verdict.requiredness,
       gateContext: settings.gateContext,
       bypassLabel: settings.bypassLabel,
-      bypassLabelState: machine.bypassLabelState,
+      bypassLabelState: verdict.bypassLabelState,
+      publishFailure,
     });
     process.stdout.write(report);
     await appendSummary(report);
@@ -3624,38 +4082,56 @@ async function reportIssues(asJson) {
   // An `unknown` requiredness is annotated on the run, because it means every
   // issue this report touched is deliberately silent about merge consequences —
   // and the reason (a scope, a rename, an outage) is fixable.
-  if (machine.requiredness?.state === REQUIREDNESS.unknown) {
+  if (verdict.requiredness?.state === REQUIREDNESS.unknown) {
     process.stderr.write(
-      `::warning title=Nightly E2E requiredness unknown::Could not read \`${settings.branch}\`'s branch rules, so the tracking issues claim neither that merges are blocked nor that they are not. ${machine.requiredness.detail ?? ""}\n`
+      `::warning title=Nightly E2E requiredness unknown::Could not read \`${settings.branch}\`'s branch rules, so the tracking issues claim neither that merges are blocked nor that they are not. ${verdict.requiredness.detail ?? ""}\n`
     );
   }
   // §10.9. An annotation rather than a failure, and that is not timidity: this
-  // job's status answers "did REPORTING work" (§10.4), and reddening it for a
+  // job's exit code answers "is the suite green" (§10.4), and reddening it for a
   // repository-configuration defect would teach operators to ignore the one job
   // that tells them a suite is down. It is loud where loudness is free.
-  if (machine.bypassLabelState?.state === BYPASS_LABEL_STATE.absent) {
+  if (verdict.bypassLabelState?.state === BYPASS_LABEL_STATE.absent) {
     process.stderr.write(
       `::error title=Nightly E2E bypass label missing::The gate is required on \`${settings.branch}\` but the \`${settings.bypassLabel}\` label does not exist in this repository, so the audited waiver cannot be applied and an unaudited admin merge is the only exit. Create it once: gh label create ${settings.bypassLabel}\n`
     );
-  } else if (machine.bypassLabelState?.state === BYPASS_LABEL_STATE.unknown) {
+  } else if (verdict.bypassLabelState?.state === BYPASS_LABEL_STATE.unknown) {
     process.stderr.write(
-      `::warning title=Nightly E2E bypass label unreadable::Could not read whether \`${settings.bypassLabel}\` exists in this repository. ${machine.bypassLabelState.detail ?? ""}\n`
+      `::warning title=Nightly E2E bypass label unreadable::Could not read whether \`${settings.bypassLabel}\` exists in this repository. ${verdict.bypassLabelState.detail ?? ""}\n`
     );
   }
-  for (const result of machine.results) {
+  for (const result of results) {
     for (const warning of result.warnings ?? []) {
       process.stderr.write(
         `::warning title=Nightly E2E tracking issue not pinned::${result.label} — ${warning}\n`
       );
     }
   }
-  const failed = machine.results.filter(result => !result.ok);
-  for (const result of failed) {
+  // A tracking issue that did not land is a `::warning::`, NOT an `::error::`
+  // and not a failure. It names the suite and the cause, which is what an
+  // operator needs to fix the publisher; the verdict it could not publish is
+  // three paragraphs up the same summary.
+  for (const result of results.filter(entry => !entry.ok)) {
+    process.stderr.write(
+      `::warning title=Nightly E2E tracking issue not updated::${result.label} — ${result.error} (the verdict for this run is in the job summary; this job's result reflects the SUITE, not the publish)\n`
+    );
+  }
+
+  // ---------------------------------------------------------------------
+  // 4. Exit on the SUITE, never on the publish.
+  // ---------------------------------------------------------------------
+  // Read off the FINDINGS, never off the plan or the results: the plan needs the
+  // Issues API to build, and a verdict that could not be reached because the
+  // publisher was unreachable is the defect this whole section deletes.
+  // `::error::` annotates but does not fail a step, so the explicit non-zero
+  // exit code is what actually carries the red.
+  const red = verdict.findings.filter(isGenuinelyRed);
+  for (const finding of red) {
     process.stderr.write(
-      `::error title=Nightly E2E tracking issue not updated::${result.label} — ${result.error}\n`
+      `::error title=Nightly E2E is not green::${finding.label} — ${finding.state.toUpperCase()}${finding.conclusion ? ` (${finding.conclusion})` : ""} [${finding.reason}]${finding.url ? ` — ${finding.url}` : ""}\n`
     );
   }
-  if (failed.length > 0) process.exitCode = 1;
+  if (red.length > 0) process.exitCode = 1;
 }
 
 /**
@@ -3740,13 +4216,30 @@ async function main(argv) {
 /**
  * Appends a report to the job summary when one exists.
  *
+ * NEVER throws. The same report has already gone to stdout, and on the gate path
+ * the verdict is additionally in the step outputs and the exit code, so an
+ * unwritable `$GITHUB_STEP_SUMMARY` is a failure of one RENDERING SURFACE and
+ * nothing more. Left to propagate it would reach top-level `main`, where on the
+ * reporting path it would fail the job AND skip publishing — a summary file the
+ * runner could not open taking down both channels at once, which is §10.4's
+ * defect wearing different clothes. It is absorbed into a `::warning::` rather
+ * than swallowed, because a summary that silently never appears is how an
+ * operator learns to stop looking at it.
+ *
  * @param {string} report - Markdown
- * @returns {Promise<void>} Resolves when written
+ * @returns {Promise<void>} Resolves when written, or when it could not be
  */
 async function appendSummary(report) {
   if (!process.env.GITHUB_STEP_SUMMARY) return;
-  const { appendFileSync } = await import("node:fs");
-  appendFileSync(process.env.GITHUB_STEP_SUMMARY, report);
+  try {
+    const { appendFileSync } = await import("node:fs");
+    appendFileSync(process.env.GITHUB_STEP_SUMMARY, report);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(
+      `::warning title=Nightly E2E job summary unwritable::Could not append to \`$GITHUB_STEP_SUMMARY\` (${message.split("\n")[0]}). The same report is in this job's log.\n`
+    );
+  }
 }
 
 /**