[coretl]

The bug

publish.yml's re-dispatch job waited for the release record
(gh release view --json publishedAt), but the deploy's gather selects releases by their
docs.zip asset.

Consumers who publish a release from the GitHub UI create the record first —
publishing creates the tag, which is what starts CI — so the wait is a no-op and the
dispatched deploy lists releases minutes before release.yml attaches the asset.

Found in blueapi, where the site is
permanently one release behind. Timeline for 1.18.1:

time (UTC)	event
09:34:14	release 1.18.1 published (UI)
09:34:16	tag CI run 32122292712 starts
09:34:50–54	re-dispatch sees the release, dispatches at once
09:35:02	dispatched deploy 32122349268 lists releases — 1.18.1 has no assets yet
09:35:57	release / release attaches docs.zip — 55 s too late

Not a one-off: 1.18.0's own deploy logged Sorted versions: ["main","1.17.0",…] — it
missed itself too, and only reached the site 11 days later carried in by 1.18.1's deploy.

This repo was immune, which is why it went unnoticed: release.yml creates the
release draft → upload → publish atomically, so publishedAt already implies the asset.

The fix

re-dispatch polls the tag's assets for docs.zip:

• skips the wait entirely when no release in the repo has ever carried one (consumers not
  using release.yml);
• 30 min budget — the release job is usually gated on a full test matrix;
• if the asset never lands: loud ::error::, dispatch anyway so the rest of the site
  refreshes, then exit 1;
• retry-until is anchored on the asset's arrival, not publishedAt — which a
  UI-published release stamps before CI even starts, burning the budget before the first
  deploy attempt.

No consumer change is required — no new shim input.

Making the next post-mortem minutes, not hours

The old logs never said why a release was skipped. Now a deploy explains itself:

• a context header — event, ref, every input, which assemble.mjs, timestamps;
• a per-release decision table (gathered / skip: no docs.zip asset /
  DOWNLOAD FAILED) plus a ::warning:: when a release published in the last 30 min has
  no asset — this bug's exact signature, which would have shown it in seconds;
• artifact gathers name the artifact, run and SHA, and split the old catch-all
  artifact unavailable into not found / download failed / contains no docs.zip
  (the last is blueapi's six stale PRs — artifacts predating the docs.zip packing
  contract, needing a CI re-run, not a bug);
• per-zip extract lines, and a job-summary table of every deployed version with the
  source it came from;
• a missing from live: version diff on verify failure, separating a stale origin from a
  bad gather.

Docs

reference/workflows.md and explanations/architecture.md explain what the re-dispatch
waits for and why the UI-publish flow breaks the record wait. New
docs/how-to/choose-publish-events.md covers which events should publish — including why
gating publish on tags alone removes self-healing entirely, which is the second half of
the blueapi failure (their ci.yml has if: … && github.ref_type == 'tag', so every PR
and main push shows publish → skipped and nothing ever corrects a bad deploy).

Verification

Each run: block was extracted and exercised against real blueapi data with a stubbed gh:

• the race — with the asset arriving late, re-dispatch waits and only then
  dispatches (old code dispatched immediately); also covered: no-asset repo → no wait,
  release missing → error, asset never arrives → error + dispatch + exit 1;
• release gather over all 188 real blueapi releases, plus a synthesised
  "published now, no asset" fixture that produces the warning;
• artifact gather reproducing all four blueapi cases distinctly; extract over
  html/-rooted, tag-rooted and malformed zips; summary rendering.

npm test (24 checks) and npm run docs --strict pass; all workflows parse and every
run: block passes bash -n.

Two silent traps the testing caught, both noted in comments:

• unzip -q a.zip member -d dir exits 0 with only a "caution: filename not matched"
  note when the member is absent — the check must be for the file, not the exit status
  (relying on the status let a bare mv fail under set -e and kill the whole deploy job);
• tab is IFS whitespace, so read collapses consecutive tabs — a null published_at
  shifted every column and could have made a good release read as asset-less; jq now
  emits "-" rather than an empty field.

🤖 Generated with Claude Code

[coretl]

Closing without merging, but keeping the fix/re-dispatch-waits-for-release-asset branch — the fix may come back.

Context: the wider question is whether publish should move off the inline ci.yml path onto workflow_run. If it does, this race disappears on its own (workflow_run fires after the tag's CI run — including release.yml — has completed, so docs.zip is already attached and there is nothing to wait for).

That hinges on whether a workflow_run-triggered Pages deploy re-serves at an already-deployed SHA. workflow_run pins GITHUB_SHA to the default branch's HEAD, but a repeat workflow_dispatch at the same SHA demonstrably does re-serve, so the same-SHA rule can't just be assumed to apply. Settling it with a live deploy experiment on this repo.

If the experiment says workflow_run is unusable, this commit gets cherry-picked onto the follow-up branch.