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
@@ -1,194 +1,196 @@
1
- # Compatibility matrix
2
-
3
- Six adapters depend on fast-changing vendor surfaces (hooks, MCP behavior,
4
- CLI flags). This table records what crewbus expects and when it was last
5
- verified. When a harness ships a new release, re-verify its row and update
6
- the date; `crewbus doctor` checks wiring presence on your machine (see
7
- note below).
8
-
9
- Standard-surface preference: where a harness accepts plain MCP tools or
10
- standard lifecycle hooks, crewbus uses those — not per-vendor private
11
- APIs — so rows below stay valid longer.
12
-
13
- | Adapter | Hooks surface | MCP surface | CLI flags used by `spawn` | Last verified |
14
- |---|---|---|---|---|
15
- | opencode 1.18.34 | plugin `client.session.promptAsync` (~1s poll) | `dm-send` tool | `run` + brief via `--file`; `--auto` = auto-approve non-denied permissions (dangerous) | 2026-10-03; CLI flags re-checked 2026-10-07 vs `bin/lib/spawn.js:184-194` |
16
- | claude (Claude Code) | SessionStart + Stop (`{"decision":"block","reason":"…"}`) + PostToolUse/SessionStart `asyncRewake` waiters (`crewbus-hook wait`, exit 2 wakes idle/mid-turn sessions) | stdio MCP (`dm_send`/`dm_inbox`/…) + marketplace-ready bundle in `claude-plugin/` | `-p` (headless), brief on stdin | 2026-10-04; CLI flags re-checked 2026-10-07 vs `bin/lib/spawn.js:196-206` |
17
- | codex (Codex CLI) | SessionStart + Stop, `{"decision":"block","reason":"…"}` | `codex mcp add crewbus -- node ./bin/crewbus-mcp.js` | `exec` pointing at brief file | 2026-09-26; CLI flags re-checked 2026-10-07 vs `bin/lib/spawn.js:208-219` |
18
- | antigravity (`agy` 1.2.5) | Stop + PreInvocation, `{"decision":"continue","reason"}` / `injectSteps` | `.agents/mcp_config.json` | `--print` (`-p`), brief inline; default `--mode accept-edits`; `--auto` = `--dangerously-skip-permissions` (native approval requests can still surface) | 2026-10-03; CLI flags re-checked 2026-10-07 vs `bin/lib/spawn.js:232-240` |
19
- | grok-build (`grok` 1.0.5) | Stop + PostToolUse (`{"decision":"block","reason"}` same-turn notes), `monitor`-tool event stream (`crewbus-hook monitor`, ~1s), `scheduler_create` 60s-minimum fallback | `grok mcp add --scope project crewbus -- node ./bin/crewbus-mcp.js` | headless `--prompt-file` (`-p` prints + exits); default `--permission-mode auto --max-turns 50`; `--auto` = `--always-approve` (blanket, cf. `acceptEdits` middle ground) | 2026-10-04; CLI flags re-checked 2026-10-07 vs `bin/lib/spawn.js:221-230` |
20
- | cursor (`cursor-agent`) | sessionStart + stop, Claude-compatible envelope | `.cursor/mcp.json` (stdio) | `cursor-agent -p --force --trust` (`--auto` adds `--yolo`) | 2026-09-26; CLI flags re-checked 2026-10-07 vs `bin/lib/spawn.js:242-253` |
21
-
22
- M6 re-check scope (2026-10-07): the `CLI flags used by spawn` column above was
23
- re-verified against `buildSpawnTarget()` in `bin/lib/spawn.js` (line refs per
24
- row). The Hooks and MCP columns were NOT re-probed (no live vendor binaries /
25
- vendor-docs re-check performed) — their prior dates stand as-is.
26
-
27
- ## Session-id capture (for a future `respawn`)
28
-
29
- Spawn boots opencode/claude/grok with JSON log output so `spawn-status`
30
- can recover the harness session id into `worker-sessions/<name>.json`.
31
- Status per harness (re-check the "no" rows when vendors change flags):
32
-
33
- - opencode: yes (`run --format json` event stream, id arrives early; no
34
- pre-set flag exists, so a kill before first output still loses it).
35
- - claude: yes, pre-assigned (`--session-id <uuid>` minted at boot, plus
36
- `-p --output-format json` corroboration; note `-p` sessions need the
37
- explicit id — `--continue` skips them).
38
- - grok: yes, pre-assigned (`-s <uuid>` minted at boot; `--output-format
39
- json` corroborates end-of-run — the pre-assign closes the mid-run-kill
40
- gap).
41
- - codex: yes (`exec --json` emits `thread.started {thread_id}` first;
42
- source-verified in `openai/codex` — `session_id: ThreadId`, one namespace,
43
- accepted by `exec resume <id>`; no live binary here to run it against).
44
- - cursor: no — id lives in `stream-json`, spawn uses plain print mode.
45
- - agy: no — `--print` emits answer text, not the conversation id.
46
-
47
- ## Resume commands (used by `respawn`)
48
-
49
- Honesty authority: `packages/contracts/harness.json` (`version: 1`,
50
- frozen-M0). `resume:true` for opencode / claude / codex / grok
51
- (`harness.json:15,29,43,57`); `resume:false` for antigravity / cursor /
52
- generic (`harness.json:71,86,103`) — UIs render resume unsupported for those
53
- three and never fake continuity. Flags below mirror
54
- `buildRespawnTarget()` in `bin/lib/spawn.js:265-284` and the
55
- `LAUNCH_DRIVER_FALLBACK` table in `bin/lib/launch.js:24-30`.
56
-
57
- - opencode: `run --session <id>` (+ `--file`, `--format json` as at spawn).
58
- - claude: `-p --resume <id>` (never `--session-id` alongside — resume
59
- rejects the combination); `CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1` is set
60
- on respawn so a killed turn continues.
61
- - codex: `exec <parent opts> resume <id> "<catch-up>"` (parent options
62
- precede the subcommand; prompt inline — `exec` has no `--file`).
63
- - grok: `--prompt-file <catch-up> -r <id>`.
64
- - agy: `-p "<catch-up>" --conversation <id>` — HONESTLY UNSUPPORTED
65
- (`resume:false`): no stable conversation id on stdout, so there is
66
- rarely an id to pass; the flag is what `respawn` would use IF one were
67
- captured (cf. session-id capture: no).
68
- - cursor: `-p --force --resume <id> "<catch-up>"` — HONESTLY UNSUPPORTED
69
- (`resume:false`): the id lives in `stream-json` while spawn uses plain
70
- print mode; same conditional as agy.
71
- - generic: no continuity — fresh boot of the catch-up brief
72
- (`resume:false`; `bin/lib/spawn.js:273-274,288-290`).
73
-
74
- ## `doctor`: what it checks (and what it can't)
75
-
76
- `crewbus doctor` validates Node ≥ 18, board schema v2, the `AGENTS.md`
77
- block, and per-harness wiring files (hook references, MCP server entries).
78
- It prints `ok` / `FAIL` / `info` lines and exits 1 when broken, plus the
79
- resolved board, `CREWBUS_DIR` state, cwd, and git rev for split-board
80
- diagnosis.
81
-
82
- Behavioral note: `doctor` checks wiring *presence*, not live harness
83
- behavior — steps it cannot verify (e.g. Codex/grok MCP registration, trust
84
- grants, harness binaries actually running) print as `info` reminders. Where
85
- a harness binary is installed, prefer the behavioral check: invoke
86
- `<harness> --version` / `--help` and confirm the flags in the row above
87
- still exist; treat a missing binary as "not installed", not as a failure.
88
- Contributions extending `doctor` toward behavioral checks (tolerant when the
89
- binary is absent) are welcome — keep them read-only and fast.
90
-
91
- ## Harness-release CI note
92
-
93
- On each harness release (where licensing allows), re-run `npm test` with the
94
- new harness binaries present so `test/integration.mjs` exercises the real
95
- `spawn --dry-run` paths, refresh the `Last verified` dates above, and note
96
- any flag changes in the changelog. Vendors change flags without notice —
97
- this table rots unless someone re-checks it per release.
98
-
99
- ## Control-plane additions (v10.0.0)
100
-
101
- Since the last vendor-verification dates above, the control plane landed
102
- (M0+M1 `2a1015c`, M6-lite `0893026`, M2 `3715344`, M3 `46e8989`, M4
103
- `2972b1c`, M5 `7569ddd`) — all ADDITIVE, confirmed against the current
104
- tree. No verified adapter, session-capture, resume, or compaction row moved:
105
-
106
- - `crewbus launch` wizard: validates the plan against
107
- `packages/contracts/launch.json`, previews exact commands with
108
- `--dry-run`, then delegates to the SAME spawn path (`bin/crewbus.js:2929-2932`;
109
- no new spawn logic).
110
- - `crewbus harnesses [detect]`: lists the 7 drivers with live binary
111
- presence via `detectHarnessBinaries()` (`bin/lib/launch.js:66-76`;
112
- contracts file wins when it holds 7 drivers, else the fallback table,
113
- `bin/lib/launch.js:33-41`).
114
- - `relay pair qr`: prints the one-time `crewbus://pair` URL (secret in
115
- `#fragment`, never query) alongside the plain token
116
- (`bin/crewbus.js:4523-4530`; `buildPairUrl`, `bin/lib/launch.js:127-132`).
117
- - Pair API: `POST /api/pair/issue`, `POST /api/pair/exchange`,
118
- `GET /api/pair/devices`, `POST /api/pair/revoke`
119
- (`bin/crewbus.js:5372,5498,5624,5661`); device creds stay relay-local
120
- (never synced/exported — see `docs/VERSION_SKEW.md`).
121
- - `POST /api/launch` on relay (`bin/crewbus.js:5224-5232`, same gates as
122
- `/api/spawn` plus launch-plan validation) and web dashboard
123
- (`bin/lib/web.js:1107-1109`); `GET /api/harnesses` (`bin/lib/web.js:1091-1097`)
124
- and `GET /api/routes` (`bin/lib/web.js:1098-1106`; relay shape at
125
- `bin/crewbus.js:5805-5814`); `serve --advertise-routes --pair-qrcode`
126
- (`bin/crewbus.js:4690-4694`).
127
- - `driver` field: worker records carry `driver`/`spawnedHarness`
128
- (`bin/lib/spawn.js:706-710`; remote-spawn results, `bin/lib/relay.js:299`);
129
- the dashboard renders `driver` + `resume` per the contracts table
130
- (`bin/lib/web.js:385,631,781`); `launch --dry-run` previews per-driver
131
- resume support (`bin/crewbus.js:3001`).
132
- - Capability `launch`: `controlPlaneCaps` in
133
- `packages/contracts/board-caps.json:8` (with the degrade note at `:17`);
134
- advertised alongside the relay caps (`bin/crewbus.js:4530,5809`;
135
- `bin/lib/web.js:1104`).
136
-
137
- Explicit statement: none of the above renames, removes, or re-semantics any
138
- `spawn` flag, session-capture shape, `respawn` flag, or compaction hook in the
139
- verified rows — `buildSpawnTarget()` (`bin/lib/spawn.js:182-256`) and the
140
- `harness.json` driver truth (7 drivers, `resume` flags) are unchanged, and the
141
- control plane reads that same table through `launchDrivers()`.
142
- Carve-out (not this pass): the grok compaction row below was rewritten to
143
- 2026-10-07 by concurrent in-progress work (grok `PostCompact` init/doctor
144
- wiring, uncommitted in `bin/crewbus.js`) — its vendor-docs citation was not
145
- checked here.
146
- See `docs/VERSION_SKEW.md` for how old peers degrade against these caps.
147
-
148
- ## Compaction hooks (context rehydration after summarize/compact)
149
-
150
- A long-running agent that survives a harness compaction wakes up having
151
- forgotten its name, board path, and token. The shared rehydration surface is:
152
-
153
- crewbus-hook compact --from <you> [--board <path>]
154
-
155
- which prints a minimal identity card (agent, board, token-file path, inbox
156
- next step; spawned workers also get their brief promptPath read
157
- best-effort from `worker-sessions/<agent>.json`). It never fails on missing
158
- files — it prints what is known — so it is safe to wire as a
159
- post-compaction hook anywhere. The opencode watcher pushes the same card
160
- automatically via `experimental.session.compacting`.
161
-
162
- | Harness | Rehydration surface | Last verified |
163
- |---|---|---|
164
- | claude (Claude Code) | `SessionStart` hook with `"matcher": "compact"` (re-inject after every compaction), and/or `PreCompact` (before; can block compaction) / `PostCompact` (after) | 2026-10-05 (vendor docs: code.claude.com hooks-guide, docs.anthropic.com hooks reference) |
165
- | opencode | plugin `experimental.session.compacting` handler (`input: { sessionID }`, push lines into `output.context`); name is experimental and may change | 2026-10-05 (vendor source: `session/compaction.ts` trigger, opencode.ai docs/plugins) |
166
- | 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) |
167
- | 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) |
168
- | 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) |
169
-
170
- ## Permission pre-approvals
171
-
172
- `init --harness` pre-approves *board-only bus I/O* so spawned workers never
173
- stall on the bus itself (crewbus MCP server, hook/CLI commands mentioning
174
- crewbus, board-path reads). All writes are additive JSON merges (same
175
- pattern as hooks/MCP merges): user config is never overwritten, re-runs are
176
- byte-identical. Harness permissions otherwise stay the user's — init
177
- deliberately does NOT widen edits/writes outside the board, network access,
178
- or unrelated commands/tools.
179
-
180
- | Harness | Allowlist surface | What `init` writes | Deliberately NOT widened | Status |
181
- |---|---|---|---|---|
182
- | 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) |
183
- | 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) |
184
- | 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) |
185
- | 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) | unverified for project-local pre-approval (vendor docs: developers.openai.com codex config-reference) |
186
- | 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) |
187
- | 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) |
188
- | copilot | n/a — skipped | nothing (not an `init --harness` adapter) | all copilot approval policy | unverified (no adapter in this repo) |
189
- | generic | n/a — skipped | nothing (no config surface) | n/a | n/a |
190
-
191
- Verification: `node test/crewbus.approvals-init.mjs` asserts the three
192
- wired harnesses (entries written, re-run byte-identical, user config
193
- preserved) and that the skipped harnesses gain no approval files. Re-verify
194
- a row when its vendor changes the allowlist format.
1
+ # Compatibility matrix
2
+
3
+ Seven adapters depend on fast-changing vendor surfaces (hooks, MCP behavior,
4
+ CLI flags). This table records what crewbus expects and when it was last
5
+ verified. When a harness ships a new release, re-verify its row and update
6
+ the date; `crewbus doctor` checks wiring presence on your machine (see
7
+ note below).
8
+
9
+ Standard-surface preference: where a harness accepts plain MCP tools or
10
+ standard lifecycle hooks, crewbus uses those — not per-vendor private
11
+ APIs — so rows below stay valid longer.
12
+
13
+ | Adapter | Hooks surface | MCP surface | CLI flags used by `spawn` | Last verified |
14
+ |---|---|---|---|---|
15
+ | opencode 1.18.34 | plugin `client.session.promptAsync` (~1s poll) | `dm-send` tool | `run` + brief via `--file`; `--auto` = auto-approve non-denied permissions (dangerous) | 2026-10-03; CLI flags re-checked 2026-10-07 vs `bin/lib/spawn.js:184-194` |
16
+ | claude (Claude Code 2.1.306) | SessionStart + Stop (`{"decision":"block","reason":"…"}`) + PostToolUse/SessionStart `asyncRewake` waiters (`crewbus-hook wait`, exit 2 wakes idle/mid-turn sessions) | stdio MCP (`dm_send`/`dm_inbox`/…) + marketplace-ready bundle in `claude-plugin/` | `-p` (headless), brief on stdin, `--session-id <uuid>` pre-assign, `--allowedTools` includes `mcp__crewbus__*`; `--auto` = `--dangerously-skip-permissions` | 2026-10-21 (live Claude Code CLI 2.1.306 re-verification) |
17
+ | codex (Codex CLI 0.163.0) | SessionStart + Stop, `{"decision":"block","reason":"…"}` | Dynamic ephemeral MCP mounted via `-c mcp_servers.crewbus.*` at spawn time, or user TOML config | `exec --json --sandbox <mode> -c approval_policy="never" --dangerously-bypass-hook-trust --skip-git-repo-check -C <cwd>`; `--auto` adds `--dangerously-bypass-approvals-and-sandbox`; brief via stdin + positional | 2026-10-21 (live Codex CLI 0.163.0 re-verification) |
18
+ | antigravity (`agy` 1.2.5) | Stop + PreInvocation, `{"decision":"continue","reason"}` / `injectSteps` | `.agents/mcp_config.json` | `--print` (`-p`), brief inline; default `--mode accept-edits`; `--auto` = `--dangerously-skip-permissions` (native approval requests can still surface) | 2026-10-21 (live Antigravity CLI re-verification) |
19
+ | grok-build (`grok` 1.0.5) | Stop + PostToolUse (`{"decision":"block","reason"}` same-turn notes), `monitor`-tool event stream (`crewbus-hook monitor`, ~1s), `scheduler_create` 60s-minimum fallback | `grok mcp add --scope project crewbus -- node ./bin/crewbus-mcp.js` | headless `--prompt-file` (`-p` prints + exits); default `--permission-mode auto --max-turns 50`; `--auto` = `--always-approve` (blanket, cf. `acceptEdits` middle ground) | 2026-10-04; CLI flags re-checked 2026-10-07 vs `bin/lib/spawn.js:221-230` |
20
+ | cursor (`cursor-agent`) | sessionStart + stop, Claude-compatible envelope | `.cursor/mcp.json` (stdio) | `cursor-agent -p --force --trust` (`--auto` adds `--yolo`) | 2026-09-26; CLI flags re-checked 2026-10-07 vs `bin/lib/spawn.js:242-253` |
21
+
22
+ M6 re-check scope (2026-10-07): the `CLI flags used by spawn` column above was
23
+ re-verified against `buildSpawnTarget()` in `bin/lib/spawn.js` (line refs per
24
+ row). The Hooks and MCP columns were NOT re-probed (no live vendor binaries /
25
+ vendor-docs re-check performed) — their prior dates stand as-is.
26
+
27
+ ## Session-id capture (for a future `respawn`)
28
+
29
+ Spawn boots opencode/claude/grok with JSON log output so `spawn-status`
30
+ can recover the harness session id into `worker-sessions/<name>.json`.
31
+ Status per harness (re-check the "no" rows when vendors change flags):
32
+
33
+ - opencode: yes (`run --format json` event stream, id arrives early; no
34
+ pre-set flag exists, so a kill before first output still loses it).
35
+ - claude: yes, pre-assigned (`--session-id <uuid>` minted at boot, plus
36
+ `-p --output-format json` corroboration; note `-p` sessions need the
37
+ explicit id — `--continue` skips them).
38
+ - grok: yes, pre-assigned (`-s <uuid>` minted at boot; `--output-format
39
+ json` corroborates end-of-run — the pre-assign closes the mid-run-kill
40
+ gap).
41
+ - codex: yes (`exec --json` emits `thread.started {thread_id}` first;
42
+ verified against live Codex CLI 0.163.0 — `session_id: ThreadId`, one namespace,
43
+ accepted by `exec resume <id>`).
44
+ - cursor: no — id lives in `stream-json`, spawn uses plain print mode.
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).
47
+
48
+ ## Resume commands (used by `respawn`)
49
+
50
+ Honesty authority: `packages/contracts/harness.json` (`version: 1`,
51
+ frozen-M0). `resume:true` for opencode / claude / codex / grok / qwen
52
+ (`harness.json:15,29,43,57`); `resume:false` for antigravity / cursor /
53
+ UIs render resume unsupported for those
54
+ three and never fake continuity. Flags below mirror
55
+ `buildRespawnTarget()` in `bin/lib/spawn.js:265-284` and the
56
+ `LAUNCH_DRIVER_FALLBACK` table in `bin/lib/launch.js:24-30`.
57
+
58
+ - opencode: `run --session <id>` (+ `--file`, `--format json` as at spawn).
59
+ - claude: `-p --resume <id>` (never `--session-id` alongside — resume
60
+ rejects the combination); `CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1` is set
61
+ on respawn so a killed turn continues.
62
+ - codex: `exec <parent opts> resume <id> "<catch-up>"` (parent options
63
+ precede the subcommand; prompt inline — `exec` has no `--file`).
64
+ - grok: `--prompt-file <catch-up> -r <id>`.
65
+ - qwen: `--resume <id>` (or `-r <id>`).
66
+ - agy: `-p "<catch-up>" --conversation <id>` — HONESTLY UNSUPPORTED
67
+ (`resume:false`): no stable conversation id on stdout, so there is
68
+ rarely an id to pass; the flag is what `respawn` would use IF one were
69
+ captured (cf. session-id capture: no).
70
+ - cursor: `-p --force --resume <id> "<catch-up>"` — HONESTLY UNSUPPORTED
71
+ (`resume:false`): the id lives in `stream-json` while spawn uses plain
72
+ print mode; same conditional as agy.
73
+ (`resume:false`; `bin/lib/spawn.js:273-274,288-290`).
74
+
75
+ ## `doctor`: what it checks (and what it can't)
76
+
77
+ `crewbus doctor` validates Node ≥ 18, board schema v2, the `AGENTS.md`
78
+ block, and per-harness wiring files (hook references, MCP server entries).
79
+ It prints `ok` / `FAIL` / `info` lines and exits 1 when broken, plus the
80
+ resolved board, `CREWBUS_DIR` state, cwd, and git rev for split-board
81
+ diagnosis.
82
+
83
+ Behavioral note: `doctor` checks wiring *presence*, not live harness
84
+ behavior — steps it cannot verify (e.g. Codex/grok MCP registration, trust
85
+ grants, harness binaries actually running) print as `info` reminders. Where
86
+ a harness binary is installed, prefer the behavioral check: invoke
87
+ `<harness> --version` / `--help` and confirm the flags in the row above
88
+ still exist; treat a missing binary as "not installed", not as a failure.
89
+ Contributions extending `doctor` toward behavioral checks (tolerant when the
90
+ binary is absent) are welcome — keep them read-only and fast.
91
+
92
+ ## Harness-release CI note
93
+
94
+ On each harness release (where licensing allows), re-run `npm test` with the
95
+ new harness binaries present so `test/integration.mjs` exercises the real
96
+ `spawn --dry-run` paths, refresh the `Last verified` dates above, and note
97
+ any flag changes in the changelog. Vendors change flags without notice —
98
+ this table rots unless someone re-checks it per release.
99
+
100
+ ## Control-plane additions (v10.0.0)
101
+
102
+ Since the last vendor-verification dates above, the control plane landed
103
+ (M0+M1 `2a1015c`, M6-lite `0893026`, M2 `3715344`, M3 `46e8989`, M4
104
+ `2972b1c`, M5 `7569ddd`) — all ADDITIVE, confirmed against the current
105
+ tree. No verified adapter, session-capture, resume, or compaction row moved:
106
+
107
+ - `crewbus launch` wizard: validates the plan against
108
+ `packages/contracts/launch.json`, previews exact commands with
109
+ `--dry-run`, then delegates to the SAME spawn path (`bin/crewbus.js:2929-2932`;
110
+ no new spawn logic).
111
+ - `crewbus harnesses [detect]`: lists the 7 drivers with live binary
112
+ presence via `detectHarnessBinaries()` (`bin/lib/launch.js:66-76`;
113
+ contracts file wins when it holds 7 drivers, else the fallback table,
114
+ `bin/lib/launch.js:33-41`).
115
+ - `relay pair qr`: prints the one-time `crewbus://pair` URL (secret in
116
+ `#fragment`, never query) alongside the plain token
117
+ (`bin/crewbus.js:4523-4530`; `buildPairUrl`, `bin/lib/launch.js:127-132`).
118
+ - Pair API: `POST /api/pair/issue`, `POST /api/pair/exchange`,
119
+ `GET /api/pair/devices`, `POST /api/pair/revoke`
120
+ (`bin/crewbus.js:5372,5498,5624,5661`); device creds stay relay-local
121
+ (never synced/exported — see `docs/VERSION_SKEW.md`).
122
+ - `POST /api/launch` on relay (`bin/crewbus.js:5224-5232`, same gates as
123
+ `/api/spawn` plus launch-plan validation) and web dashboard
124
+ (`bin/lib/web.js:1107-1109`); `GET /api/harnesses` (`bin/lib/web.js:1091-1097`)
125
+ and `GET /api/routes` (`bin/lib/web.js:1098-1106`; relay shape at
126
+ `bin/crewbus.js:5805-5814`); `serve --advertise-routes --pair-qrcode`
127
+ (`bin/crewbus.js:4690-4694`).
128
+ - `driver` field: worker records carry `driver`/`spawnedHarness`
129
+ (`bin/lib/spawn.js:706-710`; remote-spawn results, `bin/lib/relay.js:299`);
130
+ the dashboard renders `driver` + `resume` per the contracts table
131
+ (`bin/lib/web.js:385,631,781`); `launch --dry-run` previews per-driver
132
+ resume support (`bin/crewbus.js:3001`).
133
+ - Capability `launch`: `controlPlaneCaps` in
134
+ `packages/contracts/board-caps.json:8` (with the degrade note at `:17`);
135
+ advertised alongside the relay caps (`bin/crewbus.js:4530,5809`;
136
+ `bin/lib/web.js:1104`).
137
+
138
+ Explicit statement: none of the above renames, removes, or re-semantics any
139
+ `spawn` flag, session-capture shape, `respawn` flag, or compaction hook in the
140
+ verified rows — `buildSpawnTarget()` (`bin/lib/spawn.js:182-256`) and the
141
+ `harness.json` driver truth (7 drivers, `resume` flags) are unchanged, and the
142
+ control plane reads that same table through `launchDrivers()`.
143
+ Carve-out (not this pass): the grok compaction row below was rewritten to
144
+ 2026-10-07 by concurrent in-progress work (grok `PostCompact` init/doctor
145
+ wiring, uncommitted in `bin/crewbus.js`) — its vendor-docs citation was not
146
+ checked here.
147
+ See `docs/VERSION_SKEW.md` for how old peers degrade against these caps.
148
+
149
+ ## Compaction hooks (context rehydration after summarize/compact)
150
+
151
+ A long-running agent that survives a harness compaction wakes up having
152
+ forgotten its name, board path, and token. The shared rehydration surface is:
153
+
154
+ crewbus-hook compact --from <you> [--board <path>]
155
+
156
+ which prints a minimal identity card (agent, board, token-file path, inbox
157
+ next step; spawned workers also get their brief promptPath read
158
+ best-effort from `worker-sessions/<agent>.json`). It never fails on missing
159
+ files — it prints what is known — so it is safe to wire as a
160
+ post-compaction hook anywhere. The opencode watcher pushes the same card
161
+ automatically via `experimental.session.compacting`.
162
+
163
+ | Harness | Rehydration surface | Last verified |
164
+ |---|---|---|
165
+ | claude (Claude Code) | `SessionStart` hook with `"matcher": "compact"` (re-inject after every compaction), and/or `PreCompact` (before; can block compaction) / `PostCompact` (after) | 2026-10-05 (vendor docs: code.claude.com hooks-guide, docs.anthropic.com hooks reference) |
166
+ | opencode | plugin `experimental.session.compacting` handler (`input: { sessionID }`, push lines into `output.context`); name is experimental and may change | 2026-10-05 (vendor source: `session/compaction.ts` trigger, opencode.ai docs/plugins) |
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) |
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) |
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) |
171
+
172
+ ## Permission pre-approvals
173
+
174
+ `init --harness` pre-approves *board-only bus I/O* so spawned workers never
175
+ stall on the bus itself (crewbus MCP server, hook/CLI commands mentioning
176
+ crewbus, board-path reads). All writes are additive JSON merges (same
177
+ pattern as hooks/MCP merges): user config is never overwritten, re-runs are
178
+ byte-identical. Harness permissions otherwise stay the user's — init
179
+ deliberately does NOT widen edits/writes outside the board, network access,
180
+ or unrelated commands/tools.
181
+
182
+ | Harness | Allowlist surface | What `init` writes | Deliberately NOT widened | Status |
183
+ |---|---|---|---|---|
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) |
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) |
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) |
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 |
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) |
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) |
191
+ | copilot | n/a — skipped | nothing (not an `init --harness` adapter) | all copilot approval policy | unverified (no adapter in this repo) |
192
+
193
+ Verification: `node test/crewbus.approvals-init.mjs` asserts the three
194
+ wired harnesses (entries written, re-run byte-identical, user config
195
+ preserved) and that the skipped harnesses gain no approval files. Re-verify
196
+ a row when its vendor changes the allowlist format.
@@ -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.
@@ -1,7 +1,7 @@
1
1
  # CrewBus Control Plane — spec (M0 frozen)
