Watch a GitHub Actions workflow run (e.g. a post-merge deploy) like watch_pull_request

[X2Borgo]

Before submitting

• I searched existing issues, PRs and discussions and did not find a duplicate.
• I am describing a concrete problem or use case, not just a vague idea.

Area

apps/server (MCP pullRequests toolkit, orchestration-v2 watch reactor), packages/contracts.

Problem or use case

watch_pull_request wakes an agent when a PR's checks finish, someone comments, or the branch conflicts. Very often the next thing an agent has to wait for is a GitHub Actions workflow run that no open PR owns. The usual case is the Deploy run that workflow_run fires after a PR merges to main. Today agents fall back to a background shell helper that polls gh run view. That means the wait runs outside T3, depends on the provider supporting background shells, and isn't visible as a T3 watch.

Job results matter, not just the run conclusion. A deploy run often concludes success while its actual deploy job was skipped, for example because of a path filter or a failed condition. An agent that only sees "success" will tell the user it's live when it isn't.

Proposed solution

Add a sibling pair to watch_pull_request / unwatch_pull_request:

• watch_workflow_run { run: <run URL | owner/repo + run id> }, or { repo, headSha, workflow } to resolve a run that may not exist yet (e.g. the post-merge deploy).
• unwatch_workflow_run { ... }

It would use the same wake mechanism and lifecycle as the PR watch (the reactor, one wake per state change, cleared when the thread settles or on unwatch). It wakes the thread once, when the run concludes, with:

• the run's conclusion and URL
• a per-job list of name: conclusion, so skipped jobs are explicit

Resolving by SHA + workflow name covers the gap between "PR merged" and "deploy run created".

Smallest useful scope

GitHub only (the PR layer now uses the GitHub API directly, #16320). Watching by run ID/URL, with a single wake on completion. Resolution by SHA + workflow name can follow if you'd rather keep v1 tiny.

Current workaround

A background gh run watch / polling script in the agent's shell, plus a manual check that the deploy job didn't skip.

Related: #14072 (marking a thread as waiting on outside work). A run watch would be one concrete source of that state.

I'm happy to implement this if the direction and scope are approved.

[BenWortley]

One more data point. I audited a month of Claude Code and Codex sessions on my machine (6 Sep to 7 Oct). Agents wrote 25 separate watchers for a single workflow run, mostly the tests run on main after a merge. Each was a gh run watch or an until gh run view …; sleep loop written from scratch. 12 of them hid gh errors, and 2 stopped at their own time limit without saying so.

Resolving by head SHA, workflow and event matters here. Of the 4 loops that looked up a run by commit, only 1 filtered by event, so the others could pick a pull_request run on the same commit instead of the push run. The per-job results you describe would also make a skipped job visible.