hive-forge: document ci-rerun --pr's event-type gap on PR status

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

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;