2
2
 
3
3
  Status: active build spec. Audience: contributors building the CLI launch
4
- wizard, evolved web dashboard, desktop shell, and mobile client in parallel.
4
+ wizard, evolved web dashboard, and mobile client in parallel.
5
5
 
6
6
  Converges spec slices 1–5: CrewBus core audit, t3Code provider pattern,
7
7
  t3Code UI layout, t3Code sync/connectivity/auth.
@@ -61,7 +61,7 @@ Constants: `MAX_BODY_CHARS=8000`, `MAX_RECIPIENTS=10000`, `MAX_SPAWN=20`,
61
61
 
62
62
  | Verb | Key flags | Lib owner |
63
63
  |---|---|---|
64
- | `init [--harness opencode,claude,codex,antigravity,grok,cursor,generic]` | `--global --board --force --no-opencode --portable` | monolith `cmdInit` |
64
+ | `init [--harness opencode,claude,codex,antigravity,grok,cursor]` | `--global --board --force --no-opencode --portable` | monolith `cmdInit` |
65
65
  | `register --from <you>` | `--session --token --role --expires-in --service --offboard --for` | `identity.js` |
66
66
  | `send --from --to --body` | `--subject --reply --priority --checkpoint --sender-type --to-group --no-rate-limit --yes` | `mail.js` |
