Files
pipelines/docs/notes/wait-command.md
T
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

5.4 KiB

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.