crewbus 10.0.11 → 11.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/AGENTS.template.md +4 -4
  2. package/CHANGELOG.md +151 -0
  3. package/README.md +713 -706
  4. package/TEAM.template.md +1 -1
  5. package/bin/crewbus-hook.js +22 -5
  6. package/bin/crewbus-mcp.js +56 -48
  7. package/bin/crewbus.js +486 -355
  8. package/bin/lib/channels.js +1 -1
  9. package/bin/lib/export.js +1 -1
  10. package/bin/lib/groups.js +1 -5
  11. package/bin/lib/identity.js +92 -152
  12. package/bin/lib/launch.js +128 -30
  13. package/bin/lib/qrcode.js +2971 -0
  14. package/bin/lib/relay.js +26 -54
  15. package/bin/lib/spawn.js +241 -194
  16. package/bin/lib/store.js +2 -2
  17. package/bin/lib/web.js +277 -59
  18. package/claude-plugin/skills/crewbus/SKILL.md +1 -1
  19. package/docs/APPROVALS.md +8 -8
  20. package/docs/AUDIT_EXPORT.md +7 -7
  21. package/docs/CERT_READINESS.md +120 -120
  22. package/docs/COMPATIBILITY.md +196 -194
  23. package/docs/CONSOLIDATOR.md +6 -6
  24. package/docs/CONTROL_PLANE_SPEC.md +12 -14
  25. package/docs/CREWS.md +16 -13
  26. package/docs/DELIVERY.md +213 -210
  27. package/docs/GROUPS.md +8 -8
  28. package/docs/HA.md +151 -151
  29. package/docs/IDENTITY.md +6 -6
  30. package/docs/LEAD_ASSIGN.md +3 -85
  31. package/docs/LONG_RUNS.md +3 -3
  32. package/docs/M1_CLI_DRAFT.md +9 -9
  33. package/docs/ORCHESTRATOR.md +87 -0
  34. package/docs/PAIRING.md +7 -7
  35. package/docs/QUICKSTART.md +24 -13
  36. package/docs/RBAC.md +84 -73
  37. package/docs/SPLIT.md +82 -82
  38. package/docs/TENANCY.md +10 -10
  39. package/docs/THREAT_MODEL.md +68 -69
  40. package/docs/VERIFIER.md +10 -10
  41. package/docs/VERSION_SKEW.md +57 -57
  42. package/documentation.html +37 -29
  43. package/examples/hermes-pairing.md +3 -3
  44. package/examples/t3-pairing.md +1 -1
  45. package/index.html +13 -14
  46. package/opencode/plugins/dm-watch.js +1 -1
  47. package/opencode/tools/dm-send.js +4 -13
  48. package/package.json +75 -50
  49. package/packages/client-runtime/README.md +40 -40
  50. package/packages/contracts/harness.json +108 -111
  51. package/packages/contracts/launch.json +2 -3
  52. package/packages/contracts/pairing.json +3 -3
  53. package/docs/DESKTOP_SPIKE.md +0 -223
package/docs/PAIRING.md CHANGED
@@ -1,14 +1,14 @@
1
1
  # Per-device relay pairing
2
2
 
3
3
  One shared relay secret for every machine is a password that cannot be
4
- un-shared. Pairing replaces it with per-device credentials: an admin mints a
4
+ un-shared. Pairing replaces it with per-device credentials: the orchestrator mints a
5
5
  single-use token, the new device swaps it once for a long-lived credential,
6
6
  and either side can kill it independently.
7
7
 
8
8
  ## Flow
9
9
 
10
10
  ```sh
11
- # on the relay (admin, token-checked):
11
+ # on the relay (orchestrator, token-checked):
12
12
  crewbus relay pair --from ops --label laptop --ttl 10m
13
13
  # -> pairing token abp-... (single-use, TTL'd, printed once)
14
14
 
@@ -24,7 +24,7 @@ crewbus sync --with http://relay:8471 --secret s3 --once \
24
24
  crewbus sync --with http://relay:8471 --device $CREWBUS_DEVICE --once
25
25
  ```
26
26
 
27
- ## Management (admin)
27
+ ## Management (orchestrator)
28
28
 
29
29
  ```sh
30
30
  crewbus relay devices --from ops [--json] # id, label, by, lastSeen, revoked?
@@ -41,14 +41,14 @@ Same mint/exchange/revoke cores as the CLI, over the relay (`bin/crewbus.js`
41
41
  serve handler; secret travels in the `crewbus://pair` URL `#fragment` only,
42
42
  never query):
43
43
 
44
- - `POST /api/pair/issue` (admin token-checked: `from` + agent token, then
44
+ - `POST /api/pair/issue` (orchestrator token-checked: `from` + agent token, then
45
45
  `authorizeCheck` `pairing`) → `{pairUrl, expiresAt}`.
46
46
  - `POST /api/pair/exchange` (unauthenticated — the one-time token IS the
47
47
  credential; narrow-only scope check before the single-use claim) →
48
48
  `{deviceId, credential}`.
49
- - `GET /api/pair/devices` (admin token-checked; a read, so it serves locally
49
+ - `GET /api/pair/devices` (orchestrator token-checked; a read, so it serves locally
50
50
  even on a standby) → device list.
51
- - `POST /api/pair/revoke` (admin token-checked, immediate) → `{ok: true}`.
51
+ - `POST /api/pair/revoke` (orchestrator token-checked, immediate) → `{ok: true}`.
52
52
  - Standby behavior: writes 503 (`issue`/`exchange`/`revoke`); reads
53
53
  (`devices`) serve locally.
54
54
 
@@ -72,7 +72,7 @@ never query):
72
72
  control-plane RPCs only). Issuance is narrow-only: requested ⊆ granted,
