@futurelastic/colab-handbook 1.20.3 → 1.20.4-rc.10

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.
@@ -56,7 +56,7 @@ on:
56
56
  # EDIT: on ONE self-hosted agent shared with trunk, go back to trunk-only until
57
57
  # trunk has its own lane — branch runs queue ahead of the one trunk run a merge
58
58
  # waits for (CONVENTIONS.md §7, "Self-hosted runners", #355). GitHub-hosted
59
- # runners, a runner pool, or a trunk-only label picked in `runs-on` on
59
+ # runners, a runner pool, or the `trunk` class picked in `runs-on` on
60
60
  # github.ref all have that capacity; keep '**' there. Trunk-only means the
61
61
  # branches this repo actually has — and never drop `dev` on a Tier A or C repo:
62
62
  # dev is the trunk, so a main-only trigger runs zero checks on the branch you
@@ -123,17 +123,21 @@ jobs:
123
123
  # run whose jobs ALL skip concludes `skipped`, which `colab ship` reads as not-green.
124
124
  # - At this SHA (#418): on a ref's first push (a claim push), a green non-PR run of this
125
125
  # workflow at the same sha means the suite already ran.
126
- # - At this TREE (#493): on a push to trunk, a green push run elsewhere whose commit has the
127
- # byte-identical tree (a squash of a branch that already contained its base) is reused and
128
- # cited in a `tree-already-green` notice. `tree-reuse: off` in .github/project.yml opts out.
129
- # A run that skipped a job (a trunk-only job skips on branches) is never reused (#511), so
130
- # never put a trunk-only job (publish, deploy, release) behind this gate.
126
+ # - At this TREE (#493): on a push to trunk, and on the first push of a batch-landing ref
127
+ # (`ship-batch/**`, #717), a green push run elsewhere whose commit has the byte-identical tree
128
+ # (a squash of a branch that already contained its base) is reused and cited in a
129
+ # `tree-already-green` notice. `tree-reuse: off` in .github/project.yml opts out.
130
+ # A run that skipped a job (a trunk-only job skips on branches) is never reused (#511) — except
131
+ # a job named in TRUNK_ONLY_JOBS below, which sits outside this gate and runs on trunk anyway.
132
+ # So a trunk-only job (publish, deploy, release) never sits behind this gate: put it in a
133
+ # workflow of its own, or keep it here ungated and list it (#717).
134
+ # The rule this keeps: one CI verdict per git tree (CONVENTIONS.md §7, "One verdict per tree").
131
135
  # Any doubt — no run, red, an API error — runs the full suite; this job never fails the run.
132
136
  dedupe:
133
137
  name: Already tested at this sha or tree?
134
138
  # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
135
139
  if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
136
- runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
140
+ runs-on: ubuntu-latest # EDIT: self-hosted → the class of the jobs below, never a host (CONVENTIONS.md §7, "Runner classes"); it needs `gh`.
137
141
  timeout-minutes: 5 # one `gh api` listing, a hung call must not hold the slot. EDIT: the default is 360.
138
142
  permissions:
139
143
  actions: read
@@ -152,15 +156,23 @@ jobs:
152
156
  CREATED: ${{ github.event.created }}
153
157
  REF_NAME: ${{ github.ref_name }}
154
158
  GUARD_NAME: Already tested at this sha or tree? # EDIT: this job's `name:`, if you rename it (#511).
159
+ # EDIT (#717): the `name:` of every job here that is trunk-only (publish, deploy, release) and
160
+ # sits OUTSIDE this gate — its `if:` never reads `needs.dedupe.outputs.tested`, so it runs on
161
+ # trunk whatever this guard decides. Comma-separated, exact names as a run lists them. A cited
162
+ # branch run may have skipped these and is still reused. Never list a suite job or any job
163
+ # behind the gate: it would then be skipped on trunk twice. Empty = #511 unchanged. Simpler
164
+ # still: keep trunk-only jobs in a workflow of their own (CONVENTIONS.md §7, "One verdict per tree").
165
+ TRUNK_ONLY_JOBS: ""
155
166
  run: |
156
167
  tested=false
157
168
  cited=
158
169
  # #511: a cited run is reusable only if it skipped no job but this guard. A job gated on
159
170
  # the trunk ref is `skipped` on every branch push and a skipped job does not fail the
160
- # run, so citing that run would skip the trunk-only job on trunk a second time.
171
+ # run, so citing that run would skip the trunk-only job on trunk a second time — unless
172
+ # the job is named in TRUNK_ONLY_JOBS: it sits outside the gate and runs here anyway (#717).
161
173
  reusable() {
162
174
  if ! SK="$(gh api "repos/$REPO/actions/runs/$1/jobs?per_page=100" \
163
- --jq 'if .total_count > (.jobs | length) then "(more than 100 jobs)" else [.jobs[] | select(.conclusion == "skipped" and .name != env.GUARD_NAME) | .name] | join(", ") end' 2>/dev/null)"; then
175
+ --jq 'if .total_count > (.jobs | length) then "(more than 100 jobs)" else [.jobs[] | select(.conclusion == "skipped" and .name != env.GUARD_NAME) | .name | select(. as $n | any((env.TRUNK_ONLY_JOBS // "") | split(",")[] | gsub("^\\s+|\\s+$"; ""); . == $n) | not)] | join(", ") end' 2>/dev/null)"; then
164
176
  echo "::notice::Could not list the jobs of run $1 — running the full suite (#511)."
165
177
  return 1
166
178
  elif [ -n "$SK" ]; then
@@ -207,13 +219,16 @@ jobs:
207
219
  echo "::notice::gh is not installed on this runner — running the full suite (#418)."
208
220
  elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
209
221
  echo "::notice::Could not read this run's workflow id — running the full suite (#418)."
