crewbus 11.3.0 → 11.4.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.
@@ -1,340 +1,16 @@
1
- # CrewBus Control Plane — spec (M0 frozen)
2
-
3
- Status: active build spec. Audience: contributors building the CLI launch
4
- wizard, evolved web dashboard, and mobile client in parallel.
5
-
6
- Converges spec slices 1–5: CrewBus core audit, t3Code provider pattern,
7
- t3Code UI layout, t3Code sync/connectivity/auth.
8
-
9
- Rule: the shared contract (§3) freezes first. No surface ships what the
10
- contract does not describe. Board files stay the truth; zero-dependency
11
- `bin/` core gains only additive endpoints.
12
-
13
- ## 0. Vision
14
-
15
- One launch flow everywhere:
16
-
17
- > Pick board → pick harness (detected, version-checked) → set agent count +
18
- > names → write task brief → set permission/isolation → preview dry-run →
19
- > launch locally or to the fleet → watch triage/approvals/results →
20
- > kill/respawn/ack from the same surface.
21
-
22
- No harness terminal required. Harnesses become executors behind the bus;
23
- the board remains shared memory. The DM is still the task — this plane
24
- adds no workflow engine, no cross-board queries, no hosted proxy tier.
25
-
26
- ## 1. Current state (CrewBus v7.0.0 baseline → v10.0.0 live release)
27
-
28
- ### 1.1 Board layout (`bin/lib/store.js`)
29
-
30
- `BOARD_VERSION = 2` (schema version; unrelated to package version).
31
- Resolution: `--board` flag > `--global` (`~/.crewbus/boards/default`) >
32
- `CREWBUS_DIR` env > walk-up `findBoardUpward()` > `./.crewbus`
33
- (`init` always plants where you stand).
34
-
35
- ```
36
- .crewbus/
37
- board.json {name, version:2, createdAt, acl?, quotas?, tenant?, caps?}
38
- agents/<name>.json {name, firstSeen, lastSeen, sessionId?, lastDir?,
39
- spawnedPid?, spawnedAt?, spawnedBy?, briefId?,
40
- spawnedWorktree?, spawnedBranch?, spawnedLifetime?,
41
- tokenHash, salt, expiresAt?, rotatedAt?, service?,
42
- offboarded?, role?}
43
- dm/<to>/<id>.json {id, from, to, body, at, subject?, replyTo?, batch?,
44
- checkpoint?, priority?, senderType?, sig?, fwd?}
45
- broadcast/<batch>.json ONE file for fan-outs over 20 + @all
46
- delivered/<agent>/<id>.json push markers (exclusive-create claims)
47
- acked/<agent>/<id>.json accept markers
48
- cursors/<agent>.json fast-forward pointers
49
- groups/<name>.json named recipient sets (+ restricted?, telemetry, result)
50
- channels/<name>.log.jsonl append-only shared logs
51
- locks/ results/ tombstones/ revoked/ holds/
52
- logs/<worker>-<stamp>.log + .prompt.md + <agent>.token (0600)
53
- worker-sessions/<name>.json harness session binding (machine-local, NEVER synced)
54
- sync-state/ relay.json index/broadcasts.json (derived, never synced)
55
- ```
56
-
57
- Constants: `MAX_BODY_CHARS=8000`, `MAX_RECIPIENTS=10000`, `MAX_SPAWN=20`,
58
- `BROADCAST_AFTER=20`, send rate 30/min/agent, thread `fwd` depth max 5,
59
- 10s dedupe window (`bin/lib/store.js`, `docs/LIMITS.md`).
60
- ### 1.2 CLI verbs (`bin/crewbus.js` dispatcher + `bin/lib/*`)
61
-
62
- | Verb | Key flags | Lib owner |
63
- |---|---|---|
64
- | `init [--harness opencode,claude,codex,antigravity,grok,cursor]` | `--global --board --force --no-opencode --portable` | monolith `cmdInit` |
65
- | `register --from <you>` | `--session --token --role --expires-in --service --offboard --for` | `identity.js` |
66
- | `send --from --to --body` | `--subject --reply --priority --checkpoint --sender-type --to-group --no-rate-limit --yes` | `mail.js` |
67
- | `inbox --from` | `--after --unacked --digest --grep --priority --json` | `mail.js` |
68
- | `listen --from` | `--timeout --watch` | `mail.js` |
69
- | `ack --id\|--all` | `--verify "<cmd>"` machine-verification hook | `mail.js` |
70
- | `spawn --from (--to\|--count --prefix) --body` | `--harness --cmd --cwd --worktree --branch --oneshot\|--persistent --model --max-turns --allow-tools --max-spawn --budget-tokens --budget-minutes --timeout --isolate --workdir-root --sender-type --auto --dry-run` | `spawn.js` |
71
- | `spawn-status --all\|--to` / `spawn-kill --all\|--to` / `respawn --to` / `stop --all` / `pool --count --pool-size` | `--json --force` | `spawn.js` + monolith |
72
- | `serve --port` | `--secret --allow-remote-spawn --allow-cmd --workdir-root --weight --standby --relay-interval --promote-on-miss --fence --tls-* --mtls-* --oidc-* --audit-forward` | `relay.js` |
73
- | `sync --with <url>` | `--once --interval --dry-run --secret --device --pair-token --bearer --mtls-cert --mtls-key --insecure` | `sync.js` |
74
- | `relay pair|devices|revoke-device|status|promote` | `--from --label --ttl` | `relay.js` |
75
- | `crew survey|dispatch` | `--relays --weights --count --prefix` (mirrors spawn flags) | `sync.js` |
76
- | `doctor` | `--harness --board` (wiring presence, not live behavior) | monolith |
77
- | `web --port` | `--host` (localhost default) | `web.js` |
78
- | `token rotate|status|revoke`, `acl set|show`, `group create|add|remove|show|list|delete|restrict`, `channel create|post|tail`, `result record|show|list`, `race start|close`, `lock acquire|release`, `prune --older-than`, `board export|import`, `snapshot schedule|run`, `quota set|show`, `storage`, `log [--audit] [--verify]` | per-command | `identity/groups/channels/export.js` |
79
-
80
- Hook helper: `bin/crewbus-hook.js`
81
- (`session-start|poll --style|wait|monitor|compact`).
82
- MCP server: `bin/crewbus-mcp.js` (`dm_send/dm_inbox/dm_ack/dm_gather/
83
- dm_register/dm_agents/dm_channel_post/dm_channel_tail/...`).
84
- Opencode embeds: `opencode/tools/dm-send.js` + `opencode/plugins/dm-watch.js`
85
- (`node sync-embeds.mjs --check` after edits).
86
-
87
- ### 1.3 Web dashboard today (`bin/lib/web.js`)
88
-
89
- Single `renderBoardHtml()` + snapshots
90
- (`boardSnapshot/fleetSnapshot/channelsSnapshot/resultsSnapshot/auditSnapshot`).
91
- Reads open; writes token-checked JSON-only:
92
-
93
- ```
94
- GET /api/board /api/fleet /api/channels /api/results /api/audit
95
- GET /api/inbox?agent=<name>&unacked=1&limit=50
96
- POST /api/kill {from, token, to[]|all:true}
97
- POST /api/ack {from, token, id|all:true}
98
- POST /api/approve {from, token, id, decision}
99
- GET /api/events (SSE)
100
- ```
101
-
102
- 5s poll. Kill/ack need the same CLI token; tokens stay in the tab.
103
- Missing: launch wizard, harness picker, pairing UI, route management.
104
-
105
- ### 1.4 Identity + RBAC (`bin/lib/identity.js`, `docs/RBAC.md`, `docs/IDENTITY.md`)
106
-
107
- First claim wins (`writeExclusiveJson`); salted `tokenHash+salt`, never
108
- plaintext; `expiresAt/rotatedAt/service/offboarded`; `revoked/` union
109
- (copy-if-missing, never undone). Secrets stripped on sync/push/serve/JSON
110
- output; local secrets always win merges. Roles `{orchestrator, worker}`
111
- (the board bootstraps one orchestrator; self-registrations are workers); `checkToken()` THEN
112
- `authorize()` — never merged, never reordered. Leads kill own crew only;
113
- auditors read-only; `acl {defaultRole, frozen}` per board; `group restrict`
114
- for private crews.
115
-
116
- ### 1.5 Sync + relay + HA (`bin/lib/sync.js`, `bin/lib/relay.js`, `docs/HA.md`, `docs/PAIRING.md`)
117
-
118
- `SYNC_SUBS=[dm,broadcast,delivered,acked,cursors,agents,groups,tombstones,
119
- channels,revoked,holds]`; `SYNC_UNION` copy-if-missing; `SYNC_LWW` HLC
120
- `(hlc,v)`; channel line-merge; per-peer cursor + 60s overlap;
121
- `RELAY_CAPS=[hlc,tombstones,channels,revoked,holds,tls,mtls,oidc,standby,
122
- audit-forward]`; manifest negotiates, legacy = 4.0 baseline, `SUB_CAP_NOTE`
123
- wording on degrade. Secrets: `x-crewbus-secret` / `?secret=` constant-time;
124
- `/api/spawn|kill` opt-in; remote `--cmd` allowlist; `cwd` under
125
- `--workdir-root`; `relay pair` single-use `abp-…` → device `abd-…`
126
- (relay-local, never synced/exported, hashed at rest, revocable, audited).
127
- Standby: one writer, pull loop, `503 + X-Relay-Role: standby` on writes,
128
- `/healthz` `{role,primary,lagMs,...}`, manual `relay promote` recommended,
129
- `--promote-on-miss` + `--fence` opt-in. Transport = operator mesh VPN
130
- (Tailscale recommended, never a dependency). Weighted crews: `crew survey`
131
- (role/weight/workers/lag) + `crew dispatch` largest-remainder split.
132
- ### 1.6 Seven-harness matrix (`spawn.js`, `docs/COMPATIBILITY.md`)
133
-
134
- `buildSpawnTarget()` maps harness → `{exe, args, shell, stdinPath?}`.
135
- `bootWorker()` writes the prompt file, launches detached with
136
- `CREWBUS_DIR/CREWBUS_AGENT` (secrets scrubbed), records pid + binding,
137
- lazily fills `worker-sessions/<name>.json` (machine-local, NEVER synced).
138
-
139
- | Harness | Spawn | Brief | Session capture | Respawn |
140
- |---|---|---|---|---|
141
- | opencode | `run --file <brief> --format json` | file | early stream event | `run --session <id>` |
142
- | claude | `-p --output-format json --session-id <uuid> --allowedTools ...` | stdin | preassigned + log | `-p --resume <id>` + resume-interrupted env |
143
- | codex | `exec --json -c approval_policy="never" --dangerously-bypass-hook-trust` | stdin + positional | `thread.started.thread_id` | `exec <opts> resume <id> "<catchup>"` |
144
- | grok | `--prompt-file -s <uuid> --output-format json` | file | preassigned (end-of-run log) | `--prompt-file <catchup> -r <id>` |
145
- | antigravity | `--print --mode accept-edits` | inline | none | `-p "<catchup>" --conversation <id>` (rare) |
146
- | cursor | `cursor-agent -p --force --trust` | inline | none | `-p --force --resume <id>` (rare) |
147
-
148
- `--auto` per harness: opencode auto-approve, claude `--dangerously-skip-permissions`, codex `--dangerously-bypass-approvals-and-sandbox`, grok `--permission-mode bypassPermissions --always-approve`, cursor `--yolo`, agy `--dangerously-skip-permissions`.
149
- Requires `--i-understand-danger` (or TTY `yes`) + sandbox warning
150
- (`docs/ISOLATION.md`). cursor/agy resume = honestly unsupported until
151
- vendors emit stable ids. `doctor` checks wiring presence, not live behavior.
152
- Windows: native `.exe` binaries launch directly via `resolveHarnessExe` with `shell: false` (exact PID tracking, immediate unbuffered stdio); legacy `.cmd` shims route safely through `resolveShellShot`.
153
-
154
- ### 1.7 Extension points (where the plane hooks in)
155
-
156
- | Plane feature | Exact hook |
157
- |---|---|
158
- | `launch` wizard | wrap `bootWorker()` + `remoteSpawn`; preview via `formatSpawnCmd()`; NEVER a new spawn path |
159
- | `harnesses detect` | `buildSpawnTarget()` arg knowledge + `doctor` checks + `<binary> --version` probes (tolerant) |
160
- | Harness picker UI | `GET /api/harnesses` over `packages/contracts/harness.json` + live detect |
161
- | `pair qr` / mobile pairing | wrap `newPairToken()`; QR encodes `crewbus://pair?...#abp-…` (fragment secret) |
162
- | Routes / env identity | extend `relay.json` + `/healthz` with `envId + advertisedRoutes + capabilities` |
163
- | `POST /api/launch` | same validation as wizard → `bootWorker` local or `remoteSpawn` per relay |
164
- | Web Dashboard | standalone loopback dashboard via `crewbus web [--open]` with /pair route |
165
- | Mobile client | `GET /api/*` + `POST /api/launch|kill|ack|approve` + `/sync/wait`; no FS access |
166
- | Scoped device creds | extend `parseDeviceCred` + `requireRelaySecret` → `requireScope(rpc)` |
167
- ## 2. t3Code lessons (reference: `pingdotgg/t3code`)
168
-
169
- ### 2.1 Provider abstraction — normalize at the adapter
170
-
171
- Orchestration never branches on provider. Driver = integration kind;
172
- instance = one config + account lifecycle; route work by instance.
173
- Quirks quarantined per adapter: opencode 1.x (server per thread) vs 2.x
174
- (server per instance + per-thread MCP entry + deny-others); Claude
175
- multi-account via `CLAUDE_CONFIG_DIR` instances; Codex `/goal` multi-turn
176
- + non-blocking questions; Antigravity profile isolation + ambient cred
177
- stripping + immutable releases; Grok probes never auth as a side effect;
178
- capabilities describe what the provider CAN do (no-rollback rejects
179
- revert BEFORE touching files).
180
-
181
- ### 2.2 Ownership + settings
182
-
183
- Execution belongs to the environment owning the workspace; clients control
184
- over RPC; shared client-runtime; RPC contract is the version boundary;
185
- subscriptions send only viewed state; event log is source of truth.
186
- Client prefs stay in client; env defaults + project overrides on server;
187
- `All environments` = bulk edit, not a durable global.
188
-
189
- ### 2.3 UI layout (spec-ui brief, landed)
190
-
191
- Sidebar: Pinned / Active / Settled + Snoozed + Archived; drag rows to
192
- change state; 5s Undo toast; `Ctrl+K` palette + message search; drag files
193
- to attach. New crew keeps project + harness/mode unless dest overrides;
194
- `No project` scratch; background-send; multi-harness fanout. Composer:
195
- chips for files/crews, queue-vs-steer, mobile offline queue. Picker in
196
- heading: remembers harness + options, project overrides, honest fallbacks
197
- (Grok→Supervised, OpenCode/Antigravity→ask). Permission modes per crew:
198
- Supervised / Auto-accept edits / Auto / Full access.
199
- ### 2.4 Connection + remote + auth
200
-
201
- One retry owner (jittered backoff, 5min cap); foreground probes before
202
- reconnect; registry per environment; transport-health vs data-freshness
203
- separated; offline-readable cache; mutations never auto-replayed. Env
204
- stable ID across restarts; advertised endpoints are hints; ordered routes
205
- first-that-works + preflight + cooldown; learned LAN/tailnet routes;
206
- pairing secret in URL FRAGMENT never query; clients use advertised caps.
207
- Env issues own sessions; per-RPC scope checks; pairing narrows scopes only;
208
- creation response alone returns raw credential; DPoP binds proof key.
209
-
210
- ## 3. Shared contract (FROZEN — M0 exit)
211
-
212
- Lives in `packages/contracts/`. All four surfaces implement against it.
213
-
214
- ### 3.1 Harness adapters (`harness.json`)
215
-
216
- One entry per driver: `{driver, displayName, binary, versionProbe,
217
- briefDelivery: file|stdin|inline, sessionCapture: preassigned|log|none,
218
- resume: true|false, capabilities:{...}, permissionMap:{...}}`.
219
- cursor/agy ship `resume:false` + `sessionCapture:none` — UIs render
220
- `resume unsupported` instead of faking continuity.
221
-
222
- ### 3.2 Launch RPC (`launch.json` + `POST /api/launch`)
223
-
224
- Request: `{board?, harness, count, prefix?, to?, body, subject?,
225
- priority?, model?, maxTurns?, allowTools?, permission:
226
- supervised|autoEdits|auto|full, isolate?, worktree?|branch?,
227
- oneshot|persistent, budgetTokens?, budgetMinutes?, timeout?,
228
- target: local|relays[{url,weight}], dryRun?}`.
229
- Response: `{crewId, batch, workers[{name,pid?,replyId,relay?}], warnings[]}`.
230
- Permission mapping: supervised = no `--auto`; autoEdits = harness middle
231
- ground or supervised + loud note; auto = `--auto` + sandbox warning;
232
- full = `--auto --i-understand-danger` + isolate recommended.
233
-
234
- ### 3.3 Env identity + routes
235
-
236
- `relay.json` + `/healthz` gain `{envId (stable uuid), advertisedRoutes[],
237
- capabilities[]}`. `GET /api/routes` lists ordered routes. Clients walk
238
- first-that-works, preflight earlier routes, learn LAN/tailnet, never fall
239
- back to loopback silently.
240
-
241
- ### 3.4 Pairing (`pairing.json`)
242
-
243
- `POST /api/pair/issue` (orchestrator) → one-time
244
- `crewbus://pair?env=<id>&routes=<json>&caps=<…>#<abp-…>` (secret in
245
- FRAGMENT; QR renders the same). `POST /api/pair/exchange` swaps once for
246
- `abd-…` with requested scopes ⊆ granted (narrow-only). Devices relay-local,
247
- hashed at rest, revocable, audited, never synced/exported.
248
-
249
- ### 3.5 Auth scopes
250
-
251
- Device creds gain `scopes[]` (default = today's full device). New pairs
252
- request narrowed (`launch:spawn/kill`, `mail:send/inbox/ack`, `fleet:read`,
253
- `admin:pair/revoke`). `requireRelaySecret` → `requireScope(rpc)`. Agent
254
- tokens + RBAC (`checkToken` then `authorize`) unchanged.
255
-
256
- ### 3.6 Board caps
257
-
258
- `board.json` gains `caps[]` (subset of `RELAY_CAPS + [launch]`).
259
- Mixed-version peers degrade with `SUB_CAP_NOTE` wording, never 500.
260
- ## 4. Surfaces (same IA, same contract)
261
-
262
- ### 4.1 CLI (`bin/`, zero-dep stays)
263
-
264
- `crewbus launch` wizard (TTY prompts; `--yes/--json/--dry-run` headless):
265
- board → `harnesses detect` table (binary? version? flags? auth?) →
266
- harness → count/prefix/names → brief (8000-char guard + split guidance) →
267
- model/turns/tools → permission segmented → isolate/worktree/lifetime/
268
- budget/timeout → target (local or `crew survey` fleet + weights) →
269
- dry-run preview (`formatSpawnCmd`) → launch. Thin over
270
- `bootWorker`/`remoteSpawn`. New: `harnesses [detect --json]`,
271
- `pair [issue|qr|devices|revoke]`, `serve --advertise-routes --pair-qrcode`.
272
- Every existing verb untouched.
273
-
274
- ### 4.2 Web dashboard (evolve `bin/lib/web.js`, no build step v1)
275
-
276
- AppRoot: left nav (Boards, Crews, Fleet, Channels, Triage, Approvals,
277
- Results, Audit, Settings); top bar (env/board picker + harness picker +
278
- connection dot + `Ctrl+K`); center launch panel (harness cards with detect
279
- state, count stepper, brief composer, permission segmented, dry-run diff);
280
- right inspector (state/pid/reply/acked/log tail/session id + kill/respawn/
281
- ack). Reuse snapshot shapes; add `GET /api/harnesses`, `GET /api/routes`,
282
- `POST /api/launch`, `POST /api/pair/issue|exchange`. Poll 5s → SSE later.
283
- Tokens in tab memory (opt-in persist).
284
-
285
- ### 4.3 Web Dashboard & Pair (`crewbus web`)
286
-
287
- Same web UI via local scheme; main owns sidecar
288
- (`node bin/crewbus.js serve --port 0` loopback), SSH tunnels, pairing
289
- window, background service; `Local environment` toggle for remote-only
290
- (no state deletion). One-day Tauri-vs-Electron spike in Phase 0.
291
-
292
- ### 4.4 Mobile (`apps/mobile`, Expo, remote-only v1)
293
-
294
- QR pair → ordered + learned routes → triage/approve/kill/launch cards;
295
- offline inbox/draft cache + explicitly-retried mutation queue (never
296
- auto-replayed); biometric credential store; no local exec; long-poll +
297
- foreground refresh v1 (no FCM).
298
-
299
- ## 5. Information architecture (all GUIs)
300
-
301
- Boards (tenants, one dir each) → Crews (launch groups) → Workers;
302
- Triage (unacked, digest-first); Approvals (high-priority, approve/deny);
303
- Channels / Groups / Results & races / Fleet / Audit / Settings.
304
- Do: digest-first, per-sender order, `[untrusted peer]` envelopes, Undo
305
- toasts, `Ctrl+K` everything. Don't: workflow engine, cross-board queries,
306
- secret sync, mutation auto-replay, silent loopback fallback.
307
-
308
- ## 6. Repo shape + milestones
309
-
310
- ```
311
- crewbus/ bin/ + bin/lib/* (additive only)
312
- packages/contracts/ harness.json launch.json pairing.json board-caps.json
313
- packages/client-runtime/ supervisor, routes, auth store, cache, hooks
314
- apps/mobile/
315
- docs/CONTROL_PLANE_SPEC.md (this file)
316
- test/crewbus.control-plane.mjs
317
- ```
318
-
319
- M0 contract freeze + M1 CLI launch shipped (`2a1015c`) → M2 web AppRoot shipped (`3715344`) + M3 client-runtime shipped (`46e8989`) → M4 desktop shipped (`2972b1c`) → M5 mobile shipped (`7569ddd`) → M6 hardening as M6-lite scope enforcement / standby pair-503s / dashboard live refresh shipped (`0893026`) plus this M6 docs tail (COMPATIBILITY refresh + version-skew matrix, no code changes).
320
-
321
- ## 7. Test plan
322
-
323
- `npm test` stays green throughout. New `test/crewbus.control-plane.mjs`:
324
- every COMPATIBILITY harness has a contracts entry with required fields;
325
- launch schema round-trips; pairing URL keeps secret in fragment;
326
- scope exchange narrows-only; caps degrade with `SUB_CAP_NOTE` wording;
327
- `launch --dry-run` previews exact commands without booting.
328
-
329
- ## 8. Risks
330
-
331
- cursor/agy session ids (report unsupported, never fake); mobile sockets
332
- (foreground re-probe + queued mutations); Windows `cmd.exe` ~60s tails
333
- (size supervision windows); secrets UX (QR + fragment + biometric +
334
- `devices` lastSeen review); version skew (caps, never 500); scope discipline
335
- (no engine, no cross-board search, no hosted proxy).
336
-
337
-
338
-
339
-
340
-
1
+ # Control Plane Specification
2
+
3
+ > **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
4
+ > - Interactive Single-Page Guide: [`documentation.html#control-plane`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#control-plane)
5
+ > - Canonical Markdown Reference: [`docs/ARCHITECTURE.md`](file:///C:/Users/Surface/Documents/crewbus/docs/ARCHITECTURE.md)
6
+
7
+ ---
8
+
9
+ ## Control Plane Architecture
10
+
11
+ - Governed by frozen v1 contracts in `packages/contracts/`:
12
+ - `launch.json` (Launch requests and permission mapping)
13
+ - `harness.json` (7 AI harness drivers and CLI flags)
14
+ - `pairing.json` (QR and relay pairing with fragment secrets)
15
+ - `board-caps.json` (Feature negotiation and capability degradation)
16
+ - Implemented via `crewbus launch`, `crewbus harnesses detect`, `crewbus web`, and `packages/client-runtime/`.
package/docs/CREWS.md CHANGED
@@ -1,58 +1,13 @@
1
- # Weighted remote crews
1
+ # Mixed-Harness Crews & Relays
2
2
 
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.
3
+ > **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
4
+ > - Interactive Single-Page Guide: [`documentation.html#control-plane`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#control-plane)
5
+ > - Canonical Markdown Reference: [`docs/ARCHITECTURE.md`](file:///C:/Users/Surface/Documents/crewbus/docs/ARCHITECTURE.md)
8
6
 
9
- ## Survey the fleet
7
+ ---
10
8
 
11
- ```sh
12
- crewbus crew survey --relays http://r1:8471,http://r2:8471 [--json]
13
- # http://r1:8471 role=primary weight=3 workers=2 lagMs=- uptimeSec=400
14
- # http://r2:8471 role=primary weight=1 workers=0 lagMs=- uptimeSec=390
15
- ```
9
+ ## Fleet Coordination
16
10
 
17
- ## Dispatch
18
-
19
- ```sh
20
- crewbus crew dispatch --from orchestrator \
21
- --relays http://r1:8471,http://r2:8471 --weights 3,1 \
22
- --count 4 --prefix w --harness opencode \
23
- --body "Triage batch 7…" --secret s3 [--dry-run]
24
- # dispatched 3/3 to http://r1:8471 [weight 3]
25
- # w-1 pid 7436 reply msg-…
26
- # dispatched 1/1 to http://r2:8471 [weight 1]
27
- # w-4 pid 4668 reply msg-…
28
- ```
29
-
30
- Flags mirror `spawn` (`--harness/--cmd/--cwd/--model/--max-turns/
31
- --allow-tools/--auto/--subject/--priority/--sender-type/--keep-env/
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.
39
-
40
- ## Credentials per relay
41
-
42
- Repeat `--relay-auth <url-prefix>=<cred>` for relays that don't share one
43
- secret (`abd-…` values go out as device credentials, anything else as the
44
- shared secret; longest prefix wins). Bare `--secret` / `--device` /
45
- `CREWBUS_*` apply to every relay. Pair each relay first
46
- (`relay pair`, see `docs/PAIRING.md`) and you never share a secret at all.
47
-
48
- ## Properties
49
-
50
- - **Weights are preferences, not quotas.** A relay that goes unreachable or
51
- standby mid-dispatch is skipped; its share is *not* re-dealt (no double
52
- boot) — the summary shows what landed where, and you re-dispatch the rest.
53
- - **Standbys never boot.** They refuse writes with 503; dispatch skips them
54
- loudly rather than queueing into a replica.
55
- - **Deterministic shares.** Same weights + count always split the same way,
56
- so `--dry-run` predicts the real run and tests can assert distributions.
57
- - **Audited both ends.** The caller's board records `crew-dispatch` (relays,
58
- count, shares); each relay records its own `remote-spawn` audit trail.
11
+ - Spawning mixed-harness crews: `--harness claude,opencode,codex`.
12
+ - Dynamic model selection per worker: `--model a,b,c`.
13
+ - Weighted relay dispatching and survey queries.
package/docs/DELIVERY.md CHANGED
@@ -1,3 +1,5 @@
1
+ > **Unified Documentation:** See [`documentation.html#delivery`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#delivery) and [`docs/ARCHITECTURE.md`](file:///C:/Users/Surface/Documents/crewbus/docs/ARCHITECTURE.md).
2
+
1
3
  # Delivery semantics
2
4
 
3
5
  How the bus behaves when things go wrong. Read this before building
@@ -1,56 +1,11 @@
1
- # Experiments: does the peer-to-peer part matter?
1
+ # Benchmarking & Ablation Experiments
2
2
 
3
- Goal: test whether crewbus's peer-to-peer messaging (vs a simple
4
- orchestrator or native subagents) changes outcomes — using public models,
5
- cheap tasks, and published negative results.
3
+ > **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
4
+ > - Interactive Single-Page Guide: [`documentation.html#scale-limits`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#scale-limits)
5
+ > - Canonical Markdown Reference: [`docs/COMPATIBILITY.md`](file:///C:/Users/Surface/Documents/crewbus/docs/COMPATIBILITY.md)
6
6
 
7
- ## Tasks (cheap, objective verifiers only)
7
+ ---
8
8
 
9
- 1. **Constraint puzzles** — e.g. small SAT/scheduling instances with a
10
- script checker. Verifier: the checker script, exit 0/1.
11
- 2. **Small formal proofs** — toy theorems with a machine-checkable proof
12
- (Lean or a purpose-built checker). Verifier: the checker.
13
- 3. **TDD code tasks** — a failing test suite ships with the task; the agent
14
- edit must turn it green without breaking the rest. Verifier: the suite.
15
- 4. **One cross-dependency task** — lateral messaging should help here if it
16
- helps anywhere: subproblems with discovered couplings (e.g. part A's
17
- interface choice constrains part B), where workers must negotiate the
18
- seam. Verifier: joint test suite + seam contract check.
9
+ ## Benchmark Suites
19
10
 
20
- Every task must state its verifier command up front. No verifier, no
21
- experiment. Suggested: `ack --verify "<command>"`-style hooks so acceptance
22
- can be automatic (see review §4.2).
23
-
24
- ## Conditions (ablate the structure)
25
-
26
- - single agent (baseline)
27
- - native subagents of one harness (vendor baseline)
28
- - orchestrator script (fan-out, collect, no lateral mail)
29
- - crewbus DMs only
30
- - DMs plus shared channel (`channel post` / `tail`)
31
- - plus consolidator (a reference reducer worker summarizing group findings)
32
-
33
- ## Scaling curves
34
-
35
- Group sizes 1 / 4 / 16 / 64 / 256 against: success rate, wall-clock time,
36
- and cost (tokens + compute). Repeat every cell — agent runs are noisy, so
37
- report means with spread, never single runs.
38
-
39
- ## Message audit rubric
40
-
41
- Sample messages from each run and classify each as:
42
-
43
- - **useful** — changed a decision, carried a result, prevented rework;
44
- - **redundant** — restated known state, duplicate, noise;
45
- - **harmful** — wrong direction, stale pointer acted on, prompt-injected.
46
-
47
- Report the mix per condition: a win on success rate with 80% redundant
48
- traffic is a different finding than a lean win.
49
-
50
- ## Reporting policy (negative results required)
51
-
52
- Publish negative results. If P2P does not beat a simple orchestrator, say
53
- so — the project keeps a defensible smaller claim (best cross-harness
54
- messaging layer) and the field learns something. File every run as:
55
- task + verifier + condition + group size + repeats + success/time/cost +
56
- message-audit sample, with hardware and model versions pinned.
11
+ - Run `npm run bench` and `npm run bench:load` to measure local board latency and throughput.
package/docs/GROUPS.md CHANGED
@@ -1,109 +1,13 @@
1
- # Groups, outcomes, races (Review §4.3)
2
-
3
- Groups are named recipient sets for variant briefs. Outcomes are native
4
- records — the interim workaround (one group per approach + `RESULT:`
5
- subjects + a verifier agent + a `gather --json` script + `spawn-kill`)
6
- is replaced by the commands below.
7
-
8
- ## Curate + brief + reduce
9
-
10
- ```sh
11
- crewbus group create team-a --add a1,a2,a3
12
- crewbus send --from orchestrator --to-group team-a --subject "variant: regularity" --body "..."
13
- crewbus gather --batch <batch> # briefs + replies + telemetry footer + contributing groups
14
- ```
15
-
16
- `gather --batch` prints a telemetry footer
17
- (`msgs, ~tokens (chars/4), contributing groups`) and the same fields in
18
- `--json` (`contributingGroups`, `telemetry`).
19
-
20
- ## Replies carry artifacts
21
-
22
- ```sh
23
- crewbus send --from e1 --to orchestrator --reply <brief-id> --artifact out/a1.json --body "done"
24
- ```
25
-
26
- `--artifact <path-or-url>` (max 500 chars) is stored on the message and
27
- shown by `inbox` / `gather` / `thread`.
28
-
29
- ## Verify, then record the result
30
-
31
- ```sh
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
- crewbus result show --group team-a
35
- crewbus result list [--group team-a] [--json]
36
- ```
37
-
38
- `results/<group>.json` holds ONE record
39
- `{group, artifact, by, msgId, verifierOutput, at}` — first verified
40
- result wins. Only verified messages are recordable: the ack marker
41
- `acked/*/<msgId>.json` must carry `verified:true`, else recording fails
42
- unless `--force` (which prints a warning to stderr).
43
-
44
- ## Race mode
45
-
46
- ```sh
47
- crewbus race start --group team-a --batch <batch> [--timeout 60000] [--json]
48
- crewbus race close --group team-a --from orchestrator [--kill]
49
- ```
50
-
51
- `race start` reports the winner (recorded result whose `msgId` is in the
52
- batch, else the first verified ack on a batch reply) or "no verified
53
- result yet". `--timeout` polls instead of checking once; there is no
54
- daemon. `race close` DMs "race closed by X" to every other member and,
55
- with `--kill`, terminates their spawned pids.
56
-
57
- ## Status + telemetry
58
-
59
- ```sh
60
- crewbus group status team-a [--json] # running (pid alive), replies, verified, spend
61
- crewbus group telemetry team-a [--json] # {messages, tokensEst, wallClockMs, members, verifiedCount}
62
- ```
63
-
64
- Spend = message count + wall-clock since the group `createdAt` +
65
- token estimate (`chars/4` over member bodies+subjects). `createdAt` is
66
- backfilled from the group file mtime for pre-existing groups.
67
-
68
- ## Attribution (agents in several groups)
69
-
70
- - A reply attributes via its chain: `--reply <msg-id>` → root brief →
71
- batch → group(s) whose members appear in the transcript.
72
- - `gather --batch` shows `contributing groups` (groups with ≥1 message
73
- from a member in the transcript).
74
- - `result record` **requires `--group` explicitly** — there is no
75
- auto-assign. When an agent is in several groups, the recorder decides
76
- which group the result counts for.
77
-
78
- ## Cross-group collaboration
79
-
80
- Groups share one board, so any member can already read anything. The
81
- thing that decides whether groups actually collaborate is whether the
82
- brief tells them the map. Since v10.0.x every `spawn` brief carries a
83
- **Crew:** block (see `buildCrewContext` in `bin/lib/spawn.js`): your
84
- group(s) + members + lane, the sibling groups of the same spawn +
85
- members, their group channels, and the peer-DM norm. Groups from
86
- unrelated concurrent briefs are deliberately NOT enumerated — they
87
- collapse to a count (`N other groups exist on this board`), so
88
- cross-task rosters stay discoverable (`crewbus group list`) without
89
- becoming prompt noise or a misleading invitation. Conventions that
90
- block assumes:
91
-
92
- - **Peer-direct for questions.** `crewbus send --from you --to-group
93
- <group> --subject "..." --body "..."` reaches every member of
94
- another group. Ask the group that owns a thing first; the orchestrator is
95
- for approvals (`--priority high`) and scope disputes only.
96
- - **Channels are the shared read surface.** `crewbus channel tail
97
- grp-<group>` shows a group's briefs + mirrored progress; reads need
98
- no token. Channel *posting* is member-scoped (default-on, no flag):
99
- a worker may post to `grp-<group>` only when it is a MEMBER of that
100
- group — board channels and foreign groups are orchestrator-only
101
- (see docs/RBAC.md).
102
- - **Boot habit.** `crewbus agents` + `crewbus group list` once at
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 orchestrator — that
105
- is a failure of the brief, not the worker.
106
- - **Scope questions stay lanes-first.** "Stay in your lane" prevents
107
- collisions; "DM the group that owns a thing" prevents silos. A
108
- brief should name both the boundary *and* the bridge.
109
-
1
+ # Groups & Member-Scoped Channels
2
+
3
+ > **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
4
+ > - Interactive Single-Page Guide: [`documentation.html#layout`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#layout)
5
+ > - Canonical Markdown Reference: [`docs/ARCHITECTURE.md`](file:///C:/Users/Surface/Documents/crewbus/docs/ARCHITECTURE.md)
6
+
7
+ ---
8
+
9
+ ## Groups & Channels
10
+
11
+ - Group creation: `crewbus group create <name> --members a,b,c`.
12
+ - Scoped channels: `grp-<name>` channels permit postings only from members of that group.
13
+ - Context isolation: Task-scoped briefs include relevant groups only, preventing cross-task leaks.