Add durable GitHub waitpoints to orchestration V2

[Jules-Astier]

Summary

• expose provider-agnostic wait_for_github, list_github_waits, and cancel_github_wait tools through the orchestration V2 MCP toolkit
• persist PR baselines, deadlines, delivery prompts, and fenced delivery leases in SQLite
• run a restart-safe local worker through the authenticated gh CLI, without T3 Connect, a GitHub App, or a public endpoint
• wake the originating V2 thread through normal queued delivery with deterministic command and message IDs
• expire waits when their originating run is interrupted or the thread advances before the trigger

Closes #4266.

Delivery semantics

wait_for_github registers an idempotent one-shot wait and returns immediately so the agent can end its current turn. The server watches for checks to settle, new review activity, or PR closure. When the condition fires, it queues a normal V2 continuation and the existing UI projections show the thread running again.

Delivery claims carry random fencing tokens. The observed continuation prompt is persisted before dispatch, and an expired delivery lease retries the same deterministic V2 command without re-probing GitHub or invalidating itself because the continuation advanced the thread.

Verification

• 20 focused tests covering contracts, migration continuity/schema, GitHub normalization and conditions, idempotent persistence, lease fencing, crash recovery, interrupted-run expiry, MCP registration, and tool metadata
• @t3tools/contracts and server TypeScript checks
• targeted formatting and lint checks for the changed files

Intentional limitations

• local authenticated gh polling rather than webhook delivery
• the local T3 server must eventually run to observe and deliver a trigger
• no bespoke sidebar waiting state in this milestone

Stack note

This draft is based directly on #2829's orchestration V2 branch so its diff contains only the waitpoint feature. After #2829 merges, this branch will be rebased and the PR retargeted to main before review.

Built with gpt-5.6-sol (high reasoning) in T3 Code via the Codex harness.

Note

Add durable GitHub waitpoints to orchestration V2 with polling, lease fencing, and MCP tools

• Introduces a full GitHub waitpoint lifecycle: register with a baseline PR snapshot, poll via GitHubPullRequestProbe (using gh pr view), evaluate conditions (checks_settled, new_review_activity, pull_request_closed), and deliver a continuation prompt to the originating thread.
• Adds GitHubWaitpointStore backed by a new github_waitpoints table (migration 45) with delivery lease fencing to prevent duplicate delivery from concurrent workers.
• Adds GitHubWaitpointService with a background worker that polls due waitpoints every 5 seconds, expires waitpoints when the originating run is interrupted, and uses deterministic IDs for idempotent delivery.
• Exposes three new MCP tools via OrchestratorMcpService: wait_for_github, list_github_waits, and cancel_github_wait, with input validation (repository format, timeout ≤ 10080 min) and a githubWaitpoints capability flag.
• Risk: the background poller adds a GitHub CLI subprocess call per due waitpoint every 5 seconds; no rate-limiting or backoff is described beyond the fixed schedule.

📊 Macroscope summarized 25ff158. 13 files reviewed, 0 issues evaluated, 0 issues filtered, 0 comments posted

🗂️ Filtered Issues

No issues evaluated.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: dd78d8da-e8e4-4c09-9d51-bae69d6f2a1c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Effect service conventions review of the new apps/server/src/github/** service modules and their call sites. Three findings, all in the new durable GitHub waitpoint services.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

One convention finding in the follow-up fix commit: the register:reload invariant failure now manufactures an Error purely to satisfy the required cause field. Everything else in this commit (inlined Context.Service interfaces, GitHubWaitpointService["Service"]["get"], and store-error passthrough) matches the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Three new Effect service modules inline their construction directly into Layer.effect(...) instead of exporting a make. The convention for a module that owns construction is imports → errors/schemas → Context.Service tag → export const make → export const layer = Layer.effect(Tag, make), which is also what the rest of apps/server/src does (e.g. sourceControl/GitHubCli.ts, orchestration-v2/ThreadLifecycleService.ts, checkpointing/CheckpointStore.ts). Everything else in the waitpoint code looks consistent with the conventions: inline service interfaces, Foo["Service"] references, namespace imports from effect/* subpaths and local service modules, structured Schema.TaggedErrorClass failures with real causes, and store errors that pass an existing domain error through instead of re-wrapping it.

^{Posted via Macroscope — Effect Service Conventions}