# `pipelines wait`: block until runs finish, then report them ## What this item changed A new read-only CLI command, `pipelines wait [run-id ...]`, in `internal/cli/`. The harness that runs the operator's work resumes a session when a *background command finishes*, so "tell me when this run is done" has to be one command that blocks and exits rather than a polling script. - `internal/cli/app.go` - `wait` resolves every id up front (so an unknown run is a fast client error, never something discovered after the others finish), then polls each run to a terminal status and prints one line per run as it finishes. - The polling is the *same* machinery the `run --wait` path already used: the per-second `get_run` reattachment is factored into `awaitRuns`, and `finishRun` now uses it too. The transport is unchanged — no subscription and no new protocol message. - Terminal statuses are `succeeded`, `failed`, `canceled` and `interrupted`; a run parked on a human decision (`waiting`) is *not* terminal for `wait`, so a wait blocks through it. `run --wait` keeps its existing active set (queued/running) unchanged. - A finished-but-unsuccessful run is still a finished run: `wait` prints it and exits 0. The exit is non-zero only for a client-side failure — an unknown id, a connection that cannot be established, or `--timeout` expiring while a run is still active. A timeout reports the still-active runs, changes nothing, and is never treated as a run's outcome. - `--timeout DURATION` is the overall client limit (default `0` = wait until the runs finish); the per-request transport timeout falls back to the usual 30 s bound. `--url` follows the existing convention. - `--json` prints the final run envelope instead of the line: one envelope for one id, an array for several. - It is read-only: it sends only `get_run`, resolves no workspace, is not refused by the workspace guard and writes nothing. - `internal/cli/commands.go` and `internal/cli/help.go` add the command to the help inventory and the EXECUTE section. - Tests: `internal/cli/wait_test.go` (line format, batch reporting, wait-until- terminal, unknown id, timeout leaves the run active, `--json` envelope shape) and `internal/cli/wait_command_test.go` (the real CLI against the real websocket server and store: terminal reporting, blocking until terminal, a batch, an unknown id, a timeout that leaves the run `queued`, and a run whose recorded workspace is absent). No protocol, server, store, TUI or Android change; no new dependency; no run is started. State: committed locally only, not deployed. ## Shared documents this change makes stale The note is written here rather than edited in place; the `docs-fold` writer should update these when it next folds notes. - `docs/cli.md` — the "Scripted runs" section (beside the `--wait` paragraph at the end of the `cd ~/repos/project` block, and the `| Run history/inspection | runs --json, inspect ID --json |` row of the "CLI/TUI capability map") should gain the `wait` command. Suggested text to add after the `--wait`/`--wait-timeout` paragraph: > `pipelines wait [run-id ...]` blocks until each run reaches a > terminal status — `succeeded`, `failed`, `canceled` or `interrupted`, and > also through a run waiting on a person — then prints one line per run with its > id, status and outcome, its final stage and how long it took, and exits 0 even > for a run that finished unsuccessfully. Several ids are waited together in one > command. The exit is non-zero only for a client-side failure: an unknown run > id, a connection that could not be established, or `--timeout` expiring while > a run is still active. A timeout says the run is still active and that nothing > was cancelled; it never cancels, retries or otherwise touches a run, and is > never reported as its outcome. It is read-only: it needs no workspace, is not > refused by the workspace guard and writes nothing. `--json` prints the final > run envelope instead of the line (one envelope for one id, an array for > several). `--timeout` is the overall client limit and defaults to 0 (wait > until the runs finish), independent of the per-request `--timeout`. and extend the capability-map row to `| Run history/inspection | runs --json, inspect ID --json, wait ID [...] |`. - `internal/author/skill/references/operations.md` — the "Inspect results first" run-operations list (around the `CLI_PREFIX inspect RUN_ID --json` bullet) should add a `CLI_PREFIX wait RUN_ID [RUN_ID ...]` bullet: it blocks until every named run is terminal (or the client `--timeout` passes) and reports each run's id, status, outcome, stage and duration; it is read-only, needs no workspace, exits 0 even for a failed run, and a timeout never cancels or changes a run. Add a dated evidence bullet naming `internal/cli/wait_test.go` and `internal/cli/wait_command_test.go`. ## Not stale - `internal/author/install.go`'s managed file inventory needs no change: no reference file is added. - `internal/author/skill/references/SKILL.md` stays a task-directed index; the wait command belongs in `operations.md`. - `internal/server/AGENTS.md` and the root `AGENTS.md` already describe the CLI, the workspace guard and the polling path, so neither area map needs a new entry. - `README.md` carries no per-command CLI inventory that names `wait`.