jcdavis131 Event-Driven Wait
Polling asks "is it done yet?" on a timer. Event-driven waiting is woken by the actual signal. Less noise, zero missed ticks, lower token cost.
When event-driven fits
The wait condition must be observable as a change:
- A file or directory appears or grows (
node_modules/appears → install progressed). - A log line matches a pattern ("Build complete", "Listening on :8000").
- A git ref advances (
git rev-parse HEADchanges). - A port opens / an endpoint returns 200.
- A background task emits a known sentinel.
If the condition is "some amount of time passes regardless of state", use a timer (see loop). If the condition is "a specific change happens", use a watcher.
How to arm a watcher
The mechanism depends on the platform, but the shape is constant: watch for the change, emit a sentinel when it fires, set notify_on_output on the sentinel.
- Filesystem event (the install case): a watcher loop that polls the file's existence on a short interval and echoes a sentinel when it appears. The polling is cheap because it's a single existence check, not a full command, and the sentinel only fires once.
- Log line: tail the log with
notify_on_outputmatching the success pattern. - Ref advance: a watcher loop that polls
git rev-parse HEADand echoes a sentinel on change. - Background task: the task's own completion notification is the event — don't re-poll; let the notification wake you.
The sentinel
Unique per wait so unrelated output doesn't trigger it:
AGENT_WAIT_<purpose> {"event":"node_modules appeared","next":"run typecheck"}
On wake, read the payload, act on next.
Why this beats blind polling
- Token cost. Each poll is a turn; a watcher is one arm + one wake. A 10-minute wait polled every 30s = 20 turns; event-driven = 2.
- Precision. You wake at the moment, not up to an interval later.
- No missed ticks. A poll can miss a transient state; a watcher catches the transition.
When NOT to use event-driven wait
Short waits (<30s), non-observable conditions (human approval), silent ops with no event — use timer or silent-op-recovery.
Extended patterns
Named monitors, failure-inclusive events, monitor chains: reference.md
Pair with
silent-op-recovery— the healthy-case counterpart. If the watcher never fires, escalate to silent-op-recovery's interim check, then kill-and-restart.fill-the-wait/persist-learnings— while the watcher is armed, fill the wait with independent work or durable learning.loop— the loop skill's dynamic schedule is the general form of this pattern.