From 62ee57123d37b68fbdcca1f7eb3e667fa4d72beb Mon Sep 17 00:00:00 2001
From: damocles <damocles@hyperhive.local>
Date: Wed, 19 Aug 2026 01:59:22 +0200
Subject: [PATCH] hive-forge: document ci-rerun --pr's event-type gap on PR
 status

---
 docs/ci.md                       | 16 ++++++++++++++++
 hive-forge/src/verbs/ci_rerun.rs |  4 +++-
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/docs/ci.md b/docs/ci.md
index 6c6e4e2e..6db8cafc 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -45,6 +45,22 @@ blocks merge.
 `hive-forge ci-rerun --pr N` dispatches a `workflow_dispatch` retrigger
 without an empty commit.
 
+**`ci-rerun --pr` verifies the code but does not reliably move the PR's own
+status checks.** Measured directly (raw `GET /repos/.../actions/tasks`
+JSON): a genuine PR-triggered run carries `event: pull_request` with the
+`#<n>` pseudo-ref as its `head_branch`; a `ci-rerun --pr`-dispatched run
+carries `event: workflow_dispatch` with the real branch name instead.
+Forgejo's PR commit-status tracking appears scoped to `pull_request`-event
+runs specifically, so a dispatched run — even a genuinely successful one —
+never writes to that status slot. Reproduced with three dispatches on one
+PR over 20+ minutes, all genuinely green, the PR's own status unmoved
+throughout. There is no known token-accessible way around this — the
+actual "rerun" web-UI button reruns the *same* run under the *same* event
+type, but is CSRF-gated (see `ci_rerun.rs`'s own doc comment for why the
+dispatch API is used instead). **Always re-check `pr-status` after a
+dispatch and believe what it says; only a new commit is guaranteed to move
+a stuck context.**
+
 ### Running checks locally
 
 Don't run `nix flake check` directly — it dispatches to the shared build farm and
diff --git a/hive-forge/src/verbs/ci_rerun.rs b/hive-forge/src/verbs/ci_rerun.rs
index db038425..00a822de 100644
--- a/hive-forge/src/verbs/ci_rerun.rs
+++ b/hive-forge/src/verbs/ci_rerun.rs
@@ -25,7 +25,9 @@
 //!   `artifact-get`) and dispatches the SAME workflow on the SAME ref the
 //!   run used (the run record's `prettyref` + `workflow_id`).
 //!
-//! Dispatch re-runs the whole workflow, so there is no single-job variant.
+//! Dispatch re-runs the whole workflow (no single-job variant). ⚠️ `--pr`
+//! verifies the code but doesn't reliably move the PR's own status
+//! checks — see `docs/ci.md`'s "CI checks" for why; re-check `pr-status`.
 
 use anyhow::{Context as _, Result, bail};
 use clap::Args as ClapArgs;