@futurelastic/colab-handbook 1.12.0-rc.35 → 1.12.0-rc.37

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.35"
30
+ "version": "1.12.0-rc.37"
31
31
  }
@@ -91,6 +91,23 @@
91
91
  # run still concludes on the `release` job. EDIT: on this route, a cron more frequent than daily
92
92
  # tags a head that release.final-spacing held back sooner.
93
93
  #
94
+ # DRY RUN ON A FIX BRANCH (#474). This workflow never runs on a branch by itself, so a fix to it
95
+ # (a moved runner label, a HANDBOOK_REF naming a missing branch) had no run to prove it, and the
96
+ # cure rule (CONVENTIONS.md §4) could only refuse it — a human ci-grant was the one door. Dispatch
97
+ # it on the fix branch instead:
98
+ #
99
+ # gh workflow run release-auto.yml --ref <fix-branch> -f dry_run=true
100
+ #
101
+ # (`colab ship` dispatches it for you when a red in this workflow is what stands between the branch
102
+ # and trunk). A dispatch on any ref other than main is ALWAYS dry, input or not. A dry run checks out
103
+ # the branch, runs every step with `--dry` — the same decisions, nothing promoted, tagged, released,
104
+ # pushed or dispatched — and skips only the steps whose names end in `[publish]`. The step
105
+ # "Dry run — nothing is tagged, released or published" runs only then; it is how the cure rule
106
+ # recognises the run. Keep both names as they are: the cure rule matches steps BY NAME, and accepts
107
+ # a dry run only if every step that ran in trunk's red run passed in it and every step it skipped
108
+ # ends in `[publish]`. So a red INSIDE a `[publish]` step, or in the npm or deploy jobs (which never
109
+ # run without a tag), cannot be cured by a dry run — that stays a human ci-grant.
110
+ #
94
111
  # IT READS TAGS AND CREATES TAGS. IT NEVER WRITES A COMMIT. No step here commits; the refs
95
112
  # pushed are the tags `colab release cut` / `colab release finalize` create (annotated, their
96
113
  # checks recorded in the tag message) and — only on a repo granting unattended promotion — the
@@ -102,6 +119,13 @@
102
119
  # failed) is the ordinary output of most runs; it is printed to the run summary as a
103
120
  # warning and the job stays green, so a refusal never paints main red for `colab ship`.
104
121
  # Only a run that produced no verdict at all (a crash, gh unusable, bad flags) fails.
122
+ # A STANDING refusal is still not a failure, but it is not a warning either (#467): one no
123
+ # later run clears by itself — no first final tag, a malformed colab:switch marker, a
124
+ # manifest that disagrees — is an `::error title=Release stalled::` annotation plus a
125
+ # summary banner, and `colab release-status` flags the repo. Still exit 0: a red run here
126
+ # would make main's head not-green and refuse the very ship that clears the stall.
127
+ # Every finalize run that makes no final says why, and lists each open candidate's reason
128
+ # and when its own test period ends (#468).
105
129
  #
106
130
  # THE CLI IGNORES THIS WORKFLOW'S OWN RUNS when it reads CI at a commit (GITHUB_WORKFLOW,
107
131
  # #425) — otherwise its own in-progress run would read as "CI not finished" forever. So
@@ -147,12 +171,21 @@ on:
147
171
  # hour is when scheduled runs queue longest.
148
172
  - cron: "17 3 * * *"
149
173
  workflow_dispatch:
174
+ # #474: a DRY RUN for a fix branch — see "DRY RUN ON A FIX BRANCH" in the header. A dispatch on
175
+ # any ref other than main is dry whether or not this is set; on main it is opt-in.
176
+ inputs:
177
+ dry_run:
178
+ description: "Dry run: decide everything, write nothing (no promotion, tag, Release or publish)"
179
+ type: boolean
180
+ default: false
150
181
 
151
182
  # One release run at a time; a second one waits rather than racing the first for the same
152
183
  # candidate number. Never cancelled mid-run: a half-finished run may have pushed a tag
153
184
  # without publishing it.
154
185
  concurrency:
155
- group: release-auto
186
+ # A dry run (#474) gets a group of its own: GitHub cancels an older PENDING run in the same group,
187
+ # so a shared one could let a branch's dry run displace a real release run waiting on main.
188
+ group: release-auto${{ github.event_name == 'workflow_dispatch' && (inputs.dry_run || github.ref_name != 'main') && format('-dry-{0}', github.ref_name) || '' }}
156
189
  cancel-in-progress: false
157
190
 
158
191
  permissions: {}
@@ -223,16 +256,34 @@ jobs:
223
256
  health-url: ${{ steps.cut.outputs.health-url }}
224
257
  env:
225
258
  GH_TOKEN: ${{ github.token }}
259
+ # #474: 'true' on a dry run — a dispatch on any ref other than main, or one with dry_run set.
260
+ # Never on workflow_run or schedule. Every write below is off when it is.
261
+ # EDIT: if your trunk is not `main`, name it here too (the same branch as `ref:` below).
262
+ DRY_RUN: ${{ github.event_name == 'workflow_dispatch' && (inputs.dry_run || github.ref_name != 'main') }}
226
263
  steps:
227
264
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
228
265
  with:
229
- ref: main
266
+ # A dry run checks out the ref it was dispatched on — the fix being proven; every other run, main.
267
+ ref: ${{ env.DRY_RUN == 'true' && github.sha || 'main' }}
230
268
  # Full history plus tags: versions, bumps and "previous final" are all read from
231
269
  # git, and the on-trunk check refuses a shallow checkout outright.
232
270
  fetch-depth: 0
233
271
  # Left on deliberately: `colab release cut` / `finalize` push their tag over the
234
- # checkout's origin. The token is this job's, scoped by `permissions:` above.
235
- persist-credentials: true
272
+ # checkout's origin. The token is this job's, scoped by `permissions:` above. Off on a dry
273
+ # run (#474): nothing is pushed, so nothing should be able to push.
274
+ persist-credentials: ${{ env.DRY_RUN != 'true' }}
275
+
276
+ # #474: the marker ci-cure reads to recognise a dry run — its name must stay byte-identical to
277
+ # DRY_RUN_STEP in the handbook's tools/lib/ci-cure.js. Skipped on every ordinary run.
278
+ - name: Dry run — nothing is tagged, released or published
279
+ if: env.DRY_RUN == 'true'
280
+ run: |
281
+ {
282
+ echo "#### Dry run (#474)"
283
+ echo
284
+ echo "Dispatched on \`$GITHUB_REF_NAME\` @ \`$GITHUB_SHA\`. Every decision below runs with \`--dry\`; steps marked \`[publish]\` are skipped. Nothing is promoted, tagged, released or published."
285
+ echo
286
+ } >> "$GITHUB_STEP_SUMMARY"
236
287
 
237
288
  # A red CI run on main is not a candidate. Gated here rather than by a job-level `if:` so
238
289
  # this run concludes success, never `skipped` (#435; the comment on the job above).
@@ -278,7 +329,8 @@ jobs:
278
329
  eval "$RETRY_TRANSIENT"
279
330
  OUT="$RUNNER_TEMP/promote.json"
280
331
  rc=0
281
- retry_transient node "$COLAB" promote --auto --json > "$OUT" || rc=$?
332
+ DRY=(); [ "${DRY_RUN:-false}" = "true" ] && DRY=(--dry)
333
+ retry_transient node "$COLAB" promote --auto ${DRY[@]+"${DRY[@]}"} --json > "$OUT" || rc=$?
282
334
  if ! jq -e 'has("promoted")' "$OUT" > /dev/null 2>&1; then
283
335
  echo "::warning::colab promote --auto gave no verdict (exit $rc; a HANDBOOK_REF older than #440?) — nothing was promoted"
284
336
  exit 0
@@ -289,7 +341,10 @@ jobs:
289
341
  jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
290
342
  echo
291
343
  } >> "$GITHUB_STEP_SUMMARY"
292
- if [ "$(jq -r '.promoted' "$OUT")" = "true" ]; then
344
+ if [ "${DRY_RUN:-false}" = "true" ]; then
345
+ # #474: a dry run promotes nothing and dispatches nothing, whatever the verdict says.
346
+ echo "Dry run — promote: $(jq -r 'if .promoted then "would promote" elif .noop then "no-op: \(.reason)" else "would refuse: \(.reason)" end' "$OUT")" | tee -a "$GITHUB_STEP_SUMMARY"
347
+ elif [ "$(jq -r '.promoted' "$OUT")" = "true" ]; then
293
348
  echo "promoted=true" >> "$GITHUB_OUTPUT"
294
349
  echo "Promoted to main @ $(jq -r '.sha' "$OUT")" | tee -a "$GITHUB_STEP_SUMMARY"
295
350
  if retry_transient gh workflow run "$CI_WORKFLOW" --ref main; then
@@ -315,7 +370,8 @@ jobs:
315
370
  eval "$RETRY_TRANSIENT"
316
371
  OUT="$RUNNER_TEMP/cut.json"
317
372
  rc=0
318
- retry_transient node "$COLAB" release cut --auto --json > "$OUT" || rc=$?
373
+ DRY=(); [ "${DRY_RUN:-false}" = "true" ] && DRY=(--dry)
374
+ retry_transient node "$COLAB" release cut --auto ${DRY[@]+"${DRY[@]}"} --json > "$OUT" || rc=$?
319
375
  # A verdict is JSON carrying `ok`; anything else is a run that never decided.
320
376
  if ! jq -e 'has("ok")' "$OUT" > /dev/null 2>&1; then
321
377
  echo "::error::colab release cut produced no verdict (exit $rc)"
@@ -329,7 +385,10 @@ jobs:
329
385
  jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
330
386
  echo
331
387
  } >> "$GITHUB_STEP_SUMMARY"
332
- if [ "$(jq -r '.created' "$OUT")" = "true" ]; then
388
+ if [ "${DRY_RUN:-false}" = "true" ]; then
389
+ # #474: a dry run never hands a tag to the publishing steps, whatever the verdict says.
390
+ echo "Dry run — would cut: $(jq -r '.tag // "nothing"' "$OUT") (created: $(jq -r '.created' "$OUT"))" | tee -a "$GITHUB_STEP_SUMMARY"
391
+ elif [ "$(jq -r '.created' "$OUT")" = "true" ]; then
333
392
  TAG="$(jq -r '.tag' "$OUT")"
334
393
  echo "tag=$TAG" >> "$GITHUB_OUTPUT"
335
394
  echo "Cut $TAG" | tee -a "$GITHUB_STEP_SUMMARY"
@@ -344,7 +403,21 @@ jobs:
344
403
  elif [ "$(jq -r '.ok' "$OUT")" = "true" ]; then
345
404
  echo "Verdict ok but nothing created." | tee -a "$GITHUB_STEP_SUMMARY"
346
405
  else
