PR Monitoring — Technical Implementation

Server-driven wake loop + a one-call MCP tool. The agent supplies judgment; the server supplies truth.

Plan · July 23, 2026 · v2 — revised after adversarial review by gpt-5.6-sol (Codex) · companion to the UX plan (v2), which fixes terminology, mocks, and decisions D1–D6 · v1→v2 changelog

1 · Architecture in one picture

Monitoring is not an agent that stays alive polling. A dedicated server-side PullRequestMonitor service owns a per-thread monitor registration, polls GitHub on a 30s cadence, and on new actionable events dispatches a normal turn to the thread with a self-contained prompt. Between wakes the thread's session is genuinely idle — zero tokens, no live activity.

2 · Why not a skill / agent-side loop

• T3 Code can't install skills. It only reads them (Claude via settingSources loading worktree .claude/; Codex via the skills/list RPC). Nothing writes skills into worktrees, so a skill-based backbone depends on every repo carrying it.
• Instructions can't drive the UI. The feature's core is the thread knowing it's monitoring — pill, blockers strip, ready state. A skill produces an agent that behaves right while the UI stays blind.
• An agent loop is the fragile thing being replaced. Transcript history shows the improvised version (self-scheduled wakeups, state re-serialized into each prompt) and its failure modes: silent stops, "Are you still going?", a live session burning tokens to do what a 30s poller does for free. A hybrid (agent loops + server watches the watcher) still needs all the server-side polling to detect a dead babysitter — strictly more complexity, no benefit.

The one skill-shaped artifact that survives: the babysitting policy text. It lives server-side as a template injected into every wake turn (§5) — versioned with the product, harness-agnostic, compaction-proof, identical for every harness (no per-harness seasoning in v1).

3 · Components

4 · Step-by-step lifecycle

5 · The wake prompt (where the "skill" actually lives)

Every wake turn is self-contained — no reliance on conversation memory surviving compaction, and identical across harnesses (per-harness seasoning cut in review; the prompt must be sufficient for all providers anyway):

New activity on PR #4412 (monitoring, wake 3/10).

Bugbot commented on src/thread.ts:141: "possible null deref when …"

Status: CI ✓ · Macroscope ✓ · Bugbot ● changes requested · CodeRabbit ○ pending
Head: a41c2f9 (approvals/checks are evaluated against this commit)

Policy:
- Verify bot claims against the source before acting.
- Fix legitimate findings and push.
- Dismiss false positives with a brief reply — never silently ignore or comply.
- For CI failures: compare against main; re-run suspected flakes; if the same
  real failure repeats, ask the user via a question rather than guessing.
- Rebase if the PR is behind main.
- If the goal has become impossible, say so and ask the user.

The PR-creation policy (in the initial-turn instructions and monitor_start's description) still says real PR, never draft — but as agent guidance, not monitoring architecture: the monitor validates PR state and reports "draft" as a blocker instead of assuming.

6 · Invariants (the regression guards)

These exist because of a live bug in today's improvised flow: merge PR → thread settles → monitor sees "something changed" → work restarts → settled thread pops back into the active list. That must be impossible by construction:

7 · Build phases

8 · Explicitly rejected

• Extending ProviderInteractionMode (default | plan) with monitoring — interaction modes are user-preselected UI state; monitoring is agent-initiated mid-conversation. The tool call is the right entry event.
• Parsing agent output to detect monitoring intent — the structured tool call is unambiguous; prose parsing is not.
• Agent-side sleep/poll loops in any form — including "hybrid" (agent loops, server supervises), which still requires all the server-side polling and adds only token burn and a second failure mode.
• Webhooks in v1 — the 30s poller works for local/self-hosted and monitoring latency tolerance is minutes, not seconds.
• Agent self-reporting gate status — server reads GitHub directly (I3).
• cut in v2monitor_stop tool — stop is a UI/domain action; the agent asks the user in prose when stuck. Removes an authorization surface and the completion/impossibility/cancel ambiguity.
• cut in v2Settle-neutral wake turns — monitoring holds the thread unsettled instead (I2); the carve-out touched far more lifecycle machinery than v1 admitted.
• cut in v2monitor.* as ProviderRuntimeEvent — server-owned state uses orchestration domain events; runtime events belong to adapters.
• cut in v2Extending VcsStatusBroadcaster — its pollers are UI-subscriber-refcounted per cwd; a client disconnect would silently kill monitoring. Dedicated service instead.
• cut in v2Server-raised user-input.requested — responses route to a live adapter deferred that wouldn't exist; the breaker ends monitoring with needs-attention instead.
• cut in v2Configurable/editable gates — arbitrary bot-name → login matching is a swamp and invites vacuous or false green; fixed readiness rule in v1, named-bot narrowing revisited in P4.
• cut in v2Per-harness prompt seasoning (Codex developer_instructions branch) — the wake prompt must carry everything for every harness anyway; revisit only if adherence measurably differs.

9 · v1 → v2 changelog (from the gpt-5.6-sol review)

Adversarial review by Codex (gpt-5.6-sol) against the actual codebase; the two highest-impact findings were independently re-verified in source before adopting. Full report: /tmp/codex-review.YtEhdY/report.md.