67
67
  | `inbox --from` | `--after --unacked --digest --grep --priority --json` | `mail.js` |
@@ -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.
@@ -139,19 +139,17 @@ lazily fills `worker-sessions/<name>.json` (machine-local, NEVER synced).
139
139
  | Harness | Spawn | Brief | Session capture | Respawn |
140
140
  |---|---|---|---|---|
141
141
  | opencode | `run --file <brief> --format json` | file | early stream event | `run --session <id>` |
142
- | claude | `-p --output-format json --session-id <uuid>` | stdin | preassigned + log | `-p --resume <id>` + resume-interrupted env |
143
- | codex | `exec --json` | inline positional | `thread.started.thread_id` | `exec <opts> resume <id> "<catchup>"` |
142
+ | claude | `-p --output-format json --session-id <uuid> --allowedTools ...` | stdin | preassigned + log | `-p --resume <id>` + resume-interrupted env |
143
+ | codex | `exec --json -c approval_policy="never" --dangerously-bypass-hook-trust` | stdin + positional | `thread.started.thread_id` | `exec <opts> resume <id> "<catchup>"` |
144
144
  | grok | `--prompt-file -s <uuid> --output-format json` | file | preassigned (end-of-run log) | `--prompt-file <catchup> -r <id>` |
145
145
  | antigravity | `--print --mode accept-edits` | inline | none | `-p "<catchup>" --conversation <id>` (rare) |
