crewbus 10.0.12 → 11.3.1

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 (48) hide show
  1. package/AGENTS.template.md +4 -4
  2. package/CHANGELOG.md +153 -0
  3. package/README.md +69 -44
  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 +459 -238
  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 +90 -128
  12. package/bin/lib/launch.js +63 -8
  13. package/bin/lib/relay.js +25 -42
  14. package/bin/lib/spawn.js +155 -162
  15. package/bin/lib/store.js +2 -2
  16. package/bin/lib/web.js +241 -60
  17. package/claude-plugin/skills/crewbus/SKILL.md +1 -1
  18. package/docs/APPROVALS.md +8 -8
  19. package/docs/AUDIT_EXPORT.md +7 -7
  20. package/docs/CERT_READINESS.md +5 -5
  21. package/docs/COMPATIBILITY.md +6 -2
  22. package/docs/CONSOLIDATOR.md +6 -6
  23. package/docs/CONTROL_PLANE_SPEC.md +3 -3
  24. package/docs/CREWS.md +58 -55
  25. package/docs/DELIVERY.md +11 -8
  26. package/docs/GROUPS.md +8 -8
  27. package/docs/IDENTITY.md +6 -6
  28. package/docs/LONG_RUNS.md +3 -3
  29. package/docs/ORCHESTRATOR.md +87 -0
  30. package/docs/PAIRING.md +7 -7
  31. package/docs/QUICKSTART.md +81 -70
  32. package/docs/RBAC.md +84 -73
  33. package/docs/TENANCY.md +10 -10
  34. package/docs/THREAT_MODEL.md +3 -3
  35. package/docs/VERIFIER.md +10 -10
  36. package/docs/VERSION_SKEW.md +1 -1
  37. package/documentation.html +34 -24
  38. package/examples/hermes-pairing.md +3 -3
  39. package/examples/t3-pairing.md +1 -1
  40. package/index.html +6 -6
  41. package/opencode/plugins/dm-watch.js +1 -1
  42. package/opencode/tools/dm-send.js +1 -1
  43. package/package.json +27 -2
  44. package/packages/contracts/harness.json +15 -1
  45. package/packages/contracts/launch.json +2 -3
  46. package/packages/contracts/pairing.json +3 -3
  47. package/docs/LEAD_ASSIGN.md +0 -74
  48. package/docs/M1_CLI_DRAFT.md +0 -175
@@ -1,6 +1,6 @@
1
1
  # Compatibility matrix
2
2
 
3
- Six adapters depend on fast-changing vendor surfaces (hooks, MCP behavior,
3
+ Seven adapters depend on fast-changing vendor surfaces (hooks, MCP behavior,
4
4
  CLI flags). This table records what crewbus expects and when it was last
5
5
  verified. When a harness ships a new release, re-verify its row and update
6
6
  the date; `crewbus doctor` checks wiring presence on your machine (see
@@ -43,11 +43,12 @@ Status per harness (re-check the "no" rows when vendors change flags):
43
43
  accepted by `exec resume <id>`).
44
44
  - cursor: no — id lives in `stream-json`, spawn uses plain print mode.
45
45
  - agy: no — `--print` emits answer text, not the conversation id.
46
+ - qwen: yes, pre-assigned (`--session-id <uuid>` minted at boot, plus `--output-format json` corroboration; mid-run kill leaves resumable id on record).
46
47
 
47
48
  ## Resume commands (used by `respawn`)
48
49
 
49
50
  Honesty authority: `packages/contracts/harness.json` (`version: 1`,
50
- frozen-M0). `resume:true` for opencode / claude / codex / grok
51
+ frozen-M0). `resume:true` for opencode / claude / codex / grok / qwen
51
52
  (`harness.json:15,29,43,57`); `resume:false` for antigravity / cursor /
52
53
  UIs render resume unsupported for those
53
54
  three and never fake continuity. Flags below mirror
@@ -61,6 +62,7 @@ three and never fake continuity. Flags below mirror
61
62
  - codex: `exec <parent opts> resume <id> "<catch-up>"` (parent options
62
63
  precede the subcommand; prompt inline — `exec` has no `--file`).
