event-driven-wait

---
name: event-driven-wait
description: When waiting on a specific observable event — a file appearing, a log line matching, a git ref advancing, a directory growing, a port opening — arm a watcher that wakes on that event instead of polling on a timer. Use when the wait condition is observable as a filesystem, log, or ref change, especially for long waits where blind polling wastes tokens and can miss the moment.
license: MIT
---

# 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 HEAD` changes).
- 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_output` matching the success pattern.
- **Ref advance**: a watcher loop that polls `git rev-parse HEAD` and 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](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.