146
146
  | cursor | `cursor-agent -p --force --trust` | inline | none | `-p --force --resume <id>` (rare) |
147
- | generic | `--cmd "<arbitrary>"` | n/a | none | fresh boot only |
148
147
 
149
- `--auto` per harness: opencode auto-approve, claude `-p` unattended, grok
150
- `--always-approve`, cursor `--yolo`, agy `--dangerously-skip-permissions`.
148
+ `--auto` per harness: opencode auto-approve, claude `--dangerously-skip-permissions`, codex `--dangerously-bypass-approvals-and-sandbox`, grok `--permission-mode bypassPermissions --always-approve`, cursor `--yolo`, agy `--dangerously-skip-permissions`.
151
149
  Requires `--i-understand-danger` (or TTY `yes`) + sandbox warning
152
150
  (`docs/ISOLATION.md`). cursor/agy resume = honestly unsupported until
153
151
  vendors emit stable ids. `doctor` checks wiring presence, not live behavior.
154
- Windows: detached `cmd.exe` wrappers linger ~60s; kills report immediately.
152
+ Windows: native `.exe` binaries launch directly via `resolveHarnessExe` with `shell: false` (exact PID tracking, immediate unbuffered stdio); legacy `.cmd` shims route safely through `resolveShellShot`.
155
153
 
