starred/orca
1
0
Fork 0
mirror of https://github.com/stablyai/orca.git synced 2026-11-03 02:27:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(cli): say orchestration check --peek and --all cannot drain a mailbox (#19161)

Browse Source 
--peek and --all return no deliveryId, so a coordinator that loops on them
never acknowledges anything. Document that, note the 100-row cap for --all
and Run --peek, and give the drain recipe: repeat plain check with
--ack <previous deliveryId> until deliveryId is null.

Co-authored-by: 서정화 <seojeonghwa@Mac.mshome.net>
Co-authored-by: Neil <neil@stably.ai>
This commit is contained in:
gum798
2026-10-28 01:04:38 -07:00
committed by GitHub
co-authored by 서정화 Neil
parent 82c492c684
commit 624e01bfcd
2 changed files with 2 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/site/content/docs/cli/orchestration.mdx
+1 -1
View File
@@ -114,7 +114,7 @@ orca orchestration dispatch --task <taskId> --to <workerHandle> --inject --json
## Messaging notes
- Default `check` is the bound Run's oldest unacked Delivery (FIFO). Replay until `--ack`.
- `--peek` / `--all` do not consume mail.
- `--peek` / `--all` do not consume mail and return no `deliveryId`, so they do not drain a mailbox on their own. `--all` and a Run `--peek` show at most 100 rows. To drain, repeat plain `check --ack <previous deliveryId>` until `deliveryId` is `null`.
- Group addresses: `@all`, `@idle`, `@claude`, `@codex`, `@opencode`, `@gemini`, `@droid`, `@grok`, `@cursor`, `@worktree:<id>` — never for `worker_done` / heartbeat.
- Every group except `@worktree:<id>` means the live Dispatches of the sender's own Run, delivered to their Dispatch mailboxes (or child Run mailboxes for nested coordinators). A sender in no Run is refused; `--run` must match the audience and never grants membership.
- Run groups exclude their owning coordinator. A worker raising a blocker sends to `run:<id>`. `@worktree:<id>` includes coordinators in that workspace.
src/cli/specs/orchestration.ts
+1 -1
View File
@@ -117,7 +117,7 @@ export const ORCHESTRATION_COMMAND_SPECS: CommandSpec[] = [
'On Windows PowerShell, quote comma-separated type filters, e.g. --types "worker_done,escalation".',
'--types is the wake condition for --wait; a returned Delivery is always the whole FIFO batch, so it is never filtered by type. Without --wait it has no effect on consuming checks. Only --peek and --all filter their rows.',
'--format renders the returned rows as local text only; it never writes to another terminal.',
'A bound Run replays the same Delivery until --ack or all its messages are marked read, even with --types; process every message before acknowledging. Several --wait calls may wait on one Run inbox; waiting reserves nothing, listeners woken together get the same Delivery, and a repeated --ack is a no-op.'
'A bound Run replays the same Delivery until --ack or all its messages are marked read, even with --types; process every message before acknowledging. Several --wait calls may wait on one Run inbox; waiting reserves nothing, listeners woken together get the same Delivery, and a repeated --ack is a no-op. --peek and --all return no deliveryId, so they do not drain a mailbox on their own; --all and a Run --peek show at most 100 rows. To drain, repeat plain check with --ack <previous deliveryId> until deliveryId is null.'
]
},
{