crewbus 10.0.11 → 11.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/AGENTS.template.md +4 -4
  2. package/CHANGELOG.md +151 -0
  3. package/README.md +713 -706
  4. package/TEAM.template.md +1 -1
  5. package/bin/crewbus-hook.js +22 -5
  6. package/bin/crewbus-mcp.js +56 -48
  7. package/bin/crewbus.js +486 -355
  8. package/bin/lib/channels.js +1 -1
  9. package/bin/lib/export.js +1 -1
  10. package/bin/lib/groups.js +1 -5
  11. package/bin/lib/identity.js +92 -152
  12. package/bin/lib/launch.js +128 -30
  13. package/bin/lib/qrcode.js +2971 -0
  14. package/bin/lib/relay.js +26 -54
  15. package/bin/lib/spawn.js +241 -194
  16. package/bin/lib/store.js +2 -2
  17. package/bin/lib/web.js +277 -59
  18. package/claude-plugin/skills/crewbus/SKILL.md +1 -1
  19. package/docs/APPROVALS.md +8 -8
  20. package/docs/AUDIT_EXPORT.md +7 -7
  21. package/docs/CERT_READINESS.md +120 -120
  22. package/docs/COMPATIBILITY.md +196 -194
  23. package/docs/CONSOLIDATOR.md +6 -6
  24. package/docs/CONTROL_PLANE_SPEC.md +12 -14
  25. package/docs/CREWS.md +16 -13
  26. package/docs/DELIVERY.md +213 -210
  27. package/docs/GROUPS.md +8 -8
  28. package/docs/HA.md +151 -151
  29. package/docs/IDENTITY.md +6 -6
  30. package/docs/LEAD_ASSIGN.md +3 -85
  31. package/docs/LONG_RUNS.md +3 -3
  32. package/docs/M1_CLI_DRAFT.md +9 -9
  33. package/docs/ORCHESTRATOR.md +87 -0
  34. package/docs/PAIRING.md +7 -7
  35. package/docs/QUICKSTART.md +24 -13
  36. package/docs/RBAC.md +84 -73
  37. package/docs/SPLIT.md +82 -82
  38. package/docs/TENANCY.md +10 -10
  39. package/docs/THREAT_MODEL.md +68 -69
  40. package/docs/VERIFIER.md +10 -10
  41. package/docs/VERSION_SKEW.md +57 -57
  42. package/documentation.html +37 -29
  43. package/examples/hermes-pairing.md +3 -3
  44. package/examples/t3-pairing.md +1 -1
  45. package/index.html +13 -14
  46. package/opencode/plugins/dm-watch.js +1 -1
  47. package/opencode/tools/dm-send.js +4 -13
  48. package/package.json +75 -50
  49. package/packages/client-runtime/README.md +40 -40
  50. package/packages/contracts/harness.json +108 -111
  51. package/packages/contracts/launch.json +2 -3
  52. package/packages/contracts/pairing.json +3 -3
  53. package/docs/DESKTOP_SPIKE.md +0 -223
package/docs/CREWS.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # Weighted remote crews
2
2
 
3
- One lead, many relays. Relays advertise a `--weight` (default 100) plus live
4
- worker count in `/healthz`; `crew survey` shows the fleet and `crew dispatch`
5
- splits an elastic crew across reachable primaries by weight (largest
6
- remainder). Standbys and unreachable relays skip loudly — they never silently
7
- absorb workers.
3
+ One orchestrator, many relays. Relays advertise a `--weight` (default 100)
4
+ plus live worker count in `/healthz`; `crew survey` shows the fleet and
5
+ `crew dispatch` splits an elastic crew across reachable primaries by weight
6
+ (largest remainder). Standbys and unreachable relays skip loudly — they never
7
+ silently absorb workers.
8
8
 
9
9
  ## Survey the fleet
10
10
 
@@ -17,9 +17,9 @@ crewbus crew survey --relays http://r1:8471,http://r2:8471 [--json]
17
17
  ## Dispatch
18
18
 