63
64
  - grok: `--prompt-file <catch-up> -r <id>`.
65
+ - qwen: `--resume <id>` (or `-r <id>`).
64
66
  - agy: `-p "<catch-up>" --conversation <id>` — HONESTLY UNSUPPORTED
65
67
  (`resume:false`): no stable conversation id on stdout, so there is
66
68
  rarely an id to pass; the flag is what `respawn` would use IF one were
@@ -165,6 +167,7 @@ automatically via `experimental.session.compacting`.
165
167
  | codex (Codex CLI) | `PreCompact` / `PostCompact` in hooks config, matcher on `trigger` = `manual`/`auto` (plain stdout ignored; JSON common-output fields) | 2026-10-05 (vendor docs: developers.openai.com/codex/hooks, codex-rs hooks source) |
166
168
  | cursor (`cursor-agent`) | `preCompact` (lowercase c) in `.cursor/hooks.json` — observational only (`user_message` output; cannot block or follow up). Claude-format `PreCompact` also maps via third-party hooks | 2026-10-05 (vendor docs: cursor.com/docs/hooks, third-party-hooks) |
167
169
  | grok-build (`grok`) | `PostCompact` in `.grok/hooks/crewbus.json` (`crewbus-hook compact` rehydration, same invocation shape as claude/codex; project hooks need folder trust — `/hooks-trust` or launch with `--trust`). Fallback for older grok builds: run `crewbus-hook compact --from <you>` as the first post-compaction step, or surface it via the `monitor` stream | 2026-10-07 (vendor docs: docs.x.ai/build/features/hooks — `PreCompact`/`PostCompact` lifecycle events, hook JSON in `~/.grok/hooks/*.json` or `<project>/.grok/hooks/*.json`, event JSON on stdin (`hookEventName`, `sessionId`, `cwd`, `workspaceRoot`) + `GROK_*` env vars, `type` `command`/`http`, project hooks require trust) |
170
+ | qwen (Qwen Code) | `PostCompact` in `.qwen/settings.json` (`crewbus-hook compact` rehydration, same invocation shape as claude/codex) | 2026-10-25 (vendor docs: features/hooks.md) |
168
171
 
169
172
  ## Permission pre-approvals
170
173
 
@@ -181,6 +184,7 @@ or unrelated commands/tools.
181
184
  | claude (Claude Code) | `.claude/settings.json` `permissions.allow` | `mcp__crewbus__*`, `Bash(node *crewbus* *)`, `Bash(crewbus* *)`, `Read(./.crewbus/**)` | everything else (edits, network, other Bash/Read) | verified 2026-10-05 (vendor docs: code.claude.com permissions) |
182
185
  | opencode 1.18.x (v1 line) | `opencode.json` project `permission` object | `dm-send: allow`, `bash: {"*crewbus*": allow}`, `read: {"**/.crewbus/**": allow}` (absent keys/patterns only; shorthand strings left alone) | `edit`, `write`, other tools; v2 `permissions` array format not written | verified 2026-10-05 (vendor docs: opencode.ai permissions) |
183
186
  | cursor (`cursor-agent`) | `.cursor/permissions.json` | `mcpAllowlist: ["crewbus:*"]`, `terminalAllowlist: ["node:*crewbus*", "crewbus"]` | `autoRun` classifier, in-app terminal allowlist beyond bus commands | verified 2026-10-05 (vendor docs: cursor.com permissions reference) |
187
+ | qwen (Qwen Code) | `.qwen/settings.json` `permissions.allow` | `mcp__crewbus__*`, `Bash(node *crewbus* *)`, `Bash(crewbus* *)`, `Read(./.crewbus/**)` | everything else (edits, network, other Bash/Read) | verified 2026-10-25 (vendor docs: configuration/settings.md) |
184
188
  | codex (Codex CLI) | none (project-local) — skipped | nothing (code comment in `applyHarness`) | `approval_policy`, `mcp_servers.*.approval_mode` (TOML user config; project `.codex/config.toml` needs folder trust first). Note: `spawn` injects `-c approval_policy="never"`, `--dangerously-bypass-hook-trust`, and dynamic ephemeral MCP configuration via `-c mcp_servers.crewbus.*` at runtime | verified 2026-10-21 against live Codex CLI 0.163.0 |