73
73
  checked before the single-use claim (`bin/crewbus.js` `/api/pair/exchange`
74
74
  handler), so a widen attempt never burns the token. Narrowed or not, a
75
- device never grants board admin — agent identity is still token-checked
75
+ device never grants board control-plane powers — agent identity is still token-checked
76
76
  per command.
77
77
  - **Audit.** `pair`, `device-issue`, and `device-revoke` all land in the
78
78
  tamper-evident log with actor + label; `devices` shows `lastSeen` per
@@ -7,7 +7,9 @@ directly. Node 18+ required.
7
7
  ## 1. Install (1 min)
8
8
 
9
9
  ```sh
10
+ # public package (scoped GitHub Packages mirror: @eamonpluto/crewbus)
10
11
  npm i -g crewbus
12
+ crewbus --version # confirm the install
11
13
  crewbus init --harness opencode # repeat per harness, comma-separated
12
14
  crewbus doctor # confirm all-ok before going further
13
15
  ```
@@ -16,25 +18,30 @@ crewbus doctor # confirm all-ok before going further
16
18
  `crewbus:start/end` block to `AGENTS.md`, and installs hook + MCP wiring.
17
19
  Restart your harness after `init` so tools/plugins load.
18
20
 
19
- > **Desktop alternative**: If using the CrewBus Desktop GUI, the app automatically manages a persistent central board at `<app-data>/board`—**no `crewbus init` is required in your project directories**! Simply install the desktop app, set your project folder in Launch Studio, and launch.
21
+ > **Web Dashboard**: Run `crewbus web --open` to launch the interactive local dashboard in your browser with live harness detection, Launch Studio, and mobile QR pairing.
20
22
 
21
- ## 2. Claim names (1 min)
23
+ ## 2. Bootstrap the board (1 min)
24
+
25
+ The board has exactly one control-plane identity, `orchestrator`. It is
26
+ created automatically by `spawn`, `web`, or `serve`; you can also do it
27
+ explicitly:
22
28
 
23
29
  ```sh
24
- crewbus register --from lead
25
- export CREWBUS_TOKEN="<printed-once-token>" # or pass --token per call
30
+ crewbus orchestrator init
31
+ # -> orchestrator initialized: token abt-...
26
32
  crewbus agents
27
33
  ```
28
34
 
29
- First claim wins: the first `send`/`register` as a new name mints its token.
30
- After that every addressed read/write needs the token.
35
+ Workers self-register as workers on their first `register`/`send`; the
36
+ orchestrator needs no manual step unless you want to act as it from your
37
+ shell.
31
38
 
32
39
  ## 3. Send the first brief (1 min)
33
40
 
34
41
  The DM *is* the task — mission + scope + definition of done, no task object:
35
42
 
36
43
  ```sh
37
- crewbus send --from lead --to alice --subject "brief: hello" \
44
+ crewbus send --from orchestrator --to alice --subject "brief: hello" \
38
45
  --body "Reply to this brief with a one-line summary."
39
46
  crewbus inbox --from alice
40
47
  ```
@@ -48,17 +55,21 @@ compare the paths first — different boards look exactly like "no mail".
48
55
 
49
56
  ```sh
50
57
  # preview first — touches nothing
51
- crewbus spawn --from lead --to alice,bob --body "Audit your scope, DM me a summary." --dry-run
52
- # for real (generic harness runs any command; other harnesses boot headless)
53
- crewbus spawn --from lead --count 2 --prefix demo --harness generic --cmd "node worker.js" --body "Audit your scope, DM me a summary."
58
+ crewbus spawn "Audit your scope, DM the orchestrator a summary." --count 2 --dry-run
59
+ # for real
60
+ crewbus spawn "Audit your scope, DM the orchestrator a summary." --count 2 --harness opencode
54
61
  crewbus spawn-status --all
55
- crewbus inbox --from lead --unacked
62
+ crewbus inbox --from orchestrator --unacked
56
63
  ```
57
64
 
65
+ `spawn` automatically creates/reuses the orchestrator, writes the worker
66
+ briefs, boots the workers, and transfers crew ownership to the orchestrator.
67
+ There is no `--from` or `--lead`.
68
+
58
69
  Workers survive the terminal closing by design — `spawn-kill` stops them:
59
70
 
60
71
  ```sh
61
- crewbus spawn-kill --from lead --all
72
+ crewbus spawn-kill --from orchestrator --all
62
73
  ```
63
74
 
64
75
  ## Next steps
@@ -67,4 +78,4 @@ crewbus spawn-kill --from lead --all
67
78
  - Something wrong? `docs/TROUBLESHOOTING.md`, then `crewbus doctor`.
68
79
  - Wondering if this fits? Read `docs/WHEN_NOT.md` first.
69
80
  - Harness versions + last-verified dates: `docs/COMPATIBILITY.md`.
