diff --git a/.github/actions/README.md b/.github/actions/README.md
index bbbfe5b..eb04b79 100644
--- a/.github/actions/README.md
+++ b/.github/actions/README.md
@@ -9,6 +9,7 @@ a README whose input, output, step and error tables are generated from its
 <!-- generated: catalogue -->
 | Action | Family | Does |
 |---|---|---|
+| [`app-token-lint`](app-token-lint/README.md) | Standalone | Fail a workflow change that mints GitHub App tokens the wrong way. Maxwell (the CI app) may not request a `permission-<x>: write` other than pull-requests and issues; Gutenberg (the release app) may be minted only in a job of the `release` environment, or in a `publish` job when the token asks for exactly `permission-contents: read`; release workflows (those using the release-candidate, release-settle, release-publish or release-route actions, and on-release.yml) mint no Maxwell token, never name their own repository in a read-only dependency token, and never use `mega-maxwell[bot]` as a git identity or PR author filter; and `environment: release` appears only in release-candidate.yml, release-settle.yml and on-release.yml. Violations are reported as `::error file=<path>::<job>/<step>: <rule>: <message>`; unreadable or malformed YAML is an error too. No network. |
 | [`claude-interactive`](claude-interactive/README.md) | [Claude CI](CLAUDE-CI.md) | Run the interactive @claude handler with centralized MegaETH permissions. |
 | [`claude-issue-triage`](claude-issue-triage/README.md) | [Claude CI](CLAUDE-CI.md) | Run the centralized MegaETH Claude issue triage. |
 | [`claude-label-check`](claude-label-check/README.md) | [Claude CI](CLAUDE-CI.md) | Run the centralized MegaETH Claude pull request label check. |
@@ -20,10 +21,11 @@ a README whose input, output, step and error tables are generated from its
 | [`notify-lark`](notify-lark/README.md) | Standalone | Post a message to a Lark (Feishu) group through a custom-bot webhook. The default is a plain text message; `msg_type: post` sends rich text with a title, and `payload` sends any JSON you built yourself (interactive cards, mentions), untouched. If the bot has signature verification enabled, pass its signing `secret` and the request is signed with the documented timestamp + HMAC-SHA256 scheme. The webhook URL and secret go through the environment and are masked. A non-2xx response or a Lark error code fails the step unless `fail_on_error` is `false`; the response body is an output either way. Nothing is organisation-specific: the webhook is an input. |
 | [`pr-lint`](pr-lint/README.md) | Standalone | Lint a pull request. Currently validates that the PR title follows Conventional Commits, posting a sticky comment on failure and removing it once fixed; further PR-level lint steps can be added here over time. Run as a step inside a job the consumer names, so the resulting status-check context is that job name. |
 | [`release-assets`](release-assets/README.md) | [Release pipeline](RELEASE.md) | Attach files, plus a generated `SHA256SUMS`, to the GitHub Release for a tag. Re-runs replace assets of the same name (`--clobber`), so the step is idempotent. `dry_run` writes and prints `SHA256SUMS` but attaches nothing. Needs a token with `contents: write` on the repository (the job token is enough). Guide: .github/actions/RELEASE.md in megaeth-labs/.github. |
-| [`release-candidate`](release-candidate/README.md) | [Release pipeline](RELEASE.md) | Start a release (trunk-first). `stage: propose` bumps the version file on the default branch, drafts this release's changelog entry (dated at settle) from the commits since the previous tag, syncs the previous release's entry from its tag, and opens a `chore/release-candidate-vX.Y.Z` PR; `stage: cut`, run when that PR merges, creates `release-vX.Y.Z` at the merge commit. No tag is created at either stage — tags come from release-publish, once, at settlement. `base_commit` releases a commit that is not the tip of the default branch: `propose` cuts the release branch there itself and points the candidate PR at it, leaving `cut` nothing to do. Run as a step in a job the consumer owns; the consumer checks the repository out first (`fetch-depth: 0`, `persist-credentials: false`). Guide: .github/actions/RELEASE.md in megaeth-labs/.github. |
-| [`release-publish`](release-publish/README.md) | [Release pipeline](RELEASE.md) | Publish a settled release. Normally runs when a `chore/release-settle-vX.Y.Z` PR merges into its release branch (or, with `commit` + `version` given, on an explicit commit that `release-settle` in `direct` mode just made): creates the annotated tag `vX.Y.Z` at the merge commit (exactly once — refuses if it exists, or if the branch moved after the settle PR was opened) and publishes the GitHub Release with the changelog section as notes. This is the only place in the release flow that creates a tag; merging the settle PR is the approval. The default branch's changelog catches up in the next release candidate PR — nothing is back-merged. The consumer checks the repository out first (`fetch-depth: 0`, `persist-credentials: false`). Guide: .github/actions/RELEASE.md in megaeth-labs/.github. |
+| [`release-candidate`](release-candidate/README.md) | [Release pipeline](RELEASE.md) | Start a release (trunk-first). `stage: propose` bumps the version file on the default branch, drafts this release's changelog entry (dated at settle) from the commits since the previous tag, syncs the previous release's entry from its tag, and opens a `chore/release-candidate-vX.Y.Z` PR; `stage: cut`, run on the push that merged that PR (the consumer passes the `commit` and `pr_number` outputs of `release-route`), re-reads the PR through the API, refuses anything but a merged, gutenberg-authored candidate into the default branch, and creates `release-vX.Y.Z` at the merge commit (a retry that finds it already there is a no-op; at any other commit it refuses). No tag is created at either stage — tags come from release-publish, once, at settlement. `base_commit` releases a commit that is not the tip of the default branch: `propose` cuts the release branch there itself, carries the default branch's release workflows onto it, and points the candidate PR at it; that PR merges into the release branch, so `cut` never runs for it. Run as a step in a job the consumer owns, in `environment: release`; the consumer checks the repository out first (`fetch-depth: 0`, `persist-credentials: false`). Guide: .github/actions/RELEASE.md in megaeth-labs/.github. |
+| [`release-publish`](release-publish/README.md) | [Release pipeline](RELEASE.md) | Publish a settled release. Runs on a push to `release-vX.Y.Z` (the consumer passes the `commit` and `pr_number` that `release-route` resolved for the push). Re-verifies the merged `chore/release-settle-vX.Y.Z` PR through the API — merged, merge commit equals the pushed commit, head/base names, author, and the settled-SHA marker against the merge commit's parent — then creates the annotated tag `vX.Y.Z` at that commit and publishes the GitHub Release with the changelog section as notes. A tag already at the commit without a Release (a run that died between the two steps) is resumed: the tag step is skipped and the Release is still created. A tag at the commit with its Release already there is a retry of a finished run and exits 0 with a notice; a tag at any other commit refuses, because a release is published once. A version that is not newer than every other `vX.Y.Z` tag (the rule `release-route` applies) is refused before the tag, and the Release is marked latest only when it is newer than the current latest Release. A tag push or Release create that loses a race to a concurrent run of the same publish keeps the winner's, if it is at this commit. This is the only place in the release flow that creates a tag; merging the settle PR is the approval. The default branch's changelog catches up in the next release candidate PR — nothing is back-merged. The consumer checks the repository out first (`fetch-depth: 0`, `persist-credentials: false`). Guide: .github/actions/RELEASE.md in megaeth-labs/.github. |
 | [`release-publish-rust-crates`](release-publish-rust-crates/README.md) | [Release pipeline](RELEASE.md) | Publish an explicit list of workspace crates to crates.io at the release version. Verifies every listed crate's manifest version first, skips crates already published at that version (so a re-run after a partial failure finishes the rest), publishes the remainder in one `cargo publish -p … -p …` invocation — Cargo orders by dependency and waits for the index between crates (requires Cargo ≥ 1.90) — then polls crates.io until every crate reports the version. `dry_run` runs `cargo publish --dry-run`: full packaging and build verification, nothing uploaded. Run inside a job that has checked out the release tag and installed the toolchain the crates need. Never use `--workspace`: a crate without `publish = false` that was never meant to be published would go out with it. Guide: .github/actions/RELEASE.md in megaeth-labs/.github. |
-| [`release-settle`](release-settle/README.md) | [Release pipeline](RELEASE.md) | Propose settling a release candidate: verify `commit` is the tip of the release branch and carries the expected version, generate release notes from the commits since the previous tag, write them into the changelog (stamping the date onto the candidate's `## vX.Y.Z` entry), and — in the default `pr` mode — open a `chore/release-settle-vX.Y.Z` PR onto the release branch; merging that PR is the settlement decision and release-publish then tags the merge commit once. In `direct` mode the dispatch itself is the decision, gated by the `release` environment the consumer puts on the settle job (optionally also by `settlers`); the changelog commit is pushed straight to the release branch (the app must be a bypass actor on that branch's ruleset), and release-publish runs immediately on that commit. Run as a step in a job the consumer owns; the consumer checks the repository out first (`fetch-depth: 0`, `persist-credentials: false`). Needs `gh` and `python3` on the runner. Guide: .github/actions/RELEASE.md in megaeth-labs/.github. |
+| [`release-route`](release-route/README.md) | [Release pipeline](RELEASE.md) | Route a push or manual dispatch to cut, refresh, publish or skip using merged release PR metadata. Read-only; uses the job token, not a release App secret. Requires a checkout with full history and persist-credentials disabled. |
+| [`release-settle`](release-settle/README.md) | [Release pipeline](RELEASE.md) | Maintain a settle PR for a release candidate: verify `commit` is the tip of the release branch and carries the expected version, generate release notes from the commits since the previous tag, write them into the changelog (stamping the date onto the candidate's `## vX.Y.Z` entry), and open or refresh a `chore/release-settle-vX.Y.Z` PR onto the release branch without rewriting its history. New commits on the release branch refresh this PR automatically; merging it is the settlement decision and release-publish then tags the merge commit once. Run as a step in a job the consumer owns; consumer checks the repository out first (`fetch-depth: 0`, `persist-credentials: false`). Needs `gh` and `python3` on the runner. Guide: .github/actions/RELEASE.md in megaeth-labs/.github. |
 | [`release-snapshot`](release-snapshot/README.md) | [Release pipeline](RELEASE.md) | The two bookends of a snapshot publish — a build of one commit pushed to the artifact registry with no tag and no GitHub Release, for components that deployments pin by commit. `stage: resolve` turns `ref` (a branch, tag or commit; empty means the run's own commit) into the coordinates the upload steps need: the full commit, and the registry `version` (the commit) and `path` (`<profile>/<label>`, e.g. `release/latest`) that match how deployment tooling addresses a snapshot. With `allowed_branches` it refuses a commit that is not reachable from one of those branches, so a dispatch cannot publish an unreviewed commit even though the environment only authorises the branch the workflow ran from. `stage: summary` writes the run summary after the uploads: where each file went, its checksum, and the manifest entry (`commit`, `version`, `profile`) a deployment repository pins; optionally it also records a commit status per package so the commit page shows what was published. Needs a checkout with history for `resolve` (the branch guard uses `merge-base`); nothing here is organisation-specific. Guide: .github/actions/RELEASE.md in megaeth-labs/.github. |
 | [`release-upload-artifact`](release-upload-artifact/README.md) | [Release pipeline](RELEASE.md) | Upload one file to Google Artifact Registry (generic repository) or a Cloud Storage bucket, idempotently: if the destination already holds a file, its hash is compared — identical means "already there" (success, nothing uploaded), different means failure, never a silent overwrite. Every destination is an input; nothing is defaulted. Authentication is the caller's job: run `google-github-actions/auth` (service-account key or Workload Identity Federation) before this step so `gcloud` is authenticated. `dry_run` computes the checksum and checks the destination but uploads nothing. Guide: .github/actions/RELEASE.md in megaeth-labs/.github. |
 | [`release-verify-version`](release-verify-version/README.md) | [Release pipeline](RELEASE.md) | Run a command that prints a built artifact's version (`my-binary --version`) and require the output to match the release version, so a binary built from the wrong tree — or a tag that does not match the manifest — never reaches a publish step. By default the expected output is `<name> <version>` (the clap shape: the command's basename, then the version without its leading `v`); `expected` overrides it. A command that cannot run at all — missing library, crash, no such flag — fails the step even on a dry run: an artifact that does not execute is never publishable, and its exit code is never swallowed. A mismatch is a warning on a dry run, so a rehearsal reports what a real run would refuse and carries on, and a hard stop otherwise. Guide: .github/actions/RELEASE.md in megaeth-labs/.github. |
@@ -65,4 +67,8 @@ actions share ([README](release-tools/README.md)).
 - A new action needs a directory with `action.yml`; the script creates its
   README skeleton, whose `Example` and `Notes` sections you then fill in.
 - Templates in `workflow-templates/` are the reference callers: keep them in
-  step with the actions they call.
+  step with the actions they call. `.github/scripts/copy_templates.py`
+  renders the release templates for one repository (version file and
+  pattern, bump command, private dependencies, default branch) into a fresh
+  directory and fails if a placeholder is left or a `with:` key is not an
+  input of the action it calls; its unit test runs in `actions-test.yml`.
diff --git a/.github/actions/RELEASE.md b/.github/actions/RELEASE.md
index 0f49a60..ab5318e 100644
--- a/.github/actions/RELEASE.md
+++ b/.github/actions/RELEASE.md
@@ -69,12 +69,14 @@ The choices that shape it:
   `publish` environment whose deployment policy allows only `v*` tag refs, so
   a branch build can never read them. The environment has no reviewers: the
   human gate is settlement.
-- **No force pushes to release branches, settle branches or tags.**
-  Re-running settle supersedes what it made before (closes the old PR, drops
-  the branch, pushes fresh), so it works in repositories whose rulesets ban
-  force pushes. The one exception is a candidate re-dispatched while its PR
-  is still open: that PR's branch is updated in place, which is a force push
-  (see [Operations](#operations-and-recovery)).
+- **Nothing force-pushes any branch, or a tag.** Re-dispatching a candidate
+  supersedes the open one: it closes that PR with a comment, deletes the
+  branch, pushes a fresh one as a new ref and opens a fresh PR. Re-running
+  settle fast-forwards its own PR's branch, or closes a PR it does not
+  maintain and starts fresh. So the pipeline works in repositories whose rulesets
+  ban force pushes on every branch, with no exemption. A test
+  (`.github/scripts/test_no_force_push.py`) fails if any shipped action or
+  template gains a forced push.
 - **Generic.** The actions know nothing about MegaETH: the version file and
   its format, the changelog path, the branch prefix, the app identity and
   every publish destination are inputs. The templates carry this
@@ -97,8 +99,9 @@ branch `chore/release-candidate-1.2.3`: the version file bumped, whatever
 changelog entry `## v1.2.3` drafted from the merged PR titles since the last
 `v*` tag (grouped by Conventional Commit type, with PR links), and the
 previous release's entry synced from its tag. Review it like any PR; fix
-wording in it if the generated entry needs work. A stale candidate branch
-from an earlier attempt is dropped first, unless its PR is still open.
+wording in it if the generated entry needs work. Re-dispatching the
+candidate supersedes this PR (closed with a comment, a fresh branch and PR
+opened, nothing force-pushed), so edits made on it are not carried over.
 
 **2. Cut.** Merging the candidate PR runs the `cut` job, which creates
 `release-v1.2.3` at the merge commit. No tag yet. From here, fixes for the
@@ -178,8 +181,10 @@ Step 1 then works differently, and steps 3 and 4 are unchanged:
   syncs the entry back from the tag the way it does after any release. The
   next version must still be newer than `v1.2.3`.
 
-The version must be newer than the newest `v*` tag in the repository, as
-usual. That covers two cases: an earlier commit on the current default
+The version must be newer than the newest `vX.Y.Z` tag in the repository, as
+usual (tags such as `v1.2.0-rc1` are not releases and are ignored). Publishing
+re-checks this when the settle PR merges, so a line that a newer release
+overtook while its settle PR was open is refused, never tagged. That covers two cases: an earlier commit on the current default
 branch, and a hotfix of the latest tag (new `release-vX.Y.Z` cut there,
 candidate PR aimed at that branch). It still does not patch an older line
 that a higher tag has already passed.
@@ -422,12 +427,17 @@ default branch has. Fix: cherry-pick the file onto the release branch through
 its own PR, then settle. (A tag's tree is final: a target that was missing
 or broken at a tag cannot be re-run for that tag; the next release gets it.)
 
-**A stale candidate branch exists** from an earlier attempt: the candidate
-action deletes it before pushing, unless a PR on it is still open, in which
-case that PR is updated in place with a force push of its branch. In a
-repository whose rulesets ban force pushes, close the open candidate PR
-before re-dispatching; the action then drops the branch and opens a fresh
-PR.
+**A candidate is re-dispatched** (a fix landed, or the first attempt failed
+part-way): the fresh candidate supersedes the old one. An open candidate PR
+for that version is closed with a comment saying so, its branch is deleted,
+the new candidate commit is pushed as a new branch and a fresh PR is opened.
+Nothing is force-pushed, so there is nothing to close by hand first. A retry
+converges from wherever the last attempt stopped (a PR already closed, a
+branch already gone, a branch pushed with no PR yet), and a concurrent run
+that pushed the branch or opened the PR first is kept rather than replaced:
+the result is always one branch and one open PR. The branch is deleted on
+merge only by the repository's "Automatically delete head branches" setting;
+without it, a merged candidate's branch stays, unused.
 
 **Two runs of the same stage overlap.** They queue, never cancel: the
 candidate's `propose` and `cut`, and `release-publish`'s `publish`, carry
diff --git a/.github/actions/app-token-lint/README.md b/.github/actions/app-token-lint/README.md
new file mode 100644
index 0000000..5fdd549
--- /dev/null
+++ b/.github/actions/app-token-lint/README.md
@@ -0,0 +1,79 @@
+# App Token Lint
+
+`uses: megaeth-labs/.github/.github/actions/app-token-lint@main`
+
+<!-- generated: description -->
+Fail a workflow change that mints GitHub App tokens the wrong way. Maxwell (the CI app) may not request a `permission-<x>: write` other than pull-requests and issues; Gutenberg (the release app) may be minted only in a job of the `release` environment, or in a `publish` job when the token asks for exactly `permission-contents: read`; release workflows (those using the release-candidate, release-settle, release-publish or release-route actions, and on-release.yml) mint no Maxwell token, never name their own repository in a read-only dependency token, and never use `mega-maxwell[bot]` as a git identity or PR author filter; and `environment: release` appears only in release-candidate.yml, release-settle.yml and on-release.yml. Violations are reported as `::error file=<path>::<job>/<step>: <rule>: <message>`; unreadable or malformed YAML is an error too. No network.
+<!-- /generated -->
+
+Standalone action; no family guide.
+
+## Inputs
+
+<!-- generated: inputs -->
+| Input | Required | Default | Description |
+|---|---|---|---|
+| `paths` | no | `.github/workflows` | Workflow files or directories of them to lint, separated by whitespace (no spaces inside a path). The repository name used by the own-repository check comes from `GITHUB_REPOSITORY`. |
+<!-- /generated -->
+
+## Outputs
+
+<!-- generated: outputs -->
+This action sets no outputs.
+<!-- /generated -->
+
+## What it runs
+
+<!-- generated: steps -->
+1. Install PyYAML if missing
+1. Lint App token usage
+<!-- /generated -->
+
+## Errors it reports
+
+<!-- generated: errors -->
+Its shell steps report no errors of their own; failures come from the actions and tools it calls.
+<!-- /generated -->
+
+## Example
+
+Lint a repository's own workflows on every pull request:
+
+```yaml
+on:
+  pull_request:
+    paths: [".github/workflows/**"]
+
+jobs:
+  app-token-lint:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: megaeth-labs/.github/.github/actions/app-token-lint@main
+```
+
+The action reads `.github/workflows` by default; pass `paths:` to lint
+another directory or several, e.g. `paths: .github/workflows workflow-templates`.
+
+## Notes
+
+- Rules, in the order violations name them: **L1** Maxwell tokens write only
+  pull-requests and issues; **L2** Gutenberg tokens need `environment: release`
+  (or `publish` with exactly `permission-contents: read`); **L3** release
+  workflows mint no Maxwell token and no read-only dependency token naming
+  their own repository; **L4** release workflows never use `mega-maxwell[bot]`;
+  **L5** `environment: release` only in `release-candidate.yml`,
+  `release-settle.yml` and `on-release.yml`; **L6** a Maxwell or Gutenberg
+  token, and any app token in a release job, requests at least one
+  `permission-<x>` (without one it gets every permission of the installation).
+- A token step is a step using `actions/create-github-app-token`; Maxwell is
+  recognised by `MEGA_MAXWELL_`, `CI_APP_ID` or `MEGA_CI_APP_PK` in
+  `client-id`, `app-id` or `private-key`, Gutenberg by `RELEASE_APP_`.
+- A permission that is not a literal value (an expression) cannot be checked
+  and counts as a violation for a Maxwell token.
+- A path that does not exist, a directory without `*.yml`/`*.yaml` files and
+  malformed YAML are errors, never a clean pass.
+- The script is `.github/scripts/app_token_lint.py`; it needs no network and
+  runs locally as `python3 .github/scripts/app_token_lint.py --repo <name> <paths>`.
diff --git a/.github/actions/app-token-lint/action.yml b/.github/actions/app-token-lint/action.yml
new file mode 100644
index 0000000..0c79263
--- /dev/null
+++ b/.github/actions/app-token-lint/action.yml
@@ -0,0 +1,40 @@
+name: App Token Lint
+description: >-
+  Fail a workflow change that mints GitHub App tokens the wrong way. Maxwell
+  (the CI app) may not request a `permission-<x>: write` other than
+  pull-requests and issues; Gutenberg (the release app) may be minted only in a
+  job of the `release` environment, or in a `publish` job when the token asks
+  for exactly `permission-contents: read`; release workflows (those using the
+  release-candidate, release-settle, release-publish or release-route actions,
+  and on-release.yml) mint no Maxwell token, never name their own repository
+  in a read-only dependency token, and never use `mega-maxwell[bot]` as a git
+  identity or PR author filter; and `environment: release` appears only in
+  release-candidate.yml, release-settle.yml and on-release.yml. Violations are
+  reported as `::error file=<path>::<job>/<step>: <rule>: <message>`; unreadable
+  or malformed YAML is an error too. No network.
+
+inputs:
+  paths:
+    description: >-
+      Workflow files or directories of them to lint, separated by whitespace
+      (no spaces inside a path). The repository name used by the own-repository
+      check comes from `GITHUB_REPOSITORY`.
+    required: false
+    default: .github/workflows
+
+runs:
+  using: composite
+  steps:
+    - name: Install PyYAML if missing
+      shell: bash
+      run: python3 -c 'import yaml' 2>/dev/null || python3 -m pip install --quiet pyyaml
+
+    - name: Lint App token usage
+      shell: bash
+      env:
+        ACTION_PATH: ${{ github.action_path }}
+        LINT_PATHS: ${{ inputs.paths }}
+      run: |
+        set -euo pipefail
+        read -r -d '' -a paths <<< "$LINT_PATHS" || true
+        python3 "$ACTION_PATH/../../scripts/app_token_lint.py" "${paths[@]}"
diff --git a/.github/actions/release-candidate/README.md b/.github/actions/release-candidate/README.md
index f733bc5..5f3d7ce 100644
--- a/.github/actions/release-candidate/README.md
+++ b/.github/actions/release-candidate/README.md
@@ -3,7 +3,7 @@
 `uses: megaeth-labs/.github/.github/actions/release-candidate@main`
 
 <!-- generated: description -->
-Start a release (trunk-first). `stage: propose` bumps the version file on the default branch, drafts this release's changelog entry (dated at settle) from the commits since the previous tag, syncs the previous release's entry from its tag, and opens a `chore/release-candidate-vX.Y.Z` PR; `stage: cut`, run when that PR merges, creates `release-vX.Y.Z` at the merge commit. No tag is created at either stage — tags come from release-publish, once, at settlement. `base_commit` releases a commit that is not the tip of the default branch: `propose` cuts the release branch there itself and points the candidate PR at it, leaving `cut` nothing to do. Run as a step in a job the consumer owns; the consumer checks the repository out first (`fetch-depth: 0`, `persist-credentials: false`). Guide: .github/actions/RELEASE.md in megaeth-labs/.github.
+Start a release (trunk-first). `stage: propose` bumps the version file on the default branch, drafts this release's changelog entry (dated at settle) from the commits since the previous tag, syncs the previous release's entry from its tag, and opens a `chore/release-candidate-vX.Y.Z` PR; `stage: cut`, run on the push that merged that PR (the consumer passes the `commit` and `pr_number` outputs of `release-route`), re-reads the PR through the API, refuses anything but a merged, gutenberg-authored candidate into the default branch, and creates `release-vX.Y.Z` at the merge commit (a retry that finds it already there is a no-op; at any other commit it refuses). No tag is created at either stage — tags come from release-publish, once, at settlement. `base_commit` releases a commit that is not the tip of the default branch: `propose` cuts the release branch there itself, carries the default branch's release workflows onto it, and points the candidate PR at it; that PR merges into the release branch, so `cut` never runs for it. Run as a step in a job the consumer owns, in `environment: release`; the consumer checks the repository out first (`fetch-depth: 0`, `persist-credentials: false`). Guide: .github/actions/RELEASE.md in megaeth-labs/.github.
 <!-- /generated -->
 
 Family: [Release pipeline](../RELEASE.md).
@@ -14,8 +14,11 @@ Family: [Release pipeline](../RELEASE.md).
 | Input | Required | Default | Description |
 |---|---|---|---|
 | `stage` | yes |  | `propose` (on workflow_dispatch) or `cut` (on the candidate PR merging). |
-| `token` | yes |  | Token that authors the PR and creates the branch. Must be a GitHub App installation token (e.g. the Maxwell app) so the PR triggers CI; the job's GITHUB_TOKEN does not. |
-| `dependency_token` | no |  | Optional read-only token for bump_command's private dependencies; defaults to token. |
+| `token` | yes |  | mega-gutenberg installation token (contents, pull-requests, workflows write) minted in an `environment: release` job; it pushes the candidate branch, opens the PR (so CI runs) and creates the release branch. |
+| `dependency_token` | no |  | Read-only token for bump_command's private dependencies. Required when bump_command is set; it never falls back to token, so the command does not run with the release token. |
+| `commit` | no |  | The merge commit of the candidate PR (the `commit` output of `release-route`). Required for `cut`; the release branch is created at it. |
+| `pr_number` | no |  | The candidate PR number (the `pr_number` output of `release-route`). Required for `cut`; the PR is re-read through the API, not trusted from the event. |
+| `release_workflows` | no | `.github/workflows/release-settle.yml .github/workflows/on-release.yml` | Newline- or space-separated workflow paths `propose` with `base_commit` copies from the default branch onto the old tree (a path absent on the default branch is skipped), and it deletes `.github/workflows/release-publish.yml`. Workflows run from the pushed ref's tree, so a branch cut at an older commit would otherwise run pre-migration release workflows. |
 | `version` | no |  | Version to release, X.Y.Z or vX.Y.Z. Required for `propose`. |
 | `base_commit` | no |  | The commit to release, for `propose`, when it must not be the tip of the default branch. Any commit-ish the checkout can resolve (a full SHA, a tag, `origin/main~3`). It must be reachable from the default branch, or sit on the latest `v*` release line (from the merge-base with trunk through that tag), so a hotfix of the current tag works even though settlement left the tag off trunk. Empty (the default) is the trunk-first flow: the candidate PR merges into the default branch and `cut` creates the release branch at that merge commit. Set, `propose` creates the release branch at this commit and opens the candidate PR against that branch, because merging it into the default branch would take the commits this release is leaving out; the default branch is then untouched and `cut` never runs. The version must still be newer than the newest `v*` tag in the repository. |
 | `version_file` | yes |  | File holding the version (VERSION, Cargo.toml, pyproject.toml, package.json). |
@@ -24,9 +27,9 @@ Family: [Release pipeline](../RELEASE.md).
 | `release_branch_prefix` | no | `release-v` | Release branch name prefix; the branch is `<prefix>X.Y.Z`. |
 | `changelog_file` | no | `CHANGELOG.md` | Changelog to draft into (Keep-a-Changelog style, newest first). Empty disables changelog handling. |
 | `pr_labels` | no |  | Comma-separated labels for the candidate PR. |
-| `pr_author` | no | `mega-maxwell[bot]` | Login the candidate PR must have been opened by for `cut` to proceed — the app identity `propose` runs under. Stops a hand-made `chore/release-candidate-*` branch from driving the cut. Empty disables the check. |
-| `git_user_name` | no | `mega-maxwell[bot]` | Committer identity for the bump commit. |
-| `git_user_email` | no | `290560214+mega-maxwell[bot]@users.noreply.github.com` | Committer email for the commits this action makes. |
+| `pr_author` | no | `mega-gutenberg[bot]` | Login the candidate PR must have been opened by for `cut` to proceed — the app identity `propose` runs under. Stops a hand-made `chore/release-candidate-*` branch from driving the cut. Empty disables the check. |
+| `git_user_name` | no | `mega-gutenberg[bot]` | Committer identity for the bump commit. |
+| `git_user_email` | no | `348780249+mega-gutenberg[bot]@users.noreply.github.com` | Committer email for the commits this action makes. |
 <!-- /generated -->
 
 ## Outputs
@@ -47,29 +50,42 @@ Family: [Release pipeline](../RELEASE.md).
 1. Configure git identity
 1. Guard (propose) *(only if `inputs.stage == 'propose'`)*
 1. Cut the release branch at the base commit (propose) *(only if `inputs.stage == 'propose' && inputs.base_commit != ''`)*
+1. Carry the release workflows (propose) *(only if `inputs.stage == 'propose' && inputs.base_commit != ''`)*
 1. Bump version file *(only if `inputs.stage == 'propose'`)*
 1. Run bump command *(only if `inputs.stage == 'propose' && inputs.bump_command != '' && steps.bump.outputs.skipped != 'true'`)*
 1. Draft changelog *(only if `inputs.stage == 'propose' && inputs.changelog_file != '' && steps.bump.outputs.skipped != 'true'`)*
-1. Drop a stale candidate branch *(only if `inputs.stage == 'propose'`)*
-1. Open candidate PR — `peter-evans/create-pull-request` *(only if `inputs.stage == 'propose'`)*
+1. Open candidate PR *(only if `inputs.stage == 'propose'`)*
 1. Cut release branch *(only if `inputs.stage == 'cut'`)*
 <!-- /generated -->
 
 ## Errors it reports
 
 <!-- generated: errors -->
+- `cut needs the pr_number input (the release-route output)`
 - `stage must be propose or cut, got`
 - `release candidates start from the default branch ($default); this run is on $GITHUB_REF_NAME`
 - `$VERSION is not newer than the latest tag ${latest:-<none>}`
 - `tag v$VERSION already exists`
 - `base_commit $BASE_COMMIT is not a commit in this checkout; check the repository out with fetch-depth: 0`
 - `base_commit $base is not reachable from the default branch ($default); a release must ship code that landed on trunk`
-- `branch $branch already exists`
+- `branch $branch already exists: v$VERSION was already cut from its merged candidate, so there is nothing left to propose; settle it from $branch`
 - `branch $branch already exists at $existing, which does not contain base_commit $base`
+- `could not create $BRANCH at $checkout (it is now at`
+- `bump_command needs a separate dependency_token, so the command never runs with the release token`
 - `after bump_command, $FILE reads $actual, expected $NEW_VERSION`
-- `cut runs on a merged candidate PR (pull_request closed, merged == true)`
+- `could not close the open candidate PR #$number ($url)`
+- `could not delete $head, and no open PR owns it`
+- `could not push $head`
+- `could not open the candidate PR for $head`
+- `cut needs the commit and pr_number inputs (the release-route outputs)`
+- `candidate PR #$PR_NUMBER has not been merged; cut only runs for a merged candidate`
+- `candidate PR #$PR_NUMBER merged as`
+- `PR #$PR_NUMBER head`
+- `candidate PR #$PR_NUMBER targets`
 - `candidate PR #$PR_NUMBER was opened by`
-- `$FILE at $MERGE_SHA says $actual, expected $VERSION`
+- `$FILE at $COMMIT says $actual, expected $VERSION`
+- `could not create $branch at $COMMIT`
+- `branch $branch already exists at $existing, not at the candidate merge commit $COMMIT; refusing to move it`
 <!-- /generated -->
 
 ## Example
@@ -94,11 +110,18 @@ both from `workflow-templates/release-candidate.yml`:
 - `propose` bumps the version file, runs `bump_command` with `OLD_VERSION`
   and `NEW_VERSION` set, drafts the `## vX.Y.Z` changelog entry from the
   merged PR titles since the last `v*` tag, syncs the previous release's
-  entry from its tag, drops a stale `chore/release-candidate-X.Y.Z` branch
-  (unless its PR is still open, in which case that PR is updated, with a
-  force push of its branch), and opens the candidate PR.
+  entry from its tag, and opens the candidate PR from a new
+  `chore/release-candidate-X.Y.Z` branch. It never rewrites a branch: a
+  candidate PR still open for that version is closed with a comment saying a
+  fresh candidate supersedes it, its branch is deleted, and the new commit is
+  pushed as a new ref. A retry, or a run racing another, converges on one
+  branch and one open PR (a branch or PR the other run made first is kept).
+  The branch is deleted on merge only by the repository's "Automatically
+  delete head branches" setting; the step log says which applies.
 - `cut` runs when that PR merges and creates `<release_branch_prefix>X.Y.Z`
-  at the merge commit; it refuses a PR not opened by `pr_author`.
+  at the merge commit; it refuses a PR not opened by `pr_author`. A retry
+  that finds the branch already at that commit exits 0 with a notice; at
+  any other commit it refuses and names both SHAs.
 - `token` must be an App installation token: a `GITHUB_TOKEN` push would not
   trigger the consumer's CI on the candidate PR.
 - The full flow, installation and recovery: [RELEASE.md](../RELEASE.md).
diff --git a/.github/actions/release-candidate/action.yml b/.github/actions/release-candidate/action.yml
index 50fc18a..853d0e0 100644
--- a/.github/actions/release-candidate/action.yml
+++ b/.github/actions/release-candidate/action.yml
@@ -4,13 +4,19 @@ description: >-
   default branch, drafts this release's changelog entry (dated at settle) from the
   commits since the previous tag, syncs the previous release's entry from its
   tag, and opens a `chore/release-candidate-vX.Y.Z` PR; `stage: cut`,
-  run when that PR merges, creates `release-vX.Y.Z` at the merge commit. No tag
+  run on the push that merged that PR (the consumer passes the `commit` and
+  `pr_number` outputs of `release-route`), re-reads the PR through the API,
+  refuses anything but a merged, gutenberg-authored candidate into the default
+  branch, and creates `release-vX.Y.Z` at the merge commit (a retry that
+  finds it already there is a no-op; at any other commit it refuses). No tag
   is created at either stage — tags come from release-publish, once, at
   settlement. `base_commit` releases a commit that is not the tip of the
-  default branch: `propose` cuts the release branch there itself and points the
-  candidate PR at it, leaving `cut` nothing to do. Run as a step in a job the
-  consumer owns; the consumer checks the repository out first
-  (`fetch-depth: 0`, `persist-credentials: false`).
+  default branch: `propose` cuts the release branch there itself, carries the
+  default branch's release workflows onto it, and points the candidate PR at
+  it; that PR merges into the release branch, so `cut` never runs for it. Run
+  as a step in a job the consumer owns, in `environment: release`; the
+  consumer checks the repository out first (`fetch-depth: 0`,
+  `persist-credentials: false`).
   Guide: .github/actions/RELEASE.md in megaeth-labs/.github.
 
 inputs:
@@ -19,14 +25,39 @@ inputs:
     required: true
   token:
     description: >-
-      Token that authors the PR and creates the branch. Must be a GitHub App
-      installation token (e.g. the Maxwell app) so the PR triggers CI; the
-      job's GITHUB_TOKEN does not.
+      mega-gutenberg installation token (contents, pull-requests, workflows
+      write) minted in an `environment: release` job; it pushes the candidate
+      branch, opens the PR (so CI runs) and creates the release branch.
     required: true
   dependency_token:
-    description: Optional read-only token for bump_command's private dependencies; defaults to token.
+    description: >-
+      Read-only token for bump_command's private dependencies. Required when
+      bump_command is set; it never falls back to token, so the command does
+      not run with the release token.
+    required: false
+    default: ""
+  commit:
+    description: >-
+      The merge commit of the candidate PR (the `commit` output of
+      `release-route`). Required for `cut`; the release branch is created at it.
+    required: false
+    default: ""
+  pr_number:
+    description: >-
+      The candidate PR number (the `pr_number` output of `release-route`).
+      Required for `cut`; the PR is re-read through the API, not trusted from
+      the event.
     required: false
     default: ""
+  release_workflows:
+    description: >-
+      Newline- or space-separated workflow paths `propose` with `base_commit` copies from
+      the default branch onto the old tree (a path absent on the default branch
+      is skipped), and it deletes `.github/workflows/release-publish.yml`.
+      Workflows run from the pushed ref's tree, so a branch cut at an older
+      commit would otherwise run pre-migration release workflows.
+    required: false
+    default: ".github/workflows/release-settle.yml .github/workflows/on-release.yml"
   version:
     description: "Version to release, X.Y.Z or vX.Y.Z. Required for `propose`."
     required: false
@@ -87,15 +118,15 @@ inputs:
       `chore/release-candidate-*` branch from driving the cut. Empty disables
       the check.
     required: false
-    default: "mega-maxwell[bot]"
+    default: "mega-gutenberg[bot]"
   git_user_name:
     description: "Committer identity for the bump commit."
     required: false
-    default: "mega-maxwell[bot]"
+    default: "mega-gutenberg[bot]"
   git_user_email:
     description: "Committer email for the commits this action makes."
     required: false
-    default: "290560214+mega-maxwell[bot]@users.noreply.github.com"
+    default: "348780249+mega-gutenberg[bot]@users.noreply.github.com"
 
 outputs:
   version:
@@ -103,7 +134,7 @@ outputs:
     value: ${{ steps.version.outputs.version }}
   pr_url:
     description: "`propose`: URL of the candidate PR."
-    value: ${{ steps.pr.outputs.pull-request-url }}
+    value: ${{ steps.pr.outputs.pr_url }}
   release_branch:
     description: "The release branch: created by `cut`, or by `propose` when `base_commit` is set."
     value: ${{ steps.cut.outputs.release_branch || steps.branch.outputs.release_branch }}
@@ -120,13 +151,20 @@ runs:
       env:
         STAGE: ${{ inputs.stage }}
         INPUT_VERSION: ${{ inputs.version }}
-        HEAD_REF: ${{ github.event.pull_request.head.ref }}
+        PR_NUMBER: ${{ inputs.pr_number }}
+        GH_TOKEN: ${{ inputs.token }}
         TOOLS: ${{ github.action_path }}/../release-tools/release_tools.py
       run: |
         set -euo pipefail
         case "$STAGE" in
           propose) raw="$INPUT_VERSION" ;;
-          cut)     raw="${HEAD_REF#chore/release-candidate-}" ;;
+          cut)
+            if [[ -z "$PR_NUMBER" ]]; then
+              echo "::error::cut needs the pr_number input (the release-route output)"; exit 1
+            fi
+            head_ref="$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER" | python3 -c 'import json,sys; print(json.load(sys.stdin)["head"]["ref"])')"
+            raw="${head_ref#chore/release-candidate-}"
+            ;;
           *) echo "::error::stage must be propose or cut, got '$STAGE'"; exit 1 ;;
         esac
         version="$(python3 "$TOOLS" normalize "$raw")"
@@ -164,7 +202,7 @@ runs:
           exit 1
         fi
         git fetch --quiet --tags origin
-        latest="$(git tag -l 'v*' --sort=-v:refname | head -n1 || true)"
+        latest="$(git tag -l 'v*' | python3 "$TOOLS" latest-tag)"
         if ! python3 "$TOOLS" is-greater "$VERSION" "$latest"; then
           echo "::error::$VERSION is not newer than the latest tag ${latest:-<none>}"
           exit 1
@@ -188,7 +226,7 @@ runs:
             # Settlement leaves the latest tag off trunk (bump + dated
             # changelog). A hotfix of that tag is still the current line,
             # not a random side branch.
-            latest="$(git tag -l 'v*' --sort=-v:refname | head -n1 || true)"
+            latest="$(git tag -l 'v*' | python3 "$TOOLS" latest-tag)"
             on_release_line=0
             if [[ -n "$latest" ]]; then
               latest_sha="$(git rev-parse --verify --quiet "${latest}^{commit}" || true)"
@@ -218,7 +256,7 @@ runs:
         checkout="$base"
         if [[ -n "$existing" ]]; then
           if [[ -z "$base" ]]; then
-            echo "::error::branch $branch already exists"; exit 1
+            echo "::error::branch $branch already exists: v$VERSION was already cut from its merged candidate, so there is nothing left to propose; settle it from $branch"; exit 1
           fi
           git fetch --quiet origin "+refs/heads/$branch:refs/remotes/origin/$branch"
           if [[ "$existing" == "$base" ]]; then
@@ -260,8 +298,16 @@ runs:
         set -euo pipefail
         checkout="${CHECKOUT:-$BASE}"
         if ! git ls-remote --exit-code --heads origin "refs/heads/$BRANCH" >/dev/null; then
-          gh api "repos/$GITHUB_REPOSITORY/git/refs" -f ref="refs/heads/$BRANCH" -f sha="$checkout" >/dev/null
-          echo "created $BRANCH at $checkout"
+          if gh api "repos/$GITHUB_REPOSITORY/git/refs" -f ref="refs/heads/$BRANCH" -f sha="$checkout" >/dev/null; then
+            echo "created $BRANCH at $checkout"
+          else
+            # Lost a race to a concurrent propose: only the same commit is ours.
+            raced="$(git ls-remote --heads origin "refs/heads/$BRANCH" | cut -f1)"
+            if [[ "$raced" != "$checkout" ]]; then
+              echo "::error::could not create $BRANCH at $checkout (it is now at '${raced:-<absent>}')"; exit 1
+            fi
+            echo "::notice title=Reusing the release branch::$BRANCH was created at $checkout by a concurrent run"
+          fi
         fi
         git fetch --quiet origin "+refs/heads/$BRANCH:refs/remotes/origin/$BRANCH"
         git checkout --quiet -B "$BRANCH" "$checkout"
@@ -269,6 +315,42 @@ runs:
         echo "candidate PR will target $BRANCH at $checkout"
         GITHUB_AUTH_COMMAND
 
+    # Workflows run from the pushed ref's tree, so a release branch cut at an
+    # older base commit would run pre-migration release workflows, and the tag
+    # cut from it would carry a pre-migration on-release.yml. The candidate
+    # commit carries the default branch's copies, so merging it into the
+    # release branch migrates the branch.
+
+    - name: Carry the release workflows (propose)
+      if: inputs.stage == 'propose' && inputs.base_commit != ''
+      shell: bash
+      env:
+        AUTH_WRAPPER: ${{ github.action_path }}/../git-auth/with-github-auth.sh
+        GITHUB_AUTH_TOKEN: ${{ inputs.token }}
+        GH_TOKEN: ${{ inputs.token }}
+        RELEASE_WORKFLOWS: ${{ inputs.release_workflows }}
+      run: |
+        "$AUTH_WRAPPER" bash --noprofile --norc -e -o pipefail <<'GITHUB_AUTH_COMMAND'
+        set -euo pipefail
+        default="$(gh repo view "$GITHUB_REPOSITORY" --json defaultBranchRef -q .defaultBranchRef.name)"
+        git fetch --quiet origin "+refs/heads/$default:refs/remotes/origin/$default"
+        set -f
+        for path in $RELEASE_WORKFLOWS; do
+          if git cat-file -e "origin/$default:$path" 2>/dev/null; then
+            git checkout --quiet "origin/$default" -- "$path"
+            echo "carried $path from $default"
+          else
+            echo "skipped $path: not on $default"
+          fi
+        done
+        set +f
+        if [[ -e .github/workflows/release-publish.yml ]]; then
+          git rm --quiet -f .github/workflows/release-publish.yml
+          echo "deleted .github/workflows/release-publish.yml"
+        fi
+        git status --short
+        GITHUB_AUTH_COMMAND
+
     - name: Bump version file
       if: inputs.stage == 'propose'
       id: bump
@@ -298,7 +380,8 @@ runs:
       shell: bash
       env:
         AUTH_WRAPPER: ${{ github.action_path }}/../git-auth/with-github-auth.sh
-        GITHUB_AUTH_TOKEN: ${{ inputs.dependency_token || inputs.token }}
+        GITHUB_AUTH_TOKEN: ${{ inputs.dependency_token }}
+        DEPENDENCY_TOKEN: ${{ inputs.dependency_token }}
         OLD_VERSION: ${{ steps.bump.outputs.old }}
         NEW_VERSION: ${{ steps.version.outputs.version }}
         BUMP_COMMAND: ${{ inputs.bump_command }}
@@ -306,6 +389,10 @@ runs:
         PATTERN: ${{ inputs.version_pattern }}
         TOOLS: ${{ github.action_path }}/../release-tools/release_tools.py
       run: |
+        if [[ -z "$DEPENDENCY_TOKEN" ]]; then
+          echo "::error::bump_command needs a separate dependency_token, so the command never runs with the release token"
+          exit 1
+        fi
         "$AUTH_WRAPPER" bash --noprofile --norc -e -o pipefail <<'GITHUB_AUTH_COMMAND'
         set -euo pipefail
         echo "bump command: $BUMP_COMMAND"
@@ -328,7 +415,7 @@ runs:
         TOOLS: ${{ github.action_path }}/../release-tools/release_tools.py
       run: |
         set -euo pipefail
-        latest="$(git tag -l 'v*' --sort=-v:refname | head -n1 || true)"
+        latest="$(git tag -l 'v*' | python3 "$TOOLS" latest-tag)"
         # 1. Sync the previous release's entry from its tag. Settle stamped
         #    the date (and any drift) on the release branch and nothing
         #    back-merges it: this PR is where the default branch catches up.
@@ -351,60 +438,155 @@ runs:
         echo "changelog: previous entry ${latest:-<none>} $synced; v$VERSION entry $drafted"
         git diff --stat
 
-    - name: Drop a stale candidate branch
+    # The candidate branch is never rewritten. A re-dispatch supersedes the
+    # open candidate instead: it closes that PR with a comment, deletes the
+    # branch, pushes a fresh one as a new ref and opens a fresh PR, so this
+    # works under a ruleset that bans force pushes on every branch. Each state
+    # a retry or a concurrent run can leave behind (a PR already closed, a ref
+    # already gone, a branch or PR another run created first) converges to
+    # one branch and one open PR.
+    - name: Open candidate PR
       if: inputs.stage == 'propose'
+      id: pr
       shell: bash
       env:
         AUTH_WRAPPER: ${{ github.action_path }}/../git-auth/with-github-auth.sh
         GITHUB_AUTH_TOKEN: ${{ inputs.token }}
         GH_TOKEN: ${{ inputs.token }}
         VERSION: ${{ steps.version.outputs.version }}
+        OLD_VERSION: ${{ steps.bump.outputs.old }}
+        # Empty means the branch this job checked out, i.e. the default
+        # branch; set, it is the release branch cut above.
+        RELEASE_BRANCH: ${{ steps.branch.outputs.release_branch }}
+        BASE_COMMIT: ${{ steps.guard.outputs.base }}
+        PREFIX: ${{ inputs.release_branch_prefix }}
+        SYNCED: ${{ steps.changelog.outputs.synced || 'n/a' }}
+        PR_LABELS: ${{ inputs.pr_labels }}
+        GIT_AUTHOR_NAME: ${{ inputs.git_user_name }}
+        GIT_AUTHOR_EMAIL: ${{ inputs.git_user_email }}
+        GIT_COMMITTER_NAME: ${{ inputs.git_user_name }}
+        GIT_COMMITTER_EMAIL: ${{ inputs.git_user_email }}
       run: |
         "$AUTH_WRAPPER" bash --noprofile --norc -e -o pipefail <<'GITHUB_AUTH_COMMAND'
         set -euo pipefail
         head="chore/release-candidate-$VERSION"
-        # A previous candidate for this version whose PR is closed/merged may
-        # have left its branch behind (repos without "auto-delete head
-        # branches"). create-pull-request would force-push it, which a
-        # no-force-push ruleset rejects. Remove it unless a PR is still open.
-        if git ls-remote --exit-code --heads origin "refs/heads/$head" >/dev/null; then
-          open="$(gh pr list --head "$head" --state open --json number -q 'length')"
-          if [[ "$open" == "0" ]]; then
-            gh api -X DELETE "repos/$GITHUB_REPOSITORY/git/refs/heads/$head" >/dev/null
-            echo "deleted stale branch $head (no open PR)"
-          else
-            echo "$head has an open PR; it will be updated"
-          fi
+        title="chore(release): candidate v$VERSION"
+        default="$(gh repo view "$GITHUB_REPOSITORY" --json defaultBranchRef -q .defaultBranchRef.name)"
+        base="${RELEASE_BRANCH:-$default}"
+        # Open PRs from this repository's $head, as "number<TAB>url" lines.
+        open_prs() {
+          gh pr list --head "$head" --state open --json number,url,isCrossRepository \
+            | python3 -c 'import json,sys; [print(p["number"], p["url"], sep="\t") for p in json.load(sys.stdin) if not p.get("isCrossRepository")]'
+        }
+        remote_head() { git ls-remote --heads origin "refs/heads/$head" | cut -f1; }
+
+        # 1. The candidate commit, local only until the old candidate is gone.
+        git checkout --quiet -B "$head"
+        git add -A
+        if git diff --cached --quiet; then
+          echo "::notice title=Nothing to propose::$base already carries v$VERSION; no candidate PR opened, nothing pushed"
+          echo "pr_url=" >> "$GITHUB_OUTPUT"
+          exit 0
         fi
-        GITHUB_AUTH_COMMAND
+        git commit --quiet -m "$title"
+        candidate="$(git rev-parse HEAD)"
+        echo "candidate commit $candidate on $(git rev-parse HEAD~1)"
 
-    - name: Open candidate PR
-      if: inputs.stage == 'propose'
-      id: pr
-      uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8
-      with:
-        token: ${{ inputs.token }}
-        branch: chore/release-candidate-${{ steps.version.outputs.version }}
-        # Empty means the branch this job checked out, i.e. the default
-        # branch; set, it is the release branch cut above.
-        base: ${{ steps.branch.outputs.release_branch }}
-        delete-branch: true
-        commit-message: "chore(release): candidate v${{ steps.version.outputs.version }}"
-        committer: "${{ inputs.git_user_name }} <${{ inputs.git_user_email }}>"
-        author: "${{ inputs.git_user_name }} <${{ inputs.git_user_email }}>"
-        title: "chore(release): candidate v${{ steps.version.outputs.version }}"
-        labels: ${{ inputs.pr_labels }}
-        body: |
-          Release candidate **v${{ steps.version.outputs.version }}** (was ${{ steps.bump.outputs.old }}).
+        # 2. Close every open candidate PR for this version. One a concurrent
+        #    run or a retry closed first is already where this wants it.
+        open_prs > "$RUNNER_TEMP/candidate-prs.tsv"
+        while IFS=$'\t' read -r number url; do
+          if gh pr close "$number" --comment "Superseded: a fresh candidate for v$VERSION replaces this PR. Its branch \`$head\` is deleted and pushed again as a new ref, never force-pushed." >/dev/null; then
+            echo "closed superseded candidate PR #$number ($url)"
+          elif ! open_prs | cut -f1 | grep -qxF "$number"; then
+            echo "::notice::candidate PR #$number was already closed"
+          else
+            echo "::error::could not close the open candidate PR #$number ($url)"; exit 1
+          fi
+        done < "$RUNNER_TEMP/candidate-prs.tsv"
 
-          ${{ steps.branch.outputs.release_branch && format('Cut from `{0}`, which is not the tip of the default branch: `{1}` already exists at that commit, and merging this PR puts the version bump and the changelog entry on it. The default branch is left untouched — the next candidate syncs this entry back from the tag.', steps.guard.outputs.base, steps.branch.outputs.release_branch) || format('Merging this PR creates the release branch `{0}{1}` at the merge commit.', inputs.release_branch_prefix, steps.version.outputs.version) }}
+        # 3. Delete the old branch, so the push below creates a new ref.
+        racer=""
+        if [[ -n "$(remote_head)" ]]; then
+          if gh api -X DELETE "repos/$GITHUB_REPOSITORY/git/refs/heads/$head" >/dev/null; then
+            echo "deleted the old $head"
+          elif [[ -z "$(remote_head)" ]]; then
+            # 404/422: a retry or a concurrent run already removed it.
+            echo "::notice::$head was already deleted"
+          elif [[ -n "$(open_prs)" ]]; then
+            racer=1
+          else
+            echo "::error::could not delete $head, and no open PR owns it"; exit 1
+          fi
+        fi
 
-          It creates **no tag**; the tag is cut once, at settlement, by `release-settle` → `release-publish`.
+        # 4. Push it as a new ref: a plain push, which never rewrites one. A
+        #    rejection means a concurrent run created $head after the delete;
+        #    its branch is then the candidate and this run only makes sure it
+        #    has a PR.
+        if [[ -z "$racer" ]]; then
+          if git push --quiet origin "$candidate:refs/heads/$head"; then
+            echo "pushed $head at $candidate as a new ref"
+          elif [[ -n "$(remote_head)" ]]; then
+            racer=1
+          else
+            echo "::error::could not push $head"; exit 1
+          fi
+        fi
+        if [[ -n "$racer" ]]; then
+          echo "::notice title=Concurrent candidate::$head was created at $(remote_head) by a concurrent run; keeping it rather than replacing it"
+        fi
 
-          Changelog: this release's entry drafted under `## v${{ steps.version.outputs.version }}` (settle stamps the date on the release branch);
-          previous release's entry synced from its tag: ${{ steps.changelog.outputs.synced || 'n/a' }}.
+        # 5. One open PR on that branch, opened here or by the concurrent run.
+        pr_url="$(open_prs | head -n1 | cut -f2)"
+        if [[ -n "$pr_url" ]]; then
+          echo "::notice::candidate PR $pr_url was opened by a concurrent run"
+        else
+          body="$RUNNER_TEMP/candidate-pr-body.md"
+          {
+            echo "Release candidate **v$VERSION** (was $OLD_VERSION)."
+            echo
+            if [[ -n "$RELEASE_BRANCH" ]]; then
+              echo "Cut from \`$BASE_COMMIT\`, which is not the tip of the default branch: \`$RELEASE_BRANCH\` already exists at that commit, and merging this PR puts the version bump and the changelog entry on it. The default branch is left untouched — the next candidate syncs this entry back from the tag."
+            else
+              echo "Merging this PR creates the release branch \`$PREFIX$VERSION\` at the merge commit."
+            fi
+            echo
+            echo "It creates **no tag**; the tag is cut once, at settlement, by \`release-settle\` → \`release-publish\`."
+            echo
+            echo "Changelog: this release's entry drafted under \`## v$VERSION\` (settle stamps the date on the release branch);"
+            echo "previous release's entry synced from its tag: $SYNCED."
+            echo
+            echo "<!-- release-candidate: v$VERSION -->"
+          } > "$body"
+          if pr_url="$(gh pr create --base "$base" --head "$head" --title "$title" --body-file "$body")"; then
+            echo "opened candidate PR $pr_url"
+            labels=()
+            IFS=',' read -ra wanted <<<"$PR_LABELS"
+            for l in "${wanted[@]}"; do
+              l="${l// /}"
+              [[ -n "$l" ]] && labels+=(-f "labels[]=$l")
+            done
+            if [[ "${#labels[@]}" -gt 0 ]]; then
+              # The issues API creates a label the repository does not have yet.
+              gh api -X POST "repos/$GITHUB_REPOSITORY/issues/${pr_url##*/}/labels" "${labels[@]}" >/dev/null
+            fi
+          else
+            pr_url="$(open_prs | head -n1 | cut -f2)"
+            [[ -n "$pr_url" ]] || { echo "::error::could not open the candidate PR for $head"; exit 1; }
+            echo "::notice::candidate PR $pr_url was opened by a concurrent run"
+          fi
+        fi
+        echo "pr_url=$pr_url" >> "$GITHUB_OUTPUT"
 
-          <!-- release-candidate: v${{ steps.version.outputs.version }} -->
+        # Nothing in this action deletes the branch once the PR merges; say
+        # what does, if anything.
+        if [[ "$(gh api "repos/$GITHUB_REPOSITORY" --jq .delete_branch_on_merge 2>/dev/null || true)" == "true" ]]; then
+          echo "$head is deleted when the PR merges, by the repository's 'Automatically delete head branches' setting"
+        else
+          echo "::notice::$head stays after the PR merges: 'Automatically delete head branches' is off (or not visible to this token). It is never reused; a later propose of v$VERSION deletes it before pushing."
+        fi
+        GITHUB_AUTH_COMMAND
 
     # -------------------------------------------------------------------- cut
     - name: Cut release branch
@@ -419,40 +601,64 @@ runs:
         PREFIX: ${{ inputs.release_branch_prefix }}
         FILE: ${{ inputs.version_file }}
         PATTERN: ${{ inputs.version_pattern }}
-        MERGED: ${{ github.event.pull_request.merged }}
-        MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}
-        PR_NUMBER: ${{ github.event.pull_request.number }}
-        PR_AUTHOR: ${{ github.event.pull_request.user.login }}
-        BASE_REF: ${{ github.event.pull_request.base.ref }}
+        COMMIT: ${{ inputs.commit }}
+        PR_NUMBER: ${{ inputs.pr_number }}
         EXPECTED_AUTHOR: ${{ inputs.pr_author }}
         TOOLS: ${{ github.action_path }}/../release-tools/release_tools.py
       run: |
         "$AUTH_WRAPPER" bash --noprofile --norc -e -o pipefail <<'GITHUB_AUTH_COMMAND'
         set -euo pipefail
-        if [[ "$MERGED" != "true" || -z "$MERGE_SHA" ]]; then
-          echo "::error::cut runs on a merged candidate PR (pull_request closed, merged == true)"; exit 1
+        if [[ -z "$COMMIT" || -z "$PR_NUMBER" ]]; then
+          echo "::error::cut needs the commit and pr_number inputs (the release-route outputs)"; exit 1
+        fi
+        # The PR is re-read through the API: the push event says which commit
+        # landed, not whether it was a merged candidate.
+        pr_json="$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER")"
+        pr_field() { python3 -c 'import functools,json,sys; v=functools.reduce(lambda d,k: d.get(k) if isinstance(d,dict) else None, sys.argv[1].split("."), json.load(sys.stdin)); print("" if v is None else v)' "$1" <<< "$pr_json"; }
+        merged_at="$(pr_field merged_at)"
+        merge_sha="$(pr_field merge_commit_sha)"
+        head_ref="$(pr_field head.ref)"
+        base_ref="$(pr_field base.ref)"
+        pr_author="$(pr_field user.login)"
+        if [[ -z "$merged_at" ]]; then
+          echo "::error::candidate PR #$PR_NUMBER has not been merged; cut only runs for a merged candidate"; exit 1
         fi
-        if [[ -n "$EXPECTED_AUTHOR" && "$PR_AUTHOR" != "$EXPECTED_AUTHOR" ]]; then
-          echo "::error::candidate PR #$PR_NUMBER was opened by '$PR_AUTHOR', not by '$EXPECTED_AUTHOR' (the identity propose runs under); refusing to cut a release branch from it"; exit 1
+        if [[ "$merge_sha" != "$COMMIT" ]]; then
+          echo "::error::candidate PR #$PR_NUMBER merged as '$merge_sha', not the pushed commit '$COMMIT'; refusing to cut a release branch at it"; exit 1
         fi
-        git fetch --quiet origin "$MERGE_SHA"
-        actual="$(git show "$MERGE_SHA:$FILE" | python3 "$TOOLS" read-file /dev/stdin "$PATTERN")"
+        if [[ "$head_ref" != "chore/release-candidate-"* ]]; then
+          echo "::error::PR #$PR_NUMBER head '$head_ref' is not a chore/release-candidate-* branch"; exit 1
+        fi
+        default="$(gh repo view "$GITHUB_REPOSITORY" --json defaultBranchRef -q .defaultBranchRef.name)"
+        if [[ "$base_ref" != "$default" ]]; then
+          echo "::error::candidate PR #$PR_NUMBER targets '$base_ref', not the default branch '$default'; a release branch is cut only from a candidate merged into the default branch"; exit 1
+        fi
+        if [[ -n "$EXPECTED_AUTHOR" && "$pr_author" != "$EXPECTED_AUTHOR" ]]; then
+          echo "::error::candidate PR #$PR_NUMBER was opened by '$pr_author', not by '$EXPECTED_AUTHOR' (the identity propose runs under); refusing to cut a release branch from it"; exit 1
+        fi
+        git fetch --quiet origin "$COMMIT"
+        actual="$(git show "$COMMIT:$FILE" | python3 "$TOOLS" read-file /dev/stdin "$PATTERN")"
         if [[ "$actual" != "$VERSION" ]]; then
-          echo "::error::$FILE at $MERGE_SHA says $actual, expected $VERSION"; exit 1
+          echo "::error::$FILE at $COMMIT says $actual, expected $VERSION"; exit 1
         fi
         branch="${PREFIX}${VERSION}"
-        # A candidate that targeted the release branch was proposed with an
-        # explicit base commit: propose already cut the branch there, this
-        # merge landed the bump on it, and there is nothing left to create.
-        if [[ "$BASE_REF" == "$branch" ]]; then
-          echo "release_branch=$branch" >> "$GITHUB_OUTPUT"
-          echo "::notice title=Release branch already cut::$branch was created by propose at the requested base commit and this candidate merged into it"
-          exit 0
+        # A retry of a cut that already succeeded, or a run that lost the race
+        # to create the ref, finds the branch. At this merge commit it is this
+        # cut, already done; anywhere else it is not ours and is refused.
+        existing="$(git ls-remote --heads origin "refs/heads/$branch" | cut -f1)"
+        if [[ -z "$existing" ]]; then
+          if gh api "repos/$GITHUB_REPOSITORY/git/refs" -f ref="refs/heads/$branch" -f sha="$COMMIT" >/dev/null; then
+            echo "created $branch at $COMMIT"
+          else
+            existing="$(git ls-remote --heads origin "refs/heads/$branch" | cut -f1)"
+            [[ -n "$existing" ]] || { echo "::error::could not create $branch at $COMMIT"; exit 1; }
+          fi
+        fi
+        if [[ -n "$existing" && "$existing" != "$COMMIT" ]]; then
+          echo "::error::branch $branch already exists at $existing, not at the candidate merge commit $COMMIT; refusing to move it"; exit 1
         fi
-        if git ls-remote --exit-code --heads origin "refs/heads/$branch" >/dev/null; then
-          echo "::error::branch $branch already exists"; exit 1
+        if [[ "$existing" == "$COMMIT" ]]; then
+          echo "::notice title=Release branch already cut::$branch already exists at $COMMIT (an earlier or concurrent cut of PR #$PR_NUMBER); nothing to do"
         fi
-        gh api "repos/$GITHUB_REPOSITORY/git/refs" -f ref="refs/heads/$branch" -f sha="$MERGE_SHA" >/dev/null
         echo "release_branch=$branch" >> "$GITHUB_OUTPUT"
-        echo "created $branch at $MERGE_SHA"
         GITHUB_AUTH_COMMAND
diff --git a/.github/actions/release-publish/README.md b/.github/actions/release-publish/README.md
index dcfd5b3..b282bfa 100644
--- a/.github/actions/release-publish/README.md
+++ b/.github/actions/release-publish/README.md
@@ -3,7 +3,7 @@
 `uses: megaeth-labs/.github/.github/actions/release-publish@main`
 
 <!-- generated: description -->
-Publish a settled release. Normally runs when a `chore/release-settle-vX.Y.Z` PR merges into its release branch (or, with `commit` + `version` given, on an explicit commit that `release-settle` in `direct` mode just made): creates the annotated tag `vX.Y.Z` at the merge commit (exactly once — refuses if it exists, or if the branch moved after the settle PR was opened) and publishes the GitHub Release with the changelog section as notes. This is the only place in the release flow that creates a tag; merging the settle PR is the approval. The default branch's changelog catches up in the next release candidate PR — nothing is back-merged. The consumer checks the repository out first (`fetch-depth: 0`, `persist-credentials: false`). Guide: .github/actions/RELEASE.md in megaeth-labs/.github.
+Publish a settled release. Runs on a push to `release-vX.Y.Z` (the consumer passes the `commit` and `pr_number` that `release-route` resolved for the push). Re-verifies the merged `chore/release-settle-vX.Y.Z` PR through the API — merged, merge commit equals the pushed commit, head/base names, author, and the settled-SHA marker against the merge commit's parent — then creates the annotated tag `vX.Y.Z` at that commit and publishes the GitHub Release with the changelog section as notes. A tag already at the commit without a Release (a run that died between the two steps) is resumed: the tag step is skipped and the Release is still created. A tag at the commit with its Release already there is a retry of a finished run and exits 0 with a notice; a tag at any other commit refuses, because a release is published once. A version that is not newer than every other `vX.Y.Z` tag (the rule `release-route` applies) is refused before the tag, and the Release is marked latest only when it is newer than the current latest Release. A tag push or Release create that loses a race to a concurrent run of the same publish keeps the winner's, if it is at this commit. This is the only place in the release flow that creates a tag; merging the settle PR is the approval. The default branch's changelog catches up in the next release candidate PR — nothing is back-merged. The consumer checks the repository out first (`fetch-depth: 0`, `persist-credentials: false`). Guide: .github/actions/RELEASE.md in megaeth-labs/.github.
 <!-- /generated -->
 
 Family: [Release pipeline](../RELEASE.md).
@@ -13,16 +13,16 @@ Family: [Release pipeline](../RELEASE.md).
 <!-- generated: inputs -->
 | Input | Required | Default | Description |
 |---|---|---|---|
-| `token` | yes |  | GitHub App installation token (e.g. the Maxwell app). The tag push must come from it so `push: tags` workflows (artifact builds) fire; the job's GITHUB_TOKEN would not trigger them. Also needs to be a bypass actor on the repository's tag ruleset. |
+| `token` | yes |  | mega-gutenberg installation token minted in an `environment: release` job; gutenberg is the bypass actor on the `v*` tag ruleset, and a Release it creates fires `release: published` workflows. |
 | `version_file` | yes |  | File holding the version (VERSION, Cargo.toml, pyproject.toml, package.json); the same value as in release-candidate. |
 | `version_pattern` | no | `plain` | How the version is stored in `version_file`: plain, toml or json. |
 | `changelog_file` | no | `CHANGELOG.md` | Changelog the entry is written to (Keep-a-Changelog style, newest first). |
 | `release_branch_prefix` | no | `release-v` | Release branch name prefix; the branch is `<prefix>X.Y.Z`. |
-| `commit` | no |  | Explicit commit to publish (full SHA), with `version`. Set by `release-settle` in `direct` mode; leave empty when triggered by the settle PR merging. The PR-specific guards (head/base names, author, drift marker) do not apply in this mode. |
-| `version` | no |  | Version for the explicit-commit mode, X.Y.Z or vX.Y.Z. |
-| `pr_author` | no | `mega-maxwell[bot]` | Login the settle PR must have been opened by — the app identity `release-settle` runs under. Stops a hand-made `chore/release-settle-*` branch from reaching the tag step. Empty disables the check. |
-| `git_user_name` | no | `mega-maxwell[bot]` | Committer identity for the commits this action makes. |
-| `git_user_email` | no | `290560214+mega-maxwell[bot]@users.noreply.github.com` | Committer email for the commits this action makes. |
+| `commit` | yes |  | The pushed commit to publish (full SHA), as resolved by `release-route`; it must be the settle PR's merge commit. |
+| `pr_number` | yes |  | Number of the merged settle PR for `commit`, as resolved by `release-route`. |
+| `pr_author` | no | `mega-gutenberg[bot]` | Login the settle PR must have been opened by — the app identity `release-settle` runs under. Stops a hand-made `chore/release-settle-*` branch from reaching the tag step. Empty disables the check. |
+| `git_user_name` | no | `mega-gutenberg[bot]` | Committer identity for the commits this action makes. |
+| `git_user_email` | no | `348780249+mega-gutenberg[bot]@users.noreply.github.com` | Committer email for the commits this action makes. |
 <!-- /generated -->
 
 ## Outputs
@@ -31,8 +31,8 @@ Family: [Release pipeline](../RELEASE.md).
 | Output | Description |
 |---|---|
 | `version` | The normalised version, X.Y.Z. |
-| `tag` | The tag created, vX.Y.Z. |
-| `release_url` | URL of the GitHub Release. |
+| `tag` | The tag published, vX.Y.Z (created now, or already at the commit from an interrupted run). |
+| `release_url` | URL of the GitHub Release (created now, or found by a retry of a finished run). |
 <!-- /generated -->
 
 ## What it runs
@@ -40,22 +40,26 @@ Family: [Release pipeline](../RELEASE.md).
 <!-- generated: steps -->
 1. Configure git identity
 1. Guard
-1. Create and push tag
-1. Publish GitHub Release
+1. Create and push tag *(only if `steps.guard.outputs.tag_exists != 'true'`)*
+1. Publish GitHub Release *(only if `steps.guard.outputs.published != 'true'`)*
 <!-- /generated -->
 
 ## Errors it reports
 
 <!-- generated: errors -->
-- `explicit mode needs a full 40-hex commit and a version`
-- `publish runs on a merged settle PR (pull_request closed, merged == true)`
+- `publish needs a full 40-hex commit and a numeric pr_number (the release-route outputs)`
+- `settle PR #$PR_NUMBER is not merged; publish only follows a merged settle PR`
+- `settle PR #$PR_NUMBER merged as`
 - `head branch`
 - `settle PR #$PR_NUMBER was opened by`
 - `settle PR for v$version merged into`
 - `settle PR body has no`
 - `release branch drifted: settle PR settled $settled but the branch tip at merge was $parent. Re-run release-settle on the current tip.`
-- `tag v$version already exists; a release is published once`
+- `tag $tag already exists (at $(git rev-parse`
 - `$FILE at $MERGE_SHA says $actual, expected $version`
+- `could not push $TAG; the remote tag is at $(git rev-parse`
+- `cannot read the latest Release to decide whether $TAG is the latest; re-run to resume`
+- `could not create the Release for $TAG`
 <!-- /generated -->
 
 ## Example
@@ -77,11 +81,16 @@ In direct mode `release-settle` calls this action itself with `commit` and
 
 ## Notes
 
-- Creates the annotated tag once (refuses if it exists) at the merge commit
+- Creates the annotated tag once (refuses if it exists elsewhere; resumes or
+  no-ops if it is already at this commit) at the merge commit
   in PR mode — refusing if the merge's first parent is not the settled SHA
   recorded in the PR, or the PR was not opened by `pr_author` — or at
-  `commit` in explicit mode; then publishes the GitHub Release, marked
-  latest, with the changelog section as notes.
+  `commit` in explicit mode; then publishes the GitHub Release with the
+  changelog section as notes, marked latest only when it is newer than the
+  current latest Release.
+- Refuses a version that is not newer than every other `vX.Y.Z` tag (the
+  rule `release-route` applies), in the guard and again right before the tag
+  push; tags that are not `vX.Y.Z` are ignored.
 - The tag push comes from the app token so `push: tags` and `release`
   workflows fire; the app must bypass the `v*` tag ruleset.
 - This workflow must exist on the release branch (it does when the branch
diff --git a/.github/actions/release-publish/action.yml b/.github/actions/release-publish/action.yml
index f265e56..a7763d9 100644
--- a/.github/actions/release-publish/action.yml
+++ b/.github/actions/release-publish/action.yml
@@ -1,14 +1,23 @@
 name: Release Publish
 description: >-
-  Publish a settled release. Normally runs when a `chore/release-settle-vX.Y.Z`
-  PR merges into its release branch (or, with `commit` + `version` given, on
-  an explicit commit that `release-settle` in `direct` mode just made):
-  creates the annotated tag `vX.Y.Z` at the
-  merge commit (exactly once — refuses if it exists, or if the branch moved
-  after the settle PR was opened) and publishes the GitHub Release with the
-  changelog section as notes. This is the only place in the release flow that
-  creates a tag; merging the settle PR is the approval. The default branch's
-  changelog catches up in the next release candidate PR — nothing is
+  Publish a settled release. Runs on a push to `release-vX.Y.Z` (the consumer
+  passes the `commit` and `pr_number` that `release-route` resolved for the
+  push). Re-verifies the merged `chore/release-settle-vX.Y.Z` PR through the
+  API — merged, merge commit equals the pushed commit, head/base names, author,
+  and the settled-SHA marker against the merge commit's parent — then creates
+  the annotated tag `vX.Y.Z` at that commit and publishes the GitHub Release
+  with the changelog section as notes. A tag already at the commit without a
+  Release (a run that died between the two steps) is resumed: the tag step is
+  skipped and the Release is still created. A tag at the commit with its
+  Release already there is a retry of a finished run and exits 0 with a
+  notice; a tag at any other commit refuses, because a release is published
+  once. A version that is not newer than every other `vX.Y.Z` tag (the rule
+  `release-route` applies) is refused before the tag, and the Release is
+  marked latest only when it is newer than the current latest Release. A
+  tag push or Release create that loses a race to a concurrent run of
+  the same publish keeps the winner's, if it is at this commit. This is the only place in the release
+  flow that creates a tag; merging the settle PR is the approval. The default
+  branch's changelog catches up in the next release candidate PR — nothing is
   back-merged. The consumer checks the repository out first
   (`fetch-depth: 0`, `persist-credentials: false`).
   Guide: .github/actions/RELEASE.md in megaeth-labs/.github.
@@ -16,10 +25,9 @@ description: >-
 inputs:
   token:
     description: >-
-      GitHub App installation token (e.g. the Maxwell app). The tag push must
-      come from it so `push: tags` workflows (artifact builds) fire; the job's
-      GITHUB_TOKEN would not trigger them. Also needs to be a bypass actor on
-      the repository's tag ruleset.
+      mega-gutenberg installation token minted in an `environment: release`
+      job; gutenberg is the bypass actor on the `v*` tag ruleset, and a Release
+      it creates fires `release: published` workflows.
     required: true
   version_file:
     description: "File holding the version (VERSION, Cargo.toml, pyproject.toml, package.json); the same value as in release-candidate."
@@ -37,43 +45,37 @@ inputs:
     required: false
     default: release-v
   commit:
-    description: >-
-      Explicit commit to publish (full SHA), with `version`. Set by
-      `release-settle` in `direct` mode; leave empty when triggered by the
-      settle PR merging. The PR-specific guards (head/base names, author,
-      drift marker) do not apply in this mode.
-    required: false
-    default: ""
-  version:
-    description: "Version for the explicit-commit mode, X.Y.Z or vX.Y.Z."
-    required: false
-    default: ""
+    description: "The pushed commit to publish (full SHA), as resolved by `release-route`; it must be the settle PR's merge commit."
+    required: true
+  pr_number:
+    description: "Number of the merged settle PR for `commit`, as resolved by `release-route`."
+    required: true
   pr_author:
     description: >-
       Login the settle PR must have been opened by — the app identity
       `release-settle` runs under. Stops a hand-made `chore/release-settle-*`
       branch from reaching the tag step. Empty disables the check.
     required: false
-    default: "mega-maxwell[bot]"
+    default: "mega-gutenberg[bot]"
   git_user_name:
     description: "Committer identity for the commits this action makes."
     required: false
-    default: "mega-maxwell[bot]"
+    default: "mega-gutenberg[bot]"
   git_user_email:
     description: "Committer email for the commits this action makes."
     required: false
-    default: "290560214+mega-maxwell[bot]@users.noreply.github.com"
+    default: "348780249+mega-gutenberg[bot]@users.noreply.github.com"
 
 outputs:
   version:
     description: "The normalised version, X.Y.Z."
     value: ${{ steps.guard.outputs.version }}
   tag:
-    description: "The tag created, vX.Y.Z."
-    value: ${{ steps.tag.outputs.tag }}
+    description: "The tag published, vX.Y.Z (created now, or already at the commit from an interrupted run)."
+    value: ${{ steps.guard.outputs.tag }}
   release_url:
-    description: "URL of the GitHub Release."
-    value: ${{ steps.release.outputs.url }}
+    description: "URL of the GitHub Release (created now, or found by a retry of a finished run)."
+    value: ${{ steps.release.outputs.url || steps.guard.outputs.release_url }}
 
 runs:
   using: composite
@@ -93,16 +95,10 @@ runs:
       env:
         AUTH_WRAPPER: ${{ github.action_path }}/../git-auth/with-github-auth.sh
         GITHUB_AUTH_TOKEN: ${{ inputs.token }}
-        MERGED: ${{ github.event.pull_request.merged }}
-        HEAD_REF: ${{ github.event.pull_request.head.ref }}
-        BASE_REF: ${{ github.event.pull_request.base.ref }}
-        MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}
-        PR_BODY: ${{ github.event.pull_request.body }}
-        PR_NUMBER: ${{ github.event.pull_request.number }}
-        PR_AUTHOR: ${{ github.event.pull_request.user.login }}
+        GH_TOKEN: ${{ inputs.token }}
+        MERGE_SHA: ${{ inputs.commit }}
+        PR_NUMBER: ${{ inputs.pr_number }}
         EXPECTED_AUTHOR: ${{ inputs.pr_author }}
-        EXPLICIT_COMMIT: ${{ inputs.commit }}
-        EXPLICIT_VERSION: ${{ inputs.version }}
         PREFIX: ${{ inputs.release_branch_prefix }}
         FILE: ${{ inputs.version_file }}
         PATTERN: ${{ inputs.version_pattern }}
@@ -111,89 +107,179 @@ runs:
       run: |
         "$AUTH_WRAPPER" bash --noprofile --norc -e -o pipefail <<'GITHUB_AUTH_COMMAND'
         set -euo pipefail
-        if [[ -n "$EXPLICIT_COMMIT" ]]; then
-          # Explicit-commit mode: release-settle (direct) made this commit a
-          # moment ago and authorised the actor; only the immutability and
-          # content checks below apply.
-          if [[ ! "$EXPLICIT_COMMIT" =~ ^[0-9a-f]{40}$ || -z "$EXPLICIT_VERSION" ]]; then
-            echo "::error::explicit mode needs a full 40-hex commit and a version"; exit 1
-          fi
-          version="$(python3 "$TOOLS" normalize "$EXPLICIT_VERSION")"
-          MERGE_SHA="$EXPLICIT_COMMIT"
-          git fetch --quiet --tags origin "$MERGE_SHA"
-        else
-          if [[ "$MERGED" != "true" || -z "$MERGE_SHA" ]]; then
-            echo "::error::publish runs on a merged settle PR (pull_request closed, merged == true)"; exit 1
-          fi
-          if [[ "$HEAD_REF" != chore/release-settle-v* ]]; then
-            echo "::error::head branch '$HEAD_REF' is not a settle PR"; exit 1
-          fi
-          if [[ -n "$EXPECTED_AUTHOR" && "$PR_AUTHOR" != "$EXPECTED_AUTHOR" ]]; then
-            echo "::error::settle PR #$PR_NUMBER was opened by '$PR_AUTHOR', not by '$EXPECTED_AUTHOR' (the identity release-settle runs under); refusing to publish from it"; exit 1
-          fi
-          version="$(python3 "$TOOLS" normalize "${HEAD_REF#chore/release-settle-}")"
-          if [[ "$BASE_REF" != "${PREFIX}${version}" ]]; then
-            echo "::error::settle PR for v$version merged into '$BASE_REF', expected ${PREFIX}${version}"; exit 1
-          fi
-          git fetch --quiet --tags origin "$MERGE_SHA"
-          # Drift guard: the settle PR recorded which commit was settled. The
-          # merge commit's parent is the release-branch tip at merge time; if
-          # anything landed after the settle PR was opened they differ, and the
-          # changelog no longer describes what is being tagged.
-          settled="$(grep -oE '<!-- release-settle: v[0-9.]+ [0-9a-f]{40} -->' <<<"$PR_BODY" | head -n1 | grep -oE '[0-9a-f]{40}' || true)"
-          if [[ -z "$settled" ]]; then
-            echo "::error::settle PR body has no '<!-- release-settle: ... -->' marker; refusing to publish an unverifiable settlement"; exit 1
+        if [[ ! "$MERGE_SHA" =~ ^[0-9a-f]{40}$ || ! "$PR_NUMBER" =~ ^[0-9]+$ ]]; then
+          echo "::error::publish needs a full 40-hex commit and a numeric pr_number (the release-route outputs)"; exit 1
+        fi
+        # Nothing about the settle PR is taken from the triggering event: the
+        # push only says which commit landed. Everything below is read back
+        # from the API and the repository.
+        pr="$RUNNER_TEMP/settle-pr.json"
+        gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER" > "$pr"
+        pr_field() { # <dotted.path>
+          python3 -c 'import json, sys
+        d = json.load(open(sys.argv[1]))
+        for k in sys.argv[2].split("."):
+            d = (d or {}).get(k)
+        print("" if d is None else d, end="")' "$pr" "$1"
+        }
+        merged_at="$(pr_field merged_at)"
+        pr_merge_sha="$(pr_field merge_commit_sha)"
+        head_ref="$(pr_field head.ref)"
+        base_ref="$(pr_field base.ref)"
+        pr_author="$(pr_field user.login)"
+        pr_body="$(pr_field body)"
+        if [[ -z "$merged_at" ]]; then
+          echo "::error::settle PR #$PR_NUMBER is not merged; publish only follows a merged settle PR"; exit 1
+        fi
+        if [[ "$pr_merge_sha" != "$MERGE_SHA" ]]; then
+          echo "::error::settle PR #$PR_NUMBER merged as '$pr_merge_sha', not the pushed commit $MERGE_SHA"; exit 1
+        fi
+        if [[ "$head_ref" != chore/release-settle-v* ]]; then
+          echo "::error::head branch '$head_ref' is not a settle PR"; exit 1
+        fi
+        if [[ -n "$EXPECTED_AUTHOR" && "$pr_author" != "$EXPECTED_AUTHOR" ]]; then
+          echo "::error::settle PR #$PR_NUMBER was opened by '$pr_author', not by '$EXPECTED_AUTHOR' (the identity release-settle runs under); refusing to publish from it"; exit 1
+        fi
+        version="$(python3 "$TOOLS" normalize "${head_ref#chore/release-settle-}")"
+        if [[ "$base_ref" != "${PREFIX}${version}" ]]; then
+          echo "::error::settle PR for v$version merged into '$base_ref', expected ${PREFIX}${version}"; exit 1
+        fi
+        git fetch --quiet --tags origin "$MERGE_SHA"
+        # Drift guard: the settle PR recorded which commit was settled. The
+        # merge commit's parent is the release-branch tip at merge time; if
+        # anything landed after the settle PR was opened they differ, and the
+        # changelog no longer describes what is being tagged.
+        settled="$(grep -oE '<!-- release-settle: v[0-9.]+ [0-9a-f]{40} -->' <<<"$pr_body" | head -n1 | grep -oE '[0-9a-f]{40}' || true)"
+        if [[ -z "$settled" ]]; then
+          echo "::error::settle PR body has no '<!-- release-settle: ... -->' marker; refusing to publish an unverifiable settlement"; exit 1
+        fi
+        parent="$(git rev-parse "$MERGE_SHA^")"
+        if [[ "$parent" != "$settled" ]]; then
+          echo "::error::release branch drifted: settle PR settled $settled but the branch tip at merge was $parent. Re-run release-settle on the current tip."; exit 1
+        fi
+        # A release is published once, at this commit. A tag already here is
+        # an earlier run of this same publish: without a Release it died
+        # between the two steps and is resumed; with one it finished, and this
+        # run is a no-op. A tag anywhere else refuses.
+        tag="v$version"
+        tag_exists=false
+        published=false
+        release_url=""
+        if git ls-remote --exit-code --tags origin "refs/tags/$tag" >/dev/null; then
+          git fetch --quiet --force origin "refs/tags/$tag:refs/tags/$tag"
+          if [[ "$(git rev-parse "$tag^{commit}")" != "$MERGE_SHA" ]]; then
+            echo "::error::tag $tag already exists (at $(git rev-parse "$tag^{commit}")), not at $MERGE_SHA; a release is published once"; exit 1
           fi
-          parent="$(git rev-parse "$MERGE_SHA^")"
-          if [[ "$parent" != "$settled" ]]; then
-            echo "::error::release branch drifted: settle PR settled $settled but the branch tip at merge was $parent. Re-run release-settle on the current tip."; exit 1
+          tag_exists=true
+          if release_url="$(gh release view "$tag" --json url -q .url 2>/dev/null)"; then
+            published=true
+          else
+            release_url=""
           fi
         fi
-        if git ls-remote --exit-code --tags origin "refs/tags/v$version" >/dev/null; then
-          echo "::error::tag v$version already exists; a release is published once"; exit 1
-        fi
         actual="$(git show "$MERGE_SHA:$FILE" | python3 "$TOOLS" read-file /dev/stdin "$PATTERN")"
         if [[ "$actual" != "$version" ]]; then
           echo "::error::$FILE at $MERGE_SHA says $actual, expected $version"; exit 1
         fi
+        # The rule release-route applies: only a version newer than every
+        # vX.Y.Z tag but its own is published, so an older line merged late
+        # (a v1.2.1 hotfix after v1.3.0) is never tagged or made the latest.
+        if [[ "$published" != true ]]; then
+          latest="$(git ls-remote --tags --refs origin 'refs/tags/v*' | cut -f2 | sed 's#^refs/tags/##' |
+            python3 "$TOOLS" latest-tag --exclude "$version")"
+          if ! refusal="$(python3 "$TOOLS" check-order "$version" "$latest")"; then
+            echo "::error title=Refusing to publish an older version::settle PR #$PR_NUMBER: $refusal"; exit 1
+          fi
+          echo "order check passed: v$version is newer than the latest tag ${latest:-<none>}"
+        fi
         notes="$RUNNER_TEMP/release-notes-v$version.md"
         git show "$MERGE_SHA:$CHANGELOG" > "$RUNNER_TEMP/changelog-at-merge.md"
         python3 "$TOOLS" changelog-extract "$RUNNER_TEMP/changelog-at-merge.md" "$version" > "$notes"
         {
           echo "version=$version"
+          echo "tag=$tag"
+          echo "tag_exists=$tag_exists"
+          echo "published=$published"
+          echo "release_url=$release_url"
           echo "merge_sha=$MERGE_SHA"
           echo "notes_file=$notes"
         } >> "$GITHUB_OUTPUT"
-        echo "publishing v$version at $MERGE_SHA"; echo "--- notes ---"; cat "$notes"
+        if [[ "$published" == true ]]; then
+          echo "::notice title=Already published::$tag is at $MERGE_SHA and its Release exists ($release_url); an earlier run finished, nothing to do"
+          exit 0
+        fi
+        echo "publishing $tag at $MERGE_SHA (tag already there: $tag_exists)"; echo "--- notes ---"; cat "$notes"
         GITHUB_AUTH_COMMAND
 
     - name: Create and push tag
       id: tag
+      if: steps.guard.outputs.tag_exists != 'true'
       shell: bash
       env:
         AUTH_WRAPPER: ${{ github.action_path }}/../git-auth/with-github-auth.sh
         GITHUB_AUTH_TOKEN: ${{ inputs.token }}
-        VERSION: ${{ steps.guard.outputs.version }}
+        TAG: ${{ steps.guard.outputs.tag }}
         MERGE_SHA: ${{ steps.guard.outputs.merge_sha }}
+        TOOLS: ${{ github.action_path }}/../release-tools/release_tools.py
       run: |
         "$AUTH_WRAPPER" bash --noprofile --norc -e -o pipefail <<'GITHUB_AUTH_COMMAND'
         set -euo pipefail
-        tag="v$VERSION"
-        git tag -a "$tag" "$MERGE_SHA" -m "Release $tag"
-        git push --quiet origin "refs/tags/$tag"
-        echo "tag=$tag" >> "$GITHUB_OUTPUT"
-        echo "tagged $MERGE_SHA as $tag"
+        # Re-check the order now, right before the tag exists: another release
+        # line publishes under its own concurrency group and may have won.
+        latest="$(git ls-remote --tags --refs origin 'refs/tags/v*' | cut -f2 | sed 's#^refs/tags/##' |
+          python3 "$TOOLS" latest-tag --exclude "$TAG")"
+        if ! refusal="$(python3 "$TOOLS" check-order "$TAG" "$latest")"; then
+          echo "::error title=Refusing to publish an older version::not tagging $MERGE_SHA: $refusal (tagged since the guard ran)"; exit 1
+        fi
+        git tag -a "$TAG" "$MERGE_SHA" -m "Release $TAG"
+        if git push --quiet origin "refs/tags/$TAG"; then
+          echo "tagged $MERGE_SHA as $TAG"
+        else
+          # A concurrent publish of the same merge pushed first: its tag is
+          # as good as ours. A tag at any other commit is not.
+          git fetch --quiet --force origin "refs/tags/$TAG:refs/tags/$TAG"
+          if [[ "$(git rev-parse "$TAG^{commit}")" != "$MERGE_SHA" ]]; then
+            echo "::error::could not push $TAG; the remote tag is at $(git rev-parse "$TAG^{commit}"), not $MERGE_SHA"; exit 1
+          fi
+          echo "::notice::$TAG was pushed at $MERGE_SHA by a concurrent run; keeping it"
+        fi
         GITHUB_AUTH_COMMAND
 
     - name: Publish GitHub Release
       id: release
+      if: steps.guard.outputs.published != 'true'
       shell: bash
       env:
         GH_TOKEN: ${{ inputs.token }}
-        TAG: ${{ steps.tag.outputs.tag }}
+        TAG: ${{ steps.guard.outputs.tag }}
         NOTES: ${{ steps.guard.outputs.notes_file }}
+        TOOLS: ${{ github.action_path }}/../release-tools/release_tools.py
       run: |
         set -euo pipefail
-        url="$(gh release create "$TAG" --verify-tag --latest --title "$TAG" --notes-file "$NOTES")"
+        # Mark the Release latest only if it is newer than the Release GitHub
+        # calls latest now (a concurrent publish of a newer line may have won).
+        if current="$(gh api "repos/$GITHUB_REPOSITORY/releases/latest" --jq .tag_name 2>"$RUNNER_TEMP/latest-release.err")"; then
+          :
+        elif grep -qF "HTTP 404" "$RUNNER_TEMP/latest-release.err"; then
+          current=""
+        else
+          cat "$RUNNER_TEMP/latest-release.err" >&2
+          echo "::error::cannot read the latest Release to decide whether $TAG is the latest; re-run to resume"; exit 1
+        fi
+        # A latest Release whose tag is not vX.Y.Z cannot be ordered: ignore it.
+        current="$(python3 "$TOOLS" latest-tag <<< "$current")"
+        if refusal="$(python3 "$TOOLS" check-order "$TAG" "$current")"; then
+          latest_flag=--latest
+          echo "marking $TAG latest: newer than the latest Release ${current:-<none>} (rule: latest only when newer than the latest Release)"
+        else
+          latest_flag=--latest=false
+          echo "::warning title=Not the latest Release::$TAG is published without becoming latest: $refusal (rule: latest only when newer than the latest Release)"
+        fi
+        if ! url="$(gh release create "$TAG" --verify-tag "$latest_flag" --title "$TAG" --notes-file "$NOTES")"; then
+          # A concurrent publish created it first; that Release is this one.
+          url="$(gh release view "$TAG" --json url -q .url)" \
+            || { echo "::error::could not create the Release for $TAG"; exit 1; }
+          echo "::notice::the Release for $TAG was created by a concurrent run; keeping it"
+        fi
         echo "url=$url" >> "$GITHUB_OUTPUT"
         echo "release: $url"
diff --git a/.github/actions/release-route/README.md b/.github/actions/release-route/README.md
new file mode 100644
index 0000000..89e27b4
--- /dev/null
+++ b/.github/actions/release-route/README.md
@@ -0,0 +1,72 @@
+# Release Route
+
+`uses: megaeth-labs/.github/.github/actions/release-route@main`
+
+<!-- generated: description -->
+Route a push or manual dispatch to cut, refresh, publish or skip using merged release PR metadata. Read-only; uses the job token, not a release App secret. Requires a checkout with full history and persist-credentials disabled.
+<!-- /generated -->
+
+Family: [Release pipeline](../RELEASE.md).
+
+## Inputs
+
+<!-- generated: inputs -->
+| Input | Required | Default | Description |
+|---|---|---|---|
+| `kind` | yes |  | Release flow to route: candidate or settle. |
+| `github_token` | no | `${{ github.token }}` | Read-only job token with contents and pull-requests read. |
+| `pr_author` | no | `mega-gutenberg[bot]` | Expected author of candidate and settle PRs. |
+| `version_file` | yes |  | File holding the release version. |
+| `version_pattern` | no | `plain` | Version file format: plain, toml or json. |
+| `release_branch_prefix` | no | `release-v` | Release branch prefix before X.Y.Z. |
+| `version` | no |  | Optional version filter for manual dispatch. |
+<!-- /generated -->
+
+## Outputs
+
+<!-- generated: outputs -->
+| Output | Description |
+|---|---|
+| `action` | Next action: cut, refresh, publish or skip. |
+| `reason` | Why this action was selected. |
+| `version` | Normalized release version, when routing one push. |
+| `release_branch` | Release branch for the pushed version. |
+| `commit` | Pushed commit for cut, refresh or publish. |
+| `pr_number` | Merged release PR number, when matched. |
+| `targets` | Compact JSON array of refresh targets. |
+<!-- /generated -->
+
+## What it runs
+
+<!-- generated: steps -->
+1. Route
+<!-- /generated -->
+
+## Errors it reports
+
+<!-- generated: errors -->
+- `release-route needs full history; check out with fetch-depth: 0`
+<!-- /generated -->
+
+## Example
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+    persist-credentials: false
+- uses: megaeth-labs/.github/.github/actions/release-route@main
+  id: route
+  with:
+    kind: settle
+    version_file: VERSION
+```
+
+## Notes
+
+The calling job needs `contents: read` and `pull-requests: read`.
+
+A push to a `release_branch_prefix` branch whose suffix is not `X.Y.Z` (for
+example `release-vnext`) routes to `skip` with a reason naming the branch; a
+manual dispatch leaves such branches out of `targets`. Input the route cannot
+read fails the step with a `Release route` error annotation.
diff --git a/.github/actions/release-route/action.yml b/.github/actions/release-route/action.yml
new file mode 100644
index 0000000..674cbb8
--- /dev/null
+++ b/.github/actions/release-route/action.yml
@@ -0,0 +1,191 @@
+name: Release Route
+description: >-
+  Route a push or manual dispatch to cut, refresh, publish or skip using merged
+  release PR metadata. Read-only; uses the job token, not a release App secret.
+  Requires a checkout with full history and persist-credentials disabled.
+
+inputs:
+  kind:
+    description: "Release flow to route: candidate or settle."
+    required: true
+  github_token:
+    description: "Read-only job token with contents and pull-requests read."
+    default: ${{ github.token }}
+  pr_author:
+    description: "Expected author of candidate and settle PRs."
+    default: "mega-gutenberg[bot]"
+  version_file:
+    description: "File holding the release version."
+    required: true
+  version_pattern:
+    description: "Version file format: plain, toml or json."
+    default: plain
+  release_branch_prefix:
+    description: "Release branch prefix before X.Y.Z."
+    default: release-v
+  version:
+    description: "Optional version filter for manual dispatch."
+    default: ""
+
+outputs:
+  action:
+    description: "Next action: cut, refresh, publish or skip."
+    value: ${{ steps.route.outputs.action }}
+  reason:
+    description: "Why this action was selected."
+    value: ${{ steps.route.outputs.reason }}
+  version:
+    description: "Normalized release version, when routing one push."
+    value: ${{ steps.route.outputs.version }}
+  release_branch:
+    description: "Release branch for the pushed version."
+    value: ${{ steps.route.outputs.release_branch }}
+  commit:
+    description: "Pushed commit for cut, refresh or publish."
+    value: ${{ steps.route.outputs.commit }}
+  pr_number:
+    description: "Merged release PR number, when matched."
+    value: ${{ steps.route.outputs.pr_number }}
+  targets:
+    description: "Compact JSON array of refresh targets."
+    value: ${{ steps.route.outputs.targets }}
+
+runs:
+  using: composite
+  steps:
+    - name: Route
+      id: route
+      shell: bash
+      env:
+        AUTH_WRAPPER: ${{ github.action_path }}/../git-auth/with-github-auth.sh
+        GITHUB_AUTH_TOKEN: ${{ inputs.github_token }}
+        GH_TOKEN: ${{ inputs.github_token }}
+        KIND: ${{ inputs.kind }}
+        DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        EXPECTED_AUTHOR: ${{ inputs.pr_author }}
+        FILE: ${{ inputs.version_file }}
+        PATTERN: ${{ inputs.version_pattern }}
+        PREFIX: ${{ inputs.release_branch_prefix }}
+        DISPATCH_VERSION: ${{ inputs.version }}
+        TOOLS: ${{ github.action_path }}/../release-tools/release_tools.py
+      run: |
+        "$AUTH_WRAPPER" bash --noprofile --norc -e -o pipefail <<'GITHUB_AUTH_COMMAND'
+        set -euo pipefail
+        if [[ "$(git rev-parse --is-shallow-repository)" == true ]]; then
+          echo "::error::release-route needs full history; check out with fetch-depth: 0"; exit 1
+        fi
+        git rev-parse --verify HEAD >/dev/null
+        default="${DEFAULT_BRANCH:-}"
+        if [[ -z "$default" ]]; then
+          default="$(gh repo view "$GITHUB_REPOSITORY" --json defaultBranchRef -q .defaultBranchRef.name)"
+        fi
+        git fetch --quiet --tags origin
+        # Only vX.Y.Z tags are releases; release_tools names and ignores the
+        # rest (v1.2.0-rc1), so such a tag can neither be "the latest" nor fail the route.
+        latest="$(git tag -l 'v*' | python3 "$TOOLS" latest-tag)"
+        pulls='[]'; branches='[]'; parent=""; actual=""; tag_commit=""
+        tag_exists=false; release_exists=false
+        # Exit 2 means no matching tag, not a failed remote read.
+        has_tag() {
+          local status
+          if git ls-remote --exit-code --tags origin "refs/tags/$1" >/dev/null; then
+            return 0
+          else
+            status=$?
+            [[ "$status" == 2 ]] || exit "$status"
+            return 1
+          fi
+        }
+        # Sets $actual to the version at <commit>. A version file that is
+        # missing or does not parse is a configuration error, not a candidate
+        # that has not landed yet, so it fails the route instead of skipping.
+        read_version() { # <commit> <where>
+          local text
+          if ! text="$(git show "$1:$FILE" 2>/dev/null)"; then
+            echo "::error title=Release route::cannot read the version file: $FILE does not exist at $1 ($2); version_file '$FILE' and version_pattern '$PATTERN' must match the release-settle step"
+            exit 1
+          fi
+          if ! actual="$(python3 "$TOOLS" read-file /dev/stdin "$PATTERN" <<< "$text")"; then
+            echo "::error title=Release route::cannot read the version file: $FILE at $1 ($2) does not parse with version_pattern '$PATTERN'; version_file and version_pattern must match the release-settle step"
+            exit 1
+          fi
+        }
+        if [[ "$GITHUB_EVENT_NAME" == push ]]; then
+          parent="$(git rev-parse --verify "$GITHUB_SHA^" 2>/dev/null || true)"
+          pulls="$(gh api --paginate "repos/$GITHUB_REPOSITORY/commits/$GITHUB_SHA/pulls" |
+            jq -ces 'if all(.[]; type == "array") then add else error("pulls API must return arrays") end')"
+          # route skips and names a prefix branch whose suffix is not X.Y.Z.
+          if [[ "$KIND" == settle && "$GITHUB_REF_NAME" == "$PREFIX"* ]] &&
+              version="$(python3 "$TOOLS" normalize "${GITHUB_REF_NAME#"$PREFIX"}" 2>/dev/null)"; then
+            tag="v$version"
+            # This version's own tag (a publication resuming) is not "newer".
+            latest="$(git tag -l 'v*' | python3 "$TOOLS" latest-tag --exclude "$version")"
+            if has_tag "$tag"; then
+              tag_exists=true
+              tag_commit="$(git ls-remote origin "refs/tags/$tag^{}" | cut -f1)"
+              if [[ -z "$tag_commit" ]]; then
+                tag_commit="$(git ls-remote origin "refs/tags/$tag" | cut -f1)"
+              fi
+              if gh release view "$tag" --json tagName >/dev/null 2>&1; then release_exists=true; fi
+            fi
+            if [[ "$release_exists" == false ]]; then
+              read_version "$GITHUB_SHA" "$GITHUB_REF_NAME"
+            fi
+            if [[ "$pulls" == '[]' ]]; then
+              pulls="$(gh pr list --state merged --base "$GITHUB_REF_NAME" \
+                --head "chore/release-settle-v$version" \
+                --json number,mergeCommit,headRefName,baseRefName,author,body,mergedAt |
+                jq -ce 'if type != "array" then error("pr list must return an array") else
+                  map({number, merge_commit_sha: .mergeCommit.oid, merged_at: .mergedAt,
+                    head: {ref: .headRefName}, base: {ref: .baseRefName},
+                    user: {login: .author.login}, body}) end')"
+            fi
+          fi
+        elif [[ "$KIND" == settle && "$GITHUB_EVENT_NAME" == workflow_dispatch ]]; then
+          heads="$(git ls-remote --heads origin "refs/heads/${PREFIX}*")"
+          while read -r tip ref; do
+            [[ -n "$tip" ]] || continue
+            branch="${ref#refs/heads/}"
+            if ! version="$(python3 "$TOOLS" normalize "${branch#"$PREFIX"}" 2>/dev/null)"; then
+              echo "::notice title=Release route::skipping $branch: not $PREFIX<X.Y.Z>"; continue
+            fi
+            git fetch --quiet origin "$tip"
+            tagged=false; actual=""
+            if has_tag "v$version"; then tagged=true; else read_version "$tip" "$branch"; fi
+            branches="$(jq -c --arg name "$branch" --arg tip "$tip" --arg actual "$actual" \
+              --argjson tagged "$tagged" \
+              '. + [{name: $name, tip: $tip, version_at_tip: (if $actual == "" then null else $actual end), tag_exists: $tagged}]' <<< "$branches")"
+          done <<< "$heads"
+        fi
+        if ! decision="$(jq -n --arg kind "$KIND" --arg event "$GITHUB_EVENT_NAME" \
+          --arg sha "$GITHUB_SHA" --arg first_parent "$parent" --arg ref_name "$GITHUB_REF_NAME" \
+          --arg default_branch "$default" --arg prefix "$PREFIX" --arg pr_author "$EXPECTED_AUTHOR" \
+          --arg version_at_sha "$actual" --arg latest_tag "$latest" --arg dispatch_version "$DISPATCH_VERSION" \
+          --arg tag_commit "$tag_commit" --argjson pulls "$pulls" --argjson branches "$branches" \
+          --argjson tag_exists "$tag_exists" --argjson release_exists "$release_exists" \
+          '{kind: $kind, event: $event, sha: $sha, first_parent: $first_parent,
+            ref_name: $ref_name, default_branch: $default_branch, prefix: $prefix, pr_author: $pr_author,
+            version_at_sha: (if $version_at_sha == "" then null else $version_at_sha end),
+            latest_tag: $latest_tag, dispatch_version: $dispatch_version,
+            tag_commit: (if $tag_commit == "" then null else $tag_commit end),
+            pulls: $pulls, branches: $branches, tag_exists: $tag_exists, release_exists: $release_exists}' |
+          python3 "$TOOLS" route)"; then
+          echo "::error title=Release route::cannot route $KIND $GITHUB_EVENT_NAME on $GITHUB_REF_NAME; see the release_tools error above"
+          exit 1
+        fi
+        # Multiline output framing also keeps API-supplied reasons from becoming output keys.
+        while read -r key; do
+          delimiter="route_$(openssl rand -hex 16)"
+          {
+            echo "$key<<$delimiter"
+            jq -r --arg key "$key" '.[$key] | if type == "array" then tojson elif . == null then "" else . end' <<< "$decision"
+            echo "$delimiter"
+          } >> "$GITHUB_OUTPUT"
+        done < <(jq -r 'keys[]' <<< "$decision")
+        action="$(jq -r .action <<< "$decision")"
+        reason="$(jq -r .reason <<< "$decision")"
+        if [[ "$action" == skip && "$tag_exists" == true && "$release_exists" == false ]]; then
+          echo "::warning::$reason"
+        fi
+        echo "::notice title=Release route::$action: $reason"
+        GITHUB_AUTH_COMMAND
diff --git a/.github/actions/release-settle/README.md b/.github/actions/release-settle/README.md
index b642bf2..fde81d2 100644
--- a/.github/actions/release-settle/README.md
+++ b/.github/actions/release-settle/README.md
@@ -3,7 +3,7 @@
 `uses: megaeth-labs/.github/.github/actions/release-settle@main`
 
 <!-- generated: description -->
-Propose settling a release candidate: verify `commit` is the tip of the release branch and carries the expected version, generate release notes from the commits since the previous tag, write them into the changelog (stamping the date onto the candidate's `## vX.Y.Z` entry), and — in the default `pr` mode — open a `chore/release-settle-vX.Y.Z` PR onto the release branch; merging that PR is the settlement decision and release-publish then tags the merge commit once. In `direct` mode the dispatch itself is the decision, gated by the `release` environment the consumer puts on the settle job (optionally also by `settlers`); the changelog commit is pushed straight to the release branch (the app must be a bypass actor on that branch's ruleset), and release-publish runs immediately on that commit. Run as a step in a job the consumer owns; the consumer checks the repository out first (`fetch-depth: 0`, `persist-credentials: false`). Needs `gh` and `python3` on the runner. Guide: .github/actions/RELEASE.md in megaeth-labs/.github.
+Maintain a settle PR for a release candidate: verify `commit` is the tip of the release branch and carries the expected version, generate release notes from the commits since the previous tag, write them into the changelog (stamping the date onto the candidate's `## vX.Y.Z` entry), and open or refresh a `chore/release-settle-vX.Y.Z` PR onto the release branch without rewriting its history. New commits on the release branch refresh this PR automatically; merging it is the settlement decision and release-publish then tags the merge commit once. Run as a step in a job the consumer owns; consumer checks the repository out first (`fetch-depth: 0`, `persist-credentials: false`). Needs `gh` and `python3` on the runner. Guide: .github/actions/RELEASE.md in megaeth-labs/.github.
 <!-- /generated -->
 
 Family: [Release pipeline](../RELEASE.md).
@@ -13,7 +13,7 @@ Family: [Release pipeline](../RELEASE.md).
 <!-- generated: inputs -->
 | Input | Required | Default | Description |
 |---|---|---|---|
-| `token` | yes |  | GitHub App installation token (e.g. the Maxwell app). Pushes the settle branch and opens the PR so that it triggers CI. |
+| `token` | yes |  | mega-gutenberg GitHub App installation token. Pushes the settle branch and opens or refreshes the PR so that it triggers CI. |
 | `version` | yes |  | Version being settled, X.Y.Z or vX.Y.Z. |
 | `commit` | yes |  | Full SHA to settle. Must be the current tip of the release branch: the settlement is a statement about a specific commit, and the tip is the only commit a later merge can build on. |
 | `version_file` | yes |  | File holding the version (VERSION, Cargo.toml, pyproject.toml, package.json); the same value as in release-candidate. |
@@ -21,12 +21,10 @@ Family: [Release pipeline](../RELEASE.md).
 | `release_branch` | no |  | Defaults to `<release_branch_prefix>X.Y.Z`. |
 | `release_branch_prefix` | no | `release-v` | Release branch name prefix; the branch is `<prefix>X.Y.Z`. |
 | `changelog_file` | no | `CHANGELOG.md` | Changelog the entry is written to (Keep-a-Changelog style, newest first). |
-| `settle_mode` | no | `pr` | `pr` (default): open a settle PR. `direct`: settle and publish now, from this dispatch. |
-| `settlers` | no | `any` | Who may settle in `direct` mode. `any` (default): no actor check — the settle job's `release` environment and its required reviewers are the gate, so use it only with `environment:` on that job. Otherwise a comma-separated list of GitHub logins and/or the keyword `admin` (the dispatching actor must have admin permission on the repository, checked with `github_token`), as an extra restriction on who may start a settle. |
-| `github_token` | no | `${{ github.token }}` | Job token used for the `admin` permission check in `direct` mode. |
+| `pr_author` | no | `mega-gutenberg[bot]` | Author of the bot-maintained settle PR; PRs by other authors are superseded. |
 | `pr_labels` | no |  | Comma-separated labels for the settle PR (for repos whose label gates apply to release branches too). |
-| `git_user_name` | no | `mega-maxwell[bot]` | Committer identity for the commits this action makes. |
-| `git_user_email` | no | `290560214+mega-maxwell[bot]@users.noreply.github.com` | Committer email for the commits this action makes. |
+| `git_user_name` | no | `mega-gutenberg[bot]` | Committer identity for the commits this action makes. |
+| `git_user_email` | no | `348780249+mega-gutenberg[bot]@users.noreply.github.com` | Committer email for the commits this action makes. |
 <!-- /generated -->
 
 ## Outputs
@@ -37,9 +35,6 @@ Family: [Release pipeline](../RELEASE.md).
 | `version` | The normalised version, X.Y.Z. |
 | `pr_url` | URL of the settle PR. |
 | `notes_file` | Path of the generated release-notes markdown. |
-| `settled_commit` | `direct` mode: the changelog commit that was tagged. |
-| `tag` | `direct` mode: the tag created. |
-| `release_url` | `direct` mode: the GitHub Release created. |
 <!-- /generated -->
 
 ## What it runs
@@ -48,11 +43,8 @@ Family: [Release pipeline](../RELEASE.md).
 1. Configure git identity
 1. Guard
 1. Compare workflows with the default branch
-1. Authorise the settler (direct mode) *(only if `inputs.settle_mode == 'direct'`)*
 1. Generate release notes
-1. Write changelog and open settle PR *(only if `inputs.settle_mode != 'direct'`)*
-1. Write changelog onto the release branch (direct mode) *(only if `inputs.settle_mode == 'direct'`)*
-1. Tag and publish (direct mode) — `megaeth-labs/.github/.github/actions/release-publish` *(only if `inputs.settle_mode == 'direct'`)*
+1. Ensure the settle PR
 <!-- /generated -->
 
 ## Errors it reports
@@ -64,9 +56,11 @@ Family: [Release pipeline](../RELEASE.md).
 - `$COMMIT is not the tip of $branch (tip is $tip). Settle the tip, or move the branch first.`
 - `$FILE at $COMMIT says $actual, expected $version`
 - `$version is not newer than the latest tag ${latest:-<none>}`
-- `$ACTOR is not authorised to settle directly (settlers: $SETTLERS)`
-- `$CHANGELOG already carries exactly this v$VERSION entry; nothing to settle`
-- `could not push the settle commit to $BRANCH — the branch moved since $COMMIT, or the app is not a bypass actor on its ruleset`
+- `settle PR not ensured; stopped while $stage`
+- `$BRANCH moved to ${tip:-<deleted>} after this refresh of $COMMIT started (a settle PR merge or a new push); not touching the settle PR, the run for the new tip refreshes it`
+- `could not merge $COMMIT into $head; close the settle PR so the next run recreates it`
+- `$head was taken by a concurrent run but no open settle PR is visible yet; re-run this workflow`
+- `settle PR not ensured after $attempt attempts of racing a concurrent run; re-run this workflow`
 <!-- /generated -->
 
 ## Example
@@ -103,7 +97,15 @@ instead.
   additionally checks the dispatcher. The dated entry is committed straight
   onto the release branch (the app must bypass its ruleset) and
   `release-publish` runs in the same job with `commit` and `version` set.
-- `pr`: pushes `chore/release-settle-vX.Y.Z` and opens the settle PR. A
-  re-run closes the previous settle PR, deletes its branch and pushes a fresh
-  one; nothing is force-pushed.
+- `pr`: pushes `chore/release-settle-vX.Y.Z` and opens the settle PR,
+  titled `chore(release): settle vX.Y.Z — merging publishes the release`.
+  Its body opens with an `[!IMPORTANT]` alert saying that merging it settles
+  the release, followed by the `<!-- release-settle: vX.Y.Z <sha> -->`
+  marker that `release-route` and `release-publish` read. A new tip on the
+  release branch merges into the same PR and moves the marker; a re-run
+  with nothing new changes nothing. Only a PR that is closed, merged or not
+  authored by `pr_author` is replaced by a fresh branch. Nothing is
+  force-pushed, and the branch is pushed only after the merge and the
+  changelog commit both succeed. A run that loses a race with a concurrent
+  run refreshes the PR that run opened.
 - The full flow, installation and recovery: [RELEASE.md](../RELEASE.md).
diff --git a/.github/actions/release-settle/action.yml b/.github/actions/release-settle/action.yml
index 4efd64a..1778556 100644
--- a/.github/actions/release-settle/action.yml
+++ b/.github/actions/release-settle/action.yml
@@ -1,16 +1,13 @@
 name: Release Settle
 description: >-
-  Propose settling a release candidate: verify `commit` is the tip of the
+  Maintain a settle PR for a release candidate: verify `commit` is the tip of the
   release branch and carries the expected version, generate release notes from
   the commits since the previous tag, write them into the changelog (stamping
-  the date onto the candidate's `## vX.Y.Z` entry), and — in the default
-  `pr` mode — open a `chore/release-settle-vX.Y.Z` PR onto the release
-  branch; merging that PR is the settlement decision and release-publish
-  then tags the merge commit once. In `direct` mode the dispatch itself is
-  the decision, gated by the `release` environment the consumer puts on the
-  settle job (optionally also by `settlers`); the changelog commit is pushed
-  straight to the release branch (the app must be a bypass actor on that
-  branch's ruleset), and release-publish runs immediately on that commit. Run as a step in a job the consumer owns; the
+  the date onto the candidate's `## vX.Y.Z` entry), and open or refresh a
+  `chore/release-settle-vX.Y.Z` PR onto the release branch without rewriting
+  its history. New commits on the release branch refresh this PR automatically;
+  merging it is the settlement decision and release-publish then tags the merge
+  commit once. Run as a step in a job the consumer owns;
   consumer checks the repository out first (`fetch-depth: 0`,
   `persist-credentials: false`). Needs `gh` and `python3` on the runner.
   Guide: .github/actions/RELEASE.md in megaeth-labs/.github.
@@ -18,8 +15,8 @@ description: >-
 inputs:
   token:
     description: >-
-      GitHub App installation token (e.g. the Maxwell app). Pushes the settle
-      branch and opens the PR so that it triggers CI.
+      mega-gutenberg GitHub App installation token. Pushes the settle branch
+      and opens or refreshes the PR so that it triggers CI.
     required: true
   version:
     description: "Version being settled, X.Y.Z or vX.Y.Z."
@@ -49,25 +46,10 @@ inputs:
     description: "Changelog the entry is written to (Keep-a-Changelog style, newest first)."
     required: false
     default: CHANGELOG.md
-  settle_mode:
-    description: "`pr` (default): open a settle PR. `direct`: settle and publish now, from this dispatch."
+  pr_author:
+    description: "Author of the bot-maintained settle PR; PRs by other authors are superseded."
     required: false
-    default: pr
-  settlers:
-    description: >-
-      Who may settle in `direct` mode. `any` (default): no actor check — the
-      settle job's `release` environment and its required reviewers are the
-      gate, so use it only with `environment:` on that job. Otherwise a
-      comma-separated list of GitHub logins and/or the keyword `admin` (the
-      dispatching actor must have admin permission on the repository, checked
-      with `github_token`), as an extra restriction on who may start a
-      settle.
-    required: false
-    default: any
-  github_token:
-    description: "Job token used for the `admin` permission check in `direct` mode."
-    required: false
-    default: ${{ github.token }}
+    default: "mega-gutenberg[bot]"
   pr_labels:
     description: "Comma-separated labels for the settle PR (for repos whose label gates apply to release branches too)."
     required: false
@@ -75,11 +57,11 @@ inputs:
   git_user_name:
     description: "Committer identity for the commits this action makes."
     required: false
-    default: "mega-maxwell[bot]"
+    default: "mega-gutenberg[bot]"
   git_user_email:
     description: "Committer email for the commits this action makes."
     required: false
-    default: "290560214+mega-maxwell[bot]@users.noreply.github.com"
+    default: "348780249+mega-gutenberg[bot]@users.noreply.github.com"
 
 outputs:
   version:
@@ -91,15 +73,6 @@ outputs:
   notes_file:
     description: Path of the generated release-notes markdown.
     value: ${{ steps.notes.outputs.notes_file }}
-  settled_commit:
-    description: "`direct` mode: the changelog commit that was tagged."
-    value: ${{ steps.direct.outputs.commit }}
-  tag:
-    description: "`direct` mode: the tag created."
-    value: ${{ steps.publish.outputs.tag }}
-  release_url:
-    description: "`direct` mode: the GitHub Release created."
-    value: ${{ steps.publish.outputs.release_url }}
 
 runs:
   using: composite
@@ -147,7 +120,7 @@ runs:
         if [[ "$actual" != "$version" ]]; then
           echo "::error::$FILE at $COMMIT says $actual, expected $version"; exit 1
         fi
-        latest="$(git tag -l 'v*' --sort=-v:refname | head -n1 || true)"
+        latest="$(git tag -l 'v*' | python3 "$TOOLS" latest-tag)"
         if ! python3 "$TOOLS" is-greater "$version" "$latest"; then
           echo "::error::$version is not newer than the latest tag ${latest:-<none>}"; exit 1
         fi
@@ -188,37 +161,6 @@ runs:
         fi
         GITHUB_AUTH_COMMAND
 
-    - name: Authorise the settler (direct mode)
-      if: inputs.settle_mode == 'direct'
-      shell: bash
-      env:
-        GH_TOKEN: ${{ inputs.github_token }}
-        ACTOR: ${{ github.actor }}
-        SETTLERS: ${{ inputs.settlers }}
-        MODE: ${{ inputs.settle_mode }}
-      run: |
-        set -euo pipefail
-        if [[ -z "$SETTLERS" || "$SETTLERS" == "any" ]]; then
-          echo "settlers: any — no actor check; the settle job's environment reviewers are the gate"
-          exit 0
-        fi
-        ok=false
-        IFS=',' read -ra entries <<<"$SETTLERS"
-        for e in "${entries[@]}"; do
-          e="${e// /}"
-          [[ -z "$e" ]] && continue
-          if [[ "$e" == "admin" ]]; then
-            perm="$(gh api "repos/$GITHUB_REPOSITORY/collaborators/$ACTOR/permission" -q .permission 2>/dev/null || true)"
-            [[ "$perm" == "admin" ]] && ok=true
-          elif [[ "$e" == "$ACTOR" ]]; then
-            ok=true
-          fi
-        done
-        if [[ "$ok" != true ]]; then
-          echo "::error::$ACTOR is not authorised to settle directly (settlers: $SETTLERS)"; exit 1
-        fi
-        echo "direct settle authorised for $ACTOR"
-
     - name: Generate release notes
       id: notes
       shell: bash
@@ -237,8 +179,7 @@ runs:
         echo "notes_file=$notes" >> "$GITHUB_OUTPUT"
         echo "--- release notes ---"; cat "$notes"
 
-    - name: Write changelog and open settle PR
-      if: inputs.settle_mode != 'direct'
+    - name: Ensure the settle PR
       id: pr
       shell: bash
       env:
@@ -251,96 +192,169 @@ runs:
         CHANGELOG: ${{ inputs.changelog_file }}
         NOTES: ${{ steps.notes.outputs.notes_file }}
         PR_LABELS: ${{ inputs.pr_labels }}
+        PR_AUTHOR: ${{ inputs.pr_author }}
         TOOLS: ${{ github.action_path }}/../release-tools/release_tools.py
       run: |
         "$AUTH_WRAPPER" bash --noprofile --norc -e -o pipefail <<'GITHUB_AUTH_COMMAND'
         set -euo pipefail
         head="chore/release-settle-v$VERSION"
+        # Conventional (repos lint PR titles) and still says what merging does.
+        title="chore(release): settle v$VERSION — merging publishes the release"
+        prs="$RUNNER_TEMP/settle-prs.json"
+        err="$RUNNER_TEMP/settle-gh-stderr.txt"
+        stage="starting"
+        trap 'echo "::error::settle PR not ensured; stopped while $stage"' ERR
+        # Refresh and publish queue separately, so since the Guard ran the
+        # settle PR may have been merged (the branch moved) and published (the
+        # tag exists). Checked again right before every remote write, so a
+        # late refresh never opens a settle PR for a released version.
+        still_unsettled() {
+          stage="re-checking that v$VERSION is untagged and $BRANCH is still at $COMMIT"
+          local status=0
+          git ls-remote --exit-code --tags origin "refs/tags/v$VERSION" >/dev/null || status=$?
+          if [[ "$status" == 0 ]]; then
+            echo "::notice title=Already tagged::v$VERSION is already tagged, so this refresh of $COMMIT does not open or update a settle PR for it"
+            echo "pr_url=" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          [[ "$status" == 2 ]] || exit "$status"
+          tip="$(git ls-remote --heads origin "refs/heads/$BRANCH" | cut -f1)"
+          if [[ "$tip" != "$COMMIT" ]]; then
+            echo "::error::$BRANCH moved to ${tip:-<deleted>} after this refresh of $COMMIT started (a settle PR merge or a new push); not touching the settle PR, the run for the new tip refreshes it"
+            exit 1
+          fi
+        }
+
         label_args=()
         IFS=',' read -ra labels <<<"$PR_LABELS"
         for l in "${labels[@]}"; do
           l="${l// /}"
           [[ -n "$l" ]] && label_args+=(--label "$l")
         done
-        git checkout --quiet -B "$head" "$COMMIT"
-        what="$(python3 "$TOOLS" changelog-insert "$CHANGELOG" "$VERSION" "$NOTES")"
-        if git diff --quiet -- "$CHANGELOG"; then
-          echo "::error::$CHANGELOG already carries exactly this v$VERSION entry; nothing to settle"; exit 1
-        fi
-        git add "$CHANGELOG"
-        git commit --quiet -m "chore(release): settle v$VERSION" -m "Changelog entry $what for v$VERSION at $COMMIT."
-        # A previous settle branch (the tip moved, or settlement was re-run)
-        # is superseded, never force-pushed: a no-force-push ruleset rejects
-        # the rewrite, and a settle PR is a statement about one commit, so a
-        # new commit gets a new PR. Close its PR first so the reason is on
-        # record, then drop the branch and push this one fresh.
-        if git ls-remote --exit-code --heads origin "refs/heads/$head" >/dev/null; then
-          for n in $(gh pr list --head "$head" --base "$BRANCH" --state open --json number -q '.[].number'); do
-            gh pr close "$n" --comment "Superseded: settlement of v$VERSION was re-run (now at \`$COMMIT\`); a fresh settle PR follows." >/dev/null
-            echo "closed superseded settle PR #$n"
-          done
-          gh api -X DELETE "repos/$GITHUB_REPOSITORY/git/refs/heads/$head" >/dev/null
-          echo "dropped previous settle branch $head"
-        fi
-        git push --quiet origin "$head"
+        # Regenerated on every run, so the alert and the marker always name the
+        # commit this run settles. release-route and release-publish parse the
+        # marker line; keep its shape and keep it outside the alert.
         body="$RUNNER_TEMP/settle-pr-body.md"
         {
-          echo "Settle **v$VERSION** at \`$COMMIT\` (tip of \`$BRANCH\`)."
+          echo "> [!IMPORTANT]"
+          echo "> **Merging this PR settles \`v$VERSION\` — this is the release settlement.** The merge commit becomes the release: it is tagged \`v$VERSION\`, the GitHub Release is published from it, and the assets are built from it. Closing this PR settles nothing. A new commit on \`$BRANCH\` refreshes this PR and moves the settlement to that tip."
           echo
-          echo "Merging this PR is the settlement decision: \`release-publish\` will tag the merge commit as \`v$VERSION\` and publish the GitHub Release with the notes below. The default branch picks this entry up in the next release candidate PR. If more commits land on \`$BRANCH\` first, this PR goes stale: re-run settle on the new tip, which closes this PR and opens a fresh one."
+          echo "Settles **v$VERSION** at \`$COMMIT\`, the tip of \`$BRANCH\`. The default branch picks this entry up in the next release candidate PR."
           echo
           echo "<!-- release-settle: v$VERSION $COMMIT -->"
           echo
           cat "$NOTES"
         } > "$body"
-        url="$(gh pr create --base "$BRANCH" --head "$head" --title "chore(release): settle v$VERSION" --body-file "$body" "${label_args[@]}")"
-        echo "pr_url=$url" >> "$GITHUB_OUTPUT"
-        echo "settle PR: $url"
-        GITHUB_AUTH_COMMAND
 
-    - name: Write changelog onto the release branch (direct mode)
-      if: inputs.settle_mode == 'direct'
-      id: direct
-      shell: bash
-      env:
-        AUTH_WRAPPER: ${{ github.action_path }}/../git-auth/with-github-auth.sh
-        GITHUB_AUTH_TOKEN: ${{ inputs.token }}
-        VERSION: ${{ steps.guard.outputs.version }}
-        BRANCH: ${{ steps.guard.outputs.branch }}
-        COMMIT: ${{ inputs.commit }}
-        CHANGELOG: ${{ inputs.changelog_file }}
-        NOTES: ${{ steps.notes.outputs.notes_file }}
-        TOOLS: ${{ github.action_path }}/../release-tools/release_tools.py
-      run: |
-        "$AUTH_WRAPPER" bash --noprofile --norc -e -o pipefail <<'GITHUB_AUTH_COMMAND'
-        set -euo pipefail
-        git checkout --quiet -B "$BRANCH" "$COMMIT"
-        what="$(python3 "$TOOLS" changelog-insert "$CHANGELOG" "$VERSION" "$NOTES")"
-        if git diff --quiet -- "$CHANGELOG"; then
-          echo "::error::$CHANGELOG already carries exactly this v$VERSION entry; nothing to settle"; exit 1
-        fi
-        git add "$CHANGELOG"
-        git commit --quiet -m "chore(release): settle v$VERSION" -m "Changelog entry $what for v$VERSION at $COMMIT (direct settle)."
-        # Fast-forward the protected branch; the app must be a bypass actor on
-        # its ruleset, and the tip must still be the settled commit.
-        if ! git push --quiet origin "HEAD:refs/heads/$BRANCH"; then
-          echo "::error::could not push the settle commit to $BRANCH — the branch moved since $COMMIT, or the app is not a bypass actor on its ruleset"; exit 1
+        # Each pass re-reads the open PR. A pass that loses a race to a
+        # concurrent run (push rejected, or "already exists" from gh pr create)
+        # goes round again and takes the refresh path on the winner's PR.
+        ensured=false
+        for attempt in 1 2 3; do
+          stage="reading the open settle PR (attempt $attempt)"
+          gh pr list --head "$head" --base "$BRANCH" --state open --json number,author,body,title,url > "$prs"
+          python3 - "$prs" "$VERSION" "$title" > "$RUNNER_TEMP/settle-prs.tsv" <<'PY'
+        import json, re, sys
+
+        for pr in json.load(open(sys.argv[1])):
+            marker = re.search(r"<!-- release-settle: v" + re.escape(sys.argv[2]) + r" ([0-9a-f]{40}) -->", pr["body"])
+            title_ok = "yes" if pr.get("title") == sys.argv[3] else "no"
+            print(pr["number"], pr["author"]["login"], pr["url"], marker[1] if marker else "-", title_ok, sep="\t")
+        PY
+          pr=""; old_marker=""; old_title_ok=""
+          while IFS=$'\t' read -r number author url marker title_ok; do
+            if [[ "$author" != "$PR_AUTHOR" ]]; then
+              gh pr close "$number" --comment "Superseded: the settle PR is now maintained by mega-gutenberg." >/dev/null \
+                || echo "::warning::could not close #$number (closed by a concurrent run?)"
+            else
+              pr="$number"; pr_url="$url"; old_marker="$marker"; old_title_ok="$title_ok"
+            fi
+          done < "$RUNNER_TEMP/settle-prs.tsv"
+
+          if [[ -n "$pr" ]]; then
+            stage="checking out $head"
+            git fetch --quiet origin "+refs/heads/$head:refs/remotes/origin/$head"
+            # --force: a pass starts from the remote, not from whatever an
+            # earlier failed pass left in the work tree.
+            git checkout --quiet --force -B "$head" "origin/$head"
+            changed=false
+            if ! git merge-base --is-ancestor "$COMMIT" HEAD; then
+              stage="merging $COMMIT into $head (local only; nothing pushed)"
+              if ! git merge --no-ff --no-edit "$COMMIT"; then
+                git merge --abort
+                echo "::error::could not merge $COMMIT into $head; close the settle PR so the next run recreates it"; exit 1
+              fi
+              changed=true
+            fi
+            stage="committing the changelog on $head (local only; nothing pushed, a re-run starts over from the remote)"
+            what="$(python3 "$TOOLS" changelog-insert "$CHANGELOG" "$VERSION" "$NOTES")"
+            if ! git diff --quiet -- "$CHANGELOG"; then
+              git add "$CHANGELOG"
+              git commit --quiet -m "chore(release): refresh settle v$VERSION" -m "Changelog entry $what for v$VERSION at $COMMIT."
+              changed=true
+            fi
+            if [[ "$changed" == false && "$old_marker" == "$COMMIT" && "$old_title_ok" == yes ]]; then
+              echo "pr_url=$pr_url" >> "$GITHUB_OUTPUT"
+              echo "::notice::settle PR is up to date: $pr_url"
+              exit 0
+            fi
+            still_unsettled
+            if [[ "$changed" == true ]]; then
+              # Only now, with the merge and the changelog both committed.
+              stage="pushing $head"
+              if ! git push --quiet origin "$head"; then
+                echo "::warning::push of $head was rejected (moved by a concurrent run?); re-reading the PR"
+                continue
+              fi
+              echo "pushed $head at $(git rev-parse HEAD): $COMMIT merged and changelog committed"
+            fi
+            stage="updating #$pr (branch already pushed; a re-run only needs to repeat this)"
+            gh pr edit "$pr" --title "$title" --body-file "$body" >/dev/null
+            echo "refreshed #$pr: marker now settles $COMMIT"
+            ensured=true; break
+          fi
+
+          if (( attempt > 1 )); then
+            # A concurrent run pushed the settle branch but its PR is not
+            # visible yet; deleting the branch now would close that PR.
+            echo "::error::$head was taken by a concurrent run but no open settle PR is visible yet; re-run this workflow"; exit 1
+          fi
+          still_unsettled
+          # A closed, merged, or superseded PR leaves no maintained history.
+          if git ls-remote --exit-code --heads origin "refs/heads/$head" >/dev/null; then
+            stage="deleting the stale $head"
+            if ! gh api -X DELETE "repos/$GITHUB_REPOSITORY/git/refs/heads/$head" >/dev/null 2>"$err"; then
+              if ! grep -qE 'HTTP 4(04|22)' "$err"; then cat "$err" >&2; false; fi
+              echo "stale $head was already deleted"
+            fi
+          fi
+          stage="committing the settlement on a fresh $head (local only; nothing pushed)"
+          git checkout --quiet --force -B "$head" "$COMMIT"
+          what="$(python3 "$TOOLS" changelog-insert "$CHANGELOG" "$VERSION" "$NOTES")"
+          if git diff --quiet -- "$CHANGELOG"; then
+            git commit --quiet --allow-empty -m "chore(release): settle v$VERSION" \
+              -m "Changelog already current at $COMMIT; this PR records the settlement decision."
+          else
+            git add "$CHANGELOG"
+            git commit --quiet -m "chore(release): settle v$VERSION" -m "Changelog entry $what for v$VERSION at $COMMIT."
+          fi
+          stage="pushing a fresh $head"
+          if ! git push --quiet origin "$head"; then
+            echo "::warning::push of a fresh $head was rejected (created by a concurrent run?); re-reading the PR"
+            continue
+          fi
+          echo "pushed a fresh $head at $(git rev-parse HEAD)"
+          stage="opening the settle PR ($head already pushed; a re-run picks it up)"
+          if ! pr_url="$(gh pr create --base "$BRANCH" --head "$head" --title "$title" --body-file "$body" "${label_args[@]}" 2>"$err")"; then
+            if ! grep -qi 'already exists' "$err"; then cat "$err" >&2; false; fi
+            echo "::notice::a concurrent run opened the settle PR first; refreshing that one"
+            continue
+          fi
+          ensured=true; break
+        done
+        if [[ "$ensured" != true ]]; then
+          echo "::error::settle PR not ensured after $attempt attempts of racing a concurrent run; re-run this workflow"; exit 1
         fi
-        echo "commit=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
-        echo "settle commit $(git rev-parse --short HEAD) pushed to $BRANCH"
+        echo "pr_url=$pr_url" >> "$GITHUB_OUTPUT"
+        echo "settle PR: $pr_url"
         GITHUB_AUTH_COMMAND
-
-    - name: Tag and publish (direct mode)
-      if: inputs.settle_mode == 'direct'
-      id: publish
-      uses: megaeth-labs/.github/.github/actions/release-publish@main
-      with:
-        token: ${{ inputs.token }}
-        commit: ${{ steps.direct.outputs.commit }}
-        version: ${{ steps.guard.outputs.version }}
-        version_file: ${{ inputs.version_file }}
-        version_pattern: ${{ inputs.version_pattern }}
-        changelog_file: ${{ inputs.changelog_file }}
-        release_branch_prefix: ${{ inputs.release_branch_prefix }}
-        git_user_name: ${{ inputs.git_user_name }}
-        git_user_email: ${{ inputs.git_user_email }}
diff --git a/.github/actions/release-tools/release_tools.py b/.github/actions/release-tools/release_tools.py
index 1a9e0e6..40c7dc7 100644
--- a/.github/actions/release-tools/release_tools.py
+++ b/.github/actions/release-tools/release_tools.py
@@ -5,8 +5,13 @@
 only transforms text so it can be unit-tested without a repository. stdlib only.
 
 Subcommands (see `main`):
+  route                                     -> stdin: routing JSON object; stdout: decision JSON object
   normalize   VERSION                       -> X.Y.Z on stdout, exit 1 if invalid
   is-greater  VERSION LATEST_TAG_OR_EMPTY   -> exit 0 if VERSION > LATEST, else 1
+  latest-tag  [--exclude VERSION]           -> stdin: tag names; stdout: the highest vX.Y.Z tag or "";
+                                               other tags (v1.2.0-rc1) are named on stderr and ignored
+  check-order VERSION LATEST_TAG_OR_EMPTY   -> exit 0 if VERSION may be published after LATEST, else
+                                               print the refusal on stdout and exit 1
   read-file   PATH PATTERN                  -> version found in the file
   bump-file   PATH PATTERN VERSION          -> rewrite in place, print old version
   notes       REPO VERSION DATE             -> stdin: "<sha>\t<subject>" lines; stdout: markdown
@@ -26,6 +31,10 @@
 from pathlib import Path
 
 SEMVER = re.compile(r"^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$")
+# A tag this flow publishes: exactly vX.Y.Z. Anything else under v* (v1.2.0-rc1,
+# vnext) is not a release and never counts as the latest one.
+RELEASE_TAG = re.compile(r"^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$")
+ORDER_RULE = "rule: a version is published only when it is newer than every vX.Y.Z tag"
 
 # Conventional Commits types, in the order they appear in the notes. Anything
 # not listed (or without a type) lands under "Other".
@@ -75,6 +84,191 @@ def is_greater(version: str, latest: str) -> bool:
     return version_tuple(version) > version_tuple(latest)
 
 
+def latest_release_tag(tags: list[str], exclude: str = "") -> tuple[str, list[str]]:
+    """(highest vX.Y.Z tag or "", tags ignored because they are not vX.Y.Z).
+
+    `exclude` (X.Y.Z or vX.Y.Z) leaves that version's own tag out, so a run
+    resuming its own half-finished publication compares against the others."""
+    skip = normalize_version(exclude) if exclude.strip() else ""
+    best, ignored = "", []
+    for raw in tags:
+        tag = raw.strip()
+        if not tag:
+            continue
+        if not RELEASE_TAG.match(tag):
+            ignored.append(tag)
+        elif normalize_version(tag) != skip and (not best or version_tuple(tag) > version_tuple(best)):
+            best = tag
+    return best, ignored
+
+
+def order_refusal(version: str, latest: str) -> str | None:
+    """Why `version` may not be published after `latest`, or None when it may.
+
+    One rule for release-route and release-publish: only a version newer than
+    the latest vX.Y.Z tag is published, so an older line merged late can never
+    become the newest Release."""
+    latest = latest.strip()
+    if not latest:
+        return None
+    if not RELEASE_TAG.match(latest):
+        return f"latest tag {latest!r} is not vX.Y.Z, so v{version} cannot be ordered against it ({ORDER_RULE})"
+    if not is_greater(version, latest):
+        return f"v{version} is not newer than the latest published tag {latest} ({ORDER_RULE})"
+    return None
+
+
+# --- release routing --------------------------------------------------------
+
+
+def _field(data: dict, key: str, default):
+    """Return data[key], treating absent and JSON null alike; reject other types."""
+    value = data.get(key)
+    if value is None:
+        return default
+    if not isinstance(value, type(default)):
+        raise ValueError(f"route field {key!r} must be {type(default).__name__}, got {value!r}")
+    return value
+
+
+def _items(data: dict, key: str) -> list[dict]:
+    items = _field(data, key, [])
+    if not all(isinstance(item, dict) for item in items):
+        raise ValueError(f"route field {key!r} must be a list of objects")
+    return items
+
+
+def _branch_version(branch: str, prefix: str) -> str | None:
+    """X.Y.Z for a release branch, None when the suffix is not a version."""
+    try:
+        return normalize_version(branch[len(prefix):])
+    except ValueError:
+        return None
+
+
+def route(data: dict) -> dict:
+    """Decide the next release action from an already collected snapshot."""
+    if not isinstance(data, dict):
+        raise ValueError("route input must be a JSON object")
+    kind, event, ref = (_field(data, key, "") for key in ("kind", "event", "ref_name"))
+    prefix = _field(data, "prefix", "release-v")
+    sha = _field(data, "sha", "")
+    result = {
+        "action": "skip",
+        "reason": f"no route for kind={kind}, event={event}, ref={ref}",
+        "version": "",
+        "release_branch": "",
+        "commit": "",
+        "pr_number": None,
+        "targets": [],
+    }
+    if event == "push" and (
+        (kind == "candidate" and ref == data.get("default_branch"))
+        or (kind == "settle" and ref.startswith(prefix))
+    ):
+        candidate = kind == "candidate"
+        head_prefix = "chore/release-candidate-"
+        if not candidate:
+            version = _branch_version(ref, prefix)
+            if version is None:
+                result["reason"] = (
+                    f"{ref} is not a release branch: {ref[len(prefix):]!r} after {prefix!r} is not X.Y.Z"
+                )
+                return result
+            result.update(version=version, release_branch=ref, commit=sha)
+            if data.get("tag_exists") and data.get("release_exists"):
+                result["reason"] = f"v{version} is already published"
+                return result
+        pr = next((
+            pr for pr in _items(data, "pulls")
+            if pr.get("merged_at") and pr.get("merge_commit_sha") == sha
+            and (pr.get("base") or {}).get("ref") == ref
+            and (
+                str((pr.get("head") or {}).get("ref") or "").startswith(head_prefix)
+                if candidate else (pr.get("head") or {}).get("ref") == f"chore/release-settle-v{version}"
+            )
+        ), None)
+        fresh = False
+        marker = None
+        if pr and not candidate:
+            match = re.search(
+                rf"<!-- release-settle: v{re.escape(version)} ([0-9a-fA-F]{{40}}) -->",
+                pr.get("body") or "",
+            )
+            marker = match.group(1) if match else None
+            fresh = marker is not None and marker == data.get("first_parent")
+        author = (pr.get("user") or {}).get("login") if pr else None
+        expected_author = _field(data, "pr_author", "mega-gutenberg[bot]")
+        if not candidate and data.get("tag_exists") and not (
+            fresh and author == expected_author
+        ):
+            result["reason"] = (
+                f"v{version} is tagged but has no Release: re-run the release-settle run "
+                "for the settle PR's merge commit"
+                f"{' ' + data['tag_commit'] if data.get('tag_commit') else ''} to finish publishing"
+            )
+            return result
+        if pr:
+            if author != expected_author:
+                result["reason"] = f"PR #{pr['number']} author {author} does not match {expected_author}"
+                return result
+            result["pr_number"] = pr["number"]
+            if candidate:
+                version = normalize_version(pr["head"]["ref"][len(head_prefix):])
+                result.update(
+                    action="cut", reason=f"merged candidate PR #{pr['number']}",
+                    version=version, release_branch=f"{prefix}{version}", commit=sha,
+                )
+                return result
+            if fresh:
+                refusal = order_refusal(version, _field(data, "latest_tag", ""))
+                if refusal:
+                    result["reason"] = f"refusing to publish settle PR #{pr['number']}: {refusal}"
+                    return result
+                result.update(action="publish", reason=f"merged fresh settle PR #{pr['number']}")
+                return result
+            settled = f"settled {marker}" if marker else "no release-settle marker"
+            result["reason"] = (
+                f"merged settle PR #{pr['number']} was stale ({settled}, "
+                f"tip was {data.get('first_parent') or 'unknown'}); a fresh settle PR follows"
+            )
+        elif candidate:
+            result["reason"] = "no merged candidate PR matches this push"
+            return result
+        elif data.get("version_at_sha") != version:
+            result["reason"] = "the candidate has not landed on this branch yet"
+            return result
+        elif refusal := order_refusal(version, _field(data, "latest_tag", "")):
+            result["reason"] = f"not refreshing a settle PR: {refusal}"
+            return result
+        else:
+            result["reason"] = f"refresh settle PR for v{version}"
+        result.update(action="refresh", targets=[
+            {"version": version, "release_branch": ref, "commit": sha},
+        ])
+    elif kind == "settle" and event == "workflow_dispatch":
+        selected = _field(data, "dispatch_version", "")
+        selected = normalize_version(selected) if selected else ""
+        for branch in _items(data, "branches"):
+            name = branch.get("name")
+            if not isinstance(name, str) or not name.startswith(prefix) or branch.get("tag_exists"):
+                continue
+            version = _branch_version(name, prefix)
+            if version is None:
+                continue
+            if (branch.get("version_at_tip") == version
+                    and order_refusal(version, _field(data, "latest_tag", "")) is None
+                    and (not selected or version == selected)):
+                result["targets"].append({
+                    "version": version, "release_branch": name, "commit": branch.get("tip") or "",
+                })
+        result.update(
+            action="refresh" if result["targets"] else "skip",
+            reason="refresh eligible release branches" if result["targets"] else "no eligible release branches",
+        )
+    return result
+
+
 # --- version files ----------------------------------------------------------
 
 # pattern -> (regex with a `v` group, description). `plain` is the whole file.
@@ -224,6 +418,8 @@ def main(argv: list[str]) -> int:
     p = argparse.ArgumentParser(prog="release_tools")
     sub = p.add_subparsers(dest="cmd", required=True)
 
+    sub.add_parser("route")
+
     s = sub.add_parser("normalize")
     s.add_argument("version")
 
@@ -231,6 +427,13 @@ def main(argv: list[str]) -> int:
     s.add_argument("version")
     s.add_argument("latest")
 
+    s = sub.add_parser("latest-tag")
+    s.add_argument("--exclude", default="")
+
+    s = sub.add_parser("check-order")
+    s.add_argument("version")
+    s.add_argument("latest")
+
     s = sub.add_parser("read-file")
     s.add_argument("path")
     s.add_argument("pattern")
@@ -261,10 +464,22 @@ def main(argv: list[str]) -> int:
 
     a = p.parse_args(argv)
     try:
-        if a.cmd == "normalize":
+        if a.cmd == "route":
+            print(json.dumps(route(json.load(sys.stdin))))
+        elif a.cmd == "normalize":
             print(normalize_version(a.version))
         elif a.cmd == "is-greater":
             return 0 if is_greater(a.version, a.latest) else 1
+        elif a.cmd == "latest-tag":
+            latest, ignored = latest_release_tag(sys.stdin.read().splitlines(), a.exclude)
+            for tag in ignored:
+                print(f"release_tools: ignoring tag {tag!r}: not vX.Y.Z, so never the latest release", file=sys.stderr)
+            print(latest)
+        elif a.cmd == "check-order":
+            refusal = order_refusal(normalize_version(a.version), a.latest)
+            if refusal:
+                print(refusal)
+                return 1
         elif a.cmd == "read-file":
             print(read_version_file(Path(a.path).read_text(), a.pattern))
         elif a.cmd == "bump-file":
@@ -299,7 +514,7 @@ def main(argv: list[str]) -> int:
                 print(f"no section for v{normalize_version(a.version)} in {a.path}", file=sys.stderr)
                 return 1
             print(body, end="")
-    except (ValueError, OSError) as e:
+    except (ValueError, OSError, TypeError, KeyError, AttributeError) as e:
         print(f"release_tools: {e}", file=sys.stderr)
         return 1
     return 0
diff --git a/.github/actions/release-tools/test_release_settle.py b/.github/actions/release-tools/test_release_settle.py
new file mode 100644
index 0000000..0c6b3ce
--- /dev/null
+++ b/.github/actions/release-tools/test_release_settle.py
@@ -0,0 +1,320 @@
+"""Drive release-settle's "Ensure the settle PR" step, extracted from its
+action.yml, against a real local remote. Only GitHub's PR and ref API is
+faked; the settle branch, merges and pushes are real git."""
+
+import json
+import os
+import pathlib
+import re
+import subprocess
+import tempfile
+import unittest
+
+import yaml
+
+import release_tools as rt
+
+ACTIONS = pathlib.Path(__file__).resolve().parent.parent
+VERSION = "1.1.0"
+BRANCH = "release-v1.1.0"
+HEAD = "chore/release-settle-v1.1.0"
+AUTHOR = "mega-gutenberg[bot]"
+
+FAKE_GH = r'''#!/usr/bin/env python3
+import json, os, pathlib, subprocess, sys
+
+path = pathlib.Path(os.environ["PR_STATE"])
+state = json.loads(path.read_text())
+args = sys.argv[1:]
+remote = os.environ["FAKE_REMOTE"]
+def option(flag):
+    return args[args.index(flag) + 1]
+def save(event):
+    state["events"].append(event)
+    path.write_text(json.dumps(state))
+def git(*cmd):
+    who = {"GIT_AUTHOR_NAME": "rival", "GIT_AUTHOR_EMAIL": "rival@example.invalid",
+           "GIT_COMMITTER_NAME": "rival", "GIT_COMMITTER_EMAIL": "rival@example.invalid"}
+    return subprocess.run(["git", "-C", remote, *cmd], check=True, text=True,
+                          capture_output=True, env={**os.environ, **who}).stdout.strip()
+def add_pr(head, base, title, body, labels=()):
+    number = len(state["pulls"]) + 1
+    pr = {"number": number, "url": f"https://example.invalid/pull/{number}", "state": "open",
+          "author": {"login": os.environ["PR_AUTHOR"]}, "headRefName": head, "baseRefName": base,
+          "title": title, "body": body, "labels": list(labels)}
+    state["pulls"].append(pr)
+    return pr
+def concurrent_settle(commit):
+    # Another run pushes its own settle branch and opens its PR first.
+    sha = git("commit-tree", f"{commit}^{{tree}}", "-p", commit, "-m", "chore(release): settle v1.1.0")
+    git("update-ref", "refs/heads/" + os.environ["HEAD_BRANCH"], sha)
+    add_pr(os.environ["HEAD_BRANCH"], os.environ["BRANCH"], "chore(release): settle v1.1.0",
+           f"<!-- release-settle: v1.1.0 {commit} -->\n")
+
+if args[:2] == ["pr", "list"]:
+    fields = option("--json").split(",")
+    pulls = [pr for pr in state["pulls"] if pr["state"] == "open"
+             and pr["headRefName"] == option("--head") and pr["baseRefName"] == option("--base")]
+    print(json.dumps([{key: pr[key] for key in fields} for pr in pulls]))
+elif args[:2] == ["pr", "create"]:
+    if state.pop("race_create", False):
+        # The competitor's PR has the same head, created between our list and create.
+        add_pr(option("--head"), option("--base"), "stale title", "")
+        save("create-lost")
+        sys.exit(f'a pull request for branch "{option("--head")}" into branch "{option("--base")}" '
+                 f'already exists:\nhttps://example.invalid/pull/{len(state["pulls"])}')
+    if any(pr["state"] == "open" and pr["headRefName"] == option("--head")
+           and pr["baseRefName"] == option("--base") for pr in state["pulls"]):
+        sys.exit("a pull request for this branch already exists")
+    pr = add_pr(option("--head"), option("--base"), option("--title"),
+                pathlib.Path(option("--body-file")).read_text(),
+                [args[i + 1] for i, arg in enumerate(args) if arg == "--label"])
+    save("create")
+    print(pr["url"])
+elif args[:2] == ["pr", "edit"]:
+    pr = state["pulls"][int(args[2]) - 1]
+    assert pr["state"] == "open"
+    if "--title" in args:
+        pr["title"] = option("--title")
+    pr["body"] = pathlib.Path(option("--body-file")).read_text()
+    save("edit")
+    print(pr["url"])
+elif args[:2] == ["pr", "close"]:
+    pr = state["pulls"][int(args[2]) - 1]
+    pr["state"] = "closed"
+    save("close")
+elif args[:3] == ["api", "-X", "DELETE"]:
+    ref = args[3].split("/git/refs/", 1)[1]
+    mode = state.pop("delete_mode", "")
+    if mode != "concurrent-creator":
+        subprocess.run(["git", "-C", remote, "update-ref", "-d", f"refs/{ref}"], check=True)
+    if mode == "gone":
+        save("delete-422")
+        sys.exit("gh: Reference does not exist (HTTP 422)")
+    if mode == "concurrent-creator":
+        git("update-ref", "-d", f"refs/{ref}")
+        concurrent_settle(state["commit"])
+    save("delete")
+else:
+    sys.exit(f"unexpected gh command: {args}")
+'''
+
+
+def ensure_script() -> str:
+    action = yaml.safe_load((ACTIONS / "release-settle" / "action.yml").read_text())
+    [step] = [s for s in action["runs"]["steps"] if s.get("name") == "Ensure the settle PR"]
+    return step["run"]
+
+
+def publish_marker_pattern() -> re.Pattern:
+    """The pattern release-publish greps the merged PR body with."""
+    text = (ACTIONS / "release-publish" / "action.yml").read_text()
+    return re.compile(re.search(r"grep -oE '(<!-- release-settle: [^']*)'", text)[1])
+
+
+class EnsureSettlePR(unittest.TestCase):
+    def setUp(self):
+        self.tmp = pathlib.Path(tempfile.mkdtemp(prefix="settle-test-"))
+        self.addCleanup(subprocess.run, ["rm", "-rf", str(self.tmp)], check=True)
+        self.remote = self.tmp / "remote.git"
+        self.repo = self.tmp / "repo"
+        self.state = self.tmp / "prs.json"
+        self.out = self.tmp / "output"
+        self.script = self.tmp / "ensure.sh"
+        self.script.write_text(ensure_script())
+        bin_dir = self.tmp / "bin"
+        bin_dir.mkdir()
+        (bin_dir / "gh").write_text(FAKE_GH)
+        (bin_dir / "gh").chmod(0o755)
+        self.env = {
+            **os.environ,
+            "PATH": f"{bin_dir}{os.pathsep}{os.environ['PATH']}",
+            "GIT_CONFIG_GLOBAL": "/dev/null", "GIT_CONFIG_NOSYSTEM": "1",
+            "AUTH_WRAPPER": str(ACTIONS / "git-auth" / "with-github-auth.sh"),
+            "GITHUB_AUTH_TOKEN": "fixture-token", "GH_TOKEN": "fixture-token",
+            "VERSION": VERSION, "BRANCH": BRANCH, "HEAD_BRANCH": HEAD,
+            "CHANGELOG": "CHANGELOG.md", "PR_LABELS": "release", "PR_AUTHOR": AUTHOR,
+            "TOOLS": str(ACTIONS / "release-tools" / "release_tools.py"),
+            "RUNNER_TEMP": str(self.tmp), "GITHUB_OUTPUT": str(self.out),
+            "GITHUB_REPOSITORY": "megaeth-labs/fake", "PR_STATE": str(self.state),
+            "FAKE_REMOTE": str(self.remote),
+        }
+        self.git("init", "--quiet", "--bare", "--initial-branch=main", str(self.remote), cwd=self.tmp)
+        self.git("clone", "--quiet", str(self.remote), str(self.repo), cwd=self.tmp)
+        self.git("config", "user.name", AUTHOR)
+        self.git("config", "user.email", "bot@users.noreply.github.com")
+        self.commit_file("VERSION", "1.0.0\n", "feat: initial release")
+        self.commit_file("CHANGELOG.md", "# Changelog\n\n## v1.0.0 (2025-01-01)\n\n- shipped\n", "docs: changelog")
+        self.git("push", "--quiet", "origin", "main")
+        self.git("checkout", "--quiet", "-b", BRANCH)
+        self.commit_file("VERSION", "1.1.0\n", "chore(release): candidate v1.1.0")
+        self.git("push", "--quiet", "origin", BRANCH)
+        self.state.write_text(json.dumps({"pulls": [], "events": []}))
+
+    def git(self, *args, cwd=None):
+        return subprocess.run(["git", *args], cwd=cwd or self.repo, env=self.env, check=True,
+                              text=True, capture_output=True).stdout.strip()
+
+    def commit_file(self, name, content, message):
+        (self.repo / name).write_text(content)
+        self.git("add", name)
+        self.git("commit", "--quiet", "-m", message)
+
+    def advance(self, line):
+        self.git("checkout", "--quiet", "-B", BRANCH, f"origin/{BRANCH}")
+        self.commit_file("fixes", line + "\n", f"fix: {line}")
+        self.git("push", "--quiet", "origin", BRANCH)
+        return self.git("rev-parse", "HEAD")
+
+    def remote_head(self, branch):
+        return self.git("rev-parse", "--verify", "--quiet", f"refs/heads/{branch}", cwd=self.remote)
+
+    def tip(self):
+        return self.remote_head(BRANCH)
+
+    def pulls(self):
+        return json.loads(self.state.read_text())["pulls"]
+
+    def events(self):
+        return json.loads(self.state.read_text())["events"]
+
+    def patch_state(self, **changes):
+        state = json.loads(self.state.read_text())
+        state.update(changes)
+        self.state.write_text(json.dumps(state))
+
+    def settle(self, commit, check=True):
+        notes = self.tmp / "notes.md"
+        notes.write_text(f"## v{VERSION} (2026-01-01)\n\n- fix: up to {commit[:10]}\n")
+        self.out.write_text("")
+        self.git("fetch", "--quiet", "origin")
+        result = subprocess.run(["bash", str(self.script)], cwd=self.repo, text=True, capture_output=True,
+                                env={**self.env, "COMMIT": commit, "NOTES": str(notes)})
+        if check:
+            self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        return result
+
+    def assert_one_open_pr_settling(self, commit):
+        open_prs = [pr for pr in self.pulls() if pr["state"] == "open"]
+        self.assertEqual(len(open_prs), 1, open_prs)
+        [pr] = open_prs
+        body = pr["body"]
+        self.assertEqual(re.findall(r"<!-- release-settle: v1\.1\.0 ([0-9a-f]{40}) -->", body), [commit])
+        # The marker sits on its own line, outside any blockquote.
+        self.assertIn(f"\n<!-- release-settle: v{VERSION} {commit} -->\n", body)
+        # Both consumers of the marker read it back as this commit.
+        self.assertEqual(re.findall(r"[0-9a-f]{40}", publish_marker_pattern().search(body)[0]), [commit])
+        decision = rt.route({
+            "kind": "settle", "event": "push", "sha": "f" * 40, "first_parent": commit,
+            "ref_name": BRANCH, "default_branch": "main", "prefix": "release-v",
+            "pr_author": AUTHOR, "tag_exists": False, "release_exists": False,
+            "version_at_sha": VERSION, "latest_tag": "v1.0.0", "branches": [], "dispatch_version": "",
+            "pulls": [{"number": pr["number"], "merged_at": "2026-01-01T00:00:00Z",
+                       "merge_commit_sha": "f" * 40, "head": {"ref": HEAD}, "base": {"ref": BRANCH},
+                       "user": {"login": AUTHOR}, "body": body}],
+        })
+        self.assertEqual(decision["action"], "publish", decision)
+        self.assertEqual(decision["commit"], "f" * 40)
+        self.assertIn(f"pr_url={pr['url']}", self.out.read_text().splitlines())
+        return pr
+
+    def test_title_is_conventional(self):
+        tip = self.tip()
+        self.settle(tip)
+        [pr] = self.pulls()
+        self.assertRegex(pr["title"], r"^chore\(release\): \S.*$")
+        self.assertTrue(rt.RELEASE_COMMIT.match(pr["title"]))
+        self.assertIn(f"v{VERSION}", pr["title"])
+
+    def test_refresh_keeps_the_pr_and_moves_the_marker(self):
+        first = self.tip()
+        self.settle(first)
+        pr = self.assert_one_open_pr_settling(first)
+        old_head = self.remote_head(HEAD)
+        second = self.advance("second fix")
+        self.settle(second)
+        refreshed = self.assert_one_open_pr_settling(second)
+        self.assertEqual(refreshed["number"], pr["number"])
+        self.assertEqual(len(self.pulls()), 1)
+        new_head = self.remote_head(HEAD)
+        self.git("merge-base", "--is-ancestor", old_head, new_head)
+        self.git("merge-base", "--is-ancestor", second, new_head)
+        self.assertEqual(self.events(), ["create", "edit"])
+
+    def test_up_to_date_rerun_is_a_noop(self):
+        tip = self.tip()
+        self.settle(tip)
+        head = self.remote_head(HEAD)
+        state = self.state.read_text()
+        result = self.settle(tip)
+        self.assertIn("settle PR is up to date", result.stdout)
+        self.assertEqual(self.state.read_text(), state)
+        self.assertEqual(self.remote_head(HEAD), head)
+        self.assert_one_open_pr_settling(tip)
+
+    def test_old_title_is_refreshed_without_a_commit(self):
+        tip = self.tip()
+        self.settle(tip)
+        head = self.remote_head(HEAD)
+        state = json.loads(self.state.read_text())
+        state["pulls"][0]["title"] = "chore(release): settle v1.1.0"
+        self.state.write_text(json.dumps(state))
+        self.settle(tip)
+        self.assertEqual(self.remote_head(HEAD), head)
+        self.assertEqual(self.events(), ["create", "edit"])
+        self.assertNotEqual(self.pulls()[0]["title"], "chore(release): settle v1.1.0")
+
+    def test_create_race_recovers_on_the_existing_pr(self):
+        tip = self.tip()
+        self.patch_state(race_create=True)
+        result = self.settle(tip)
+        self.assertIn("concurrent run opened the settle PR first", result.stdout)
+        pr = self.assert_one_open_pr_settling(tip)
+        self.assertEqual(pr["number"], 1)
+        self.assertEqual(self.events(), ["create-lost", "edit"])
+
+    def test_stale_ref_already_deleted(self):
+        tip = self.tip()
+        self.settle(tip)
+        self.patch_state(pulls=[{**self.pulls()[0], "state": "closed"}])
+        self.patch_state(delete_mode="gone")
+        result = self.settle(tip)
+        self.assertIn("already deleted", result.stdout)
+        self.assert_one_open_pr_settling(tip)
+        self.assertEqual(self.events()[-2:], ["delete-422", "create"])
+
+    def test_concurrent_creator_after_delete(self):
+        tip = self.tip()
+        self.settle(tip)
+        self.patch_state(pulls=[{**self.pulls()[0], "state": "closed"}])
+        self.patch_state(delete_mode="concurrent-creator", commit=tip)
+        result = self.settle(tip)
+        self.assertIn("push of a fresh", result.stdout)
+        pr = self.assert_one_open_pr_settling(tip)
+        self.assertEqual(pr["number"], 2)
+        self.assertEqual(len(self.pulls()), 2)
+        self.assertEqual(self.events()[-2:], ["delete", "edit"])
+
+    def test_failed_changelog_commit_pushes_nothing_and_a_rerun_recovers(self):
+        first = self.tip()
+        self.settle(first)
+        head = self.remote_head(HEAD)
+        second = self.advance("third fix")
+        hooks = self.tmp / "hooks"
+        hooks.mkdir()
+        (hooks / "pre-commit").write_text("#!/bin/sh\nexit 1\n")
+        (hooks / "pre-commit").chmod(0o755)
+        self.git("config", "core.hooksPath", str(hooks))
+        result = self.settle(second, check=False)
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("nothing pushed", result.stdout)
+        self.assertEqual(self.remote_head(HEAD), head)
+        self.assertEqual(self.events(), ["create"])
+        self.git("config", "--unset", "core.hooksPath")
+        self.settle(second)
+        self.assert_one_open_pr_settling(second)
+        self.git("merge-base", "--is-ancestor", head, self.remote_head(HEAD))
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/.github/actions/release-tools/test_release_tools.py b/.github/actions/release-tools/test_release_tools.py
index 845d8d7..314bc05 100644
--- a/.github/actions/release-tools/test_release_tools.py
+++ b/.github/actions/release-tools/test_release_tools.py
@@ -1,4 +1,8 @@
+import contextlib
+import io
+import json
 import unittest
+from unittest.mock import patch
 
 import release_tools as rt
 
@@ -17,6 +21,372 @@ def test_is_greater(self):
         self.assertFalse(rt.is_greater("1.9.9", "v1.10.0"))
         self.assertFalse(rt.is_greater("2.2.0", "2.2.0"))
 
+    def test_latest_tag_ignores_tags_that_are_not_plain_releases(self):
+        # git's -v:refname puts v1.2.0-rc1 above v1.2.0; it is not a release.
+        tags = ["v1.2.0-rc1", "v1.2.0", "v1.10.0-beta", "vnext", "v1.9.0", "1.99.0", "v01.0.0", ""]
+        self.assertEqual(rt.latest_release_tag(tags),
+                         ("v1.9.0", ["v1.2.0-rc1", "v1.10.0-beta", "vnext", "1.99.0", "v01.0.0"]))
+        self.assertEqual(rt.latest_release_tag(["v1.2.0-rc1"]), ("", ["v1.2.0-rc1"]))
+        self.assertEqual(rt.latest_release_tag([]), ("", []))
+
+    def test_latest_tag_can_leave_out_the_version_being_published(self):
+        tags = ["v1.2.0", "v1.3.0", "v1.1.0"]
+        self.assertEqual(rt.latest_release_tag(tags, "1.3.0")[0], "v1.2.0")
+        self.assertEqual(rt.latest_release_tag(tags, "v1.2.0")[0], "v1.3.0")
+
+    def test_latest_tag_cli(self):
+        out, err = io.StringIO(), io.StringIO()
+        with patch("sys.stdin", io.StringIO("v1.2.0\nv1.3.0-rc1\nv1.1.0\n")), \
+                contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+            self.assertEqual(rt.main(["latest-tag"]), 0)
+        self.assertEqual(out.getvalue(), "v1.2.0\n")
+        self.assertIn("ignoring tag 'v1.3.0-rc1'", err.getvalue())
+        out = io.StringIO()
+        with patch("sys.stdin", io.StringIO("v1.2.0\n")), contextlib.redirect_stdout(out):
+            self.assertEqual(rt.main(["latest-tag", "--exclude", "1.2.0"]), 0)
+        self.assertEqual(out.getvalue(), "\n")
+
+    def test_order_refusal_names_both_versions_and_the_rule(self):
+        self.assertIsNone(rt.order_refusal("1.3.0", "v1.2.0"))
+        self.assertIsNone(rt.order_refusal("1.3.0", ""))
+        for latest in ("v1.3.0", "v1.10.0"):
+            refusal = rt.order_refusal("1.3.0", latest)
+            self.assertIn("v1.3.0 is not newer than the latest published tag " + latest, refusal)
+            self.assertIn(rt.ORDER_RULE, refusal)
+        self.assertIn("'v1.4.0-rc1' is not vX.Y.Z", rt.order_refusal("1.3.0", "v1.4.0-rc1"))
+
+    def test_check_order_cli(self):
+        out = io.StringIO()
+        with contextlib.redirect_stdout(out):
+            self.assertEqual(rt.main(["check-order", "v1.2.1", "v1.3.0"]), 1)
+            self.assertEqual(rt.main(["check-order", "1.3.1", "v1.3.0"]), 0)
+            self.assertEqual(rt.main(["check-order", "1.0.0", ""]), 0)
+        self.assertEqual(out.getvalue().strip(),
+                         f"v1.2.1 is not newer than the latest published tag v1.3.0 ({rt.ORDER_RULE})")
+
+
+class Route(unittest.TestCase):
+    SHA = "a" * 40
+    PARENT = "b" * 40
+
+    def fixture(self, kind="settle"):
+        candidate = kind == "candidate"
+        ref = "main" if candidate else "release-v1.2.0"
+        return {
+            "kind": kind, "event": "push", "sha": self.SHA,
+            "first_parent": self.PARENT, "ref_name": ref, "default_branch": "main",
+            "pr_author": "mega-gutenberg[bot]", "tag_exists": False,
+            "release_exists": False, "version_at_sha": "1.2.0", "latest_tag": "v1.1.0",
+            "pulls": [{
+                "number": 42, "merged_at": "2026-10-27T00:00:00Z",
+                "merge_commit_sha": self.SHA, "base": {"ref": ref},
+                "head": {"ref": "chore/release-candidate-v1.2.0" if candidate
+                         else "chore/release-settle-v1.2.0"},
+                "user": {"login": "mega-gutenberg[bot]"},
+                "body": f"<!-- release-settle: v1.2.0 {self.PARENT} -->",
+            }],
+        }
+
+    def decision(self, data, action):
+        result = rt.route(data)
+        self.assertEqual(result["action"], action)
+        self.assertTrue(result["reason"])
+        self.assertEqual(set(result), {
+            "action", "reason", "version", "release_branch", "commit", "pr_number", "targets",
+        })
+        if action != "refresh":
+            self.assertEqual(result["targets"], [])
+        return result
+
+    def test_candidate_push_cuts_normalized_version(self):
+        data = self.fixture("candidate")
+        for suffix in ("v1.2.0", "1.2.0"):
+            with self.subTest(suffix=suffix):
+                data["pulls"][0]["head"]["ref"] = "chore/release-candidate-" + suffix
+                result = self.decision(data, "cut")
+                self.assertEqual(
+                    (result["version"], result["release_branch"], result["commit"], result["pr_number"]),
+                    ("1.2.0", "release-v1.2.0", self.SHA, 42),
+                )
+
+    def test_author_mismatch_never_cuts_publishes_or_refreshes(self):
+        for kind in ("candidate", "settle"):
+            with self.subTest(kind=kind):
+                data = self.fixture(kind)
+                data["pulls"][0]["user"]["login"] = "mega-maxwell[bot]"
+                result = self.decision(data, "skip")
+                self.assertIn("mega-maxwell[bot]", result["reason"])
+
+    def test_unmerged_pr_is_not_selected(self):
+        self.assert_unmatched_pr("merged_at", None)
+
+    def test_merge_commit_sha_mismatch_is_not_selected(self):
+        self.assert_unmatched_pr("merge_commit_sha", "c" * 40)
+
+    def test_base_mismatch_is_not_selected(self):
+        self.assert_unmatched_pr("base", {"ref": "other"})
+
+    def test_head_mismatch_is_not_selected(self):
+        self.assert_unmatched_pr("head", {"ref": "chore/other"})
+
+    def assert_unmatched_pr(self, field, value):
+        for kind in ("candidate", "settle"):
+            with self.subTest(kind=kind):
+                data = self.fixture(kind)
+                data["pulls"][0][field] = value
+                self.decision(data, "skip" if kind == "candidate" else "refresh")
+
+    def test_selects_matching_pr_among_unrelated_pulls(self):
+        data = self.fixture("candidate")
+        data["pulls"].insert(0, dict(data["pulls"][0], merge_commit_sha="c" * 40))
+        self.decision(data, "cut")
+
+    def test_settle_push_publishes_fresh_merge(self):
+        result = self.decision(self.fixture(), "publish")
+        self.assertEqual(
+            (result["version"], result["release_branch"], result["commit"], result["pr_number"]),
+            ("1.2.0", "release-v1.2.0", self.SHA, 42),
+        )
+
+    def test_stale_marker_refreshes_even_before_version_checks(self):
+        data = self.fixture()
+        data["pulls"][0]["body"] = f"<!-- release-settle: v1.2.0 {'c' * 40} -->"
+        data.update(version_at_sha=None, latest_tag="v9.0.0")
+        result = self.decision(data, "refresh")
+        self.assertIn("was stale", result["reason"])
+        self.assertIn(self.PARENT, result["reason"])
+        self.assertEqual(result["targets"], [{
+            "version": "1.2.0", "release_branch": "release-v1.2.0", "commit": self.SHA,
+        }])
+
+    def test_missing_or_invalid_marker_is_stale(self):
+        for body in (None, "", "no marker", f"<!-- release-settle: v1.1.0 {self.PARENT} -->",
+                     "<!-- release-settle: v1.2.0 bad-sha -->"):
+            with self.subTest(body=body):
+                data = self.fixture()
+                data["pulls"][0]["body"] = body
+                result = self.decision(data, "refresh")
+                self.assertIn("was stale", result["reason"])
+                self.assertNotIn("None", result["reason"])
+
+    def test_tag_and_release_exist_skips_before_pr_checks(self):
+        data = self.fixture()
+        data.update(tag_exists=True, release_exists=True, pulls=[])
+        result = self.decision(data, "skip")
+        self.assertIn("v1.2.0 is already published", result["reason"])
+
+    def test_fresh_merge_of_an_older_version_is_not_published(self):
+        # release-v1.2.1 (a hotfix line) is merged after v1.3.0 was published.
+        data = self.fixture()
+        data.update(latest_tag="v1.3.0")
+        for tag_exists in (False, True):
+            with self.subTest(tag_exists=tag_exists):
+                data["tag_exists"] = tag_exists
+                result = self.decision(data, "skip")
+                self.assertIn("refusing to publish settle PR #42", result["reason"])
+                self.assertIn("v1.2.0 is not newer than the latest published tag v1.3.0", result["reason"])
+                self.assertIn(rt.ORDER_RULE, result["reason"])
+
+    def test_fresh_merge_of_the_same_version_as_latest_is_not_published(self):
+        data = self.fixture()
+        data.update(latest_tag="v1.2.0")
+        self.assertIn("not newer than the latest published tag v1.2.0", self.decision(data, "skip")["reason"])
+
+    def test_unparsable_latest_tag_skips_instead_of_failing(self):
+        for pulls in ("fresh", "none"):
+            with self.subTest(pulls=pulls):
+                data = self.fixture()
+                data["latest_tag"] = "v1.3.0-rc1"
+                if pulls == "none":
+                    data["pulls"] = []
+                result = self.decision(data, "skip")
+                self.assertIn("'v1.3.0-rc1' is not vX.Y.Z", result["reason"])
+        data = self.dispatch_fixture()
+        data["latest_tag"] = "v1.3.0-rc1"
+        self.decision(data, "skip")
+
+    def test_tag_without_release_fresh_merge_resumes_publish(self):
+        data = self.fixture()
+        data["tag_exists"] = True
+        self.decision(data, "publish")
+
+    def test_tag_without_release_other_push_requires_rerun(self):
+        for state in ("no-pr", "stale", "missing", "wrong-author", "unmerged"):
+            with self.subTest(state=state):
+                data = self.fixture()
+                data["tag_exists"] = True
+                if state == "no-pr":
+                    data["pulls"] = []
+                elif state == "stale":
+                    data["first_parent"] = "c" * 40
+                elif state == "missing":
+                    data["pulls"][0]["body"] = None
+                elif state == "wrong-author":
+                    data["pulls"][0]["user"]["login"] = "mega-maxwell[bot]"
+                else:
+                    data["pulls"][0]["merged_at"] = None
+                result = self.decision(data, "skip")
+                self.assertIn("v1.2.0 is tagged but has no Release", result["reason"])
+                self.assertIn("re-run the release-settle run", result["reason"])
+                self.assertIn("merge commit to finish publishing", result["reason"])
+                self.assertNotIn("<", result["reason"])
+
+    def test_tag_without_release_reason_names_existing_tag_commit(self):
+        data = self.fixture()
+        data.update(tag_exists=True, pulls=[], tag_commit="c" * 40)
+        result = self.decision(data, "skip")
+        self.assertIn(f"merge commit {'c' * 40} to finish publishing", result["reason"])
+        data["tag_commit"] = None
+        self.assertIn("merge commit to finish publishing", self.decision(data, "skip")["reason"])
+
+    def test_unpublished_branch_refreshes_without_matching_pr(self):
+        data = self.fixture()
+        data["pulls"] = []
+        result = self.decision(data, "refresh")
+        self.assertEqual(result["targets"], [{
+            "version": "1.2.0", "release_branch": "release-v1.2.0", "commit": self.SHA,
+        }])
+
+    def test_version_file_not_yet_bumped_skips(self):
+        for version in (None, "1.1.0"):
+            with self.subTest(version=version):
+                data = self.fixture()
+                data.update(pulls=[], version_at_sha=version)
+                result = self.decision(data, "skip")
+                self.assertIn("candidate has not landed", result["reason"])
+
+    def test_old_or_equal_version_skips(self):
+        for latest in ("v1.2.0", "v1.10.0"):
+            with self.subTest(latest=latest):
+                data = self.fixture()
+                data.update(pulls=[], latest_tag=latest)
+                self.decision(data, "skip")
+
+    def test_no_latest_tag_refreshes(self):
+        data = self.fixture()
+        data.update(pulls=[], latest_tag="")
+        self.decision(data, "refresh")
+
+    def dispatch_fixture(self):
+        data = self.fixture()
+        data.update(event="workflow_dispatch", branches=[
+            {"name": "release-v1.2.0", "tip": self.SHA, "version_at_tip": "1.2.0", "tag_exists": False},
+            {"name": "release-v1.3.0", "tip": self.PARENT, "version_at_tip": "1.3.0", "tag_exists": True},
+        ])
+        return data
+
+    def test_dispatch_two_branches_excludes_tagged_branch(self):
+        result = self.decision(self.dispatch_fixture(), "refresh")
+        self.assertEqual(result["targets"], [{
+            "version": "1.2.0", "release_branch": "release-v1.2.0", "commit": self.SHA,
+        }])
+
+    def test_dispatch_version_filter(self):
+        data = self.dispatch_fixture()
+        data["branches"][1]["tag_exists"] = False
+        data["dispatch_version"] = "v1.3.0"
+        result = self.decision(data, "refresh")
+        self.assertEqual(result["targets"], [{
+            "version": "1.3.0", "release_branch": "release-v1.3.0", "commit": self.PARENT,
+        }])
+        data["dispatch_version"] = "9.9.9"
+        self.decision(data, "skip")
+
+    def test_dispatch_excludes_unbumped_old_and_unrelated_branches(self):
+        data = self.dispatch_fixture()
+        data["branches"] = [
+            {"name": "main", "tip": self.SHA, "version_at_tip": "1.2.0", "tag_exists": False},
+            {"name": "release-v1.2.0", "tip": self.SHA, "version_at_tip": None, "tag_exists": False},
+            {"name": "release-v1.1.0", "tip": self.SHA, "version_at_tip": "1.1.0", "tag_exists": False},
+        ]
+        self.decision(data, "skip")
+        data["branches"] = []
+        self.decision(data, "skip")
+
+    def test_custom_branch_prefix(self):
+        data = self.fixture()
+        data.update(prefix="stable-", ref_name="stable-1.2.0", pulls=[])
+        result = self.decision(data, "refresh")
+        self.assertEqual(result["targets"][0]["release_branch"], "stable-1.2.0")
+        data = self.dispatch_fixture()
+        data.update(prefix="stable-")
+        data["branches"][0]["name"] = "stable-1.2.0"
+        self.decision(data, "refresh")
+
+    def test_other_kind_event_or_ref_skips_with_context(self):
+        for kind, event, ref in (
+            ("unknown", "push", "main"), ("candidate", "push", "other"),
+            ("settle", "push", "main"), ("candidate", "workflow_dispatch", "main"),
+            ("settle", "schedule", "release-v1.2.0"),
+        ):
+            with self.subTest(kind=kind, event=event, ref=ref):
+                data = self.fixture()
+                data.update(kind=kind, event=event, ref_name=ref)
+                result = self.decision(data, "skip")
+                for value in (kind, event, ref):
+                    self.assertIn(value, result["reason"])
+
+    def test_unparsable_release_branch_push_skips_naming_branch(self):
+        for ref in ("release-vnext", "release-v1.2", "release-v"):
+            with self.subTest(ref=ref):
+                data = self.fixture()
+                data.update(ref_name=ref, version_at_sha=None)
+                result = self.decision(data, "skip")
+                self.assertIn(ref, result["reason"])
+                self.assertEqual(result["version"], "")
+
+    def test_dispatch_ignores_unparsable_release_branch(self):
+        data = self.dispatch_fixture()
+        data["branches"].insert(0, {
+            "name": "release-vnext", "tip": self.PARENT, "version_at_tip": None, "tag_exists": False,
+        })
+        result = self.decision(data, "refresh")
+        self.assertEqual([t["release_branch"] for t in result["targets"]], ["release-v1.2.0"])
+
+    def test_null_fields_behave_like_absent(self):
+        data = self.fixture()
+        data.update(pulls=None, latest_tag=None, prefix=None, pr_author=None, first_parent=None)
+        self.assertEqual(self.decision(data, "refresh")["targets"][0]["release_branch"], "release-v1.2.0")
+        data = self.dispatch_fixture()
+        data.update(latest_tag=None, dispatch_version=None)
+        self.decision(data, "refresh")
+        data.update(branches=None)
+        self.decision(data, "skip")
+        for key in ("ref_name", "kind", "event"):
+            with self.subTest(key=key):
+                data = self.fixture()
+                data[key] = None
+                self.decision(data, "skip")
+
+    def test_route_cli_rejects_wrong_types_without_traceback(self):
+        for data in (
+            {"kind": "settle", "event": "push", "ref_name": 7},
+            {**self.fixture(), "pulls": {"number": 1}},
+            {**self.fixture(), "pulls": ["x"]},
+            {**self.dispatch_fixture(), "branches": [None]},
+        ):
+            with self.subTest(data=data):
+                stdout, stderr = io.StringIO(), io.StringIO()
+                with patch("sys.stdin", io.StringIO(json.dumps(data))), contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
+                    self.assertEqual(rt.main(["route"]), 1)
+                self.assertEqual(stdout.getvalue(), "")
+                self.assertTrue(stderr.getvalue().startswith("release_tools: "))
+                self.assertEqual(len(stderr.getvalue().splitlines()), 1)
+
+    def test_route_cli_json_and_invalid_input(self):
+        for raw, code in ((json.dumps(self.fixture()), 0), ("not json", 1), ("[]", 1)):
+            with self.subTest(raw=raw):
+                stdout, stderr = io.StringIO(), io.StringIO()
+                with patch("sys.stdin", io.StringIO(raw)), contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
+                    self.assertEqual(rt.main(["route"]), code)
+                if code == 0:
+                    self.assertEqual(json.loads(stdout.getvalue())["action"], "publish")
+                    self.assertEqual(stderr.getvalue(), "")
+                else:
+                    self.assertEqual(stdout.getvalue(), "")
+                    self.assertIn("release_tools:", stderr.getvalue())
+                    self.assertNotIn("Traceback", stderr.getvalue())
+
 
 class VersionFiles(unittest.TestCase):
     def test_plain(self):
diff --git a/.github/scripts/app_token_lint.py b/.github/scripts/app_token_lint.py
new file mode 100644
index 0000000..45a3531
--- /dev/null
+++ b/.github/scripts/app_token_lint.py
@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+"""Lint GitHub App token minting in workflow files.
+
+The org has two GitHub Apps that mint tokens through actions/create-github-app-token:
+
+  Maxwell    CI app (vars.MEGA_MAXWELL_CLIENT_ID / secrets.MEGA_MAXWELL_PK, older
+             names CI_APP_ID / MEGA_CI_APP_PK). Its commits and PRs are what
+             automation shows as `mega-maxwell[bot]`; it never touches a release.
+  Gutenberg  Release app (vars.RELEASE_APP_CLIENT_ID / secrets.RELEASE_APP_PRIVATE_KEY),
+             only usable from a job in the `release` environment.
+
+Rules, each reported as `::error file=<path>::<job>/<step>: <rule>: <message>`:
+
+  L1  A Maxwell token may not request `permission-<x>: write` except for
+      pull-requests and issues (a permission that is not a literal value, such as
+      an expression, cannot be verified and is refused too).
+  L2  A Gutenberg token must sit in a job whose `environment` is `release`, or in a
+      `publish` job when the token requests exactly `permission-contents: read`
+      (private-dependency reads in on-release build jobs).
+  L3  In a release workflow, no Maxwell token at all; and a Gutenberg read-only
+      dependency token's `repositories:` must not name the repository itself.
+  L4  A release workflow may not use `mega-maxwell[bot]` as a git identity or a
+      PR author filter.
+  L5  `environment: release` may appear only in release-candidate.yml,
+      release-settle.yml and on-release.yml.
+  L6  A Maxwell or Gutenberg token, and any app token in a release workflow or
+      a `release`-environment job, must request at least one `permission-<x>`:
+      without one, create-github-app-token returns every permission the
+      installation has, contents write included.
+
+A release workflow is one that uses megaeth-labs/.github's release-candidate,
+release-settle, release-publish or release-route action, or is on-release.yml.
+
+Input problems (unreadable or malformed YAML, a missing path, a directory without
+workflow files) are errors too, so a broken file never lints clean.
+
+stdlib only, except PyYAML (present on GitHub-hosted runners). No network.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+from collections.abc import Iterator
+from pathlib import Path
+
+import yaml
+
+TOKEN_ACTION = "actions/create-github-app-token@"
+MAXWELL_MARKERS = ("MEGA_MAXWELL_", "CI_APP_ID", "MEGA_CI_APP_PK")
+GUTENBERG_MARKER = "RELEASE_APP_"
+MAXWELL_WRITABLE = {"permission-pull-requests", "permission-issues"}
+RELEASE_USES = re.compile(r"megaeth-labs/\.github/\.github/actions/release-(candidate|settle|publish|route)")
+ON_RELEASE = "on-release"
+RELEASE_ENVIRONMENT_FILES = {"release-candidate", "release-settle", ON_RELEASE}
+MAXWELL_IDENTITY = "mega-maxwell[bot]"
+WORKFLOW_SUFFIXES = (".yml", ".yaml")
+
+Violation = tuple[str, str, str, str]
+
+
+def escape_data(text: str) -> str:
+    return text.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+
+
+def escape_property(text: str) -> str:
+    return escape_data(text).replace(":", "%3A").replace(",", "%2C")
+
+
+def error_line(path: str, violation: Violation) -> str:
+    job, step, rule, message = violation
+    return f"::error file={escape_property(path)}::{escape_data(f'{job}/{step}: {rule}: {message}')}"
+
+
+def strings(node: object) -> Iterator[str]:
+    if isinstance(node, str):
+        yield node
+    elif isinstance(node, dict):
+        for key, value in node.items():
+            yield from strings(key)
+            yield from strings(value)
+    elif isinstance(node, list):
+        for value in node:
+            yield from strings(value)
+
+
+def mentions_maxwell_identity(node: object) -> bool:
+    return any(MAXWELL_IDENTITY in text.lower() for text in strings(node))
+
+
+def environment_name(job: dict) -> str | None:
+    environment = job.get("environment")
+    if isinstance(environment, dict):
+        environment = environment.get("name")
+    return environment.strip() if isinstance(environment, str) else None
+
+
+def step_label(step: dict, index: int) -> str:
+    for key in ("name", "id"):
+        if isinstance(step.get(key), str) and step[key].strip():
+            return " ".join(step[key].split())
+    return f"#{index}"
+
+
+def permissions_of(with_: dict) -> dict[str, str]:
+    return {str(k): str(v).strip() for k, v in with_.items() if str(k).startswith("permission-")}
+
+
+def is_read_only_contents(permissions: dict[str, str]) -> bool:
+    return {k: v.lower() for k, v in permissions.items()} == {"permission-contents": "read"}
+
+
+def repository_names(with_: dict) -> set[str]:
+    names = re.split(r"[\s,]+", str(with_.get("repositories") or ""))
+    return {n.rsplit("/", 1)[-1].lower() for n in names if n}
+
+
+def is_release_workflow(path: str, doc: dict) -> bool:
+    if Path(path).stem == ON_RELEASE:
+        return True
+    jobs = doc.get("jobs") if isinstance(doc.get("jobs"), dict) else {}
+    for job in jobs.values():
+        if not isinstance(job, dict):
+            continue
+        uses = [job.get("uses")] + [s.get("uses") for s in job.get("steps") or [] if isinstance(s, dict)]
+        if any(isinstance(u, str) and RELEASE_USES.search(u) for u in uses):
+            return True
+    return False
+
+
+def lint_job(job_id: str, job: dict, stem: str, release: bool, repo: str | None) -> list[Violation]:
+    found: list[Violation] = []
+    environment = environment_name(job)
+    if environment == "release" and stem not in RELEASE_ENVIRONMENT_FILES:
+        found.append((job_id, "-", "L5", "environment `release` is only for release-candidate.yml, release-settle.yml and on-release.yml"))
+    if release and mentions_maxwell_identity({k: v for k, v in job.items() if k != "steps"}):
+        found.append((job_id, "-", "L4", f"{MAXWELL_IDENTITY} is not a release identity"))
+    steps = job.get("steps") if isinstance(job.get("steps"), list) else []
+    for index, step in enumerate(steps, start=1):
+        if not isinstance(step, dict):
+            found.append((job_id, f"#{index}", "parse", "step is not a mapping"))
+            continue
+        label = step_label(step, index)
+        if release and mentions_maxwell_identity(step):
+            found.append((job_id, label, "L4", f"{MAXWELL_IDENTITY} is not a release identity"))
+        uses = step.get("uses")
+        if not (isinstance(uses, str) and uses.startswith(TOKEN_ACTION)):
+            continue
+        with_ = step.get("with") if isinstance(step.get("with"), dict) else {}
+        refs = " ".join(str(with_.get(k, "")) for k in ("client-id", "app-id", "private-key"))
+        permissions = permissions_of(with_)
+        maxwell = any(m in refs for m in MAXWELL_MARKERS)
+        if not permissions and (maxwell or GUTENBERG_MARKER in refs or release or environment == "release"):
+            app = "Maxwell" if maxwell else "Gutenberg" if GUTENBERG_MARKER in refs else "app"
+            found.append((job_id, label, "L6", f"{app} token requests no permission-* inputs, so it gets every permission of the installation (contents write included); list the permissions it needs"))
+        if maxwell:
+            for name, value in permissions.items():
+                if name not in MAXWELL_WRITABLE and (value.lower() == "write" or "${{" in value):
+                    found.append((job_id, label, "L1", f"Maxwell token requests {name}: {value}; Maxwell may only write pull-requests and issues"))
+            if release:
+                found.append((job_id, label, "L3", "no Maxwell token in a release workflow; mint a Gutenberg token instead"))
+        if GUTENBERG_MARKER in refs:
+            if not (environment == "release" or (environment == "publish" and is_read_only_contents(permissions))):
+                found.append((job_id, label, "L2", f"Gutenberg token needs `environment: release` (or `publish` with only permission-contents: read), job has {environment or 'none'}"))
+            if release and repo and is_read_only_contents(permissions) and repo.lower() in repository_names(with_):
+                found.append((job_id, label, "L3", f"read-only dependency token names the repository itself ({repo})"))
+    return found
+
+
+def lint_source(path: str, text: str, repo: str | None) -> list[str]:
+    try:
+        doc = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        mark = getattr(exc, "problem_mark", None)
+        where = f" (line {mark.line + 1})" if mark else ""
+        reason = getattr(exc, "problem", None) or str(exc)
+        return [error_line(path, ("-", "-", "parse", f"malformed YAML{where}: {reason}"))]
+    if not isinstance(doc, dict):
+        return [error_line(path, ("-", "-", "parse", "not a workflow: the document is not a mapping"))]
+    jobs = doc.get("jobs")
+    if jobs is not None and not isinstance(jobs, dict):
+        return [error_line(path, ("-", "-", "parse", "`jobs` is not a mapping"))]
+    release = is_release_workflow(path, doc)
+    stem = Path(path).stem
+    found: list[Violation] = []
+    if release and mentions_maxwell_identity({k: v for k, v in doc.items() if k != "jobs"}):
+        found.append(("(workflow)", "-", "L4", f"{MAXWELL_IDENTITY} is not a release identity"))
+    for job_id, job in (jobs or {}).items():
+        if isinstance(job, dict):
+            found.extend(lint_job(str(job_id), job, stem, release, repo))
+        else:
+            found.append((str(job_id), "-", "parse", "job is not a mapping"))
+    return [error_line(path, v) for v in found]
+
+
+def collect(paths: list[str]) -> tuple[list[str], list[str]]:
+    files: list[str] = []
+    errors: list[str] = []
+    for given in paths:
+        path = Path(given)
+        if path.is_dir():
+            here = sorted(str(f) for f in path.iterdir() if f.is_file() and f.suffix in WORKFLOW_SUFFIXES)
+            if not here:
+                errors.append(error_line(given, ("-", "-", "input", "no workflow files (*.yml, *.yaml) found")))
+            files.extend(here)
+        elif path.is_file():
+            files.append(given)
+        else:
+            errors.append(error_line(given, ("-", "-", "input", "no such file or directory")))
+    return files, errors
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    parser.add_argument("paths", nargs="+", help="workflow files or directories of them")
+    parser.add_argument("--repo", help="name of the repository being linted (default: from $GITHUB_REPOSITORY)")
+    args = parser.parse_args()
+    repo = (args.repo or os.environ.get("GITHUB_REPOSITORY") or "").rsplit("/", 1)[-1] or None
+    if repo is None:
+        print("::warning::app-token-lint: repository name unknown (pass --repo); the own-repository check of L3 is skipped")
+    files, errors = collect(args.paths)
+    for file in files:
+        try:
+            text = Path(file).read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError) as exc:
+            errors.append(error_line(file, ("-", "-", "parse", f"cannot read file: {exc}")))
+            continue
+        errors.extend(lint_source(file, text, repo))
+    for line in errors:
+        print(line)
+    if errors:
+        print(f"app-token-lint: {len(errors)} violation(s) in {len(files)} file(s)")
+        return 1
+    print(f"app-token-lint: {len(files)} file(s) clean")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.github/scripts/copy_templates.py b/.github/scripts/copy_templates.py
new file mode 100644
index 0000000..ea8d4fc
--- /dev/null
+++ b/.github/scripts/copy_templates.py
@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""Render the release workflow templates for one repository.
+
+GitHub's "New workflow" picker only fills `$default-branch`; everything else
+in workflow-templates/ is this organisation's example value (`VERSION`,
+`plain`, the job's own repository). This script copies the release templates
+with a repository's real values filled in, so a consumer's workflows start as
+an exact copy of the reference callers:
+
+    copy_templates.py --repo mega-reth --default-branch develop \\
+        --version-file Cargo.toml --version-pattern toml \\
+        --bump-command "cargo update --workspace" \\
+        --dependency-repositories rust-rocksdb,pstd,rocksdb \\
+        --out /tmp/mega-reth-workflows
+
+Each substitution is anchored on exact template text and must match at least
+once, so a template edit that drops an anchor fails here instead of shipping
+an unfilled copy. Values are written as YAML scalars, quoted when a plain
+scalar would change them (`make bump # regenerate` would otherwise lose its
+comment-like tail). The rendered files are then checked: no placeholder left,
+every `with:` key given to a megaeth-labs/.github action is an input of that
+action (read from this checkout's action.yml) with every required input
+present, and every substituted value reads back exactly as given.
+
+`--out` must not exist: the files are written to a fresh directory, never on
+top of an earlier render. Without `--out` a new temporary directory is used.
+Copy the files into `.github/workflows/` of the target repository from there.
+
+stdlib only, except PyYAML (present on GitHub-hosted runners). No network.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+import tempfile
+from pathlib import Path
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[2]
+TEMPLATES = ROOT / "workflow-templates"
+ACTIONS = ROOT / ".github" / "actions"
+RELEASE_TEMPLATES = ("release-candidate.yml", "release-settle.yml", "app-token-lint.yml")
+SHARED_ACTION = re.compile(r"megaeth-labs/\.github/\.github/actions/(?P<name>[a-z0-9-]+)@(?P<ref>\S+)")
+TOKEN_ACTION = "actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3"
+# Template text that a render must replace; any left over is an unfilled placeholder.
+PLACEHOLDERS = ("$default-branch", "${{ github.event.repository.name }}")
+BUMP_EXAMPLE = re.compile(r"^ *# Anything else that must move with the version.*?\n(?: *#.*\n)*", re.M)
+CANDIDATE_STEP = "      - uses: megaeth-labs/.github/.github/actions/release-candidate@main\n        with:\n          stage: propose\n"
+
+
+ACTIONS_REF = re.compile(r"[A-Za-z0-9._/-]+")
+
+
+class RenderError(Exception):
+    pass
+
+
+def scalar(value: str, flow: bool = False) -> str:
+    """`value` as a YAML scalar after `key: ` (or inside `[...]` with `flow`):
+    plain when it reads back unchanged there, double-quoted otherwise."""
+    try:
+        plain = (yaml.safe_load(f"k: [{value}]") == {"k": [value]} if flow
+                 else yaml.safe_load(f"k: {value}") == {"k": value})
+    except yaml.YAMLError:
+        plain = False
+    return value if plain else json.dumps(value)
+
+
+def expected_inputs(args: argparse.Namespace) -> dict[str, str]:
+    """Inputs of the shared actions that the render fills, as they must read back."""
+    values = {"version_file": args.version_file, "version_pattern": args.version_pattern,
+              "changelog_file": args.changelog_file}
+    if args.bump_command:
+        values["bump_command"] = args.bump_command
+    return values
+
+
+def replace(text: str, old: str, new: str, name: str, what: str) -> str:
+    if old not in text:
+        raise RenderError(f"{name}: template no longer contains {old!r} ({what})")
+    return text.replace(old, new)
+
+
+def pin(text: str, ref: str) -> str:
+    return SHARED_ACTION.sub(lambda m: m[0].replace(f"@{m['ref']}", f"@{ref}"), text)
+
+
+def bump_block(bump_command: str, dependency_token: str) -> str:
+    indent = " " * 10
+    return f"{indent}bump_command: {scalar(bump_command)}\n{indent}dependency_token: {dependency_token}\n"
+
+
+def dependency_step(repositories: str) -> str:
+    return (
+        "      # bump_command reads private dependencies with its own read-only token.\n"
+        f"      - uses: {TOKEN_ACTION}\n"
+        "        id: dependency-token\n"
+        "        with:\n"
+        "          client-id: ${{ vars.RELEASE_APP_CLIENT_ID }}\n"
+        "          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}\n"
+        "          owner: megaeth-labs\n"
+        f"          repositories: {scalar(repositories)}\n"
+        "          permission-contents: read\n\n"
+    )
+
+
+def render(name: str, text: str, args: argparse.Namespace) -> str:
+    if name != "release-settle.yml":  # settle runs on release-v* pushes only
+        text = replace(text, "$default-branch", scalar(args.default_branch, flow=True), name, "default branch")
+    if name == "app-token-lint.yml":
+        return pin(text, args.actions_ref)
+    text = replace(text, "repositories: ${{ github.event.repository.name }}",
+                   f"repositories: {scalar(args.repo)}", name, "release token repository")
+    text = replace(text, "version_file: VERSION", f"version_file: {scalar(args.version_file)}", name,
+                   "version file")
+    text = replace(text, "version_pattern: plain", f"version_pattern: {scalar(args.version_pattern)}", name,
+                   "version pattern")
+    text = replace(text, "changelog_file: CHANGELOG.md", f"changelog_file: {scalar(args.changelog_file)}", name,
+                   "changelog file")
+    if name == "release-candidate.yml":
+        match = BUMP_EXAMPLE.search(text)
+        if match is None:
+            raise RenderError(f"{name}: template no longer contains the bump_command example")
+        if args.bump_command:
+            token = "${{ github.token }}"
+            if args.dependency_repositories:
+                token = "${{ steps.dependency-token.outputs.token }}"
+                text = replace(text, CANDIDATE_STEP, dependency_step(args.dependency_repositories) + CANDIDATE_STEP,
+                               name, "propose step")
+                match = BUMP_EXAMPLE.search(text)
+            text = text[:match.start()] + bump_block(args.bump_command, token) + text[match.end():]
+    return pin(text, args.actions_ref)
+
+
+def action_inputs(name: str) -> dict:
+    path = ACTIONS / name / "action.yml"
+    if not path.is_file():
+        raise RenderError(f"no action {name} in this checkout ({path})")
+    return yaml.safe_load(path.read_text()).get("inputs") or {}
+
+
+def check(name: str, text: str, expected: dict[str, str] | None = None) -> list[str]:
+    """Problems in one rendered workflow: placeholders left, unknown or missing
+    action inputs, and (given `expected`) a filled input that reads back differently."""
+    problems = [f"{name}: unfilled placeholder {p!r}" for p in PLACEHOLDERS if p in text]
+    try:
+        doc = yaml.safe_load(text)
+    except yaml.YAMLError as error:
+        return problems + [f"{name}: not valid YAML: {error}"]
+    for job_id, job in (doc.get("jobs") or {}).items():
+        for index, step in enumerate(job.get("steps") or []):
+            match = SHARED_ACTION.fullmatch(str(step.get("uses", "")))
+            if not match:
+                continue
+            inputs = action_inputs(match["name"])
+            given = step.get("with") or {}
+            where = f"{name}: {job_id}/{step.get('id') or index} ({match['name']})"
+            problems += [f"{where}: {key!r} is not an input" for key in given if key not in inputs]
+            problems += [f"{where}: required input {key!r} missing" for key, spec in inputs.items()
+                         if (spec or {}).get("required") and key not in given]
+            problems += [f"{where}: {key} reads back as {given[key]!r}, not {value!r}"
+                         for key, value in (expected or {}).items() if key in given and given[key] != value]
+    return problems
+
+
+def parse_args(argv: list[str] | None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    parser.add_argument("--repo", required=True, help="repository name, e.g. mega-reth")
+    parser.add_argument("--default-branch", required=True, help="e.g. main or develop")
+    parser.add_argument("--version-file", required=True, help="e.g. VERSION or Cargo.toml")
+    parser.add_argument("--version-pattern", required=True, help="e.g. plain, toml, json")
+    parser.add_argument("--changelog-file", default="CHANGELOG.md")
+    parser.add_argument("--bump-command", default="", help="e.g. 'cargo update --workspace'")
+    parser.add_argument("--dependency-repositories", default="",
+                        help="comma-separated private repositories bump_command reads, e.g. rust-rocksdb,pstd")
+    parser.add_argument("--actions-ref", default="main", help="ref the shared actions are pinned to")
+    parser.add_argument("--out", type=Path, help="directory to create (must not exist)")
+    args = parser.parse_args(argv)
+    for field in ("repo", "default_branch", "version_file", "version_pattern", "changelog_file", "actions_ref"):
+        if not getattr(args, field).strip():
+            parser.error(f"--{field.replace('_', '-')} must not be blank")
+    if not ACTIONS_REF.fullmatch(args.actions_ref):
+        parser.error("--actions-ref must be a branch, tag or SHA (letters, digits, . _ / -)")
+    if args.dependency_repositories and not args.bump_command:
+        parser.error("--dependency-repositories is only used by --bump-command")
+    if args.repo in {r.strip() for r in args.dependency_repositories.split(",")}:
+        parser.error("--dependency-repositories must not name the repository itself")
+    return args
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    if args.out is not None and args.out.exists():
+        print(f"error: {args.out} already exists; render into a fresh directory", file=sys.stderr)
+        return 1
+    try:
+        rendered = {name: render(name, (TEMPLATES / name).read_text(), args) for name in RELEASE_TEMPLATES}
+        problems = [p for name, text in rendered.items() for p in check(name, text, expected_inputs(args))]
+    except RenderError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 1
+    if problems:
+        for problem in problems:
+            print(f"error: {problem}", file=sys.stderr)
+        return 1
+    if args.out is None:
+        out = Path(tempfile.mkdtemp(prefix=f"{args.repo}-workflows-"))
+    else:
+        out = args.out
+        out.mkdir(parents=True)
+    for name, text in rendered.items():
+        (out / name).write_text(text)
+        print(out / name)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.github/scripts/test_app_token_lint.py b/.github/scripts/test_app_token_lint.py
new file mode 100644
index 0000000..d28c181
--- /dev/null
+++ b/.github/scripts/test_app_token_lint.py
@@ -0,0 +1,300 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+import app_token_lint
+from app_token_lint import lint_source
+
+SCRIPT = Path(app_token_lint.__file__)
+TOKEN_ACTION = "actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3"
+APPS = {
+    "maxwell": ("${{ vars.MEGA_MAXWELL_CLIENT_ID }}", "${{ secrets.MEGA_MAXWELL_PK }}"),
+    "legacy": ("${{ secrets.CI_APP_ID }}", "${{ secrets.MEGA_CI_APP_PK }}"),
+    "gutenberg": ("${{ vars.RELEASE_APP_CLIENT_ID }}", "${{ secrets.RELEASE_APP_PRIVATE_KEY }}"),
+    "other": ("${{ vars.SOMETHING_ELSE_ID }}", "${{ secrets.SOMETHING_ELSE_KEY }}"),
+}
+LINE = re.compile(r"^::error file=(?P<file>[^:]*)::(?P<job>[^/]+)/(?P<step>.+?): (?P<rule>\w+): ")
+
+
+def job(name="build", *, environment=None, app="maxwell", permissions=None, repositories=None,
+        release_step=False, run=None, job_if=None):
+    lines = [f"  {name}:", "    runs-on: ubuntu-24.04"]
+    if job_if is not None:
+        lines.append(f"    if: {job_if}")
+    if environment is not None:
+        lines.append(f"    environment: {environment}")
+    lines.append("    steps:")
+    if release_step:
+        lines.append("      - uses: megaeth-labs/.github/.github/actions/release-settle@main")
+    if app:
+        client, key = APPS[app]
+        lines += [f"      - uses: {TOKEN_ACTION}", "        id: token", "        with:",
+                  f"          client-id: {client}", f"          private-key: {key}", "          owner: megaeth-labs"]
+        if repositories:
+            lines.append("          repositories: |")
+            lines += [f"            {r}" for r in repositories]
+        for permission, value in (permissions or {}).items():
+            lines.append(f"          permission-{permission}: {value}")
+    if run is not None:
+        lines += ["      - run: |", f"          {run}"]
+    return "\n".join(lines) + "\n"
+
+
+def workflow(*jobs, top=""):
+    return "name: t\non: push\n" + top + "jobs:\n" + "".join(jobs)
+
+
+def lint(path, text, repo="my-repo"):
+    return lint_source(path, text, repo)
+
+
+def rules(lines):
+    return [(m["rule"], m["job"]) for m in (LINE.match(line) for line in lines)]
+
+
+class L1Maxwell(unittest.TestCase):
+    def test_pull_requests_and_issues_write_and_contents_read_pass(self):
+        text = workflow(job(permissions={"contents": "read", "pull-requests": "write", "issues": "write"}))
+        self.assertEqual(lint("ci.yml", text), [])
+
+    def test_contents_write_fails_with_the_documented_line(self):
+        lines = lint("ci.yml", workflow(job(permissions={"contents": "write"})))
+        self.assertEqual(rules(lines), [("L1", "build")])
+        self.assertTrue(lines[0].startswith("::error file=ci.yml::build/token: L1: "))
+
+    def test_older_app_names_are_maxwell_too(self):
+        lines = lint("ci.yml", workflow(job(app="legacy", permissions={"workflows": "write"})))
+        self.assertEqual(rules(lines), [("L1", "build")])
+
+    def test_unverifiable_permission_fails(self):
+        lines = lint("ci.yml", workflow(job(permissions={"contents": "${{ inputs.level }}"})))
+        self.assertEqual(rules(lines), [("L1", "build")])
+
+    def test_other_apps_are_not_checked(self):
+        self.assertEqual(lint("ci.yml", workflow(job(app="other", permissions={"contents": "write"}))), [])
+
+
+class L6ExplicitPermissions(unittest.TestCase):
+    def test_maxwell_token_without_permissions_fails(self):
+        # create-github-app-token without permission-* returns the
+        # installation's full set, contents write included.
+        for app in ("maxwell", "legacy"):
+            with self.subTest(app=app):
+                lines = lint("ci.yml", workflow(job(app=app)))
+                self.assertEqual(rules(lines), [("L6", "build")])
+                self.assertTrue(lines[0].startswith("::error file=ci.yml::build/token: L6: Maxwell token requests no permission-* inputs"))
+
+    def test_gutenberg_token_without_permissions_fails_even_in_release(self):
+        text = workflow(job(app="gutenberg", environment="release", release_step=True))
+        self.assertEqual(rules(lint("release-settle.yml", text)), [("L6", "build")])
+
+    def test_any_app_token_in_a_release_job_needs_permissions(self):
+        self.assertEqual(rules(lint("ci.yml", workflow(job(app="other", release_step=True)))), [("L6", "build")])
+        text = workflow(job(app="other", environment="release"))
+        self.assertEqual(rules(lint("release-candidate.yml", text)), [("L6", "build")])
+
+    def test_other_app_outside_release_jobs_is_not_checked(self):
+        self.assertEqual(lint("ci.yml", workflow(job(app="other"))), [])
+
+    def test_a_single_read_permission_is_enough(self):
+        self.assertEqual(lint("ci.yml", workflow(job(permissions={"contents": "read"}))), [])
+
+
+class L2GutenbergEnvironment(unittest.TestCase):
+    WRITE = {"contents": "write", "pull-requests": "write"}
+
+    def test_release_environment_as_string_passes(self):
+        self.assertEqual(lint("release-candidate.yml", workflow(job(app="gutenberg", environment="release", permissions=self.WRITE))), [])
+
+    def test_release_environment_as_mapping_passes(self):
+        text = workflow(job(app="gutenberg", environment="{ name: release }", permissions=self.WRITE))
+        self.assertEqual(lint("release-settle.yml", text), [])
+
+    def test_publish_environment_with_only_contents_read_passes(self):
+        text = workflow(job(app="gutenberg", environment="publish", permissions={"contents": "read"}, repositories=["rust-rocksdb"]))
+        self.assertEqual(lint("on-release.yml", text), [])
+
+    def test_no_environment_fails(self):
+        self.assertEqual(rules(lint("ci.yml", workflow(job(app="gutenberg", permissions=self.WRITE)))), [("L2", "build")])
+
+    def test_other_environment_fails(self):
+        text = workflow(job(app="gutenberg", environment="staging", permissions={"contents": "read"}))
+        self.assertEqual(rules(lint("ci.yml", text)), [("L2", "build")])
+
+    def test_publish_environment_with_write_fails(self):
+        text = workflow(job(app="gutenberg", environment="publish", permissions={"contents": "write"}))
+        self.assertEqual(rules(lint("on-release.yml", text)), [("L2", "build")])
+
+    def test_publish_environment_with_more_than_contents_read_fails(self):
+        text = workflow(job(app="gutenberg", environment="publish", permissions={"contents": "read", "pull-requests": "read"}))
+        self.assertEqual(rules(lint("on-release.yml", text)), [("L2", "build")])
+
+
+class L3ReleaseWorkflows(unittest.TestCase):
+    def test_maxwell_token_in_a_workflow_using_a_release_action_fails(self):
+        text = workflow(job(release_step=True, permissions={"contents": "read"}))
+        self.assertEqual(rules(lint("ci.yml", text)), [("L3", "build")])
+
+    def test_maxwell_token_in_on_release_fails_by_name(self):
+        text = workflow(job(permissions={"contents": "read"}))
+        self.assertEqual(rules(lint("on-release.yml", text)), [("L3", "build")])
+
+    def test_read_only_maxwell_token_outside_release_workflows_passes(self):
+        text = workflow(job(permissions={"contents": "read"}, repositories=["rust-rocksdb"]))
+        self.assertEqual(lint("snapshot-publish.yml", text), [])
+
+    def test_dependency_read_token_naming_the_repository_fails(self):
+        text = workflow(job(app="gutenberg", environment="release", permissions={"contents": "read"}, repositories=["pstd", "My-Repo"]))
+        self.assertEqual(rules(lint("on-release.yml", text)), [("L3", "build")])
+
+    def test_owner_qualified_repository_name_is_still_the_repository(self):
+        text = workflow(job(app="gutenberg", environment="release", permissions={"contents": "read"}, repositories=["megaeth-labs/my-repo"]))
+        self.assertEqual(rules(lint("on-release.yml", text)), [("L3", "build")])
+
+    def test_dependency_read_token_naming_only_dependencies_passes(self):
+        text = workflow(job(app="gutenberg", environment="release", permissions={"contents": "read"}, repositories=["rust-rocksdb", "pstd"]))
+        self.assertEqual(lint("on-release.yml", text), [])
+
+    def test_write_token_for_the_repository_itself_passes(self):
+        text = workflow(job(app="gutenberg", environment="release", release_step=True,
+                            permissions={"contents": "write", "pull-requests": "write"}, repositories=["my-repo"]))
+        self.assertEqual(lint("release-candidate.yml", text), [])
+
+    def test_without_a_repository_name_the_own_repository_check_is_skipped(self):
+        text = workflow(job(app="gutenberg", environment="release", permissions={"contents": "read"}, repositories=["my-repo"]))
+        self.assertEqual(lint_source("on-release.yml", text, None), [])
+
+
+class L4MaxwellIdentity(unittest.TestCase):
+    def test_git_identity_in_a_release_step_fails(self):
+        text = workflow(job(app=None, environment="release", release_step=True, run='git config user.name "mega-maxwell[bot]"'))
+        self.assertEqual(rules(lint("release-settle.yml", text)), [("L4", "build")])
+
+    def test_pr_author_filter_in_a_release_job_condition_fails(self):
+        text = workflow(job(app=None, release_step=True, job_if="\"github.event.pull_request.user.login == 'mega-maxwell[bot]'\""))
+        lines = lint("release-publish.yml", text)
+        self.assertEqual(rules(lines), [("L4", "build")])
+        self.assertIn("build/-: L4:", lines[0])
+
+    def test_workflow_level_value_fails(self):
+        text = workflow(job(app=None, release_step=True), top="env:\n  BOT: mega-maxwell[bot]\n")
+        self.assertEqual(rules(lint("release-publish.yml", text)), [("L4", "(workflow)")])
+
+    def test_same_identity_outside_a_release_workflow_passes(self):
+        text = workflow(job(app=None, run='git config user.name "mega-maxwell[bot]"'))
+        self.assertEqual(lint("ci.yml", text), [])
+
+    def test_gutenberg_identity_in_a_release_workflow_passes(self):
+        text = workflow(job(app=None, environment="release", release_step=True, run='git config user.name "mega-gutenberg[bot]"'))
+        self.assertEqual(lint("release-settle.yml", text), [])
+
+
+class L5ReleaseEnvironment(unittest.TestCase):
+    def test_release_environment_in_another_file_fails(self):
+        self.assertEqual(rules(lint("ci.yml", workflow(job(app=None, environment="release")))), [("L5", "build")])
+
+    def test_release_environment_as_mapping_in_another_file_fails(self):
+        text = workflow(job(app=None, environment="{ name: release }"))
+        self.assertEqual(rules(lint("release-publish.yml", text)), [("L5", "build")])
+
+    def test_release_environment_in_the_three_allowed_files_passes(self):
+        text = workflow(job(app=None, environment="release"))
+        for name in ("release-candidate.yml", "release-settle.yml", "on-release.yml"):
+            with self.subTest(name):
+                self.assertEqual(lint(name, text), [])
+
+    def test_other_environments_are_free(self):
+        self.assertEqual(lint("ci.yml", workflow(job(app=None, environment="publish"))), [])
+
+
+class MalformedInput(unittest.TestCase):
+    def assert_parse_error(self, text, where="-/-"):
+        lines = lint("bad.yml", text)
+        self.assertEqual(len(lines), 1, lines)
+        self.assertTrue(lines[0].startswith(f"::error file=bad.yml::{where}: parse: "), lines[0])
+
+    def test_broken_yaml_is_an_error_line_not_a_traceback(self):
+        self.assert_parse_error("jobs:\n  a: [unclosed\n")
+
+    def test_empty_file_is_an_error(self):
+        self.assert_parse_error("")
+
+    def test_scalar_document_is_an_error(self):
+        self.assert_parse_error("just a string\n")
+
+    def test_jobs_that_is_a_list_is_an_error(self):
+        self.assert_parse_error("jobs:\n  - a\n")
+
+    def test_a_job_that_is_not_a_mapping_is_an_error(self):
+        self.assert_parse_error("jobs:\n  build: nope\n", "build/-")
+
+    def test_a_step_that_is_not_a_mapping_is_an_error(self):
+        self.assert_parse_error("jobs:\n  build:\n    steps:\n      - just-a-string\n", "build/#1")
+
+    def test_token_step_without_with_is_ignored(self):
+        text = ("jobs:\n  build:\n    runs-on: x\n    steps:\n"
+                "      - uses: actions/create-github-app-token@v3\n"
+                "      - uses: actions/create-github-app-token@v3\n        with:\n"
+                "      - run: echo\n")
+        self.assertEqual(lint("ci.yml", text), [])
+
+
+class CommandLine(unittest.TestCase):
+    def run_cli(self, *args, repository=None):
+        env = {k: v for k, v in os.environ.items() if k != "GITHUB_REPOSITORY"}
+        if repository:
+            env["GITHUB_REPOSITORY"] = repository
+        return subprocess.run([sys.executable, "-I", str(SCRIPT), *args], capture_output=True, text=True, env=env)
+
+    def directory(self, files):
+        tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(tmp.cleanup)
+        for name, text in files.items():
+            Path(tmp.name, name).write_text(text)
+        return tmp.name
+
+    def test_clean_directory_exits_zero(self):
+        directory = self.directory({"release-settle.yml": workflow(job(app="gutenberg", environment="release", release_step=True, permissions={"contents": "write"})),
+                                    "release-settle.properties.json": "{not yaml"})
+        result = self.run_cli("--repo", "my-repo", directory)
+        self.assertEqual((result.returncode, result.stderr), (0, ""))
+        self.assertIn("1 file(s) clean", result.stdout)
+
+    def test_violations_exit_one_with_error_lines_naming_the_file(self):
+        directory = self.directory({"ci.yml": workflow(job(permissions={"contents": "write"}))})
+        result = self.run_cli("--repo", "my-repo", directory)
+        self.assertEqual(result.returncode, 1)
+        self.assertIn(f"::error file={directory}/ci.yml::build/token: L1: ", result.stdout)
+
+    def test_malformed_file_exits_one_without_a_traceback(self):
+        directory = self.directory({"bad.yml": "jobs:\n  a: [unclosed\n"})
+        result = self.run_cli("--repo", "my-repo", directory)
+        self.assertEqual(result.returncode, 1)
+        self.assertNotIn("Traceback", result.stderr)
+        self.assertIn("::error file=", result.stdout)
+
+    def test_missing_path_and_empty_directory_exit_one(self):
+        empty = self.directory({})
+        for target in (empty + "/nope.yml", empty):
+            with self.subTest(target):
+                result = self.run_cli("--repo", "my-repo", target)
+                self.assertEqual(result.returncode, 1)
+                self.assertIn("::error file=", result.stdout)
+
+    def test_repository_defaults_to_github_repository(self):
+        directory = self.directory({"on-release.yml": workflow(job(app="gutenberg", environment="release", permissions={"contents": "read"}, repositories=["my-repo"]))})
+        self.assertEqual(self.run_cli(directory, repository="megaeth-labs/my-repo").returncode, 1)
+        unknown = self.run_cli(directory)
+        self.assertEqual(unknown.returncode, 0)
+        self.assertIn("::warning::", unknown.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/.github/scripts/test_copy_templates.py b/.github/scripts/test_copy_templates.py
new file mode 100644
index 0000000..419fc5c
--- /dev/null
+++ b/.github/scripts/test_copy_templates.py
@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import contextlib
+import io
+import tempfile
+import unittest
+from pathlib import Path
+
+import yaml
+
+import app_token_lint
+import copy_templates
+from copy_templates import PLACEHOLDERS, RELEASE_TEMPLATES, TEMPLATES, RenderError, check, main, parse_args, render
+
+MEGA_RETH = [
+    "--repo", "mega-reth", "--default-branch", "develop",
+    "--version-file", "Cargo.toml", "--version-pattern", "toml",
+    "--bump-command", "cargo update --workspace",
+    "--dependency-repositories", "rust-rocksdb,pstd,rocksdb",
+]
+
+
+def run(argv):
+    out, err = io.StringIO(), io.StringIO()
+    with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+        code = main(argv)
+    return code, out.getvalue(), err.getvalue()
+
+
+def steps(doc, job):
+    return doc["jobs"][job]["steps"]
+
+
+def shared(doc, job, action):
+    return [s for s in steps(doc, job) if f"/.github/actions/{action}@" in str(s.get("uses", ""))]
+
+
+class MegaRethRender(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.tmp = tempfile.TemporaryDirectory()
+        cls.out = Path(cls.tmp.name) / "workflows"
+        code, _, err = run(MEGA_RETH + ["--out", str(cls.out)])
+        assert code == 0, err
+        cls.text = {name: (cls.out / name).read_text() for name in RELEASE_TEMPLATES}
+        cls.doc = {name: yaml.safe_load(text) for name, text in cls.text.items()}
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.tmp.cleanup()
+
+    def test_writes_exactly_the_release_templates(self):
+        self.assertEqual(sorted(p.name for p in self.out.iterdir()), sorted(RELEASE_TEMPLATES))
+
+    def test_no_placeholder_is_left(self):
+        for name, text in self.text.items():
+            for placeholder in PLACEHOLDERS:
+                self.assertNotIn(placeholder, text, f"{name} still has {placeholder}")
+            self.assertNotIn("version_file: VERSION", text, name)
+            self.assertNotIn("version_pattern: plain", text, name)
+
+    def test_triggers_use_the_default_branch(self):
+        self.assertEqual(self.doc["release-candidate.yml"][True]["push"]["branches"], ["develop"])
+        self.assertEqual(self.doc["app-token-lint.yml"][True]["push"]["branches"], ["develop"])
+        self.assertEqual(self.doc["release-settle.yml"][True]["push"]["branches"], ["release-v*"])
+
+    def test_every_shared_action_call_is_valid(self):
+        for name, text in self.text.items():
+            self.assertEqual(check(name, text), [], name)
+
+    def test_with_keys_are_inputs_of_the_called_action(self):
+        # Independent of check(): walk every step and compare against action.yml directly.
+        seen = 0
+        for doc in self.doc.values():
+            for job in doc["jobs"].values():
+                for step in job.get("steps") or []:
+                    match = copy_templates.SHARED_ACTION.fullmatch(str(step.get("uses", "")))
+                    if not match:
+                        continue
+                    action = yaml.safe_load((copy_templates.ACTIONS / match["name"] / "action.yml").read_text())
+                    self.assertLessEqual(set(step.get("with") or {}), set(action.get("inputs") or {}), step["uses"])
+                    seen += 1
+        self.assertEqual(seen, 7)
+
+    def test_release_tokens_are_scoped_to_the_repository(self):
+        for name, jobs in (("release-candidate.yml", ("propose", "cut")),
+                           ("release-settle.yml", ("refresh", "publish"))):
+            for job in jobs:
+                self.assertEqual(self.doc[name]["jobs"][job]["environment"], "release", job)
+                token = next(s for s in steps(self.doc[name], job) if s.get("id") == "release-token")
+                self.assertEqual(token["with"]["repositories"], "mega-reth", job)
+
+    def test_bump_command_reads_dependencies_with_a_read_only_token(self):
+        doc = self.doc["release-candidate.yml"]
+        ids = [s.get("id") for s in steps(doc, "propose")]
+        self.assertLess(ids.index("dependency-token"), len(ids) - 1)
+        dependency = steps(doc, "propose")[ids.index("dependency-token")]["with"]
+        self.assertEqual(dependency["repositories"], "rust-rocksdb,pstd,rocksdb")
+        self.assertEqual({k for k in dependency if k.startswith("permission-")}, {"permission-contents"})
+        self.assertEqual(dependency["permission-contents"], "read")
+        (propose,) = shared(doc, "propose", "release-candidate")
+        self.assertEqual(propose["with"]["bump_command"], "cargo update --workspace")
+        self.assertEqual(propose["with"]["dependency_token"], "${{ steps.dependency-token.outputs.token }}")
+        self.assertEqual(propose["with"]["version_file"], "Cargo.toml")
+        self.assertEqual(propose["with"]["version_pattern"], "toml")
+
+    def test_pr_labels_are_left_empty(self):
+        for name, text in self.text.items():
+            self.assertNotIn("pr_labels", text, name)
+
+    def test_rendered_files_lint_clean(self):
+        for name, text in self.text.items():
+            self.assertEqual(app_token_lint.lint_source(name, text, "mega-reth"), [], name)
+
+
+class Render(unittest.TestCase):
+    def args(self, *extra):
+        return parse_args(["--repo", "r", "--default-branch", "main", "--version-file", "VERSION",
+                           "--version-pattern", "plain", *extra])
+
+    def test_refuses_an_existing_output_directory(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            stale = Path(tmp) / "release-candidate.yml"
+            stale.write_text("old render\n")
+            code, out, err = run(MEGA_RETH + ["--out", tmp])
+            self.assertEqual(code, 1)
+            self.assertIn("already exists", err)
+            self.assertEqual(out, "")
+            self.assertEqual(stale.read_text(), "old render\n")
+
+    def test_without_out_each_render_gets_a_new_directory(self):
+        dirs = []
+        for _ in range(2):
+            code, out, err = run(MEGA_RETH)
+            self.assertEqual(code, 0, err)
+            dirs.append(Path(out.splitlines()[0]).parent)
+        try:
+            self.assertNotEqual(dirs[0], dirs[1])
+        finally:
+            for d in dirs:
+                for f in d.iterdir():
+                    f.unlink()
+                d.rmdir()
+
+    def test_without_bump_command_the_example_stays_a_comment(self):
+        text = render("release-candidate.yml", (TEMPLATES / "release-candidate.yml").read_text(), self.args())
+        (propose,) = shared(yaml.safe_load(text), "propose", "release-candidate")
+        self.assertNotIn("bump_command", propose["with"])
+        self.assertNotIn("dependency_token", propose["with"])
+        self.assertIn("#   bump_command: cargo update --workspace", text)
+
+    def test_bump_command_without_dependencies_uses_the_job_token(self):
+        text = render("release-candidate.yml", (TEMPLATES / "release-candidate.yml").read_text(),
+                      self.args("--bump-command", "make bump"))
+        (propose,) = shared(yaml.safe_load(text), "propose", "release-candidate")
+        self.assertEqual(propose["with"]["dependency_token"], "${{ github.token }}")
+        self.assertNotIn("dependency-token", text)
+
+    def test_bump_command_with_a_hash_is_kept_whole(self):
+        # Unquoted, ` # regenerate lock` would be a YAML comment and vanish.
+        for command in ("make bump # regenerate lock", "make bump: all", "'quoted' && echo \"x\"",
+                        "[ -f x ] || make", "@scripts/bump", "true", "123", "*glob"):
+            with self.subTest(command=command):
+                text = render("release-candidate.yml", (TEMPLATES / "release-candidate.yml").read_text(),
+                              self.args("--bump-command", command))
+                (propose,) = shared(yaml.safe_load(text), "propose", "release-candidate")
+                self.assertEqual(propose["with"]["bump_command"], command)
+                self.assertEqual(check("release-candidate.yml", text, {"bump_command": command}), [])
+
+    def test_plain_values_stay_plain(self):
+        text = render("release-candidate.yml", (TEMPLATES / "release-candidate.yml").read_text(),
+                      self.args("--bump-command", "cargo update --workspace"))
+        self.assertIn("          bump_command: cargo update --workspace\n", text)
+
+    def test_other_substituted_values_read_back_exactly(self):
+        args = self.args("--version-file", "crates/a #b/Cargo.toml", "--changelog-file", "docs/CHANGES: all.md",
+                         "--default-branch", "dev,next", "--bump-command", "x",
+                         "--dependency-repositories", "pstd #1")
+        for name in RELEASE_TEMPLATES:
+            text = render(name, (TEMPLATES / name).read_text(), args)
+            doc = yaml.safe_load(text)
+            self.assertEqual(check(name, text, copy_templates.expected_inputs(args)), [], name)
+            if name != "release-settle.yml":
+                self.assertEqual(doc[True]["push"]["branches"], ["dev,next"], name)
+        text = render("release-candidate.yml", (TEMPLATES / "release-candidate.yml").read_text(), args)
+        (token,) = [s for s in steps(yaml.safe_load(text), "propose") if s.get("id") == "dependency-token"]
+        self.assertEqual(token["with"]["repositories"], "pstd #1")
+
+    def test_check_reports_a_value_that_reads_back_differently(self):
+        text = render("release-candidate.yml", (TEMPLATES / "release-candidate.yml").read_text(),
+                      self.args("--bump-command", "make bump"))
+        problems = check("release-candidate.yml", text, {"bump_command": "make bump # regenerate lock"})
+        self.assertEqual(len(problems), 1, problems)
+        self.assertIn("bump_command reads back as 'make bump', not 'make bump # regenerate lock'", problems[0])
+
+    def test_refuses_an_actions_ref_that_cannot_sit_in_uses(self):
+        for ref in ("main # v3", "a b", ""):
+            with self.subTest(ref=ref), contextlib.redirect_stderr(io.StringIO()), self.assertRaises(SystemExit):
+                self.args("--actions-ref", ref)
+
+    def test_actions_ref_pins_every_shared_action(self):
+        sha = "0" * 40
+        for name in RELEASE_TEMPLATES:
+            text = render(name, (TEMPLATES / name).read_text(), self.args("--actions-ref", sha))
+            refs = {m["ref"] for m in copy_templates.SHARED_ACTION.finditer(text)}
+            self.assertEqual(refs, {sha}, name)
+
+    def test_template_drift_is_an_error(self):
+        text = (TEMPLATES / "release-candidate.yml").read_text().replace("version_file: VERSION", "version_file: X")
+        with self.assertRaisesRegex(RenderError, "version file"):
+            render("release-candidate.yml", text, self.args())
+
+    def test_check_reports_an_unfilled_placeholder(self):
+        text = (TEMPLATES / "app-token-lint.yml").read_text()
+        self.assertEqual(check("app-token-lint.yml", text), ["app-token-lint.yml: unfilled placeholder '$default-branch'"])
+
+    def test_check_reports_an_unknown_and_a_missing_input(self):
+        text = render("release-settle.yml", (TEMPLATES / "release-settle.yml").read_text(), self.args())
+        text = text.replace("          release_branch: ${{ matrix.target.release_branch }}",
+                            "          release_brnach: ${{ matrix.target.release_branch }}")
+        text = text.replace("          pr_number: ${{ needs.route.outputs.pr_number }}\n", "")
+        problems = check("release-settle.yml", text)
+        self.assertIn("release-settle.yml: refresh/2 (release-settle): 'release_brnach' is not an input", problems)
+        self.assertIn("release-settle.yml: publish/2 (release-publish): required input 'pr_number' missing", problems)
+
+    def test_templates_call_only_known_inputs(self):
+        for name in RELEASE_TEMPLATES:
+            problems = check(name, (TEMPLATES / name).read_text())
+            self.assertEqual([p for p in problems if "placeholder" not in p], [], name)
+
+    def test_refuses_dependencies_naming_the_repository(self):
+        with contextlib.redirect_stderr(io.StringIO()), self.assertRaises(SystemExit):
+            self.args("--bump-command", "x", "--dependency-repositories", "pstd,r")
+
+    def test_refuses_dependencies_without_a_bump_command(self):
+        with contextlib.redirect_stderr(io.StringIO()), self.assertRaises(SystemExit):
+            self.args("--dependency-repositories", "pstd")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/.github/scripts/test_no_force_push.py b/.github/scripts/test_no_force_push.py
new file mode 100644
index 0000000..d42418f
--- /dev/null
+++ b/.github/scripts/test_no_force_push.py
@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Nothing this repository ships may force-push a branch.
+
+The release pipeline is built so that no branch is ever rewritten: settle and
+candidate re-runs supersede (close the PR, delete the branch, push a new ref)
+instead. Consumers run it under rulesets that ban force pushes on every
+branch, so one forced push anywhere breaks a release. This scans every file
+under the shipped actions and workflow templates and fails on any push that
+could rewrite a ref. `git fetch --force` of a tag refspec only updates the
+runner's local copy and is allowed, explicitly, below.
+"""
+from __future__ import annotations
+
+import re
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+SHIPPED = [ROOT / ".github" / "actions", ROOT / "workflow-templates"]
+
+# `git [global options] push ...`, up to the end of that command.
+GIT_PUSH = re.compile(r"\bgit\b(?:\s+(?:-C\s+\S+|-c\s+\S+|--[\w-]+(?:=\S+)?))*\s+push\b(?P<args>[^;&|)\n]*)")
+GIT_FETCH = re.compile(r"\bgit\b(?:\s+(?:-C\s+\S+|-c\s+\S+|--[\w-]+(?:=\S+)?))*\s+fetch\b(?P<args>[^;&|)\n]*)")
+FORCING_ARG = re.compile(
+    r"""(?:^|\s)["']?(?:
+        --force(?:-with-lease|-if-includes)?(?:=\S*)?   # --force, --force-with-lease[=...]
+      | --mirror                                        # mirror pushes force every ref
+      | -[a-zA-Z]*f[a-zA-Z]*                            # -f, -fq, -uf ...
+      | \+\S+                                           # +refspec
+    )(?=\s|["']|$)""",
+    re.X,
+)
+# Other ways to rewrite a ref: the action that force-pushes its branch when
+# it updates a PR, and a forced ref update through the API.
+OTHER = [
+    (re.compile(r"peter-evans/create-pull-request"), "create-pull-request force-pushes the PR branch it updates"),
+    (re.compile(r"(?:-[fF]|--(?:raw-)?field)\s+force=true"), "a ref update through the API with force=true"),
+]
+
+
+def logical_lines(text: str):
+    """(line number, line) with backslash continuations joined."""
+    start, buf = None, []
+    for n, line in enumerate(text.splitlines(), 1):
+        if start is None:
+            start = n
+        if line.rstrip().endswith("\\"):
+            buf.append(line.rstrip()[:-1])
+            continue
+        buf.append(line)
+        yield start, " ".join(buf)
+        start, buf = None, []
+    if buf:
+        yield start, " ".join(buf)
+
+
+def violations(text: str):
+    """(line, reason, source) for every ref rewrite in `text`."""
+    found = []
+    for n, line in logical_lines(text):
+        for m in GIT_PUSH.finditer(line):
+            arg = FORCING_ARG.search(m["args"])
+            if arg:
+                found.append((n, f"git push with {arg.group().strip()!r}", line.strip()))
+        for pattern, reason in OTHER:
+            if pattern.search(line):
+                found.append((n, reason, line.strip()))
+    return found
+
+
+def forced_fetches(text: str):
+    """`git fetch --force` lines. (A `+` refspec into refs/remotes/ is the
+    ordinary way to refresh a remote-tracking ref and is not listed.)"""
+    return [line.strip() for _, line in logical_lines(text)
+            if any(re.search(r"(?:^|\s)(?:--force|-[a-zA-Z]*f[a-zA-Z]*)(?=\s|$)", m["args"])
+                   for m in GIT_FETCH.finditer(line))]
+
+
+def shipped_files():
+    for top in SHIPPED:
+        for path in sorted(top.rglob("*")):
+            if path.is_file() and path.name != Path(__file__).name:
+                try:
+                    yield path, path.read_text()
+                except UnicodeDecodeError:
+                    continue
+
+
+class NothingShippedForcePushes(unittest.TestCase):
+    def test_no_shipped_file_rewrites_a_ref(self):
+        found = [f"{path.relative_to(ROOT)}:{n}: {reason}: {src}"
+                 for path, text in shipped_files() for n, reason, src in violations(text)]
+        self.assertEqual(found, [], "a shipped file can rewrite a branch:\n" + "\n".join(found))
+
+    def test_the_scan_sees_the_shipped_pushes(self):
+        # A scan that matches nothing proves nothing: the candidate and settle
+        # pushes must be in view.
+        pushing = {path.parent.name for path, text in shipped_files()
+                   if any(GIT_PUSH.search(line) for _, line in logical_lines(text))}
+        self.assertLessEqual({"release-candidate", "release-settle"}, pushing)
+
+    def test_forced_tag_fetches_are_allowed_explicitly(self):
+        # release-publish re-reads the tag it is about to verify with
+        # `git fetch --force` on a refs/tags refspec: that only replaces the
+        # runner's local tag. Every forced fetch shipped must be exactly that.
+        fetches = [line for _, text in shipped_files() for line in forced_fetches(text)]
+        self.assertTrue(fetches, "expected release-publish's forced tag fetches to be in view")
+        for line in fetches:
+            self.assertRegex(line, r'"refs/tags/[^"]+:refs/tags/[^"]+"', line)
+            self.assertEqual(violations(line), [], line)
+
+
+class TheScanner(unittest.TestCase):
+    def assertFlags(self, text):
+        self.assertTrue(violations(text), f"not flagged: {text}")
+
+    def assertClean(self, text):
+        self.assertEqual(violations(text), [], text)
+
+    def test_forced_pushes_are_flagged(self):
+        for text in [
+            'git push --force origin "$head"',
+            'git push --quiet --force-with-lease origin "$head"',
+            'git push --force-with-lease=refs/heads/x: origin HEAD:refs/heads/x',
+            'git push --force-if-includes origin x',
+            'git push -f origin x',
+            'git push -qf origin x',
+            'git -C "$D" push --quiet origin "+HEAD:refs/heads/x"',
+            "git push origin +refs/heads/a:refs/heads/a",
+            "git push --mirror origin",
+            'git -c http.extraHeader=x push --quiet \\\n  --force origin "$head"',
+            "if git push --force origin x; then :; fi",
+            "  uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8",
+            'gh api -X PATCH "repos/$R/git/refs/heads/x" -f sha="$s" -F force=true',
+        ]:
+            with self.subTest(text=text):
+                self.assertFlags(text)
+
+    def test_plain_pushes_deletes_and_fetches_are_clean(self):
+        for text in [
+            'git push --quiet origin "$candidate:refs/heads/$head"',
+            'git push --quiet origin "$head"',
+            'git push --quiet origin ":$ref"',
+            "git push --quiet -u origin main",
+            'git fetch --quiet --force origin "refs/tags/$tag:refs/tags/$tag"',
+            'git fetch --quiet origin "+refs/heads/$b:refs/remotes/origin/$b"',
+            'echo "never force-pushed"; git push origin x',
+            'gh api -X DELETE "repos/$R/git/refs/heads/$head"',
+        ]:
+            with self.subTest(text=text):
+                self.assertClean(text)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/.github/workflows/actions-test.yml b/.github/workflows/actions-test.yml
index b05a7aa..6714040 100644
--- a/.github/workflows/actions-test.yml
+++ b/.github/workflows/actions-test.yml
@@ -49,6 +49,19 @@ jobs:
             -p 'test_*.py' \
             -v
 
+      - name: Test app-token-lint and the template copy helper
+        env:
+          PYTHONDONTWRITEBYTECODE: "1"
+        run: |
+          python3 -m pip install --quiet pyyaml
+          python3 -m unittest discover \
+            -s .github/scripts \
+            -p 'test_*.py' \
+            -v
+
+      - name: Lint workflow templates for App token usage
+        run: python3 .github/scripts/app_token_lint.py --repo my-repo workflow-templates/
+
   # release-verify-version is bash inside a composite action; drive it with
   # fake binaries and check each outcome the README promises.
   verify-version:
@@ -452,6 +465,461 @@ jobs:
           [[ "$SKIP" == "false" && -z "$PR" ]] || { echo "skip-check=$SKIP pr_number=$PR"; exit 1; }
           echo "false outside a queue, as documented"
 
+  # Drive the shipped settle scripts against a real local remote. Only GitHub's
+  # PR API is faked; branch ancestry, conflicts, notes and recovery are real.
+  release-settle:
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    timeout-minutes: 5
+    env:
+      TOOLS: ${{ github.workspace }}/.github/actions/release-tools/release_tools.py
+      ACTION: ${{ github.workspace }}/.github/actions/release-settle/action.yml
+      AUTH_WRAPPER: ${{ github.workspace }}/.github/actions/git-auth/with-github-auth.sh
+      GITHUB_AUTH_TOKEN: fixture-token
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Where the settle rehearsal lives
+        run: |
+          set -euo pipefail
+          {
+            echo "FIXTURE=$RUNNER_TEMP/release-settle"
+            echo "REPO=$RUNNER_TEMP/release-settle/repo"
+            echo "SH=$RUNNER_TEMP/release-settle/sh"
+            echo "OUT=$RUNNER_TEMP/release-settle/output"
+            echo "PR_STATE=$RUNNER_TEMP/release-settle/prs.json"
+          } >> "$GITHUB_ENV"
+
+      - name: Extract the settle shell and its helpers
+        run: |
+          set -euo pipefail
+          mkdir -p "$SH" "$FIXTURE/bin"
+          python3 - "$ACTION" "$SH" <<'PY'
+          import pathlib, sys, yaml
+
+          action = yaml.safe_load(open(sys.argv[1]))
+          assert action["inputs"]["pr_author"]["default"] == "mega-gutenberg[bot]"
+          assert action["inputs"]["git_user_name"]["default"] == "mega-gutenberg[bot]"
+          assert action["inputs"]["git_user_email"]["default"] == "348780249+mega-gutenberg[bot]@users.noreply.github.com"
+          assert not {"settle_mode", "settlers", "github_token"} & action["inputs"].keys()
+          assert set(action["outputs"]) == {"version", "pr_url", "notes_file"}
+          want = {"Guard": "guard.sh", "Generate release notes": "notes.sh", "Ensure the settle PR": "ensure.sh"}
+          found = {s["name"]: s["run"] for s in action["runs"]["steps"] if s.get("name") in want}
+          assert found.keys() == want.keys(), f"missing shipped steps: {want.keys() - found.keys()}"
+          for name, script in found.items():
+              pathlib.Path(sys.argv[2], want[name]).write_text(script)
+              print(f"extracted {name!r}")
+          PY
+          cat > "$SH/helpers.sh" <<'SH'
+          export VERSION=1.1.0 BRANCH=release-v1.1.0 HEAD_BRANCH=chore/release-settle-v1.1.0
+          export GH_TOKEN=fixture-token PR_AUTHOR='mega-gutenberg[bot]' PR_LABELS='release, needs-ci'
+          export GITHUB_REPOSITORY=megaeth-labs/fake GITHUB_OUTPUT="$OUT"
+          export INPUT_VERSION=v1.1.0 BRANCH_IN='' PREFIX=release-v FILE=VERSION PATTERN=plain CHANGELOG=CHANGELOG.md
+          export GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_NOSYSTEM=1
+
+          make_repo() {
+            git init --quiet --bare --initial-branch=main "$REPO.git"
+            git -C "$REPO.git" config receive.denyNonFastForwards true
+            git clone --quiet "$REPO.git" "$REPO"
+            git -C "$REPO" config user.name 'mega-gutenberg[bot]'
+            git -C "$REPO" config user.email '348780249+mega-gutenberg[bot]@users.noreply.github.com'
+            (
+              cd "$REPO"
+              printf '1.0.0\n' > VERSION
+              printf '# Changelog\n\n## v1.0.0 (2025-01-01)\n\n- shipped\n' > CHANGELOG.md
+              git add VERSION CHANGELOG.md
+              git commit --quiet -m 'feat: initial release'
+              git tag v1.0.0
+              git push --quiet origin main refs/tags/v1.0.0
+              git checkout --quiet -b "$BRANCH"
+              printf '1.1.0\n' > VERSION
+              printf '# Changelog\n\n## v1.1.0\n\n- candidate draft\n\n## v1.0.0 (2025-01-01)\n\n- shipped\n' > CHANGELOG.md
+              git add VERSION CHANGELOG.md
+              git commit --quiet -m 'chore(release): candidate v1.1.0'
+              git push --quiet origin "$BRANCH"
+            )
+            printf '{"pulls": [], "events": []}\n' > "$PR_STATE"
+          }
+
+          remote_head() {
+            git -C "$REPO" ls-remote --heads origin "refs/heads/$1" | cut -f1
+          }
+
+          settle() {
+            (
+              cd "$REPO"
+              export COMMIT="$1" RUNNER_TEMP="$FIXTURE"
+              : > "$OUT"
+              bash "$SH/guard.sh" || exit
+              grep -qxF "version=$VERSION" "$OUT"
+              grep -qxF "branch=$BRANCH" "$OUT"
+              export PREVIOUS=v1.0.0
+              bash "$SH/notes.sh" || exit
+              export NOTES="$FIXTURE/release-notes-v$VERSION.md"
+              bash "$SH/ensure.sh"
+            )
+          }
+
+          assert_pr() { # number, marker SHA
+            python3 - "$PR_STATE" "$1" "$2" <<'PY'
+          import json, sys
+          state = json.load(open(sys.argv[1]))
+          pr = state["pulls"][int(sys.argv[2]) - 1]
+          assert pr["state"] == "open", pr
+          assert pr["author"]["login"] == "mega-gutenberg[bot]", pr
+          assert pr["headRefName"] == "chore/release-settle-v1.1.0", pr
+          assert pr["baseRefName"] == "release-v1.1.0", pr
+          assert pr["body"].count(f"<!-- release-settle: v1.1.0 {sys.argv[3]} -->") == 1, pr
+          assert pr["labels"] == ["release", "needs-ci"], pr
+          PY
+            [[ "${3:-}" == no-output ]] || grep -qxF "pr_url=https://example.invalid/pull/$1" "$OUT"
+          }
+
+          advance() {
+            git -C "$REPO" checkout --quiet -B "$BRANCH" "origin/$BRANCH"
+            printf '%s\n' "$1" >> "$REPO/fixes"
+            git -C "$REPO" add fixes
+            git -C "$REPO" commit --quiet -m "fix: $1"
+            git -C "$REPO" push --quiet origin "$BRANCH"
+          }
+
+          merge_settle() { # number, route fixture
+            git -C "$REPO" checkout --quiet -B "$BRANCH" "origin/$BRANCH"
+            git -C "$REPO" merge --quiet --no-ff --no-edit "origin/$HEAD_BRANCH"
+            git -C "$REPO" push --quiet origin "$BRANCH"
+            python3 - "$PR_STATE" "$1" "$2" "$REPO" <<'PY'
+          import json, pathlib, subprocess, sys
+          path = pathlib.Path(sys.argv[1])
+          state = json.loads(path.read_text())
+          pr = state["pulls"][int(sys.argv[2]) - 1]
+          sha = subprocess.check_output(["git", "-C", sys.argv[4], "rev-parse", "HEAD"], text=True).strip()
+          parent = subprocess.check_output(["git", "-C", sys.argv[4], "rev-parse", "HEAD^1"], text=True).strip()
+          pr["state"] = "merged"
+          path.write_text(json.dumps(state))
+          pull = {"number": pr["number"], "merged_at": "2026-01-01T00:00:00Z", "merge_commit_sha": sha,
+                  "head": {"ref": pr["headRefName"]}, "base": {"ref": pr["baseRefName"]},
+                  "user": pr["author"], "body": pr["body"]}
+          fixture = {"kind": "settle", "event": "push", "sha": sha, "first_parent": parent,
+                     "ref_name": pr["baseRefName"], "default_branch": "main", "prefix": "release-v",
+                     "pr_author": "mega-gutenberg[bot]", "pulls": [pull], "tag_exists": False,
+                     "release_exists": False, "version_at_sha": "1.1.0", "latest_tag": "v1.0.0",
+                     "branches": [], "dispatch_version": ""}
+          pathlib.Path(sys.argv[3]).write_text(json.dumps(fixture))
+          PY
+          }
+          SH
+
+      - name: Fake GitHub PR state and a fixed notes date
+        run: |
+          set -euo pipefail
+          cat > "$FIXTURE/bin/gh" <<'PY'
+          #!/usr/bin/env python3
+          import json, os, pathlib, subprocess, sys
+
+          path = pathlib.Path(os.environ["PR_STATE"])
+          state = json.loads(path.read_text())
+          args = sys.argv[1:]
+          def option(flag):
+              return args[args.index(flag) + 1]
+          def save(event):
+              state["events"].append(event)
+              path.write_text(json.dumps(state))
+
+          if args[:2] == ["pr", "list"]:
+              assert option("--state") == "open"
+              fields = option("--json").split(",")
+              pulls = [pr for pr in state["pulls"] if pr["state"] == "open"
+                       and pr["headRefName"] == option("--head") and pr["baseRefName"] == option("--base")]
+              print(json.dumps([{key: pr[key] for key in fields} for pr in pulls]))
+          elif args[:2] == ["pr", "create"]:
+              assert not any(pr["state"] == "open" and pr["headRefName"] == option("--head")
+                             and pr["baseRefName"] == option("--base") for pr in state["pulls"])
+              number = len(state["pulls"]) + 1
+              pr = {"number": number, "url": f"https://example.invalid/pull/{number}", "state": "open",
+                    "author": {"login": os.environ["PR_AUTHOR"]}, "headRefName": option("--head"),
+                    "baseRefName": option("--base"), "title": option("--title"),
+                    "body": pathlib.Path(option("--body-file")).read_text(),
+                    "labels": [args[i + 1] for i, arg in enumerate(args) if arg == "--label"]}
+              state["pulls"].append(pr)
+              save("create")
+              print(pr["url"])
+          elif args[:2] == ["pr", "edit"]:
+              if os.environ.get("FAIL_PR_EDIT") == "1":
+                  save("edit-failed")
+                  sys.exit("simulated gh pr edit failure")
+              pr = state["pulls"][int(args[2]) - 1]
+              assert pr["state"] == "open"
+              if "--title" in args:
+                  pr["title"] = option("--title")
+              pr["body"] = pathlib.Path(option("--body-file")).read_text()
+              save("edit")
+              print(pr["url"])
+          elif args[:2] == ["pr", "close"]:
+              pr = state["pulls"][int(args[2]) - 1]
+              assert pr["state"] == "open"
+              pr["state"] = "closed"
+              pr["comment"] = option("--comment")
+              save("close")
+          elif args[:3] == ["api", "-X", "DELETE"]:
+              prefix = "repos/megaeth-labs/fake/git/refs/heads/"
+              assert len(args) == 4 and args[3].startswith(prefix), args
+              subprocess.run(["git", "push", "--quiet", "--delete", "origin", args[3][len(prefix):]], check=True)
+              save("delete")
+          else:
+              sys.exit(f"unexpected gh command: {args}")
+          PY
+          # Notes are unchanged across reruns even if a run crosses UTC midnight.
+          printf '#!/bin/bash\n[[ "$*" == "-u +%%F" ]] || exit 1\nprintf "2026-01-01\\n"\n' > "$FIXTURE/bin/date"
+          chmod +x "$FIXTURE/bin/gh" "$FIXTURE/bin/date"
+          echo "$FIXTURE/bin" >> "$GITHUB_PATH"
+
+      - name: Create then refresh then no-op without rewriting history
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+          make_repo
+          tip="$(remote_head "$BRANCH")"
+          # A leftover local branch must not prevent the action's checkout -B.
+          git -C "$REPO" branch "$HEAD_BRANCH" "$tip"
+          settle "$tip"
+          assert_pr 1 "$tip"
+          old="$(remote_head "$HEAD_BRANCH")"
+          [[ "$(git -C "$REPO" rev-parse "$old^1")" == "$tip" ]]
+          advance 'second fix'
+          tip="$(remote_head "$BRANCH")"
+          settle "$tip"
+          assert_pr 1 "$tip"
+          # The refresh keeps the same PR: no second one is opened.
+          python3 - "$PR_STATE" <<'PY'
+          import json, sys
+          pulls = json.load(open(sys.argv[1]))["pulls"]
+          assert [pr["number"] for pr in pulls] == [1], pulls
+          PY
+          new="$(remote_head "$HEAD_BRANCH")"
+          git -C "$REPO" merge-base --is-ancestor "$old" "$new"
+          git -C "$REPO" merge-base --is-ancestor "$tip" "$new"
+          [[ "$(git -C "$REPO" rev-list --count --merges "$old..$new")" == 1 ]]
+          [[ "$(remote_head "$BRANCH")" == "$tip" ]]
+          git -C "$REPO" show "$new:CHANGELOG.md" | grep -qF 'second fix'
+          cp "$PR_STATE" "$FIXTURE/before-noop.json"
+          settle "$tip"
+          assert_pr 1 "$tip"
+          [[ "$(remote_head "$HEAD_BRANCH")" == "$new" ]]
+          cmp "$PR_STATE" "$FIXTURE/before-noop.json"
+          python3 - "$PR_STATE" <<'PY'
+          import json, sys
+          assert json.load(open(sys.argv[1]))["events"] == ["create", "edit"]
+          PY
+          echo "PASS create -> refresh -> no-op; old settle head $old is an ancestor of $new"
+
+      - name: Replace an open Maxwell-authored settle PR
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+          python3 - "$PR_STATE" <<'PY'
+          import json, pathlib, sys
+          path = pathlib.Path(sys.argv[1])
+          state = json.loads(path.read_text())
+          state["pulls"][0]["author"]["login"] = "mega-maxwell[bot]"
+          path.write_text(json.dumps(state))
+          PY
+          tip="$(remote_head "$BRANCH")"
+          settle "$tip"
+          assert_pr 2 "$tip"
+          new="$(remote_head "$HEAD_BRANCH")"
+          [[ "$(git -C "$REPO" rev-parse "$new^1")" == "$tip" ]]
+          python3 - "$PR_STATE" <<'PY'
+          import json, sys
+          state = json.load(open(sys.argv[1]))
+          assert state["pulls"][0]["state"] == "closed"
+          assert state["pulls"][0]["comment"] == "Superseded: the settle PR is now maintained by mega-gutenberg."
+          assert state["events"][-3:] == ["close", "delete", "create"], state
+          PY
+          echo "PASS Maxwell PR closed and replaced, including orphan branch deletion"
+
+      - name: Resume a refresh after gh pr edit fails
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+          old_tip="$(remote_head "$BRANCH")"
+          old_head="$(remote_head "$HEAD_BRANCH")"
+          advance 'retry fix'
+          tip="$(remote_head "$BRANCH")"
+          if FAIL_PR_EDIT=1 settle "$tip" > "$FIXTURE/edit-failed.log" 2>&1; then
+            echo "expected gh pr edit failure"; exit 1
+          fi
+          assert_pr 2 "$old_tip" no-output
+          pushed="$(remote_head "$HEAD_BRANCH")"
+          [[ "$pushed" != "$old_head" ]]
+          git -C "$REPO" merge-base --is-ancestor "$old_head" "$pushed"
+          git -C "$REPO" merge-base --is-ancestor "$tip" "$pushed"
+          settle "$tip"
+          assert_pr 2 "$tip"
+          [[ "$(remote_head "$HEAD_BRANCH")" == "$pushed" ]]
+          python3 - "$PR_STATE" <<'PY'
+          import json, sys
+          state = json.load(open(sys.argv[1]))
+          assert len(state["pulls"]) == 2
+          assert state["events"][-2:] == ["edit-failed", "edit"]
+          PY
+          echo "PASS rerun repairs the stale marker without adding a commit or PR"
+
+      - name: Merge a refreshed settle PR whose marker update failed
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+          old_tip="$(remote_head "$BRANCH")"
+          advance 'stale merge fix'
+          tip="$(remote_head "$BRANCH")"
+          if FAIL_PR_EDIT=1 settle "$tip" > "$FIXTURE/stale-edit-failed.log" 2>&1; then
+            echo "expected gh pr edit failure"; exit 1
+          fi
+          assert_pr 2 "$old_tip" no-output
+          pushed="$(remote_head "$HEAD_BRANCH")"
+          git -C "$REPO" merge-base --is-ancestor "$tip" "$pushed"
+          git -C "$REPO" show "$pushed:CHANGELOG.md" | grep -qF 'stale merge fix'
+          merge_settle 2 "$FIXTURE/stale-route.json"
+          merged="$(remote_head "$BRANCH")"
+          [[ "$(git -C "$REPO" rev-parse "$merged^1")" == "$tip" ]]
+          python3 - "$FIXTURE/stale-route.json" "$old_tip" <<'PY'
+          import json, sys
+          fixture = json.load(open(sys.argv[1]))
+          assert f"<!-- release-settle: v1.1.0 {sys.argv[2]} -->" in fixture["pulls"][0]["body"]
+          assert fixture["first_parent"] != sys.argv[2]
+          PY
+          echo "PASS stale marker retained after the refreshed notes merge at $merged"
+
+      - name: Route the stale merge to refresh
+        run: |
+          set -euo pipefail
+          python3 "$TOOLS" route < "$FIXTURE/stale-route.json" > "$FIXTURE/stale-decision.json"
+          python3 - "$FIXTURE/stale-decision.json" <<'PY'
+          import json, sys
+          decision = json.load(open(sys.argv[1]))
+          assert decision["action"] == "refresh", decision
+          assert decision["reason"], decision
+          print("PASS stale merge routes to refresh:", decision)
+          PY
+
+      - name: Record the replacement settlement with an empty commit
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+          tip="$(remote_head "$BRANCH")"
+          settle "$tip"
+          assert_pr 3 "$tip"
+          head="$(remote_head "$HEAD_BRANCH")"
+          [[ "$head" != "$tip" ]]
+          [[ "$(git -C "$REPO" rev-parse "$head^1")" == "$tip" ]]
+          git -C "$REPO" diff --exit-code "$tip" "$head"
+          [[ "$(git -C "$REPO" show -s --format=%s "$head")" == "chore(release): settle v1.1.0" ]]
+          git -C "$REPO" show -s --format=%b "$head" | grep -qxF \
+            "Changelog already current at $tip; this PR records the settlement decision."
+          merge_settle 3 "$FIXTURE/fresh-route.json"
+          python3 - "$FIXTURE/fresh-route.json" "$PR_STATE" <<'PY'
+          import json, sys
+          fixture = json.load(open(sys.argv[1]))
+          assert f'<!-- release-settle: v1.1.0 {fixture["first_parent"]} -->' in fixture["pulls"][0]["body"]
+          state = json.load(open(sys.argv[2]))
+          assert len(state["pulls"]) == 3
+          assert state["events"][-2:] == ["delete", "create"]
+          assert not any(pr["state"] == "open" for pr in state["pulls"])
+          PY
+          [[ "$(git -C "$REPO" ls-remote --tags origin | wc -l)" == 1 ]]
+          echo "PASS empty settle commit, replacement marker and fresh merge; no release tag created"
+
+      - name: Route the replacement merge to publish
+        run: |
+          set -euo pipefail
+          python3 "$TOOLS" route < "$FIXTURE/fresh-route.json" > "$FIXTURE/fresh-decision.json"
+          python3 - "$FIXTURE/fresh-decision.json" <<'PY'
+          import json, sys
+          decision = json.load(open(sys.argv[1]))
+          assert decision["action"] == "publish", decision
+          assert decision["reason"], decision
+          print("PASS replacement merge routes to publish:", decision)
+          PY
+
+      # Refresh and publish run in different concurrency groups. A refresh
+      # whose Guard passed just before settle PR #3 was merged must not open a
+      # fourth settle PR (or delete the head branch) for a published version.
+      - name: A refresh that started before the merge opens no settle PR
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+          merged="$(remote_head "$BRANCH")"
+          before="$(git -C "$REPO" rev-parse "$merged^1")"
+          head="$(remote_head "$HEAD_BRANCH")"
+          cp "$PR_STATE" "$FIXTURE/before-late.json"
+          late() { # <commit>: the steps after a Guard that already passed
+            (
+              cd "$REPO"
+              export COMMIT="$1" RUNNER_TEMP="$FIXTURE" PREVIOUS=v1.0.0
+              : > "$OUT"
+              bash "$SH/notes.sh" > /dev/null
+              export NOTES="$FIXTURE/release-notes-v$VERSION.md"
+              bash "$SH/ensure.sh"
+            )
+          }
+          # Merged, not yet tagged: the branch moved past the settled tip.
+          if late "$before" > "$FIXTURE/late.log" 2>&1; then
+            echo "a late refresh of the pre-merge tip succeeded"; cat "$FIXTURE/late.log"; exit 1
+          fi
+          grep -qF "$BRANCH moved to $merged after this refresh of $before started" "$FIXTURE/late.log" \
+            || { cat "$FIXTURE/late.log"; exit 1; }
+          cmp "$PR_STATE" "$FIXTURE/before-late.json"
+          [[ "$(remote_head "$HEAD_BRANCH")" == "$head" ]]
+          # Published: the tag exists, so even the current tip is not settled again.
+          git -C "$REPO" tag -a v1.1.0 "$merged" -m published
+          git -C "$REPO" push --quiet origin refs/tags/v1.1.0
+          late "$merged" > "$FIXTURE/late.log" 2>&1 || { cat "$FIXTURE/late.log"; exit 1; }
+          grep -qF "::notice title=Already tagged::v1.1.0 is already tagged, so this refresh of $merged does not open or update a settle PR for it" \
+            "$FIXTURE/late.log" || { cat "$FIXTURE/late.log"; exit 1; }
+          grep -qxF "pr_url=" "$OUT"
+          cmp "$PR_STATE" "$FIXTURE/before-late.json"
+          [[ "$(remote_head "$HEAD_BRANCH")" == "$head" ]]
+          git -C "$REPO" push --quiet origin :refs/tags/v1.1.0
+          git -C "$REPO" tag -d v1.1.0 > /dev/null
+          echo "PASS a late refresh neither deletes the head branch nor opens a settle PR"
+
+      - name: A conflicting changelog asks the maintainer to close the PR
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+          export REPO="$FIXTURE/conflict" PR_STATE="$FIXTURE/conflict-prs.json"
+          make_repo
+          settle "$(remote_head "$BRANCH")"
+          before="$(remote_head "$HEAD_BRANCH")"
+          cp "$PR_STATE" "$FIXTURE/before-conflict.json"
+          git -C "$REPO" checkout --quiet -B "$BRANCH" "origin/$BRANCH"
+          printf '# Changelog\n\n## v1.1.0\n\n- maintainer changes the draft\n\n## v1.0.0 (2025-01-01)\n\n- shipped\n' > "$REPO/CHANGELOG.md"
+          git -C "$REPO" add CHANGELOG.md
+          git -C "$REPO" commit --quiet -m 'fix: conflicting changelog'
+          git -C "$REPO" push --quiet origin "$BRANCH"
+          if settle "$(remote_head "$BRANCH")" > "$FIXTURE/conflict.log" 2>&1; then
+            echo "expected a conflicting merge to fail"; exit 1
+          fi
+          cat "$FIXTURE/conflict.log"
+          grep -qF 'close the settle PR so the next run recreates it' "$FIXTURE/conflict.log"
+          [[ "$(remote_head "$HEAD_BRANCH")" == "$before" ]]
+          cmp "$PR_STATE" "$FIXTURE/before-conflict.json"
+          [[ -z "$(git -C "$REPO" status --porcelain)" ]]
+          if git -C "$REPO" rev-parse --verify MERGE_HEAD; then
+            echo "failed merge was not aborted"; exit 1
+          fi
+          echo "PASS conflicting CHANGELOG fails, aborts the merge and leaves remote refs and PR untouched"
+
+      - name: Remove settle rehearsal resources
+        if: always()
+        run: |
+          set -euo pipefail
+          rm -rf "$FIXTURE"
+          [[ ! -e "$FIXTURE" ]]
+          echo "removed $FIXTURE (both throwaway remotes, clones, PR state and extracted scripts)"
+
   # release-candidate's propose shell runs at the start of every release in
   # every repository, and a real run needs an app token and a live remote.
   # Drive the shipped script instead — extracted from action.yml, never copied
@@ -494,7 +962,12 @@ jobs:
           want = {
               "Guard (propose)": "guard.sh",
               "Cut the release branch at the base commit (propose)": "cut-branch.sh",
+              "Carry the release workflows (propose)": "carry.sh",
+              "Run bump command": "bump.sh",
               "Draft changelog": "changelog.sh",
+              "Resolve version": "version.sh",
+              "Cut release branch": "cut.sh",
+              "Open candidate PR": "open-pr.sh",
           }
           steps = yaml.safe_load(open(sys.argv[1]))["runs"]["steps"]
           found = {s["name"]: s["run"] for s in steps if s.get("name") in want}
@@ -504,6 +977,9 @@ jobs:
           for name, script in found.items():
               pathlib.Path(sys.argv[2], want[name]).write_text(script)
               print(f"extracted {name!r} -> {want[name]}")
+          # The carry step's shipped default is part of what is under test.
+          default = yaml.safe_load(open(sys.argv[1]))["inputs"]["release_workflows"]["default"]
+          pathlib.Path(sys.argv[2], "release_workflows.default").write_text(default)
           PY
           cat > "$SH/helpers.sh" <<'SH'
           # Run the guard the way the action's step does.
@@ -540,14 +1016,70 @@ jobs:
           mkdir -p "$RUNNER_TEMP/bin"
           cat > "$RUNNER_TEMP/bin/gh" <<'SH'
           #!/usr/bin/env bash
-          # Only what the shell under test calls: the default branch, and
-          # creating a ref, which here is a push into the throwaway remote.
+          # Only what the shell under test calls: the default branch, pull
+          # requests (fake-pr.py, below), the repository's auto-delete setting,
+          # labels, and creating or deleting a ref, which here is a push into
+          # the throwaway remote and fails like GitHub's 422. A case injects a
+          # concurrent run by leaving a file: race-create (a sha the racer
+          # creates the ref at first), race-delete (the racer deletes it
+          # first), race-recreate (the racer keeps it and opens a PR),
+          # race-push (right after the delete the racer pushes its own commit,
+          # and opens a PR if the file says "with-pr"), fail-delete (the
+          # delete just fails).
           set -euo pipefail
           case "${1:-}" in
             repo)
               echo "main"
               ;;
+            pr)
+              shift
+              exec python3 "$RUNNER_TEMP/bin/fake-pr.py" "$@"
+              ;;
             api)
+              # A pull request read: the fixture the case wrote for that number.
+              if [[ "${2:-}" == repos/*/pulls/* ]]; then
+                cat "$RUNNER_TEMP/pr/${2##*/}.json"
+                exit 0
+              fi
+              if [[ "${2:-}" =~ ^repos/[^/]+/[^/]+$ ]]; then
+                cat "$RUNNER_TEMP/auto-delete" 2>/dev/null || echo false
+                exit 0
+              fi
+              if [[ "${2:-}" == -X && "${3:-}" == POST && "${4:-}" == repos/*/issues/*/labels ]]; then
+                n="${4%/labels}"; n="${n##*/}"; shift 4; labels=()
+                while [[ $# -gt 0 ]]; do
+                  [[ "$1" == -f ]] && labels+=("${2#labels[]=}")
+                  shift 2
+                done
+                exec python3 "$RUNNER_TEMP/bin/fake-pr.py" label "$n" "${labels[@]}"
+              fi
+              if [[ "${2:-}" == -X && "${3:-}" == DELETE ]]; then
+                ref="refs/${4#repos/*/git/refs/}"
+                if [[ -e "$RUNNER_TEMP/race-delete" ]]; then
+                  rm "$RUNNER_TEMP/race-delete"; git push --quiet origin ":$ref"
+                fi
+                if [[ -e "$RUNNER_TEMP/race-recreate" ]]; then
+                  rm "$RUNNER_TEMP/race-recreate"
+                  python3 "$RUNNER_TEMP/bin/fake-pr.py" racer "${ref#refs/heads/}" >/dev/null
+                  echo "gh: Reference update failed (HTTP 422)" >&2; exit 1
+                fi
+                if [[ -e "$RUNNER_TEMP/fail-delete" ]]; then
+                  echo "gh: Server Error (HTTP 500)" >&2; exit 1
+                fi
+                if ! git ls-remote --exit-code origin "$ref" >/dev/null; then
+                  echo "gh: Reference does not exist (HTTP 422)" >&2; exit 1
+                fi
+                git push --quiet origin ":$ref"
+                if [[ -e "$RUNNER_TEMP/race-push" ]]; then
+                  racer="$(git commit-tree "HEAD^{tree}" -p HEAD~1 -m "chore(release): a concurrent candidate")"
+                  git push --quiet origin "$racer:$ref"
+                  if [[ "$(cat "$RUNNER_TEMP/race-push")" == with-pr ]]; then
+                    python3 "$RUNNER_TEMP/bin/fake-pr.py" racer "${ref#refs/heads/}" >/dev/null
+                  fi
+                  rm "$RUNNER_TEMP/race-push"
+                fi
+                exit 0
+              fi
               ref=""; sha=""
               while [[ $# -gt 0 ]]; do
                 if [[ "$1" == "-f" ]]; then
@@ -561,12 +1093,84 @@ jobs:
                 fi
               done
               if [[ -n "$ref" && -n "$sha" ]]; then
+                if [[ -e "$RUNNER_TEMP/race-create" ]]; then
+                  git push --quiet origin "$(cat "$RUNNER_TEMP/race-create"):$ref"
+                  rm "$RUNNER_TEMP/race-create"
+                fi
+                if git ls-remote --exit-code origin "$ref" >/dev/null; then
+                  echo "gh: Reference already exists (HTTP 422)" >&2; exit 1
+                fi
                 git push --quiet origin "$sha:$ref"
               fi
               ;;
           esac
           SH
           chmod +x "$RUNNER_TEMP/bin/gh"
+          # Pull requests live in $RUNNER_TEMP/prs/<n>.json. race-close: a
+          # concurrent run closes the PR first, and this close fails. race-pr:
+          # a concurrent run opens the PR first, and this create fails.
+          cat > "$RUNNER_TEMP/bin/fake-pr.py" <<'PY'
+          import json, os, pathlib, subprocess, sys
+
+          temp = pathlib.Path(os.environ["RUNNER_TEMP"])
+          store = temp / "prs"
+          store.mkdir(exist_ok=True)
+
+          def load():
+              return {int(f.stem): json.loads(f.read_text()) for f in store.glob("*.json")}
+
+          def save(pr):
+              (store / f"{pr['number']}.json").write_text(json.dumps(pr))
+
+          def new(head, base, title, body, by):
+              n = max(load(), default=99) + 1
+              pr = {"number": n, "url": f"https://github.com/megaeth-labs/fake/pull/{n}", "head": head,
+                    "base": base, "title": title, "body": body, "author": by, "state": "OPEN",
+                    "labels": [], "comments": []}
+              save(pr)
+              return pr
+
+          def opt(args, name):
+              return args[args.index(name) + 1] if name in args else None
+
+          def race(name):
+              f = temp / name
+              if f.exists():
+                  f.unlink()
+                  return True
+              return False
+
+          cmd, args = sys.argv[1], sys.argv[2:]
+          if cmd == "list":
+              head, state = opt(args, "--head"), (opt(args, "--state") or "open").upper()
+              print(json.dumps([{"number": p["number"], "url": p["url"], "isCrossRepository": False}
+                                for p in load().values() if p["head"] == head and p["state"] == state]))
+          elif cmd == "close":
+              pr = load()[int(args[0])]
+              if race("race-close"):
+                  pr["state"] = "CLOSED"; save(pr)
+              if pr["state"] != "OPEN":
+                  sys.exit(f"Pull request #{pr['number']} is already closed")
+              pr["state"] = "CLOSED"; pr["comments"].append(opt(args, "--comment")); save(pr)
+          elif cmd == "create":
+              head, base = opt(args, "--head"), opt(args, "--base")
+              if race("race-pr"):
+                  new(head, base, "a concurrent candidate", "", "mega-gutenberg[bot]")
+              if any(p["head"] == head and p["state"] == "OPEN" for p in load().values()):
+                  sys.exit(f"a pull request for branch \"{head}\" into branch \"{base}\" already exists")
+              if subprocess.run(["git", "ls-remote", "--exit-code", "origin", f"refs/heads/{head}"],
+                                capture_output=True).returncode != 0:
+                  sys.exit("pull request create failed: Head sha can't be blank, Head ref must be a branch")
+              print(new(head, base, opt(args, "--title"), pathlib.Path(opt(args, "--body-file")).read_text(),
+                        "mega-gutenberg[bot]")["url"])
+          elif cmd == "label":
+              pr = load()[int(args[0])]
+              pr["labels"] += args[1:]; save(pr)
+          elif cmd == "racer":
+              print(new(args[0], "main", "a concurrent candidate", "", "mega-gutenberg[bot]")["url"])
+          else:
+              sys.exit(f"fake gh pr: {cmd} is not faked")
+          PY
           echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
 
       - name: A repository shaped like a settled release line
@@ -727,6 +1331,1309 @@ jobs:
             || { echo "HEAD was reset to the base commit, dropping hotfix commits"; exit 1; }
           echo "propose sits on $tip, not $base"
 
+      # Workflows run from the pushed ref's tree, so a release branch cut at an
+      # older base commit must be given the default branch's release workflows
+      # in the candidate commit. The fixture's base tree is pre-migration: an old
+      # release-settle.yml, a release-publish.yml and an on-release.yml whose
+      # dist-docs job writes with a Maxwell token and commits as Maxwell. (The
+      # fixtures use literal secret names, not expressions: this script is
+      # itself a workflow, and `${{ }}` in it would be expanded.)
+      - name: The release workflows are carried onto a base_commit candidate
+        run: |
+          set -euo pipefail
+          CREPO="$RUNNER_TEMP/carry"
+          LINT="$GITHUB_WORKSPACE/.github/scripts/app_token_lint.py"
+          wf=.github/workflows
+          TOKEN_ACTION=actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1
+          git init --quiet --bare "$CREPO.git"
+          git clone --quiet "$CREPO.git" "$CREPO" 2>/dev/null
+          cd "$CREPO"
+          mkdir -p "$wf"
+          echo 1.0.0 > VERSION
+          cat > "$wf/release-settle.yml" <<YML
+          name: release-settle
+          on:
+            workflow_dispatch:
+          jobs:
+            settle:
+              runs-on: ubuntu-24.04
+              steps:
+                - uses: $TOKEN_ACTION # v3
+                  id: token
+                  with:
+                    client-id: MEGA_MAXWELL_CLIENT_ID
+                    private-key: MEGA_MAXWELL_PK
+                    permission-contents: write
+                - uses: megaeth-labs/.github/.github/actions/release-settle@main
+                  with:
+                    token: from-the-step
+          YML
+          cat > "$wf/on-release.yml" <<YML
+          name: on-release
+          on:
+            release:
+              types: [published]
+          jobs:
+            dist-docs:
+              runs-on: ubuntu-24.04
+              steps:
+                - uses: $TOKEN_ACTION # v3
+                  id: token
+                  with:
+                    client-id: MEGA_MAXWELL_CLIENT_ID
+                    private-key: MEGA_MAXWELL_PK
+                    repositories: dist-docs
+                    permission-contents: write
+                - run: |
+                    git config user.name "mega-maxwell[bot]"
+                    git config user.email "290560214+mega-maxwell[bot]@users.noreply.github.com"
+          YML
+          printf 'name: release-publish\non: workflow_dispatch\njobs:\n  publish:\n    runs-on: ubuntu-24.04\n    steps:\n      - run: echo old publish\n' > "$wf/release-publish.yml"
+          printf 'name: daily-audit\non: workflow_dispatch\njobs:\n  audit:\n    runs-on: ubuntu-24.04\n    steps:\n      - run: echo audit\n' > "$wf/daily-audit.yml"
+          git add -A && git commit --quiet -m "feat: pre-migration release workflows"
+          git rev-parse HEAD > "$RUNNER_TEMP/carry-base"
+          # The default branch has moved on: migrated workflows, no release-publish.
+          cat > "$wf/release-settle.yml" <<YML
+          name: release-settle
+          on:
+            workflow_dispatch:
+          jobs:
+            settle:
+              runs-on: ubuntu-24.04
+              environment: release
+              steps:
+                - uses: $TOKEN_ACTION # v3
+                  id: release-token
+                  with:
+                    client-id: RELEASE_APP_CLIENT_ID
+                    private-key: RELEASE_APP_PRIVATE_KEY
+                    permission-contents: write
+                - uses: megaeth-labs/.github/.github/actions/release-settle@main
+                  with:
+                    token: from-the-step
+          YML
+          cat > "$wf/on-release.yml" <<YML
+          name: on-release
+          on:
+            release:
+              types: [published]
+          jobs:
+            dist-docs:
+              runs-on: ubuntu-24.04
+              environment: release
+              steps:
+                - uses: $TOKEN_ACTION # v3
+                  id: release-token
+                  with:
+                    client-id: RELEASE_APP_CLIENT_ID
+                    private-key: RELEASE_APP_PRIVATE_KEY
+                    repositories: dist-docs
+                    permission-contents: write
+                - run: |
+                    git config user.name "mega-gutenberg[bot]"
+                    git config user.email "348780249+mega-gutenberg[bot]@users.noreply.github.com"
+          YML
+          git rm --quiet "$wf/release-publish.yml"
+          git add -A && git commit --quiet -m "feat: migrate the release workflows"
+          git push --quiet -u origin main
+          base="$(cat "$RUNNER_TEMP/carry-base")"
+
+          # Stale state: the base tree really is pre-migration, and the lint says so.
+          mkdir -p "$RUNNER_TEMP/carry-base-tree" "$RUNNER_TEMP/carry-candidate-tree"
+          git archive "$base" "$wf" | tar -x -C "$RUNNER_TEMP/carry-base-tree"
+          [[ -f "$RUNNER_TEMP/carry-base-tree/$wf/release-publish.yml" ]] \
+            || { echo "the base tree has no release-publish.yml"; exit 1; }
+          rc=0
+          python3 "$LINT" --repo fake "$RUNNER_TEMP/carry-base-tree/$wf/release-settle.yml" \
+            "$RUNNER_TEMP/carry-base-tree/$wf/on-release.yml" > "$RUNNER_TEMP/lint-base.log" 2>&1 || rc=$?
+          [[ "$rc" -eq 1 ]] || { echo "the lint exits $rc on the base tree, not 1"; cat "$RUNNER_TEMP/lint-base.log"; exit 1; }
+
+          # Propose: cut the branch at the base, carry the workflows. The
+          # checkout is dirty (an untracked file) the way a real job's is.
+          : > "$OUT"
+          env GH_TOKEN=fake GITHUB_REPOSITORY=megaeth-labs/fake GITHUB_OUTPUT="$OUT" \
+            BRANCH=release-v1.1.0 BASE="$base" bash "$SH/cut-branch.sh"
+          echo scratch > scratch.txt
+          env GH_TOKEN=fake GITHUB_REPOSITORY=megaeth-labs/fake \
+            RELEASE_WORKFLOWS="$(cat "$SH/release_workflows.default")" bash "$SH/carry.sh" \
+            | tee "$RUNNER_TEMP/carry.log"
+          git add "$wf" && git commit --quiet -m "chore(release): candidate v1.1.0"
+          candidate="$(git rev-parse HEAD)"
+
+          # The candidate commit's tree, not the log, is the evidence.
+          for f in release-settle.yml on-release.yml; do
+            git show "$candidate:$wf/$f" > "$RUNNER_TEMP/got"
+            git show "origin/main:$wf/$f" > "$RUNNER_TEMP/want"
+            cmp "$RUNNER_TEMP/got" "$RUNNER_TEMP/want" \
+              || { echo "$f is not the default branch's, byte for byte"; exit 1; }
+          done
+          if git cat-file -e "$candidate:$wf/release-publish.yml" 2>/dev/null; then
+            echo "release-publish.yml is still in the candidate tree"; exit 1
+          fi
+          [[ "$(git diff --name-only "$base" "$candidate" | sort | tr '\n' ' ')" \
+              == "$wf/on-release.yml $wf/release-publish.yml $wf/release-settle.yml " ]] \
+            || { echo "the candidate changed more than the release workflows:"; git diff --name-only "$base" "$candidate"; exit 1; }
+          [[ "$(git status --porcelain)" == "?? scratch.txt" ]] \
+            || { echo "the carry touched the rest of the checkout:"; git status --porcelain; exit 1; }
+          git archive "$candidate" "$wf" | tar -x -C "$RUNNER_TEMP/carry-candidate-tree"
+          python3 "$LINT" --repo fake "$RUNNER_TEMP/carry-candidate-tree/$wf/release-settle.yml" \
+            "$RUNNER_TEMP/carry-candidate-tree/$wf/on-release.yml"
+          [[ "$(git ls-remote --heads origin refs/heads/release-v1.1.0 | cut -f1)" == "$base" ]] \
+            || { echo "the release branch is not at the base commit"; exit 1; }
+
+          # Re-running the carry on the candidate changes nothing; an absent
+          # path is skipped, not an error.
+          env GH_TOKEN=fake GITHUB_REPOSITORY=megaeth-labs/fake \
+            RELEASE_WORKFLOWS="$(cat "$SH/release_workflows.default")"$'\n'"$wf/not-there.yml" \
+            bash "$SH/carry.sh" | tee "$RUNNER_TEMP/carry2.log"
+          grep -qF "skipped $wf/not-there.yml" "$RUNNER_TEMP/carry2.log" \
+            || { echo "an absent path was not reported as skipped"; exit 1; }
+          [[ "$(git status --porcelain)" == "?? scratch.txt" ]] \
+            || { echo "a second carry changed the tree"; git status --porcelain; exit 1; }
+          echo "candidate $candidate carries the default branch's release workflows"
+
+      - name: The bump command never runs with the release token
+        run: |
+          set -euo pipefail
+          cd "$RUNNER_TEMP/carry"
+          marker="$RUNNER_TEMP/bump-ran"
+          rm -f "$marker"
+          bump() { # <dependency token>
+            env GITHUB_AUTH_TOKEN="$1" DEPENDENCY_TOKEN="$1" GH_TOKEN=fake \
+              OLD_VERSION=0.9.0 NEW_VERSION=1.0.0 BUMP_COMMAND="touch '$marker'" \
+              FILE=VERSION PATTERN=plain TOOLS="$TOOLS" bash "$SH/bump.sh"
+          }
+          if bump "" > "$RUNNER_TEMP/bump.log" 2>&1; then
+            echo "the bump command ran without a dependency token"; cat "$RUNNER_TEMP/bump.log"; exit 1
+          fi
+          grep -qF "bump_command needs a separate dependency_token" "$RUNNER_TEMP/bump.log" \
+            || { echo "refused, but not for the missing dependency token:"; cat "$RUNNER_TEMP/bump.log"; exit 1; }
+          [[ ! -e "$marker" ]] || { echo "the bump command ran before the refusal"; exit 1; }
+          bump dependency-token
+          [[ -e "$marker" ]] || { echo "the bump command did not run with a dependency token"; exit 1; }
+          echo "refused without a dependency token, runs with one"
+
+      # `cut` runs on the push that merged the candidate. It re-reads the PR
+      # through the API (fixtures here) and trusts nothing from the event.
+      - name: Cut refuses what is not a merged candidate and creates the branch for one
+        run: |
+          set -euo pipefail
+          UP="$RUNNER_TEMP/cut"
+          git init --quiet --bare "$UP.git"
+          git clone --quiet "$UP.git" "$UP" 2>/dev/null
+          cd "$UP"
+          echo 1.0.0 > VERSION
+          git add -A && git commit --quiet -m "feat: first"
+          echo 1.3.0 > VERSION
+          git add -A && git commit --quiet -m "chore(release): candidate v1.3.0 (#7)"
+          git push --quiet -u origin main
+          merge="$(git rev-parse HEAD)"
+          earlier="$(git rev-parse HEAD~1)"
+          mkdir -p "$RUNNER_TEMP/pr"
+          pr() { # <number> <merged_at|null> <merge sha> <head ref> <base ref> <author>
+            python3 - "$@" "$RUNNER_TEMP/pr" <<'PY'
+          import json, sys
+          number, merged_at, sha, head, base, login, out = sys.argv[1:]
+          doc = {
+              "number": int(number),
+              "merged_at": None if merged_at == "null" else merged_at,
+              "merge_commit_sha": sha,
+              "head": {"ref": head},
+              "base": {"ref": base},
+              "user": {"login": login},
+          }
+          json.dump(doc, open(f"{out}/{number}.json", "w"))
+          PY
+          }
+          run_cut() { # <pr number> <commit>
+            : > "$OUT"
+            ( cd "$UP" && env \
+                GH_TOKEN=fake \
+                GITHUB_REPOSITORY=megaeth-labs/fake \
+                GITHUB_OUTPUT="$OUT" \
+                VERSION=1.3.0 \
+                PREFIX=release-v \
+                FILE=VERSION \
+                PATTERN=plain \
+                COMMIT="$2" \
+                PR_NUMBER="$1" \
+                EXPECTED_AUTHOR='mega-gutenberg[bot]' \
+                TOOLS="$TOOLS" \
+                bash "$SH/cut.sh" ) > "$RUNNER_TEMP/cut.log" 2>&1
+          }
+          branch_at() { git -C "$UP" ls-remote --heads origin refs/heads/release-v1.3.0 | cut -f1; }
+          refuse_cut() { # <pr number> <commit> <message fragment>
+            if run_cut "$1" "$2"; then
+              echo "expected a refusal for PR $1"; cat "$RUNNER_TEMP/cut.log"; exit 1
+            fi
+            grep -qF "$3" "$RUNNER_TEMP/cut.log" \
+              || { echo "PR $1 refused, but not for '$3':"; cat "$RUNNER_TEMP/cut.log"; exit 1; }
+            [[ -z "$(branch_at)" ]] || { echo "a refused cut still created release-v1.3.0"; exit 1; }
+          }
+          candidate=chore/release-candidate-1.3.0
+          merged=2026-01-01T00:00:00Z
+          bot='mega-gutenberg[bot]'
+          pr 12 "$merged" "$merge" "$candidate" main 'mega-maxwell[bot]'
+          pr 13 null "$merge" "$candidate" main "$bot"
+          pr 14 "$merged" "$earlier" "$candidate" main "$bot"
+          pr 15 "$merged" "$merge" "$candidate" release-v1.2.0 "$bot"
+          pr 16 "$merged" "$merge" feature/x main "$bot"
+          pr 17 "$merged" "$earlier" "$candidate" main "$bot"
+          refuse_cut 12 "$merge" "not by 'mega-gutenberg[bot]'"
+          refuse_cut 13 "$merge" "has not been merged"
+          refuse_cut 14 "$merge" "not the pushed commit"
+          refuse_cut 15 "$merge" "not the default branch 'main'"
+          refuse_cut 16 "$merge" "is not a chore/release-candidate-* branch"
+          refuse_cut 17 "$earlier" "says 1.0.0, expected 1.3.0"
+          refuse_cut "" "$merge" "cut needs the commit and pr_number inputs"
+          refuse_cut 11 "" "cut needs the commit and pr_number inputs"
+
+          # The version comes from the PR's head ref, read through the API.
+          pr 11 "$merged" "$merge" "$candidate" main "$bot"
+          : > "$OUT"
+          env STAGE=cut PR_NUMBER=11 INPUT_VERSION= GH_TOKEN=fake GITHUB_REPOSITORY=megaeth-labs/fake \
+            GITHUB_OUTPUT="$OUT" TOOLS="$TOOLS" bash "$SH/version.sh"
+          expect_out() { grep -qxF "$1" "$OUT" || { echo "no '$1' in the step output:"; cat "$OUT"; exit 1; }; }
+          expect_out "version=1.3.0"
+
+          run_cut 11 "$merge" || { cat "$RUNNER_TEMP/cut.log"; exit 1; }
+          expect_out "release_branch=release-v1.3.0"
+          [[ "$(branch_at)" == "$merge" ]] \
+            || { echo "release-v1.3.0 is not at the merge commit: '$(branch_at)'"; exit 1; }
+          echo "release-v1.3.0 created at $merge"
+
+          # A retry of the cut that succeeded: the branch is already at the
+          # merge commit, so it is a no-op that says so and exits 0.
+          run_cut 11 "$merge" || { echo "a retried cut failed"; cat "$RUNNER_TEMP/cut.log"; exit 1; }
+          expect_out "release_branch=release-v1.3.0"
+          grep -qF "release-v1.3.0 already exists at $merge" "$RUNNER_TEMP/cut.log" \
+            || { echo "the retry did not report the existing cut:"; cat "$RUNNER_TEMP/cut.log"; exit 1; }
+          [[ "$(branch_at)" == "$merge" ]] || { echo "the existing branch moved"; exit 1; }
+
+          # The branch at another commit is not this cut: refused, both SHAs
+          # named, and it is not moved.
+          git -C "$UP" push --quiet origin ":refs/heads/release-v1.3.0"
+          git -C "$UP" push --quiet origin "$earlier:refs/heads/release-v1.3.0"
+          if run_cut 11 "$merge"; then
+            echo "a cut over a branch at another commit succeeded"; cat "$RUNNER_TEMP/cut.log"; exit 1
+          fi
+          grep -qF "branch release-v1.3.0 already exists at $earlier, not at the candidate merge commit $merge" "$RUNNER_TEMP/cut.log" \
+            || { echo "refused, but without both SHAs:"; cat "$RUNNER_TEMP/cut.log"; exit 1; }
+          [[ "$(branch_at)" == "$earlier" ]] || { echo "the conflicting branch moved"; exit 1; }
+
+          # Two cuts race: the ref is absent when this one looks, a concurrent
+          # one creates it first and this create gets a 422. At the merge
+          # commit that is the same cut; anywhere else it is refused.
+          git -C "$UP" push --quiet origin ":refs/heads/release-v1.3.0"
+          echo "$merge" > "$RUNNER_TEMP/race-create"
+          run_cut 11 "$merge" || { echo "a cut that lost the race to the same cut failed"; cat "$RUNNER_TEMP/cut.log"; exit 1; }
+          [[ ! -e "$RUNNER_TEMP/race-create" ]] || { echo "the race was not exercised"; exit 1; }
+          grep -qF "release-v1.3.0 already exists at $merge" "$RUNNER_TEMP/cut.log" \
+            || { echo "the lost race was not reported:"; cat "$RUNNER_TEMP/cut.log"; exit 1; }
+          [[ "$(branch_at)" == "$merge" ]] || { echo "release-v1.3.0 is not at the merge commit after the race"; exit 1; }
+          git -C "$UP" push --quiet origin ":refs/heads/release-v1.3.0"
+          echo "$earlier" > "$RUNNER_TEMP/race-create"
+          if run_cut 11 "$merge"; then
+            echo "a cut that lost the race to another commit succeeded"; cat "$RUNNER_TEMP/cut.log"; exit 1
+          fi
+          grep -qF "already exists at $earlier, not at the candidate merge commit $merge" "$RUNNER_TEMP/cut.log" \
+            || { echo "refused, but not for the racer's commit:"; cat "$RUNNER_TEMP/cut.log"; exit 1; }
+          echo "cut creates the branch for a merged gutenberg candidate, is a no-op when it is already there, and refuses the rest"
+
+      # propose never rewrites the candidate branch. A re-dispatch closes the
+      # open candidate PR, deletes the branch and pushes a fresh one as a new
+      # ref; the remote here refuses every non-fast-forward update, the way a
+      # ruleset that bans force pushes does, so a forced push anywhere in the
+      # step fails this case. Retries and concurrent runs, whoever got where
+      # first, converge on one branch and one open PR.
+      - name: A re-dispatched candidate supersedes the open one, and nothing is force-pushed
+        run: |
+          set -euo pipefail
+          C="$RUNNER_TEMP/candidate"
+          git init --quiet --bare "$C.git"
+          git -C "$C.git" config receive.denyNonFastForwards true
+          git clone --quiet "$C.git" "$C" 2>/dev/null
+          echo 1.2.0 > "$C/VERSION"
+          git -C "$C" add -A && git -C "$C" commit --quiet -m "feat: first"
+          git -C "$C" push --quiet origin HEAD:refs/heads/main
+          main="$(git -C "$C" rev-parse HEAD)"
+          head=chore/release-candidate-1.3.0
+          app='mega-gutenberg[bot]'
+          rm -rf "$RUNNER_TEMP/prs"
+          # Each propose commits at its own time, so every candidate is a
+          # different commit and an in-place update would be non-fast-forward.
+          tick=1700000000
+          propose() { # [VAR=value ...] — the bump, then the step, on a fresh checkout of main
+            tick=$((tick + 60))
+            export GIT_AUTHOR_DATE="@$tick +0000" GIT_COMMITTER_DATE="@$tick +0000"
+            git -C "$C" checkout --quiet -B main "$main"
+            echo "${BUMP_TO:-1.3.0}" > "$C/VERSION"
+            : > "$OUT"
+            ( cd "$C" && env GH_TOKEN=fake GITHUB_REPOSITORY=megaeth-labs/fake GITHUB_OUTPUT="$OUT" \
+                VERSION=1.3.0 OLD_VERSION=1.2.0 RELEASE_BRANCH= BASE_COMMIT= PREFIX=release-v SYNCED=unchanged \
+                PR_LABELS="release, candidate" \
+                GIT_AUTHOR_NAME="$app" GIT_AUTHOR_EMAIL=app@example.invalid \
+                GIT_COMMITTER_NAME="$app" GIT_COMMITTER_EMAIL=app@example.invalid \
+                "$@" bash "$SH/open-pr.sh" ) > "$RUNNER_TEMP/open-pr.log" 2>&1
+          }
+          says() { grep -qF "$1" "$RUNNER_TEMP/open-pr.log" || { echo "no '$1' in:"; cat "$RUNNER_TEMP/open-pr.log"; exit 1; }; }
+          ok() { propose "$@" || { echo "propose failed:"; cat "$RUNNER_TEMP/open-pr.log"; exit 1; }; }
+          remote_head() { git -C "$C" ls-remote --heads origin "refs/heads/$head" | cut -f1; }
+          pr() { # <number> <field>
+            python3 -c 'import json,sys; v=json.load(open(sys.argv[1]))[sys.argv[2]]; print(v if isinstance(v,str) else json.dumps(v))' \
+              "$RUNNER_TEMP/prs/$1.json" "$2"
+          }
+          open_prs() { python3 "$RUNNER_TEMP/bin/fake-pr.py" list --head "$head" --state open \
+            | python3 -c 'import json,sys; print(" ".join(str(p["number"]) for p in json.load(sys.stdin)))'; }
+          converged() { # <the one open PR> — one branch, one open PR, and the step reported it
+            [[ "$(open_prs)" == "$1" ]] || { echo "open candidate PRs: '$(open_prs)', expected '$1'"; exit 1; }
+            [[ -n "$(remote_head)" ]] || { echo "$head is missing"; exit 1; }
+            grep -qxF "pr_url=https://github.com/megaeth-labs/fake/pull/$1" "$OUT" \
+              || { echo "the step did not report PR $1:"; cat "$OUT"; exit 1; }
+          }
+
+          # The fixture remote really refuses a forced update.
+          git -C "$C" push --quiet origin "HEAD:refs/heads/probe"
+          if git -C "$C" push --quiet --force origin "$(git -C "$C" commit-tree "HEAD^{tree}" -m probe):refs/heads/probe" 2>/dev/null; then
+            echo "the fixture remote accepted a force push"; exit 1
+          fi
+          git -C "$C" push --quiet origin :refs/heads/probe
+
+          # A first propose: a new branch on main, one PR, opened by the app.
+          ok
+          converged 100
+          first="$(remote_head)"
+          [[ "$(git -C "$C" rev-parse "$first~1")" == "$main" ]] || { echo "the candidate is not on main"; exit 1; }
+          [[ "$(git -C "$C" log -1 --format='%an|%cn|%s' "$first")" == "$app|$app|chore(release): candidate v1.3.0" ]] \
+            || { echo "wrong commit: $(git -C "$C" log -1 --format='%an|%cn|%s' "$first")"; exit 1; }
+          [[ "$(git -C "$C" show "$first:VERSION")" == 1.3.0 ]] || { echo "the bump is not in the candidate"; exit 1; }
+          [[ "$(pr 100 base)" == main && "$(pr 100 author)" == "$app" ]] || { echo "PR 100 base/author is wrong"; exit 1; }
+          [[ "$(pr 100 labels)" == '["release", "candidate"]' ]] || { echo "PR 100 labels: $(pr 100 labels)"; exit 1; }
+          pr 100 body > "$RUNNER_TEMP/body"
+          grep -qxF '<!-- release-candidate: v1.3.0 -->' "$RUNNER_TEMP/body" || { echo "no marker:"; cat "$RUNNER_TEMP/body"; exit 1; }
+          grep -qF "Merging this PR creates the release branch \`release-v1.3.0\` at the merge commit." "$RUNNER_TEMP/body" \
+            || { cat "$RUNNER_TEMP/body"; exit 1; }
+          grep -qxF "previous release's entry synced from its tag: unchanged." "$RUNNER_TEMP/body" || { cat "$RUNNER_TEMP/body"; exit 1; }
+          says "pushed $head at $first as a new ref"
+          says "stays after the PR merges"
+
+          # A re-dispatch supersedes it: closed with a comment, the branch
+          # deleted and pushed again as a new ref, a fresh PR.
+          echo true > "$RUNNER_TEMP/auto-delete"
+          ok
+          converged 101
+          [[ "$(remote_head)" != "$first" ]] || { echo "the re-dispatch did not make a new candidate commit"; exit 1; }
+          [[ "$(pr 100 state)" == CLOSED ]] || { echo "the superseded PR is still open"; exit 1; }
+          grep -qF "Superseded: a fresh candidate for v1.3.0 replaces this PR" <<< "$(pr 100 comments)" \
+            || { echo "no supersede comment: $(pr 100 comments)"; exit 1; }
+          says "closed superseded candidate PR #100"
+          says "deleted the old $head"
+          says "deleted when the PR merges, by the repository's 'Automatically delete head branches' setting"
+          rm "$RUNNER_TEMP/auto-delete"
+
+          # A retry after a partial failure: the PR was closed, the branch is
+          # still there and has no PR (equally: pushed, then died before the PR).
+          python3 "$RUNNER_TEMP/bin/fake-pr.py" close 101 --comment "closed by hand"
+          ok
+          converged 102
+          says "deleted the old $head"
+
+          # The PR this run would close was closed by a concurrent run first.
+          : > "$RUNNER_TEMP/race-close"
+          ok
+          converged 103
+          says "candidate PR #102 was already closed"
+
+          # The branch was deleted by a concurrent run first.
+          : > "$RUNNER_TEMP/race-delete"
+          ok
+          converged 104
+          says "was already deleted"
+
+          # A concurrent run pushed its own branch right after the delete and
+          # opened its PR: this push is refused, its branch and PR stand.
+          echo with-pr > "$RUNNER_TEMP/race-push"
+          ok
+          converged 105
+          [[ ! -e "$RUNNER_TEMP/race-push" ]] || { echo "the race was not exercised"; exit 1; }
+          [[ "$(git -C "$C" log -1 --format=%s "$(remote_head)")" == "chore(release): a concurrent candidate" ]] \
+            || { echo "the concurrent run's branch was replaced"; exit 1; }
+          says "was created at $(remote_head) by a concurrent run"
+          says "candidate PR https://github.com/megaeth-labs/fake/pull/105 was opened by a concurrent run"
+
+          # The same, but the concurrent run died before its PR: this run opens it.
+          echo no-pr > "$RUNNER_TEMP/race-push"
+          ok
+          converged 106
+          [[ "$(git -C "$C" log -1 --format=%s "$(remote_head)")" == "chore(release): a concurrent candidate" ]] \
+            || { echo "the concurrent run's branch was replaced"; exit 1; }
+          says "opened candidate PR https://github.com/megaeth-labs/fake/pull/106"
+
+          # A concurrent run opened the PR between this push and this create.
+          : > "$RUNNER_TEMP/race-pr"
+          ok
+          converged 107
+          says "candidate PR https://github.com/megaeth-labs/fake/pull/107 was opened by a concurrent run"
+
+          # The delete lost to a concurrent run that kept the branch and opened
+          # a PR: nothing is pushed over it.
+          before="$(remote_head)"
+          : > "$RUNNER_TEMP/race-recreate"
+          ok
+          converged 108
+          [[ "$(remote_head)" == "$before" ]] || { echo "the concurrent run's branch moved"; exit 1; }
+          says "by a concurrent run; keeping it rather than replacing it"
+
+          # A delete that just fails, with no PR owning the branch, is an error.
+          python3 "$RUNNER_TEMP/bin/fake-pr.py" close 108 --comment "closed by hand"
+          : > "$RUNNER_TEMP/fail-delete"
+          if propose; then echo "a failed delete succeeded"; cat "$RUNNER_TEMP/open-pr.log"; exit 1; fi
+          says "could not delete $head, and no open PR owns it"
+          rm "$RUNNER_TEMP/fail-delete"
+          ok
+          converged 109
+
+          # Nothing to propose: no PR closed, nothing pushed.
+          before="$(remote_head)"
+          BUMP_TO=1.2.0 ok
+          says "no candidate PR opened, nothing pushed"
+          grep -qxF "pr_url=" "$OUT" || { cat "$OUT"; exit 1; }
+          [[ "$(open_prs)" == 109 && "$(remote_head)" == "$before" ]] || { echo "an empty propose touched the candidate"; exit 1; }
+
+          # A base_commit candidate targets the release branch.
+          ok RELEASE_BRANCH=release-v1.3.0 BASE_COMMIT="$main"
+          converged 110
+          [[ "$(pr 110 base)" == release-v1.3.0 ]] || { echo "PR 110 targets $(pr 110 base)"; exit 1; }
+          pr 110 body | grep -qF "Cut from \`$main\`, which is not the tip of the default branch: \`release-v1.3.0\` already exists" \
+            || { pr 110 body; exit 1; }
+          echo "every propose left one $head and one open PR, and the remote never took a forced update"
+
+  # release-publish re-verifies the merged settle PR through the API and tags
+  # the pushed commit. The three steps that do it are extracted by name and run
+  # against a throwaway bare remote, a fake gh that answers from fixtures and
+  # records what it was asked to create, and fixtures for each refusal.
+  release-publish:
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    timeout-minutes: 5
+    env:
+      TOOLS: ${{ github.workspace }}/.github/actions/release-tools/release_tools.py
+      ACTION: ${{ github.workspace }}/.github/actions/release-publish/action.yml
+      AUTH_WRAPPER: ${{ github.workspace }}/.github/actions/git-auth/with-github-auth.sh
+      GITHUB_AUTH_TOKEN: fixture-token
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      # `runner` is not a context a job-level `env:` may read, so the paths
+      # the steps below share are set here instead.
+      - name: Where the rehearsal lives
+        run: |
+          set -euo pipefail
+          {
+            echo "REPO=$RUNNER_TEMP/repo"
+            echo "SH=$RUNNER_TEMP/sh"
+            echo "OUT=$RUNNER_TEMP/step-output"
+            echo "FIX=$RUNNER_TEMP/fixtures"
+            echo "ARGS=$RUNNER_TEMP/fixtures/release-create-args"
+            echo "RELEASES=$RUNNER_TEMP/fixtures/releases"
+          } >> "$GITHUB_ENV"
+
+      - name: The shell under test, taken from the action
+        run: |
+          set -euo pipefail
+          python3 -m pip install --quiet pyyaml
+          mkdir -p "$SH"
+          python3 - "$ACTION" "$SH" <<'PY'
+          import pathlib, sys, yaml
+
+          want = {
+              "Guard": "guard.sh",
+              "Create and push tag": "tag.sh",
+              "Publish GitHub Release": "release.sh",
+          }
+          steps = yaml.safe_load(open(sys.argv[1]))["runs"]["steps"]
+          found = {s["name"]: s["run"] for s in steps if s.get("name") in want}
+          missing = sorted(set(want) - set(found))
+          if missing:
+              sys.exit(f"action.yml has no step named {missing}; this job drives them by name")
+          # The job below skips the tag step by this condition; if the action's
+          # changes, the rehearsal would no longer be rehearsing it.
+          cond = next(s for s in steps if s.get("name") == "Create and push tag").get("if")
+          if cond != "steps.guard.outputs.tag_exists != 'true'":
+              sys.exit(f"the tag step's condition is {cond!r}; update this job to match")
+          cond = next(s for s in steps if s.get("name") == "Publish GitHub Release").get("if")
+          if cond != "steps.guard.outputs.published != 'true'":
+              sys.exit(f"the Release step's condition is {cond!r}; update this job to match")
+          for name, script in found.items():
+              pathlib.Path(sys.argv[2], want[name]).write_text(script)
+              print(f"extracted {name!r} -> {want[name]}")
+          PY
+          cat > "$SH/helpers.sh" <<'SH'
+          out_get() { grep -m1 "^$1=" "$OUT" | cut -d= -f2-; }
+
+          expect_output() { # <exact line the guard should have written>
+            grep -qxF "$1" "$OUT" || { echo "no '$1' in the guard output:"; cat "$OUT"; exit 1; }
+          }
+
+          # The three steps, the way the action's steps run them.
+          guard() { # <pr> [expected author]
+            : > "$OUT"
+            ( cd "$REPO" && env \
+                GH_TOKEN=fake \
+                GITHUB_REPOSITORY=megaeth-labs/fake \
+                GITHUB_OUTPUT="$OUT" \
+                MERGE_SHA="$(cat "$FIX/merge-$1")" \
+                PR_NUMBER="$1" \
+                EXPECTED_AUTHOR="${2-mega-gutenberg[bot]}" \
+                PREFIX=release-v \
+                FILE=VERSION \
+                PATTERN=plain \
+                CHANGELOG=CHANGELOG.md \
+                bash "$SH/guard.sh" )
+          }
+
+          tag_step() {
+            ( cd "$REPO" && env \
+                TAG="$(out_get tag)" \
+                MERGE_SHA="$(out_get merge_sha)" \
+                bash "$SH/tag.sh" ) || return 1
+            touch "$FIX/tag-ran"
+          }
+
+          release_step() {
+            touch "$FIX/release-ran"
+            : > "$OUT.release"
+            ( cd "$REPO" && env \
+                GH_TOKEN=fake \
+                GITHUB_REPOSITORY=megaeth-labs/fake \
+                TAG="$(out_get tag)" \
+                NOTES="$(out_get notes_file)" \
+                GITHUB_OUTPUT="$OUT.release" \
+                bash "$SH/release.sh" )
+          }
+
+          # The action's step list: the tag step runs unless the guard says the
+          # tag is already at the commit, the Release step unless the guard
+          # found the Release too.
+          publish() { # <pr> [expected author]
+            rm -f "$FIX/tag-ran" "$FIX/release-ran"
+            guard "$@" || return 1
+            if [[ "$(out_get tag_exists)" != true ]]; then
+              tag_step || return 1
+            fi
+            if [[ "$(out_get published)" != true ]]; then
+              release_step || return 1
+            fi
+          }
+
+          refuse() { # <pr> <message fragment> [expected author]
+            local log="$RUNNER_TEMP/refused.log"
+            if publish "$1" "${3-mega-gutenberg[bot]}" > "$log" 2>&1; then
+              echo "expected a refusal for PR $1"; cat "$log"; exit 1
+            fi
+            grep -qF "$2" "$log" || { echo "refused, but not for '$2':"; cat "$log"; exit 1; }
+            [[ ! -e "$FIX/tag-ran" ]] || { echo "a refused publish still ran the tag step"; exit 1; }
+          }
+
+          # What the remote says, not what the logs say.
+          remote_commit() { # <tag> -> commit an annotated remote tag points at, or nothing
+            git ls-remote "$REPO.git" "refs/tags/$1^{}" | cut -f1
+          }
+          remote_tag_object() { # <tag>
+            git ls-remote "$REPO.git" "refs/tags/$1" | cut -f1
+          }
+          seed_tag() { # <tag> <sha>: an annotated tag already on the remote
+            git -C "$REPO" tag -a "$1" "$2" -m seed
+            git -C "$REPO" push --quiet origin "refs/tags/$1"
+            git -C "$REPO" tag -d "$1" > /dev/null
+          }
+
+          # A release branch: the settled commit, optionally a late commit on
+          # top (LATE=1), then the settle PR's merge commit. The PR fixture
+          # describes it; O_* variables bend one field of that fixture.
+          settle() { # <version> <pr>
+            local v="$1" pr="$2"
+            git -C "$REPO" checkout --quiet -B "release-v$v" "$(cat "$FIX/root")"
+            (
+              cd "$REPO"
+              echo "${WRONG_FILE:-$v}" > VERSION
+              printf '# Changelog\n\n## v%s (2024-02-01)\n\n- shipped in %s\n\n## v1.0.0 (2024-01-01)\n\n- shipped in 1.0.0\n' "$v" "$v" > CHANGELOG.md
+              git add -A && git commit --quiet -m "chore(release): changelog for v$v"
+              git rev-parse HEAD > "$FIX/settled-$pr"
+              if [[ "${LATE:-}" == 1 ]]; then
+                git commit --quiet --allow-empty -m "fix: landed after the settle PR opened"
+              fi
+              git commit --quiet --allow-empty -m "Merge settle PR #$pr"
+              git rev-parse HEAD > "$FIX/merge-$pr"
+              git push --quiet --force origin "release-v$v"
+              git checkout --quiet main
+            )
+            write_pr "$pr" "$v"
+          }
+
+          write_pr() { # <pr> <version>
+            python3 - "$FIX" "$1" "$2" <<'PY'
+          import json, os, pathlib, sys
+
+          fix, pr, v = pathlib.Path(sys.argv[1]), sys.argv[2], sys.argv[3]
+          env = os.environ.get
+          settled = env("O_SETTLED") or (fix / f"settled-{pr}").read_text().strip()
+          merge = env("O_MERGE_SHA") or (fix / f"merge-{pr}").read_text().strip()
+          body = f"Settle v{v}."
+          if env("O_MARKER") != "none":
+              body += f"\n\n<!-- release-settle: v{v} {settled} -->\n"
+          doc = {
+              "merged_at": None if env("O_UNMERGED") else "2024-02-02T00:00:00Z",
+              "merge_commit_sha": merge,
+              "head": {"ref": env("O_HEAD") or f"chore/release-settle-v{v}"},
+              "base": {"ref": env("O_BASE") or f"release-v{v}"},
+              "user": {"login": env("O_USER") or "mega-gutenberg[bot]"},
+              "body": body,
+          }
+          (fix / f"pr-{pr}.json").write_text(json.dumps(doc))
+          PY
+          }
+          SH
+
+      - name: A fake gh
+        run: |
+          set -euo pipefail
+          mkdir -p "$RUNNER_TEMP/bin" "$FIX"
+          : > "$ARGS"
+          : > "$RELEASES"
+          cat > "$RUNNER_TEMP/bin/gh" <<'SH'
+          #!/usr/bin/env bash
+          # Only what the shell under test calls. The pull request comes from a
+          # fixture; a Release exists once `release create` has been asked for
+          # it, and what it was asked is recorded for the assertions.
+          set -euo pipefail
+          if [[ "${1:-}" == api && "${2:-}" == repos/*/pulls/* ]]; then
+            f="$FIX/pr-${2##*/}.json"
+            [[ -f "$f" ]] || { echo "gh: no fixture $f" >&2; exit 1; }
+            cat "$f"
+            exit 0
+          fi
+          if [[ "${1:-}" == api && "${2:-}" == repos/*/releases/latest ]]; then
+            if [[ -s "$FIX/latest-release" ]]; then
+              cat "$FIX/latest-release"
+              exit 0
+            fi
+            echo "gh: Not Found (HTTP 404)" >&2
+            exit 1
+          fi
+          if [[ "${1:-}" == release && "${2:-}" == view ]]; then
+            if grep -qxF "${3:-}" "$RELEASES"; then
+              echo "https://github.com/megaeth-labs/fake/releases/tag/$3"
+              exit 0
+            fi
+            echo "release not found" >&2
+            exit 1
+          fi
+          if [[ "${1:-}" == release && "${2:-}" == create ]]; then
+            if [[ -e "$FIX/fail-create" ]]; then
+              echo "gh: release create failed (injected)" >&2
+              exit 1
+            fi
+            if grep -qxF "${3:-}" "$RELEASES"; then
+              echo "HTTP 422: Validation Failed (Release.tag_name already_exists)" >&2
+              exit 1
+            fi
+            notes=""
+            args=("$@")
+            for ((i = 0; i < ${#args[@]}; i++)); do
+              if [[ "${args[i]}" == --notes-file ]]; then notes="${args[i + 1]}"; fi
+            done
+            [[ -s "$notes" ]] || { echo "gh: --notes-file '$notes' is missing or empty" >&2; exit 1; }
+            echo "$*" >> "$ARGS"
+            echo "$3" >> "$RELEASES"
+            # GitHub's "latest" moves only for a Release created with --latest.
+            if [[ " $* " == *" --latest "* ]]; then echo "$3" > "$FIX/latest-release"; fi
+            echo "https://github.com/megaeth-labs/fake/releases/tag/$3"
+            exit 0
+          fi
+          echo "gh: unexpected call: $*" >&2
+          exit 99
+          SH
+          chmod +x "$RUNNER_TEMP/bin/gh"
+          echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
+
+      - name: A repository shaped like a trunk with a release line to cut
+        run: |
+          set -euo pipefail
+          git init --quiet --bare -b main "$REPO.git"
+          git clone --quiet "$REPO.git" "$REPO" 2>/dev/null
+          cd "$REPO"
+          # Local config only: the steps under test run with the global and
+          # system config blanked, as they do in the action.
+          git config user.name tester
+          git config user.email tester@example.invalid
+          git config commit.gpgsign false
+          git config tag.gpgsign false
+          echo 1.0.0 > VERSION
+          printf '# Changelog\n\n## v1.0.0 (2024-01-01)\n\n- shipped in 1.0.0\n' > CHANGELOG.md
+          git add -A && git commit --quiet -m "feat: the first release"
+          git push --quiet -u origin main
+          git rev-parse HEAD > "$FIX/root"
+
+      - name: A settled release is tagged at its merge commit and published
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+          settle 1.2.0 101
+          publish 101
+          merge="$(cat "$FIX/merge-101")"
+          expect_output "version=1.2.0"
+          expect_output "tag=v1.2.0"
+          expect_output "tag_exists=false"
+          [[ -e "$FIX/tag-ran" ]] || { echo "the tag step did not run"; exit 1; }
+          [[ "$(git --git-dir="$REPO.git" cat-file -t refs/tags/v1.2.0)" == tag ]] \
+            || { echo "v1.2.0 is not an annotated tag"; exit 1; }
+          [[ "$(remote_commit v1.2.0)" == "$merge" ]] \
+            || { echo "v1.2.0 does not point at the merge commit $merge"; exit 1; }
+          git --git-dir="$REPO.git" cat-file -p refs/tags/v1.2.0 | grep -qxF "Release v1.2.0" \
+            || { echo "the tag annotation changed"; exit 1; }
+          grep -qF "release create v1.2.0 --verify-tag --latest --title v1.2.0 --notes-file " "$ARGS" \
+            || { echo "the Release was not created for v1.2.0:"; cat "$ARGS"; exit 1; }
+          grep -qx "v1.2.0" "$RELEASES" || { echo "no Release v1.2.0"; exit 1; }
+          grep -qxF -- "- shipped in 1.2.0" "$RUNNER_TEMP/release-notes-v1.2.0.md" \
+            || { echo "the notes are not the changelog section"; exit 1; }
+          echo "v1.2.0 is an annotated tag at $merge and the Release was asked for with --verify-tag"
+
+      - name: A retry of a finished publish is a no-op
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+          before="$(remote_tag_object v1.2.0)"
+          publish 101 > "$RUNNER_TEMP/retry.log" 2>&1 \
+            || { echo "a retry of a finished publish failed"; cat "$RUNNER_TEMP/retry.log"; exit 1; }
+          expect_output "tag_exists=true"
+          expect_output "published=true"
+          expect_output "release_url=https://github.com/megaeth-labs/fake/releases/tag/v1.2.0"
+          grep -qF "Already published" "$RUNNER_TEMP/retry.log" \
+            || { echo "the no-op was not reported:"; cat "$RUNNER_TEMP/retry.log"; exit 1; }
+          [[ ! -e "$FIX/tag-ran" && ! -e "$FIX/release-ran" ]] || { echo "a step ran on the retry"; exit 1; }
+          [[ "$(remote_tag_object v1.2.0)" == "$before" ]] || { echo "the tag moved"; exit 1; }
+          [[ "$(grep -c 'release create v1.2.0 ' "$ARGS")" == 1 ]] || { echo "a second Release was created"; exit 1; }
+          echo "tag and Release both at the commit: exit 0, notice, nothing changed"
+
+      - name: A run that died after the tag is resumed, not refused
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+          settle 1.3.0 102
+          merge="$(cat "$FIX/merge-102")"
+          # The Release call fails once: the tag is pushed, no Release exists.
+          : > "$FIX/fail-create"
+          if publish 102 > "$RUNNER_TEMP/first-run.log" 2>&1; then
+            echo "the first run should have failed at the Release"; exit 1
+          fi
+          rm "$FIX/fail-create"
+          [[ "$(remote_commit v1.3.0)" == "$merge" ]] \
+            || { echo "the interrupted run left no tag at the merge commit"; exit 1; }
+          ! grep -qx "v1.3.0" "$RELEASES" || { echo "a Release exists after the failed run"; exit 1; }
+          object="$(remote_tag_object v1.3.0)"
+          # Re-run: the tag is already there, so the tag step is skipped.
+          publish 102
+          expect_output "tag=v1.3.0"
+          expect_output "tag_exists=true"
+          [[ ! -e "$FIX/tag-ran" ]] || { echo "the tag step ran again"; exit 1; }
+          [[ "$(remote_tag_object v1.3.0)" == "$object" ]] || { echo "the tag was rewritten"; exit 1; }
+          grep -qF "release create v1.3.0 --verify-tag --latest --title v1.3.0 --notes-file " "$ARGS" \
+            || { echo "the Release was not created with the guard's tag:"; cat "$ARGS"; exit 1; }
+          grep -qx "v1.3.0" "$RELEASES" || { echo "no Release v1.3.0"; exit 1; }
+          echo "v1.3.0 resumed: tag step skipped, tag untouched, Release created"
+
+      - name: Anything that does not describe a settled release is refused
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+
+          settle 1.4.0 103
+          O_USER=someone-else write_pr 103 1.4.0
+          refuse 103 "was opened by 'someone-else'"
+
+          # A commit landed after the settle PR was opened: the merge commit's
+          # parent is no longer the settled one.
+          LATE=1 settle 1.5.0 104
+          refuse 104 "drifted"
+
+          settle 1.6.0 105
+          seed_tag v1.6.0 "$(cat "$FIX/settled-105")"
+          refuse 105 "a release is published once"
+          [[ "$(remote_commit v1.6.0)" == "$(cat "$FIX/settled-105")" ]] || { echo "the tag moved"; exit 1; }
+
+          WRONG_FILE=1.8.1 settle 1.8.0 107
+          refuse 107 "says 1.8.1, expected 1.8.0"
+
+          settle 1.9.0 108
+          O_UNMERGED=1 write_pr 108 1.9.0
+          refuse 108 "is not merged"
+
+          settle 1.9.1 109
+          O_MERGE_SHA="$(cat "$FIX/settled-109")" write_pr 109 1.9.1
+          refuse 109 "not the pushed commit"
+
+          settle 1.9.2 110
+          O_MARKER=none write_pr 110 1.9.2
+          refuse 110 "settle PR body has no"
+
+          settle 1.9.3 111
+          O_BASE=main write_pr 111 1.9.3
+          refuse 111 "merged into 'main'"
+
+          settle 1.9.4 112
+          O_HEAD=feature/x write_pr 112 1.9.4
+          refuse 112 "is not a settle PR"
+
+          # The remote and the recorded calls, not the messages, say that
+          # nothing was published: only the two good releases were created.
+          for v in 1.4.0 1.5.0 1.8.0 1.9.0 1.9.1 1.9.2 1.9.3 1.9.4; do
+            [[ -z "$(git ls-remote "$REPO.git" "refs/tags/v$v")" ]] \
+              || { echo "v$v was tagged although it was refused"; exit 1; }
+          done
+          [[ "$(grep -c . "$ARGS")" == 2 ]] \
+            || { echo "expected exactly the v1.2.0 and v1.3.0 Releases:"; cat "$ARGS"; exit 1; }
+          echo "nine refusals, no tag, no Release"
+
+      # Two publishes of the same merge race (a re-run while the first is still
+      # going): whichever pushes the tag or creates the Release second keeps
+      # the first one's, if it is at this commit.
+      - name: A publish that loses a race to its twin keeps the winner's tag and Release
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+          settle 2.0.0 120
+          merge="$(cat "$FIX/merge-120")"
+          guard 120
+          expect_output "tag_exists=false"
+          seed_tag v2.0.0 "$merge"          # the twin pushed first
+          object="$(remote_tag_object v2.0.0)"
+          tag_step > "$RUNNER_TEMP/race.log" 2>&1 \
+            || { echo "losing the tag race to the same commit failed"; cat "$RUNNER_TEMP/race.log"; exit 1; }
+          grep -qF "by a concurrent run" "$RUNNER_TEMP/race.log" || { cat "$RUNNER_TEMP/race.log"; exit 1; }
+          [[ "$(remote_tag_object v2.0.0)" == "$object" ]] || { echo "the twin's tag was replaced"; exit 1; }
+          echo v2.0.0 >> "$RELEASES"          # the twin created the Release first
+          release_step > "$RUNNER_TEMP/race.log" 2>&1 \
+            || { echo "losing the Release race failed"; cat "$RUNNER_TEMP/race.log"; exit 1; }
+          grep -qxF "url=https://github.com/megaeth-labs/fake/releases/tag/v2.0.0" "$OUT.release" \
+            || { echo "no url for the twin's Release:"; cat "$OUT.release"; exit 1; }
+          [[ "$(grep -c 'release create v2.0.0 ' "$ARGS")" == 0 ]] || { echo "a Release was recorded twice"; exit 1; }
+
+          # The twin's tag at another commit is not ours: the tag step fails.
+          settle 2.1.0 121
+          guard 121
+          seed_tag v2.1.0 "$(cat "$FIX/settled-121")"
+          if tag_step > "$RUNNER_TEMP/race.log" 2>&1; then
+            echo "a tag race lost to another commit succeeded"; exit 1
+          fi
+          grep -qF "not $(cat "$FIX/merge-121")" "$RUNNER_TEMP/race.log" || { cat "$RUNNER_TEMP/race.log"; exit 1; }
+          echo "races at the same commit converge; a tag elsewhere still fails"
+
+      # v2.1.0 is tagged (above): a settle PR for an older line that is merged
+      # now must not be tagged, and must not take "latest" from a newer one.
+      - name: An older version merged after a newer one is refused, and only the newest is latest
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+          created="$(grep -c . "$ARGS")"
+          settle 1.9.5 130
+          refuse 130 "v1.9.5 is not newer than the latest published tag v2.1.0"
+          # The guard refuses, not only the tag step's re-check behind it.
+          grep -qF "::error title=Refusing to publish an older version::settle PR #130: v1.9.5 is not newer than the latest published tag v2.1.0 (rule: a version is published only when it is newer than every vX.Y.Z tag)" \
+            "$RUNNER_TEMP/refused.log" || { cat "$RUNNER_TEMP/refused.log"; exit 1; }
+          grep -qxF "version=1.9.5" "$OUT" && { echo "the guard wrote outputs for a refused version"; exit 1; }
+          [[ -z "$(git ls-remote "$REPO.git" refs/tags/v1.9.5)" ]] || { echo "v1.9.5 was tagged"; exit 1; }
+          [[ "$(grep -c . "$ARGS")" == "$created" ]] || { echo "a Release was created for v1.9.5"; exit 1; }
+
+          # Two lines publish under their own concurrency groups. v3.0.0 passes
+          # its guard, then v3.1.0 is published before v3.0.0's tag step runs.
+          settle 3.0.0 131
+          guard 131
+          cp "$OUT" "$OUT.131"
+          settle 3.1.0 132
+          publish 132
+          grep -qF "release create v3.1.0 --verify-tag --latest --title v3.1.0 " "$ARGS" || { cat "$ARGS"; exit 1; }
+          [[ "$(cat "$FIX/latest-release")" == v3.1.0 ]]
+          cp "$OUT.131" "$OUT"
+          if tag_step > "$RUNNER_TEMP/late.log" 2>&1; then echo "a tag step after a newer tag succeeded"; exit 1; fi
+          grep -qF "v3.0.0 is not newer than the latest published tag v3.1.0" "$RUNNER_TEMP/late.log" \
+            || { cat "$RUNNER_TEMP/late.log"; exit 1; }
+          [[ -z "$(git ls-remote "$REPO.git" refs/tags/v3.0.0)" ]] || { echo "v3.0.0 was tagged"; exit 1; }
+
+          # Its tag got out before the newer Release (a run resumed late): the
+          # Release is still created, but it does not take "latest".
+          seed_tag v3.0.0 "$(cat "$FIX/merge-131")"
+          release_step > "$RUNNER_TEMP/late.log" 2>&1 || { cat "$RUNNER_TEMP/late.log"; exit 1; }
+          grep -qF "release create v3.0.0 --verify-tag --latest=false --title v3.0.0 " "$ARGS" || { cat "$ARGS"; exit 1; }
+          grep -qF "Not the latest Release::v3.0.0 is published without becoming latest" "$RUNNER_TEMP/late.log" \
+            || { cat "$RUNNER_TEMP/late.log"; exit 1; }
+          [[ "$(cat "$FIX/latest-release")" == v3.1.0 ]] || { echo "latest moved back to $(cat "$FIX/latest-release")"; exit 1; }
+          echo "v1.9.5 refused after v2.1.0; v3.0.0 not tagged after v3.1.0, and its late Release is not latest"
+
+  release-route:
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    timeout-minutes: 5
+    env:
+      TOOLS: ${{ github.workspace }}/.github/actions/release-tools/release_tools.py
+      ACTION: ${{ github.workspace }}/.github/actions/release-route/action.yml
+      PUBLISH_ACTION: ${{ github.workspace }}/.github/actions/release-publish/action.yml
+      AUTH_WRAPPER: ${{ github.workspace }}/.github/actions/git-auth/with-github-auth.sh
+      GITHUB_AUTH_TOKEN: fixture-token
+      GH_TOKEN: fixture-token
+      # GitHub ignores env: for its default GITHUB_* variables, so the runner's
+      # real GITHUB_REPOSITORY would reach the scripts; every invocation below
+      # passes this one explicitly instead.
+      FAKE_REPOSITORY: megaeth-labs/fake
+      EXPECTED_AUTHOR: mega-gutenberg[bot]
+      PREFIX: release-v
+      FILE: VERSION
+      PATTERN: plain
+      DISPATCH_VERSION: ""
+      DEFAULT_BRANCH: ""
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Where the rehearsal lives
+        run: |
+          set -euo pipefail
+          {
+            echo "REPO=$RUNNER_TEMP/route-repo"
+            echo "SH=$RUNNER_TEMP/route-sh"
+            echo "FIX=$RUNNER_TEMP/route-fixtures"
+            echo "OUT=$RUNNER_TEMP/route-output"
+            echo "REAL_GIT=$(command -v git)"
+          } >> "$GITHUB_ENV"
+
+      - name: Extract shipped scripts and install fakes
+        run: |
+          set -euo pipefail
+          python3 -m pip install --quiet pyyaml
+          mkdir -p "$SH" "$FIX" "$RUNNER_TEMP/route-bin"
+          python3 - <<'PY'
+          import os, pathlib, yaml
+
+          for action, name, dest in (("ACTION", "Route", "route.sh"),
+                                     ("PUBLISH_ACTION", "Guard", "publish-guard.sh")):
+              steps = yaml.safe_load(pathlib.Path(os.environ[action]).read_text())["runs"]["steps"]
+              script = next(s["run"] for s in steps if s.get("name") == name)
+              pathlib.Path(os.environ["SH"], dest).write_text(script)
+          PY
+          [[ "$(grep -c AUTH_WRAPPER "$ACTION")" -ge 2 ]]
+          cat > "$SH/helpers.sh" <<'SH'
+          route() { # <kind> <ref> <sha> [event]
+            : > "$OUT"
+            ( cd "$REPO" && env KIND="$1" GITHUB_REPOSITORY="$FAKE_REPOSITORY" GITHUB_REF_NAME="$2" \
+                GITHUB_SHA="$3" GITHUB_EVENT_NAME="${4:-push}" GITHUB_OUTPUT="$OUT" bash "$SH/route.sh" )
+          }
+          out_get() {
+            python3 - "$OUT" "$1" <<'PY'
+          import pathlib, sys
+          lines = iter(pathlib.Path(sys.argv[1]).read_text().splitlines())
+          values = {}
+          for line in lines:
+              if "<<" in line:
+                  key, end = line.split("<<", 1)
+                  parts = []
+                  for part in lines:
+                      if part == end:
+                          break
+                      parts.append(part)
+                  values[key] = "\n".join(parts)
+              else:
+                  key, value = line.split("=", 1)
+                  values[key] = value
+          print(values.get(sys.argv[2], ""), end="")
+          PY
+          }
+          expect_output() {
+            local actual
+            actual="$(out_get "$1")"
+            [[ "$actual" == "$2" ]] || { echo "expected $1=$2, got '$actual'"; cat "$OUT"; exit 1; }
+          }
+          SH
+          cat > "$RUNNER_TEMP/route-bin/git" <<'SH'
+          #!/usr/bin/env bash
+          set -euo pipefail
+          if [[ "${1:-}" == fetch || "${1:-}" == ls-remote ]]; then
+            [[ "${GITHUB_AUTH_TOKEN:-}" == fixture-token && -n "${GIT_ASKPASS:-}" \
+                && "${GIT_CONFIG_GLOBAL:-}" == /dev/null ]] \
+              || { echo "remote git bypassed auth wrapper" >&2; exit 97; }
+            echo "authenticated $1" >> "$FIX/auth-calls"
+          fi
+          exec "$REAL_GIT" "$@"
+          SH
+          cat > "$RUNNER_TEMP/route-bin/gh" <<'SH'
+          #!/usr/bin/env bash
+          set -euo pipefail
+          [[ "$GH_TOKEN" == fixture-token ]]
+          # Calls without a repo argument resolve it from the checkout's remote.
+          [[ -z "${GH_REPO:-}" && "$(git config --get remote.origin.url)" == "https://github.com/$FAKE_REPOSITORY.git" ]] \
+            || { echo "gh would resolve a repository other than $FAKE_REPOSITORY" >&2; exit 98; }
+          case "$*" in
+            "repo view $FAKE_REPOSITORY "*) echo main ;;
+            api*"repos/$FAKE_REPOSITORY/commits/"*"/pulls")
+              cat "$FIX/pulls.json" ;;
+            api*"repos/$FAKE_REPOSITORY/pulls/42")
+              jq '.[0]' "$FIX/settle.json" ;;
+            "pr list "*)
+              echo fallback >> "$FIX/fallback-calls"
+              cat "$FIX/fallback.json" ;;
+            "release view "*)
+              [[ -e "$FIX/release-exists" ]] || exit 1
+              echo '{"tagName":"v1.2.0"}' ;;
+            *) echo "unexpected gh call: $*" >&2; exit 99 ;;
+          esac
+          SH
+          chmod +x "$RUNNER_TEMP/route-bin/"*
+          echo "$RUNNER_TEMP/route-bin" >> "$GITHUB_PATH"
+
+      - name: A local remote and merged PR fixtures
+        run: |
+          set -euo pipefail
+          git init --quiet --bare -b main "$REPO.git"
+          git clone --quiet "$REPO.git" "$REPO" 2>/dev/null
+          cd "$REPO"
+          git config user.name tester
+          git config user.email tester@example.invalid
+          git config commit.gpgsign false
+          git config tag.gpgsign false
+          echo 1.1.0 > VERSION
+          git add VERSION && git commit --quiet -m "feat: initial release"
+          git tag -a v1.1.0 -m seed
+          git push --quiet origin main --tags
+          git rev-parse HEAD > "$FIX/old"
+          git branch release-v1.2.0
+          git branch release-v1.1.0
+          echo 1.2.0 > VERSION
+          printf '# Changelog\n\n## v1.2.0 (2026-10-27)\n\n- shipped\n' > CHANGELOG.md
+          git add -A && git commit --quiet -m "chore(release): candidate v1.2.0"
+          git rev-parse HEAD > "$FIX/candidate"
+          git checkout --quiet release-v1.2.0
+          git merge --quiet --ff-only main
+          git rev-parse HEAD > "$FIX/parent"
+          git commit --quiet --allow-empty -m "Merge settle PR"
+          git rev-parse HEAD > "$FIX/merge"
+          git push --quiet origin main release-v1.2.0 release-v1.1.0 --tags
+          git checkout --quiet release-v1.2.0
+          # Local rewrite survives the real wrapper's blank global config.
+          # Without the wrapper the git shim refuses before touching HTTPS.
+          git config "url.file://$REPO.git.insteadOf" "https://github.com/$FAKE_REPOSITORY.git"
+          git remote set-url origin "https://github.com/$FAKE_REPOSITORY.git"
+          if git ls-remote origin > "$FIX/unwrapped.log" 2>&1; then
+            echo "unwrapped remote read succeeded"; exit 1
+          else
+            [[ "$?" == 97 ]]
+          fi
+          grep -qxF "remote git bypassed auth wrapper" "$FIX/unwrapped.log"
+          python3 - <<'PY'
+          import json, os, pathlib
+
+          fix = pathlib.Path(os.environ["FIX"])
+          def sha(name):
+              return (fix / name).read_text().strip()
+          def pr(kind):
+              return {
+                  "number": 41 if kind == "candidate" else 42,
+                  "merged_at": "2026-10-27T00:00:00Z",
+                  "merge_commit_sha": sha(kind if kind == "candidate" else "merge"),
+                  "head": {"ref": f"chore/release-{kind}-v1.2.0"},
+                  "base": {"ref": "main" if kind == "candidate" else "release-v1.2.0"},
+                  "user": {"login": "mega-gutenberg[bot]"},
+                  "body": f"<!-- release-settle: v1.2.0 {sha('parent')} -->",
+              }
+          for kind in ("candidate", "settle"):
+              (fix / f"{kind}.json").write_text(json.dumps([pr(kind)]))
+          p = pr("settle")
+          fallback = [{"number": p["number"], "mergeCommit": {"oid": p["merge_commit_sha"]},
+                       "mergedAt": p["merged_at"], "headRefName": p["head"]["ref"],
+                       "baseRefName": p["base"]["ref"], "author": p["user"], "body": p["body"]}]
+          (fix / "fallback-good.json").write_text(json.dumps(fallback))
+          (fix / "fallback.json").write_text("[]")
+          PY
+
+      - name: Candidate cut and author mismatch
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+          cp "$FIX/candidate.json" "$FIX/pulls.json"
+          route candidate main "$(cat "$FIX/candidate")"
+          expect_output action cut
+          expect_output version 1.2.0
+          expect_output release_branch release-v1.2.0
+          expect_output commit "$(cat "$FIX/candidate")"
+          expect_output pr_number 41
+          expect_output targets '[]'
+          jq '.[0].user.login = "mega-maxwell[bot]"' "$FIX/candidate.json" > "$FIX/pulls.json"
+          route candidate main "$(cat "$FIX/candidate")"
+          expect_output action skip
+          [[ "$(out_get reason)" == *"mega-maxwell[bot]"* ]]
+
+      - name: Old version skips and fresh or stale settlement routes
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+          echo '[]' > "$FIX/pulls.json"
+          route settle release-v1.2.0 "$(cat "$FIX/old")"
+          expect_output action skip
+          cp "$FIX/settle.json" "$FIX/pulls.json"
+          route settle release-v1.2.0 "$(cat "$FIX/merge")"
+          expect_output action publish
+          expect_output commit "$(cat "$FIX/merge")"
+          expect_output pr_number 42
+          jq '.[0].body = "<!-- release-settle: v1.2.0 0000000000000000000000000000000000000000 -->"' \
+            "$FIX/settle.json" > "$FIX/pulls.json"
+          route settle release-v1.2.0 "$(cat "$FIX/merge")"
+          expect_output action refresh
+          [[ "$(out_get targets | jq -r '.[0].commit')" == "$(cat "$FIX/merge")" ]]
+
+      - name: Dispatch excludes tagged branches and filters versions
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+          route settle main "$(cat "$FIX/candidate")" workflow_dispatch
+          expect_output action refresh
+          [[ "$(out_get targets | jq length)" == 1 ]]
+          [[ "$(out_get targets | jq -r '.[0].release_branch')" == release-v1.2.0 ]]
+          DISPATCH_VERSION=v1.1.0 route settle main "$(cat "$FIX/candidate")" workflow_dispatch
+          expect_output action skip
+          expect_output targets '[]'
+
+      - name: Lagging index uses merged PR fallback and malformed API fails
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+          echo '[]' > "$FIX/pulls.json"
+          cp "$FIX/fallback-good.json" "$FIX/fallback.json"
+          route settle release-v1.2.0 "$(cat "$FIX/merge")"
+          expect_output action publish
+          expect_output pr_number 42
+          [[ -s "$FIX/fallback-calls" ]]
+          echo '{"message":"API failure"}' > "$FIX/pulls.json"
+          if route settle release-v1.2.0 "$(cat "$FIX/merge")" > "$FIX/malformed.log" 2>&1; then
+            echo "non-array API response succeeded"; exit 1
+          fi
+          [[ ! -s "$OUT" ]]
+          grep -qF "pulls API must return arrays" "$FIX/malformed.log"
+          echo '[]' > "$FIX/fallback.json"
+
+      # git's -v:refname sorts v1.3.0-rc1 above every v1.2.x: it must not be
+      # taken for the latest release, or every route would fail on it.
+      - name: A tag that is not vX.Y.Z is ignored, not fatal
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+          git -C "$REPO" tag v1.3.0-rc1 "$(cat "$FIX/old")"
+          "$AUTH_WRAPPER" git -C "$REPO" push --quiet origin refs/tags/v1.3.0-rc1
+          [[ "$(git -C "$REPO" tag -l 'v*' --sort=-v:refname | head -n1)" == v1.3.0-rc1 ]]
+          cp "$FIX/settle.json" "$FIX/pulls.json"
+          route settle release-v1.2.0 "$(cat "$FIX/merge")" > "$FIX/rc.log" 2>&1 \
+            || { echo "an rc tag failed the route"; cat "$FIX/rc.log"; exit 1; }
+          expect_output action publish
+          grep -qF "ignoring tag 'v1.3.0-rc1'" "$FIX/rc.log" || { cat "$FIX/rc.log"; exit 1; }
+          jq '.[0].body = "<!-- release-settle: v1.2.0 0000000000000000000000000000000000000000 -->"' \
+            "$FIX/settle.json" > "$FIX/pulls.json"
+          route settle release-v1.2.0 "$(cat "$FIX/merge")"
+          expect_output action refresh
+          route settle main "$(cat "$FIX/candidate")" workflow_dispatch
+          expect_output action refresh
+          [[ "$(out_get targets | jq -r '.[0].release_branch')" == release-v1.2.0 ]]
+          echo "v1.3.0-rc1 is ignored: publish, refresh and dispatch all route"
+
+      # A hotfix line merged after a newer release would otherwise be tagged
+      # and made the latest Release.
+      - name: An older version merged after a newer release is not published
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+          merge="$(cat "$FIX/merge")"
+          git -C "$REPO" tag v1.3.0 "$(cat "$FIX/old")"
+          "$AUTH_WRAPPER" git -C "$REPO" push --quiet origin refs/tags/v1.3.0
+          cp "$FIX/settle.json" "$FIX/pulls.json"
+          route settle release-v1.2.0 "$merge"
+          expect_output action skip
+          expect_output reason "refusing to publish settle PR #42: v1.2.0 is not newer than the latest published tag v1.3.0 (rule: a version is published only when it is newer than every vX.Y.Z tag)"
+          : > "$OUT"
+          if ( cd "$REPO" && env GITHUB_REPOSITORY="$FAKE_REPOSITORY" MERGE_SHA="$merge" PR_NUMBER=42 \
+              CHANGELOG=CHANGELOG.md GITHUB_OUTPUT="$OUT" bash "$SH/publish-guard.sh" ) > "$FIX/older.log" 2>&1; then
+            echo "the publish guard accepted an older version"; cat "$FIX/older.log"; exit 1
+          fi
+          grep -qF "Refusing to publish an older version::settle PR #42: v1.2.0 is not newer than the latest published tag v1.3.0" "$FIX/older.log" \
+            || { cat "$FIX/older.log"; exit 1; }
+          [[ ! -s "$OUT" ]]
+          [[ -z "$(git ls-remote "$REPO.git" refs/tags/v1.2.0)" ]]
+          "$AUTH_WRAPPER" git -C "$REPO" push --quiet origin :refs/tags/v1.3.0
+          git -C "$REPO" tag -d v1.3.0 > /dev/null
+          echo "route and publish guard both refuse v1.2.0 after v1.3.0"
+
+      - name: An unreadable version file fails the route instead of skipping
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+          echo '[]' > "$FIX/pulls.json"
+          for case in "MISSING plain does not exist" "VERSION toml does not parse"; do
+            read -r file pattern message <<< "$case"
+            for event in push workflow_dispatch; do
+              if FILE="$file" PATTERN="$pattern" route settle release-v1.2.0 "$(cat "$FIX/merge")" "$event" \
+                  > "$FIX/unreadable.log" 2>&1; then
+                echo "$event with $file/$pattern routed: $(out_get action) $(out_get reason)"; exit 1
+              fi
+              grep -qF "cannot read the version file: $file" "$FIX/unreadable.log" || { cat "$FIX/unreadable.log"; exit 1; }
+              grep -qF "$message" "$FIX/unreadable.log" || { cat "$FIX/unreadable.log"; exit 1; }
+              grep -qF "'$pattern'" "$FIX/unreadable.log" || { cat "$FIX/unreadable.log"; exit 1; }
+              [[ ! -s "$OUT" ]]
+            done
+          done
+          echo "a missing or unparsable version file fails push and dispatch routes, naming file and pattern"
+
+      - name: Partial publication resumes and reports the actual tag commit
+        run: |
+          set -euo pipefail
+          source "$SH/helpers.sh"
+          merge="$(cat "$FIX/merge")"
+          git -C "$REPO" tag -a v1.2.0 "$merge" -m seed
+          "$AUTH_WRAPPER" git -C "$REPO" push --quiet origin refs/tags/v1.2.0
+          cp "$FIX/settle.json" "$FIX/pulls.json"
+          route settle release-v1.2.0 "$merge"
+          expect_output action publish
+          : > "$OUT"
+          ( cd "$REPO" && env GITHUB_REPOSITORY="$FAKE_REPOSITORY" MERGE_SHA="$merge" PR_NUMBER=42 \
+              CHANGELOG=CHANGELOG.md GITHUB_OUTPUT="$OUT" bash "$SH/publish-guard.sh" )
+          expect_output tag_exists true
+          expect_output merge_sha "$merge"
+          git -C "$REPO" tag v1.3.0 "$merge"
+          "$AUTH_WRAPPER" git -C "$REPO" push --quiet origin refs/tags/v1.3.0
+          # A different push must name the peeled commit, not the tag object.
+          echo '[]' > "$FIX/pulls.json"
+          route settle release-v1.2.0 "$(cat "$FIX/old")" > "$FIX/tagged-skip.log"
+          expect_output action skip
+          [[ "$(out_get reason)" == *"merge commit $merge to finish publishing"* ]]
+          grep -qF "::warning::" "$FIX/tagged-skip.log"
+          # Lightweight tags use the unpeeled ref as the commit.
+          route settle release-v1.3.0 "$(cat "$FIX/old")"
+          expect_output action skip
+          tip="$(git -C "$REPO" rev-parse v1.3.0)"
+          [[ "$(out_get reason)" == *"merge commit $tip to finish publishing"* ]]
+          touch "$FIX/release-exists"
+          cp "$FIX/settle.json" "$FIX/pulls.json"
+          route settle release-v1.2.0 "$merge"
+          expect_output action skip
+          expect_output reason "v1.2.0 is already published"
+          [[ -s "$FIX/auth-calls" ]]
+          echo "all route decisions and publication resume assertions passed"
+
+      - name: Remove rehearsal repositories
+        if: always()
+        run: |
+          rm -rf "$REPO" "$REPO.git" "$SH" "$FIX" "$RUNNER_TEMP/route-bin"
+          rm -f "$OUT"
+
   # The generated parts of every action README (inputs, outputs, steps,
   # errors) and the catalogue come from action.yml; stale docs fail here.
   docs:
diff --git a/README.md b/README.md
index bc57267..d41396d 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,8 @@ by every repository, and the workflow templates that show up under
   shared actions, how to consume one, how to change one.
 - [`.github/actions/RELEASE.md`](.github/actions/RELEASE.md) — the release
   pipeline: candidate, settle, publish, publish targets.
+- [`docs/RELEASING.md`](docs/RELEASING.md) — operator runbook for the release
+  pipeline: the four flows, environments, dry run, troubleshooting.
 - [`.github/actions/CLAUDE-CI.md`](.github/actions/CLAUDE-CI.md) — the Claude
   checks: PR review, label check, issue triage, interactive.
 - `.github/actions/<action>/README.md` — one reference per action; the
@@ -19,8 +21,23 @@ by every repository, and the workflow templates that show up under
   [`merge-queue-skipper`](.github/actions/merge-queue-skipper/README.md),
   [`pr-lint`](.github/actions/pr-lint/README.md).
 - [`workflow-templates/`](workflow-templates/) — the reference callers.
+  [`.github/scripts/copy_templates.py`](.github/scripts/copy_templates.py)
+  renders the release templates with one repository's values filled in.
 - [`profile/`](profile/) — the organisation profile page.
 
 `actions-test.yml` is the only gate between a change here and every
 consumer's CI: unit tests of the helpers, an end-to-end drive of the actions
 that can run without a repository, and the documentation check.
+
+## App tokens: Maxwell and Gutenberg
+
+Two GitHub Apps mint tokens through `actions/create-github-app-token`.
+Maxwell is the CI app (`vars.MEGA_MAXWELL_CLIENT_ID`, `secrets.MEGA_MAXWELL_PK`):
+it may write only pull requests and issues and never touches a release.
+Gutenberg is the release app (`vars.RELEASE_APP_CLIENT_ID`,
+`secrets.RELEASE_APP_PRIVATE_KEY`), minted only in a job of the `release`
+environment, where every write of a release is made. The
+[`app-token-lint`](.github/actions/app-token-lint/README.md) action enforces
+this on every workflow change (rules L1-L6, listed with their messages in the
+[runbook](docs/RELEASING.md#app-token-lint-errors)); run it locally with
+`python3 .github/scripts/app_token_lint.py --repo <repo> <workflows dir>`.
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
new file mode 100644
index 0000000..2827524
--- /dev/null
+++ b/docs/RELEASING.md
@@ -0,0 +1,215 @@
+# Releasing: operator runbook
+
+How a megaeth-labs repository ships a release, who does what, and what to do
+when a step stops. This page is the short operator view; the mechanics of each
+action are in the [release guide](../.github/actions/RELEASE.md) and the
+per-action READMEs linked below.
+
+## Who acts: the identity model
+
+| Identity | Does | Never does |
+|---|---|---|
+| `mega-gutenberg[bot]` (the release app) | Every write of the release: the candidate PR, the `release-vX.Y.Z` branch, the settle PR, the tag, the GitHub Release, the dist-docs PR | Nothing is approved by it; it is not a reviewer |
+| `mega-maxwell[bot]` (the CI app) | Only ever reads, as far as a release is concerned: at most a read-only token for private dependencies | Create a branch, PR, tag or Release of a release; appear as a git identity or PR-author filter in a release workflow |
+| A human reviewer | Reviews and merges the candidate PR and the settle PR; adds the `compat:` label | - |
+
+The gutenberg token can be minted only in a job that runs in the `release`
+environment. The [app-token lint](#app-token-lint) enforces both halves of this
+split on every workflow change.
+
+## The four flows
+
+Each flow ends in a push (or a merge) that the next flow listens for; there is
+no polling. The read-only `route` step ([`release-route`](../.github/actions/release-route/README.md))
+decides what a push means: `cut`, `refresh`, `publish` or `skip`, with a
+one-sentence reason in the job log.
+
+1. **Candidate: push to the default branch, then the cut.** An operator starts
+   the Release Candidate workflow with the version (and optionally
+   `base_commit`). Gutenberg opens a `chore/release-candidate-vX.Y.Z` PR that
+   bumps the version file and drafts the changelog entry. A reviewer adds the
+   `compat:` label (see [the reviewer step](#the-reviewer-step-the-compat-label))
+   and merges it. The merge is a push to the default branch; `route` finds the
+   merged, gutenberg-authored candidate PR and answers `cut`, and
+   [`release-candidate`](../.github/actions/release-candidate/README.md) creates
+   `release-vX.Y.Z` at the merge commit. With `base_commit`, the PR targets a
+   release branch that `propose` already cut, so there is no `cut`.
+2. **Settle: push to `release-vX.Y.Z`, then the settle PR.** The creation of the
+   branch (and every later push to it) starts the Release Settle workflow.
+   Once the candidate has landed on the branch, `route` answers `refresh` and
+   [`release-settle`](../.github/actions/release-settle/README.md) opens or
+   updates one long-lived `chore/release-settle-vX.Y.Z` PR onto the release
+   branch, with the changelog entry for the commits since the previous tag. New
+   commits on the release branch refresh the same PR. A manual dispatch refreshes
+   every eligible release branch (or the one named by `version`) and never
+   publishes.
+3. **Tag: merge the settle PR.** A reviewer adds the `compat:` label and merges
+   the settle PR. That is the release decision; nothing waits for a click on a
+   run. The merge is a push to the release branch; `route` re-checks that the PR
+   is gutenberg's, that it settled exactly the branch tip it was merged onto, and
+   answers `publish`. [`release-publish`](../.github/actions/release-publish/README.md)
+   then creates the annotated tag `vX.Y.Z` at the merge commit (once) and the
+   GitHub Release with the changelog section as notes. A settle PR that went stale
+   before it merged publishes nothing; `route` answers `refresh` and a fresh PR
+   follows.
+4. **Assets: the tag push (the Release) fires On Release.** Publishing the
+   Release runs the repository's `on-release.yml`, which builds, verifies the
+   version ([`release-verify-version`](../.github/actions/release-verify-version/README.md)),
+   uploads ([`release-upload-artifact`](../.github/actions/release-upload-artifact/README.md)),
+   attaches [release assets](../.github/actions/release-assets/README.md), and
+   publishes crates. Repositories that keep release notes in `dist-docs` (mega-reth)
+   also open the dist-docs PR in this workflow, as gutenberg.
+
+## Environments and their variables
+
+| Environment | Holds | Deployment policy | Reviewers |
+|---|---|---|---|
+| `release` | variable `RELEASE_APP_CLIENT_ID` (the app's Client ID, not the numeric App ID); secret `RELEASE_APP_PRIVATE_KEY` | the default branch and `release-v*` branches (add the tag `v*` only where a release-event job needs gutenberg, such as mega-reth's dist-docs job) | none: merging the settle PR is the decision |
+| `publish` | `CARGO_REGISTRY_TOKEN`, `GCP_AUTH_KEY` (the publish targets) | tags `v*` | none |
+
+`environment: release` appears only in `release-candidate.yml`,
+`release-settle.yml` and `on-release.yml` (lint rule L5). A job in `publish` that
+only reads private dependencies may also mint a gutenberg token, but only with
+`permission-contents: read` (L2).
+
+Rulesets the app relies on:
+
+- `v*` tag ruleset: bypass actors are the repository admin role and
+  mega-gutenberg. No other app.
+- `release-*` branch ruleset: no app bypass, so the settle PR is genuinely
+  reviewed. Required checks use `do_not_enforce_on_create: true`; "require
+  branches to be up to date" is on; merge methods include squash or merge, not
+  rebase only.
+- No exemption from a `prohibit-force-push` ruleset is needed, even one that
+  covers all branches (mega-reth's does): nothing in the pipeline force-pushes
+  any branch. A re-dispatched candidate supersedes the open one — it closes
+  that PR with a comment, deletes its `chore/release-candidate-*` branch,
+  pushes a fresh one as a new ref and opens a fresh PR. A re-run settle
+  fast-forwards its own open PR's branch, or closes a PR it does not maintain
+  and starts a new branch. The app does need to delete those branches, so a
+  ruleset that restricts deletions must not cover `refs/heads/chore/release-*`.
+
+## The dry-run flag
+
+`on-release.yml` has a `dry_run` input, true by default when dispatched. A
+rehearsal runs every job (build, verify, check destinations, `cargo publish
+--dry-run`) and uploads, publishes and attaches nothing. Start it from the
+Actions tab with the workflow's ref set to the tag `vX.Y.Z` and `dry_run`
+ticked; a run started by the Release event is never a dry run. The same flag
+exists as `dry_run` on [`release-assets`](../.github/actions/release-assets/README.md),
+[`release-upload-artifact`](../.github/actions/release-upload-artifact/README.md),
+[`release-publish-rust-crates`](../.github/actions/release-publish-rust-crates/README.md)
+and [`release-verify-version`](../.github/actions/release-verify-version/README.md).
+The candidate and settle workflows have no dry-run: their output is a PR, which
+is itself the preview.
+
+## Copying a template
+
+The reference callers live in [`workflow-templates/`](../workflow-templates/).
+In a repository, use "New workflow → By megaeth-labs", or copy the file by
+hand and edit the placeholders (version file, changelog, destinations). For
+example, to copy the snapshot template into a clone of your repository:
+
+```sh
+cp workflow-templates/snapshot-publish.yml /path/to/my-repo/.github/workflows/
+```
+
+Copy the release templates the same way: `release-candidate.yml`,
+`release-settle.yml`, `on-release.yml` and `app-token-lint.yml`. Then check the
+copy before pushing (from a checkout of this repository):
+
+```sh
+python3 .github/scripts/app_token_lint.py --repo my-repo /path/to/my-repo/.github/workflows
+```
+
+Each template ships with a `.properties.json` sidecar that feeds the "New
+workflow" picker; keep the pair together when copying. The templates carry the
+mega-reth values as the worked example: `Cargo.toml` with `version_pattern:
+toml`, `cargo update --workspace` as the bump command, and the private
+dependency repos as the read-only dependency token's `repositories`.
+
+## The reviewer step: the `compat:` label
+
+Every PR into the default branch or a `release-*` branch must carry a label
+starting with `compat:` (mega-reth's required check "Compatibility Label Check",
+in `pr-title.yml`). The patch/minor/major call is a per-release judgement, so
+the pipeline leaves `pr_labels` empty on the candidate and settle PRs. The
+reviewer adds the label to both PRs while reviewing. `pr-title.yml` also
+listens for `labeled`, so adding the label re-runs the check and turns it green;
+no push or manual re-run is needed.
+
+## Troubleshooting
+
+Messages are quoted from the actions and from
+[`app_token_lint.py`](../.github/scripts/app_token_lint.py). `::error::` stops the
+run; `::warning::` and the route `skip` reason do not.
+
+### Route says skip
+
+| Message | Meaning and action |
+|---|---|
+| `no merged candidate PR matches this push` | A push to the default branch that is not the merge of a candidate PR. Normal for every other push. |
+| `PR #N author X does not match mega-gutenberg[bot]` | The PR was not opened by gutenberg (for example a hand-made or pre-migration PR). It never cuts or publishes. Close it and start the release again. |
+| `the candidate has not landed on this branch yet` | The release branch still has the old version. Nothing to do until the candidate PR merges into it. |
+| `not refreshing a settle PR: vX.Y.Z is not newer than the latest published tag vA.B.C (rule: …)` | The branch is not newer than the latest `vX.Y.Z` tag. Not a release. |
+| `refusing to publish settle PR #N: vX.Y.Z is not newer than the latest published tag vA.B.C (rule: a version is published only when it is newer than every vX.Y.Z tag)` | An older line (a hotfix branch) was settled after a newer release was published. It is not tagged, so the newer Release stays latest. Cut the fix as a version above vA.B.C instead. |
+| `vX.Y.Z is already published` | The tag and the Release both exist. |
+| `merged settle PR #N was stale (settled …, tip was …); a fresh settle PR follows` | The branch moved after the settle PR was written. Review and merge the fresh PR. |
+| `vX.Y.Z is tagged but has no Release: re-run the release-settle run for the settle PR's merge commit … to finish publishing` (also a `::warning::`) | `publish` died between tag and Release. Re-run the failed run for that merge commit; it creates the missing Release. |
+| `no route for kind=…, event=…, ref=…` | The event is not one the pipeline handles. |
+
+### Errors from the actions
+
+| Message | Meaning and action |
+|---|---|
+| `release-route needs full history; check out with fetch-depth: 0` | The route job's checkout is shallow. |
+| `cannot read the version file: FILE does not exist at … ` / `… does not parse with version_pattern '…'` | The route's `version_file` or `version_pattern` does not match the repository (or the settle step). The route fails, it does not skip: fix the workflow. |
+| `cut needs the commit and pr_number inputs (the release-route outputs)` | The `cut` job did not pass the route outputs. |
+| `candidate PR #N has not been merged; cut only runs for a merged candidate` | `cut` ran for a PR that was closed unmerged. |
+| `candidate PR #N targets '…', not the default branch '…'` | Only a candidate merged into the default branch is cut. |
+| `branch <name> already exists` | The branch was cut before. If the release was abandoned, delete the branch and propose again. |
+| `release candidates start from the default branch (…); this run is on …` | Dispatch the candidate workflow from the default branch. |
+| `base_commit … is not reachable from the default branch (…); a release must ship code that landed on trunk` | Choose a commit that is on the default branch. |
+| `$FILE at $COMMIT says X, expected Y` | The version file does not carry the release version at that commit. |
+| `could not merge … into …; close the settle PR so the next run recreates it` | A refresh conflicts with the settle PR branch. Close the settle PR; the next settle run recreates it. |
+| `… is not the tip of release-vX.Y.Z (tip is …). Settle the tip, or move the branch first.` | The branch moved while the settle ran. Re-run on the current tip. |
+| `release branch drifted: settle PR settled X but the branch tip at merge was Y. Re-run release-settle on the current tip.` | The settle PR was merged after the branch moved. Re-run, review the fresh PR. |
+| `settle PR body has no '<!-- release-settle: ... -->' marker; refusing to publish an unverifiable settlement` | The PR body was edited. Close it and let settle recreate it. |
+| `settle PR #N was opened by '…', not by 'mega-gutenberg[bot]' …; refusing to publish from it` | A hand-made settle PR never publishes. |
+| `tag vX.Y.Z already exists … and is not an unfinished release of …; a release is published once` | Publish refuses to retag. Investigate the existing tag. |
+| `Refusing to publish an older version::settle PR #N: vX.Y.Z is not newer than the latest published tag vA.B.C …` | Publish re-checks the route's order rule, in the guard and again right before the tag push. Nothing was tagged. |
+| `::warning title=Not the latest Release::vX.Y.Z is published without becoming latest …` | A newer Release was published while this one was in flight. The Release exists but GitHub's "latest" stays on the newer one. |
+| `release-vX.Y.Z moved to … after this refresh of … started …` | A refresh lost the race to a settle-PR merge or a newer push. It wrote nothing; the run for the new tip refreshes the settle PR. |
+| `::notice title=Already tagged::vX.Y.Z is already tagged, so this refresh … does not open or update a settle PR for it` | The release was published while this refresh ran. Nothing to do. |
+| `::warning::… lacks workflows that <default> has: … — a release-event workflow runs from the tagged commit's tree …` | The release branch is missing a workflow that the default branch has (usually `on-release.yml`). Add it to the branch through its own PR before merging the settle PR, or the Release publishes with nothing attached. |
+
+### App-token lint errors
+
+Each is reported as `::error file=<path>::<job>/<step>: <rule>: <message>`.
+
+| Code | Message | Fix |
+|---|---|---|
+| L1 | `Maxwell token requests permission-contents: write; Maxwell may only write pull-requests and issues` | Drop the permission, or mint a gutenberg token in a release job. A `permission-…` that is an expression is refused too. |
+| L2 | ``Gutenberg token needs `environment: release` (or `publish` with only permission-contents: read), job has none`` | Put the job in `environment: release`. |
+| L3 | `no Maxwell token in a release workflow; mint a Gutenberg token instead` | Replace the Maxwell token. |
+| L3 | `read-only dependency token names the repository itself (…)` | Remove the repository from `repositories:`; the checkout uses the job token. |
+| L4 | `mega-maxwell[bot] is not a release identity` | Use `mega-gutenberg[bot]` as git identity and PR-author filter. |
+| L5 | ``environment `release` is only for release-candidate.yml, release-settle.yml and on-release.yml`` | Move the job, or use a different environment. |
+| L6 | `Maxwell token requests no permission-* inputs, so it gets every permission of the installation (contents write included); list the permissions it needs` (also for Gutenberg, and for any app token in a release job) | Add the `permission-<x>:` inputs the job needs. |
+| parse | `malformed YAML …`, `not a workflow: the document is not a mapping`, `no such file or directory`, `no workflow files (*.yml, *.yaml) found` | Fix the input; a file that cannot be read never lints clean. |
+
+## App-token lint
+
+The check is `app-token-lint` ([README](../.github/actions/app-token-lint/README.md)),
+run on every workflow change through the `app-token-lint.yml` template. Its
+unit tests run in this repository's `actions-test.yml`. See the
+[root README](../README.md#app-tokens-maxwell-and-gutenberg) for the rules in
+one paragraph.
+
+## Keeping this page honest
+
+The generated tables in the action READMEs must match their `action.yml` (`python3 .github/scripts/action_docs.py` rewrites them). Confirm nothing drifted:
+
+```sh
+python3 .github/scripts/action_docs.py --check
+```
diff --git a/workflow-templates/app-token-lint.properties.json b/workflow-templates/app-token-lint.properties.json
new file mode 100644
index 0000000..7e0adc7
--- /dev/null
+++ b/workflow-templates/app-token-lint.properties.json
@@ -0,0 +1,8 @@
+{
+  "name": "App Token Lint",
+  "description": "Lint workflows for GitHub App token misuse: no CI-app token in release workflows, release-app tokens only in the release environment.",
+  "iconName": "octicon shield-check",
+  "categories": [
+    "Automation"
+  ]
+}
diff --git a/workflow-templates/app-token-lint.yml b/workflow-templates/app-token-lint.yml
new file mode 100644
index 0000000..31ab10f
--- /dev/null
+++ b/workflow-templates/app-token-lint.yml
@@ -0,0 +1,27 @@
+name: App Token Lint
+
+# Fails a pull request that mints a GitHub App token the wrong way: a CI-app
+# token with write permissions it must not have, the CI app in a release
+# workflow, or a release-app (mega-gutenberg) token outside the `release`
+# environment. Read-only; no secrets. The rules are listed in the guide.
+#
+# Guide: https://github.com/megaeth-labs/.github/blob/main/.github/actions/app-token-lint/README.md
+
+on:
+  pull_request:
+    paths: [".github/workflows/**"]
+  push:
+    branches: [$default-branch]
+
+permissions:
+  contents: read
+
+jobs:
+  app-token-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+
+      - uses: megaeth-labs/.github/.github/actions/app-token-lint@main
diff --git a/workflow-templates/on-release.yml b/workflow-templates/on-release.yml
index ef37b00..85ffaa1 100644
--- a/workflow-templates/on-release.yml
+++ b/workflow-templates/on-release.yml
@@ -1,10 +1,10 @@
 name: On Release
 
 # Publish targets for a release. Runs when the release pipeline publishes the
-# GitHub Release (release-publish creates it after the tag), and on demand
-# for a rehearsal on a tag ref, which runs every job with nothing uploaded,
-# published or attached (release-settle creates the Release right after the
-# tag; release-publish does the same for repos that settle by PR):
+# GitHub Release (the release-publish action, run by release-settle's publish
+# job with the release app mega-gutenberg, creates it right after the tag),
+# and on demand for a rehearsal on a tag ref, which runs every job with
+# nothing uploaded, published or attached:
 #   gh workflow run on-release.yml --ref vX.Y.Z -f dry_run=true
 # The tag being released is always the run's own ref; there is no tag input.
 # The `publish` environment authorises that ref, so it must also be what
@@ -14,7 +14,7 @@ name: On Release
 # workflow from the tag's tree, not from the default branch. A release branch
 # cut from a default branch that has it carries it; a branch cut before it
 # landed needs it cherry-picked (through its own PR — the `release-*` ruleset
-# requires one) before settlement is dispatched, or the Release publishes
+# requires one) before the settle PR is merged, or the Release publishes
 # with nothing attached and no failed run. release-settle warns when the
 # settled commit lacks a workflow the default branch has. A rehearsal
 # likewise needs a tag whose tree has this file.
@@ -23,8 +23,14 @@ name: On Release
 # policy of "selected tags: v*" and put CARGO_REGISTRY_TOKEN / GCP_AUTH_KEY
 # in it as environment secrets. A job can then use them only when the run's
 # ref is a v* tag — a release event or a tag-ref rehearsal — never from a
-# branch build. Give it no required reviewers: the human gate is the settle
-# approval, and a second click here only holds up the uploads.
+# branch build. Give it no required reviewers: the human gate is merging the
+# settle PR, and a second click here only holds up the uploads.
+#
+# Release-pipeline jobs mint only release-app (mega-gutenberg) tokens. A build
+# job that reads private dependency repositories in the `publish` environment
+# mints one with `permission-contents: read` and `repositories:` naming only
+# those repositories (never this one); it needs RELEASE_APP_CLIENT_ID and
+# RELEASE_APP_PRIVATE_KEY in `publish` too.
 #
 # Each target is its own job so a hiccup in one never blocks another. Delete
 # the jobs this repository does not need; keep the shared actions at @main.
diff --git a/workflow-templates/release-candidate.properties.json b/workflow-templates/release-candidate.properties.json
index 58219e1..0926e07 100644
--- a/workflow-templates/release-candidate.properties.json
+++ b/workflow-templates/release-candidate.properties.json
@@ -1,6 +1,6 @@
 {
   "name": "Release Candidate",
-  "description": "Start a release: bump the version on the default branch via PR, then cut release-vX.Y.Z on merge.",
+  "description": "Start a release: bump the version on the default branch via PR, then cut release-vX.Y.Z when it merges. All writes use the release app (mega-gutenberg).",
   "iconName": "octicon tag",
   "categories": [
     "Automation"
diff --git a/workflow-templates/release-candidate.yml b/workflow-templates/release-candidate.yml
index 125553f..abf6061 100644
--- a/workflow-templates/release-candidate.yml
+++ b/workflow-templates/release-candidate.yml
@@ -2,14 +2,22 @@ name: Release Candidate
 
 # Trunk-first release start. Dispatch with a version: the shared action bumps
 # the version file on the default branch, drafts the changelog entry, and
-# opens a candidate PR. When that
-# PR merges, the `cut` job creates `release-vX.Y.Z` at the merge commit. No
-# tag is created here — see release-settle / release-publish.
+# opens a candidate PR. When that PR merges, the push to the default branch
+# starts this workflow again: `route` recognises the merged candidate PR and
+# `cut` creates `release-vX.Y.Z` at the merge commit. No tag is created here;
+# see release-settle.
 #
 # To release a commit that is not the tip of the default branch, dispatch with
 # `base_commit` as well: `propose` creates `release-vX.Y.Z` at that commit and
 # aims the candidate PR at it, so that PR never touches the default branch and
-# the `cut` job below does not run.
+# `route` never selects `cut` for it.
+#
+# Every write is made by the release GitHub App (mega-gutenberg). Its token is
+# minted only in jobs that run in the `release` environment: create that
+# environment with a deployment policy of the default branch and `release-v*`
+# branches, and no required reviewers. The decision to release is made by
+# merging the candidate PR, not by a click on the run. `route` is read-only
+# and uses the job token.
 #
 # Guide: https://github.com/megaeth-labs/.github/blob/main/.github/actions/RELEASE.md
 
@@ -25,8 +33,7 @@ on:
         required: false
         type: string
         default: ""
-  pull_request:
-    types: [closed]
+  push:
     branches: [$default-branch]
 
 permissions:
@@ -36,20 +43,26 @@ jobs:
   propose:
     if: github.event_name == 'workflow_dispatch'
     # One proposal at a time: two dispatches would race on the candidate
-    # branch. Job-level, not workflow-level: every PR closing on the default
-    # branch also starts this workflow, and a workflow-wide group would let
-    # that noise evict a queued release run (one pending run per group).
+    # branch. Job-level, not workflow-level: every push to the default branch
+    # also starts this workflow, and a workflow-wide group would let that
+    # noise evict a queued release run (one pending run per group).
     # A skipped job holds no slot in a job-level group.
     concurrency:
       group: ${{ github.workflow }}-propose
       cancel-in-progress: false
     runs-on: ubuntu-latest
+    environment: release
     steps:
       - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3
-        id: app-token
+        id: release-token
         with:
-          client-id: ${{ vars.MEGA_MAXWELL_CLIENT_ID }}
-          private-key: ${{ secrets.MEGA_MAXWELL_PK }}
+          client-id: ${{ vars.RELEASE_APP_CLIENT_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+          owner: megaeth-labs
+          repositories: ${{ github.event.repository.name }}
+          permission-contents: write
+          permission-pull-requests: write
+          permission-workflows: write
 
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
@@ -59,7 +72,7 @@ jobs:
       - uses: megaeth-labs/.github/.github/actions/release-candidate@main
         with:
           stage: propose
-          token: ${{ steps.app-token.outputs.token }}
+          token: ${{ steps.release-token.outputs.token }}
           version: ${{ inputs.version }}
           base_commit: ${{ inputs.base_commit }}
           version_file: VERSION
@@ -67,29 +80,58 @@ jobs:
           changelog_file: CHANGELOG.md
           # Anything else that must move with the version, e.g. a lockfile:
           #   bump_command: cargo update --workspace
-          # (install the toolchain it needs in this job, before this step)
+          #   dependency_token: ${{ github.token }}
+          # (install the toolchain it needs in this job, before this step;
+          # dependency_token is what the bump command uses to read other
+          # repositories, and the job token reads this one)
+
+  # Read-only: decides from the pushed commit whether it is a merged candidate
+  # PR that targeted the default branch. One proposed with `base_commit` merges
+  # into the release branch propose already cut, and routes to nothing here.
+  route:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      action: ${{ steps.route.outputs.action }}
+      commit: ${{ steps.route.outputs.commit }}
+      pr_number: ${{ steps.route.outputs.pr_number }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - id: route
+        uses: megaeth-labs/.github/.github/actions/release-route@main
+        with:
+          kind: candidate
+          version_file: VERSION
+          version_pattern: plain
 
-  # Only candidate PRs that targeted the default branch reach this job (the
-  # `branches:` filter above): one proposed with `base_commit` merges into the
-  # release branch propose already cut.
   cut:
-    if: >-
-      github.event_name == 'pull_request' &&
-      github.event.pull_request.merged == true &&
-      startsWith(github.event.pull_request.head.ref, 'chore/release-candidate-') &&
-      github.event.pull_request.user.login == 'mega-maxwell[bot]'
-    # One cut at a time, never cancelled: pull_request.closed does not refire.
+    needs: route
+    if: needs.route.outputs.action == 'cut'
+    # One cut at a time, never cancelled: a push does not refire.
     # Job-level for the reason given on `propose`.
     concurrency:
       group: ${{ github.workflow }}-cut
       cancel-in-progress: false
     runs-on: ubuntu-latest
+    environment: release
     steps:
       - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3
-        id: app-token
+        id: release-token
         with:
-          client-id: ${{ vars.MEGA_MAXWELL_CLIENT_ID }}
-          private-key: ${{ secrets.MEGA_MAXWELL_PK }}
+          client-id: ${{ vars.RELEASE_APP_CLIENT_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+          owner: megaeth-labs
+          repositories: ${{ github.event.repository.name }}
+          permission-contents: write
+          permission-pull-requests: read
+          permission-workflows: write
 
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
@@ -99,6 +141,8 @@ jobs:
       - uses: megaeth-labs/.github/.github/actions/release-candidate@main
         with:
           stage: cut
-          token: ${{ steps.app-token.outputs.token }}
+          token: ${{ steps.release-token.outputs.token }}
+          commit: ${{ needs.route.outputs.commit }}
+          pr_number: ${{ needs.route.outputs.pr_number }}
           version_file: VERSION
           version_pattern: plain
diff --git a/workflow-templates/release-publish.properties.json b/workflow-templates/release-publish.properties.json
deleted file mode 100644
index 97b82fd..0000000
--- a/workflow-templates/release-publish.properties.json
+++ /dev/null
@@ -1,8 +0,0 @@
-{
-  "name": "Release Publish",
-  "description": "Tag and publish a settled release when its settle PR merges (PR-mode settlement only).",
-  "iconName": "octicon tag",
-  "categories": [
-    "Automation"
-  ]
-}
diff --git a/workflow-templates/release-publish.yml b/workflow-templates/release-publish.yml
deleted file mode 100644
index c71b3e1..0000000
--- a/workflow-templates/release-publish.yml
+++ /dev/null
@@ -1,58 +0,0 @@
-name: Release Publish
-
-# Publishes a settled release when its settle PR merges into the release
-# branch: annotated tag at the merge commit (once) and a GitHub Release with
-# the changelog section as notes. Merging the settle PR is the release approval (the
-# `release-*` branch ruleset requires a reviewed PR), so no environment gate
-# is needed; add the CI app as a bypass actor on the `v*` tag ruleset.
-#
-# This file must exist on the release branch (it does, when the branch is cut
-# from a default branch that has it).
-#
-# Only settlement by PR reaches this workflow. With `settle_mode: direct` in
-# release-settle.yml (the template's default) the settle job publishes
-# itself and nothing here ever fires: the job gate above rejects any settle
-# PR the app did not open.
-#
-# Guide: https://github.com/megaeth-labs/.github/blob/main/.github/actions/RELEASE.md
-
-on:
-  pull_request:
-    types: [closed]
-    branches: ["release-v*"]
-
-permissions:
-  contents: read
-
-jobs:
-  publish:
-    if: >-
-      github.event.pull_request.merged == true &&
-      startsWith(github.event.pull_request.head.ref, 'chore/release-settle-') &&
-      github.event.pull_request.user.login == 'mega-maxwell[bot]'
-    # One publish per release branch: the tag guard and the tag push are two
-    # steps, so a re-run must queue behind a run in flight, never overlap it.
-    # Job-level: other PRs closing on the release branch also start this
-    # workflow, and must not evict a queued publish (one pending per group).
-    concurrency:
-      group: ${{ github.workflow }}-${{ github.event.pull_request.base.ref }}
-      cancel-in-progress: false
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3
-        id: app-token
-        with:
-          client-id: ${{ vars.MEGA_MAXWELL_CLIENT_ID }}
-          private-key: ${{ secrets.MEGA_MAXWELL_PK }}
-
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-        with:
-          fetch-depth: 0
-          persist-credentials: false
-
-      - uses: megaeth-labs/.github/.github/actions/release-publish@main
-        with:
-          token: ${{ steps.app-token.outputs.token }}
-          version_file: VERSION
-          version_pattern: plain
-          changelog_file: CHANGELOG.md
diff --git a/workflow-templates/release-settle.properties.json b/workflow-templates/release-settle.properties.json
index 7376bbd..5755b7c 100644
--- a/workflow-templates/release-settle.properties.json
+++ b/workflow-templates/release-settle.properties.json
@@ -1,6 +1,6 @@
 {
   "name": "Release Settle",
-  "description": "Settle a release candidate: the dispatch is the approval (release environment + admin check); notes, changelog commit, tag and GitHub Release follow.",
+  "description": "Settle a release candidate by PR: a push to release-v* refreshes the settle PR; merging it tags and publishes the GitHub Release. All writes use the release app (mega-gutenberg).",
   "iconName": "octicon tag",
   "categories": [
     "Automation"
diff --git a/workflow-templates/release-settle.yml b/workflow-templates/release-settle.yml
index 8b9bb4e..477fdf7 100644
--- a/workflow-templates/release-settle.yml
+++ b/workflow-templates/release-settle.yml
@@ -1,56 +1,97 @@
 name: Release Settle
 
-# Settle a release candidate. Dispatch from the default branch with the
-# version and the full SHA of the release-branch tip; the shared action
-# verifies it, generates release notes from the commits since the previous
-# tag, commits them to the changelog on the release branch, and publishes:
-# annotated tag at that commit, GitHub Release with the notes.
+# Settle a release candidate by pull request. A push to a `release-v*` branch
+# starts this workflow and `route` decides what the push means:
+#   refresh  the candidate has landed on the release branch: generate release
+#            notes from the commits since the previous tag and open or update
+#            a reviewed `chore/release-settle-vX.Y.Z` PR onto the release
+#            branch with the changelog entry;
+#   publish  that settle PR was just merged: create the annotated tag at the
+#            merge commit and the GitHub Release with the changelog section
+#            as notes.
+# Merging the settle PR is the release decision, so nothing waits for a click
+# on the run. To refresh every eligible release branch by hand, dispatch this
+# workflow (optionally with `version` to refresh just one); it never publishes.
 #
-# The dispatch is the settlement decision, gated by the `release`
-# environment on the job: its required reviewers approve the run before it
-# starts (give the environment a deployment branch policy of the default
-# branch only). The app must be a bypass actor on the release-branch ruleset
-# and on the `v*` tag ruleset. To also restrict who may *start* a settle, set
-# `settlers` on the action (logins and/or `admin`); the default `any` relies
-# on the environment alone.
+# Every write is made by the release GitHub App (mega-gutenberg), whose token
+# is minted only in jobs that run in the `release` environment. Create that
+# environment with a deployment policy of the default branch and `release-v*`
+# branches, and no required reviewers. The app is a bypass actor on the `v*`
+# tag ruleset only; the `release-*` branch ruleset still requires the reviewed
+# settle PR. `route` is read-only and uses the job token.
 #
-# To settle by PR instead — a reviewed `chore/release-settle-vX.Y.Z` PR onto
-# the release branch, tagged by release-publish.yml when it merges — remove
-# `environment:` and `settle_mode` below.
+# This file must exist on the release branch (it does, when the branch is cut
+# from a default branch that has it); a push to the branch runs the copy of
+# the workflow on that branch.
 #
 # Guide: https://github.com/megaeth-labs/.github/blob/main/.github/actions/RELEASE.md
 
 on:
+  push:
+    branches: ["release-v*"]
   workflow_dispatch:
     inputs:
       version:
-        description: "Version to settle (X.Y.Z)"
-        required: true
+        description: "Version to refresh (X.Y.Z); blank: every eligible release branch"
+        required: false
         type: string
-      commit:
-        description: "Full SHA of the release-branch tip being settled"
-        required: true
-        type: string
-
-# One settle per version: two dispatches for the same version would race on
-# the release branch. Queue, never cancel.
-concurrency:
-  group: ${{ github.workflow }}-${{ inputs.version }}
-  cancel-in-progress: false
+        default: ""
 
 permissions:
   contents: read
 
 jobs:
-  settle:
+  # Read-only: classifies the push (or the dispatch) as refresh, publish or skip.
+  route:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      action: ${{ steps.route.outputs.action }}
+      targets: ${{ steps.route.outputs.targets }}
+      release_branch: ${{ steps.route.outputs.release_branch }}
+      commit: ${{ steps.route.outputs.commit }}
+      pr_number: ${{ steps.route.outputs.pr_number }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - id: route
+        uses: megaeth-labs/.github/.github/actions/release-route@main
+        with:
+          kind: settle
+          version: ${{ inputs.version }}
+          version_file: VERSION
+          version_pattern: plain
+
+  refresh:
+    needs: route
+    if: needs.route.outputs.action == 'refresh'
+    strategy:
+      fail-fast: false
+      matrix:
+        target: ${{ fromJSON(needs.route.outputs.targets) }}
+    # One refresh per release branch, queued and never cancelled: two runs
+    # would race on the settle PR branch.
+    concurrency:
+      group: release-settle-refresh-${{ matrix.target.release_branch }}
+      cancel-in-progress: false
     runs-on: ubuntu-latest
     environment: release
     steps:
       - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3
-        id: app-token
+        id: release-token
         with:
-          client-id: ${{ vars.MEGA_MAXWELL_CLIENT_ID }}
-          private-key: ${{ secrets.MEGA_MAXWELL_PK }}
+          client-id: ${{ vars.RELEASE_APP_CLIENT_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+          owner: megaeth-labs
+          repositories: ${{ github.event.repository.name }}
+          permission-contents: write
+          permission-pull-requests: write
+          permission-workflows: write
 
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
@@ -59,11 +100,46 @@ jobs:
 
       - uses: megaeth-labs/.github/.github/actions/release-settle@main
         with:
-          token: ${{ steps.app-token.outputs.token }}
-          version: ${{ inputs.version }}
-          commit: ${{ inputs.commit }}
+          token: ${{ steps.release-token.outputs.token }}
+          version: ${{ matrix.target.version }}
+          commit: ${{ matrix.target.commit }}
+          release_branch: ${{ matrix.target.release_branch }}
+          version_file: VERSION
+          version_pattern: plain
+          changelog_file: CHANGELOG.md
+
+  publish:
+    needs: route
+    if: needs.route.outputs.action == 'publish'
+    # One publish per release branch: the tag guard and the tag push are two
+    # steps, so a re-run must queue behind a run in flight, never overlap it.
+    concurrency:
+      group: release-settle-publish-${{ needs.route.outputs.release_branch }}
+      cancel-in-progress: false
+    runs-on: ubuntu-latest
+    environment: release
+    steps:
+      - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3
+        id: release-token
+        with:
+          client-id: ${{ vars.RELEASE_APP_CLIENT_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+          owner: megaeth-labs
+          repositories: ${{ github.event.repository.name }}
+          permission-contents: write
+          permission-pull-requests: read
+          permission-workflows: write
+
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: megaeth-labs/.github/.github/actions/release-publish@main
+        with:
+          token: ${{ steps.release-token.outputs.token }}
+          commit: ${{ needs.route.outputs.commit }}
+          pr_number: ${{ needs.route.outputs.pr_number }}
           version_file: VERSION
           version_pattern: plain
           changelog_file: CHANGELOG.md
-          settle_mode: direct
-          # settlers: admin   # optional: also require the dispatcher to be an admin (or a listed login)