Following Runs: Observe and Await
How to follow dispatched runs with observe and await, where run truth lives on disk, and the three-signal rule for declaring a run finished.
Canonical source — docs/public/cli/observe-await.md
Following Runs: Observe and Await
Every dispatch creates a run in the control plane, identified by a run id
such as impl-<timestamp>-<id> or scaf-<timestamp>-<id>. The run — not the
terminal tab, not the process — is the unit of truth. Two verbs follow it:
observe reads what a run produced; await blocks until it lands. observe
may read through vc-server. await subscribes to the dispatcher-owned Unix
stream for that run; it does not start a private filesystem poller and does
not require vc-server for wake delivery.
The two verbs
vibecrafted observe <agent> --last # watch the last run live
vibecrafted observe <agent> --run-id <id> # watch a specific run live
vibecrafted observe <agent> --run-id <id> --tail 30 # one-shot: last 30 lines
vibecrafted observe <agent> --run-id <id> --head 30 # one-shot: first 30 lines
vibecrafted await <agent> --last # wait for the last run
vibecrafted await <agent> --run-id <id> # wait for a specific run
Arm await immediately after dispatching — supervisor-side, before doing
anything else with the run:
vibecrafted implement codex --prompt "Ship <task>"
vibecrafted await codex --run-id impl-<timestamp>-<id>
Bare observe is a live watch — the default mode. It prints the run status
and a short rendered backlog, then follows appended transcript events
(rendered through the agent’s stream parser, so per-token streams coalesce
into sentences) until the run turns terminal. Exit code is 0 when the run
terminates in a success state, 1 on a terminal failure; Ctrl-C detaches and
never touches the run. --interval SECONDS sets the poll cadence (default
1.0); --watch names the default explicitly. --tail [N] and --head [N]
are the bounded one-shot reads (N defaults to 40). With --json, one-shot
reads add a transcript_tail/transcript_head array to the observation
payload, and the watch emits one JSON event per rendered line
(vibecrafted.observe-event.v1) between begin and terminal markers
(vibecrafted.observe-watch.v1). observe never creates an await monitor.
await connects to the one dispatcher Unix
stream for that run id. Twenty CLI clients still share that one socket:
heartbeats and the terminal line fan out to every connected awaiter, and a
late client receives the last event replay while the dispatcher is up. Files
remain the durable triad; the socket only wakes.
--timeout is an idle window, not a wall-clock deadline. It resets while
the dispatcher stream moves or qualified worker ownership remains live. Use
--hard-cap when the caller needs an absolute bound:
vibecrafted await codex --run-id <id> --timeout 25 --hard-cap 120
JSON names the two outcomes separately as idle_stall and hard_cap. Human
output uses the same names. await is control_plane.await_run over the
dispatcher socket. A missing, refused, or broken socket is a wake that reads
the file triad once — it is not permission to poll, and it is not a
requirement to start vc-server. Dashboards may still use the server HTTP
/await projection; that eye is optional and is not the CLI wake path.
Do not hedge await with manual sleep/poll/process monitors. If you feel the
need to double-guard it, that is a bug report against the runtime contract,
not a supervision pattern.
Run ids, transcripts, and reports
On-disk truth, when the CLI is not enough:
| Path | What it holds |
|---|---|
~/.vibecrafted/control_plane/runs/<id>.json | run state, liveness, exit code |
~/.vibecrafted/control_plane/runs/archive/ | settled runs |
~/.vibecrafted/control_plane/runtime_runs/<id>/ | transcript.log and runtime artifacts |
~/.vibecrafted/control_plane/launches/*.log | launcher stderr — first stop for silent deaths |
~/.vibecrafted/artifacts/<org>/<repo>/<date>/ | plans, briefs, reports |
Reports carry YAML frontmatter (run_id, agent, skill, status, claim
fields) — the same contract documented in
Briefs and reports.
Liveness: the three-signal rule
Declaring a run finished is always a multi-signal decision, because any single channel can lie: a worker can die without writing a report, metadata can lag a completed worker, and an exit code alone proves nothing about delivery.
Before declaring a run done, reconcile:
- The await verdict — the dispatcher socket woke
awaitand the file triad produced a terminal verdict for the run id. - Terminal state in run meta — the run record shows a terminal state
(
completed,failed), notactiveorstalled. - Qualified process truth — PID, PGID, start token, command identity and run id agree, or the canonical PGID contains a child explicitly owned by that run. PID existence alone is never enough.
When a report path was promised, add a fourth check: the report file exists and is non-empty.
Two agreeing signals justify cautious next steps or recovery. Three are
required to declare done. Any disagreement means: treat the run as live and
re-arm await.
Reading the signals
# 1. await verdict
vibecrafted await codex --run-id impl-<timestamp>-<id>
# 2. run meta terminal state
cat ~/.vibecrafted/control_plane/runs/impl-<timestamp>-<id>.json
# 3. report delivered and non-empty
vibecrafted observe codex --run-id impl-<timestamp>-<id> --tail
Failure signatures worth knowing:
- Startup death: transcript under a few KB and silent for minutes — the
worker died near launch. Check
launches/*.log, then stop and refire the same brief; briefs are idempotent. - Mid-flight death: transcript frozen, pid gone — stop and refire; the run record stays as evidence.
- Evidence disagreement: canonical state and current qualified process
evidence disagree —
awaitfails closed and names the disagreement; neither the dispatcher socket nor the optional server projection fabricates settlement.
Settled runs
Finished runs settle into the f · x · n ledger (finalized / failed /
needs-attention). Query it read-only:
vibecrafted settlements summary
vibecrafted settlements inspect <run_id>
A worker’s own status: completed claim is triangulated against exit code,
report, and transcript — contradictions land in needs-attention rather than
being trusted. See Commands for the full settlements
surface and vc-frame for the dashboard projection of the
same truth.