19
19
  ```sh
20
- crewbus crew dispatch --from lead \
20
+ crewbus crew dispatch --from orchestrator \
21
21
  --relays http://r1:8471,http://r2:8471 --weights 3,1 \
22
- --count 4 --prefix w --harness generic --cmd "node worker.js" \
22
+ --count 4 --prefix w --harness opencode \
23
23
  --body "Triage batch 7…" --secret s3 [--dry-run]
24
24
  # dispatched 3/3 to http://r1:8471 [weight 3]
25
25
  # w-1 pid 7436 reply msg-…
@@ -29,10 +29,13 @@ crewbus crew dispatch --from lead \
29
29
 
30
30
  Flags mirror `spawn` (`--harness/--cmd/--cwd/--model/--max-turns/
31
31
  --allow-tools/--auto/--subject/--priority/--sender-type/--keep-env/
32
- --allow-env`, budgets stay local-only). `--dry-run` prints the shares
33
- without booting. Every boot lands under your identity on that relay
34
- (first-claim mints there if needed); replies land on each relay's board —
35
- `sync` them back or `gather` per relay.
32
+ --allow-env`, budgets stay local-only). `--model` also takes a comma list
33
+ (`a,b,c`) cycled in worker order. `--dry-run` prints the shares
34
+ without booting.
35
+
36
+ Remote boots run as each relay board's orchestrator. The relay secret or a
37
+ device credential with `launch:spawn` is the auth boundary; replies land on
38
+ each relay's board — `sync` them back or `gather` per relay.
36
39
 
37
40
  ## Credentials per relay
38
41
 
@@ -51,5 +54,5 @@ shared secret; longest prefix wins). Bare `--secret` / `--device` /
51
54
  loudly rather than queueing into a replica.
52
55
  - **Deterministic shares.** Same weights + count always split the same way,
53
56
  so `--dry-run` predicts the real run and tests can assert distributions.
