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.
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.gowaitresolves 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 --waitpath already used: the per-secondget_runreattachment is factored intoawaitRuns, andfinishRunnow uses it too. The transport is unchanged — no subscription and no new protocol message. - Terminal statuses are
succeeded,failed,canceledandinterrupted; a run parked on a human decision (waiting) is not terminal forwait, so a wait blocks through it.run --waitkeeps its existing active set (queued/running) unchanged. - A finished-but-unsuccessful run is still a finished run:
waitprints 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--timeoutexpiring 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 DURATIONis the overall client limit (default0= wait until the runs finish); the per-request transport timeout falls back to the usual 30 s bound.--urlfollows the existing convention.--jsonprints 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.goandinternal/cli/help.goadd 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,--jsonenvelope shape) andinternal/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 runqueued, 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--waitparagraph at the end of thecd ~/repos/projectblock, and the| Run history/inspection | runs --json, inspect ID --json |row of the "CLI/TUI capability map") should gain thewaitcommand. Suggested text to add after the--wait/--wait-timeoutparagraph:pipelines wait <run-id> [run-id ...]blocks until each run reaches a terminal status —succeeded,failed,canceledorinterrupted, 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--timeoutexpiring 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.--jsonprints the final run envelope instead of the line (one envelope for one id, an array for several).--timeoutis 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 theCLI_PREFIX inspect RUN_ID --jsonbullet) should add aCLI_PREFIX wait RUN_ID [RUN_ID ...]bullet: it blocks until every named run is terminal (or the client--timeoutpasses) 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 naminginternal/cli/wait_test.goandinternal/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.mdstays a task-directed index; the wait command belongs inoperations.md.internal/server/AGENTS.mdand the rootAGENTS.mdalready describe the CLI, the workspace guard and the polling path, so neither area map needs a new entry.README.mdcarries no per-command CLI inventory that nameswait.