feat(guard): require a bounded timeout-minutes on every required-context job (#398)

[avrabe]

Closes #398.

The problem

A required status check that hangs is not a wrong-green — it is an indefinite merge block with no signal. A wedged job leaves its context at Expected — waiting for status to be reported, which is byte-identical to "still running", and a job with no timeout-minutes inherits GitHub's 360-minute default before anything cancels it. For up to six hours the PR is unmergeable for a reason nobody can see, the job holds a self-hosted runner, and — branch protection is strict = true — every other open PR queues behind it. Detect changed paths is the sharpest case: it gates ten of the other jobs, so wedging it stalls the entire suite.

Measured against the live required set: 15 of the 18 required contexts declared no timeout-minutes. The 3 that did: Mutation Testing (240), Verification Gate (60), Lean typecheck (90).

What this does

1. A guard — tools/check_job_timeouts.py. A sibling of check_required_contexts.py that reuses its restricted, PyYAML---cross-checked workflow reader rather than copying it. Every GATEABLE job — exactly the set that gate proves must be required — must declare a timeout-minutes that is a static integer in the open interval (0, 360):

• missing → the defect (inherits the 360 default);
• ${{ … }} template → not a static bound a reader can evaluate;
• <= 0 → not a number of minutes;
• >= 360 → no tighter than the default it replaces, so it buys nothing.

Advisory (continue-on-error) and undeliverable (path-scoped) jobs are out of scope — they can't block a merge. The scan fails closed: zero gateable jobs found, or a glob that misses .yaml, is a blind read, not a PASS.

The check_required_contexts.py reader is extended (additively) to capture timeout-minutes; --self-test and --cross-check on it still pass.

2. The 15 missing values, sized to a few multiples of each job's observed p95 (cold-cache worst case), cited per-job in the workflow comments:

jobs	timeout
Detect changed paths (×2), Format, Cargo Deny, Supply Chain	5
Security Audit (RustSec)	15
Test, Proptest, Bench compile smoke, Code Coverage, Miri, Fuzz smoke	30
Clippy, Rivet validate	45
Codegen compile oracle	60

Durations were read from recent CI run history (2 main runs + 1 PR run). This does not try to machine-check that the values are well-sized — that's a human judgement; the gate only draws the line that isn't one: an unbounded (or uselessly-bounded) required job must not ship.

Oracle (executed, non-vacuous)

tools/check_job_timeouts.py --self-test — a 9-row decision table plus two production-corpus assertions — runs before the gate, as a step of the rivet-validate job (same steps-of-this-job rationale as the sibling: a new job would itself be gateable and need admin-token branch-protection sync).

• Distinct inputs → distinct verdicts: valid → 0, missing/templated/zero/non-integer/>=360 → 1, 359 → 0, advisory/undeliverable with no timeout → 0.
• Fails closed on a blind scan (zero gateable / glob misses .yaml).
• Demonstrated live: against the pre-change tree the check exits 1 naming all 15 unbounded contexts; against this branch it exits 0 with "18 gateable job(s)".

An independent clean-room pass re-derived the 15/18 numbers, proved non-vacuity by sabotaging validate_timeout (self-test then fails), and checked the PROVEN-vs-ASSUMED honesty — no over-claim found.

Honest scoping

PROVEN: every job backing a required context declares a static bound in (0, 360), and the gate fails closed on a missing/templated/degenerate bound and on a blind scan.
ASSUMED (not proven here): that the chosen minute values are correctly sized; that GitHub actually cancels at the declared minute (runtime, not exercised); that the GATEABLE set equals the branch-protection-enforced set (the admin-token gap check_required_contexts.py states and this inherits).
NOT claimed: that advisory jobs are bounded — a hung continue-on-error job wastes a runner but can't wedge the merge gate; left to a successor.

Tracked as REQ-GUARD-CONTEXT-TIMEOUT-001 / TEST-GUARD-CONTEXT-TIMEOUT (real steps + satisfies/verifies links). rivet validate: 0 broken cross-refs.

🤖 Generated with Claude Code

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[github-actions]

Rivet verification gate

✅ 20/20 passed

	count
Passed	20
Failed	0
Skipped (no steps)	0

Filter: (and (= type "feature") (or (has-tag "v093") (has-tag "v0100")))

Failed artifacts

(none)

_{Updated automatically by tools/post_verification_comment.py. Source of truth: artifacts/verification.yaml.}