release.sh: merge bump PR after publication and recover failed unpublished releases on resume #1674

This was generated by AI during triage.

Context

When cutting 0.18.8, scripts/release.sh pushed tag v0.18.8, immediately merged the bump PR (#1661) into main, and then waited for the Release workflow (release.yml). A transient GitHub Actions artifact download failure broke build-local-artifacts (x86_64-unknown-linux-musl) before host or custom-publish-crates ran, so v0.18.8 was never published to GitHub Releases or crates.io.

Because the bump PR had already been merged into main and v0.18.8 was already tagged on the old bump commit:

1. Re-running bash scripts/release.sh 0.18.8 exited 1 immediately, telling the operator to run gh run rerun --failed <id> by hand and then invoke release.sh a third time.
2. Meanwhile, new commits landed on main with Cargo.toml already at 0.18.8, and release.sh 0.18.8 had no way to re-cut the unpublished 0.18.8 release from the latest green commit on main.

Agent Brief

Category: enhancement
Summary: Merge the bump PR only after the release workflow succeeds, and make re-running release.sh <version> after a failed unpublished release workflow either re-cut from a newer green main commit or automatically rerun the failed workflow jobs.

Current behavior:

1. scripts/release.sh opens the release-<version> bump PR, waits for its checks, tags the bump commit as v<version>, and immediately merges the bump PR into main before waiting for the release workflow.
2. If the release workflow fails before publishing the GitHub Release, main already carries the bumped Cargo.toml / Cargo.lock version and the merged bump PR.
3. Re-running scripts/release.sh <version> after a release workflow failure sees the completed failed run and exits 1 again without rerunning the failed jobs or checking whether main has advanced to a newer green commit.

Desired behavior:

• Merge after publication. scripts/release.sh tags the bump commit at the head of release-<version>, pushes v<version>, and waits for the release workflow to succeed before merging the bump PR into main. Once the release workflow succeeds, it merges the open bump PR with a merge commit (if not already merged) and prints the GitHub Release URL. As before, if merging the bump PR fails after the release workflow has succeeded, the published release stands: the script prints the warning naming the PR for the Day shift to merge and exits 0.
• Resuming when the release workflow already succeeded (or the GitHub Release exists) but the bump PR is still open. If v<version> is on origin at the head of release-<version> and the release workflow run succeeded, a resumed run merges the still-open bump PR, prints the GitHub Release URL, and exits 0.
• Resuming after a failed release workflow when v<version> is not yet published: When v<version> is already tagged on origin at the head of release-<version>, its latest release workflow run completed in failure, and no GitHub Release exists yet for v<version> (gh release view v<version> fails):
  • Newer green main commit available: If main has a commit newer than the current bump commit's base (head^1) whose latest push CI run succeeded, re-cut release-<version> from that newest green main commit:
    • Run the release Experiment on the new base when --with-experiment is passed.
    • Regenerate the release summary and version diff (honoring --review if passed).
    • Force-push the new bump commit to refs/heads/release-<version> on origin and update the open bump PR's body (gh pr edit).
    • Wait for the bump PR's checks on the new bump commit.
    • Force-push the v<version> tag on origin (git push --force --quiet origin "$head:refs/tags/$tag") to the new bump commit, wait for the new release workflow run to succeed, and then merge the bump PR.
  • No newer green main commit: Automatically rerun the failed jobs of the release workflow run with gh run rerun --failed <id>, print a stamped progress line noting that it reran the failed jobs, and wait for the rerun to complete (and then merge the bump PR on success).
• Published releases are never moved. If a GitHub Release for v<version> already exists, release.sh never force-pushes release-<version> or moves v<version>.

Key interfaces:

• scripts/release.sh workflow ordering (wait_for_release before merge_bump_pr), resume detection, and release workflow recovery.
• scripts/release.sh top-level documentation comments, docs/guide.md, and the generated user manual (site/docs/index.html via npm run docs --prefix site).
• Fake gh and git harness in the release integration test suite (gh run rerun --failed, gh pr edit, gh release view).

Acceptance criteria:

• On a fresh run, scripts/release.sh <version> pushes v<version> on the bump commit, waits for the release workflow to succeed, and only merges the bump PR after the release workflow succeeds.
• If the release workflow fails on the first run, the bump PR remains open and unmerged (so main's Cargo.toml is not bumped before publication), and the script exits 1 naming the failed jobs and run URL.
• Re-running scripts/release.sh <version> after a failed release workflow when no GitHub Release exists and main has no newer green commit runs gh run rerun --failed <id>, waits for the rerun to succeed, merges the bump PR, and exits 0.
• Re-running scripts/release.sh <version> after a failed release workflow when no GitHub Release exists and main has a newer green commit re-cuts release-<version> from the newer green commit, updates the open bump PR body, waits for PR checks, force-pushes v<version> to the new bump commit, waits for the release workflow, merges the bump PR, and exits 0.
• Resuming when v<version>'s release workflow already succeeded while the bump PR is still open merges the bump PR, prints the GitHub Release URL, and exits 0.
• Documentation (scripts/release.sh header comment, docs/guide.md, and generated site/docs/index.html) and the release test suite are updated to match.

Out of scope:

• Changing .github/workflows/release.yml or cargo-dist configuration.
• Automatically retrying failed jobs inside the initial release.sh invocation without the operator re-running release.sh (the initial failure still exits 1 so the operator sees it; re-running release.sh <version> performs the recovery).