@deftai/directive-content 0.55.2 → 0.56.0

package/scripts/release_rollback.py

@@ -0,0 +1,980 @@
+#!/usr/bin/env python3
+"""release_rollback.py -- State-aware release unwind (#716, #725).
+
+Companion to ``scripts/release.py`` and ``scripts/release_publish.py``
+per the #716 safety hardening Q3 decision. ``task release:rollback --
+<version>`` performs a state-aware unwind, tailoring its action to one
+of four detected post-release states:
+
++----+----------------------------------------+--------------------------------------------+
+| #  | Detected state                          | Action                                     |
++====+========================================+============================================+
+| 1  | Local commit + tag, no push            | resolve release-prep SHA + git tag -d +    |
+|    |                                        | git revert <sha> --no-edit                 |
+| 2  | Tag pushed, no release                 | resolve release-prep SHA + git push        |
+|    |                                        | --delete origin v* + tag -d +              |
+|    |                                        | git revert <sha> --no-edit + git push      |
+|    |                                        | origin <base> (no force)                   |
+| 3  | Release published, downloads <= guard  | resolve release-prep SHA + gh release      |
+|    |                                        | delete --yes --cleanup-tag + git revert    |
+|    |                                        | <sha> --no-edit + git push origin <base>   |
+|    |                                        | (no force)                                 |
+| 4  | Release published, downloads > guard   | Refuse unless --allow-data-loss; recommend |
+|    |                                        | hot-fix-path (next patch with withdrawal   |
+|    |                                        | note)                                      |
++----+----------------------------------------+--------------------------------------------+
+
+Forward-revert + normal push (#725)
+-----------------------------------
+Prior to #725 the unwind used ``git reset --hard HEAD~1`` and
+``git push --force-with-lease origin <base>``. Both were unsafe:
+
+- ``HEAD~1`` is the wrong target whenever ANY commit lands between
+  release-prep and the rollback invocation (a normal operational
+  scenario -- fix a release defect via PR, then decide to rollback).
+  Live demonstration: PR #722 merged on top of release-prep ``6573335``;
+  ``task release:rollback`` then reset master from ``94d1aa5`` ->
+  ``6573335``, unwinding PR #722 instead of release-prep.
+- ``--force-with-lease`` is rejected by GitHub branch-protection rules
+  that disallow force-push on ``master`` (the default for protected
+  branches), so the rollback aborts after ``gh release delete`` already
+  succeeded -- leaving the operator in a half-rolled-back state.
+
+#725 fix: resolve the actual release-prep commit SHA (``git rev-parse
+v<version>^{commit}`` first; ``git log --grep='^chore(release):
+v<version>'`` fallback) BEFORE the tag is deleted, then run ``git
+revert <sha> --no-edit`` (forward commit, branch-protection-compatible).
+Push is a normal ``git push origin <base>`` (no ``--force``).
+
+Manual recovery on revert conflict
+----------------------------------
+``git revert`` can conflict when an intervening commit touched a file
+the release-prep commit also touched (e.g. CHANGELOG.md / ROADMAP.md
+edited by an out-of-band hot-fix between release-prep and rollback).
+The script aborts the revert (``git revert --abort``) and refuses with
+an operator-readable diagnostic. Manual recovery::
+
+    1. git revert <release-prep-sha> --no-edit  # re-run, observe conflicts
+    2. Resolve conflicts in CHANGELOG.md / ROADMAP.md (or whatever).
+       - Restore the pre-release Unreleased section that the release
+         commit replaced (look for it on the parent commit).
+       - Drop the new ## [<version>] heading.
+    3. git add <resolved-files>
+    4. git revert --continue  # produces the revert commit
+    5. git push origin <base-branch>
+
+The SHA is logged via ``[rollback] Resolve release-prep SHA... OK
+(<sha>)`` so the operator can copy it out of the script's stderr.
+
+Time-windowed download-count guard (Q3)
+---------------------------------------
+The threshold for "low download count" varies with release age::
+
+    release_age = now - release.created_at
+    if release_age < 5_minutes:
+        threshold = 0          # nobody noticed yet; safe
+    elif release_age < 30_minutes:
+        threshold = max(args.allow_low_downloads, 10)  # filter bots
+    else:
+        require(args.allow_data_loss, "release > 30 min old")
+
+Three escape hatches (progressive warnings):
+- ``--allow-low-downloads N`` -- accept up to N downloads
+- ``--allow-data-loss`` -- accept any download count (consumer impact)
+- ``--force-strict-0`` -- override time-window; require exactly 0 regardless
+  of release age (use for security-incident hot-rollbacks)
+
+Race-condition mitigation
+-------------------------
+GitHub's release-asset download_count is eventually-consistent (~30s
+cache staleness). The guard reads ``download_count`` once, sleeps
+5 seconds, reads again; only proceeds if BOTH reads agree below the
+threshold (catches a download arriving between read 1 and the rollback
+action).
+
+Three-state exit codes
+----------------------
+    0 -- rollback completed (or already-clean no-op)
+    1 -- refusal due to guard (downloads > threshold without escape hatch),
+         or step-level failure (gh / git failure during unwind)
+    2 -- config / argument error (malformed version, repo unresolvable, ...)
+
+Refs #725 (HEAD~1 + force-push fix), #716 (canonical spec; safety
+hardening Item 3 of 7), #722 (subprocess PATHEXT fix; release._resolve_gh
+helper), #74 (foundation), #233, #642, #635, #709, #710.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import datetime as _dt
+import json
+import os
+import shutil  # noqa: F401  -- kept for tests that monkeypatch release_rollback.shutil.which
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+# Make sibling scripts importable so we can re-use _resolve_repo /
+# _resolve_project_root / _validate_version + the EXIT_* constants from
+# release.py without duplicating them.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from _stdio_utf8 import reconfigure_stdio  # noqa: E402
+
+reconfigure_stdio()
+
+import release  # noqa: E402
+
+EXIT_OK = release.EXIT_OK
+EXIT_VIOLATION = release.EXIT_VIOLATION
+EXIT_CONFIG_ERROR = release.EXIT_CONFIG_ERROR
+
+# ---- Constants --------------------------------------------------------------
+
+# Download-count guard time windows. Comments use minutes for readability;
+# the constants are seconds so we can compare against `(now - created_at).seconds`.
+_FIVE_MINUTES_SECONDS = 5 * 60
+_THIRTY_MINUTES_SECONDS = 30 * 60
+
+# Default threshold inside the 5-30 minute window (filters bot fetches that
+# typically scrape new releases for indexing).
+_DEFAULT_BOT_THRESHOLD = 10
+
+# Race-condition double-read sleep duration. GitHub's release asset
+# download_count cache typically takes ~30s to invalidate; 5s gives
+# downstream callers a chance to surface a fresh count without
+# meaningfully extending rollback wall-clock time.
+_DOUBLE_READ_SLEEP_SECONDS = 5
+
+
+# ---- Data classes -----------------------------------------------------------
+
+
+@dataclass
+class RollbackConfig:
+    version: str
+    repo: str
+    base_branch: str
+    project_root: Path
+    dry_run: bool
+    allow_low_downloads: int  # 0 = no override
+    allow_data_loss: bool
+    force_strict_0: bool
+    # When True, skip the wall-clock sleep between download_count reads
+    # (used by tests to keep latency negligible without disabling the
+    # double-read semantic).
+    skip_sleep: bool = False
+
+
+# ---- argument parsing -------------------------------------------------------
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="release_rollback",
+        description=(
+            "State-aware release unwind (#716 safety hardening). Detects "
+            "one of four post-release states (local-only / tag-pushed / "
+            "released-low-downloads / released-high-downloads) and applies "
+            "the matching tiered recovery."
+        ),
+    )
+    parser.add_argument(
+        "version",
+        help="Release version, e.g. 0.21.0 (no leading 'v', strict X.Y.Z).",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print the rollback plan without invoking gh / git side-effects.",
+    )
+    parser.add_argument(
+        "--repo",
+        default=None,
+        metavar="OWNER/REPO",
+        help="Override repo (default: resolved from `git remote get-url origin`).",
+    )
+    parser.add_argument(
+        "--base-branch",
+        default=release.DEFAULT_BASE_BRANCH,
+        metavar="BRANCH",
+        help=f"Base branch (default: {release.DEFAULT_BASE_BRANCH}).",
+    )
+    parser.add_argument(
+        "--project-root",
+        type=Path,
+        default=None,
+        metavar="PATH",
+        help="Repository root (default: $DEFT_PROJECT_ROOT or scripts/.. ).",
+    )
+    parser.add_argument(
+        "--allow-low-downloads",
+        type=int,
+        default=0,
+        metavar="N",
+        help=(
+            "Accept up to N downloads (defaults to the time-window-derived "
+            "value). The maximum of this flag and the time-window default "
+            "wins, so passing N=5 with a 10-min-old release still allows up "
+            f"to {_DEFAULT_BOT_THRESHOLD}."
+        ),
+    )
+    parser.add_argument(
+        "--allow-data-loss",
+        action="store_true",
+        help=(
+            "Accept any download count; explicit acknowledgment of consumer "
+            "impact. Required when the release is > 30 minutes old."
+        ),
+    )
+    parser.add_argument(
+        "--force-strict-0",
+        action="store_true",
+        help=(
+            "Override the time-window: require exactly 0 downloads regardless "
+            "of release age. Use for security-incident hot-rollbacks where "
+            "even bot scrapes are unacceptable."
+        ),
+    )
+    return parser
+
+
+# ---- gh helpers -------------------------------------------------------------
+
+
+def _gh_release_view_json(version: str, repo: str) -> tuple[bool, dict | None, str]:
+    """Fetch full release metadata as JSON; returns (ok, payload, reason).
+
+    Includes ``createdAt`` and the ``assets[]`` array (each with
+    ``downloadCount``). Used by the guard logic.
+    """
+    gh_path = release._resolve_gh()
+    if gh_path is None:
+        return False, None, "gh CLI not found on PATH"
+    tag = f"v{version}"
+    cmd = [
+        gh_path, "release", "view", tag,
+        "--repo", repo,
+        "--json", "isDraft,name,tagName,createdAt,publishedAt,assets,url",
+    ]
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=60,
+            check=False,
+            env=os.environ.copy(),
+        )
+    except FileNotFoundError:
+        return False, None, "gh CLI not found on PATH"
+    if result.returncode != 0:
+        stderr = (result.stderr or "").strip()
+        return False, None, stderr
+    try:
+        return True, json.loads(result.stdout), ""
+    except json.JSONDecodeError as exc:
+        return False, None, f"non-JSON: {exc}"
+
+
+def gh_release_exists(version: str, repo: str) -> tuple[str, dict | None, str]:
+    """Returns ('exists', payload, '') / ('not-found', None, '...') / ('error', None, '...')."""
+    ok, payload, reason = _gh_release_view_json(version, repo)
+    if ok:
+        return "exists", payload, ""
+    lowered = reason.lower()
+    if "not found" in lowered:
+        return "not-found", None, reason
+    return "error", None, reason
+
+
+def gh_release_delete(version: str, repo: str) -> tuple[bool, str]:
+    gh_path = release._resolve_gh()
+    if gh_path is None:
+        return False, "gh CLI not found on PATH"
+    tag = f"v{version}"
+    cmd = [
+        gh_path, "release", "delete", tag,
+        "--repo", repo,
+        "--yes",
+        "--cleanup-tag",
+    ]
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=60,
+            check=False,
+            env=os.environ.copy(),
+        )
+    except FileNotFoundError:
+        return False, "gh CLI not found on PATH"
+    if result.returncode != 0:
+        return False, f"gh release delete failed: {result.stderr.strip()}"
+    return True, f"deleted release {tag} (with tag cleanup)"
+
+
+# ---- git helpers ------------------------------------------------------------
+
+
+def git_tag_exists_local(project_root: Path, version: str) -> bool:
+    tag = f"v{version}"
+    result = release._run_git(project_root, "tag", "-l", tag)
+    return bool(result.stdout.strip())
+
+
+def git_tag_exists_origin(project_root: Path, version: str) -> bool:
+    tag = f"v{version}"
+    result = release._run_git(
+        project_root, "ls-remote", "--tags", "origin", f"refs/tags/{tag}"
+    )
+    return bool(result.stdout.strip())
+
+
+def git_delete_local_tag(project_root: Path, version: str) -> tuple[bool, str]:
+    tag = f"v{version}"
+    result = release._run_git(project_root, "tag", "-d", tag)
+    if result.returncode != 0:
+        return False, f"git tag -d failed: {result.stderr.strip()}"
+    return True, f"deleted local tag {tag}"
+
+
+def git_delete_remote_tag(project_root: Path, version: str) -> tuple[bool, str]:
+    tag = f"v{version}"
+    result = release._run_git(
+        project_root, "push", "--delete", "origin", tag
+    )
+    if result.returncode != 0:
+        return False, f"git push --delete failed: {result.stderr.strip()}"
+    return True, f"deleted remote tag {tag}"
+
+
+# Subject prefix for the auto-generated release-prep commit. Mirrors
+# `scripts/release.py::_release_commit_subject` but kept as a private
+# constant here so resolve_release_prep_sha does not have to import the
+# subject-builder helper at module scope (release.py is already imported
+# above for shared helpers; this avoids creating a tighter coupling).
+_RELEASE_COMMIT_SUBJECT_PREFIX = "chore(release): v"
+
+
+def resolve_release_prep_sha(
+    project_root: Path, version: str
+) -> tuple[str, str]:
+    """Resolve the release-prep commit SHA for ``v<version>`` (#725).
+
+    Returns ``(sha, reason)``. ``sha`` is the empty string when neither
+    probe resolves; ``reason`` carries a one-line operator-readable
+    diagnostic (empty on success).
+
+    Probe order:
+
+    1. ``git rev-parse v<version>^{commit}`` -- works whenever the local
+       tag still points at the release-prep commit (states 1, 2, and 3
+       BEFORE ``gh release delete --cleanup-tag`` removes the remote
+       ref; callers MUST resolve before the tag is deleted).
+    2. ``git log --grep='^chore(release): v<version>' --format=%H -n 1``
+       -- fallback that walks back from HEAD looking for the canonical
+       release-commit subject. Useful when the tag is missing (e.g. the
+       operator deleted it manually before invoking the rollback).
+
+    The pre-#725 implementation used ``git reset --hard HEAD~1`` which
+    silently picked the wrong commit whenever ANY commit landed between
+    release-prep and rollback (a normal operational scenario). #725
+    replaces that with this resolved-SHA helper + a forward ``git
+    revert`` so the unwind targets the right commit regardless of
+    intervening history.
+    """
+    tag = f"v{version}"
+    rev_parse = release._run_git(
+        project_root, "rev-parse", f"{tag}^{{commit}}"
+    )
+    if rev_parse.returncode == 0:
+        sha = (rev_parse.stdout or "").strip()
+        if sha:
+            return sha, ""
+
+    # Fallback: --grep walks back from HEAD looking for the canonical
+    # release-commit subject (see scripts/release.py::_release_commit_subject).
+    grep_pattern = f"^{_RELEASE_COMMIT_SUBJECT_PREFIX}{version}"
+    grep = release._run_git(
+        project_root,
+        "log",
+        "--grep",
+        grep_pattern,
+        "--format=%H",
+        "-n",
+        "1",
+    )
+    if grep.returncode == 0:
+        # Single strip + splitlines; the pre-#720 form ran .strip() twice
+        # with diverging condition vs. value expressions which Greptile
+        # flagged as confusing on PR #728.
+        lines = (grep.stdout or "").strip().splitlines()
+        if lines:
+            sha = lines[0]
+            if sha:
+                return sha, ""
+
+    return "", (
+        f"could not resolve release-prep SHA for v{version} "
+        f"(tried `git rev-parse {tag}^{{commit}}` and "
+        f"`git log --grep={grep_pattern!r}`)"
+    )
+
+
+def git_revert_release_commit(
+    project_root: Path, release_prep_sha: str
+) -> tuple[bool, str]:
+    """Forward-revert the release-prep commit (#725).
+
+    Runs ``git revert <release_prep_sha> --no-edit``. On conflict (revert
+    cannot apply cleanly because an intervening commit touched the same
+    files), runs ``git revert --abort`` to restore a clean working tree
+    and returns ``(False, manual-recovery hint)`` so the caller can
+    refuse the rollback rather than leave the operator in a half-applied
+    state. The hint points at the Manual recovery section in the module
+    docstring.
+
+    Replaces the pre-#725 ``git reset --hard HEAD~1`` flow which (a)
+    silently unwound the wrong commit when intervening commits existed
+    and (b) required a force-push to land on origin (rejected by GitHub
+    branch-protection rules disallowing force-push). The forward revert
+    is auditable, branch-protection-compatible, and safe across
+    intervening history.
+    """
+    result = release._run_git(
+        project_root, "revert", release_prep_sha, "--no-edit"
+    )
+    if result.returncode == 0:
+        return True, (
+            f"reverted release-prep commit {release_prep_sha[:12]} "
+            f"(forward revert; no force-push required)"
+        )
+    # Conflict path: abort the in-progress revert so the working tree is
+    # clean for the operator's manual recovery, then refuse with a
+    # diagnostic + pointer to the script docstring.
+    abort = release._run_git(project_root, "revert", "--abort")
+    abort_note = ""
+    if abort.returncode != 0:
+        abort_note = (
+            f" (additionally, `git revert --abort` failed: "
+            f"{abort.stderr.strip()})"
+        )
+    stderr = (result.stderr or "").strip()
+    return False, (
+        f"git revert {release_prep_sha[:12]} conflicted: {stderr}{abort_note}. "
+        f"Manual recovery: re-run `git revert {release_prep_sha} --no-edit`, "
+        f"resolve conflicts (typically CHANGELOG.md / ROADMAP.md), "
+        f"`git revert --continue`, then `git push origin <base-branch>`. "
+        f"See the Manual recovery section in scripts/release_rollback.py."
+    )
+
+
+def git_push_base(
+    project_root: Path, base_branch: str
+) -> tuple[bool, str]:
+    """Push the (revert-augmented) base branch to origin (#725).
+
+    Forward-only push: ``git push origin <base_branch>`` with NO
+    ``--force`` / ``--force-with-lease``. Compatible with GitHub
+    branch-protection rules that disallow force-push on ``master``
+    (the default for protected branches), so the rollback flow lands
+    end-to-end on a protected default branch instead of failing the
+    second-to-last step like the pre-#725 force-with-lease path did.
+    """
+    result = release._run_git(project_root, "push", "origin", base_branch)
+    if result.returncode != 0:
+        return False, f"git push failed: {result.stderr.strip()}"
+    return True, f"pushed {base_branch} to origin (no force)"
+
+
+# ---- guard logic ------------------------------------------------------------
+
+
+def _sum_downloads(payload: dict) -> int:
+    """Sum the ``downloadCount`` across all assets in a release payload."""
+    assets = payload.get("assets", []) or []
+    total = 0
+    for asset in assets:
+        # gh returns the field as ``downloadCount`` (camelCase under --json).
+        count = asset.get("downloadCount", 0)
+        with contextlib.suppress(TypeError, ValueError):
+            total += int(count)
+    return total
+
+
+def _release_age_seconds(payload: dict, *, now: _dt.datetime | None = None) -> int:
+    """Age of the release in seconds, derived from ``createdAt``.
+
+    Returns 0 when the timestamp cannot be parsed (which lets the
+    "release age < 5 min" branch evaluate True so the strict-0 default
+    threshold applies -- safe-by-default).
+    """
+    created_at = payload.get("createdAt") or payload.get("publishedAt")
+    if not created_at:
+        return 0
+    try:
+        # gh ISO-8601 with trailing Z; Python 3.11 accepts a trailing 'Z'
+        # via fromisoformat as long as we strip it manually for older.
+        if created_at.endswith("Z"):
+            created_at = created_at[:-1] + "+00:00"
+        dt = _dt.datetime.fromisoformat(created_at)
+    except ValueError:
+        return 0
+    now = now or _dt.datetime.now(_dt.UTC)
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=_dt.UTC)
+    delta = now - dt
+    return max(0, int(delta.total_seconds()))
+
+
+def compute_threshold(
+    age_seconds: int,
+    *,
+    allow_low_downloads: int,
+    allow_data_loss: bool,
+    force_strict_0: bool,
+) -> tuple[int | None, str]:
+    """Compute the maximum acceptable download count given the time window.
+
+    Returns ``(threshold, reason)`` where:
+
+    - ``threshold`` is an int (the count below or equal to which rollback is
+      permitted), or ``None`` if rollback is unconditionally refused at the
+      time-window level (the operator must pass ``--allow-data-loss``).
+    - ``reason`` is a one-line operator-readable explanation.
+
+    ``--force-strict-0`` short-circuits the time window and always returns
+    threshold=0; ``--allow-data-loss`` accepts any download count.
+    """
+    if force_strict_0:
+        return 0, "--force-strict-0 override (require exactly 0 downloads)"
+    if allow_data_loss:
+        # int(2**31 - 1) avoids overflow surprises on 32-bit pickle paths.
+        return 2**31 - 1, "--allow-data-loss override (accept any count)"
+    if age_seconds < _FIVE_MINUTES_SECONDS:
+        return 0, "release age < 5 min; threshold=0 (rollback safe)"
+    if age_seconds < _THIRTY_MINUTES_SECONDS:
+        threshold = max(allow_low_downloads, _DEFAULT_BOT_THRESHOLD)
+        return threshold, (
+            f"release age 5-30 min; threshold={threshold} "
+            f"(filters bot fetches; --allow-low-downloads={allow_low_downloads})"
+        )
+    # 30+ minutes old: refuse without --allow-data-loss.
+    return None, (
+        "release age > 30 min; downloads likely consumer-driven. "
+        "Pass --allow-data-loss to acknowledge consumer impact, OR "
+        "abandon rollback in favour of a hot-fix release with a "
+        "withdrawal note in the next CHANGELOG entry."
+    )
+
+
+def double_read_downloads(
+    version: str, repo: str, *, sleep_seconds: int = _DOUBLE_READ_SLEEP_SECONDS
+) -> tuple[bool, int, int, str]:
+    """Read ``download_count`` twice with a sleep between; require agreement.
+
+    Returns ``(ok, first_count, second_count, reason)``.
+
+    ``ok`` is True when both reads succeed AND ``second_count <=
+    first_count`` (a count cannot legitimately decrease over a 5-second
+    window without manual intervention; any decrease signals a stale
+    cache and rollback should re-read). Otherwise ``ok`` is False and
+    ``reason`` carries the diagnostic.
+
+    Tests that want to skip the wall-clock sleep can pass
+    ``sleep_seconds=0`` (the double-read semantic still applies).
+    """
+    ok1, payload1, reason1 = _gh_release_view_json(version, repo)
+    if not ok1 or payload1 is None:
+        return False, 0, 0, f"first read failed: {reason1}"
+    first_count = _sum_downloads(payload1)
+    if sleep_seconds > 0:
+        time.sleep(sleep_seconds)
+    ok2, payload2, reason2 = _gh_release_view_json(version, repo)
+    if not ok2 or payload2 is None:
+        return False, first_count, 0, f"second read failed: {reason2}"
+    second_count = _sum_downloads(payload2)
+    if second_count > first_count:
+        return False, first_count, second_count, (
+            f"download_count grew between reads ({first_count} -> "
+            f"{second_count}); a real consumer downloaded the asset during "
+            "the rollback window. Re-run with the new count visible."
+        )
+    return True, first_count, second_count, ""
+
+
+# ---- state detection --------------------------------------------------------
+
+
+def detect_state(
+    config: RollbackConfig,
+) -> tuple[str, dict | None, str]:
+    """Return the post-release state for ``v<version>``.
+
+    States:
+      - ``"local-only"`` -- local commit + tag, NOT pushed to origin
+      - ``"tag-pushed-no-release"`` -- tag exists on origin, no GH release
+      - ``"released"`` -- GH release exists; payload returned
+      - ``"absent"`` -- nothing to roll back (no local tag, no remote tag,
+        no release)
+      - ``"error"`` -- gh / git probe failed; reason carries diagnostic
+    """
+    project_root = config.project_root
+    version = config.version
+    repo = config.repo
+
+    # First check whether a GH release exists; if so, return early with the
+    # payload so the caller has the assets[] array for guard evaluation.
+    state, payload, reason = gh_release_exists(version, repo)
+    if state == "exists":
+        return "released", payload, ""
+    if state == "error":
+        # gh probe failed; surface the error so the caller can refuse rather
+        # than guess at local/remote state.
+        return "error", None, reason
+
+    # No GH release. Probe local + remote tag.
+    local = git_tag_exists_local(project_root, version)
+    remote = git_tag_exists_origin(project_root, version)
+    if remote:
+        return "tag-pushed-no-release", None, ""
+    if local:
+        return "local-only", None, ""
+    return "absent", None, ""
+
+
+# ---- pipeline ---------------------------------------------------------------
+
+
+def _emit(label: str, status: str) -> None:
+    print(f"[rollback] {label}... {status}", file=sys.stderr)
+
+
+def _resolve_prep_sha_or_emit(
+    config: RollbackConfig,
+) -> tuple[str, int | None]:
+    """Resolve the release-prep SHA and emit a status line.
+
+    Returns ``(sha, exit_code)``. ``exit_code`` is None on success (the
+    caller proceeds with the SHA); when the probe fails it is
+    ``EXIT_VIOLATION`` so the caller can ``return rc`` immediately
+    without a separate emit. Used by every unwind branch (states 1, 2,
+    3) to capture the SHA BEFORE any tag deletion (which would make
+    rev-parse fail) -- centralised here so the per-state code stays
+    short and the resolution-then-refuse semantics are consistent.
+    """
+    sha, reason = resolve_release_prep_sha(config.project_root, config.version)
+    if not sha:
+        _emit(f"Resolve release-prep SHA for v{config.version}", f"FAIL ({reason})")
+        return "", EXIT_VIOLATION
+    _emit(
+        f"Resolve release-prep SHA for v{config.version}",
+        f"OK ({sha})",
+    )
+    return sha, None
+
+
+def _unwind_local(config: RollbackConfig) -> int:
+    """State 1: local commit + tag, no push.
+
+    Pre-#725 used ``git tag -d`` + ``git reset --hard HEAD~1``. #725
+    replaces the reset with a resolved-SHA forward revert so the
+    unwind targets the release-prep commit even when the operator made
+    additional local commits on top. No push is required (state 1
+    means nothing has been pushed).
+    """
+    project_root = config.project_root
+    version = config.version
+    if config.dry_run:
+        _emit(
+            f"Unwind local v{version}",
+            (
+                f"DRYRUN (would resolve release-prep SHA + run "
+                f"`git tag -d v{version}` + `git revert <sha> --no-edit`)"
+            ),
+        )
+        return EXIT_OK
+    # Resolve BEFORE deleting the tag (rev-parse depends on the tag).
+    sha, refusal = _resolve_prep_sha_or_emit(config)
+    if refusal is not None:
+        return refusal
+    ok, reason = git_delete_local_tag(project_root, version)
+    if not ok:
+        _emit(f"Delete local tag v{version}", f"FAIL ({reason})")
+        return EXIT_VIOLATION
+    _emit(f"Delete local tag v{version}", f"OK ({reason})")
+    ok, reason = git_revert_release_commit(project_root, sha)
+    if not ok:
+        _emit(f"Revert release-prep commit {sha[:12]}", f"FAIL ({reason})")
+        return EXIT_VIOLATION
+    _emit(f"Revert release-prep commit {sha[:12]}", f"OK ({reason})")
+    return EXIT_OK
+
+
+def _unwind_tag_pushed_no_release(config: RollbackConfig) -> int:
+    """State 2: tag pushed, no release.
+
+    Pre-#725 deleted both tag refs, reset --hard HEAD~1, and force-pushed.
+    #725 deletes both tag refs, runs a forward revert against the resolved
+    release-prep SHA, then pushes normally (no force) so the flow is safe
+    across intervening commits and compatible with branch protection.
+    """
+    project_root = config.project_root
+    version = config.version
+    base_branch = config.base_branch
+    if config.dry_run:
+        _emit(
+            f"Unwind pushed tag v{version}",
+            (
+                f"DRYRUN (would resolve release-prep SHA + run "
+                f"`git push --delete origin v{version}` + "
+                f"`git tag -d v{version}` + `git revert <sha> --no-edit` + "
+                f"`git push origin {base_branch}` (no force))"
+            ),
+        )
+        return EXIT_OK
+
+    # Resolve BEFORE deleting either tag ref (rev-parse depends on the tag).
+    sha, refusal = _resolve_prep_sha_or_emit(config)
+    if refusal is not None:
+        return refusal
+
+    ok, reason = git_delete_remote_tag(project_root, version)
+    if not ok:
+        _emit(f"Delete remote tag v{version}", f"FAIL ({reason})")
+        return EXIT_VIOLATION
+    _emit(f"Delete remote tag v{version}", f"OK ({reason})")
+
+    if git_tag_exists_local(project_root, version):
+        ok, reason = git_delete_local_tag(project_root, version)
+        if not ok:
+            _emit(f"Delete local tag v{version}", f"FAIL ({reason})")
+            return EXIT_VIOLATION
+        _emit(f"Delete local tag v{version}", f"OK ({reason})")
+
+    ok, reason = git_revert_release_commit(project_root, sha)
+    if not ok:
+        _emit(f"Revert release-prep commit {sha[:12]}", f"FAIL ({reason})")
+        return EXIT_VIOLATION
+    _emit(f"Revert release-prep commit {sha[:12]}", f"OK ({reason})")
+
+    # Forward push (no --force / --force-with-lease). Compatible with GitHub
+    # branch-protection rules disallowing force-push (#725).
+    ok, reason = git_push_base(project_root, base_branch)
+    if not ok:
+        _emit(f"Push {base_branch} to origin", f"FAIL ({reason})")
+        return EXIT_VIOLATION
+    _emit(f"Push {base_branch} to origin", f"OK ({reason})")
+    return EXIT_OK
+
+
+def _unwind_released(
+    config: RollbackConfig, payload: dict
+) -> int:
+    """States 3 & 4: GitHub release exists. Apply guard, then unwind."""
+    project_root = config.project_root
+    version = config.version
+    repo = config.repo
+
+    age_seconds = _release_age_seconds(payload)
+    threshold, threshold_reason = compute_threshold(
+        age_seconds,
+        allow_low_downloads=config.allow_low_downloads,
+        allow_data_loss=config.allow_data_loss,
+        force_strict_0=config.force_strict_0,
+    )
+    _emit(
+        f"Compute guard threshold (age={age_seconds}s)",
+        threshold_reason,
+    )
+    if threshold is None:
+        # Time-window refusal (release > 30 min old, no escape hatch).
+        _emit(
+            "Guard refusal",
+            "FAIL (release > 30 min old without --allow-data-loss; "
+            "see hot-fix-path recommendation in script docstring)",
+        )
+        return EXIT_VIOLATION
+
+    if config.dry_run:
+        _emit(
+            f"Double-read download_count (threshold={threshold})",
+            "DRYRUN (would read download_count, sleep 5s, re-read)",
+        )
+        _emit(
+            f"Delete release v{version}",
+            f"DRYRUN (would run `gh release delete v{version} --yes --cleanup-tag`)",
+        )
+        _emit(
+            f"Revert release-prep commit for v{version}",
+            (
+                f"DRYRUN (would resolve release-prep SHA + run "
+                f"`git revert <sha> --no-edit` + `git push origin "
+                f"{config.base_branch}` (no force))"
+            ),
+        )
+        return EXIT_OK
+
+    # Resolve the release-prep SHA BEFORE `gh release delete --cleanup-tag`
+    # removes the remote tag (rev-parse uses the local tag, which is still
+    # present at this point because the operator pushed but has not yet
+    # rolled back). Capturing here also defends against the local tag
+    # being inadvertently cleaned up by the gh call (some gh versions
+    # update local refs as well as remote).
+    sha, refusal = _resolve_prep_sha_or_emit(config)
+    if refusal is not None:
+        return refusal
+
+    sleep_seconds = 0 if config.skip_sleep else _DOUBLE_READ_SLEEP_SECONDS
+    ok, first_count, second_count, reason = double_read_downloads(
+        version, repo, sleep_seconds=sleep_seconds
+    )
+    _emit(
+        f"Double-read download_count (threshold={threshold})",
+        f"first={first_count}, second={second_count}, ok={ok}; reason: {reason or 'agreed'}",
+    )
+    if not ok:
+        # Race: download arrived during read window. Refuse so the operator
+        # re-runs with the fresh count visible.
+        return EXIT_VIOLATION
+    if max(first_count, second_count) > threshold:
+        _emit(
+            "Guard refusal",
+            (
+                f"FAIL (download_count={max(first_count, second_count)} > "
+                f"threshold={threshold}; pass --allow-low-downloads or "
+                f"--allow-data-loss to override)"
+            ),
+        )
+        return EXIT_VIOLATION
+
+    # Guard passed: delete the release (with cleanup-tag) and unwind the commit.
+    ok, reason = gh_release_delete(version, repo)
+    if not ok:
+        _emit(f"Delete release v{version}", f"FAIL ({reason})")
+        return EXIT_VIOLATION
+    _emit(f"Delete release v{version}", f"OK ({reason})")
+
+    # Tag deletion is handled by --cleanup-tag in the gh delete call; we
+    # don't need a separate `git push --delete`. Local tag may still
+    # exist (gh deletes only the remote ref); clean it up if present.
+    if git_tag_exists_local(project_root, version):
+        ok, reason = git_delete_local_tag(project_root, version)
+        if not ok:
+            _emit(f"Delete local tag v{version}", f"WARN ({reason})")
+        else:
+            _emit(f"Delete local tag v{version}", f"OK ({reason})")
+
+    ok, reason = git_revert_release_commit(project_root, sha)
+    if not ok:
+        _emit(f"Revert release-prep commit {sha[:12]}", f"FAIL ({reason})")
+        return EXIT_VIOLATION
+    _emit(f"Revert release-prep commit {sha[:12]}", f"OK ({reason})")
+
+    # Forward push (no --force / --force-with-lease). Compatible with GitHub
+    # branch-protection rules disallowing force-push (#725).
+    ok, reason = git_push_base(project_root, config.base_branch)
+    if not ok:
+        _emit(f"Push {config.base_branch} to origin", f"FAIL ({reason})")
+        return EXIT_VIOLATION
+    _emit(f"Push {config.base_branch} to origin", f"OK ({reason})")
+
+    return EXIT_OK
+
+
+def run_rollback(config: RollbackConfig) -> int:
+    """Execute the rollback pipeline; returns the process exit code."""
+    if config.dry_run:
+        _emit(
+            "Detect post-release state",
+            f"DRYRUN (would probe gh release view v{config.version} + "
+            f"git tag -l + git ls-remote)",
+        )
+        # In dry-run, we still need a state to exercise the right branch.
+        # Default to "released" so the dry-run output covers the most
+        # complex path (the others print as DRYRUN inside their own
+        # branches as well; if the operator wants a specific branch they
+        # can run the script live).
+        # However, if we can probe live state (gh + git available), do so
+        # and report the actual branch. Otherwise fall back to the
+        # most-complex branch.
+        state, payload, reason = detect_state(config)
+        _emit("State (dry-run probe)", f"{state} ({reason or 'no reason'})")
+        if state == "absent":
+            _emit("Rollback", "DRYRUN (no-op; nothing to unwind)")
+            return EXIT_OK
+        if state == "local-only":
+            return _unwind_local(config)
+        if state == "tag-pushed-no-release":
+            return _unwind_tag_pushed_no_release(config)
+        if state == "released" and payload is not None:
+            return _unwind_released(config, payload)
+        if state == "error":
+            _emit("State probe", f"FAIL ({reason})")
+            return EXIT_VIOLATION
+        # Fallback for unknown state (shouldn't happen): no-op.
+        return EXIT_OK
+
+    state, payload, reason = detect_state(config)
+    _emit("Detect post-release state", f"{state} ({reason or 'ok'})")
+    if state == "absent":
+        _emit("Rollback", "NOOP (no local tag, no remote tag, no release)")
+        return EXIT_OK
+    if state == "error":
+        return EXIT_VIOLATION
+    if state == "local-only":
+        return _unwind_local(config)
+    if state == "tag-pushed-no-release":
+        return _unwind_tag_pushed_no_release(config)
+    if state == "released":
+        assert payload is not None
+        return _unwind_released(config, payload)
+    # Unknown state: refuse rather than guess.
+    _emit("Rollback", f"FAIL (unknown state {state!r})")
+    return EXIT_VIOLATION
+
+
+# ---- main -------------------------------------------------------------------
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        release._validate_version(args.version)
+    except ValueError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return EXIT_CONFIG_ERROR
+
+    project_root = release._resolve_project_root(args.project_root)
+    repo = release._resolve_repo(args.repo, project_root)
+
+    if args.allow_low_downloads < 0:
+        print(
+            f"Error: --allow-low-downloads must be >= 0 (got {args.allow_low_downloads}).",
+            file=sys.stderr,
+        )
+        return EXIT_CONFIG_ERROR
+
+    config = RollbackConfig(
+        version=args.version,
+        repo=repo,
+        base_branch=args.base_branch,
+        project_root=project_root,
+        dry_run=args.dry_run,
+        allow_low_downloads=args.allow_low_downloads,
+        allow_data_loss=args.allow_data_loss,
+        force_strict_0=args.force_strict_0,
+    )
+    return run_rollback(config)
+
+
+if __name__ == "__main__":
+    sys.exit(main())