54
- - **Audited both ends.** The lead's board records `crew-dispatch` (relays,
55
- count, shares); each relay records its own `remote-spawn` audit trail.
57
+ - **Audited both ends.** The caller's board records `crew-dispatch` (relays,
58
+ count, shares); each relay records its own `remote-spawn` audit trail.
package/docs/DELIVERY.md CHANGED
@@ -1,210 +1,213 @@
1
- # Delivery semantics
2
-
3
- How the bus behaves when things go wrong. Read this before building
4
- orchestrators on top of `send`/`spawn`.
5
-
6
- ## At-least-once, not at-most-once
7
-
8
- - **Files are the truth.** `send` writes one immutable file per DM
9
- (`dm/<recipient>/<id>.json`) or one `broadcast/<batch>.json` for
10
- fan-outs over 20. A send that echoes an id **landed**.
11
- - **Push is at-least-once.** The opencode watcher and the hook helpers
12
- claim `delivered/<agent>/<msg>.json` markers with an exclusive create,
13
- and the cursor advances only on successful injection. A failed push
14
- (e.g. into a stale session) releases the marker and is **retried**, so a
15
- recipient may see a DM twice across a crash — never zero times.
16
- - **Pull (`inbox`) is idempotent.** No mark-read side effects; page with
17
- `--after`, filter with `--unacked`. `redeliver --id|--all` rewinds the
18
- cursor after a dead watcher consumed mail.
19
-
20
- ## Ordering
21
-
22
- - **No global order.** DMs from different senders interleave arbitrarily.
23
- - **Per-sender order is wall-clock + id.** `inbox`/`gather`/`thread`
24
- present oldest first by `at` timestamp; ids sort ties (4 random bytes,
25
- unique under parallel sends).
26
- - **Channels append.** `channels/<name>.log.jsonl` is append-only; concurrent
27
- posts serialize on file append. Sync merges channel logs **union-by-id**,
28
- so both sides' lines survive a partition.
29
-
30
- ## What happens when a worker dies mid-brief
31
-
32
- - The **brief survives** — it is a file, not a process. A replacement
33
- worker with the same name sees it via `inbox` (stale names are reusable;
34
- spawning refuses names with a *live* worker behind them).
35
- - A **detached worker's reply may never come.** `spawn-status` shows
36
- `running? reply landed? acked?` plus a log tail: an exited worker with
37
- no reply failed silently — read its log in `.crewbus/logs/`.
38
- - **Pool mode** (`pool --count N --pool-size S`) replaces dead workers
39
- automatically up to N total, with backpressure (queue refuses past
40
- 4× pool size).
41
-
42
- ## Presence you can trust (recycled-pid guard)
43
-
44
- `spawn-status` liveness used to be `kill(pid, 0)` alone: after a reboot
45
- the OS recycles pids and a dead worker could read as "running". Status
46
- now also resolves the process start time (`ps` elapsed on unix,
47
- `Get-Process` on Windows, 60s memo) and compares it against the recorded
48
- `spawnedAt` (±120s skew): a live pid whose process started *after* the
49
- spawn is a stranger, and `alive` flips to false. The verdict rides along
50
- as `aliveVerified` (`true` corroborated, `false` contradicted, `null`
51
- unverifiable on this platform — the old kill-0 verdict stands). The
52
- override needs positive evidence (start time after spawn + skew), so a
53
- false "dead" takes a >2min clock jump between spawn and check — rare,
54
- and missing data never flips a verdict. Practical effect: after a
55
- reboot, recycled pids read dead instead of running, so `respawn` is
56
- allowed instead of wrongly refused. Reconcile sweeps (`doctor`,
57
- post-reboot `spawn-status --all` review) remain the operator's job for
58
- now.
59
-
60
- ## Progress checkpoints
61
-
62
- Long briefs die mid-way; re-deriving progress from files wastes the
63
- resume. Workers checkpoint every few steps (or before anything risky):
64
-
65
- ```sh
66
- crewbus send --from <you> --to <lead> --reply <brief-id> --checkpoint --body "done X / next Y"
67
- ```
68
-
69
- (`dm_send` takes `checkpoint: true`; same on the opencode `dm-send`
70
- tool.) Checkpoints ride the normal DM thread, so `thread`/`gather`,
71
- sync, and push delivery all work unchanged — but they are *progress*,
72
- not work awaiting acceptance:
73
-
74
- - `--unacked` (CLI and `dm_inbox`) and the `ack --timeout` hint skip
75
- them; transcripts label them (`checkpoint: progress`, `[checkpoint]`
76
- in digests).
77
- - `spawn-status` reply detection ignores them: only a non-checkpoint
78
- reply to the brief counts as "reply landed".
79
- - `ack --all` still records them if run (harmless); rate limits and
80
- duplicate suppression apply like any send, so checkpoint every few
81
- steps — not every tool call.
82
-
83
- A respawned worker reads the latest checkpoint off the thread
84
- (`inbox`/`thread --id <brief-id>`) and continues from "next Y" instead
85
- of restarting. Checkpoints are unverified progress: they never feed
86
- `result record` / `race` winner logic (that still needs `ack --verify`).
87
-
88
- ## Pool supervision + re-attach
89
-
90
- `pool` briefs all workers up front, boots at most `--pool-size`
91
- concurrently, and replaces exits until N total — but the supervision loop
92
- runs inside the invoking CLI process. If that process dies (lead restart,
93
- shutdown, supervision-window timeout), `pool-resume --id <pool> --from
94
- <you>` re-attaches: it reconciles every launched worker (replied → done,
95
- live → re-adopted, dead w/o reply → done with a `respawn` hint), then
96
- supervises the unstarted remainder for a fresh window. Briefs are reused
97
- by id, never duplicated; one supervisor at a time via an advisory pool
98
- lock (TTL expiry lets a later attach take over after a crash).
99
- `finishedAt` marks true completion only — a timed-out pool stays
100
- resumable. Pools created before the resumable schema (no queue cursor)
101
- are refused with guidance. Lead/admin only.
102
-
103
- Windows note: console-less detached `cmd.exe` wrappers linger up to ~60s
104
- after their payload exits, so natural-exit detection on `shell:true`
105
- harnesses (opencode/claude/codex/cursor/generic) trails by up to a
106
- minute; kills report immediately. Pool turnover and `spawn-status`
107
- inherit the tail — size supervision windows accordingly.
108
-
109
- ## Long runs (the 10-day task)
110
-
111
- Don't run one agent for 10 days — run a board for 10 days. Full playbook:
112
- `docs/LONG_RUNS.md` (setup checklist, wave pattern, recovery ladder).
113
- The short version: sessions are a cache, the board is the database —
114
- rotate workers in waves, checkpoint progress, poll digest-first, persist
115
- tokens to files, bound everything, and let compaction/restart/reboot
116
- happen. A cold session plus a warm board is a crew that never sleeps.
117
-
118
- ## Unacknowledged-brief timeout (retry / reassign)
119
-
120
- `ack` is orthogonal to delivery: a reply that sits `--unacked` is work
121
- nobody accepted. The reassign pattern:
122
-
123
- ```sh
124
- # what is still open — and how long has it waited?
125
- crewbus inbox --from lead --unacked --older-than 10m
126
-
127
- # the brief is a file: re-brief a fresh worker on the same thread
128
- crewbus send --from lead --to w9 --reply <brief-id> --body "picking this up (w3 went silent)"
129
-
130
- # the dead watcher's mail, if any, can be replayed
131
- crewbus redeliver --from w3 --all
132
- ```
133
-
134
- There is no automatic reaper: leads own the timeout policy for their
135
- crew. `spawn --timeout 10m` records `deadlineAt` (`spawn-status` flags
136
- passed deadlines — reap with `spawn-kill`/`stop`); `stop --all --from <you>`
137
- terminates everything when the whole run is lost.
138
-
139
- ## Sync partitions
140
-
141
- - Message files are immutable with unique ids: sync is **conflict-free
142
- union** — both sides end up with both sides' mail.
143
- - Presence, cursors and groups merge by **hybrid logical clock +
144
- version counter** (wall-mtime fallback for legacy docs); newer
145
- `(hlc, v)` wins, ties keep local content and converge clocks so the
146
- next round is `pulled 0, pushed 0`.
147
- - **Prune stays local.** Deletions replicate only as **tombstones**
148
- (`tombstones/*.json`, synced): a pruned message never resurrects on a
149
- partitioned peer, but the peer's other history is untouched.
150
- - Rounds after the first are incremental (per-peer cursor, 60s overlap);
151
- `--dry-run` previews pulls/pushes/tombstones without touching files.
152
-
153
- ## Worker lifetime
154
-
155
- - `spawn` defaults to **oneshot**: headless workers (`claude -p`,
156
- `codex exec`, `cursor-agent -p`, …) run the brief and exit. Their mail
157
- **waits for pull** — a finished worker cannot receive push.
158
- - `--persistent` marks long-lived peers (opencode sessions, daemons)
159
- that stay addressable. `spawn-status` shows the recorded lifetime.
160
- - Either way: **finished workers' DMs are files** — `inbox --from <name>`
161
- reads them after the process is gone.
162
- - **Session-id capture (respawn prerequisite).** Spawn boots the four
163
- JSON-output harnesses with machine-readable logs (`opencode run
164
- --format json`, `claude -p --output-format json`, `grok
165
- --output-format json`, `codex exec --json`) so the harness session id
166
- can be recovered from the worker log. `spawn-status` lazily extracts it
167
- into `worker-sessions/<name>.json` (kept beside — not inside — the
168
- agent doc, so presence heartbeats can never wipe it; machine-local,
169
- never synced). Provenance is tracked (`preassigned` /
170
- `preassigned-confirmed` / `log` / `log-override` — a disagreeing log
171
- wins, in case the installed harness ignored the flag).
172
- - **Pre-assigned ids (the mid-run-kill case).** Log parsing can't cover a
173
- worker killed before emitting anything (notably grok, whose id only
174
- arrives end-of-run). Where the CLI supports creating with an id,
175
- `bootWorker` mints a UUID and passes it in (`claude --session-id`,
176
- grok `-s`), so the binding holds a resumable id from boot. opencode
177
- has no pre-set flag (its id arrives in the first stream event — the
178
- residual window is milliseconds); codex relies on `thread.started`;
179
- cursor/agy offer neither.
180
- - **Respawn (`respawn --from <lead> --to <worker>`).** Reboots one dead
181
- worker in its *same* harness conversation: `opencode run --session`,
182
- `claude -p --resume` (+ `CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1` so a
183
- killed turn continues), `codex exec resume`, `grok -r`, agy
184
- `--conversation`, cursor `--resume`; generic has no continuity and
185
- re-boots fresh. The catch-up brief points at the original prompt file
186
- and threads the same reply id, so the worker continues instead of
187
- restarting; codex points at the catch-up file itself (its positional
188
- prompt can't attach files). Refuses live workers unless `--force`
189
- (kills first, own-crew scoped like `spawn-kill`); refuses unknown,
190
- never-captured, and pre-capture-era workers with re-brief guidance.
191
- Attempts count on the binding; `--dry-run` previews. Lead/admin only.
192
-
193
- ## Poll discipline (long runs)
194
-
195
- Plain `inbox` dumps everything — over days that burns context.
196
- Poll digest-first instead, escalate only on hits:
197
-
198
- 1. `crewbus inbox --from <you> --unacked --digest` — cheap
199
- one-line-per-message sweep (`dm_inbox({ agent, unacked: true,
200
- digest: true })` on MCP).
201
- 2. Filtered full read — same sweep narrowed before expanding:
202
- `inbox --from <you> --unacked --grep <pat>` /
203
- `--priority high` (MCP: `grep` / `priority` params).
204
- 3. `thread --id <msg-id>` / `gather` for context — only once a hit
205
- proves worth reading.
206
-
207
- Cadence: poll cheap and often; full reads on signal. Push wakes you;
208
- digest tells you if it matters. Checkpoints compose: digests mark
209
- progress notes `[checkpoint]` (skipped by `--unacked` triage, never
210
- need ack), so the cheap poll still shows where a thread stands.
1
+ # Delivery semantics
2
+
3
+ How the bus behaves when things go wrong. Read this before building
4
+ orchestrators on top of `send`/`spawn`.
5
+
6
+ ## At-least-once, not at-most-once
7
+
8
+ - **Files are the truth.** `send` writes one immutable file per DM
9
+ (`dm/<recipient>/<id>.json`) or one `broadcast/<batch>.json` for
10
+ fan-outs over 20. A send that echoes an id **landed**.
11
+ - **Push is at-least-once.** The opencode watcher and the hook helpers
12
+ claim `delivered/<agent>/<msg>.json` markers with an exclusive create,
13
+ and the cursor advances only on successful injection. A failed push
14
+ (e.g. into a stale session) releases the marker and is **retried**, so a
15
+ recipient may see a DM twice across a crash — never zero times.
16
+ - **Pull (`inbox`) is idempotent.** No mark-read side effects; page with
17
+ `--after`, filter with `--unacked`. `redeliver --id|--all` rewinds the
18
+ cursor after a dead watcher consumed mail.
19
+
20
+ ## Ordering
21
+
22
+ - **No global order.** DMs from different senders interleave arbitrarily.
23
+ - **Per-sender order is wall-clock + id.** `inbox`/`gather`/`thread`
24
+ present oldest first by `at` timestamp; ids sort ties (4 random bytes,
25
+ unique under parallel sends).
26
+ - **Channels append.** `channels/<name>.log.jsonl` is append-only; concurrent
27
+ posts serialize on file append. Sync merges channel logs **union-by-id**,
28
+ so both sides' lines survive a partition.
29
+
30
+ ## What happens when a worker dies mid-brief
31
+
32
+ - The **brief survives** — it is a file, not a process. A replacement
33
+ worker with the same name sees it via `inbox` (stale names are reusable;
34
+ spawning refuses names with a *live* worker behind them).
35
+ - A **detached worker's reply may never come.** `spawn-status` shows
36
+ `running? reply landed? acked?` plus a log tail: an exited worker with
37
+ no reply failed silently — read its log in `.crewbus/logs/`.
38
+ - **Pool mode** (`pool --count N --pool-size S`) replaces dead workers
39
+ automatically up to N total, with backpressure (queue refuses past
40
+ 4× pool size).
41
+
42
+ ## Presence you can trust (recycled-pid guard)
43
+
44
+ `spawn-status` liveness used to be `kill(pid, 0)` alone: after a reboot
45
+ the OS recycles pids and a dead worker could read as "running". Status
46
+ now also resolves the process start time (`ps` elapsed on unix,
47
+ `Get-Process` on Windows, 60s memo) and compares it against the recorded
48
+ `spawnedAt` (±120s skew): a live pid whose process started *after* the
49
+ spawn is a stranger, and `alive` flips to false. `spawnedAt` is the launch
50
+ time of the currently recorded pid — it is set at spawn and refreshed on
51
+ every respawn, so a live replacement is not mistaken for a recycled pid.
52
+ The original registration time stays in `firstSeen`. The verdict rides along
53
+ as `aliveVerified` (`true` corroborated, `false` contradicted, `null`
54
+ unverifiable on this platform — the old kill-0 verdict stands). The
55
+ override needs positive evidence (start time after spawn + skew), so a
56
+ false "dead" takes a >2min clock jump between spawn and check — rare,
57
+ and missing data never flips a verdict. Practical effect: after a
58
+ reboot, recycled pids read dead instead of running, so `respawn` is
59
+ allowed instead of wrongly refused. Reconcile sweeps (`doctor`,
60
+ post-reboot `spawn-status --all` review) remain the operator's job for
61
+ now.
62
+
63
+ ## Progress checkpoints
64
+
65
+ Long briefs die mid-way; re-deriving progress from files wastes the
66
+ resume. Workers checkpoint every few steps (or before anything risky):
67
+
68
+ ```sh
69
+ crewbus send --from <you> --to orchestrator --reply <brief-id> --checkpoint --body "done X / next Y"
70
+ ```
71
+
72
+ (`dm_send` takes `checkpoint: true`; same on the opencode `dm-send`
73
+ tool.) Checkpoints ride the normal DM thread, so `thread`/`gather`,
74
+ sync, and push delivery all work unchanged — but they are *progress*,
75
+ not work awaiting acceptance:
76
+
77
+ - `--unacked` (CLI and `dm_inbox`) and the `ack --timeout` hint skip
78
+ them; transcripts label them (`checkpoint: progress`, `[checkpoint]`
79
+ in digests).
80
+ - `spawn-status` reply detection ignores them: only a non-checkpoint
81
+ reply to the brief counts as "reply landed".
82
+ - `ack --all` still records them if run (harmless); rate limits and
83
+ duplicate suppression apply like any send, so checkpoint every few
84
+ steps — not every tool call.
85
+
86
+ A respawned worker reads the latest checkpoint off the thread
87
+ (`inbox`/`thread --id <brief-id>`) and continues from "next Y" instead
88
+ of restarting. Checkpoints are unverified progress: they never feed
89
+ `result record` / `race` winner logic (that still needs `ack --verify`).
90
+
91
+ ## Pool supervision + re-attach
92
+
93
+ `pool` briefs all workers up front, boots at most `--pool-size`
94
+ concurrently, and replaces exits until N total — but the supervision loop
95
+ runs inside the invoking CLI process. If that process dies (orchestrator restart,
96
+ shutdown, supervision-window timeout), `pool-resume --id <pool> --from
97
+ <you>` re-attaches: it reconciles every launched worker (replied → done,
98
+ live → re-adopted, dead w/o reply → done with a `respawn` hint), then
99
+ supervises the unstarted remainder for a fresh window. Briefs are reused
100
+ by id, never duplicated; one supervisor at a time via an advisory pool
101
+ lock (TTL expiry lets a later attach take over after a crash).
102
+ `finishedAt` marks true completion only — a timed-out pool stays
103
+ resumable. Pools created before the resumable schema (no queue cursor)
104
+ are refused with guidance. Orchestrator-only.
105
+
106
+ Windows note: console-less detached `cmd.exe` wrappers linger up to ~60s
107
+ after their payload exits, so natural-exit detection on `shell:true`
108
+ harnesses (opencode/claude/codex/cursor) trails by up to a
109
+ minute; kills report immediately. Pool turnover and `spawn-status`
110
+ inherit the tail — size supervision windows accordingly.
111
+
112
+ ## Long runs (the 10-day task)
113
+
114
+ Don't run one agent for 10 days — run a board for 10 days. Full playbook:
115
+ `docs/LONG_RUNS.md` (setup checklist, wave pattern, recovery ladder).
116
+ The short version: sessions are a cache, the board is the database —
117
+ rotate workers in waves, checkpoint progress, poll digest-first, persist
118
+ tokens to files, bound everything, and let compaction/restart/reboot
119
+ happen. A cold session plus a warm board is a crew that never sleeps.
120
+
121
+ ## Unacknowledged-brief timeout (retry / reassign)
122
+
123
+ `ack` is orthogonal to delivery: a reply that sits `--unacked` is work
124
+ nobody accepted. The reassign pattern:
125
+
126
+ ```sh
127
+ # what is still open — and how long has it waited?
128
+ crewbus inbox --from orchestrator --unacked --older-than 10m
129
+
130
+ # the brief is a file: re-brief a fresh worker on the same thread
131
+ crewbus send --from orchestrator --to w9 --reply <brief-id> --body "picking this up (w3 went silent)"
132
+
133
+ # the dead watcher's mail, if any, can be replayed
134
+ crewbus redeliver --from w3 --all
135
+ ```
136
+
137
+ There is no automatic reaper: leads own the timeout policy for their
138
+ crew. `spawn --timeout 10m` records `deadlineAt` (`spawn-status` flags
139
+ passed deadlines — reap with `spawn-kill`/`stop`); `stop --all --from <you>`
140
+ terminates everything when the whole run is lost.
141
+
142
+ ## Sync partitions
143
+
144
+ - Message files are immutable with unique ids: sync is **conflict-free
145
+ union** — both sides end up with both sides' mail.
146
+ - Presence, cursors and groups merge by **hybrid logical clock +
147
+ version counter** (wall-mtime fallback for legacy docs); newer
148
+ `(hlc, v)` wins, ties keep local content and converge clocks so the
149
+ next round is `pulled 0, pushed 0`.
150
+ - **Prune stays local.** Deletions replicate only as **tombstones**
151
+ (`tombstones/*.json`, synced): a pruned message never resurrects on a
152
+ partitioned peer, but the peer's other history is untouched.
153
+ - Rounds after the first are incremental (per-peer cursor, 60s overlap);
154
+ `--dry-run` previews pulls/pushes/tombstones without touching files.
155
+
156
+ ## Worker lifetime
157
+
158
+ - `spawn` defaults to **oneshot**: headless workers (`claude -p`,
159
+ `codex exec`, `cursor-agent -p`, …) run the brief and exit. Their mail
160
+ **waits for pull** — a finished worker cannot receive push.
161
+ - `--persistent` marks long-lived peers (opencode sessions, daemons)
162
+ that stay addressable. `spawn-status` shows the recorded lifetime.
163
+ - Either way: **finished workers' DMs are files** — `inbox --from <name>`
164
+ reads them after the process is gone.
165
+ - **Session-id capture (respawn prerequisite).** Spawn boots the four
166
+ JSON-output harnesses with machine-readable logs (`opencode run
167
+ --format json`, `claude -p --output-format json`, `grok
168
+ --output-format json`, `codex exec --json`) so the harness session id
169
+ can be recovered from the worker log. `spawn-status` lazily extracts it
170
+ into `worker-sessions/<name>.json` (kept beside — not inside — the
171
+ agent doc, so presence heartbeats can never wipe it; machine-local,
172
+ never synced). Provenance is tracked (`preassigned` /
173
+ `preassigned-confirmed` / `log` / `log-override` — a disagreeing log
174
+ wins, in case the installed harness ignored the flag).
175
+ - **Pre-assigned ids (the mid-run-kill case).** Log parsing can't cover a
176
+ worker killed before emitting anything (notably grok, whose id only
177
+ arrives end-of-run). Where the CLI supports creating with an id,
178
+ `bootWorker` mints a UUID and passes it in (`claude --session-id`,
179
+ grok `-s`), so the binding holds a resumable id from boot. opencode
180
+ has no pre-set flag (its id arrives in the first stream event — the
181
+ residual window is milliseconds); codex relies on `thread.started`;
182
+ cursor/agy offer neither.
183
+ - **Respawn (`respawn --from orchestrator --to <worker>`).** Reboots one dead
184
+ worker in its *same* harness conversation: `opencode run --session`,
185
+ `claude -p --resume` (+ `CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1` so a
186
+ killed turn continues), `codex exec resume`, `grok -r`, agy
187
+ `--conversation`, cursor `--resume`; `--fresh` re-boots fresh without
188
+ prior conversation continuity. The catch-up brief points at the original prompt file
189
+ and threads the same reply id, so the worker continues instead of
190
+ restarting; codex points at the catch-up file itself (its positional
191
+ prompt can't attach files). Refuses live workers unless `--force`
192
+ (kills first, own-crew scoped like `spawn-kill`); refuses unknown,
193
+ never-captured, and pre-capture-era workers with re-brief guidance.
194
+ Attempts count on the binding; `--dry-run` previews. Orchestrator-only.
195
+
196
+ ## Poll discipline (long runs)
197
+
198
+ Plain `inbox` dumps everything — over days that burns context.
199
+ Poll digest-first instead, escalate only on hits:
200
+
201
+ 1. `crewbus inbox --from <you> --unacked --digest` — cheap
202
+ one-line-per-message sweep (`dm_inbox({ agent, unacked: true,
203
+ digest: true })` on MCP).
204
+ 2. Filtered full read — same sweep narrowed before expanding:
205
+ `inbox --from <you> --unacked --grep <pat>` /
206
+ `--priority high` (MCP: `grep` / `priority` params).
207
+ 3. `thread --id <msg-id>` / `gather` for context — only once a hit
208
+ proves worth reading.
209
+
210
+ Cadence: poll cheap and often; full reads on signal. Push wakes you;
211
+ digest tells you if it matters. Checkpoints compose: digests mark
212
+ progress notes `[checkpoint]` (skipped by `--unacked` triage, never
213
+ need ack), so the cheap poll still shows where a thread stands.
package/docs/GROUPS.md CHANGED
@@ -9,7 +9,7 @@ is replaced by the commands below.
9
9
 
10
10
  ```sh
11
11
  crewbus group create team-a --add a1,a2,a3
12
- crewbus send --from lead --to-group team-a --subject "variant: regularity" --body "..."
12
+ crewbus send --from orchestrator --to-group team-a --subject "variant: regularity" --body "..."
13
13
  crewbus gather --batch <batch> # briefs + replies + telemetry footer + contributing groups
14
14
  ```
15
15
 
@@ -20,7 +20,7 @@ crewbus gather --batch <batch> # briefs + replies + telemetry footer + contrib
20
20
  ## Replies carry artifacts
21
21
 
22
22
  ```sh
23
- crewbus send --from e1 --to lead --reply <brief-id> --artifact out/a1.json --body "done"
23
+ crewbus send --from e1 --to orchestrator --reply <brief-id> --artifact out/a1.json --body "done"
24
24
  ```
25
25
 
26
26
  `--artifact <path-or-url>` (max 500 chars) is stored on the message and
@@ -29,8 +29,8 @@ shown by `inbox` / `gather` / `thread`.
29
29
  ## Verify, then record the result
30
30
 
31
31
  ```sh
32
- crewbus ack --from lead --id <reply-id> --verify "node test/check.mjs --input out/a1.json"
33
- crewbus result record --group team-a --msg <reply-id> --artifact out/a1.json --from lead
32
+ crewbus ack --from orchestrator --id <reply-id> --verify "node test/check.mjs --input out/a1.json"
33
+ crewbus result record --group team-a --msg <reply-id> --artifact out/a1.json --from orchestrator
34
34
  crewbus result show --group team-a
35
35
  crewbus result list [--group team-a] [--json]
36
36
  ```
@@ -45,7 +45,7 @@ unless `--force` (which prints a warning to stderr).
45
45
 
46
46
  ```sh
47
47
  crewbus race start --group team-a --batch <batch> [--timeout 60000] [--json]
48
- crewbus race close --group team-a --from lead [--kill]
48
+ crewbus race close --group team-a --from orchestrator [--kill]
49
49
  ```
50
50
 
51
51
  `race start` reports the winner (recorded result whose `msgId` is in the
@@ -91,17 +91,17 @@ block assumes:
91
91
 
92
92
  - **Peer-direct for questions.** `crewbus send --from you --to-group
93
93
  <group> --subject "..." --body "..."` reaches every member of
94
- another group. Ask the group that owns a thing first; the lead is
94
+ another group. Ask the group that owns a thing first; the orchestrator is
95
95
  for approvals (`--priority high`) and scope disputes only.
96
96
  - **Channels are the shared read surface.** `crewbus channel tail
97
97
  grp-<group>` shows a group's briefs + mirrored progress; reads need
98
98
  no token. Channel *posting* is member-scoped (default-on, no flag):
99
99
  a worker may post to `grp-<group>` only when it is a MEMBER of that
100
- group — board channels and foreign groups stay lead|admin-only
100
+ group — board channels and foreign groups are orchestrator-only
101
101
  (see docs/RBAC.md).
102
102
  - **Boot habit.** `crewbus agents` + `crewbus group list` once at
103
103
  start, so a worker knows who else is here. A worker that never runs
104
- a discovery command will work star-topology through the lead — that
104
+ a discovery command will work star-topology through the orchestrator — that
105
105
  is a failure of the brief, not the worker.
106
106
  - **Scope questions stay lanes-first.** "Stay in your lane" prevents
107
107
  collisions; "DM the group that owns a thing" prevents silos. A