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.
- package/AGENTS.template.md +4 -4
- package/CHANGELOG.md +151 -0
- package/README.md +713 -706
- package/TEAM.template.md +1 -1
- package/bin/crewbus-hook.js +22 -5
- package/bin/crewbus-mcp.js +56 -48
- package/bin/crewbus.js +486 -355
- package/bin/lib/channels.js +1 -1
- package/bin/lib/export.js +1 -1
- package/bin/lib/groups.js +1 -5
- package/bin/lib/identity.js +92 -152
- package/bin/lib/launch.js +128 -30
- package/bin/lib/qrcode.js +2971 -0
- package/bin/lib/relay.js +26 -54
- package/bin/lib/spawn.js +241 -194
- package/bin/lib/store.js +2 -2
- package/bin/lib/web.js +277 -59
- package/claude-plugin/skills/crewbus/SKILL.md +1 -1
- package/docs/APPROVALS.md +8 -8
- package/docs/AUDIT_EXPORT.md +7 -7
- package/docs/CERT_READINESS.md +120 -120
- package/docs/COMPATIBILITY.md +196 -194
- package/docs/CONSOLIDATOR.md +6 -6
- package/docs/CONTROL_PLANE_SPEC.md +12 -14
- package/docs/CREWS.md +16 -13
- package/docs/DELIVERY.md +213 -210
- package/docs/GROUPS.md +8 -8
- package/docs/HA.md +151 -151
- package/docs/IDENTITY.md +6 -6
- package/docs/LEAD_ASSIGN.md +3 -85
- package/docs/LONG_RUNS.md +3 -3
- package/docs/M1_CLI_DRAFT.md +9 -9
- package/docs/ORCHESTRATOR.md +87 -0
- package/docs/PAIRING.md +7 -7
- package/docs/QUICKSTART.md +24 -13
- package/docs/RBAC.md +84 -73
- package/docs/SPLIT.md +82 -82
- package/docs/TENANCY.md +10 -10
- package/docs/THREAT_MODEL.md +68 -69
- package/docs/VERIFIER.md +10 -10
- package/docs/VERSION_SKEW.md +57 -57
- package/documentation.html +37 -29
- package/examples/hermes-pairing.md +3 -3
- package/examples/t3-pairing.md +1 -1
- package/index.html +13 -14
- package/opencode/plugins/dm-watch.js +1 -1
- package/opencode/tools/dm-send.js +4 -13
- package/package.json +75 -50
- package/packages/client-runtime/README.md +40 -40
- package/packages/contracts/harness.json +108 -111
- package/packages/contracts/launch.json +2 -3
- package/packages/contracts/pairing.json +3 -3
- 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
|
|
4
|
-
worker count in `/healthz`; `crew survey` shows the fleet and
|
|
5
|
-
splits an elastic crew across reachable primaries by weight
|
|
6
|
-
remainder). Standbys and unreachable relays skip loudly — they never
|
|
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
|
|
20
|
+
crewbus crew dispatch --from orchestrator \
|
|
21
21
|
--relays http://r1:8471,http://r2:8471 --weights 3,1 \
|
|
22
|
-
--count 4 --prefix w --harness
|
|
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). `--
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
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
|
|
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.
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
- `
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
#
|
|
128
|
-
crewbus
|
|
129
|
-
|
|
130
|
-
# the
|
|
131
|
-
crewbus
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
(
|
|
149
|
-
|
|
150
|
-
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
`
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
Poll
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
`
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
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
|
|
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
|
|
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
|
|
33
|
-
crewbus result record --group team-a --msg <reply-id> --artifact out/a1.json --from
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|