Watches & Callbacks

Stop sleeping, start waiting

An agent waiting on a CI run has had one option: sleep in a loop and check again. That costs a process and a terminal for as long as the wait lasts, it dies without a word if the pane dies, and nothing survives a daemon restart — so the agent waits forever for something that will never arrive.

A watch is the durable replacement. The agent says what it is waiting for, stops, and Grove delivers the outcome as ordinary mail when it settles.

Before and after

The difference is who does the waiting. Today the agent waits, and a watch hands the waiting to Grove.

flowchart TB
    subgraph today["Today: the agent waits"]
        direction LR
        A1["sleep 60"] --> A2["Check CI"]
        A2 -->|"still running"| A1
        A2 -->|"done"| A3["Continue"]
        A2 -->|"pane dies,<br/>CI hangs"| A4["Silence"]
    end
    subgraph watch["With a watch: Grove waits"]
        direction LR
        B1["Register,<br/>end the turn"] --> B2["Grove<br/>checks CI"]
        B2 -->|"finished"| B3["Mail: the result"]
        B2 -->|"deadline"| B4["Mail: not met"]
    end
    today ~~~ watch

	A sleep loop today	A watch
While it waits	The agent holds a turn, a process and a pane, and every check costs tokens	The turn has ended. One scheduler for the whole host does the checking
If CI hangs	The loop runs until somebody notices	The deadline passes and the agent is told the condition was not met
If the pane or daemon restarts	The loop dies and the result is lost	The watch is saved to disk and picks up where it left off
When it settles	Only a loop that is still running sees it	The result arrives as mail, even in an idle session
Many agents waiting	Each one adds its own process and polling	They share one timer, so waiting is free

How it behaves

Register a watch and end the turn. When the thing settles, the callback arrives through the mailbox and the agent picks up where it left off.
If the deadline passes first, the expiry is delivered too — so stopping is always safe. There is no case where an agent halts and hears nothing back, which is the guarantee a sleep loop cannot make.
The callback is a self-contained message, not a ping. It may reach a fresh turn with no memory of the registration, so it carries what happened and where to look.
One scheduler serves the whole host. Nothing runs while nothing is due, and a hundred pending watches cost one timer between them — waiting is free.
A watch outlives a restart. The registry is durable, and recovered watches re-arm spread across their interval rather than all firing at once.

What you can wait for

Predicate	Settles when	Typical use
`ci`	Every check on a commit has concluded	A pushed branch before opening a PR
`timer`	A wall-clock instant arrives	A durable `sleep`
`cmd`	A command exits with a status you name	Anything Grove does not model
`ticket`	Never: it reports each change and keeps watching	Registered by Grove for you, below

Changes to your attached tickets

Attach an issue or pull request to a running workspace, and Grove tells the agent whenever a person changes it:

A new title, a close, reopen or merge, a draft marked ready, an edited description, or a new comment arrives as one message listing each change.
Nobody registers this, and it lasts exactly as long as the workspace runs. Detaching the ticket, or pausing or killing the workspace, stops it.
Grove's own writes never count. Its status comment, its badge footer, its assignment and anything its bot account posts are left out of what is compared, so its progress updates cannot wake the agent in a loop.
Each ticket is read at most once a minute, however many workspaces are attached to it. The status comment reuses the same read.
The Watches card in the web dashboard lists each ticket watch as "Watching while the workspace runs", and grove watch ls shows them too.

ci is keyed on the commit SHA, never a branch name: a force-push makes a different commit, and a watch that followed the name would answer about work nobody asked about.

Using it

grove watch ci <commit-sha> --owner <owner> --repo <repo> --deadline 45
grove watch timer 20
grove watch cmd -- <command>
grove watch ls
grove watch cancel <id>

Over MCP the same three verbs are grove_register_watch, grove_list_watches and grove_cancel_watch. The recipient defaults to the calling workspace, read from GROVE_PHASE_FILE, exactly as the mailbox does — so an agent registers for itself without knowing its own id.

What a callback does and does not say

A delivered callback means Grove handed the message to that session's transport. It is not evidence that a model read it or acted on it — the same contract every mailbox receipt carries.

A ticket watch stays pending for as long as its workspace runs, and ends cancelled when the ticket is detached or the workspace pauses or ends. Every other watch ends in one of four states: fired (it settled and the callback went out), expired (the deadline came first), cancelled (withdrawn), or undeliverable (it settled, but the recipient was no longer live to be told). grove watch ls shows all of them, including recently settled ones, because that record is also what stops a restart from delivering the same callback twice.

Limits

Checks run at most every 15 seconds. A faster interval is refused: nothing real settles quicker, and a fleet of impatient watches is a rate-limit incident on somebody else's forge.
Every watch an agent waits on has a deadline, and the agent chooses it — up to a day. A ticket watch has none, because nobody waits on it. When it passes, the agent is messaged that the condition was not met, so no watch can leave a session stalled.
With no deadline set, ci and cmd give up after 15 minutes; a timer defaults to its own time. Pass --deadline for anything you expect to take longer, such as a full CI run.
A failure to reach a forge is never read as a result. "I could not tell" and "it failed" are different answers, and only the second one is ever delivered.