185
189
  | grok-build (`grok`) | none (project-local JSON) — skipped | nothing (code comment in `applyHarness`) | `[permission]` rules in `.grok/config.toml` (TOML — no zero-dep-safe merge); note grok reads Claude-compat `.claude/settings.json`, covered under `--harness claude` | unverified (vendor docs: docs.x.ai permissions; community config reference) |
186
190
  | antigravity (`agy`) | none (project-local) — skipped | nothing (code comment in `applyHarness`) | `permissions.allow` with `mcp(server/*)`, `command(...)` lives in GLOBAL `~/.gemini/antigravity-cli/settings.json`, which init never touches | unverified for project-local (vendor docs: antigravity.google permissions) |
@@ -2,7 +2,7 @@
2
2
 
3
3
  One group rarely finishes the job. The consolidator is a reference worker
4
4
  that **summarizes one group's findings and hands them to the next group**
5
- (or the lead): a small crew solves the easy slice first, its summary
5
+ (or the orchestrator): a small crew solves the easy slice first, its summary
6
6
  seeds the main crews' briefs.
7
7
 
8
8
  ## Quick use
@@ -11,11 +11,11 @@ seeds the main crews' briefs.
11
11
  # group A works a batch; its replies land threaded on the brief
12
12
  batch="<batch-id from the send echo>"
13
13
 
14
- # summarize A's transcript, DM it to the lead, mirror to the group channel
15
- node examples/consolidator.mjs --from gateway --to lead --batch "$batch" --group team-a
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
16
 
17
- # lead briefs group B with A's findings attached
18
- crewbus send --from lead --to-group team-b --subject "variant: build on team-a" --body "<paste summary>"
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
19
  ```
20
20
 
21
21
  What the script does (all via the CLI, token-checked like any agent):
@@ -24,7 +24,7 @@ What the script does (all via the CLI, token-checked like any agent):
24
24
  reply, oldest first.
25
25
  2. Builds an extractive summary: brief count, reply count, first line of
26
26
  each reply, artifact references (`send --artifact`), per-sender counts.
27
- 3. `send --from gateway --to lead --reply <first-brief> --subject "RESULT: <batch>"`
27
+ 3. `send --from gateway --to orchestrator --reply <first-brief> --subject "RESULT: <batch>"`
28
28
  — the handoff, threaded so `thread --id` shows the full chain.
29
29
  4. `channel post grp-team-a` — mirrors the summary to the group-scoped
30
30
  channel, so late joiners and sibling groups can `channel tail` it.
@@ -107,8 +107,8 @@ Missing: launch wizard, harness picker, pairing UI, route management.
107
107
  First claim wins (`writeExclusiveJson`); salted `tokenHash+salt`, never
108
108
  plaintext; `expiresAt/rotatedAt/service/offboarded`; `revoked/` union
109
109
  (copy-if-missing, never undone). Secrets stripped on sync/push/serve/JSON
110
- output; local secrets always win merges. Roles `{admin,lead,worker,auditor}`
111
- (first registration = admin; legacy = lead); `checkToken()` THEN
110
+ output; local secrets always win merges. Roles `{orchestrator, worker}`
111
+ (the board bootstraps one orchestrator; self-registrations are workers); `checkToken()` THEN
112
112
  `authorize()` — never merged, never reordered. Leads kill own crew only;
113
113
  auditors read-only; `acl {defaultRole, frozen}` per board; `group restrict`
114
114
  for private crews.
@@ -240,7 +240,7 @@ back to loopback silently.
240
240
 
241
241
  ### 3.4 Pairing (`pairing.json`)
242
242
 
243
- `POST /api/pair/issue` (admin) → one-time
243
+ `POST /api/pair/issue` (orchestrator) → one-time
244
244
  `crewbus://pair?env=<id>&routes=<json>&caps=<…>#<abp-…>` (secret in
