b7c2ba7d56
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.
93 lines
5.4 KiB
Markdown
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`.
|