Guides

Wake an agent when CI or a review lands on its PR

Status: Stable for local-gh and webhook

An agent that opens a PR and then just sits there idle wastes a turn: CI takes minutes, a human review can take hours. A sentinel is a persisted watch that waits for a GitHub event - a check finishing, a review landing, the PR closing - and delivers it straight into the owning session's inbox, re-prompting the session so it can act on the result without a human polling gh pr checks on its behalf.

This guide covers the local-gh provider end to end - zero infrastructure - then the webhook and agentpush providers, then what sentinels don't do. To add a provider for another system, see Write a sentinel provider.

End to end

  1. An agent opens a PR. Whether it ran gh pr create itself (via command_execute) or a reconciler later discovers the PR it opened, the daemon records it against the session.

  2. The daemon auto-watches it - no action needed. On a newly recorded PR, the daemon creates a sentinel for the owning session automatically: match: github:owner/repo#N with the default PR type set, until: subject_terminal (expires when the PR closes or merges), delivered back at next-turn urgency. This is agentproto sentinel watch pr running itself, not something you call.

    This auto-watch is gated by (in order):

    • Per-spawn opt-out. agent_start's sentinel: false disables it for that one session, regardless of the daemon config.
    • config.sentinel.autoWatchPrs. Unset, it defaults to true only when local-gh is usable (the host's gh CLI is authenticated) - otherwise false, logged once. Set it explicitly to override the probe:
      agentproto config set sentinel.autoWatchPrs true
      Takes effect on the next PR a session opens - no daemon restart.
    • config.sentinel.autoWatchUrgency. The urgency the auto-created sentinel delivers at: fyi, next-turn (default), steer or interrupt.
      agentproto config set sentinel.autoWatchUrgency fyi

    Only PRs a session is known to have created are auto-watched. A PR url that merely appears in a session's output (a supervisor reporting a child's PR, say) is recorded for provenance but never auto-watched.

    You can also watch a PR (or any subject) by hand - see sentinel.md:

    agentproto sentinel watch pr https://github.com/owner/repo/pull/42 --session sess_abc123
  3. local-gh polls. Every 15-60 seconds (faster right after recent activity, slower once a sentinel's been quiet for 10+ minutes), the daemon diffs the PR's state over the host's already-authenticated gh CLI - no credentials to configure, no public URL, no webhook to manage. It produces events for: a check suite completing, a new commit pushed, a review submitted, the PR closing or merging. (It does not poll comments - see Providers.)

  4. CI finishes, or a review lands. The next poll sees the state change and emits a matching event.

  5. The owning session is re-prompted. The event lands in the session's inbox as a notice message at the sentinel's configured urgency (next-turn by default) - if the session is idle, this starts a fresh turn; if it's mid-turn, the notice queues behind it. The agent sees something like [github] Check suite failure for owner/repo#42 with the structured event data attached, and can act on it (fix the failing check, respond to review comments, merge) in the same session that opened the PR

    • no new session, no lost context.

    If the session already exited (crashed, or was resumable but torn down), the daemon resumes it via the same path inbound-router.ts uses for any other inbound message before delivering. A session closed on purpose (done/abandoned) is never resumed - the notice instead goes to its live parent at fyi urgency, or is parked if there's no live parent.

    Parked events are not lost: the daemon retries them once the sentinel's target becomes reachable again - when the sentinel is retargeted to a live session, when that session registers, or on a later poll if an unchanged target starts accepting delivery. Each successfully redelivered event is dropped from sentinels-parked.jsonl, so it is not sent twice. Events parked only because their PR/issue had already closed are never replayed.

    Superseded commits. After a push, GitHub keeps reporting the CI that ran on the previous head (a check_suite or workflow_run completing minutes later). From the pull_request events it sees, the sentinel keeps each PR's current head and the commits it replaced (a push's before sha, and any previously recorded head). A CI event for one of those replaced commits is delivered marked instead of as-is: data.stale: true, data.current_head_sha, a [superseded] prefix on the summary, and fyi urgency, so it never wakes the session and never ends the watch. It is not dropped: the agent can still read it. A CI event for a commit the sentinel has never seen (for example the new head, when its CI result beats the push event) is delivered unchanged, so a real failure is never demoted. Heads are learned before the sentinel's types filter, so the webhook provider tracks them even when types omits pull_request.*; an agentpush sentinel only receives the types it subscribes to, so keep a github.pull_request.* type (the default set has synchronize) or nothing is marked. local-gh only ever reports the current head.

Listing, stopping, expiry

agentproto sentinel list                 # every sentinel the daemon knows about
agentproto sentinel status sen_01ABC...  # one sentinel's full detail
agentproto sentinel rm sen_01ABC...      # stop and remove it

A sentinel created with until: closed (the default for watch pr, and for the PR auto-watch) expires on its own once the PR reaches a terminal state

  • merged or closed - no rm needed. A sentinel watching a raw subject defaults to until: never (the caller presumably wants rm to be the only way out).

Expiry is checked on every poll, on every delivery, and swept periodically on daemon boot and while running - an expired sentinel's provider-side watch is torn down and it's flipped to status: expired (still visible in sentinel list, no longer polled).

Full reference, including every flag: sentinel.md.

Push providers: webhook and agentpush

  • webhook (in daily use: when a stable public URL and a hook-capable gh token are configured, the automatic auto:pr#N sentinels pick it over local-gh; a quick tunnel is public but not stable, so it is not picked) - near-real-time push via a GitHub repo webhook, instead of polling. Needs a public URL for the daemon (a named tunnel via tunnel.md, or the AGENTPROTO_PUBLIC_URL environment variable) and a gh token scoped admin:repo_hook (or write:repo_hook / repo) to create the hook. Without both, readiness() reports why and sentinel watch --provider webhook fails with the specific fix needed rather than silently falling back.

  • agentpush - a hosted durable subscription: agentpush queues matching events server-side, so they survive the daemon being offline, and can push to the daemon or be polled. Needs an agentpush workspace API key, set up via the setup_sentinel_provider MCP tool (not reachable through this CLI's --provider flag directly - once configured, auto-selection picks it over webhook/local-gh automatically). It's a separate, paid hosted service, not something the daemon runs itself. Experimental: no real usage yet.

With neither configured, --provider omitted always resolves to local-gh.

  • webhook target - a sentinel can also deliver matching events as signed HTTP POSTs to a callback URL instead of into a session's inbox. This is a different thing from the webhook provider above. The signature scheme, secret rotation, callback verification, SSRF rules, retry schedule and persisted outbox are in the Sentinel webhook target reference.

What it doesn't do

  • No backfill. A sentinel only sees events from the moment it's created onward - it does not retroactively discover a review or check that already finished before the watch started.
  • local-gh doesn't watch comments. github.issue_comment.created is in the default PR type set but local-gh doesn't produce it - add webhook or agentpush for comment events.
  • It delivers, it doesn't decide. A sentinel's job ends at landing the event in the session's inbox at the requested urgency. Whether that starts a new turn immediately, queues, or just sits in the inbox as fyi is ordinary inbox-delivery behaviour, not something sentinels add on top.
  • A deliberately closed session is never resumed to receive an event - the notice is rerouted to a live parent (if any) instead, never silently dropped, but also never forces a closed session back open.
  • No non-GitHub external source built in. The built-in providers watch GitHub subjects and this daemon's own sessions (session:<id>); there's no built-in sentinel for, say, a CI system that isn't GitHub Actions reporting through GitHub's check-run API. A package can add one: see Write a sentinel provider.

To wake a session on what other sessions do (turn ends, exits, crashes, PRs opened/merged) rather than on GitHub events, see session-follow.