friction: bound exact-head hosted CI setup starvation

[ll7]

Archetype Metadata

archetype: workflow
evidence_tier: smoke
linked_policy:
  - docs/dev/worktree_lifecycle.md
  - docs/code_review.md
  - docs/dev/agents/relocated-agents-guidance.md

Goal / Problem

Bounded exact-head CI monitoring currently reports a hosted run as in_progress while its jobs are
stuck in environment setup beyond the repository's starvation warning, without a failure or a
deterministic recovery handoff. On 2026-09-04, PR #8413 head
6d2c3fb09cff6097e1d0756e16606481a452682d had 27 successful checks, while fast-feedback (2) and
exact-repeat-model-preflight remained in Set up CI Python environment for more than 15 minutes;
watch_pr_ci_status.py emitted actions_gate_age and suggested inspection, but the review loop had
to classify the state manually.

The expected behavior is an explicit, fail-closed hosted-runner handoff that distinguishes setup
starvation from a normal active check, preserves the exact head/base, and never treats the run as
green or silently cancels/retries it.

Scope

• In scope:
  • identify the canonical CI watcher/status owner and define a stable setup-starvation result;
  • add deterministic fixtures for jobs stuck in setup, ordinary in-progress jobs, completed
    failures, and completed successes;
  • report the exact affected job/run, age threshold, head SHA, and a bounded operator action;
  • document that cancellation/rerun requires explicit authorization and that merge admission stays
    blocked until a fresh exact-head success.
• Out of scope:
  • changing branch protection or required-check policy;
  • automatic cancellation, retry, or replacement of hosted runs;
  • weakening CI, merge-ready, current-base CAS, or research/domain gates;
  • treating fallback/degraded execution as success evidence.
• Entry points: the repository's existing CI status watcher and its focused developer-tool tests.

Added Value Estimation

• User value: high for autonomous review loops; a stalled hosted job becomes an actionable handoff.
• Benchmark value: protects benchmark and research PRs from being mistaken for complete proof.
• Maintenance value: medium; removes repeated manual interpretation of the same status shape.
• Why now: the exact-head fix(tooling): validate slow-test capture inputs (#8053) #8413 review encountered this state while all source and local proof were
  already complete.

Effort Estimation

• Rough estimate (hours): 2–4
• Best estimate (hours): 3
• Unknowns: whether the stable contract belongs in the watcher, CI status helper, or both.

Complexity Estimation

• Implementation complexity: low to medium
• Dependencies: GitHub Actions job status payloads and existing watcher fixtures.
• Open questions: whether GitHub exposes a reliable setup-step timestamp across all required jobs.

Risk Assessment

• Functional risk: a false starvation classification could cause premature handoff.
• Compatibility risk: status payloads differ between queued, setup, and runner-assigned jobs.
• Rollout risk: a new non-success status could be misread as a CI failure by callers.
• Mitigation: preserve the current fail-closed pending semantics, add fixture coverage, and expose
  diagnostics without mutating or bypassing the run.

Affected Files

• scripts/dev/watch_pr_ci_status.py or its canonical status-owner module — bounded classification.
• tests/dev/ — deterministic status-payload regression coverage.
• Review/CI guidance only if the implementation changes the operator handoff contract.

Definition of Done

• Setup starvation is distinguishable from ordinary in-progress status using a documented
  threshold and exact run/job evidence.
• The watcher remains fail-closed: starvation is never reported as success or merge-ready.
• Tests cover setup-stalled, ordinary pending, failed, and successful job payloads.
• Output identifies the exact head and a bounded next action without issuing cancellation/rerun.
• Focused tests, Ruff/format, and the repository readiness gate pass.

Success Metrics

• A reproducible setup-stalled fixture emits one stable handoff classification.
• A normal in-progress fixture remains pending and is not mislabeled as starvation.
• Review tooling can preserve the exact-head blocker without manual interpretation.

Validation / Testing

• Add or extend deterministic watcher tests with captured status payloads.
• Run the focused watcher/status suite and static checks.
• Run the canonical readiness gate from a clean linked worktree.
• Verify no GitHub run or branch state is mutated by the diagnostic path.

Estimate Discussion

• Why these values were proposed: the repository already emits the age warning; the likely change is
  classification plus fixture coverage rather than a new CI subsystem.
• Uncertainty / confidence: 70%; the main uncertainty is the stable boundary between queue delay and
  runner setup delay in GitHub's payload.
• What evidence would move the estimate: two or more captured setup-stall payloads across workflows.

Project Metadata

• Priority: unassigned pending triage
• Effort (h): 3
• Reviewed: no