From 624e01bfcda0d2017aa8edf5211862975904323f Mon Sep 17 00:00:00 2001 From: gum798 <33922655+gum798@users.noreply.github.com> Date: Wed, 28 Oct 2026 17:04:38 +0900 Subject: [PATCH] docs(cli): say orchestration check --peek and --all cannot drain a mailbox (#19161) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --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 until deliveryId is null. Co-authored-by: 서정화 Co-authored-by: Neil --- docs/site/content/docs/cli/orchestration.mdx | 2 +- src/cli/specs/orchestration.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/site/content/docs/cli/orchestration.mdx b/docs/site/content/docs/cli/orchestration.mdx index 88355cb8c82..47725eeda8e 100644 --- a/docs/site/content/docs/cli/orchestration.mdx +++ b/docs/site/content/docs/cli/orchestration.mdx @@ -114,7 +114,7 @@ orca orchestration dispatch --task --to --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 ` until `deliveryId` is `null`. - Group addresses: `@all`, `@idle`, `@claude`, `@codex`, `@opencode`, `@gemini`, `@droid`, `@grok`, `@cursor`, `@worktree:` — never for `worker_done` / heartbeat. - Every group except `@worktree:` 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:`. `@worktree:` includes coordinators in that workspace. diff --git a/src/cli/specs/orchestration.ts b/src/cli/specs/orchestration.ts index 20008e45749..df82997c9ce 100644 --- a/src/cli/specs/orchestration.ts +++ b/src/cli/specs/orchestration.ts @@ -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 until deliveryId is null.' ] }, {