347
- echo "::warning::colab release cut refused: $(jq -r '[.checks[]? | select(.ok | not) | .condition] | join(", ")' "$OUT")"
406
+ # #467: a refusal no later run clears by itself (no first final, a malformed marker, a
407
+ # wrong manifest) is a STALL — an error annotation and a summary banner, still exit 0: a red
408
+ # release run at main's head would make trunk not-green and refuse the very ship that fixes it.
409
+ STANDING="$(jq -r '(.standing // []) | join(", ")' "$OUT")"
410
+ if [ -n "$STANDING" ]; then
411
+ echo "::error title=Release stalled::colab release cut refused on a condition that does not clear by itself: $(jq -r '. as $v | [$v.checks[]? | select(.ok | not) | select(.condition as $c | any(($v.standing // [])[]; . == $c)) | "\(.condition) — \(.detail)"] | join("; ")' "$OUT")"
412
+ {
413
+ echo "#### ⚠ Release stalled"
414
+ echo
415
+ echo "\`colab release cut --auto\` refused on **$STANDING** — the next run refuses the same way until a human acts (the ✗ rows above say what). The run stays green on purpose, so it never blocks the ship that fixes it."
416
+ echo
417
+ } >> "$GITHUB_STEP_SUMMARY"
418
+ else
419
+ echo "::warning::colab release cut refused: $(jq -r '[.checks[]? | select(.ok | not) | .condition] | join(", ")' "$OUT")"
420
+ fi
348
421
  fi
349
422
 
350
423
  - name: Finalize the newest clean candidate (colab release finalize --auto)
@@ -355,7 +428,8 @@ jobs:
355
428
  eval "$RETRY_TRANSIENT"
356
429
  OUT="$RUNNER_TEMP/finalize.json"
357
430
  rc=0
358
- retry_transient node "$COLAB" release finalize --auto --json > "$OUT" || rc=$?
431
+ DRY=(); [ "${DRY_RUN:-false}" = "true" ] && DRY=(--dry)
432
+ retry_transient node "$COLAB" release finalize --auto ${DRY[@]+"${DRY[@]}"} --json > "$OUT" || rc=$?
359
433
  if ! jq -e 'has("state")' "$OUT" > /dev/null 2>&1; then
360
434
  echo "::error::colab release finalize produced no verdict (exit $rc)"
361
435
  echo "colab release finalize produced no verdict (exit $rc) — the reason is in this step's log." >> "$GITHUB_STEP_SUMMARY"
@@ -363,29 +437,41 @@ jobs:
363
437
  exit 1
364
438
  fi
365
439
  STATE="$(jq -r '.state' "$OUT")"
440
+ # #468: why no final, and every other open candidate with its own reason — the checklist
441
+ # above it is only the picked candidate's, which alone reads as "only the newest counts".
442
+ WHY="$(jq -r '.why.line // empty' "$OUT")"
366
443
  {
367
444
  echo "### colab release finalize --auto — $STATE"
368
445
  echo
369
446
  jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
370
447
  echo
448
+ if [ -n "$WHY" ]; then echo "**Why no final:** $WHY"; echo; fi
449
+ if [ "$(jq -r '(.skipped // []) | length' "$OUT")" != "0" ]; then
450
+ echo "Other open candidates:"
451
+ jq -r '(.skipped // [])[:10][] | "- \(.tag): \(.state)\(if .detail then " — \(.detail)" else "" end)"' "$OUT"
452
+ jq -r '(.skipped // []) | if length > 10 then "- … \(length - 10) more" else empty end' "$OUT"
453
+ echo
454
+ fi
371
455
  } >> "$GITHUB_STEP_SUMMARY"
372
- if [ "$(jq -r '.tagged' "$OUT")" = "true" ]; then
456
+ if [ "${DRY_RUN:-false}" = "true" ]; then
457
+ echo "Dry run — finalize: $STATE (would tag: $(jq -r '.finalTag // "nothing"' "$OUT"))" | tee -a "$GITHUB_STEP_SUMMARY"
458
+ elif [ "$(jq -r '.tagged' "$OUT")" = "true" ]; then
373
459
  TAG="$(jq -r '.finalTag' "$OUT")"
374
460
  echo "tag=$TAG" >> "$GITHUB_OUTPUT"
375
461
  echo "Finalized $TAG" | tee -a "$GITHUB_STEP_SUMMARY"
376
462
  else
377
463
  case "$STATE" in
378
- refused|needs-new-candidate|held) echo "::warning::colab release finalize: $STATE" ;;
379
- *) echo "Finalize: $STATE" ;;
464
+ refused|needs-new-candidate|held) echo "::warning::colab release finalize: $STATE${WHY:+ — $WHY}" ;;
465
+ *) echo "Finalize: $STATE${WHY:+ — $WHY}" ;;
380
466
  esac
381
467
  fi
382
468
 
383
469
  # Whether the npm job publishes what this run tagged — `colab release npm` reads the
384
470
  # release: block (one reading, the same as cut/finalize). A CLI older than #433 gives no
385
471
  # verdict; that is a warning and no npm publish, never a failed release.
386
- - name: Read the npm target (colab release npm)
472
+ - name: Read the npm target (colab release npm) [publish]
387
473
  id: npm-target
388
- if: steps.cut.outputs.tag != '' || steps.finalize.outputs.tag != ''
474
+ if: env.DRY_RUN != 'true' && (steps.cut.outputs.tag != '' || steps.finalize.outputs.tag != '')
389
475
  env:
390
476
  TAGS: ${{ steps.cut.outputs.tag }} ${{ steps.finalize.outputs.tag }}
391
477
  run: |
@@ -414,8 +500,8 @@ jobs:
414
500
 
415
501
  # Publishes every tag THIS run created. In this run, never via a tag-push workflow:
416
502
  # see "PUBLISHING HAPPENS IN THIS RUN" in the header.
417
- - name: Publish GitHub Release (same run)
418
- if: steps.cut.outputs.tag != '' || steps.finalize.outputs.tag != ''
503
+ - name: Publish GitHub Release (same run) [publish]
504
+ if: env.DRY_RUN != 'true' && (steps.cut.outputs.tag != '' || steps.finalize.outputs.tag != '')
419
505
  env:
420
506
  TAGS: ${{ steps.cut.outputs.tag }} ${{ steps.finalize.outputs.tag }}
421
507
  run: |