245
245
  FRAGMENT; QR renders the same). `POST /api/pair/exchange` swaps once for
246
246
  `abd-…` with requested scopes ⊆ granted (narrow-only). Devices relay-local,
package/docs/CREWS.md CHANGED
@@ -1,55 +1,58 @@
1
- # Weighted remote crews
2
-
3
- One lead, many relays. Relays advertise a `--weight` (default 100) plus live
4
- worker count in `/healthz`; `crew survey` shows the fleet and `crew dispatch`
5
- splits an elastic crew across reachable primaries by weight (largest
6
- remainder). Standbys and unreachable relays skip loudly — they never silently
7
- absorb workers.
8
-
9
- ## Survey the fleet
10
-
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
- ```
16
-
17
- ## Dispatch
18
-
19
- ```sh
20
- crewbus crew dispatch --from lead \
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). `--dry-run` prints the shares
33
- without booting. Every boot lands under your identity on that relay
34
- (first-claim mints there if needed); replies land on each relay's board —
35
- `sync` them back or `gather` per relay.
36
-
37
- ## Credentials per relay
38
-
39
- Repeat `--relay-auth <url-prefix>=<cred>` for relays that don't share one
40
- secret (`abd-…` values go out as device credentials, anything else as the
41
- shared secret; longest prefix wins). Bare `--secret` / `--device` /
42
- `CREWBUS_*` apply to every relay. Pair each relay first
43
- (`relay pair`, see `docs/PAIRING.md`) and you never share a secret at all.
44
-
45
- ## Properties
46
-
47
- - **Weights are preferences, not quotas.** A relay that goes unreachable or
48
- standby mid-dispatch is skipped; its share is *not* re-dealt (no double
49
- boot) — the summary shows what landed where, and you re-dispatch the rest.
50
- - **Standbys never boot.** They refuse writes with 503; dispatch skips them
51
- loudly rather than queueing into a replica.
52
- - **Deterministic shares.** Same weights + count always split the same way,
53
- so `--dry-run` predicts the real run and tests can assert distributions.
54
- - **Audited both ends.** The lead's board records `crew-dispatch` (relays,
55
- count, shares); each relay records its own `remote-spawn` audit trail.
1
+ # Weighted remote crews
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.
8
+
9
+ ## Survey the fleet
10
+
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
+ ```
16
+
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.
package/docs/DELIVERY.md CHANGED
@@ -46,7 +46,10 @@ the OS recycles pids and a dead worker could read as "running". Status
46
46
  now also resolves the process start time (`ps` elapsed on unix,
47
47
  `Get-Process` on Windows, 60s memo) and compares it against the recorded
48
48
  `spawnedAt` (±120s skew): a live pid whose process started *after* the
49
- spawn is a stranger, and `alive` flips to false. The verdict rides along
49
+ spawn is a stranger, and `alive` flips to false. `spawnedAt` is the launch
50
+ time of the currently recorded pid — it is set at spawn and refreshed on
51
+ every respawn, so a live replacement is not mistaken for a recycled pid.
52
+ The original registration time stays in `firstSeen`. The verdict rides along
50
53
  as `aliveVerified` (`true` corroborated, `false` contradicted, `null`
51
54
  unverifiable on this platform — the old kill-0 verdict stands). The
52
55
  override needs positive evidence (start time after spawn + skew), so a
@@ -63,7 +66,7 @@ Long briefs die mid-way; re-deriving progress from files wastes the
63
66
  resume. Workers checkpoint every few steps (or before anything risky):
64
67
 
65
68
  ```sh
66
- crewbus send --from <you> --to <lead> --reply <brief-id> --checkpoint --body "done X / next Y"
69
+ crewbus send --from <you> --to orchestrator --reply <brief-id> --checkpoint --body "done X / next Y"
67
70
  ```
68
71
 
69
72
  (`dm_send` takes `checkpoint: true`; same on the opencode `dm-send`
@@ -89,7 +92,7 @@ of restarting. Checkpoints are unverified progress: they never feed
89
92
 
90
93
  `pool` briefs all workers up front, boots at most `--pool-size`
91
94
  concurrently, and replaces exits until N total — but the supervision loop
92
- runs inside the invoking CLI process. If that process dies (lead restart,
95
+ runs inside the invoking CLI process. If that process dies (orchestrator restart,
93
96
  shutdown, supervision-window timeout), `pool-resume --id <pool> --from