156
154
  ### 1.7 Extension points (where the plane hooks in)
157
155
 
@@ -163,7 +161,7 @@ Windows: detached `cmd.exe` wrappers linger ~60s; kills report immediately.
163
161
  | `pair qr` / mobile pairing | wrap `newPairToken()`; QR encodes `crewbus://pair?...#abp-…` (fragment secret) |
164
162
  | Routes / env identity | extend `relay.json` + `/healthz` with `envId + advertisedRoutes + capabilities` |
165
163
  | `POST /api/launch` | same validation as wizard → `bootWorker` local or `remoteSpawn` per relay |
166
- | Desktop sidecar | spawn `node bin/crewbus.js serve --port 0` on loopback, own lifecycle |
164
+ | Web Dashboard | standalone loopback dashboard via `crewbus web [--open]` with /pair route |
167
165
  | Mobile client | `GET /api/*` + `POST /api/launch|kill|ack|approve` + `/sync/wait`; no FS access |
168
166
  | Scoped device creds | extend `parseDeviceCred` + `requireRelaySecret` → `requireScope(rpc)` |
169
167
  ## 2. t3Code lessons (reference: `pingdotgg/t3code`)
@@ -242,7 +240,7 @@ back to loopback silently.
242
240
 
243
241
  ### 3.4 Pairing (`pairing.json`)
