crewbus 10.0.11 → 11.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/AGENTS.template.md +4 -4
  2. package/CHANGELOG.md +151 -0
  3. package/README.md +713 -706
  4. package/TEAM.template.md +1 -1
  5. package/bin/crewbus-hook.js +22 -5
  6. package/bin/crewbus-mcp.js +56 -48
  7. package/bin/crewbus.js +486 -355
  8. package/bin/lib/channels.js +1 -1
  9. package/bin/lib/export.js +1 -1
  10. package/bin/lib/groups.js +1 -5
  11. package/bin/lib/identity.js +92 -152
  12. package/bin/lib/launch.js +128 -30
  13. package/bin/lib/qrcode.js +2971 -0
  14. package/bin/lib/relay.js +26 -54
  15. package/bin/lib/spawn.js +241 -194
  16. package/bin/lib/store.js +2 -2
  17. package/bin/lib/web.js +277 -59
  18. package/claude-plugin/skills/crewbus/SKILL.md +1 -1
  19. package/docs/APPROVALS.md +8 -8
  20. package/docs/AUDIT_EXPORT.md +7 -7
  21. package/docs/CERT_READINESS.md +120 -120
  22. package/docs/COMPATIBILITY.md +196 -194
  23. package/docs/CONSOLIDATOR.md +6 -6
  24. package/docs/CONTROL_PLANE_SPEC.md +12 -14
  25. package/docs/CREWS.md +16 -13
  26. package/docs/DELIVERY.md +213 -210
  27. package/docs/GROUPS.md +8 -8
  28. package/docs/HA.md +151 -151
  29. package/docs/IDENTITY.md +6 -6
  30. package/docs/LEAD_ASSIGN.md +3 -85
  31. package/docs/LONG_RUNS.md +3 -3
  32. package/docs/M1_CLI_DRAFT.md +9 -9
  33. package/docs/ORCHESTRATOR.md +87 -0
  34. package/docs/PAIRING.md +7 -7
  35. package/docs/QUICKSTART.md +24 -13
  36. package/docs/RBAC.md +84 -73
  37. package/docs/SPLIT.md +82 -82
  38. package/docs/TENANCY.md +10 -10
  39. package/docs/THREAT_MODEL.md +68 -69
  40. package/docs/VERIFIER.md +10 -10
  41. package/docs/VERSION_SKEW.md +57 -57
  42. package/documentation.html +37 -29
  43. package/examples/hermes-pairing.md +3 -3
  44. package/examples/t3-pairing.md +1 -1
  45. package/index.html +13 -14
  46. package/opencode/plugins/dm-watch.js +1 -1
  47. package/opencode/tools/dm-send.js +4 -13
  48. package/package.json +75 -50
  49. package/packages/client-runtime/README.md +40 -40
  50. package/packages/contracts/harness.json +108 -111
  51. package/packages/contracts/launch.json +2 -3
  52. package/packages/contracts/pairing.json +3 -3
  53. package/docs/DESKTOP_SPIKE.md +0 -223
@@ -6,8 +6,8 @@
6
6
  "note": "Same validation as CLI launch wizard. Thin over bootWorker (local) or remoteSpawn (per relay). dryRun previews exact commands without booting.",