94
97
  <you>` re-attaches: it reconciles every launched worker (replied → done,
95
98
  live → re-adopted, dead w/o reply → done with a `respawn` hint), then
@@ -98,7 +101,7 @@ by id, never duplicated; one supervisor at a time via an advisory pool
98
101
  lock (TTL expiry lets a later attach take over after a crash).
99
102
  `finishedAt` marks true completion only — a timed-out pool stays
100
103
  resumable. Pools created before the resumable schema (no queue cursor)
101
- are refused with guidance. Lead/admin only.
104
+ are refused with guidance. Orchestrator-only.
102
105
 
103
106
  Windows note: console-less detached `cmd.exe` wrappers linger up to ~60s
104
107
  after their payload exits, so natural-exit detection on `shell:true`
@@ -122,10 +125,10 @@ nobody accepted. The reassign pattern:
122
125
 
123
126
  ```sh
124
127
  # what is still open — and how long has it waited?
125
- crewbus inbox --from lead --unacked --older-than 10m
128
+ crewbus inbox --from orchestrator --unacked --older-than 10m
126
129
 
127
130
  # the brief is a file: re-brief a fresh worker on the same thread
128
- crewbus send --from lead --to w9 --reply <brief-id> --body "picking this up (w3 went silent)"
131
+ crewbus send --from orchestrator --to w9 --reply <brief-id> --body "picking this up (w3 went silent)"
129
132
 
130
133
  # the dead watcher's mail, if any, can be replayed
131
134
  crewbus redeliver --from w3 --all
@@ -177,7 +180,7 @@ terminates everything when the whole run is lost.
177
180
  has no pre-set flag (its id arrives in the first stream event — the
178
181
  residual window is milliseconds); codex relies on `thread.started`;
179
182
  cursor/agy offer neither.
180
- - **Respawn (`respawn --from <lead> --to <worker>`).** Reboots one dead
183
+ - **Respawn (`respawn --from orchestrator --to <worker>`).** Reboots one dead
181
184
  worker in its *same* harness conversation: `opencode run --session`,
182
185
  `claude -p --resume` (+ `CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1` so a
183
186
  killed turn continues), `codex exec resume`, `grok -r`, agy
@@ -188,7 +191,7 @@ terminates everything when the whole run is lost.
188
191
  prompt can't attach files). Refuses live workers unless `--force`
189
192
  (kills first, own-crew scoped like `spawn-kill`); refuses unknown,
190
193
  never-captured, and pre-capture-era workers with re-brief guidance.
191
- Attempts count on the binding; `--dry-run` previews. Lead/admin only.
194
+ Attempts count on the binding; `--dry-run` previews. Orchestrator-only.
192
195
 
193
196
  ## Poll discipline (long runs)
194
197
 
package/docs/GROUPS.md CHANGED
@@ -9,7 +9,7 @@ is replaced by the commands below.
9
9
 
10
10
  ```sh
11
11
  crewbus group create team-a --add a1,a2,a3
12
- crewbus send --from lead --to-group team-a --subject "variant: regularity" --body "..."
12
+ crewbus send --from orchestrator --to-group team-a --subject "variant: regularity" --body "..."
13
13
  crewbus gather --batch <batch> # briefs + replies + telemetry footer + contributing groups
14
14
  ```
15
15
 
@@ -20,7 +20,7 @@ crewbus gather --batch <batch> # briefs + replies + telemetry footer + contrib
20
20
  ## Replies carry artifacts
21
21
 
22
22
  ```sh
23
- crewbus send --from e1 --to lead --reply <brief-id> --artifact out/a1.json --body "done"
23
+ crewbus send --from e1 --to orchestrator --reply <brief-id> --artifact out/a1.json --body "done"
24
24
  ```