package/tools/colab CHANGED
@@ -1324,7 +1324,7 @@ function measureCandidateConditions(repoAbs, { sha, lastFinal, at, readRuns, iss
1324
1324
  const why = ghUnusableWhy(repoAbs);
1325
1325
  ci = { ok: false, detail: `gh not usable (${why}) — cannot confirm CI at ${at}` };
1326
1326
  suite = { ok: false, detail: `gh not usable (${why}) — cannot confirm the suite ran at ${at}` };
1327
- switches = { ok: false, detail: `gh not usable (${why}) — the colab:switch markers cannot be read` };
1327
+ switches = { ok: false, unread: true, detail: `gh not usable (${why}) — the colab:switch markers cannot be read` };
1328
1328
  } else {
1329
1329
  const rows = readRuns();
1330
1330
  const run = git.summarizeRunsForCommit(rows, sha);
@@ -1340,7 +1340,7 @@ function measureCandidateConditions(repoAbs, { sha, lastFinal, at, readRuns, iss
1340
1340
  const declared = migrationPaths.unionPaths(projectDoc(repoAbs), projectDocAt(repoAbs, sha));
1341
1341
  const changes = releaseCutChanges(repoAbs, lastFinal, sha, declared);
1342
1342
  const schema = changes === null
1343
- ? { ok: false, detail: 'git diff failed — schema changes cannot be read' }
1343
+ ? { ok: false, unread: true, detail: 'git diff failed — schema changes cannot be read' }
1344
1344
  : releaseCut.schemaVerdict(changes, lastFinal || 'the first commit', declared);
1345
1345
  // #441: every migration file since the last final, destructive or not — an operator-granted
1346
1346
  // automatic final refuses an ungranted one (release-finalize.js migrationGrantVerdict).
@@ -1474,7 +1474,7 @@ function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, au
1474
1474
  const trust = trustAt(repoAbs, `${remote}/main`);
1475
1475
  const finalGrant = isGhUsable(repoAbs)
1476
1476
  ? releasePolicy.finalGrantVerdict(git.ghIssueView(repoAbs, grantDecl.issue, ['state', 'labels', 'comments']), { issue: grantDecl.issue, trust })
1477
- : { ok: false, ruledBy: null, detail: `release.final-grant #${grantDecl.issue} could not be read: gh not usable (${ghUnusableWhy(repoAbs)})` };
1477
+ : { ok: false, unread: true, ruledBy: null, detail: `release.final-grant #${grantDecl.issue} could not be read: gh not usable (${ghUnusableWhy(repoAbs)})` };
1478
1478
  const holds = releaseCut.holdsVerdict(issues);
1479
1479
  let tracking = null;
1480
1480
  let grant = null;
@@ -1647,7 +1647,7 @@ function cmdReleaseCut(argv) {
1647
1647
  if (opts.json) {
1648
1648
  print(JSON.stringify({
1649
1649
  repo: shortRepo(repoAbs), sha, ...(offTrunk ? { trunk } : {}), lastFinal, suggestion, dry: !!opts.dry, auto: !!opts.auto,
1650
- ok: verdict.ok, noop: !!verdict.noop, tag: verdict.tag, created, published, channel, version: verdict.version, bump: verdict.bump,
1650
+ ok: verdict.ok, noop: !!verdict.noop, standing: verdict.standing || [], tag: verdict.tag, created, published, channel, version: verdict.version, bump: verdict.bump,
1651
1651
  overridden: verdict.overridden, signals: verdict.signals ? verdict.signals.lines : null, checks: verdict.checks,
1652
1652
  // #446: present on every route, so the workflow reads one shape — final only on deploy-tag-fast.
1653
1653
  final: !!verdict.final,
@@ -1673,6 +1673,8 @@ function cmdReleaseCut(argv) {
1673
1673
  }
1674
1674
  if (!verdict.ok) {
1675
1675
  print(`✗ refused — ${verdict.refusals.length} condition(s) failed; nothing cut.`);
1676
+ // #467: a refusal no further run clears by itself is a stall — say so, so nobody waits on it.
1677
+ if (verdict.standing && verdict.standing.length) print(` release stalled — ${verdict.standing.join(', ')} will not clear by itself; a human act is owed (the next run refuses the same way).`);
1676
1678
  if (handoff) print(`\nA migration rides this release. The one command, for a human to run:\n ${handoff}`);
1677
1679
  return 1;
1678
1680
  }
@@ -1968,7 +1970,7 @@ function cmdReleaseFinalize(argv) {
1968
1970
  manifests, ancestry, tags: tagNames, finalGrant, migrations,
1969
1971
  human: { bar: humanBar, answeredBy: opts.answeredBy || null },
1970
1972
  });
1971
- return { candidate: cand, verdict, period, tracking };
1973
+ return { candidate: cand, verdict, period, tracking, trunk };
1972
1974
  };
1973
1975
 
1974
1976
  let cand = null; let verdict; let period = null; let tracking = version0 ? trackings.get(version0) : null;
@@ -1976,14 +1978,23 @@ function cmdReleaseFinalize(argv) {
1976
1978
  if (walk) {
1977
1979
  const MAX_JUDGED = 10;
1978
1980
  const evals = [];
1981
+ // #468: every red trunk run a judged candidate's window held. One red run puts every candidate cut
1982
+ // in the test period before it into needs-new-candidate; on a repo cutting several a day, judging
1983
+ // each one in full spent MAX_JUDGED on them and the walk stopped before the older clean one.
1984
+ const knownRed = [];
1979
1985
  for (const c of releaseFinalize.openCandidates(tags, remote)) {
1980
- if (c.refused) { skipped.push({ tag: c.tag, state: 'refused', detail: c.refused }); continue; }
1986
+ if (c.refused) { skipped.push({ tag: c.tag, state: 'refused', detail: c.refused, endsAt: null }); continue; }
1981
1987
  const tr = trackings.has(c.version) ? trackings.get(c.version) : trackingFor(c.version, { isCandidate: true });
1982
1988
  const p = releaseFinalize.periodVerdict({ cutAt: c.cutAt, trackingCreatedAt: tr && tr.createdAt, testPeriodDays: policy.effective.testPeriodDays, now });
1983
1989
  // Cheap skip: a younger candidate whose own period has not elapsed cannot finalize — only the newest is judged regardless, so the report has a state.
1984
- if (!p.elapsed && evals.length) { skipped.push({ tag: c.tag, state: 'testing', detail: p.detail }); continue; }
1990
+ if (!p.elapsed && evals.length) { skipped.push({ tag: c.tag, state: 'testing', detail: `test-period: ${p.detail}`, endsAt: p.endsAt }); continue; }
1991
+ // #468: cheap skip, the second kind — a red run already seen inside this candidate's own window.
1992
+ // Not counted toward MAX_JUDGED. May be wrong only in the safe direction (windowHasRed).
1993
+ const seenRed = evals.length ? releaseFinalize.windowHasRed(p, knownRed) : null;
1994
+ if (seenRed) { skipped.push({ tag: c.tag, state: 'needs-new-candidate', detail: `trunk-green: trunk went red at ${seenRed}, inside its own test period (seen judging a newer candidate)`, endsAt: p.endsAt }); continue; }
1985
1995
  const e = judge(c, { kind: 'candidate', candidate: c, superseded: [], detail: `${c.tag} at ${shortSha(c.sha)}, cut ${c.cutAt} (--auto: judged on its own clock)` });
1986
1996
  evals.push(e);
1997
+ if (e.trunk && Array.isArray(e.trunk.redAt)) knownRed.push(...e.trunk.redAt);
1987
1998
  if (e.verdict.state === 'finalized' || e.verdict.state === 'held' || evals.length >= MAX_JUDGED) break;
1988
1999
  }
1989
2000
  const pick = releaseFinalize.pickNewestClean(evals);
@@ -2080,13 +2091,16 @@ function cmdReleaseFinalize(argv) {
2080
2091
  const trackingOut = tracking && !tracking.error
2081
2092
  ? { number: tracking.number || null, url: tracking.url || null, created: trackingCreated && (!cand || cand.version === version0), held: !!tracking.held, supersededHeld }
2082
2093
  : null;
2094
+ // #468: why this run made no final, and which candidate finals first — the line the release
2095
+ // workflow prints, so "no final" never has to be reconstructed from a checklist.
2096
+ const why = releaseFinalize.whyNoFinal({ state: verdict.state, candidate: cand, checks: verdict.checks, period, skipped: walk ? skipped : [], now });
2083
2097
  if (opts.json) {
2084
2098
  print(JSON.stringify({
2085
2099
  repo: shortRepo(repoAbs), row: policy.derived.row, route: policy.effective.route, final: policy.effective.final, testPeriodDays: policy.effective.testPeriodDays,
2086
2100
  lastFinal, dry: !!opts.dry, auto: !!opts.auto, candidate: cand, tracking: trackingOut,
2087
2101
  periodStart: period ? period.start : null, periodEndsAt: period ? period.endsAt : null,
2088
2102
  state: verdict.state, tagged, finalTag: verdict.finalTag, checks: verdict.checks, handoff: verdict.handoff,
2089
- skipped: walk ? skipped : undefined, announced, grant: verdict.grant || null, channel,
2103
+ skipped: walk ? skipped : undefined, why, next: why ? why.next : null, announced, grant: verdict.grant || null, channel,
2090
2104
  }, null, 2));
2091
2105
  } else {
2092
2106
  print(`colab release finalize${opts.auto ? ' --auto' : ''} — ${shortRepo(repoAbs)} (last final: ${lastFinal || 'none'}${cand ? `, candidate: ${cand.tag}` : ''})`);
@@ -2098,6 +2112,7 @@ function cmdReleaseFinalize(argv) {
2098
2112
  }
2099
2113
  print('');
2100
2114
  print(`state: ${verdict.state}${opts.dry ? ' [--dry: nothing written]' : ''}${tagged ? ` — tagged ${verdict.finalTag} and pushed it to ${remote}` : ''}`);
2115
+ if (why) print(`why no final: ${why.line}`);
2101
2116
  if (announced && announced.issues.length) print(`released in ${verdict.finalTag || version0}: told ${announced.posted.length ? announced.posted.map((n) => `#${n}`).join(', ') : 'nobody new'} (carried: ${announced.issues.map((n) => `#${n}`).join(', ')}${announced.skipped.length ? `; unreadable: ${announced.skipped.map((n) => `#${n}`).join(', ')}` : ''})`);
2102
2117
  if (channel && channel.ok) print(`✓ ${channel.detail}`);
2103
2118
  else if (channel) warn(`${channel.detail} — the final tag stands`);
@@ -6929,7 +6944,9 @@ Per tag-gated repo:
6929
6944
  headCandidate #443, where candidates are automatic: { state, flag, detail } — whether the newest
6930
6945
  candidate names main's head. Flags (state untagged, "head not a candidate") when
6931
6946
  head has been green for longer than one CI cycle — the longest suite run at that
6932
- sha — and carries no tag. Other states: named · nothing-owed · not-green ·
6947
+ sha — and carries no tag. Also flags (state no-final, #467) when there is no final tag
6948
+ at all: \`release cut --auto\` refuses every run until a human tags the first version,
6949
+ a stall that otherwise reads green. Other states: named · nothing-owed · not-green ·
6933
6950
  pending (inside one cycle) · not-promotion (trunk: dev, a hotfix head) · unread · off.
6934
6951
  semverSuggestion from Conventional-Commit types since the last tag: a breaking change (! or a
6935
6952
  BREAKING CHANGE: footer) -> major, else feat -> minor, else fix -> patch,
@@ -6941,7 +6958,7 @@ fetch failure does not abort the row — it degrades to whatever is on disk and
6941
6958
  rather than reporting nothing.
6942
6959
 
6943
6960
  Exit code: 0 when nothing is flagged, 1 when at least one repo is (an unpromoted or unreleased
6944
- fix/breaking commit, or a green head that is not a candidate) — same posture as \`colab update\`'s "behind" tally.
6961
+ fix/breaking commit, a green head that is not a candidate, or no final tag at all) — same posture as \`colab update\`'s "behind" tally.
6945
6962
  `;
6946
6963
 
6947
6964
  function cmdReleaseStatus(argv) {
@@ -6990,7 +7007,7 @@ function cmdReleaseStatus(argv) {
6990
7007
  const tableRows = printable.map((r) => {
6991
7008
  const up = r.unpromoted ? `${r.unpromoted.commits}${r.unpromoted.fixFlag ? ' ⚠' : ''}` : '—';
6992
7009
  const un = r.unreleased.tag ? `${r.unreleased.commits}${r.unreleased.fixFlag ? ' ⚠' : ''} (${r.unreleased.days}d since ${r.unreleased.tag})` : 'no tags yet';
6993
- const hc = r.headCandidate ? (r.headCandidate.flag ? '⚠ not a candidate' : r.headCandidate.state) : '—';
7010
+ const hc = r.headCandidate ? (r.headCandidate.flag ? (r.headCandidate.state === 'no-final' ? '⚠ no final' : '⚠ not a candidate') : r.headCandidate.state) : '—';
6994
7011
  return [r.repo, up, un, hc, r.semverSuggestion.bump || '—', r.flag ? '⚠ FLAGGED' : ''];
6995
7012
  });
6996
7013
  print(table(tableRows, ['REPO', 'UNPROMOTED', 'UNRELEASED', 'HEAD', 'SUGGEST', '']));
@@ -7007,7 +7024,7 @@ function cmdReleaseStatus(argv) {
7007
7024
  }
7008
7025
  print('');
7009
7026
  if (flagged.length) {
7010
- print(`${flagged.length} repo(s) FLAGGED — a fix or breaking commit is sitting unreleased/unpromoted, or a green head is not a candidate:`);
7027
+ print(`${flagged.length} repo(s) FLAGGED — a fix or breaking commit is sitting unreleased/unpromoted, a green head is not a candidate, or there is no final for candidates to follow:`);
7011
7028
  for (const r of flagged) print(` ${r.repo}${r.headCandidate && r.headCandidate.flag ? ` — ${r.headCandidate.detail}` : ''}`);
7012
7029
  print('Who cuts the tag follows the release rung of CONVENTIONS §6 — this only measures the gap.');
7013
7030
  } else {
@@ -9433,9 +9450,9 @@ function ciGrantTrailerLine(grantVerdict, branch, trunk) {
9433
9450
  */
9434
9451
  function ciCureTrailerLine(cureVerdict, branch, trunk) {
9435
9452
  if (!cureVerdict || !cureVerdict.ok) return null;
9436
- const via = cureVerdict.carveOut
9453
+ const via = (cureVerdict.carveOut
9437
9454
  ? ` via workflow-carve-out jobs ${cureVerdict.carveOut.jobs.map((j) => j.name).join(',')}`
9438
- : '';
9455
+ : '') + (cureVerdict.dryRun ? ` via dry-run jobs ${cureVerdict.dryRun.jobs.join(',')}` : '');
9439
9456
  return `CI-Cure: branch ${branch} over-red ${trunk}@${shortSha(cureVerdict.redSha)} evidence ${shortSha(cureVerdict.evidenceSha)}${via}`;
9440
9457
  }
9441
9458
 
@@ -10409,9 +10426,10 @@ function applyRedTrunkExemptions(raw, target, trunk, redSha, grantThunk, cureThu
10409
10426
  const via = cureVerdict.carveOut
10410
10427
  ? ` THROUGH THE #321 WORKFLOW CARVE-OUT — every job red on trunk ran to success here: ${cureVerdict.carveOut.jobs.map((j) => `${j.name} (${j.redMs}ms red, ${j.branchMs}ms passing)`).join(', ')}`
10411
10428
  : '';
10429
+ const viaDry = cureVerdict.dryRun ? ` — main-only job(s) ${cureVerdict.dryRun.jobs.join(', ')} proven by a DRY RUN on the branch (#474)` : '';
10412
10430
  return {
10413
10431
  name: raw.name, ok: true, class: null,
10414
- detail: `PRECONDITION OVERRIDDEN by the cure rule (#281) — branch contains red ${shortSha(redSha)} and is green at its own head${via} (raw: ${raw.detail})`,
10432
+ detail: `PRECONDITION OVERRIDDEN by the cure rule (#281) — branch contains red ${shortSha(redSha)} and is green at its own head${via}${viaDry} (raw: ${raw.detail})`,
10415
10433
  grantVerdict: null, cureVerdict,
10416
10434
  };
10417
10435
  }
@@ -10531,11 +10549,23 @@ function shipCiCure(repoAbs, gh, target, trunk, redSha, branch) {
10531
10549
  // so a branch that cannot cure pays no job-level `gh` calls for it.
10532
10550
  const jobEvidence = (containsRedSha && evidence && evidence.ok)
10533
10551
  ? shipCureJobEvidence(repoAbs, trunk, redSha, branch, evRun) : null;
10552
+ // #474: which workflows at the branch head offer a dry run — a static read (git show), read only
10553
+ // when job evidence exists, so a branch that already refuses on containment or 2a pays nothing.
10554
+ const capable = jobEvidence && evidence ? dryRunCapableWorkflows(repoAbs, evidence.sha) : [];
10534
10555
  const verdict = ciCure.cureVerdict({ containsRedSha, evidence, redSha, stacking, jobEvidence,
10535
10556
  workflowsTouched: diff.workflowsTouched,
10536
10557
  manifestScriptsTouched: diff.manifestScriptsTouched, manifestPaths: diff.manifestPaths,
10537
- pythonManifestTouched: diff.pythonManifestTouched, pythonManifestPaths: diff.pythonManifestPaths });
10538
- return { ...verdict, redSha, evidenceSha: evidence ? evidence.sha : null };
10558
+ pythonManifestTouched: diff.pythonManifestTouched, pythonManifestPaths: diff.pythonManifestPaths,
10559
+ dryRunCapable: capable.map((w) => w.name) });
10560
+ // The dispatch plan carries the FILE and the exact command, so the refusal can name it and the
10561
+ // real ship path can run it — measurement only here; nothing is dispatched by this function.
10562
+ const dryRunDispatch = verdict.dryRunWanted
10563
+ ? verdict.dryRunWanted.map((name) => {
10564
+ const w = capable.find((c) => c.name === name);
10565
+ return { workflow: name, file: w.file, command: `gh workflow run ${w.file} --ref ${branch} -f ${DRY_RUN_INPUT}=true` };
10566
+ })
10567
+ : null;
10568
+ return { ...verdict, ...(dryRunDispatch ? { dryRunDispatch } : {}), redSha, evidenceSha: evidence ? evidence.sha : null };
10539
10569
  }
10540
10570
 
10541
10571
  /**
@@ -10613,9 +10643,71 @@ function ciCurePayload(ciResult) {
10613
10643
  carveOut: c.carveOut
10614
10644
  ? { jobs: c.carveOut.jobs.map((j) => ({ name: j.name, redDurationMs: j.redMs, branchDurationMs: j.branchMs })) }
10615
10645
  : null,
10646
+ // #474: the red job(s) proven only by a dry run of a main-only workflow — null otherwise.
10647
+ dryRun: c.dryRun ? { jobs: c.dryRun.jobs.slice() } : null,
10648
+ // #474: on a refusal, the dry run(s) that would supply the missing 2b evidence — what the real
10649
+ // ship dispatches; `--dry --json` only reports it. null when none would help.
10650
+ dryRunWanted: c.dryRunDispatch ? c.dryRunDispatch.map((d) => ({ ...d })) : null,
10616
10651
  };
10617
10652
  }
10618
10653
 
10654
+ /** The dispatch input a dry-run-capable workflow declares (#474, templates/release-auto.yml). */
10655
+ const DRY_RUN_INPUT = 'dry_run';
10656
+
10657
+ /**
10658
+ * The workflows at `treeish` that offer a dry run (#474): a top-level `name:`, a `workflow_dispatch`
10659
+ * input named `dry_run`, and ci-cure's sentinel step text. All three, read statically at the BRANCH's
10660
+ * head — the copy a dispatch on that ref would run. A pre-#474 copy has no forced-dry mode and would
10661
+ * really publish if dispatched, which is exactly why this read gates every dispatch. `[]` on any
10662
+ * failed read: no capability is ever assumed.
10663
+ */
10664
+ function dryRunCapableWorkflows(repoAbs, treeish) {
10665
+ const ls = git.git(['ls-tree', '--name-only', `${treeish}:.github/workflows`], repoAbs);
10666
+ if (!ls.ok) return [];
10667
+ const out = [];
10668
+ for (const f of ls.stdout.split('\n').map((x) => x.trim()).filter((x) => /\.ya?ml$/.test(x))) {
10669
+ const r = git.git(['show', `${treeish}:.github/workflows/${f}`], repoAbs);
10670
+ if (!r.ok) continue;
10671
+ const name = workflowTriggers.workflowNameOf(r.stdout);
10672
+ if (!name || !r.stdout.includes(ciCure.DRY_RUN_STEP)) continue;
10673
+ if (!workflowTriggers.workflowDispatchInputs(r.stdout).includes(DRY_RUN_INPUT)) continue;
10674
+ out.push({ name, file: f });
10675
+ }
10676
+ return out;
10677
+ }
10678
+
10679
+ /**
10680
+ * Dispatch the dry run(s) a refused cure asked for (#474) — the REAL ship path only, never `--dry`,
10681
+ * never `--dry --json`, never from the measurement above (which runs up to three times per ship).
10682
+ * Skips a workflow that already has ANY run at the branch head, whatever its status: a queued run has
10683
+ * no jobs yet, so "job absent" alone would dispatch it twice. Never waits — the caller re-runs ship
10684
+ * once the run completes (code-ship B1a's bounded wait), the same no-polling stance as every other
10685
+ * read here.
10686
+ */
10687
+ function shipDispatchDryRuns(repoAbs, branch, plan) {
10688
+ const head = git.git(['rev-parse', branch], repoAbs);
10689
+ const runs = head.ok ? git.ghRunsForCommit(repoAbs, branch, head.stdout.trim(), 30) : null;
10690
+ for (const p of plan) {
10691
+ const existing = runs ? runs.filter((r) => r.workflowName === p.workflow) : null;
10692
+ if (existing === null) {
10693
+ warn(` dry run for ${p.workflow} NOT dispatched: the runs at ${branch}'s head could not be read — run it yourself: ${p.command}`);
10694
+ continue;
10695
+ }
10696
+ if (existing.length) {
10697
+ const r = existing[0];
10698
+ warn(` dry run for ${p.workflow} already exists at ${branch}'s head (run ${r.databaseId}, ${r.status}${r.conclusion ? '/' + r.conclusion : ''}) — not dispatched again; re-run \`colab ship\` once it completes.`);
10699
+ continue;
10700
+ }
10701
+ const d = git.ghWorkflowDispatch(repoAbs, p.file, branch, { [DRY_RUN_INPUT]: 'true' });
10702
+ if (d.ok) {
10703
+ warn(` ↻ dispatched a dry run of ${p.workflow} on ${branch} (#474)${d.withInputs ? '' : ' — without the input, which GitHub refused; the ref forces dry mode'}. ` +
10704
+ 'Re-run `colab ship` once it completes (code-ship B1a\'s bounded wait) — it is the evidence this cure is missing.');
10705
+ } else {
10706
+ warn(` dry run for ${p.workflow} could NOT be dispatched (${d.detail}) — run it yourself: ${p.command}`);
10707
+ }
10708
+ }
10709
+ }
10710
+
10619
10711
  /**
10620
10712
  * Previews whether B0's merge (target INTO the branch) would conflict — WITHOUT touching the real
10621
10713
  * worktree, the branch, or the network beyond a fetch — so `ship --dry --json`'s "no hand-merge
@@ -12048,6 +12140,11 @@ function cmdShip(argv) {
12048
12140
  }
12049
12141
  const dryOk = preOk && dryClosingConflicts.length === 0;
12050
12142
  print(dryOk ? '→ READY: preconditions pass. Re-run without --dry to ship.' : '→ NOT READY: fix the ✗ rows above.');
12143
+ if (!ciOk && ciResult.cureVerdict && ciResult.cureVerdict.dryRunDispatch) {
12144
+ for (const d of ciResult.cureVerdict.dryRunDispatch) {
12145
+ print(` Dry run wanted (#474): ${d.workflow} has no run on this branch — a real \`colab ship\` dispatches \`${d.command}\` and refuses until it completes.`);
12146
+ }
12147
+ }
12051
12148
  if (mode.evidenceClose) {
12052
12149
  print(' Plan: no merge, no commit, no push · post evidence comment + CLOSE each issue · ' +
12053
12150
  (opts.keepWorktree ? 'keep worktree' : 'worktree rm') + ' (releases claims)');
@@ -12078,7 +12175,14 @@ function cmdShip(argv) {
12078
12175
  if (refsIssues.length) print(` Refs (kept open, NOT closed): ${refsIssues.map((n) => '#' + n).join(' ')}`);
12079
12176
  return dryOk ? 0 : 1;
12080
12177
  }
12081
- if (!preOk) { process.stderr.write('✗ Aborting: one or more preconditions failed (see ✗ above). Nothing was pushed.\n'); return 1; }
12178
+ if (!preOk) {
12179
+ // #474: the cure is missing only a main-only workflow's run, and that workflow offers a dry run —
12180
+ // dispatch it now (once), so the re-run has the evidence. Never on --dry: that returned above.
12181
+ if (!ciOk && ciResult.cureVerdict && ciResult.cureVerdict.dryRunDispatch && gh) {
12182
+ shipDispatchDryRuns(repoAbs, sess.branch, ciResult.cureVerdict.dryRunDispatch);
12183
+ }
12184
+ process.stderr.write('✗ Aborting: one or more preconditions failed (see ✗ above). Nothing was pushed.\n'); return 1;
12185
+ }
12082
12186
 
12083
12187
  // ---- (b3) evidence-close: the whole B0–B2 sequence is skipped, because there is nothing to merge ----
12084
12188
  if (mode.evidenceClose) return shipEvidenceClose({
@@ -126,6 +126,33 @@
126
126
  * is the obvious first follow-up the moment that refusal is observed in the field, but adding it
127
127
  * unmeasured is precisely the speculative loosening condition 4 exists to resist.
128
128
  *
129
+ * DRY-RUN EVIDENCE FOR A MAIN-ONLY WORKFLOW (#474). Some checks never run on a branch at all:
130
+ * `release-auto.yml` fires on `workflow_run` after trunk CI, or on a schedule. 2b then refuses every
131
+ * fix for a red in it (the job is absent on the branch), and a human ci-grant was the only door,
132
+ * even for a mechanical defect. The workflow template therefore offers a DRY RUN: dispatched on the
133
+ * fix branch, it runs the same job and the same steps, but with every external write turned off. Steps
134
+ * that would publish are skipped, and their names end in `PUBLISH_STEP_MARKER`. A sentinel step named
135
+ * `DRY_RUN_STEP` runs only in that mode, and is how a job instance is recognised as a dry run here.
136
+ * Such an instance counts as the job's evidence for 2b (and hence 4a) only when, on top of 2b:
137
+ *
138
+ * D1. both step lists are measurable — trunk's ran-steps and the dry run's steps;
139
+ * D2. every step that RAN on trunk, the failing one included, concluded `success` in the dry run.
140
+ * This is the not-a-back-door proof: a red INSIDE a publishing step can never be cured this way,
141
+ * because the dry run skips exactly that step. It is 4b, applied to dry-run instances on every
142
+ * path, not only the carve-out's;
143
+ * D3. every step the dry run did NOT run to success is a skipped publishing step. A dry run that
144
+ * also skipped some ordinary step past trunk's failure point has not run the job, it has run
145
+ * part of it.
146
+ *
147
+ * Why a NAME marker and not a list declared in the workflow: steps are matched by exact name (D2/4b),
148
+ * so marking the very step that failed on trunk renames it, and D2 then reads it as absent and
149
+ * refuses. A list inside the workflow would be read from the branch, which is the party being graded.
150
+ *
151
+ * Limit, stated: a red in a publishing step, or in a later job that only runs after a tag (npm,
152
+ * deploy), cannot be cured by a dry run. That stays a ci-grant. So does a red job that ran ZERO steps
153
+ * (a runner that never picked it up) on the carve-out path: 4c has no usable duration for it and
154
+ * refuses, which is the safe direction and a deliberately unmade loosening, like the timeout case.
155
+ *
129
156
  * PURE BY CONSTRUCTION, identical posture to ci-grant.js / migration-grant.js / readiness.js /
130
157
  * shipguard.js: signals in, verdict out. No git, no network, no `gh`. The caller (tools/colab)
131
158
  * measures containment, evidence, anti-stacking and the workflow-file diff, and hands them in.
@@ -177,6 +204,25 @@ const PYTHON_MANIFEST_REFUSAL =
177
204
  * never ran is not a job that failed. */
178
205
  const NOT_RED_CONCLUSIONS = new Set(['success', 'cancelled', 'skipped']);
179
206
 
207
+ /** The suffix a step name carries when the dry run skips it because it writes outside the run (#474).
208
+ * The template names its publishing steps with it; D3 admits no other skipped step. */
209
+ const PUBLISH_STEP_MARKER = '[publish]';
210
+
211
+ /** The sentinel step a dry-run job instance runs and an ordinary one skips (#474). Its successful
212
+ * presence is the only thing that marks an instance as a dry run here. Must match the template's
213
+ * step name byte for byte. */
214
+ const DRY_RUN_STEP = 'Dry run — nothing is tagged, released or published';
215
+
216
+ function isPublishStepName(name) {
217
+ return typeof name === 'string' && name.trimEnd().endsWith(PUBLISH_STEP_MARKER);
218
+ }
219
+
220
+ /** A job instance is a dry run iff its sentinel step concluded `success`. A skipped sentinel is an
221
+ * ordinary run (the template's `if:` was false), never a dry one. */
222
+ function isDryRunSteps(steps) {
223
+ return Array.isArray(steps) && steps.some((s) => s && s.name === DRY_RUN_STEP && s.conclusion === 'success');
224
+ }
225
+
180
226
  /** A step "ran" on trunk iff it reached a terminal conclusion that is not `skipped`/`cancelled`.
181
227
  * Steps after the failing one are skipped by GitHub, and a skipped step constrains nothing. */
182
228
  function stepRan(s) {
@@ -245,6 +291,7 @@ function shapeJobEvidence({ redRunJobs, branchRunJobs } = {}) {
245
291
  conclusion: j && j.conclusion,
246
292
  durationMs: j ? durationMs(j.startedAt, j.completedAt) : null,
247
293
  steps: j && Array.isArray(j.steps) ? j.steps.map((s) => ({ name: s && s.name, conclusion: s && s.conclusion })) : null,
294
+ dryRun: !!j && isDryRunSteps(j.steps),
248
295
  }));
249
296
 
250
297
  return { redJobs, branchJobs };
@@ -279,13 +326,46 @@ function indexBranchJobs(branchJobs) {
279
326
  const isRed = j.status === 'completed' && !NOT_RED_CONCLUSIONS.has(j.conclusion);
280
327
  const isPending = j.status !== 'completed';
281
328
  if (!prev) { idx.set(k, { job: j, hasRed: isRed, hasPending: isPending }); continue; }
282
- const better = j.status === 'completed' && j.conclusion === 'success'
283
- && !(prev.job.status === 'completed' && prev.job.conclusion === 'success');
329
+ const ok = (x) => x.status === 'completed' && x.conclusion === 'success';
330
+ // A green ORDINARY instance outranks a green dry run (#474): the dry-run rules only apply when
331
+ // a dry run is the sole evidence the branch has for that job.
332
+ const better = ok(j) && (!ok(prev.job) || (prev.job.dryRun && !j.dryRun));
284
333
  idx.set(k, { job: better ? j : prev.job, hasRed: prev.hasRed || isRed, hasPending: prev.hasPending || isPending });
285
334
  }
286
335
  return idx;
287
336
  }
288
337
 
338
+ /**
339
+ * The dry-run rules (#474), D1–D3 — see the module header. `red` is a trunk red job (with
340
+ * `ranSteps`), `mine` the branch's dry-run instance of the same job (with `steps`). Returns a refusal
341
+ * reason, or '' when the dry run is admissible evidence for this job.
342
+ */
343
+ function dryRunEvidence(red, mine) {
344
+ const label = jobLabel(red);
345
+ if (!Array.isArray(red.ranSteps) || !Array.isArray(mine.steps)) {
346
+ return `job \`${label}\` is proven only by a dry run, and its step lists could not be read — a dry run is admissible only step by step`;
347
+ }
348
+ const mySteps = new Map();
349
+ for (const s of mine.steps) if (s && s.name) mySteps.set(s.name, s);
350
+ for (const stepName of red.ranSteps) {
351
+ const s = mySteps.get(stepName);
352
+ if (!s) {
353
+ return `step \`${stepName}\` RAN in job \`${label}\` on trunk and is absent from the branch's dry run — a dry run proves only the steps it executes`;
354
+ }
355
+ if (s.conclusion !== 'success') {
356
+ return `step \`${stepName}\` RAN in job \`${label}\` on trunk and concluded \`${s.conclusion}\` in the branch's dry run — ` +
357
+ 'a dry run cannot cure a red in a step it does not execute (a red in a publishing step stays a ci-grant)';
358
+ }
359
+ }
360
+ for (const s of mine.steps) {
361
+ if (!s || s.conclusion === 'success') continue;
362
+ if (s.conclusion === 'skipped' && isPublishStepName(s.name)) continue;
363
+ return `step \`${s && s.name}\` concluded \`${s && s.conclusion}\` in the branch's dry run of job \`${label}\` and is not a publishing step ` +
364
+ `(name ending \`${PUBLISH_STEP_MARKER}\`) — a dry run may skip only the steps that write outside the run`;
365
+ }
366
+ return '';
367
+ }
368
+
289
369
  /**
290
370
  * Sub-test 4a (#321), and — since #297 — condition 2b of EVERY cure: every job RED on trunk exists
291
371
  * on the branch's runs at its own head, completed and successful.
@@ -299,7 +379,8 @@ function indexBranchJobs(branchJobs) {
299
379
  * that exists only on the branch: this certifies that the branch cures trunk's red, not that the
300
380
  * branch is spotless.
301
381
  *
302
- * Returns `{ok, reason, jobs}` — `jobs` is the list of red job names proven on the branch.
382
+ * Returns `{ok, reason, jobs, dryRunJobs}` — `jobs` is the list of red job names proven on the branch,
383
+ * `dryRunJobs` the subset proven only by a dry run (#474), each having passed D1–D3.
303
384
  * Every unmeasurable input is a refusal, never a pass.
304
385
  */
305
386
  function redJobsProvenOnBranch(jobEvidence) {
@@ -317,6 +398,7 @@ function redJobsProvenOnBranch(jobEvidence) {
317
398
  return { ok: false, jobs: [], reason: "the branch's own run reported no jobs to compare against" };
318
399
  }
319
400
  const idx = indexBranchJobs(branchJobs);
401
+ const dryRunJobs = [];
320
402
 
321
403
  for (const red of redJobs) {
322
404
  if (!red || !red.name) {
@@ -341,8 +423,13 @@ function redJobsProvenOnBranch(jobEvidence) {
341
423
  return { ok: false, jobs: [],
342
424
  reason: `job \`${label}\` is red on trunk and failed in another run at the branch's own head — a job that both passed and failed at one sha has proven nothing` };
343
425
  }
426
+ if (mine.dryRun) {
427
+ const why = dryRunEvidence(red, mine);
428
+ if (why) return { ok: false, jobs: [], reason: why };
429
+ dryRunJobs.push(red.name);
430
+ }
344
431
  }
345
- return { ok: true, jobs: redJobs.map((r) => r.name), reason: '' };
432
+ return { ok: true, jobs: redJobs.map((r) => r.name), ...(dryRunJobs.length ? { dryRunJobs } : {}), reason: '' };
346
433
  }
347
434
 
348
435
  /**
@@ -402,6 +489,34 @@ function workflowCarveOut(jobEvidence) {
402
489
  return { ok: true, jobs, reason: '' };
403
490
  }
404
491
 
492
+ /**
493
+ * Would a dry run on the branch supply the evidence 2b is missing (#474)? PURE. Returns the sorted
494
+ * workflow names to dispatch, or `[]`. Non-empty only when EVERY red job is either already passing
495
+ * on the branch (completed `success`, nothing red or pending beside it) or ABSENT from the branch's
496
+ * runs in a workflow listed in `dryRunCapable` — and at least one is absent. A red job that is
497
+ * present-but-failing, pending, or absent in a workflow without a dry-run mode means no dispatch
498
+ * would help, so none is asked for. Whether the dry run, once it exists, passes D1–D3 is decided
499
+ * then, not predicted now.
500
+ */
501
+ function dryRunDispatchPlan(jobEvidence, dryRunCapable) {
502
+ const capable = new Set(Array.isArray(dryRunCapable) ? dryRunCapable : dryRunCapable instanceof Set ? [...dryRunCapable] : []);
503
+ if (!capable.size || !jobEvidence || !Array.isArray(jobEvidence.redJobs) || !jobEvidence.redJobs.length) return [];
504
+ const idx = indexBranchJobs(Array.isArray(jobEvidence.branchJobs) ? jobEvidence.branchJobs : []);
505
+ const want = new Set();
506
+ for (const red of jobEvidence.redJobs) {
507
+ if (!red || !red.name) return [];
508
+ const entry = idx.get(jobKey(red));
509
+ if (!entry) {
510
+ if (!red.workflowName || !capable.has(red.workflowName)) return [];
511
+ want.add(red.workflowName);
512
+ continue;
513
+ }
514
+ const mine = entry.job;
515
+ if (mine.status !== 'completed' || entry.hasPending || mine.conclusion !== 'success' || entry.hasRed) return [];
516
+ }
517
+ return [...want].sort();
518
+ }
519
+
405
520
  /**
406
521
  * The cure verdict for one branch's attempt to ship into a red trunk.
407
522
  *
@@ -453,7 +568,7 @@ function workflowCarveOut(jobEvidence) {
453
568
  * the presence of `carveOut` rather than by re-deriving it.
454
569
  */
455
570
  function cureVerdict({ containsRedSha, evidence, redSha, stacking, workflowsTouched, jobEvidence,
456
- manifestScriptsTouched, manifestPaths, pythonManifestTouched, pythonManifestPaths }) {
571
+ manifestScriptsTouched, manifestPaths, pythonManifestTouched, pythonManifestPaths, dryRunCapable }) {
457
572
  if (!containsRedSha) {
458
573
  return { ok: false,
459
574
  reason: `branch does not contain trunk's current red head \`${redSha}\` as an ancestor — ` +
@@ -473,10 +588,20 @@ function cureVerdict({ containsRedSha, evidence, redSha, stacking, workflowsTouc
473
588
  }
474
589
  const proven = redJobsProvenOnBranch(jobEvidence);
475
590
  if (!proven.ok) {
476
- return { ok: false,
591
+ const out = { ok: false,
477
592
  reason: `branch's run is green, but the check trunk is red on is not proven here: ${proven.reason} — ` +
478
593
  'a cure must pass the named failing job(s), not merely produce a green run (#297)' };
594
+ // #474: say which dry run would supply the missing evidence — only when every LATER condition
595
+ // already holds, so a dispatch is never asked for on a branch that would refuse anyway.
596
+ const wanted = dryRunDispatchPlan(jobEvidence, dryRunCapable);
597
+ if (wanted.length && stacking && stacking.ok && manifestScriptsTouched === false && pythonManifestTouched === false
598
+ && typeof workflowsTouched === 'boolean') {
599
+ out.dryRunWanted = wanted;
600
+ }
601
+ return out;
479
602
  }
603
+ const dry = proven.dryRunJobs && proven.dryRunJobs.length ? { jobs: proven.dryRunJobs } : null;
604
+ const drySuffix = dry ? ` — the main-only job(s) ${dry.jobs.map((n) => `\`${n}\``).join(', ')} proven by a dry run on the branch (#474)` : '';
480
605
  if (!stacking || !stacking.ok) {
481
606
  return { ok: false, reason: (stacking && stacking.reason) || 'anti-stacking verdict unavailable' };
482
607
  }
@@ -500,13 +625,13 @@ function cureVerdict({ containsRedSha, evidence, redSha, stacking, workflowsTouc
500
625
  return { ok: false, reason: `${WORKFLOW_REFUSAL}. The #321 carve-out does not admit it either: ${carve.reason}` };
501
626
  }
502
627
  const detail = carve.jobs.map((j) => `\`${j.name}\` (${j.redMs}ms red on trunk, ${j.branchMs}ms passing here)`).join(', ');
503
- return { ok: true, provenJobs: proven.jobs, carveOut: { jobs: carve.jobs },
628
+ return { ok: true, provenJobs: proven.jobs, carveOut: { jobs: carve.jobs }, ...(dry ? { dryRun: dry } : {}),
504
629
  reason: `branch contains red \`${redSha}\` as an ancestor AND is green at its own current head (\`${evidence.sha}\`) — proven cure, ` +
505
- `admitted through the #321 workflow carve-out: every job red on trunk ran to success here with every step it took on trunk — ${detail}` };
630
+ `admitted through the #321 workflow carve-out: every job red on trunk ran to success here with every step it took on trunk — ${detail}${drySuffix}` };
506
631
  }
507
- return { ok: true, provenJobs: proven.jobs,
508
- reason: `branch contains red \`${redSha}\` as an ancestor AND is green at its own current head (\`${evidence.sha}\`) — proven cure` };
632
+ return { ok: true, provenJobs: proven.jobs, ...(dry ? { dryRun: dry } : {}),
633
+ reason: `branch contains red \`${redSha}\` as an ancestor AND is green at its own current head (\`${evidence.sha}\`) — proven cure${drySuffix}` };
509
634
  }
510
635
 
511
- module.exports = { cureVerdict, redJobsProvenOnBranch, workflowCarveOut, shapeJobEvidence, WORKFLOW_REFUSAL, MANIFEST_SCRIPTS_REFUSAL,
512
- PYTHON_MANIFEST_REFUSAL };
636
+ module.exports = { cureVerdict, redJobsProvenOnBranch, workflowCarveOut, shapeJobEvidence, dryRunDispatchPlan, WORKFLOW_REFUSAL,
637
+ MANIFEST_SCRIPTS_REFUSAL, PYTHON_MANIFEST_REFUSAL, PUBLISH_STEP_MARKER, DRY_RUN_STEP };
package/tools/lib/git.js CHANGED
@@ -1157,6 +1157,25 @@ function ghRunJobs(repo, runDatabaseId) {
1157
1157
  }));
1158
1158
  }
1159
1159
 
1160
+ /**
1161
+ * Dispatch `workflowFile` on `ref` (#474) — `gh workflow run <file> --ref <ref> -f k=v…`. Returns
1162
+ * `{ok, withInputs, detail}`. If the call with inputs is refused (GitHub can validate inputs against
1163
+ * a workflow file that does not declare them yet), it is retried ONCE without them: the release-auto
1164
+ * template forces dry mode on any ref other than main, so an input-less dispatch of a capable file is
1165
+ * still a dry run. The caller only ever dispatches a file it read as dry-run capable at that ref.
1166
+ * Never waits for the run.
1167
+ */
1168
+ function ghWorkflowDispatch(repo, workflowFile, ref, inputs = {}) {
1169
+ const flags = [];
1170
+ for (const [k, v] of Object.entries(inputs)) flags.push('-f', `${k}=${v}`);
1171
+ const first = run('gh', ['workflow', 'run', workflowFile, '--ref', ref, ...flags], { cwd: repo });
1172
+ if (first.ok) return { ok: true, withInputs: true, detail: '' };
1173
+ if (!flags.length) return { ok: false, withInputs: false, detail: (first.stderr || first.stdout || '').trim().split('\n')[0] || 'gh workflow run failed' };
1174
+ const second = run('gh', ['workflow', 'run', workflowFile, '--ref', ref], { cwd: repo });
1175
+ if (second.ok) return { ok: true, withInputs: false, detail: (first.stderr || '').trim().split('\n')[0] || '' };
1176
+ return { ok: false, withInputs: false, detail: (second.stderr || second.stdout || '').trim().split('\n')[0] || 'gh workflow run failed' };
1177
+ }
1178
+
1160
1179
  /**
1161
1180
  * Issues claimed by the current gh user in a repo = assigned to @me AND labeled in-progress
1162
1181
  * (that pairing is exactly what `colab claim` writes). Returns array of numbers, or null on failure.
@@ -1177,7 +1196,7 @@ module.exports = {
1177
1196
  dirtyTracked, dirtyUntracked, dirtyAny,
1178
1197
  ghAvailable, ghState, ghIssueEdit, ghListLabels, ghOpenIssueNumbersByLabel, ghAssignedIssues,
1179
1198
  ghCurrentLogin, ghIssueView, ghIssueComment, ghRunForSha, ghRunForCommit, ghRunsForCommit, ghRunsForRef, ghRunsAtCommit, ghRunForCommitAnyRef, commitTimeMs, ghRunsSince, summarizeRunsForCommit, isRepoOwnedRun,
1180
- ghRunJobCount, ghRunJobs,
1199
+ ghRunJobCount, ghRunJobs, ghWorkflowDispatch,
1181
1200
  ghIssueListByLabel, ghLabelDelete, ghLabelCreate, ghListLabelsDetailed, ghLabelEditDescription,
1182
1201
  ghApi, isGraphqlRateLimit, ghIssueRelease, ghClaimHolder, ghIssueLabelEvents, ghIssueLabelActors,
1183
1202
  ghPrForBranch, ghPrCreate, ghPrClose, ghRepoVisibility,
@@ -85,6 +85,20 @@ const CONDITIONS = Object.freeze([
85
85
  'final-grant', 'release-hold', 'migration-grant',
86
86
  ]);
87
87
 
88
+ /**
89
+ * #467: the refusals that do NOT clear by themselves. A run refused on one of these refuses again on
90
+ * the next run and the one after — nothing but a human act (a first final tag, a fixed marker, a
91
+ * fixed manifest, a recorded grant) moves it — so the release workflow reports it as a STALL, an
92
+ * error annotation, never as the routine warning a CI-still-running refusal gets. The rest are
93
+ * transient: `ci-green` / `full-suite` (a run in flight, a red run the next merge fixes), an UNREAD
94
+ * anything (a read that failed — the next run reads again), and `release-hold` (a deliberate human
95
+ * veto is not a stall; it is the system working). Classified in decide() as `standing`.
96
+ */
97
+ const STANDING_CONDITIONS = Object.freeze([
98
+ 'release-policy', 'prerelease-trigger', 'version', 'schema-additive', 'switch-dependencies',
99
+ ...releaseTag.PRE_TAG_CONDITIONS, 'final-grant', 'migration-grant',
100
+ ]);
101
+
88
102
  /** #446: the conditions only route deploy-tag-fast reports. */
89
103
  const FAST_CONDITIONS = Object.freeze(['spacing', 'already-final', 'final-grant', 'release-hold', 'migration-grant']);
90
104
 
@@ -371,7 +385,7 @@ function parseMigrationSection(text, version) {
371
385
  function decideAutoVersion({ lastFinal, signals, migration, tags }) {
372
386
  const refuse = (detail, extra = {}) => ({ ok: false, detail, ...extra });
373
387
  const s = signals || { total: 0, breaking: [], minor: [], patch: [], unread: [] };
374
- if (s.unread && s.unread.length) return refuse(`a bump signal could not be read — fail closed: ${s.unread.join('; ')}`);
388
+ if (s.unread && s.unread.length) return refuse(`a bump signal could not be read — fail closed: ${s.unread.join('; ')}`, { unread: true });
375
389
  if (!lastFinal) return refuse('no final release tag (vX.Y.Z) on main yet — the first version is a human decision, not a computed bump');
376
390
  const last = parseVersion(lastFinal);
377
391
  if (!last) return refuse(`the last release tag ${lastFinal} is not vX.Y.Z — cannot compute a bump from it`);
@@ -443,7 +457,7 @@ function spacingVerdict({ finals, spacingHours, now }) {
443
457
  * to put the label on, so a human may put it on any issue, and only a human removes it.
444
458
  */
445
459
  function holdsVerdict(issues) {
446
- if (issues === null || issues === undefined) return { ok: false, detail: `the open issues could not be read — an unread ${HOLD_LABEL} is not an absent one` };
460
+ if (issues === null || issues === undefined) return { ok: false, unread: true, detail: `the open issues could not be read — an unread ${HOLD_LABEL} is not an absent one` };
447
461
  const held = issues.filter((i) => i && (!i.state || String(i.state).toUpperCase() === 'OPEN')
448
462
  && (i.labels || []).some((l) => (l && typeof l === 'object' ? l.name : l) === HOLD_LABEL)).map((i) => i.number);
449
463
  return held.length
@@ -480,16 +494,22 @@ const DOWNSTREAM_EVENTS = Object.freeze(['workflow_run', 'schedule', 'workflow_d
480
494
  * whole suite-duration after it went green is one the release run did not tag.
481
495
  *
482
496
  * Returns { state, flag, detail, greenAt, cycleMs } — state is one of: off · named · nothing-owed ·
483
- * not-promotion · unread · not-green · pending · untagged. Only `untagged` flags.
497
+ * no-final · not-promotion · unread · not-green · pending · untagged. `untagged` and `no-final` flag.
498
+ *
499
+ * `no-final` (#467): candidates are automatic but there is no final tag to compute a bump from, so
500
+ * `release cut --auto` refuses on every run, forever, until a human tags the first version. That is a
501
+ * stall, not "nothing owed" — reading it as nothing-owed is how a repo sat green for days with no tag.
484
502
  */
485
503
  function headCandidateVerdict({ candidatesAuto, sha, tagsAtSha, owed, runs, promotion, now }) {
486
504
  const at = `main@${String(sha || '').slice(0, 7)}`;
487
- const out = (state, detail, extra = {}) => ({ state, flag: state === 'untagged', detail, greenAt: null, cycleMs: null, ...extra });
505
+ const out = (state, detail, extra = {}) => ({ state, flag: state === 'untagged' || state === 'no-final', detail, greenAt: null, cycleMs: null, ...extra });
488
506
  if (!candidatesAuto) return out('off', 'candidates are not automatic here — nothing names the head by itself');
489
507
  const named = (tagsAtSha || []).filter((t) => /^v[0-9]+\.[0-9]+\.[0-9]+(-rc\.[1-9][0-9]*)?$/.test(t));
490
508
  if (named.length) return out('named', `${at} is ${named.join(', ')}`);
491
509
  if (owed === 0) return out('nothing-owed', `nothing merged on main since the last final — no candidate is owed`);
492
- if (owed === null || owed === undefined) return out('nothing-owed', 'no final tag yet — the first version is a human decision, so no candidate is owed');
510
+ if (owed === null || owed === undefined) {
511
+ return out('no-final', 'no final tag yet — `release cut --auto` refuses every run until a human tags the first version (CONVENTIONS.md §6, Versioning); release stalled');
512
+ }
493
513
  if (promotion && !promotion.ok) return out('not-promotion', `${at} is not a promotion of trunk — --auto never cuts it (${promotion.detail})`);
494
514
  if (!Array.isArray(runs)) return out('unread', `gh run list failed — cannot tell whether ${at} is green`);
495
515
  const suite = runs.filter((r) => r && !DOWNSTREAM_EVENTS.includes(r.event));
@@ -725,7 +745,7 @@ function closedDone(issue) {
725
745
  * here: this is the release-time consequence, not the edge audit.
726
746
  */
727
747
  function switchVerdict(issues) {
728
- if (issues === null || issues === undefined) return { ok: false, detail: 'the issue list could not be read — switch dependencies cannot be cleared' };
748
+ if (issues === null || issues === undefined) return { ok: false, unread: true, detail: 'the issue list could not be read — switch dependencies cannot be cleared' };
729
749
  const problems = [];
730
750
  const needsOf = new Map(); // name -> { needs: [..], from: #N }
731
751
  const declared = new Set();
@@ -799,11 +819,18 @@ function promotionVerdict({ trunk, sha, parents, headOnTrunk, mergedFromTrunk, e
799
819
  function decide(facts) {
800
820
  const f = facts || {};
801
821
  const checks = [];
802
- const add = (condition, ok, detail) => checks.push({ condition, ok: !!ok, detail });
822
+ // #467: `unread` marks a failure that is a failed READ, not a measured fact — the next run reads
823
+ // again, so it is never a standing refusal. Kept out of the check rows (their shape is frozen).
824
+ const unreadSet = new Set();
825
+ const add = (condition, ok, detail, unread) => {
826
+ checks.push({ condition, ok: !!ok, detail });
827
+ if (!ok && unread) unreadSet.add(condition);
828
+ };
829
+ const isUnread = (verdict) => !!(verdict && verdict.unread);
803
830
 
804
831
  const p = f.policy;
805
832
  const fast = isFastRoute(p) && !(p.findings && p.findings.length);
806
- if (!p) add('release-policy', false, 'no release policy was evaluated');
833
+ if (!p) add('release-policy', false, 'no release policy was evaluated', true);
807
834
  else if (p.findings && p.findings.length) add('release-policy', false, `the release: block is invalid — ${p.findings.map((x) => x.text).join('; ')}`);
808
835
  else if (fast && !f.auto) {
809
836
  add('release-policy', false, 'route deploy-tag-fast tags its finals only from the release workflow (`colab release cut --auto`), where the deploy runs in the same run — a final cut by hand would reach production with no deploy job behind it');
@@ -822,7 +849,7 @@ function decide(facts) {
822
849
  let noop = false;
823
850
  if (f.auto) {
824
851
  const cad = f.auto.cadence || { ok: false, detail: 'cadence not measured' };
825
- add('cadence', cad.ok, cad.detail);
852
+ add('cadence', cad.ok, cad.detail, !f.auto.cadence);
826
853
  if (!cad.ok) noop = !!f.auto.cadence;
827
854
  if (fast) {
828
855
  const sp = f.auto.spacing || { ok: false, detail: 'final spacing not measured' };
@@ -832,7 +859,7 @@ function decide(facts) {
832
859
  // #429: on `trunk:` other than main, only a promotion head is a candidate; anything else no-ops.
833
860
  const pr = f.auto.promotion;
834
861
  if (pr) {
835
- add('promotion', pr.ok, pr.detail);
862
+ add('promotion', pr.ok, pr.detail, isUnread(pr));
836
863
  if (!pr.ok && !pr.unread) noop = true;
837
864
  }
838
865
  }
@@ -844,7 +871,7 @@ function decide(facts) {
844
871
  const v = f.auto
845
872
  ? decideAutoVersion({ lastFinal: f.lastFinal, signals: f.auto.signals, migration: f.auto.migration, tags: f.tags })
846
873
  : decideVersion({ lastFinal: f.lastFinal, suggestion: f.suggestion, override: f.override, tags: f.tags });
847
- add('version', v.ok, v.detail);
874
+ add('version', v.ok, v.detail, isUnread(v));
848
875
  // "Nothing merged since the last final" is a no-op for the release workflow, not a failure.
849
876
  if (f.auto && v.nothing) noop = true;
850
877
 
@@ -875,7 +902,10 @@ function decide(facts) {
875
902
  // #424: the three pre-tag checks, on the tag this run would create.
876
903
  if (tag) {
877
904
  for (const c of releaseTag.preTagChecks({ tag, manifests: f.manifests, ancestry: f.ancestry, tags: f.tags, trunk: RELEASE_BRANCH, versionSource: versionSourceOf(p) })) {
878
- add(c.condition, c.ok, c.detail);
905
+ // An unread manifest list or an unmeasured ancestry is a failed read, not a wrong manifest.
906
+ const unreadPre = (c.condition === 'manifest-version' && (f.manifests === null || f.manifests === undefined))
907
+ || (c.condition === 'on-trunk' && !f.ancestry);
908
+ add(c.condition, c.ok, c.detail, unreadPre);
879
909
  if (c.derivable && c.derivable.length) derivable = c.derivable;
880
910
  }
881
911
  } else if (f.ancestry && f.ancestry.shallow) {
@@ -884,8 +914,8 @@ function decide(facts) {
884
914
  }
885
915
 
886
916
  for (const [condition, verdict] of [['ci-green', f.ci], ['full-suite', f.suite], ['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
887
- if (!verdict) add(condition, false, 'not measured');
888
- else add(condition, verdict.ok, verdict.detail);
917
+ if (!verdict) add(condition, false, 'not measured', true);
918
+ else add(condition, verdict.ok, verdict.detail, isUnread(verdict));
889
919
  }
890
920
 
891
921
  // #446: what the fast route keeps in place of the test period it does not have.
@@ -893,19 +923,24 @@ function decide(facts) {
893
923
  let grant = null;
894
924
  if (fast) {
895
925
  const g = f.finalGrant || { ok: false, detail: `release.final-grant #${p.effective.finalGrant.issue} was not resolved — an unresolved grant is not a grant` };
896
- add('final-grant', g.ok, g.detail);
926
+ add('final-grant', g.ok, g.detail, !f.finalGrant || isUnread(g));
897
927
  if (g.ok) grant = { issue: p.effective.finalGrant.issue, ruledBy: g.ruledBy || null };
898
928
  const h = f.holds || { ok: false, detail: `${HOLD_LABEL} was not measured` };
899
- add('release-hold', h.ok, h.detail);
929
+ add('release-hold', h.ok, h.detail, !f.holds || isUnread(h));
900
930
  const mig = f.migrations || { ok: false, detail: 'migrations since the last final were not measured' };
901
- add('migration-grant', mig.ok, mig.detail);
931
+ add('migration-grant', mig.ok, mig.detail, !f.migrations || isUnread(mig));
902
932
  if (!mig.ok && v.ok && mig.paths && mig.paths.length) handoff = migrationHandoff(f.trackingIssue, v.version);
903
933
  }
904
934
 
905
935
  const refusals = checks.filter((c) => !c.ok);
906
936
  const ok = refusals.length === 0 && !!tag;
937
+ // #467: the refusals that will not clear by themselves — empty on ok and on a no-op, whose
938
+ // "failures" (cadence, nothing merged, head already a candidate) are the route holding.
939
+ const standing = ok || noop ? [] : refusals
940
+ .filter((c) => STANDING_CONDITIONS.includes(c.condition) && !unreadSet.has(c.condition))
941
+ .map((c) => c.condition);
907
942
  return {
908
- ok, noop: !ok && noop, checks, refusals, version: v.ok ? v.version : null, tag: ok ? tag : null,
943
+ ok, noop: !ok && noop, standing, checks, refusals, version: v.ok ? v.version : null, tag: ok ? tag : null,
909
944
  bump: v.ok ? v.bump : (v.bump || null), overridden: v.ok ? v.overridden : null,
910
945
  signals: f.auto ? f.auto.signals || null : null, migration: v.migration || null,
911
946
  derivable,
@@ -945,7 +980,7 @@ function tagMessage(verdict, { sha, lastFinal }) {
945
980
  }
946
981
 
947
982
  module.exports = {
948
- CONDITIONS, FAST_CONDITIONS, BUMPS, MIGRATION_FILE, RELEASE_BRANCH, HOLD_LABEL,
983
+ CONDITIONS, FAST_CONDITIONS, STANDING_CONDITIONS, BUMPS, MIGRATION_FILE, RELEASE_BRANCH, HOLD_LABEL,
949
984
  isFastRoute, spacingVerdict, holdsVerdict, migrationHandoff,
950
985
  parseVersion, formatVersion, candidateNumbers, nextCandidateNumber, decideVersion,
951
986
  parseGuardOutput, exportsDiff, switchRemovalsSince, autoSignals, parseMigrationSection, decideAutoVersion, cadenceVerdict,
@@ -202,18 +202,102 @@ function openCandidates(tags, remote = 'origin') {
202
202
  }
203
203
 
204
204
  /**
205
- * --auto (#423): `evaluations` is [{ candidate, verdict }] NEWEST FIRST, one decide() per candidate
206
- * judged. Returns { candidate, verdict, skipped: [{ tag, state }] }:
205
+ * #468: the one check that explains a verdict's state, as `<condition>: <detail>` — or null when the
206
+ * state needs no explaining (finalized, already-final). What a reader of a run needs is WHY this
207
+ * candidate did not finalize, not the whole checklist again.
208
+ */
209
+ function stateDetail(verdict) {
210
+ const v = verdict || {};
211
+ const checks = v.checks || [];
212
+ const failing = (name) => checks.find((c) => c.condition === name && !c.ok);
213
+ const fmt = (c) => (c ? `${c.condition}: ${c.detail}` : null);
214
+ switch (v.state) {
215
+ case 'finalized': case 'already-final': return null;
216
+ case 'held': return fmt(failing('release-hold'));
217
+ case 'needs-new-candidate': return fmt(failing('regressions') || failing('trunk-green'));
218
+ case 'testing': return fmt(failing('test-period') || failing('trunk-green'));
219
+ case 'candidate-ready': return fmt(failing('human'));
220
+ default: return fmt(checks.find((c) => c.required !== false && !c.ok) || checks.find((c) => !c.ok));
221
+ }
222
+ }
223
+
224
+ /**
225
+ * --auto (#423): `evaluations` is [{ candidate, verdict, period? }] NEWEST FIRST, one decide() per
226
+ * candidate judged. Returns { candidate, verdict, skipped: [{ tag, state, detail, endsAt }] }:
207
227
  * - any `held` verdict wins outright — a human veto is never walked around;
208
228
  * - else the first `finalized` (the newest candidate clean on its own clock);
209
229
  * - else the newest candidate's verdict (testing, refused …), with the older ones listed as skipped.
230
+ * #468: each skipped entry says why (stateDetail) and when its own period ends, so a run that
231
+ * finalizes nothing can say which candidate finals first — the fallback to the newest candidate
232
+ * otherwise reads exactly like "only the newest candidate is considered".
210
233
  */
211
234
  function pickNewestClean(evaluations) {
212
235
  const ev = evaluations || [];
213
236
  if (!ev.length) return { candidate: null, verdict: null, skipped: [] };
214
237
  const held = ev.find((e) => e.verdict.state === 'held');
215
238
  const pick = held || ev.find((e) => e.verdict.state === 'finalized') || ev[0];
216
- return { candidate: pick.candidate, verdict: pick.verdict, skipped: ev.filter((e) => e !== pick).map((e) => ({ tag: e.candidate.tag, state: e.verdict.state })) };
239
+ return {
240
+ candidate: pick.candidate,
241
+ verdict: pick.verdict,
242
+ skipped: ev.filter((e) => e !== pick).map((e) => ({
243
+ tag: e.candidate.tag, state: e.verdict.state, detail: stateDetail(e.verdict), endsAt: e.period ? e.period.endsAt : null,
244
+ })),
245
+ };
246
+ }
247
+
248
+ /**
249
+ * #468: is any red trunk run (`redAts`, ISO createdAt times from trunkGreenVerdict's `redAt`) inside
250
+ * this candidate's own window [start, endsAt)? The window is half-open exactly as trunkGreenVerdict
251
+ * reads it. True means the candidate would read `needs-new-candidate` — IF the red run's workflow is
252
+ * among the ones that vetted it; that is only known after a full judge, so a true here may be wrong
253
+ * in the safe direction only: a final delayed, never one made.
254
+ */
255
+ function windowHasRed(period, redAts) {
256
+ if (!period) return null;
257
+ const startMs = Date.parse(period.start);
258
+ const endMs = Date.parse(period.endsAt);
259
+ return (redAts || []).find((t) => { const ms = Date.parse(t); return ms >= startMs && ms < endMs; }) || null;
260
+ }
261
+
262
+ /**
263
+ * #468: why a run produced no final, in one line, plus the candidate that finals first.
264
+ * state, candidate, checks the picked verdict (and its candidate) — the run's reported state
265
+ * period the picked candidate's own period, or null
266
+ * skipped pickNewestClean's skipped list, the cheap-skipped testing ones included
267
+ * now ISO timestamp (the module stays clock-free)
268
+ * Returns null when a final was made (or the version is already final); else { line, next } where
269
+ * `next` = { tag, endsAt, hoursLeft } for the TESTING candidate whose own period ends soonest, or null.
270
+ */
271
+ function whyNoFinal({ state, candidate, checks, period, skipped, now } = {}) {
272
+ if (state === 'finalized' || state === 'already-final') return null;
273
+ const nowMs = Date.parse(now);
274
+ const testing = [
275
+ ...(state === 'testing' && candidate && period ? [{ tag: candidate.tag, endsAt: period.endsAt }] : []),
276
+ ...(skipped || []).filter((x) => x.state === 'testing' && x.endsAt),
277
+ ].filter((x) => !Number.isNaN(Date.parse(x.endsAt)));
278
+ testing.sort((a, b) => Date.parse(a.endsAt) - Date.parse(b.endsAt) || String(a.tag).localeCompare(String(b.tag)));
279
+ const first = testing[0] || null;
280
+ const next = first
281
+ ? { tag: first.tag, endsAt: first.endsAt, hoursLeft: Number.isNaN(nowMs) ? null : Math.max(0, Math.ceil((Date.parse(first.endsAt) - nowMs) / 3600000)) }
282
+ : null;
283
+ const nextText = next ? `${next.tag} is first, its own test period ends ${next.endsAt}${next.hoursLeft !== null ? ` (${next.hoursLeft}h left)` : ''}` : null;
284
+ const why = stateDetail({ state, checks });
285
+ const tag = candidate ? candidate.tag : 'no candidate';
286
+ let line;
287
+ if (state === 'no-candidate') line = `no open candidate to finalize${why ? ` — ${why}` : ''}`;
288
+ else if (state === 'testing') {
289
+ const allTesting = (skipped || []).every((x) => x.state === 'testing');
290
+ line = allTesting && nextText
291
+ ? `no candidate's own test period has elapsed clean — ${nextText}`
292
+ : `${tag} is still testing (${why || 'test period'})${nextText ? `; ${nextText}` : ''}`;
293
+ } else line = `${tag}: ${state}${why ? ` — ${why}` : ''}${nextText ? `; ${nextText}` : ''}`;
294
+ const older = (skipped || []).filter((x) => x.state !== 'testing');
295
+ if (older.length && state === 'testing') {
296
+ const counts = {};
297
+ for (const x of older) counts[x.state] = (counts[x.state] || 0) + 1;
298
+ line += `; older candidates: ${Object.entries(counts).map(([k, n]) => `${n} ${k}`).join(', ')}`;
299
+ }
300
+ return { line, next };
217
301
  }
218
302
 
219
303
  // ---- the test period ----------------------------------------------------------------------------
@@ -263,7 +347,9 @@ function trunkGreenVerdict(runs, { periodStart, periodEnd = null, suiteWorkflows
263
347
  const inWindow = runs.filter((r) => r && Date.parse(r.createdAt) >= startMs && Date.parse(r.createdAt) < endMs && suite.has(r.workflowName || '(unnamed workflow)') && r.event !== 'pull_request');
264
348
  const red = inWindow.filter((r) => r.status === 'completed' && !NOT_RED.has(r.conclusion) && r.conclusion !== 'cancelled');
265
349
  if (red.length) {
266
- return { ok: false, permanent: true, pending: false, detail: `trunk went red during the test period: ${red.map((r) => `${r.workflowName} ${r.conclusion}${r.branch ? ` on ${r.branch}` : ''} at ${String(r.headSha).slice(0, 7)} (${r.createdAt})`).join('; ')}` };
350
+ // #468: redAt — when each red run started — lets an --auto walk skip older candidates whose
351
+ // window holds the same red run without paying a full judge for each (windowHasRed).
352
+ return { ok: false, permanent: true, pending: false, redAt: red.map((r) => r.createdAt), detail: `trunk went red during the test period: ${red.map((r) => `${r.workflowName} ${r.conclusion}${r.branch ? ` on ${r.branch}` : ''} at ${String(r.headSha).slice(0, 7)} (${r.createdAt})`).join('; ')}` };
267
353
  }
268
354
  const unsettled = [];
269
355
  let pending = inWindow.some((r) => r.status !== 'completed');
@@ -342,7 +428,7 @@ function regressionVerdict(edges, { periodStart }) {
342
428
  * evaluate. Returns { ok, detail }.
343
429
  */
344
430
  function migrationGrantVerdict({ paths, grant, since }) {
345
- if (paths === null || paths === undefined) return { ok: false, detail: 'the migration files since the last final could not be read — an unread migration is not an absent one' };
431
+ if (paths === null || paths === undefined) return { ok: false, unread: true, detail: 'the migration files since the last final could not be read — an unread migration is not an absent one' };
346
432
  if (!paths.length) return { ok: true, detail: `no migration file changed since ${since || 'the first commit'}` };
347
433
  const list = paths.join(', ');
348
434
  if (grant && grant.ok) return { ok: true, detail: `${paths.length} migration file(s) since ${since || 'the first commit'} (${list}), granted on the tracking issue #${grant.issue}` };
@@ -522,7 +608,7 @@ module.exports = {
522
608
  STATES, CONDITIONS, HOLD_LABEL, CUT_SUBJECT_SUFFIX,
523
609
  parseVersion, compareVersions, parseCandidate,
524
610
  parseReleaseMarker, releaseMarker, eventMarker, hasEvent, trackingTitle, trackingBody,
525
- selectCandidate, openCandidates, pickNewestClean, periodVerdict, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
611
+ selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
526
612
  handoffCommand, decide, tagMessage, migrationGrantVerdict,
527
613
  carriedIssues, previousFinal, releasedEvent, releasedComment,
528
614
  };
@@ -421,7 +421,7 @@ function parseGrantIssue(v) {
421
421
  function finalGrantVerdict(record, { issue, trust } = {}) {
422
422
  const decisionRecord = require('./decision-record.js');
423
423
  const ref = `release.final-grant #${issue}`;
424
- if (!record) return { ok: false, ruledBy: null, detail: `${ref} could not be read from the tracker — an unread grant is not a grant` };
424
+ if (!record) return { ok: false, unread: true, ruledBy: null, detail: `${ref} could not be read from the tracker — an unread grant is not a grant` };
425
425
  const labels = (record.labels || []).map((l) => (l && typeof l === 'object' ? l.name : l));
426
426
  const all = decisionRecord.liveDecisions(record.comments);
427
427
  const live = decisionRecord.trustedDecisions(record.comments, trust);
@@ -265,9 +265,57 @@ function prereleaseTagTriggers({ readFile, workflows, deploy }) {
265
265
  return out;
266
266
  }
267
267
 
268
+ // --------------------------------------------------- workflow_dispatch inputs (#474)
269
+ //
270
+ // The names declared under `on: workflow_dispatch: inputs:`, in order. `[]` for a bare
271
+ // `workflow_dispatch:` (or one with no inputs), and for a workflow with no dispatch trigger at all —
272
+ // a caller asking "can this be dispatched with dry_run?" needs the same answer for both. Same
273
+ // pragmatic, indentation-aware scan as parseWorkflowOn; the inline `on:` forms carry no inputs.
274
+ function workflowDispatchInputs(text) {
275
+ if (!text) return [];
276
+ const all = text.split(/\r?\n/);
277
+ const start = all.findIndex((l) => /^(on|["']on["'])\s*:\s*(#.*)?$/.test(l));
278
+ if (start === -1) return [];
279
+ const body = [];
280
+ for (let i = start + 1; i < all.length; i++) {
281
+ if (/^\S/.test(all[i])) break;
282
+ body.push(all[i]);
283
+ }
284
+ const indentOf = (l) => l.match(/^(\s*)/)[1].length;
285
+ const meaningful = (l) => l.trim() && !/^\s*#/.test(l);
286
+ const block = (from, parentIndent) => {
287
+ const out = [];
288
+ for (let j = from; j < body.length; j++) {
289
+ if (!meaningful(body[j])) continue;
290
+ if (indentOf(body[j]) <= parentIndent) break;
291
+ out.push(j);
292
+ }
293
+ return out;
294
+ };
295
+ const wd = body.findIndex((l) => /^\s*workflow_dispatch\s*:/.test(l));
296
+ if (wd === -1) return [];
297
+ const wdIndent = indentOf(body[wd]);
298
+ const inp = block(wd + 1, wdIndent).find((j) => /^\s*inputs\s*:\s*(#.*)?$/.test(body[j]));
299
+ if (inp === undefined) return [];
300
+ const lines = block(inp + 1, indentOf(body[inp]));
301
+ if (!lines.length) return [];
302
+ const keyIndent = Math.min(...lines.map((j) => indentOf(body[j])));
303
+ return lines.filter((j) => indentOf(body[j]) === keyIndent)
304
+ .map((j) => (body[j].match(/^\s*([A-Za-z_][\w-]*)\s*:/) || [])[1]).filter(Boolean);
305
+ }
306
+
307
+ // A workflow's top-level `name:` — what the runs API reports as `workflowName` — or null.
308
+ function workflowNameOf(text) {
309
+ if (!text) return null;
310
+ const m = text.match(/^name:\s*(.+?)\s*$/m);
311
+ if (!m) return null;
312
+ return m[1].replace(/\s+#.*$/, '').replace(/^["']|["']$/g, '').trim() || null;
313
+ }
314
+
268
315
  module.exports = {
269
316
  PRERELEASE_TAG_PROBE,
270
317
  parseWorkflowOn, listField, githubFilterRegex, githubFilterMatches, workflowFiresOnTag,
271
318
  workflowFiresOnBranchPush, workflowsFiringOnBranchPush,
272
319
  isDeployWorkflow, isReleaseTagTemplateCopy, prereleaseTagTriggers,
320
+ workflowDispatchInputs, workflowNameOf,
273
321
  };