Files
alan b7c2ba7d56 cli: add wait <run-id> to block until runs finish, then report them
The harness resumes a session when a background command finishes, so "tell me
when this run is done" needs one command that blocks and exits rather than a
polling script.

- `pipelines wait <run-id> [run-id ...]` resolves every id up front (an unknown
  run is a fast client error), then polls each run to a terminal status -
  `succeeded`, `failed`, `canceled` or `interrupted`, blocking through a run
  parked on a human decision - and prints one line per run as it finishes with
  id, status and outcome, stage and duration.
- A finished-but-unsuccessful run is still a finished run: it is reported and
  the command 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.
- Reuses the existing `run --wait` polling machinery: the per-second `get_run`
  reattachment is factored into `awaitRuns`, used by `finishRun` too. No
  subscription or new protocol message. `--url`/`--timeout` follow the existing
  client conventions; `--timeout` is the overall client limit (default 0).
- Read-only: sends only `get_run`, resolves no workspace, is not refused by the
  workspace guard and writes nothing. `--json` prints the final run envelope
  (one envelope for one id, an array for several).
- `commands.go` and `help.go` add it to the usage inventory and EXECUTE help.

Tests: `wait_test.go` (line format, batch reporting, wait-until-terminal,
unknown id, timeout leaves the run active, `--json` shape) and
`wait_command_test.go` (real CLI against the real websocket server and store).

Packaged assets checked: no packaged template changes. No authoring skill
reference file is added, so `internal/author/install.go`'s managed inventory
needs no change. `internal/author/skill/references/operations.md` (the
"inspect results first" run-operations list) and `docs/cli.md` (the scripted-runs
`--wait` paragraph and the CLI/TUI capability-map row) are now stale and are
recorded - not edited - in `docs/notes/wait-command.md` for the `docs-fold`
writer. `SKILL.md` stays a task-directed index; no shared document is edited
here.

No protocol, server, store, TUI or Android change; no new dependency; no run
started. Committed locally only, not pushed or deployed.
2026-10-18 01:11:26 +01:00

93 lines
5.4 KiB
Markdown

# `pipelines wait`: block until runs finish, then report them
## What this item changed
A new read-only CLI command, `pipelines wait <run-id> [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> [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`.