docs(orchestration): name --include-remote on the guides' enumeration paths

The stall path told coordinators to enumerate with plain worker-list, but
a worker started --on <environment> reads unverifiable without
--include-remote. Also names page.nextCursor for fleets past 100 rows.
This commit is contained in:
Jinwoo-H
2026-09-04 15:24:31 -04:00
parent e587416932
commit cbe2d378fb
4 changed files with 18 additions and 1 deletions
@@ -327,6 +327,10 @@ describe('owned orchestration references', () => {
'ORCA project setup-existing-folder --project <project_id> --host <host_id> --path <abs_path> --kind folder --json'
)
expect(squash(reference)).toContain('and rejects a plain directory')
expect(reference).toContain('ORCA orchestration worker-list --include-remote --json')
expect(squash(reference)).toContain(
'enumerate remote workers with `--include-remote` or every one of them reads `unverifiable`'
)
})
it('owns FIFO mail, Dispatch addresses, groups, questions, and gates', () => {
@@ -384,6 +388,9 @@ describe('owned orchestration references', () => {
)
expect(reference).toContain('`projection.nextAction` argv')
expect(reference).toContain('the fleet verdict decides')
expect(reference).toContain('ORCA orchestration worker-list --include-remote --json')
expect(reference).toContain('reads `unverifiable` until you enumerate with `--include-remote`')
expect(reference).toContain('follow `page.nextCursor` with `--cursor <value>`')
})
it('requires positive evidence of exit before stop, abandon, retry, or release', () => {
@@ -60,8 +60,12 @@ terminal handle.
ORCA orchestration worker-show --dispatch <dispatch_id> --json
ORCA orchestration worker-read --dispatch <dispatch_id> --limit 50 --json
ORCA orchestration send --to dispatch:<dispatch_id> --subject "Follow-up" --body "<guidance>" --json
ORCA orchestration worker-list --include-remote --json
```
`worker-list` reads local fleet state only; enumerate remote workers with
`--include-remote` or every one of them reads `unverifiable`.
## Execution-host and mixed-version floor
The execution host owns process, filesystem, transcript, stop, and cleanup
@@ -17,6 +17,7 @@ decision, stop/abandon request, retention request, or uncertain release.
```text
ORCA orchestration worker-list --json
ORCA orchestration worker-list --include-remote --json
ORCA orchestration worker-show --dispatch <dispatch_id> --json
ORCA orchestration worker-read --dispatch <dispatch_id> --limit 50 --json
```
@@ -28,6 +29,11 @@ argv to run. `worker-show`'s `observation.status` is PTY liveness only, so a
`live` terminal whose agent died at a trust prompt still reads `live` there.
When the two disagree, the fleet verdict decides.
A worker started with `--on <environment>` reads `unverifiable` until you
enumerate with `--include-remote`, which asks its execution host for the
verdict. Past 100 rows the response pages, so follow `page.nextCursor` with
`--cursor <value>` until `page.hasMore` is false.
## Stall needs positive evidence
Leave the wait only on positive proof the agent stopped: `exited` liveness, the
File diff suppressed because one or more lines are too long