dots wait

dots wait [options] <condition> [target...]

The blocking session primitive. One invocation blocks until the named condition occurs, prints the occurrence through the ordinary --format pipeline, and exits. Every wait runs under a deadline, so no invocation blocks forever: --timeout sets it in seconds, DOTS_WAIT_TIMEOUT_MS sets it in whole milliseconds for a caller that spawns the CLI under its own wall budget, and without either the wait stops after 600 seconds. A deadline expiry exits non-zero naming what it was waiting on; the condition itself is unaffected, and re-running with a larger --timeout keeps waiting.

An agent uses this instead of a sleep-and-recheck loop: the command holds the wait server-side where a stream exists and polls with bounded backoff where none does, so the session wakes the moment the condition occurs rather than on the next polling tick.

Arguments:

• <condition> — What to wait for: job, notification, presence, or onboarding-run. An unknown condition is a typed usage error naming the four, never an open-ended block.
• [target...] — The condition's target: the execution UUID for job, the <dotabase-slug> <rowHumanId> pair for presence; notification and onboarding-run take none.

Options:

• --timeout <seconds> — Give up after this many seconds and exit non-zero; the condition is not affected. DOTS_WAIT_TIMEOUT_MS sets the same deadline in whole milliseconds. Without either, the wait stops after 600 seconds.
• --after <id> — Resume from this event id: an occurrence between invocations is replayed instead of missed. Only the replay-capable stream conditions (notification, onboarding-run) accept it.

Conditions

The transport splits by what the server carries. Three conditions each hold one of the origin-root SSE streams open; the job condition polls, because no server stream carries job events.

Job

dots wait job <executionId> --timeout 120

Polls the durable job execution named by the UUID (from dots jobs run or dots jobs list) until it reaches a terminal status — completed, partial, failed, or cancelled — and prints the terminal execution whole, result and error included. The poll backs off from half a second to a five-second ceiling, each sleep clamped to the time the deadline has left. The same bounded poll backs dots jobs run --wait, whose --wait-timeout <seconds> flag carries the identical precedence: flag, then DOTS_WAIT_TIMEOUT_MS, then the 600-second default.

Notification

dots wait notification --after <notificationId>

Holds the global notification stream open and resolves on the next notification created for this actor, printing the notification and its event id. Read, dismissed, and updated frames are cross-tab synchronization, not occurrences, and do not resolve the wait. Pass the last seen notification id as --after and one created while nothing was listening is replayed immediately instead of being missed.

Presence

dots wait presence <dotabase-slug> <rowHumanId>

Holds the row-presence stream for one row open and resolves once the live roster names an active session besides this wait's own connection — a collaborator arriving on the row, or one already there when the wait began. Presence is ephemeral who-is-here state with no event ids, so this condition carries no --after.

Onboarding-Run

dots wait onboarding-run --after <eventId>

Holds the onboarding run stream open and resolves on the next run event for this actor, printing the run id, sequence number, and event payload. The stream replays the actor's latest run on connect, so without --after the wait resolves on the first replayed event; with --after naming the last seen event id, only what follows it resolves the wait.

Exemption

dots wait is CLI-only and carries no MCP twin, named-exempt under the streaming axis: it blocks holding an open stream, and a stdio tool call cannot hold a stream. Every other family is listed in CLI Reference.