25
25
 
26
26
  `--artifact <path-or-url>` (max 500 chars) is stored on the message and
@@ -29,8 +29,8 @@ shown by `inbox` / `gather` / `thread`.
29
29
  ## Verify, then record the result
30
30
 
31
31
  ```sh
32
- crewbus ack --from lead --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 lead
32
+ crewbus ack --from orchestrator --id <reply-id> --verify "node test/check.mjs --input out/a1.json"
33
+ crewbus result record --group team-a --msg <reply-id> --artifact out/a1.json --from orchestrator
34
34
  crewbus result show --group team-a
35
35
  crewbus result list [--group team-a] [--json]
36
36
  ```
@@ -45,7 +45,7 @@ unless `--force` (which prints a warning to stderr).
45
45
 
46
46
  ```sh
47
47
  crewbus race start --group team-a --batch <batch> [--timeout 60000] [--json]
48
- crewbus race close --group team-a --from lead [--kill]
48
+ crewbus race close --group team-a --from orchestrator [--kill]
49
49
  ```
50
50
 
51
51
  `race start` reports the winner (recorded result whose `msgId` is in the
@@ -91,17 +91,17 @@ block assumes:
91
91
 
92
92
  - **Peer-direct for questions.** `crewbus send --from you --to-group
93
93
  <group> --subject "..." --body "..."` reaches every member of
94
- another group. Ask the group that owns a thing first; the lead is
94
+ another group. Ask the group that owns a thing first; the orchestrator is
95
95
  for approvals (`--priority high`) and scope disputes only.
96
96
  - **Channels are the shared read surface.** `crewbus channel tail
97
97
  grp-<group>` shows a group's briefs + mirrored progress; reads need
98
98
  no token. Channel *posting* is member-scoped (default-on, no flag):
99
99
  a worker may post to `grp-<group>` only when it is a MEMBER of that
100
- group — board channels and foreign groups stay lead|admin-only
100
+ group — board channels and foreign groups are orchestrator-only
101
101
  (see docs/RBAC.md).
102
102
  - **Boot habit.** `crewbus agents` + `crewbus group list` once at
103
103
  start, so a worker knows who else is here. A worker that never runs
104
- a discovery command will work star-topology through the lead — that
104
+ a discovery command will work star-topology through the orchestrator — that
105
105
  is a failure of the brief, not the worker.
106
106
  - **Scope questions stay lanes-first.** "Stay in your lane" prevents
107
107
  collisions; "DM the group that owns a thing" prevents silos. A
package/docs/IDENTITY.md CHANGED
@@ -58,8 +58,8 @@ crewbus token status --from alice [--json]
58
58
 
59
59
  ## Mover (rename / team change)
60
60
 
61
- 1. Offboard the old name (admin, token-checked):
62
- `register --offboard old-name --from admin`
61
+ 1. Offboard the old name (orchestrator, token-checked):
62
+ `register --offboard old-name --from orchestrator`
63
63
  2. Register the new name: `register --from new-name`
64
64
  3. History stays: DMs to/from the old name remain on disk and in `--all`
65
65
  dumps for audit.
@@ -68,16 +68,16 @@ crewbus token status --from alice [--json]
68
68
 
69
69
  ```
70
70
  # kill one identity's live tokens (identity stays, they must re-register):
71
- crewbus token revoke --from admin --target bob [--reason "laptop lost"]
71
+ crewbus token revoke --from orchestrator --target bob [--reason "laptop lost"]
72
72
 
73
73
  # full deprovision (revokes tokens + marks offboarded, inbox preserved):
74
- crewbus register --offboard bob --from admin
74
+ crewbus register --offboard bob --from orchestrator
75
75
  ```
76
76
 
77
77
  - Revoked callers get: `token for "bob" is revoked — re-register...`.
78
78
  - Offboarded callers get: `agent "bob" is offboarded — sends ... refused`.
79
79
  - Re-register after revoke mints fresh (no dead token needed);
80
- offboarded names stay refused until an admin re-onboards.
80
+ offboarded names stay refused until the orchestrator re-onboards them.
81
81
 
82
82
  ## Sync hygiene
83
83
 
@@ -160,7 +160,7 @@ Compaction amnesia used to mint throwaway identities (`unknown` on the board,
160
160
  miss does it print the `crewbus recover` instruction — never a "you are
161
161
  unknown" blessing.
162
162
  - **Bindings survive daily traffic:** register stores `sessionId`; later
163
- sessionless sends/re-registers/admin touches must NOT wipe it
163
+ sessionless sends/re-registers/orchestrator touches must NOT wipe it
164
164
  (`mergeAgentDoc` deletes undefined patch keys — callers add `sessionId`
165
165
  to the patch only when given). Heartbeats merge field-by-field and never
166
166
  touch unrelated fields.
package/docs/LONG_RUNS.md CHANGED
@@ -14,7 +14,7 @@ the board.
14
14
  2. Tokens persist themselves: every register/mint/rotate writes
15
15
  `.crewbus/logs/<agent>.token` (0600). Workers re-read it after any
16
16
  restart or compaction instead of re-registering (re-registering a
17
- claimed name fails). Truly lost it? Lead runs `token revoke --target
17
+ claimed name fails). Truly lost it? The orchestrator runs `token revoke --target
18
18
  <name>`, worker re-registers fresh. Never commit or post token files;
19
19
  `prune`/export skip `*.token`.
20
20
  3. Poll digest-first: `inbox --unacked --digest`, full reads only on
@@ -43,10 +43,10 @@ the board.
43
43
  |---|---|
44
44
  | Post-compaction amnesia | Identity card is auto-injected (hook compact / opencode plugin); unknown who you are? run `crewbus recover` — read-only candidate ranking (session binding → token-file↔tokenHash → cwd), then follow the printed resume script |
45
45
  | Landed as "unknown" | Sentinel names ("unknown"/"me"/"you") never mint (register/send refuse them). Run `crewbus recover [--session <id>]` to re-find your real identity; only then re-register your true name |
46
- | Token lost entirely | Lead `token revoke --target`, worker re-registers |
46
+ | Token lost entirely | Orchestrator `token revoke --target`, worker re-registers |
47
47
  | Worker silent | `spawn-status`: no reply → read its log; re-brief or `respawn` |
48
48
  | Supervisor gone | `pool-resume --id`; stale locks expire via TTL |
49
- | Reboot | `doctor` → `spawn-status --all` (stale pids read dead, not running) → `respawn`/`pool-resume`; dead coordinator: `crewbus spawn --count 0 --body "<what the crew was on>"` (C9 lead revive, workers untouched) |
49
+ | Reboot | `doctor` → `spawn-status --all` (stale pids read dead, not running) → `respawn`/`pool-resume`; dead coordinator: `crewbus spawn --count 0 --body "<what the crew was on>"` (C9 orchestrator revive, workers untouched) |
50
50
  | Primary relay down | `relay promote` on the standby (see `docs/HA.md`) |
51
51
 
52
52
  ## Bottom line
@@ -0,0 +1,87 @@
1
+ # Orchestrator & Worker Lane Model
2
+
3
+ Crewbus separates **spawning** from **leading** with exactly two roles.
4
+ `spawn` provisions the board's single **orchestrator** and boots the workers;
5
+ the orchestrator owns the crew, while workers collaborate peer-to-peer.
6
+
7
+ - **Workers** communicate directly, self-organize strategy, and write
8
+ findings to shared ambient memory (the board / Workbench).
9
+ - The **orchestrator** monitors health, chases failures/timeouts, fail-closes
10
+ approvals, verifies claims against actual artifacts, and posts the aggregate.
11
+ - The **user/operator** runs `crewbus spawn` with a brief and a worker count.
12
+ There is no separate `boss`, `admin`, `lead`, or `auditor` identity.
13
+
14
+ ---
15
+
16
+ ## 1. The Lane Model
17
+
18
+ | Lane | Actor | Authority & Responsibilities |
19
+ |---|---|---|
20
+ | **Orchestrator** | Board control plane (`orchestrator`) | • Sets the mission from the user's brief.<br>• Observes health, TTLs, respawns (`spawn-status --all`, `respawn`).<br>• Decides irreversible/high-risk approvals (`fail-closed`).<br>• Audits worker claims against files/logs before aggregating.<br>• Posts the aggregate outcome on the board.<br>• *Never* does workers' implementation tasks. |
21
+ | **Workers** | Worker agents (`worker-1`, `worker-2`, ...) | • Own task strategy, execution, and local decisions.<br>• Direct peer-to-peer DMs for cooperation and rescue calls.<br>• Post lessons and artifacts directly to the board Workbench.<br>• Checkpoint progress along threads.<br>• Consult groups first; escalate to the orchestrator only for scope/approvals. |
22
+
23
+ ---
24
+
25
+ ## 2. CLI: brief + count
26
+
27
+ ```sh
28
+ # Default: provisions or reuses the board orchestrator
29
+ crewbus spawn "Implement feature X" --count 3 --harness opencode
30
+ ```
31
+
32
+ There is no `--from` and no `--lead` flag. `spawn` runs as the board
33
+ orchestrator; `--body "..."` and a positional brief are equivalent.
34
+
35
+ ### Architecture
36
+
37
+ - Auto-provisions or reuses the board's single `orchestrator` lane.
38
+ - Worker briefs pin reply targets and approval requests to `--to orchestrator`.
39
+ - The orchestrator runs persistently to monitor health and approvals.
40
+ - Crewbus requires a coding harness (`opencode`, `claude`, `codex`, `grok`,
41
+ `antigravity`, `cursor`, `qwen`).
42
+
43
+ ---
44
+
45
+ ## 3. Provisioning & Collision Rules
46
+
47
+ 1. **Single identity**
48
+ - `ensureOrchestrator` mints the `orchestrator` identity with
49
+ `role: "orchestrator"` when missing.
50
+ - The token is saved to `logs/orchestrator.token` (token-file convention).
51
+ - `crewbus orchestrator init` bootstraps explicitly; `orchestrator show`
52
+ reports the identity read-only.
53
+
54
+ 2. **Reuse standing orchestrators**
55
+ - If a live, non-stale coordinator runs on the `orchestrator` lane,
56
+ subsequent `spawn` bursts reuse it rather than duplicating it.
57
+ - Workers from new bursts are transferred to the orchestrator
58
+ (`spawnedBy: "orchestrator"`), preserving own-crew permissions for
59
+ health tracking and `spawn-kill`.
60
+
61
+ 3. **Offboarded lane**
62
+ - If the `orchestrator` lane has been marked `offboarded: true`,
63
+ auto-provisioning refuses silently to resurrect a deliberate teardown.
64
+ Re-onboard it explicitly before spawning again.
65
+
66
+ 4. **Revive (`crewbus spawn --count 0`)**
67
+ - Boots NOTHING except the orchestrator lane: zero worker boots, zero DMs.
68
+ - The mission text you pass becomes the orchestrator's reminder of what the
69
+ crew was working on (worker threads and scope live on the board).
70
+ - Worker selectors (`--to`/`--to-file`/`--to-group`) are refused.
71
+ - A standing orchestrator is reused, never duplicated.
72
+
73
+ ---
74
+
75
+ ## 4. Prompt Engineering
76
+
77
+ - **Workers (`buildSpawnPrompt`)**:
78
+ - Direct completion summaries, checkpoints, and approval requests to
79
+ `--to orchestrator`.
80
+ - Tell the worker that the orchestrator owns the crew.
81
+ - Reinforce peer-first habits: consult groups before escalating.
82
+ - **Orchestrator (`buildOrchestratorPrompt`)**:
83
+ - Injected with the verbatim user brief.
84
+ - Lists worker brief IDs for threading and reply tracking.
85
+ - Enforces polling discipline (`listen` / `inbox --digest`), fail-closed
86
+ approval timeouts, and maximum 2 respawn attempts per lane before posting
87
+ the stall on the board.
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