crewbus 11.3.1 → 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,47 +1,12 @@
1
- # Consolidator pattern (cross-group handoff)
1
+ # Consolidator Pattern
2
2
 
3
- One group rarely finishes the job. The consolidator is a reference worker
4
- that **summarizes one group's findings and hands them to the next group**
5
- (or the orchestrator): a small crew solves the easy slice first, its summary
6
- seeds the main crews' briefs.
3
+ > **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
4
+ > - Interactive Single-Page Guide: [`documentation.html#workflow`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#workflow)
5
+ > - Canonical Markdown Reference: [`docs/ARCHITECTURE.md`](file:///C:/Users/Surface/Documents/crewbus/docs/ARCHITECTURE.md)
7
6
 
8
- ## Quick use
7
+ ---
9
8
 
10
- ```sh
11
- # group A works a batch; its replies land threaded on the brief
12
- batch="<batch-id from the send echo>"
9
+ ## Consolidator Pattern
13
10
 
14
- # summarize A's transcript, DM it to the orchestrator, mirror to the group channel
15
- node examples/consolidator.mjs --from gateway --to orchestrator --batch "$batch" --group team-a
16
-
17
- # the orchestrator briefs group B with A's findings attached
18
- crewbus send --from orchestrator --to-group team-b --subject "variant: build on team-a" --body "<paste summary>"
19
- ```
20
-
21
- What the script does (all via the CLI, token-checked like any agent):
22
-
23
- 1. `gather --batch <batch> --json` — the reduce step: brief(s) + every
24
- reply, oldest first.
25
- 2. Builds an extractive summary: brief count, reply count, first line of
26
- each reply, artifact references (`send --artifact`), per-sender counts.
27
- 3. `send --from gateway --to orchestrator --reply <first-brief> --subject "RESULT: <batch>"`
28
- — the handoff, threaded so `thread --id` shows the full chain.
29
- 4. `channel post grp-team-a` — mirrors the summary to the group-scoped
30
- channel, so late joiners and sibling groups can `channel tail` it.
31
- `channel post` creates `grp-<group>` on first use; `group channel
32
- <name>` shows the mapping and post count.
33
-
34
- ## Conventions
35
-
36
- - **One consolidator per batch.** Name it `gateway` or `<group>-gateway`
37
- so `gather` transcripts stay readable.
38
- - **Summaries are untrusted peer data** like any DM: they render with the
39
- `[untrusted peer:...]` envelope. Verify before building on them —
40
- ideally `ack --verify "<checker>"` on the underlying replies first and
41
- only consolidate verified results (`result record`).
42
- - **Keep the summary short.** The script caps each reply at its first line
43
- (200 chars); for long transcripts prefer `channel summarize <chan>`
44
- or `inbox --digest --max-chars <n>` at the receiving end instead.
45
- - For racing groups, run the consolidator on the **winner only**
46
- (`race start` finds the first verified result; `race close --kill`
47
- stops the losers), then feed the winner's summary to the next stage.
11
+ - An observer pattern where a dedicated worker synthesizes and reconciles work from multiple parallel task workers.
12
+ - Gathers thread deliverables using `crewbus gather <brief-id>`.
@@ -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.