244
242
 
245
- `POST /api/pair/issue` (admin) → one-time
243
+ `POST /api/pair/issue` (orchestrator) → one-time
246
244
  `crewbus://pair?env=<id>&routes=<json>&caps=<…>#<abp-…>` (secret in
247
245
  FRAGMENT; QR renders the same). `POST /api/pair/exchange` swaps once for
248
246
  `abd-…` with requested scopes ⊆ granted (narrow-only). Devices relay-local,
@@ -284,7 +282,7 @@ ack). Reuse snapshot shapes; add `GET /api/harnesses`, `GET /api/routes`,
284
282
  `POST /api/launch`, `POST /api/pair/issue|exchange`. Poll 5s → SSE later.
285
283
  Tokens in tab memory (opt-in persist).
286
284
 
287
- ### 4.3 Desktop (`apps/desktop`, Tauri preferred)
285
+ ### 4.3 Web Dashboard & Pair (`crewbus web`)
288
286
 
289
287
  Same web UI via local scheme; main owns sidecar
290
288
  (`node bin/crewbus.js serve --port 0` loopback), SSH tunnels, pairing
@@ -313,7 +311,7 @@ secret sync, mutation auto-replay, silent loopback fallback.
313
311
  crewbus/ bin/ + bin/lib/* (additive only)
314
312
  packages/contracts/ harness.json launch.json pairing.json board-caps.json
315
313
  packages/client-runtime/ supervisor, routes, auth store, cache, hooks
316
- apps/web/ apps/desktop/ apps/mobile/
314
+ apps/mobile/
317
315
  docs/CONTROL_PLANE_SPEC.md (this file)
318
316
  test/crewbus.control-plane.mjs
319
317
  ```