70
- - Prefer a wizard/GUI? `crewbus harnesses` detects installed drivers, `launch --dry-run` previews the exact boot commands, and `crewbus web` is the dashboard alternative.
81
+ - Prefer a wizard/GUI? `crewbus harnesses` detects installed drivers, `launch --dry-run` previews the exact boot commands, and `crewbus web` is the dashboard alternative.
package/docs/RBAC.md CHANGED
@@ -1,73 +1,84 @@
1
- # RBAC + per-board ACLs + group-scoped send permissions (Phase 1b)
2
-
3
- Zero-dependency, file-local. Composes with Phase 1a tokens: `checkToken()`
4
- proves WHO you are; `authorize()` decides WHAT your role may do. `authorize()`
5
- is a SEPARATE function called AFTER `checkToken()` passes — never before,
6
- never instead, never merged into token code.
7
-
8
- ## Roles
9
-
10
- Agent records carry `role` in `{admin, lead, worker, auditor}`.
11
-
12
- - First-registered agent on a board becomes **admin**; everyone else gets
13
- `acl.defaultRole` (default `"worker"`).
14
- - `register --role <r>` is only honored when the caller is **admin**,
15
- otherwise ignored with a warning on stderr (no self-promotion).
16
- - Grant/change: `register --from <admin> --for <target> [--role <r>]`
17
- (admin-only, bypasses frozen boards; also re-onboards offboarded names).
18
- - `agents --json` exposes roles (secrets stripped, role kept).
19
-
20
- ## Permission matrix (minimal)
21
-
22
- | action | admin | lead | worker | auditor |
23
- |---|---|---|---|---|
24
- | send / inbox / ack / redeliver / lock (scoped) | yes | yes | yes | read-only: inbox yes; send/ack/lock NO |
25
- | spawn / pool / spawn-kill (own crew) / group manage / result record / race close | yes | yes | NO | NO |
26
- | channel post | yes (anywhere) | yes (anywhere) | members-only: the channel's own group only (`grp-<group>` where the caller is a member) | NO |
27
- | launch (same RBAC + audit as spawn: `cmdLaunch` delegates to `cmdSpawn`; `handleApiLaunch` checks `spawn`) | yes | yes | NO | NO |
28
- | relay pair issue / devices / revoke (`pairing`: CLI gate + `POST /api/pair/*`, `GET /api/pair/devices`) | yes | NO | NO | NO |
29
- | prune / acl set / role-grant / offboard / group restrict / serve `--allow-remote-spawn` | yes | NO | NO | NO |
30
- | reads (gather / thread / log / channel tail / group show / result show / spawn-status / agents) | yes | yes | yes | yes |
31
-
32
- Notes:
33
-
34
- - Reads not listed above default-allow (fail-closed only for writes).
35
- - `spawn-kill` for leads is own-crew only: every target's `spawnedBy` must
36
- equal the caller (or the target was never spawned). Admins may kill any.
37
- - `lock release` still requires ownership even when acquire is allowed.
38
- - MCP twins: `dm_send`→send, `dm_inbox`→inbox, `dm_ack`→ack,
39
- `dm_channel_post`→channel-post (member-scoped like the CLI: lead|admin post anywhere, members post only to their own group's channel). `dm_gather` /
40
- `dm_channel_tail` are identity-less reads (like CLI `gather`), default-allow.
41
- - Member-scoped channel posting (C4) is default-on with no flag (briefs sent
42
- with `--also-channel` to a group the sender is not a member of still
43
- deliver as DMs; only the channel mirror is skipped, with a visible note).
44
- - Relay: `POST /api/spawn`→spawn, `POST /api/launch`→spawn, `POST /api/kill`→spawn-kill (403 on denial); pair endpoints→`pairing` (admin): `POST /api/pair/issue|exchange|revoke`, `GET /api/pair/devices`.
45
- - Device-scope layer: transport credential scopes (`requireScope` in `bin/lib/relay.js`) compose UNDER role checks — a narrowed device can only further restrict, never widen, what the agent token's role allows.
46
- - `prune` and `group create/add/remove` keep the bare operator path (no
47
- `--from`) open for back-compat; with `--from` the caller is token-checked
48
- and authorized. `serve --allow-remote-spawn` with `--from` requires admin.
49
-
50
- ## Per-board ACLs
51
-
52
- `board.json` gains `acl: {defaultRole, frozen?}`.
53
-
54
- - `acl set --from <admin> [--default-role worker] [--freeze|--unfreeze]`
55
- (admin-only). `acl show [--json]` is read-only.
56
- - Frozen boards refuse new registrations (including first-send auto-mint),
57
- except by admin grant (`register --from <admin> --for <new>`).
58
-
59
- ## Group-scoped send permissions
60
-
61
- - `group restrict <name> --from <admin>` sets `restricted: true`
62
- (`group unrestrict` clears it). Admin-only. The flag survives member edits.
63
- - Sends with `--to-group` (or `to_group` / relay `to_group`) to a restricted
64
- group are refused unless the caller is admin/lead or a group member.
65
- - Pattern: curate a private crew (`group create elite --add a,b`),
66
- then `group restrict elite --from <admin>`; outsiders get a loud refusal,
67
- members + leads keep working.
68
-
69
- ## Back-compat
70
-
71
- Boards/agents without roles behave as today: legacy records without `role`
72
- map to **lead**, so existing crews keep working (and keep spawn/group/channel
73
- powers). Token-less legacy records keep the existing migrate-on-auth behavior.
1
+ # RBAC + per-board ACLs + group-scoped send permissions
2
+
3
+ Zero-dependency, file-local. Composes with tokens: `checkToken()` proves WHO
4
+ you are; `authorize()` decides WHAT your role may do. `authorize()` is a
5
+ SEPARATE function called AFTER `checkToken()` passes — never before, never
6
+ instead, never merged into token code.
7
+
8
+ ## Roles
9
+
10
+ Agent records carry `role` in `{orchestrator, worker}`.
11
+
12
+ - **orchestrator** — the board's single control-plane identity. It owns the
13
+ crew: spawn/respawn/kill, approvals, verification, groups, channels, ACLs,
14
+ pairing, and every worker action. `spawn` (and `web`/`serve`) bootstrap it
15
+ automatically as the agent named `orchestrator`, with its token at
16
+ `logs/orchestrator.token`.
17
+ - **worker** — the data plane. Send/inbox/ack/redeliver/lock, artifacts,
18
+ lessons, member-scoped channel posts, and reads. No control-plane actions.
19
+ - Every self-registering agent is a **worker**. Only
20
+ `ensureOrchestrator`/`crewbus orchestrator init` mints the orchestrator.
21
+ - Records with any other or missing role are treated as **worker** (an
22
+ unknown role can never gain control-plane powers).
23
+
24
+ ## Permission matrix
25
+
26
+ | action | orchestrator | worker |
27
+ |---|---|---|
28
+ | send / inbox / ack / redeliver / lock (scoped) | yes | yes |
29
+ | spawn / respawn / pool / spawn-kill / group manage / result record / race close | yes | NO |
30
+ | channel post | yes (anywhere) | members-only: the channel's own group (`grp-<group>` where the caller is a member) |
31
+ | launch (same RBAC + audit as spawn) | yes | NO |
32
+ | relay pair issue / devices / revoke (`pairing`) | yes | NO |
33
+ | prune / acl set / role-grant / offboard / group restrict / serve `--allow-remote-spawn` / import / snapshot / quota / legal hold | yes | NO |
34
+ | reads (gather / thread / log / channel tail / group show / result show / spawn-status / agents / hold status) | yes | yes |
35
+
36
+ Notes:
37
+
38
+ - Reads not listed above default-allow (fail-closed only for writes).
39
+ - `spawn-kill` is orchestrator-only; the orchestrator owns every crew.
40
+ - `lock release` still requires ownership even when acquire is allowed.
41
+ - MCP twins: `dm_send`→`send`, `dm_inbox`→`inbox`, `dm_ack`→`ack`,
42
+ `dm_channel_post`→`channel-post` (member-scoped like the CLI),
43
+ `dm_gather`/`dm_channel_tail` are identity-less reads.
44
+ - Relay: `POST /api/spawn`→`spawn`, `POST /api/launch`→`spawn`,
45
+ `POST /api/kill`→`spawn-kill` (403 on denial); pair endpoints→`pairing`.
46
+ Remote control-plane actions run as the relay board's orchestrator; the
47
+ relay secret or a device credential with `launch:spawn` is the auth
48
+ boundary.
49
+ - Device-scope layer: transport credential scopes (`requireScope` in
50
+ `bin/lib/relay.js`) compose UNDER role checks — a narrowed device can only
51
+ further restrict, never widen, what the agent token's role allows.
52
+ - `prune` and `group create/add/remove` keep the bare operator path (no
53
+ `--from`) open; with `--from` the caller is token-checked and authorized.
54
+ `serve --allow-remote-spawn` with `--from` requires the orchestrator.
55
+
56
+ ## Per-board ACLs
57
+
58
+ `board.json` gains `acl: {defaultRole, frozen?}`.
59
+
60
+ - `acl set --from orchestrator [--default-role worker] [--freeze|--unfreeze]`
61
+ (orchestrator-only). `acl show [--json]` is read-only.
62
+ - Every new registration is a worker; `defaultRole` stays `worker`.
63
+ - Frozen boards refuse new registrations (including first-send auto-mint),
64
+ except by orchestrator grant (`register --from orchestrator --for <new>`).
65
+
66
+ ## Group-scoped send permissions
67
+
68
+ - `group restrict <name> --from orchestrator` sets `restricted: true`
69
+ (`group unrestrict` clears it). Orchestrator-only. The flag survives
70
+ member edits.
71
+ - Sends with `--to-group` (or `to_group` / relay `to_group`) to a restricted
72
+ group are refused unless the caller is the orchestrator or a group member.
73
+ - Pattern: curate a private crew (`group create elite --add a,b`), then
74
+ `group restrict elite --from orchestrator`; outsiders get a loud refusal,
75
+ members + the orchestrator keep working.
76
+
77
+ ## Bootstrap and migration
78
+
79
+ - Fresh boards: `spawn`, `web`, or `serve` ensure the orchestrator; or run
80
+ `crewbus orchestrator init` explicitly (prints the token once).
81
+ - Existing boards with roles outside `{orchestrator, worker}` are treated as
82
+ worker-only; mint the orchestrator with `crewbus orchestrator init`.
83
+ - `crewbus orchestrator show` reports the identity, live pid, and token path
84
+ without booting anything.
package/docs/SPLIT.md CHANGED
@@ -1,82 +1,82 @@
1
- # Split: `bin/crewbus.js` → `bin/lib/*.js`
2
-
3
- Status: landed. `bin/crewbus.js` is a dispatcher that intentionally
4
- retains the `cmd*` wrappers, `USAGE`, `main()`, and the opencode
5
- tool/plugin embeds; domain logic lives in the 13 lib modules
6
- (`bin/lib/` holds channels, export, groups, identity, launch, mail,
7
- relay, spawn, store, sync, tokenfile, web, workbench; import block,
8
- `bin/crewbus.js` lines 44–56). No behavior change is intended, with one deliberate exception recorded in CHANGELOG (parseRecipients full-version canonicalization).
9
-
10
- ## Module map
11
-
12
- | File | Responsibility (per file header) | Key exports |
13
- |---|---|---|
14
- | `bin/lib/store.js` | Board filesystem layer: constants, board resolution, JSON IO, `clean*` validators, HLC | `BOARD_VERSION`, `MAX_BODY_CHARS`, `MAX_RECIPIENTS`, `MAX_SPAWN`, `BROADCAST_AFTER`, `boardDir`, `dirs`, `ensureBoard`, `readJson`, `writeJson`, `writeExclusiveJson`, `clean*` (`cleanSubject`, `cleanGroupName`, `cleanChannelName`, `cleanWebName`, …), `nextHlc`, `stampSyncDoc`, `hlcCompare` |
15
- | `bin/lib/identity.js` | Tokens + RBAC: mint/verify, salted hashes, ACLs, `authorize` | `mintToken`, `hashToken`, `checkToken`, `ensureSender`, `sanitizeAgentForSync`, `mergeSyncedAgent`, `VALID_ROLES`, `authorize`, `authorizeCheck`, `authorizeThrow`, `touchAgent` |
16
- | `bin/lib/sync.js` | Sync engine + outbound client: union-by-id merge, HLC LWW, tombstones, per-peer cursors | `SYNC_SUBS`, `SYNC_UNION`, `SYNC_LWW`, `syncRound`, `syncWalk`, `httpJson`, `relayAuthEntries`, `crewSurvey`, `splitByWeight`, `readSyncState`, `tombstoneIdForRel` |
17
- | `bin/lib/relay.js` | Relay serve-side: secrets, device/pairing creds, OIDC, remote spawn/kill cores, per-call device scope gate | `relaySecretFromArgs`, `requireRelaySecret`, `requireRelayClientCert`, `readRelayState`, `tryAcquireFence`, `remoteSpawn`, `newPairToken`, `newDeviceCred`, `verifyOidcJwt`, `requireScope` |
18
- | `bin/lib/spawn.js` | Worker boot / spawn: prompts, harness targets, env scrub, pid liveness | `bootWorker`, `buildSpawnPrompt`, `buildSpawnTarget`, `scrubChildEnv`, `parseAllowEnv`, `workerStatus`, `pidAlive`, `killWorkers`, `provisionWorktree`, `provisionBranch` |
19
- | `bin/lib/launch.js` | Launch planning + harness detect + pair-URL helpers; pure helpers only, monolith keeps cmd wrappers | `LAUNCH_PERMISSIONS`, `LAUNCH_LIFETIMES`, `LAUNCH_PRIORITIES`, `PAIR_SCOPES`, `LAUNCH_DRIVER_FALLBACK`, `launchDrivers`, `probeBinary`, `detectHarnessBinaries`, `validateLaunchPlan`, `buildPairUrl`, `advertiseEnv` |
20
- | `bin/lib/export.js` | Backup/restore/quotas/storage + audit chain + legal hold | `doExportToFile`, `collectBoardFiles`, `encryptBackupPayload`, `decryptBackupPayload`, `readBoardQuotas`, `enforce*Quota`, `holdActive`, `readHold`, `appendChainRecord`, `verifyChainRecords`, `spoolAuditEvent`, `snapshotStamp` |
21
- | `bin/lib/mail.js` | DMs + delivery: send-path expansion, broadcast manifest, visible reads, digest, ack, verifier, thread/prune/listen/redeliver cores | `deliverDMs`, `readDMs`, `readVisible`, `parseRecipients`, `recordBroadcastManifest`, `ackedIds`, `runVerifier`, `signMessage`, `verifyMessageSig`, `checkSendRateLimit` |
22
- | `bin/lib/groups.js` | Groups + outcomes: group docs, expansion, telemetry, batch gather, results, races | `readGroup`, `expandGroups`, `expandGroupsOrFail`, `collectBatch`, `groupTelemetryData`, `gatherTelemetry`, `readResultRecord`, `writeResultRecord`, `findFirstVerifiedReply` |
23
- | `bin/lib/channels.js` | Shared channels + locks: log IO, per-reader cursors, digest/summarize, group mirrors, advisory locks, channel text-merge | `appendChannelPost`, `readChannelPosts`, `tailChannelPosts`, `parseChannelText`, `mergeChannelText`, `mirrorToGroupChannels`, `acquireLockDoc`, `releaseLockDoc` |
24
- | `bin/lib/web.js` | Dashboard + API: snapshots, HTML render, ack/kill/launch handlers, `cmdWeb`; control-plane additions: `handleApiLaunch`, `POST /api/launch`, `GET /api/harnesses\|routes\|holds\|quotas`, Holds/Quotas/AppRoot sections | `boardSnapshot`, `fleetSnapshot`, `channelsSnapshot`, `resultsSnapshot`, `auditSnapshot`, `renderBoardHtml`, `handleApiAck`, `handleApiKill`, `handleApiLaunch`, `cmdWeb` |
25
- | `bin/lib/tokenfile.js` | Token-file convention for long runs: save/re-read agent tokens across compaction/restart amnesia (0600 best-effort); standalone, no local imports (cycle-free) | `tokenFilePath`, `saveTokenFile`, `loadTokenFile` |
26
- | `bin/lib/workbench.js` | Artifacts + lessons (compound-memory layer): artifact objects with deps/adoption/verification edges, scoped lessons, spawn-brief Workbench block, gather metrics; pure helpers, monolith keeps `cmdArtifact`/`cmdLesson` | `publishArtifact`, `adoptArtifact`, `verifyArtifact`, `readArtifactById`, `listArtifacts`, `listLessons`, `postLesson`, `selectLessons`, `renderWorkbenchBlock`, `workbenchMetrics`, `cleanArtifactId`, `cleanLessonScope`, `parseArtifactDeps`, `ARTIFACT_ID_RE` |
27
-
28
- Full export lists: see the import block at the top of `bin/crewbus.js`
29
- (lines 44–56). Entry-point `cmd*` functions (e.g. `cmdSend`, `cmdSync`,
30
- `cmdServe`) stay in the monolith; lib modules carry the computation helpers
31
- those verbs call.
32
-
33
- ## Dependency rules
34
-
35
- - `store` ← everyone. All lib modules may import from `store.js`; `store.js`
36
- imports only node builtins.
37
- - Top-level side-effect-free: every `bin/lib/*.js` module must contain only
38
- imports + consts + function declarations at top level — no top-level I/O
39
- or calls — so import evaluation order is never hazardous.
40
- - Deferred-call cycles allowed (safe only because tops are side-effect-free
41
- and every cross-module use is inside function bodies, never at import
42
- time):
43
- - `identity` ↔ `groups` via `mail` (`identity.js` imports `readGroup`
44
- from `groups.js`; `groups.js` imports `readDMs`/`findMessageById` from
45
- `mail.js`; `mail.js` imports `writeAgentFile` from `identity.js`).
46
- - `sync` ↔ `relay` (`sync.js` imports `parseDeviceCred` from `relay.js`;
47
- `relay.js` imports `httpJson` from `sync.js`).
48
- - Canonical homes for duplicated helpers (keep exactly one; delete the rest
49
- in favor of these):
50
- - `clean*` validators → `store.js`.
51
- - Channel text merge (`parseChannelText`, `mergeChannelText`) →
52
- `channels.js` (`sync.js` imports them from there).
53
- - `handleApiKill` → `web.js` (dedup done — `relay.js` re-exports
54
- `handleApiKill` from `web.js`).
55
- - HLC (`nextHlc`, `stampSyncDoc`, `hlcCompare`) → `store.js`.
56
- - Out-of-monolith surfaces: `packages/client-runtime/` (shared retry/route/auth/cache core for desktop/mobile shells) and `apps/desktop|mobile` consume `bin/` over HTTP (sidecar/spawn + dashboard fetch), never import it.
57
-
58
- ## How to add a command
59
-
60
- 1. Add the `cmd*` wrapper + `main()` switch case (+ `USAGE` text) in
61
- `bin/crewbus.js` (dispatcher owns CLI parsing and flag handling).
62
- 2. Put reusable logic in the owning `bin/lib/*.js` module (table above);
63
- keep the new lib code side-effect-free at top level.
64
- 3. Add tests under `test/` covering the new path (`npm test` runs
65
- `test/crewbus.*.mjs` — smoke, harness, compact, tokenfile, digest,
66
- control-plane, launch, web-launch, pair-api, web-panel, web-approot,
67
- client-runtime, runtime-wiring, desktop-sidecar, mobile-client,
68
- grok-hooks, holds-quotas, approval-protocol, approvals-init,
69
- approvals-web — plus `test/fault-injection.mjs` + `test/integration.mjs`;
70
- see root `package.json` `scripts.test`).
71
-
72
- ## Embeds note
73
-
74
- The `OPENCODE_TOOL_DM_SEND` / `OPENCODE_PLUGIN_DM_WATCH` template literals
75
- stay in `bin/crewbus.js` (populated from `opencode/tools/dm-send.js` +
76
- `opencode/plugins/dm-watch.js`). `sync-embeds.mjs` is unaffected by this
77
- split — keep running `node sync-embeds.mjs --check` after edits.
78
-
79
- ## MCP note
80
-
81
- `bin/crewbus-mcp.js` is still standalone (own copies, no `bin/lib/*`
82
- imports). Sharing lib modules with the MCP server is future work, NOT done.
1
+ # Split: `bin/crewbus.js` → `bin/lib/*.js`
2
+
3
+ Status: landed. `bin/crewbus.js` is a dispatcher that intentionally
4
+ retains the `cmd*` wrappers, `USAGE`, `main()`, and the opencode
5
+ tool/plugin embeds; domain logic lives in the 13 lib modules
6
+ (`bin/lib/` holds channels, export, groups, identity, launch, mail,
7
+ relay, spawn, store, sync, tokenfile, web, workbench; import block,
8
+ `bin/crewbus.js` lines 44–56). No behavior change is intended, with one deliberate exception recorded in CHANGELOG (parseRecipients full-version canonicalization).
9
+
10
+ ## Module map
11
+
12
+ | File | Responsibility (per file header) | Key exports |
13
+ |---|---|---|
14
+ | `bin/lib/store.js` | Board filesystem layer: constants, board resolution, JSON IO, `clean*` validators, HLC | `BOARD_VERSION`, `MAX_BODY_CHARS`, `MAX_RECIPIENTS`, `MAX_SPAWN`, `BROADCAST_AFTER`, `boardDir`, `dirs`, `ensureBoard`, `readJson`, `writeJson`, `writeExclusiveJson`, `clean*` (`cleanSubject`, `cleanGroupName`, `cleanChannelName`, `cleanWebName`, …), `nextHlc`, `stampSyncDoc`, `hlcCompare` |
15
+ | `bin/lib/identity.js` | Tokens + RBAC: mint/verify, salted hashes, ACLs, `authorize` | `mintToken`, `hashToken`, `checkToken`, `ensureSender`, `sanitizeAgentForSync`, `mergeSyncedAgent`, `VALID_ROLES`, `authorize`, `authorizeCheck`, `authorizeThrow`, `touchAgent` |
16
+ | `bin/lib/sync.js` | Sync engine + outbound client: union-by-id merge, HLC LWW, tombstones, per-peer cursors | `SYNC_SUBS`, `SYNC_UNION`, `SYNC_LWW`, `syncRound`, `syncWalk`, `httpJson`, `relayAuthEntries`, `crewSurvey`, `splitByWeight`, `readSyncState`, `tombstoneIdForRel` |
17
+ | `bin/lib/relay.js` | Relay serve-side: secrets, device/pairing creds, OIDC, remote spawn/kill cores, per-call device scope gate | `relaySecretFromArgs`, `requireRelaySecret`, `requireRelayClientCert`, `readRelayState`, `tryAcquireFence`, `remoteSpawn`, `newPairToken`, `newDeviceCred`, `verifyOidcJwt`, `requireScope` |
18
+ | `bin/lib/spawn.js` | Worker boot / spawn: prompts, harness targets, env scrub, pid liveness | `bootWorker`, `buildSpawnPrompt`, `buildSpawnTarget`, `scrubChildEnv`, `parseAllowEnv`, `workerStatus`, `pidAlive`, `killWorkers`, `provisionWorktree`, `provisionBranch` |
19
+ | `bin/lib/launch.js` | Launch planning + harness detect + pair-URL helpers; pure helpers only, monolith keeps cmd wrappers | `LAUNCH_PERMISSIONS`, `LAUNCH_LIFETIMES`, `LAUNCH_PRIORITIES`, `PAIR_SCOPES`, `LAUNCH_DRIVER_FALLBACK`, `launchDrivers`, `probeBinary`, `detectHarnessBinaries`, `validateLaunchPlan`, `buildPairUrl`, `advertiseEnv` |
20
+ | `bin/lib/export.js` | Backup/restore/quotas/storage + audit chain + legal hold | `doExportToFile`, `collectBoardFiles`, `encryptBackupPayload`, `decryptBackupPayload`, `readBoardQuotas`, `enforce*Quota`, `holdActive`, `readHold`, `appendChainRecord`, `verifyChainRecords`, `spoolAuditEvent`, `snapshotStamp` |
21
+ | `bin/lib/mail.js` | DMs + delivery: send-path expansion, broadcast manifest, visible reads, digest, ack, verifier, thread/prune/listen/redeliver cores | `deliverDMs`, `readDMs`, `readVisible`, `parseRecipients`, `recordBroadcastManifest`, `ackedIds`, `runVerifier`, `signMessage`, `verifyMessageSig`, `checkSendRateLimit` |
22
+ | `bin/lib/groups.js` | Groups + outcomes: group docs, expansion, telemetry, batch gather, results, races | `readGroup`, `expandGroups`, `expandGroupsOrFail`, `collectBatch`, `groupTelemetryData`, `gatherTelemetry`, `readResultRecord`, `writeResultRecord`, `findFirstVerifiedReply` |
23
+ | `bin/lib/channels.js` | Shared channels + locks: log IO, per-reader cursors, digest/summarize, group mirrors, advisory locks, channel text-merge | `appendChannelPost`, `readChannelPosts`, `tailChannelPosts`, `parseChannelText`, `mergeChannelText`, `mirrorToGroupChannels`, `acquireLockDoc`, `releaseLockDoc` |
24
+ | `bin/lib/web.js` | Dashboard + API: snapshots, HTML render, ack/kill/launch handlers, `cmdWeb`; control-plane additions: `handleApiLaunch`, `POST /api/launch`, `GET /api/harnesses\|routes\|holds\|quotas`, Holds/Quotas/AppRoot sections | `boardSnapshot`, `fleetSnapshot`, `channelsSnapshot`, `resultsSnapshot`, `auditSnapshot`, `renderBoardHtml`, `handleApiAck`, `handleApiKill`, `handleApiLaunch`, `cmdWeb` |
25
+ | `bin/lib/tokenfile.js` | Token-file convention for long runs: save/re-read agent tokens across compaction/restart amnesia (0600 best-effort); standalone, no local imports (cycle-free) | `tokenFilePath`, `saveTokenFile`, `loadTokenFile` |
26
+ | `bin/lib/workbench.js` | Artifacts + lessons (compound-memory layer): artifact objects with deps/adoption/verification edges, scoped lessons, spawn-brief Workbench block, gather metrics; pure helpers, monolith keeps `cmdArtifact`/`cmdLesson` | `publishArtifact`, `adoptArtifact`, `verifyArtifact`, `readArtifactById`, `listArtifacts`, `listLessons`, `postLesson`, `selectLessons`, `renderWorkbenchBlock`, `workbenchMetrics`, `cleanArtifactId`, `cleanLessonScope`, `parseArtifactDeps`, `ARTIFACT_ID_RE` |
27
+
28
+ Full export lists: see the import block at the top of `bin/crewbus.js`
29
+ (lines 44–56). Entry-point `cmd*` functions (e.g. `cmdSend`, `cmdSync`,
30
+ `cmdServe`) stay in the monolith; lib modules carry the computation helpers
31
+ those verbs call.
32
+
33
+ ## Dependency rules
34
+
35
+ - `store` ← everyone. All lib modules may import from `store.js`; `store.js`
36
+ imports only node builtins.
37
+ - Top-level side-effect-free: every `bin/lib/*.js` module must contain only
38
+ imports + consts + function declarations at top level — no top-level I/O
39
+ or calls — so import evaluation order is never hazardous.
40
+ - Deferred-call cycles allowed (safe only because tops are side-effect-free
41
+ and every cross-module use is inside function bodies, never at import
42
+ time):
43
+ - `identity` ↔ `groups` via `mail` (`identity.js` imports `readGroup`
44
+ from `groups.js`; `groups.js` imports `readDMs`/`findMessageById` from
45
+ `mail.js`; `mail.js` imports `writeAgentFile` from `identity.js`).
46
+ - `sync` ↔ `relay` (`sync.js` imports `parseDeviceCred` from `relay.js`;
47
+ `relay.js` imports `httpJson` from `sync.js`).
48
+ - Canonical homes for duplicated helpers (keep exactly one; delete the rest
49
+ in favor of these):
50
+ - `clean*` validators → `store.js`.
51
+ - Channel text merge (`parseChannelText`, `mergeChannelText`) →
52
+ `channels.js` (`sync.js` imports them from there).
53
+ - `handleApiKill` → `web.js` (dedup done — `relay.js` re-exports
54
+ `handleApiKill` from `web.js`).
55
+ - HLC (`nextHlc`, `stampSyncDoc`, `hlcCompare`) → `store.js`.
56
+ - Out-of-monolith surfaces: `packages/client-runtime/` (shared retry/route/auth/cache core for desktop/mobile shells) and `apps/mobile` consume `bin/` over HTTP (sidecar/spawn + dashboard fetch), never import it.
57
+
58
+ ## How to add a command
59
+
60
+ 1. Add the `cmd*` wrapper + `main()` switch case (+ `USAGE` text) in
61
+ `bin/crewbus.js` (dispatcher owns CLI parsing and flag handling).
62
+ 2. Put reusable logic in the owning `bin/lib/*.js` module (table above);
63
+ keep the new lib code side-effect-free at top level.
64
+ 3. Add tests under `test/` covering the new path (`npm test` runs
65
+ `test/crewbus.*.mjs` — smoke, harness, compact, tokenfile, digest,
66
+ control-plane, launch, web-launch, pair-api, web-panel, web-approot,
67
+ client-runtime, runtime-wiring, mobile-client,
68
+ grok-hooks, holds-quotas, approval-protocol, approvals-init,
69
+ approvals-web — plus `test/fault-injection.mjs` + `test/integration.mjs`;
70
+ see root `package.json` `scripts.test`).
71
+
72
+ ## Embeds note
73
+
74
+ The `OPENCODE_TOOL_DM_SEND` / `OPENCODE_PLUGIN_DM_WATCH` template literals
75
+ stay in `bin/crewbus.js` (populated from `opencode/tools/dm-send.js` +
76
+ `opencode/plugins/dm-watch.js`). `sync-embeds.mjs` is unaffected by this
77
+ split — keep running `node sync-embeds.mjs --check` after edits.
78
+
79
+ ## MCP note
80
+
81
+ `bin/crewbus-mcp.js` is still standalone (own copies, no `bin/lib/*`
82
+ imports). Sharing lib modules with the MCP server is future work, NOT done.
package/docs/TENANCY.md CHANGED
@@ -11,7 +11,7 @@ inboxes, no tenant-aware routing — a board IS the tenant boundary.
11
11
  access to the board files can read everything on that board (tokens stop
12
12
  CLI-level `--from` spoofing, not local file tampering) — separate
13
13
  directories per trust zone.
14
- - Name the tenant: `quota set --from <admin> --tenant acme` stores
14
+ - Name the tenant: `quota set --from orchestrator --tenant acme` stores
15
15
  `tenant: "acme"` in `board.json`. `quota show` and `storage --json`
16
16
  report it. It is a label, not an enforcement mechanism; the directory
17
17
  is the enforcement.
@@ -21,10 +21,10 @@ inboxes, no tenant-aware routing — a board IS the tenant boundary.
21
21
  `board export` is the tenant-move vehicle:
22
22
 
23
23
  ```
24
- # on board A (admin or auditor)
25
- crewbus board export --from <admin> --out ./acme.abbackup.json
24
+ # on board A (orchestrator)
25
+ crewbus board export --from orchestrator --out ./acme.abbackup.json
26
26
  # creates board B
27
- crewbus board import --from <admin> --in ./acme.abbackup.json --into <dir-B> --force
27
+ crewbus board import --from orchestrator --in ./acme.abbackup.json --into <dir-B> --force
28
28
  ```
29
29
 
30
30
  Exports are encrypted with AES-256-GCM (key = 32-byte hex/base64 used raw,
@@ -40,28 +40,28 @@ warning, encrypt the file, store it like a password).
40
40
  unlimited).
