[Enhancement]: Report missing required checks and behind-base in native PR watches

[kaovilai]

Problem

T3's watch_pull_request lets an agent wait for selected PR events, but it does not cover two signals that CI babysitting workflows rely on. As a result, an agent using T3's native watch may still need a separate monitor or repeated manual polling when a required check never reports, or when a branch drifts behind its base while waiting to merge.

Use case

While working on a PR, an agent needs to monitor CI and keep the user informed across supported Git hosting and CI systems. Examples include a required job that never reports a status (so "all required checks passed" is wrong, or the PR waits forever), or a branch that falls behind its base while waiting to merge.

Requested behavior

Extend native PR watching so a thread can:

• Detect required checks that have not reported any status, including jobs absent from the provider's check/status results when that information is available.
• Report when the PR falls behind its base, in addition to detecting conflicts.

Startup failures, changing checks, rebase state and completion should keep being reported clearly, including for multiple PRs watched at once.

Scope

This request is about making T3's native watch report these two signals for persistent CI babysitting from any supported provider and hosting service. It does not ask the agent to rebase branches automatically or to diagnose CI logs.

Opt-in, restart-safe CI actions (retrying a check, requesting a missing job, retrying a timed-out validation request) were split out into a separate idea: #17712.

Issue #16924 already requests wakeups for every check-state change; this request focuses on missing required statuses and behind-base detection.

Current state (from reading the watch code)

Ask	Today
Failures that already exist when the watch starts	Works. A new watch starts with no failures recorded, so the first pass reports existing ones.
Several PRs watched at once	Works. Each thread/PR pair gets its own wake.
Behind base	Partial. The PR detail already carries a base comparison on some hosts, but the watch never reads it.
Required check that never reports	Missing, and it produces a wrong report: the "passed" gate only looks at checks that reported, so a required check that never appears still yields "all required checks passed".

Proposed plan

Phase 1: required checks that never report

• Add an optional list of expected required check names to the provider's PR detail. A host that cannot say reports null, meaning "unknown" (no behavior change).
• In the watch evaluation, compute missing = expected − reported. While anything is missing, do not report "passed".
• Report a missing check only after a grace period following the head commit, and only once per commit. Persist the head-seen time and the already-reported names in the watch state.
• Edge cases to cover:
  • A check skipped by a path filter never reports and can block merge indefinitely; this is worth surfacing.
  • Rules that match by pattern or app identity rather than name should be treated as unknown, not guessed.
  • Workflows waiting for maintainer approval should not be flagged as missing.
  • Cache the rules lookup per base branch so it does not spend rate limit on every pass.

Phase 2: behind base

• Add a persisted behind flag to the watch state (with a decoding default so already-saved watches still load) and a new change kind in the wake message.
• Avoid noise on busy base branches: where the host distinguishes "behind and blocked" from "has newer upstream commits", only wake on the former, once per head commit. The raw commit count can inform a softer message.
• Treat behind-only wakes like comment-only wakes for the consecutive-wake limit, so they cannot loop an agent.
• Detection delay: a push to the base branch does not change the PR's own fingerprint, so a behind state is noticed on the quiet re-read interval. Either document that or include the base commit in the fingerprint.
• Hosts that cannot answer stay silent.

Tests (written first)

Extend pullRequestWatch.test.ts to cover: a missing required check during and after the grace period, passed being withheld while a check is missing, behind turning on and off and waking once per commit, behind-only wakes counting toward the wake limit, and decoding of watches saved before the new fields.

Note

Responses generated with Codex and Claude

[leomontigatti]

Supporting this with field data from a repo whose agents use watch_pull_request with classic branch protection (strict: true; required: checks, db-gate, docs-gate, actions-gate, pr-title). Implementation in #17831.

Early "required checks passed"

db-gate is a needs: [db-shard] job, so it is absent from the rollup until the four shards finish (~4 min after the others). The watch reported passed on the four contexts it could see, three times on 2026-10-14:

Head	Wake	db-gate started
fd40c21b	~12:43:09Z "All 4 required checks passed"	12:43:32Z
ea9152cd	12:49:16Z	12:49:42Z
15de7a58	~14:03:20Z "All 4 required checks passed"	14:04:26Z

The agent has to re-read branch protection on every wake and run its own gh pr checks --watch to cover the gap.

Behind base

With strict: true, three PRs went BEHIND while being watched (other PRs merging), and none got a wake. The agent only found out by reading mergeStateStatus after an unrelated wake, then ran gh pr update-branch. One PR needed it twice in 10 minutes.

The BEHIND-only signal in #17831 matches this setup. The "hold back passed while a required check is missing" part would remove the early wakes above.

Observed on T3 Code v0.0.46-nightly.20261014.3105 (Linux AppImage, Claude Code provider). Drafted by Claude Opus 5.5 in Claude Code in T3 Code, reviewed and posted by me.