Repository navigation
docs(design): C18 records the #268 decisions - #274
Conversation
describe probes but writes nothing, wait --timeout takes a duration with a unit (30s by default), continue waits for a step another worker runs, and the CLI reference is generated into its own file. Claude-Session: https://claude.ai/code/session_01PvecNurNanbbbk5qLA5qpM
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 18fd467488
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | `version` | — | `capabilities` | | ||
|
|
||
| `get` prints a table, one row per item, with columns from the kind's entry (L3); `-o wide` adds the low-priority columns. `describe` prints everything a person needs about one item: for a run, its status, position, the arrow into it, what it needs, the outstanding invocation, the commands that answer it, and whether a worker is alive. It is the one call that answers "what is this run doing and what do I do?" (`describe run/X -o json` gives the same as an object, which kubectl lacks.) `get events --run X` replaces `events`, as `get` with a parent (L6). `get runs --unfinished` keeps today's `list --unfinished`: only unfinished runs, newest first, filtered in the store rather than by the caller. `get runs` keeps `list`'s tree in text output: a child run is indented under its parent, in sibling order, with the parent node named. `start` and `execute` take the same targets `start` and `run` take today: `workflow/<name>` for a workflow in the project folder, or a path to a workflow folder, its `workflow.dot` or a built artifact. As today, an existing path wins: a target that names an existing file or folder is that path, and only otherwise is it a workflow name in the project folder. `workflow/<name>` always means the name. When two folders share a workflow name, which a lookup by name refuses with `workflow.ambiguous`, `get workflows -o name` prints each of them by its path, which every workflow verb takes. | ||
| `get` prints a table, one row per item, with columns from the kind's entry (L3); `-o wide` adds the low-priority columns. `describe` prints everything a person needs about one item: for a run, its status, position, the arrow into it, what it needs, the outstanding invocation, the commands that answer it, and whether a worker is alive. It is the one call that answers "what is this run doing and what do I do?" (`describe run/X -o json` gives the same as an object, which kubectl lacks.) `describe` changes nothing and shows nothing stale (#268). At a held async step whose action has a probe, it runs the probe. On a `dead` answer it records nothing: it shows the attempt as cut off with reason `probe-dead` and what happens next, the same way `status` already shows a worker's try that was cut off. The expiry is written by the verbs that write, as today: `serve`'s sweep, `claim` and `continue`. `status --no-probe` does not carry over, since `describe` writes nothing; the alias accepts it and ignores it. `wait` reads the same live view. `continue run/X` works the run until it parks, as `worker --run --until-parked` does: it runs watches, and exits 6 at a held step with no watch, or one whose watch says the holder waits for a person. At a step another worker runs, it waits for that worker's result instead of returning exit 0, so it replaces `worker --run --until-parked` exactly (#268). `get events --run X` replaces `events`, as `get` with a parent (L6). `get runs --unfinished` keeps today's `list --unfinished`: only unfinished runs, newest first, filtered in the store rather than by the caller. `get runs` keeps `list`'s tree in text output: a child run is indented under its parent, in sibling order, with the parent node named. `start` and `execute` take the same targets `start` and `run` take today: `workflow/<name>` for a workflow in the project folder, or a path to a workflow folder, its `workflow.dot` or a built artifact. As today, an existing path wins: a target that names an existing file or folder is that path, and only otherwise is it a workflow name in the project folder. `workflow/<name>` always means the name. When two folders share a workflow name, which a lookup by name refuses with `workflow.ambiguous`, `get workflows -o name` prints each of them by its path, which every workflow verb takes. |
There was a problem hiding this comment.
Ignoring status --no-probe removes the only detailed read that does not launch probe processes. The existing live-view contract in docs/design/c17-live-run-view.md:55-59 invokes this command once per second for every visible run, while spec/host.md:965-967 otherwise limits sweep probes to once per 30 seconds; after this alias change, those displays can execute an external probe every second even though they requested a store-only refresh. Keep the flag's behavior during compatibility releases and provide an equivalent store-only option for describe before migrating that polling flow.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Partly fixed in a1e5c2d: through 0.4 the status alias keeps --no-probe as in 0.2, a read of the store with no probe (L9), so c17's once-a-second poll (docs/design/c17-live-run-view.md:57) is unchanged. Escalated, left open: what that poll moves to by 0.5 (a store-only describe, a probe answer reused for a while, or a push channel) is a design call on top of #268 §1.
Writes the decisions from #268 into C18 (
docs/design/c18-cli-grammar.md):describeprobes but writes nothing. Adeadanswer shows the attempt as cut off (probe-dead), and the sweep,claimandcontinuestill write the expiry.status --no-probedoes not carry over. (§1)wait --timeout <duration>takes a value with a unit (30s,5m,1m30s). A bare number exits 2 with an error that shows the fix. The default is 30s, and0schecks once. (§2)continueis the until-parked mode, and now also waits for a step another worker runs, so it replacesworker --run --until-parkedexactly. (§3)spec/cli-reference.md, andspec/cli.mdstays hand-written prose. (§5)Plugin kind identity (§4) is postponed to the plugin work and isn't changed here. Whether
getprobes (§1) is still open in #268.Refs #268
https://claude.ai/code/session_01PvecNurNanbbbk5qLA5qpM