41
41
 
42
42
  ```
43
- crewbus quota set --from <admin> --max-bytes 10mb --max-agents 50 --max-channels 20
44
- crewbus quota set --from <admin> --max-bytes unlimited # clear one
45
- crewbus quota set --from <admin> --clear # clear all
43
+ crewbus quota set --from orchestrator --max-bytes 10mb --max-agents 50 --max-channels 20
44
+ crewbus quota set --from orchestrator --max-bytes unlimited # clear one
45
+ crewbus quota set --from orchestrator --clear # clear all
46
46
  crewbus quota show [--json]
47
47
  ```
48
48
 
49
49
  Enforcement is check-then-write, best-effort (races under parallel writers
50
50
  may overshoot; the single-writer case refuses loudly BEFORE the write):
51
51
 
52
- - `register` (including admin grants) refuses new identities at `maxAgents`
52
+ - `register` (including orchestrator grants) refuses new identities at `maxAgents`
53
53
  (re-registering an existing name never counts as new).
54
54
  - `send` refuses when the estimated new mail would push total board bytes
55
55
  past `maxBytes`.
56
56
  - `channel post` refuses on `maxBytes`; `channel create` refuses at
57
57
  `maxChannels`.
58
- - `quota-set` is admin-only; `quota show` and `storage [--json]` are reads
58
+ - `quota-set` is orchestrator-only; `quota show` and `storage [--json]` are reads
59
59
  (`storage --json` reports `quotas`/`tenant`/`quota` limit-vs-actual).
60
60
 
61
61
  ## Scheduled snapshots (no daemon)
62
62
 
63
63
  ```
64
- crewbus snapshot schedule --from <admin> --every 24h --keep 7 --out-dir /var/backups/ab
64
+ crewbus snapshot schedule --from orchestrator --every 24h --keep 7 --out-dir /var/backups/ab
65
65
  crewbus snapshot run # from cron / systemd / Task Scheduler
66
66
  ```
67
67