210
- elif [ "${CREATED:-}" = "false" ]; then
211
- # A non-creating push: trunk tree mode (#493). Every branch below but one runs the suite.
222
+ elif [ "${CREATED:-}" = "false" ] || [[ "$REF_NAME" == ship-batch/* ]]; then
223
+ # Tree mode (#493): a non-creating push to trunk, or the creating push of a batch-landing
224
+ # ref (#717), whose new sha often carries a tree a member branch already passed. Same
225
+ # checks either way; only the trunk check is the ref's own. Every branch below but one
226
+ # runs the suite.
212
227
  if ! DESC="$(gh api "repos/$REPO/contents/.github/project.yml?ref=$SHA" -H 'Accept: application/vnd.github.raw' 2>/dev/null)" || [ -z "$DESC" ]; then
213
228
  echo "::notice::Could not read .github/project.yml at $SHA — running the full suite (#493)."
214
229
  elif grep -Eq '^tree-reuse[[:space:]]*:' <<< "$DESC"; then
215
230
  echo "::notice::tree-reuse is declared in .github/project.yml — running the full suite (#493)."
216
- elif [ "$(printf '%s\n' "$DESC" | sed -nE "s/^trunk:[[:space:]]*[\"']?([A-Za-z0-9._/-]+).*/\\1/p" | head -n 1)" != "$REF_NAME" ]; then
231
+ elif [ "${CREATED:-}" = "false" ] && [ "$(printf '%s\n' "$DESC" | sed -nE "s/^trunk:[[:space:]]*[\"']?([A-Za-z0-9._/-]+).*/\\1/p" | head -n 1)" != "$REF_NAME" ]; then
217
232
  echo "::notice::$REF_NAME is not this repo's trunk — running the full suite (#493)."
218
233
  elif ! OURS="$(gh api "repos/$REPO/git/commits/$SHA" --jq .tree.sha 2>/dev/null)" || [ -z "$OURS" ]; then
219
234
  echo "::notice::Could not read the tree of $SHA — running the full suite (#493)."
@@ -247,13 +262,14 @@ jobs:
247
262
  name: Secret scan (gitleaks)
248
263
  needs: dedupe
249
264
  if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
250
- runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
265
+ runs-on: ubuntu-latest # EDIT: self-hosted → a class, never a host: quick on a branch, trunk on trunk (CONVENTIONS.md §7, "Runner classes").
251
266
  timeout-minutes: 15 # a scan of the checkout. EDIT: the default is 360.
252
267
  steps:
253
268
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
254
269
  with:
255
- # Full history: gitleaks scans commits, not just the working tree, so a
256
- # secret that was committed and later removed is still caught.
270
+ # Full history: the scan's range is computed against trunk (origin/<trunk>..HEAD), and
271
+ # the two ends of that range have to be in the clone. The range itself is narrow — see
272
+ # "gitleaks detect" below (#716).
257
273
  fetch-depth: 0
258
274
  persist-credentials: false
259
275
 
@@ -364,14 +380,46 @@ jobs:
364
380
  fi
365
381
  echo "$dir" >> "$GITHUB_PATH"
366
382
 
383
+ # The scan range (#716): only the commits this run brings, never `git log --all`. A
384
+ # fetch-depth-0 checkout holds every branch and tag, and gitleaks' default range is all of
385
+ # them — so one unshipped branch's finding turned EVERY branch's run red, a trunk cure
386
+ # included, until that branch rewrote its history.
387
+ # - A branch push: the commits not yet on trunk (origin/<trunk>..HEAD).
388
+ # - A trunk push: the pushed range (before..HEAD).
389
+ # - No range to read (a dispatch, a first or forced trunk push, trunk not fetched): HEAD's
390
+ # own history — still never another branch's.
391
+ # Trunk is `trunk:` in .github/project.yml, else the repository's default branch. Every
392
+ # commit trunk's tip can reach is scanned by the heavy lane instead (templates/
393
+ # ci-<stack>-heavy.yml, job `secrets`), which blocks no merge. The step keeps its name.
367
394
  - name: gitleaks detect
368
- run: gitleaks detect --source . --no-banner
395
+ env:
396
+ EVENT: ${{ github.event_name }}
397
+ REF_NAME: ${{ github.ref_name }}
398
+ BEFORE: ${{ github.event.before }}
399
+ DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
400
+ run: |
401
+ trunk="$(sed -nE "s/^trunk:[[:space:]]*[\"']?([A-Za-z0-9._/-]+).*/\\1/p" .github/project.yml 2>/dev/null | head -n 1 || true)"
402
+ trunk="${trunk:-$DEFAULT_BRANCH}"
403
+ commit() { [ -n "$1" ] && git rev-parse --verify -q "$1^{commit}" >/dev/null; }
404
+ if [ -n "$trunk" ] && [ "$REF_NAME" = "$trunk" ]; then
405
+ if [ "$EVENT" = push ] && commit "$BEFORE" && git merge-base --is-ancestor "$BEFORE" HEAD; then
406
+ range="$BEFORE..HEAD"
407
+ else
408
+ range=HEAD
409
+ fi
410
+ elif [ -n "$trunk" ] && commit "refs/remotes/origin/$trunk"; then
411
+ range="refs/remotes/origin/$trunk..HEAD"
412
+ else
413
+ range=HEAD
414
+ fi
415
+ echo "Secret scan range: $range ($(git rev-list --count "$range") commit(s))"
416
+ gitleaks detect --source . --no-banner --log-opts="$range"
369
417
 
370
418
  build:
371
419
  name: Build (Python)
372
420
  needs: dedupe
373
421
  if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
374
- runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
422
+ runs-on: ubuntu-latest # EDIT: self-hosted → a class, never a host: full (quick if it keeps quick's promise) on a branch, trunk on trunk (CONVENTIONS.md §7, "Runner classes").
375
423
  timeout-minutes: 30 # a hung build must not hold the runner for the 360-minute default (#572).
376
424
  # EDIT: NOT a measured fit (#572) — one Python adopter, whose build is a byte-compile (p99
377
425
  # under 1 min). Set it well above YOUR p99 — below it a slow but healthy suite goes red.
@@ -706,7 +754,7 @@ jobs:
706
754
  # # including `dedupe`, which is skipped on every ordinary push (#418). `roundtrip` is `on`
707
755
  # # only once ROUNDTRIP_APPLY (the workflow env, above) is set — skipped until then (#625).
708
756
  # if: ${{ !cancelled() && needs.build.result == 'success' && needs.build.outputs.roundtrip == 'on' }}
709
- # runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
757
+ # runs-on: ubuntu-latest # EDIT: self-hosted → a class, never a host: e2e (service containers) (CONVENTIONS.md §7, "Runner classes").
710
758
  # timeout-minutes: 15 # a hung round-trip must not hold the runner for the 360-minute default (#572).
711
759
  # # EDIT: NOT measured for Python (#572) — ci-node's adopters ran p99 under 4 min. Keep it well above your own p99.
712
760
  # strategy:
@@ -11,6 +11,7 @@ on:
11
11
  jobs:
12
12
  instruction-files:
13
13
  uses: futurelastic/colab-handbook/.github/workflows/instruction-files.yml@main
14
- # No GitHub-hosted minutes (self-hosted-only org)? Pass your runner (#594) — a label or a JSON list:
14
+ # No GitHub-hosted minutes (self-hosted-only org)? Pass your runner (#594) — a label or a JSON list,
15
+ # naming a job class, never a host (CONVENTIONS.md §7, "Runner classes"):
15
16
  # with:
16
- # runs-on: '["self-hosted","linux"]'
17
+ # runs-on: '["self-hosted","quick"]'
@@ -32,6 +32,9 @@
32
32
  // DOWNLOADS_KEY_FILE the private key file the workflow wrote from DOWNLOADS_SSH_KEY
33
33
  // DOWNLOADS_KNOWN_HOSTS_FILE the known-hosts file the workflow wrote from DOWNLOADS_SSH_KNOWN_HOSTS
34
34
  // DOWNLOADS_RESERVED names the site keeps for itself, refused as an app slug (space/comma list)
35
+ // DOWNLOADS_READ_HEADERS optional (#714): a site that requires sign-in for every file. One `Name: value`
36
+ // HTTP header per line, sent on every read of the site (the requires check, the
37
+ // read-back); never printed. Unset, the site is read with no credential
35
38
  //
36
39
  // THE APPS IT REQUIRES (#653) come from manifest.json's optional `requires`: [{"slug": "<app>", "min": "X.Y.Z"}],
37
40
  // other apps on the same site that its installers install first. Before anything is sent, every slug must have a final
@@ -570,6 +573,29 @@ function runRsync({ rsync, sshArgs, args, log }) {
570
573
  if (r.status !== 0) throw new Error(`rsync failed (${r.status ?? r.signal}): ${(r.stderr || r.stdout || '').trim()}`)
571
574
  }
572
575
 
576
+ /**
577
+ * DOWNLOADS_READ_HEADERS (#714) as a headers object: one `Name: value` per line, blank lines ignored. A line that is not
578
+ * a header throws naming its line number only — the value is a credential and is never echoed.
579
+ */
580
+ export function readHeaders(text) {
581
+ const out = {}
582
+ const lines = String(text ?? '').split(/\r?\n/)
583
+ for (let i = 0; i < lines.length; i++) {
584
+ const line = lines[i].trim()
585
+ if (!line) continue
586
+ const m = /^([A-Za-z0-9!#$%&'*+.^_`|~-]+):[ \t]*(\S.*)$/.exec(line)
587
+ if (!m) throw new Error(`DOWNLOADS_READ_HEADERS: line ${i + 1} is not a "Name: value" header (the value is not shown); nothing was published`)
588
+ out[m[1].toLowerCase()] = m[2]
589
+ }
590
+ return out
591
+ }
592
+
593
+ /** `fetchImpl` with `headers` added to every request — how every read of the site carries DOWNLOADS_READ_HEADERS. */
594
+ export function withHeaders(fetchImpl, headers) {
595
+ if (!Object.keys(headers).length) return fetchImpl
596
+ return (url, init = {}) => fetchImpl(url, { ...init, headers: { ...headers, ...(init.headers ?? {}) } })
597
+ }
598
+
573
599
  async function get(fetchImpl, url, attempts = 3) {
574
600
  let last
575
601
  for (let i = 0; i < attempts; i++) {
@@ -589,6 +615,8 @@ async function get(fetchImpl, url, attempts = 3) {
589
615
  async function readBytes(fetchImpl, url) {
590
616
  const res = await get(fetchImpl, url)
591
617
  if (res.status === 404) return null
618
+ if (res.status === 401 || res.status === 403)
619
+ throw new Error(`${url} answered ${res.status} — the site requires sign-in: set or check the DOWNLOADS_READ_HEADERS secret (docs/downloads.md)`)
592
620
  if (!res.ok) throw new Error(`${url} answered ${res.status}`)
593
621
  return Buffer.from(await res.arrayBuffer())
594
622
  }
@@ -826,12 +854,13 @@ async function main(argv, env) {
826
854
  const dryRun = rest.includes('--dry-run')
827
855
  const assetsDir = resolve(rest.filter((a) => !a.startsWith('--'))[0] ?? '')
828
856
  const baseUrl = env.DOWNLOADS_URL
857
+ const fetchImpl = withHeaders(fetch, readHeaders(env.DOWNLOADS_READ_HEADERS))
829
858
  const outDir = mkdtempSync(join(tmpdir(), 'publish-downloads-'))
830
859
  const staged = await stage({ tag, assetsDir, outDir, baseUrl, root, config, manifest })
831
860
  console.log(`Staged ${config.app} ${staged.version}: ${[...Object.keys(staged.files), ...staged.images].join(', ')}`)
832
861
  await assertResolves(baseUrl)
833
862
  const target = dryRun ? { dest: 'DRY-RUN:', sshArgs: undefined } : sshCommand(env)
834
- const result = await publish({ outDir, app: config.app, ...target, baseUrl, dryRun })
863
+ const result = await publish({ outDir, app: config.app, ...target, baseUrl, dryRun, fetchImpl })
835
864
  if (dryRun) console.log(`Dry run of ${result.version} done — nothing was uploaded`)
836
865
  else
837
866
  console.log(
@@ -58,6 +58,10 @@
58
58
  # repo set up before the rename keeps publishing; rename the secret when convenient.
59
59
  # variable DOWNLOADS_URL — the site's root address (https). The script appends /<app>; no host is ever
60
60
  # written in the repository.
61
+ # secret DOWNLOADS_READ_HEADERS — optional (#714), only for a site that requires sign-in for every file: one
62
+ # `Name: value` HTTP header per line (e.g. `Authorization: Bearer …`, or an access proxy's two
63
+ # service-token headers), sent on every read of the site. The same secret release-auto.yml's downloads
64
+ # sweep reads latest.json with. Unset, the site is read with no credential.
61
65
  #
62
66
  # THIS FILE DOES NOT CHANGE YOUR REPO'S EXPOSURE (OR LEGACY TIER): it publishes files a final already made.
63
67
  name: Publish downloads
@@ -174,6 +178,7 @@ jobs:
174
178
  - name: Publish
175
179
  env:
176
180
  ASSETS: ${{ steps.assets.outputs.dir }}
181
+ DOWNLOADS_READ_HEADERS: ${{ secrets.DOWNLOADS_READ_HEADERS }}
177
182
  DOWNLOADS_KEY_FILE: ${{ runner.temp }}/downloads-ssh/key
178
183
  DOWNLOADS_KNOWN_HOSTS_FILE: ${{ runner.temp }}/downloads-ssh/known_hosts
179
184
  run: |
@@ -145,7 +145,11 @@
145
145
  # one (a complete version sends nothing), and when the site cannot be read from this job's runner —
146
146
  # a warning then, never a red run; the next daily run retries. The site is read at
147
147
  # vars.DOWNLOADS_URL/<downloads.app>/latest.json FROM THE RELEASE JOB'S RUNNER: a site only a private
148
- # network reaches needs the release job on a runner inside it (RUNNERS, below). The wiring:
148
+ # network reaches needs the release job on a runner inside it (RUNNERS, below). A site that requires
149
+ # sign-in (#714) is read with the optional DOWNLOADS_READ_HEADERS secret — one `Name: value` header
150
+ # per line, the same secret publish-downloads.yml reads with; a 401/403 is not the transient warning
151
+ # but an `::error title=Downloads not shipped::` plus a failing `downloads/<app>` commit status on
152
+ # the final, naming it (still exit 0, for the reason "A REFUSAL IS NOT A FAILURE" gives). The wiring:
149
153
  #
150
154
  # build-macos: # EDIT: one job per platform you build
151
155
  # needs: release
@@ -217,9 +221,11 @@
217
221
  # owner's billing fails GitHub refuses a hosted job before it starts: main goes red, every landing
218
222
  # is refused until a human steps in — measured twice in a row on one adopting repo, where this was
219
223
  # the only workflow on main still on hosted runners. So:
220
- # private / internal repo `release`, `npm-record` (and `deploy`, if you enable it) run on the
221
- # SAME self-hosted label your ci.yml's trunk jobs use. The runner needs
222
- # git, node, gh and jq on its PATH (GitHub-hosted images have all four).
224
+ # private / internal repo `release` and `npm-record` run on the trunk class, `[self-hosted,
225
+ # trunk]` — the class your ci.yml's trunk jobs use (CONVENTIONS.md §7,
226
+ # "Runner classes"); `deploy`, if you enable it, on its own restricted
227
+ # deploy label. The runner needs git, node, gh and jq on its PATH
228
+ # (GitHub-hosted images have all four).
223
229
  # public repo `ubuntu-latest` is fine — hosted minutes are free there.
224
230
  # the `npm` job GitHub-hosted on every repo: npm trusted publishing requires it. It only
225
231
  # runs on a public repo (a private one is refused outright, #432), so it
@@ -355,13 +361,14 @@ jobs:
355
361
  # the whole run as `skipped` at that main sha, and `colab ship` reads any finished run that is
356
362
  # neither success nor cancelled as "not green". Re-run CI green on that sha and the skipped
357
363
  # Release (auto) row would still sit beside it, refusing every ship until main moves.
358
- # EDIT: PRIVATE repo → your ci.yml's self-hosted trunk label, e.g. [self-hosted, linux]
364
+ # EDIT: PRIVATE repo → the trunk class, [self-hosted, trunk] — a class, never a host
359
365
  # (RUNNERS, above). ubuntu-latest only on a public repo.
360
366
  runs-on: ubuntu-latest
361
367
  permissions:
362
368
  contents: write # push the tags (and, with promotion: main-loop, the promotion), publish the GitHub Release
363
369
  issues: write # finalize opens / comments on / closes the "release: vX.Y.Z" tracking issue
364
370
  actions: write # read the runs at a commit (ci-green, full-suite, trunk-green); dispatch CI after a promotion
371
+ statuses: write # the downloads sweep marks a final its site refused to read (401/403) failed (#714)
365
372
  # What the npm job below needs (#433) — empty / publish=false unless this run tagged something (or
366
373
  # the daily sweep found a final npm lacks, #612) AND .github/project.yml opts in with release.npm.
367
374
  outputs:
@@ -823,7 +830,8 @@ jobs:
823
830
  # when the site's latest.json does not name it yet (absent → never published, older → behind) — a
824
831
  # final a person tagged (early, #627, or `final: human`) is never tagged by a run, so without this
825
832
  # sweep it never reached the site. The site at that version or newer, no `downloads:` block, no
826
- # DOWNLOADS_URL, or an unreadable site: nothing is handed on, and the step stays green.
833
+ # DOWNLOADS_URL, or an unreadable site: nothing is handed on, and the step stays green — a 401/403
834
+ # (#714) too, but as an error annotation and a failing commit status on the final, not a warning.
827
835
  - name: Read the downloads target [publish]
828
836
  id: downloads-target
829
837
  if: env.DRY_RUN != 'true' && (steps.cut.outputs.tag != '' || steps.finalize.outputs.tag != '' || (github.event_name == 'schedule' && env.RETRY_RUN != 'true') || github.event_name == 'workflow_dispatch')
@@ -831,6 +839,8 @@ jobs:
831
839
  TAGS: ${{ steps.cut.outputs.tag }} ${{ steps.finalize.outputs.tag }}
832
840
  SWEEP: ${{ (github.event_name == 'schedule' && env.RETRY_RUN != 'true') || github.event_name == 'workflow_dispatch' }}
833
841
  DOWNLOADS_URL: ${{ vars.DOWNLOADS_URL }}
842
+ # #714: a site that requires sign-in for every file. Optional; unset, the read sends no credential.
843
+ DOWNLOADS_READ_HEADERS: ${{ secrets.DOWNLOADS_READ_HEADERS }}
834
844
  run: |
835
845
  set -uo pipefail
836
846
  # The `downloads:` block's `app:` — the same key publish-downloads.mjs reads. No block, no target.
@@ -871,7 +881,20 @@ jobs:
871
881
  { echo "tag=$FINAL"; echo "swept=$FINAL"; } >> "$GITHUB_OUTPUT"
872
882
  echo "downloads sweep: $1 — handing $FINAL to the build and downloads jobs (#669)" | tee -a "$GITHUB_STEP_SUMMARY"
873
883
  }
874
- if BODY="$(retry_transient curl -fsSL "$URL" 2> "$ERR")"; then
884
+ # #714: DOWNLOADS_READ_HEADERS — one `Name: value` header per line (docs/downloads.md, "A site
885
+ # that requires sign-in") — goes to curl from a file, never on its command line, and is never printed.
886
+ AUTH=()
887
+ if [ -n "${DOWNLOADS_READ_HEADERS:-}" ]; then
888
+ HDRS="$RUNNER_TEMP/downloads-read-headers"
889
+ trap 'rm -f "$HDRS"' EXIT
890
+ ( umask 077; printf '%s\n' "$DOWNLOADS_READ_HEADERS" | tr -d '\r' | sed '/^[[:space:]]*$/d' > "$HDRS" )
891
+ if grep -qvE '^[A-Za-z0-9!#$%&*+.^_`|~-]+:[[:space:]]*[^[:space:]]' "$HDRS"; then
892
+ echo "::error title=Downloads not shipped::the DOWNLOADS_READ_HEADERS secret has a line that is not a 'Name: value' header (the value is not shown) — $FINAL is not handed on"
893
+ exit 0 # a standing refusal, not a red run (the 401/403 branch below says why)
894
+ fi
895
+ AUTH=(-H "@$HDRS")
896
+ fi
897
+ if BODY="$(retry_transient curl -fsSL ${AUTH[@]+"${AUTH[@]}"} "$URL" 2> "$ERR")"; then
875
898
  SITE="$(jq -r '.version // empty' <<< "$BODY" 2> /dev/null || true)"
876
899
  if [ -z "$SITE" ]; then
877
900
  echo "::warning::downloads sweep: $URL names no version — $FINAL is not handed on in this run"
@@ -884,6 +907,29 @@ jobs:
884
907
  fi
885
908
  elif grep -q 'error: 404' "$ERR"; then
886
909
  hand_on "$FINAL is final on main and the site has no latest.json for $APP"
910
+ elif CODE="$(grep -oE 'error: 40[13]' "$ERR" | head -n 1 | grep -oE '40[13]')"; then
911
+ # #714: 401/403 is a refusal no later run clears by itself, so it is not the warning below: a
912
+ # final whose files would never ship. Visible, but exit 0 — the #467 rule (header, "A REFUSAL
913
+ # IS NOT A FAILURE"): a red run would make main's head not-green and refuse the very ship
914
+ # that fixes it. So: an error annotation, a summary banner, and a failing commit status
915
+ # `downloads/<app>` on the final's own commit. The next daily run re-reads and re-posts.
916
+ if [ -n "${DOWNLOADS_READ_HEADERS:-}" ]; then
917
+ WHY="the site refused the DOWNLOADS_READ_HEADERS credential — check or replace that secret"
918
+ else
919
+ WHY="the site requires sign-in and no DOWNLOADS_READ_HEADERS secret is set on this repo"
920
+ fi
921
+ MSG="$URL answered $CODE, so $FINAL is final on main but its files never ship: $WHY (docs/downloads.md, \"A site that requires sign-in\")"
922
+ echo "::error title=Downloads not shipped::downloads sweep: $MSG"
923
+ { echo "#### ⚠ Downloads not shipped — $FINAL"; echo; echo "$MSG"; } >> "$GITHUB_STEP_SUMMARY"
924
+ SHA="$(git rev-list -n 1 "$FINAL")"
925
+ # github.com only: a forge reads CI from commit statuses (#681), where a failing one would be the
926
+ # red main this branch exists to avoid. There the annotation stands alone.
927
+ if [ "${GITHUB_SERVER_URL:-https://github.com}" != "https://github.com" ]; then
928
+ :
929
+ elif ! retry_transient gh api --silent -X POST "repos/$GITHUB_REPOSITORY/statuses/$SHA" -f state=failure \
930
+ -f context="downloads/$APP" -f description="$FINAL not on the site: latest.json answered $CODE" > /dev/null; then
931
+ echo "::warning::downloads sweep: could not post the failing downloads/$APP status on $FINAL — the annotation above stands"
932
+ fi
887
933
  else
888
934
  echo "::warning::downloads sweep: could not read $URL from this runner ($(tail -n 1 "$ERR" 2> /dev/null)) — $FINAL is not handed on in this run; the next daily run retries"
889
935
  fi
@@ -107,7 +107,7 @@ jobs:
107
107
  release:
108
108
  name: Publish release
109
109
  needs: heavy
110
- runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
110
+ runs-on: ubuntu-latest # EDIT: self-hosted → the trunk class, never a host (CONVENTIONS.md §7, "Runner classes").
111
111
  permissions:
112
112
  # Required to create the release. Nothing else is needed — keep it minimal.
113
113
  contents: write
package/tools/colab CHANGED
@@ -1358,7 +1358,11 @@ Refuses, naming each failed condition (all are reported, not just the first):
1358
1358
  format is NAMED in the detail, and the release notes still owe the §6
1359
1359
  judgement on the diff. When nothing was read — no default layout and no
1360
1360
  \`migrations:\` declared, or a declared migration in another format changed —
1361
- the row prints · "not checked" (#670): it refuses nothing, and it is never a ✓
1361
+ the row prints · "not checked" (#670): it refuses nothing, and it is never a ✓.
1362
+ An SQLite table rebuild (CREATE t_new; INSERT INTO t_new SELECT … FROM t; DROP
1363
+ TABLE t; ALTER TABLE t_new RENAME TO t — every row copied, no WHERE/DISTINCT/
1364
+ OR IGNORE) is additive (#709); copied by an explicit column list it prints ·
1365
+ "not checked", since whether the list names every old column is not in the file
1362
1366
  switch-dependencies a colab:switch marker is malformed, or a finished switch needs one that is not
1363
1367
  manifest-version the tag does not equal the version a manifest declares (VERSION, package.json,
1364
1368
  Cargo.toml [package], else [workspace.package] (#620), pyproject.toml
@@ -1414,7 +1418,9 @@ Route deploy-tag-fast (#446) — a deploy: tag repo with the operator's grant an
1414
1418
  release-hold an open issue carries the release-hold label (a human veto)
1415
1419
  migration-grant a migration since the last final with no grant on the version's tracking
1416
1420
  issue — refused; a non-dry run opens "release: vX.Y.Z" if needed and posts the
1417
- one human command (COLAB_HUMAN=1 colab migration-grant <N> --branch vX.Y.Z)
1421
+ one human command (COLAB_HUMAN=1 colab migration-grant <N> --branch vX.Y.Z).
1422
+ That grant is also the person's decision a destructive schema-additive finding
1423
+ needs on this route (#709): with it live, the row passes and names the grant
1418
1424
 
1419
1425
  The bump (without --auto) is release-status's semverSuggestion since the last final tag (candidates skipped): fix ->
1420
1426
  patch, feat -> minor; a breaking change is a minor pre-1.0 and a refusal from 1.0 on.
@@ -1938,7 +1944,7 @@ function cmdReleaseCut(argv) {
1938
1944
  if (num) {
1939
1945
  handoff = releaseCut.migrationHandoff(num, verdict.version);
1940
1946
  commentOnce(repoAbs, num, { state: 'migration-handoff', version: verdict.version },
1941
- `**${verdict.version} carries a database migration**, and route deploy-tag-fast never deploys an ungranted one. The one command, run by a human, lets it ride — the next green run then tags and deploys it:\n\n\`\`\`sh\n${handoff}\n\`\`\``);
1947
+ `**${verdict.version} carries a database migration**, and route deploy-tag-fast never deploys an ungranted one. The one command, run by a human, lets it ride — the next green run then tags and deploys it:\n\n\`\`\`sh\n${handoff}\n\`\`\`${verdict.refusals.some((c) => c.condition === 'schema-additive') ? '\n\nThe schema check also read a **destructive** change (`schema-additive` in the run\'s output). On this route the same grant is the person\'s decision that lets it ride (#709) — read the migration before granting.' : ''}`);
1942
1948
  }
1943
1949
  }
1944
1950
  }
@@ -11961,13 +11967,13 @@ function descriptorHolds(doc) {
11961
11967
  * caller can build the --dry --json `ciGrant`/`ciCure` payloads from the SAME verdicts the prose
11962
11968
  * detail string was built from — see ciGrantPayload/ciCurePayload, below.
11963
11969
  */
11964
- function shipCiCheck(repoAbs, gh, target, trunk, grantThunk, cureThunk, branch = null) {
11970
+ function shipCiCheck(repoAbs, gh, target, trunk, grantThunk, cureThunk, branch = null, docsOnlyThunk = null) {
11965
11971
  const name = `${target === trunk ? 'trunk' : 'line'} CI green`;
11966
11972
  const r = readCiVerdict(repoAbs, gh, target, trunk);
11967
11973
  // #678: on a forge the engine map names, the verdict is final — the #482 no-workflow door counts
11968
11974
  // `.github/workflows` and reads the branch through gh, neither of which describes a forge's CI.
11969
11975
  if (forgeCi(repoAbs)) return { name, ...r.verdict, grantVerdict: null, cureVerdict: null };
11970
- const nw = noWorkflowTrunkDoor(repoAbs, r, target, trunk, branch);
11976
+ const nw = noWorkflowTrunkDoor(repoAbs, r, target, trunk, branch, docsOnlyThunk);
11971
11977
  if (nw) return { name, ...nw, grantVerdict: null, cureVerdict: null };
11972
11978
  if (r.final) return { name, ...r.verdict, grantVerdict: null, cureVerdict: null };
11973
11979
  return applyRedTrunkExemptions({ name, ...r.verdict }, target, trunk, r.run.sha, grantThunk, cureThunk);
@@ -11985,14 +11991,27 @@ function shipCiCheck(repoAbs, gh, target, trunk, grantThunk, cureThunk, branch =
11985
11991
  * real gap (CI not wired, or never started) and still blocks exactly as before. Runs ahead of the
11986
11992
  * #413 grace window too: a run that can never exist is not worth waiting ten minutes for. Returns null when
11987
11993
  * the door does not apply, or a `{ok, class, detail}` verdict when it does.
11994
+ *
11995
+ * #711: a DOCS-ONLY candidate (#606's measurement, secret check included — `docsOnlyThunk` returns
11996
+ * shipDocsOnlyCi's shape, called lazily, only once the trunk is known to have no workflow) passes here
11997
+ * without a run of its own: #606 already ruled that run not required, and a docs-only branch on a
11998
+ * no-workflow trunk can never draw one. Only for a branch on the remote (the same precondition as the
11999
+ * branch-run read). A failed secret check, or a branch that is not docs-only, falls through to the
12000
+ * branch's own run as before.
11988
12001
  */
11989
- function noWorkflowTrunkDoor(repoAbs, r, target, trunk, branch) {
12002
+ function noWorkflowTrunkDoor(repoAbs, r, target, trunk, branch, docsOnlyThunk = null) {
11990
12003
  if (target !== trunk || !branch || !r.run || r.run.status !== 'none' || !r.run.sha || r.verdict.ok) return null;
11991
12004
  if (trunkWorkflowFiles(repoAbs, r.run.sha) !== 0) return null;
11992
12005
  const at = `${trunk}@${shortSha(r.run.sha)}`;
11993
12006
  const own = git.ghRunForSha(repoAbs, branch);
11994
12007
  // Branch not on the remote, or its runs unreadable: nothing to decide with — the prior verdict stands.
12008
+ // #711 keeps this precondition: the docs-only pass below is for a pushed candidate only.
11995
12009
  if (!own) return null;
12010
+ const dc = docsOnlyThunk ? docsOnlyThunk() : null;
12011
+ if (dc && dc.applies && dc.scan && dc.scan.ok) {
12012
+ return { ok: true, class: null,
12013
+ detail: `none — ${at} has no repo-owned workflow, so nothing there can be red (#482); no workflow on trunk; docs-only branch, CI not required (${dc.files} files, secret check clean — #606)${excludedRunsNote(r.run)}` };
12014
+ }
11996
12015
  const ownAt = own.sha ? `${branch}@${shortSha(own.sha)}` : branch;
11997
12016
  if (own && own.status === 'completed' && own.conclusion === 'success') {
11998
12017
  const n = own.runCount == null ? 1 : own.runCount;
@@ -12035,6 +12054,37 @@ function pushVerifiedWorkflowsAt(repoAbs, sha) {
12035
12054
  return names;
12036
12055
  }
12037
12056
 
12057
+ /**
12058
+ * #723: the workflows that SHOULD have a push run at `sha`, the head of `branch` — read from the
12059
+ * workflow files at that sha, the head commit's message (a skip directive), the repo's policy and the
12060
+ * workflows API's state (verify-runs.js `expectedWorkflows`). Null when the tree cannot be read (the
12061
+ * commit is not local and one fetch does not bring it): no expected set, so the runs that exist
12062
+ * decide, as before. GitHub only — a forge's commit statuses carry no workflow identity to match.
12063
+ */
12064
+ function expectedWorkflowsAt(repoAbs, sha, branch) {
12065
+ if (!sha || !branch) return null;
12066
+ if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) {
12067
+ git.git(['fetch', '--quiet', git.remoteFor(repoAbs) || 'origin', sha], repoAbs);
12068
+ if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) return null;
12069
+ }
12070
+ const ls = git.git(['ls-tree', '--name-only', `${sha}:.github/workflows`], repoAbs);
12071
+ const defs = [];
12072
+ if (ls.ok) {
12073
+ for (const f of ls.stdout.split('\n').map((x) => x.trim()).filter((x) => /\.ya?ml$/.test(x))) {
12074
+ const rel = `.github/workflows/${f}`;
12075
+ const show = git.git(['show', `${sha}:${rel}`], repoAbs);
12076
+ if (show.ok) defs.push({ path: rel, text: show.stdout });
12077
+ }
12078
+ }
12079
+ if (!defs.length) return { expected: [], skipDirective: false };
12080
+ const msg = git.git(['log', '-1', '--format=%B', sha], repoAbs);
12081
+ const headMessage = msg.ok ? msg.stdout : null;
12082
+ if (verifyRuns.skipsWorkflows(headMessage)) return { expected: [], skipDirective: true }; // no API call spent
12083
+ return verifyRuns.expectedWorkflows({
12084
+ defs, branch, policy: verifyRuns.parsePolicy(projectDoc(repoAbs)), states: git.ghWorkflowStates(repoAbs), headMessage,
12085
+ });
12086
+ }
12087
+
12038
12088
  /** Number of workflow files in `.github/workflows` at `sha`, or null when the tree cannot be read. */
12039
12089
  function trunkWorkflowFiles(repoAbs, sha) {
12040
12090
  if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) return null;
@@ -12460,7 +12510,9 @@ function shipStaleBaseCheck(repoAbs, gh, base, branch) {
12460
12510
  // head row below never refuses on a run that policy sets aside (a release lane, an ignored workflow).
12461
12511
  const rows = git.ghRunsForCommit(repoAbs, branch, headSha);
12462
12512
  run = git.summarizeRunsForCommit(rows, headSha);
12463
- verifiedRun = git.summarizeRunsForCommit(rows, headSha, { verifying: verifyingPolicy(repoAbs), finishedRed: true });
12513
+ // #723: the workflows that should have fired at the head — one with no run there holds the head row.
12514
+ const exp = rows ? expectedWorkflowsAt(repoAbs, headSha, branch) : null;
12515
+ verifiedRun = git.summarizeRunsForCommit(rows, headSha, { verifying: verifyingPolicy(repoAbs), finishedRed: true, expected: exp ? exp.expected : [] });
12464
12516
  }
12465
12517
  // #606: `run`/`headSha` are additive — the docs-only row reads whether that run finished red.
12466
12518
  // #682: on a forge, `headCi` is the branch head's own CI verdict (green / red / pending), its own
@@ -13200,7 +13252,8 @@ function cmdShipDryJson(opts) {
13200
13252
  const gh = isGhUsable(repoAbs);
13201
13253
  const ciResultJson = shipCiCheck(repoAbs, gh, target, trunk,
13202
13254
  (redSha) => shipCiGrants(repoAbs, gh, sess.issues, sess.branch, trunk, redSha),
13203
- (redSha) => shipCiCure(repoAbs, gh, target, trunk, redSha, sess.branch), sess.branch);
13255
+ (redSha) => shipCiCure(repoAbs, gh, target, trunk, redSha, sess.branch), sess.branch,
13256
+ () => shipDocsOnlyCi(repoAbs, doc, target, sess.branch)); // #711: the #482 door learns the #606 measurement
13204
13257
  ciGrantPayloadVal = ciGrantPayload(ciResultJson);
13205
13258
  ciCurePayloadVal = ciCurePayload(ciResultJson);
13206
13259
  checks.push({ name: ciResultJson.name, ok: ciResultJson.ok, class: ciResultJson.class, detail: ciResultJson.detail });
@@ -13494,8 +13547,9 @@ function shipMode(repoAbs, target, branch, commits) {
13494
13547
  * this ship actually closed, read its NATIVE parent and let lib/container-close.js decide; close
13495
13548
  * the parent with an evidence comment only on `close`, then ask the same question of ITS parent
13496
13549
  * (an epic of epics empties from the bottom up). Every other verdict leaves the parent exactly as
13497
- * it is; the ones a human should see (`not-container`, `unfiled-items`, `unknown`) are printed as
13498
- * findings. Best-effort like every post-merge write: a failure here warns, never fails the ship —
13550
+ * it is; the ones a human should see (`not-container`, `unfiled-items`, `done-when`, `unknown`)
13551
+ * are printed as findings. `done-when` (#713) also gets a one-line proposal comment on the epic —
13552
+ * every filed child is closed, but the body's `Done when` acceptance is the coordinator's to read. Best-effort like every post-merge write: a failure here warns, never fails the ship —
13499
13553
  * the merge already landed. A lagging `subIssuesSummary` reads as `children-open` and is caught by
13500
13554
  * the next ship of a sibling or by code-sweep §5, never by guessing.
13501
13555
  */
@@ -13520,6 +13574,10 @@ function shipCloseSpentContainers(repoAbs, closedIssues, { sha, target } = {}) {
13520
13574
  if (c.verdict !== 'close') {
13521
13575
  const finding = containerClose.containerFinding({ ...c, number: c.number === null ? pnum : c.number });
13522
13576
  if (finding) warn(`container ${finding}`);
13577
+ if (c.verdict === 'done-when') {
13578
+ const pc = git.ghIssueComment(repoAbs, pnum, containerClose.containerProposalComment({ child, sha, total: c.total, target }));
13579
+ if (!pc.ok) warnDeferred(`could not post the done-when proposal on #${pnum} — it stays open either way`);
13580
+ }
13523
13581
  break;
13524
13582
  }
13525
13583
  const body = containerClose.containerCloseComment({ child, sha, total: c.total, target });
@@ -14510,7 +14568,8 @@ function cmdShip(argv) {
14510
14568
  // ordinary green-trunk ship makes zero extra `gh` reads for a door nobody needs.
14511
14569
  const ciResult = shipCiCheck(repoAbs, gh, target, trunk,
14512
14570
  (redSha) => shipCiGrants(repoAbs, gh, sess.issues, sess.branch, trunk, redSha),
14513
- (redSha) => shipCiCure(repoAbs, gh, target, trunk, redSha, sess.branch), sess.branch);
14571
+ (redSha) => shipCiCure(repoAbs, gh, target, trunk, redSha, sess.branch), sess.branch,
14572
+ () => shipDocsOnlyCi(repoAbs, doc, target, sess.branch)); // #711: the #482 door learns the #606 measurement
14514
14573
  const ciOk = ciResult.ok;
14515
14574
  checks.push([ciResult.ok ? '✓' : '✗', ciResult.name, ciResult.detail]);
14516
14575
 
@@ -15052,7 +15111,8 @@ function cmdShip(argv) {
15052
15111
  if (gh || forgeCi(repoAbs)) { // #678: a forge's CI is re-read at B1 exactly as GitHub's is
15053
15112
  const measureB1 = () => shipCiCheck(repoAbs, gh, target, trunk,
15054
15113
  (redSha) => shipCiGrants(repoAbs, gh, sess.issues, sess.branch, trunk, redSha),
15055
- (redSha) => shipCiCure(repoAbs, gh, target, trunk, redSha, sess.branch), sess.branch);
15114
+ (redSha) => shipCiCure(repoAbs, gh, target, trunk, redSha, sess.branch), sess.branch,
15115
+ () => shipDocsOnlyCi(repoAbs, doc, target, sess.branch)); // #711, same door as the table row
15056
15116
  let ciResultB1 = measureB1();
15057
15117
  // #538: the table admitted this branch through a door (cure or grant) at red sha X, and B1 —
15058
15118
  // seconds later, at the SAME red sha — refused. Nothing the door judges moved (trunk's head is
@@ -16836,6 +16896,15 @@ Exit codes — branch on these, never on the text:
16836
16896
  4 RATE_LIMITED GitHub refused for quota (403/429) — the wait ENDS, it does not retry
16837
16897
  5 UNKNOWN a read failed or returned a state it cannot classify
16838
16898
  6 ALREADY_WAITING another live ci-wait on this checkout holds the same run/sha
16899
+ 7 NO_RUN --sha with --branch: the deadline passed and a workflow whose definition at the
16900
+ head fires on a push to that branch still had NO run there (#723). The runs that
16901
+ do exist never stand in for it, so such a head is pending, never GREEN. The
16902
+ output names it (\`no-run:<workflow>\`) and how to get it a run — a hint only
16903
+
16904
+ Expected at a branch head (#723): a workflow file at the head sha triggered by \`push\`, whose
16905
+ branch filters match the branch, with no \`paths\`/\`paths-ignore\` filter, in ship-gate-workflows
16906
+ when declared, not in ship-ignore-workflows, and not disabled. None when the head commit carries a
16907
+ skip directive ([skip ci] …). Any doubt (an unreadable filter, an unread tree) means not expected.
16839
16908
 
16840
16909
  On a remote the machine config's \`forges\` names as Forgejo (#678, #682), --sha reads the commit's
16841
16910
  combined status instead — no gh call, no conditional request; a status has no run id, so <run-id>
@@ -16843,7 +16912,7 @@ is a usage error there. RED and --json name the contexts that are not green (\`n
16843
16912
 
16844
16913
  It prints the wait it did: outcome, elapsed time, polls, and how many were 304s.
16845
16914
  --json { outcome, exit, target, polls, notModified, forced, waitedSec, deadlineSec, deadlineBasis,
16846
- detail, status, conclusion, url, notGreen? }`;
16915
+ detail, status, conclusion, url, notGreen?, missing?, hint? }`;
16847
16916
 
16848
16917
  function cmdCiWait(argv) {
16849
16918
  const opts = parseArgs(argv, {
@@ -16911,6 +16980,10 @@ function cmdCiWait(argv) {
16911
16980
  }
16912
16981
 
16913
16982
  const verifyPolicy = verifyingPolicy(repoAbs);
16983
+ // #723: on a branch head, the workflows that should have a run there — read once, before the loop. A
16984
+ // missing one holds green as pending and ends the wait NO_RUN (exit 7) at the deadline.
16985
+ const expectedSet = !fc && !runId && opts.branch ? expectedWorkflowsAt(repoAbs, opts.sha, opts.branch) : null;
16986
+ const expected = expectedSet ? expectedSet.expected : [];
16914
16987
  // #681: inside a Forgejo Actions run (the release workflow waiting on CI at its own sha) the calling
16915
16988
  // workflow's own contexts are dropped — a run never waits on itself (#425's rule; a no-op elsewhere).
16916
16989
  const poll = fc ? () => ciWait.forgePoll(fc.ciVerdict(opts.sha, { branch: opts.branch || null, rowsFilter: (rows) => releaseCut.withoutOwnWorkflow(rows) }), fc.kind) : (etag) => {
@@ -16933,7 +17006,7 @@ function cmdCiWait(argv) {
16933
17006
  }
16934
17007
  // #503: the same verifying-runs policy ship reads — a wait on trunk's head ends when the CI
16935
17008
  // that verifies the code ends, not when the post-CI release run does.
16936
- summary = git.summarizeRunsForCommit(rows, opts.sha, { verifying: verifyPolicy });
17009
+ summary = git.summarizeRunsForCommit(rows, opts.sha, { verifying: verifyPolicy, expected });
16937
17010
  const pick = rows.find((x) => x.databaseId === summary.databaseId);
16938
17011
  summary = { ...summary, url: pick ? pick.url : null };
16939
17012
  }
@@ -16958,13 +17031,14 @@ function cmdCiWait(argv) {
16958
17031
  status: s.status || null, conclusion: s.conclusion || null, url: s.url || null,
16959
17032
  ...(Array.isArray(s.setAside) && s.setAside.length ? { setAside: s.setAside } : {}),
16960
17033
  ...(Array.isArray(s.dispatchCounted) && s.dispatchCounted.length ? { dispatchCounted: s.dispatchCounted } : {}),
17034
+ ...(Array.isArray(s.missing) && s.missing.length ? { missing: s.missing, hint: verifyRuns.missingHint(s.missing, opts.branch) } : {}), // #723
16961
17035
  ...(s.readVia ? { readVia: s.readVia } : {}), // #654: the verdict names how it was read
16962
17036
  ...(Array.isArray(s.notGreen) && s.notGreen.length ? { notGreen: s.notGreen } : {}), // #682: forge contexts not green
16963
17037
  };
16964
17038
  if (opts.json) print(JSON.stringify(out, null, 2));
16965
17039
  else {
16966
17040
  print(`${res.outcome} ${target} — waited ${ciWait.fmtDuration(res.waitedMs)}, ${res.polls} poll(s), ${res.notModified} of them 304` +
16967
- `${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}${verifyRuns.setAsideNote(s.setAside)}${verifyRuns.dispatchCountedNote(s.dispatchCounted)}${readViaNote(s)}${notGreenNote(s)}`);
17041
+ `${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}${verifyRuns.setAsideNote(s.setAside)}${verifyRuns.dispatchCountedNote(s.dispatchCounted)}${verifyRuns.missingNote(s.missing, opts.branch)}${readViaNote(s)}${notGreenNote(s)}`);
16968
17042
  }
16969
17043
  return code;
16970
17044
  }