7
7
  "request": {
8
8
  "required": ["harness", "body"],
9
- "optional": ["board", "count", "prefix", "to", "subject", "priority", "model", "maxTurns", "allowTools", "permission", "isolate", "worktree", "branch", "lifetime", "budgetTokens", "budgetMinutes", "timeout", "target", "dryRun", "lead"],
10
- "defaults": { "count": 1, "permission": "supervised", "lifetime": "oneshot", "target": "local", "dryRun": false, "lead": "auto" },
9
+ "optional": ["board", "count", "prefix", "to", "subject", "priority", "model", "models", "orchestratorModel", "maxTurns", "allowTools", "permission", "isolate", "worktree", "branch", "lifetime", "budgetTokens", "budgetMinutes", "timeout", "target", "dryRun"],
10
+ "defaults": { "count": 1, "permission": "supervised", "lifetime": "oneshot", "target": "local", "dryRun": false },
11
11
  "constraints": {
12
12
  "harness": "one of harness.json drivers",
13
13
  "body": "max 8000 chars (MAX_BODY_CHARS)",
@@ -15,7 +15,6 @@
15
15
  "permission": "supervised|autoEdits|auto|full",
16
16
  "lifetime": "oneshot|persistent",
17
17
  "priority": "high|normal",
18
- "lead": "auto|board|none",
19
18
  "target": "local | {relays:[{url,weight}]}"
20
19
  },
21
20
  "permissionMapping": {
@@ -16,10 +16,10 @@
16
16
  "treat pairing URLs + abd- creds as passwords (no screenshots/logs/bug reports)"
17
17
  ],
18
18
  "endpoints": {
19
- "issue": "POST /api/pair/issue (admin, token-checked; body {label?, ttl?, scopes?}) -> {pairUrl, expiresAt}",
19
+ "issue": "POST /api/pair/issue (orchestrator, token-checked; body {label?, ttl?, scopes?}) -> {pairUrl, expiresAt}",
20
20
  "exchange": "POST /api/pair/exchange (body {pairToken, label?, scopes?}) -> {deviceId, credential (abd-..., once only)}; requested scopes must be subset of granted (narrow-only, never widen)",
21
- "devices": "GET /api/pair/devices (admin) -> [{id, label, by, lastSeen, revoked?}]",
22
- "revoke": "POST /api/pair/revoke (admin; body {deviceId}) -> immediate 403 on next use"
21
+ "devices": "GET /api/pair/devices (orchestrator) -> [{id, label, by, lastSeen, revoked?}]",
22
+ "revoke": "POST /api/pair/revoke (orchestrator; body {deviceId}) -> immediate 403 on next use"
23
23
  },
24
24
  "scopes": ["launch:spawn", "launch:kill", "mail:send", "mail:inbox", "mail:ack", "fleet:read", "admin:pair", "admin:revoke"],
25
25
  "defaultScope": "full device (today's secret-equivalent) unless narrowed at exchange",
@@ -1,223 +0,0 @@
1
- # M4 desktop spike — Tauri vs Electron (decision record)
2
-
3
- Status: DECIDED — **Tauri** (confirms `docs/CONTROL_PLANE_SPEC.md` §4.3 preference).
4
- Scaffold: `apps/desktop/` (static, hand-written on a machine with NO Rust
5
- toolchain — nothing here has been compiled; see `apps/desktop/README.md`).
6
-
7
- Sources read for this spike (2026-10-06):
8
-
9
- - `docs/CONTROL_PLANE_SPEC.md` §4.3 (Desktop: same web UI via local scheme,
10
- main owns sidecar `node bin/crewbus.js serve --port 0` on loopback, SSH
11
- tunnels, pairing window, background service, `Local environment` toggle
12
- for remote-only) + §5 (IA: Boards → Crews → Workers; digest-first; no
13
- engine, no cross-board queries, no secret sync, no mutation auto-replay,
14
- no silent loopback fallback).
15
- - `packages/client-runtime/README.md` + `index.js`/`supervisor.js`/`auth.js`:
16
- runtime-agnostic Supervisor (single retry owner, jittered backoff, 5min
17
- cap), route-walk (`fetchAdvertisedRoutes`/`walkRoutes`, loopback only with
18
- `allowLoopback: true` — desktop-sidecar-only flag), `parsePairUrl()`
19
- (secret from `#fragment` only, query secrets throw), narrow-only scopes,
20
- cache with explicitly-retried mutation queue.
21
- - Pairing fragment rule (frozen M0): `packages/contracts/pairing.json`
22
- (`pairUrlRules`: secret in FRAGMENT only, one-time link per device, treat
23
- URLs + `abd-` creds as passwords) + `bin/lib/launch.js` `buildPairUrl()`
24
- (`crewbus://pair?env=…&routes=…&caps=…#<abp-…>`) + `docs/M1_CLI_DRAFT.md`
25
- §1c–d (`relay pair qr`, `serve --advertise-routes --pair-qrcode`, same
26
- mint + audit as `relay pair`).
27
- - `bin/lib/web.js` `renderBoardHtml()` + `cmdWeb`: single-file dashboard,
28
- no build step; AppRoot shell (Boards/Crews/Fleet/Channels/Triage/Approvals/
29
- Results/Audit/Settings, top bar with harness quick-pick + `#conn-dot` +
30
- `Ctrl+K`); reads open (`GET /api/board|fleet|channels|results|audit`,
31
- `/api/inbox`, `/api/harnesses`, `/api/routes`), writes JSON-only +
32
- token-checked (`POST /api/launch|kill|ack|approve`); 5s poll; tokens in
33
- tab memory. This is what the desktop shell embeds — no UI duplication.
34
-
35
- ## 1. What the shell embeds
36
-
37
- `cmdWeb` binds `--host` (default `127.0.0.1`) + `--port` (`0` = random, the
38
- actual address is printed on stdout), serves `GET /` → `renderBoardHtml()`
39
- + the `/api/*` set above, and blocks until SIGINT. The desktop shell therefore
40
- needs no board UI of its own: it owns a loopback sidecar process, learns its
41
- actual `127.0.0.1:PORT`, and points a webview at it. All IA (§5), RBAC, and
42
- contract behavior ride along unchanged.
43
-
44
- Spike finding (verified in source): `serve`'s `GET /` is currently a
45
- **plaintext relay banner** (`bin/crewbus.js` ~L4896), NOT the dashboard —
46
- `renderBoardHtml()` is served by `web` only. So "same web UI via sidecar
47
- `serve`" needs one additive endpoint (M4b owns it): `serve` should answer
48
- `GET /` with the same `renderBoardHtml()` body `web` serves (same loopback
49
- trust zone, pure reuse, allowed — "zero-dep core gains only additive
50
- endpoints"). Until that lands, the scaffold's supervisor spawns `serve`
51
- per spec and the shell degrades gracefully (status line says what it is
52
- waiting for). No second sidecar, no forked UI.
53
-
54
- ## 2. Evaluation
55
-
56
- ### (a) Sidecar ownership (`node bin/crewbus.js serve --port 0` loopback lifecycle)
57
-
58
- - Tauri: Rust supervisor spawns system `node` with fixed args, reads stdout
59
- for the first `http://127.0.0.1:PORT`, holds the child handle, kills it on
60
- window close / toggle-off, restarts with backoff. `--port 0` means the port
61
- is *learned*, never configured — both shells must parse it. Tauri's
62
- plugin-shell `spawn` scope pins the exact binary + arg prefix, so the
63
- supervisor cannot be repurposed into an arbitrary command runner.
64
- - Electron: same lifecycle in Node (trivially easy — it IS Node), but the
65
- main process has no capability boundary: any RCE in the renderer-adjacent
66
- main preload chain inherits full `child_process`. Ownership is easier to
67
- write, harder to confine.
68
-
69
- Edge for Tauri (confinement), with one cost: the sidecar needs a **system
70
- `node` ≥ 18 on PATH** — Tauri does not ship a JS runtime. Recorded as a
71
- build/packaging prerequisite, not a blocker (the fleet already assumes node).
72
-
73
- ### (b) Webview loading the local dashboard
74
-
75
- - Tauri: system webview (WebView2 / WKWebView / WebKitGTK), CSP in
76
- `tauri.conf.json` pinned to `http://127.0.0.1:*` + `http://localhost:*`,
77
- dashboard loaded in an `<iframe>` so *zero* dashboard code is duplicated —
78
- `renderBoardHtml()` stays the single implementation. No bundled Chromium.
79
- - Electron: bundled Chromium — pixel-identical rendering everywhere, but the
80
- shell ships a whole browser to display a localhost page, and the renderer
81
- bridge (`ipcRenderer`/`contextBridge`) is a perennial CVE surface for an
82
- app whose page already does everything over plain `fetch`.
83
-
84
- Edge for Tauri (no duplicated browser, smaller surface). Residual risk:
85
- WebKitGTK lag on Linux — accepted, dashboard is plain HTML + 5s poll.
86
-
87
- ### (c) Pairing-window flow (render `crewbus://pair` QR from `--pair-qrcode` output, fragment-secret hygiene)
88
-
89
- Flow is identical either way: supervisor mints via `serve --pair-qrcode`
90
- (same mint + audit as `relay pair`), captures the
91
- `crewbus://pair?env=…&routes=…&caps=…#<abp-…>` stdout line, hands **only the
92
- in-memory string** to a second window that renders the QR client-side.
93
- Hygiene rules (from `pairing.json` + `parsePairUrl()`), enforced in the
94
- scaffold's `pair.js` comments:
95
-
96
- 1. Secret travels in `#fragment` only — never query (fragments never leave
97
- the client; `parsePairUrl()` throws on query secrets).
98
- 2. The full URL is never logged, persisted, or screenshotted — strip the
99
- fragment before any status line; one-time link per device.
100
- 3. The shell never stores the `abp-` token — exchange swaps it once for
101
- `abd-…` (narrow-only scopes) held in the client-runtime auth store
102
- (OS keychain via Tauri `stronghold`/keyring on the toolchain machine;
103
- memory store in the spike).
104
-
105
- No differentiator on capability — slight edge for Tauri: the pair window is
106
- a declaratively scoped second webview (`pair.html`, `visible: false` until
107
- invoked) with no Node access, whereas Electron needs explicit
108
- `BrowserWindow` hardening per window.
109
-
110
- ### (d) Background-service story
111
-
112
- Spec wants the desktop to act as an environment that survives window close
113
- (sidecar keeps serving; mobile pairs against it). Neither framework is an
114
- OS service manager — both need per-OS registration:
115
-
116
- - Windows: Task Scheduler entry / WinSW wrapper; macOS: `launchd` plist;
117
- Linux: `systemd --user` unit. `apps/desktop/README.md` records all three.
118
- - Tauri adds: single-instance plugin (second launch focuses, never double-
119
- spawns the sidecar) + autostart plugin. Electron adds: same via
120
- `app.requestSingleInstanceLock()` + `app.setLoginItemSettings()`.
121
-
122
- Rough parity; Tauri's smaller resident footprint matters more for an
123
- always-on sidecar host. Edge for Tauri (weakly).
124
-
125
- ### (e) Packaging size / signer burden
126
-
127
- - Tauri: ~8–15 MB installer (system webview + ~2 MB Rust supervisor);
128
- signing/notarization identical paperwork but a far smaller artifact to
129
- ship and update (updater deltas stay tiny).
130
- - Electron: ~80–150 MB per platform (bundled Chromium + Node), three
131
- platform builds of a full browser to sign, notarize, and push through
132
- the updater on every release.
133
-
134
- Strong edge for Tauri. For a localhost dashboard host, shipping a second
135
- browser is pure burden.
136
-
137
- ### (f) Fit with zero-dep Node core + `packages/client-runtime`
138
-
139
- - The core stays zero-dep either way: the sidecar is stock
140
- `bin/crewbus.js`, spawned, not bundled — neither framework touches `bin/`
141
- or `packages/`.
142
- - `packages/client-runtime` is runtime-agnostic ESM with injected
143
- `fetch`/timers/storage. Tauri's frontend is plain ESM (`src/main.js`
144
- imports it at build time on a toolchain machine; the spike keeps the
145
- shell dependency-free and notes the import point). Electron could
146
- `require()` it in main, but that drags Node-only patterns into the shell
147
- the runtime was designed to avoid (`node-adapter.js` is deliberately NOT
148
- re-exported from `index.js`). Tauri's split — Rust owns the process,
149
- ESM owns the policy — matches the runtime's injection design better.
150
-
151
- Edge for Tauri.
152
-
153
- ## 3. Decision
154
-
155
- **Tauri wins 5–0–1 (one parity). Confirm the spec preference — no overturn.**
156
-
157
- | Criterion | Winner | Why in one line |
158
- |---|---|---|
159
- | (a) sidecar ownership | Tauri | spawn scope pins binary+args; lifetime in Rust, not in a web page |
160
- | (b) local dashboard | Tauri | system webview + iframe reuse; no second browser |
161
- | (c) pairing window | Tauri (slight) | scoped second webview, no per-window Node hardening |
162
- | (d) background service | Tie (Tauri weakly) | both need OS registration; Tauri is the lighter resident |
163
- | (e) packaging/signing | Tauri (strong) | ~10 MB vs ~100 MB to sign, ship, and update |
164
- | (f) core/runtime fit | Tauri | external-node sidecar keeps core zero-dep; ESM injection fits a web shell |
165
-
166
- ## 4. Consequences
167
-
168
- 1. Builds require a toolchain machine (Rust stable + Node ≥ 18 + Tauri CLI
169
- + platform webview SDKs) — this repo machine has none, so `apps/desktop/`
170
- is an uncompiled static scaffold. `npm install` was deliberately NOT run
171
- (no `node_modules`, no lockfile).
172
- 2. Runtime requires system `node` ≥ 18 on PATH for the sidecar. The
173
- installer story must either assert it at first run or vendor node next
174
- to the binary (M5 packaging question below).
175
- 3. M4b owns the sidecar test surface + the additive `serve GET /` dashboard
176
- route (§1 finding). This scaffold adds no repo tests.
177
- 4. `Local environment` toggle semantics (spec §4.3): remote-only mode stops
178
- the sidecar process WITHOUT deleting board state — stopping `serve`
179
- touches nothing under `.crewbus/` (it only reads/writes live); the board
180
- directory is never removed. Implemented as `stop_sidecar` + documented
181
- in `apps/desktop/README.md`.
182
- 5. No remote capability is granted anywhere in the scaffold (capability file
183
- allows `http` fetch to loopback only, `shell` spawn of the pinned sidecar
184
- command only, no `fs` scope at all).
185
-
186
- ## 5. Scaffold map (see `apps/desktop/README.md` for build/run)
187
-
188
- - `apps/desktop/package.json` — scripts (`dev`/`build`/`test`/`tauri`),
189
- deps listed (`@tauri-apps/api`, `@tauri-apps/cli`), never installed here.
190
- - `apps/desktop/src-tauri/tauri.conf.json` — product/identifier, `frontendDist
191
- ../src`, main + hidden pair windows, loopback-pinned CSP, bundle metadata.
192
- - `apps/desktop/src-tauri/capabilities/main.json` — loopback-only grant:
193
- core default, shell spawn of `node bin/crewbus.js serve --port 0` only,
194
- http fetch to `127.0.0.1`/`localhost` only, no fs, no remote.
195
- - `apps/desktop/src-tauri/Cargo.toml` + `src-tauri/src/main.rs` — Rust
196
- supervisor stub (spawn/parse-port/emit/stop, single-instance note).
197
- UNCOMPILED — validate with `npm run tauri build` on a toolchain machine.
198
- - `apps/desktop/src/index.html` + `src/main.js` — shell page: connection dot
199
- (5s `/api/board` poll, same signal as the dashboard's `#conn-dot`), Local
200
- environment toggle, pair-window button, sidecar-URL resolution
201
- (`?dashboard=` → Tauri `dashboard-ready` event → manual entry), dashboard
202
- in `<iframe>` (its UI is reused, never duplicated).
203
- - `apps/desktop/src/pair.html` + `src/pair.js` — pair-QR window placeholder:
204
- paste/capture of the `crewbus://pair…#abp-…` URL, fragment-hygiene rules,
205
- QR box placeholder (wire a QR renderer on the toolchain machine).
206
- - `apps/desktop/scripts/check.mjs` — static self-check (`npm test`): every
207
- JSON parses, every cross-referenced path exists. This is the M4 desktop
208
- verify hook until M4b's sidecar tests land.
209
-
210
- ## 6. Open questions for M5 (mobile + hardening)
211
-
212
- 1. `serve GET /` dashboard route (§1): M4b confirms shape + test, or the
213
- supervisor must target `web --port 0` for the iframe while keeping
214
- `serve` for relay — decide before M5 pairs phones against desktops.
215
- 2. Vendor node vs assert node: does the installer bundle a node binary
216
- (size/signer cost) or refuse to start without system node ≥ 18?
217
- 3. QR renderer choice for the pair window (no-dep canvas encoder vs a pinned
218
- dependency) + `stronghold`/keyring binding for the `abd-…` auth store.
219
- 4. `advertiseEnv()` routes for a laptop desktop (LAN/Tailscale hints via
220
- `serve --advertise-routes`) so M5 route-walk has something to prove.
221
- 5. Icon set + updater signing certs per OS (needs the toolchain machine;
222
- `npm run tauri icon` + CI secrets).
223
- 6. WebKitGTK floor version for the Linux shell (oldest distro to support).