DOCS · CLI
ALL DOCS FIG. 15 · DWG VC-015

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:

PathWhat it holds
~/.vibecrafted/control_plane/runs/<id>.jsonrun 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/*.loglauncher 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:

  1. The await verdict — the dispatcher socket woke await and the file triad produced a terminal verdict for the run id.
  2. Terminal state in run meta — the run record shows a terminal state (completed, failed), not active or stalled.
  3. 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 — await fails 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.