crewbus 10.0.11 → 10.0.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,194 +1,192 @@
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
+ 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 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
+
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
+ 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
+ (`resume:false`; `bin/lib/spawn.js:273-274,288-290`).
72
+
73
+ ## `doctor`: what it checks (and what it can't)
74
+
75
+ `crewbus doctor` validates Node ≥ 18, board schema v2, the `AGENTS.md`
76
+ block, and per-harness wiring files (hook references, MCP server entries).
77
+ It prints `ok` / `FAIL` / `info` lines and exits 1 when broken, plus the
78
+ resolved board, `CREWBUS_DIR` state, cwd, and git rev for split-board
79
+ diagnosis.
80
+
81
+ Behavioral note: `doctor` checks wiring *presence*, not live harness
82
+ behavior — steps it cannot verify (e.g. Codex/grok MCP registration, trust
83
+ grants, harness binaries actually running) print as `info` reminders. Where
84
+ a harness binary is installed, prefer the behavioral check: invoke
85
+ `<harness> --version` / `--help` and confirm the flags in the row above
86
+ still exist; treat a missing binary as "not installed", not as a failure.
87
+ Contributions extending `doctor` toward behavioral checks (tolerant when the
88
+ binary is absent) are welcome — keep them read-only and fast.
89
+
90
+ ## Harness-release CI note
91
+
92
+ On each harness release (where licensing allows), re-run `npm test` with the
93
+ new harness binaries present so `test/integration.mjs` exercises the real
94
+ `spawn --dry-run` paths, refresh the `Last verified` dates above, and note
95
+ any flag changes in the changelog. Vendors change flags without notice —
96
+ this table rots unless someone re-checks it per release.
97
+
98
+ ## Control-plane additions (v10.0.0)
99
+
100
+ Since the last vendor-verification dates above, the control plane landed
101
+ (M0+M1 `2a1015c`, M6-lite `0893026`, M2 `3715344`, M3 `46e8989`, M4
102
+ `2972b1c`, M5 `7569ddd`) — all ADDITIVE, confirmed against the current
103
+ tree. No verified adapter, session-capture, resume, or compaction row moved:
104
+
105
+ - `crewbus launch` wizard: validates the plan against
106
+ `packages/contracts/launch.json`, previews exact commands with
107
+ `--dry-run`, then delegates to the SAME spawn path (`bin/crewbus.js:2929-2932`;
108
+ no new spawn logic).
109
+ - `crewbus harnesses [detect]`: lists the 7 drivers with live binary
110
+ presence via `detectHarnessBinaries()` (`bin/lib/launch.js:66-76`;
111
+ contracts file wins when it holds 7 drivers, else the fallback table,
112
+ `bin/lib/launch.js:33-41`).
113
+ - `relay pair qr`: prints the one-time `crewbus://pair` URL (secret in
114
+ `#fragment`, never query) alongside the plain token
115
+ (`bin/crewbus.js:4523-4530`; `buildPairUrl`, `bin/lib/launch.js:127-132`).
116
+ - Pair API: `POST /api/pair/issue`, `POST /api/pair/exchange`,
117
+ `GET /api/pair/devices`, `POST /api/pair/revoke`
118
+ (`bin/crewbus.js:5372,5498,5624,5661`); device creds stay relay-local
119
+ (never synced/exported — see `docs/VERSION_SKEW.md`).
120
+ - `POST /api/launch` on relay (`bin/crewbus.js:5224-5232`, same gates as
121
+ `/api/spawn` plus launch-plan validation) and web dashboard
122
+ (`bin/lib/web.js:1107-1109`); `GET /api/harnesses` (`bin/lib/web.js:1091-1097`)
123
+ and `GET /api/routes` (`bin/lib/web.js:1098-1106`; relay shape at
124
+ `bin/crewbus.js:5805-5814`); `serve --advertise-routes --pair-qrcode`
125
+ (`bin/crewbus.js:4690-4694`).
126
+ - `driver` field: worker records carry `driver`/`spawnedHarness`
127
+ (`bin/lib/spawn.js:706-710`; remote-spawn results, `bin/lib/relay.js:299`);
128
+ the dashboard renders `driver` + `resume` per the contracts table
129
+ (`bin/lib/web.js:385,631,781`); `launch --dry-run` previews per-driver
130
+ resume support (`bin/crewbus.js:3001`).
131
+ - Capability `launch`: `controlPlaneCaps` in
132
+ `packages/contracts/board-caps.json:8` (with the degrade note at `:17`);
133
+ advertised alongside the relay caps (`bin/crewbus.js:4530,5809`;
134
+ `bin/lib/web.js:1104`).
135
+
136
+ Explicit statement: none of the above renames, removes, or re-semantics any
137
+ `spawn` flag, session-capture shape, `respawn` flag, or compaction hook in the
138
+ verified rows — `buildSpawnTarget()` (`bin/lib/spawn.js:182-256`) and the
139
+ `harness.json` driver truth (7 drivers, `resume` flags) are unchanged, and the
140
+ control plane reads that same table through `launchDrivers()`.
141
+ Carve-out (not this pass): the grok compaction row below was rewritten to
142
+ 2026-10-07 by concurrent in-progress work (grok `PostCompact` init/doctor
143
+ wiring, uncommitted in `bin/crewbus.js`) — its vendor-docs citation was not
144
+ checked here.
145
+ See `docs/VERSION_SKEW.md` for how old peers degrade against these caps.
146
+
147
+ ## Compaction hooks (context rehydration after summarize/compact)
148
+
149
+ A long-running agent that survives a harness compaction wakes up having
150
+ forgotten its name, board path, and token. The shared rehydration surface is:
151
+
152
+ crewbus-hook compact --from <you> [--board <path>]
153
+
154
+ which prints a minimal identity card (agent, board, token-file path, inbox
155
+ next step; spawned workers also get their brief promptPath read
156
+ best-effort from `worker-sessions/<agent>.json`). It never fails on missing
157
+ files — it prints what is known — so it is safe to wire as a
158
+ post-compaction hook anywhere. The opencode watcher pushes the same card
159
+ automatically via `experimental.session.compacting`.
160
+
161
+ | Harness | Rehydration surface | Last verified |
162
+ |---|---|---|
163
+ | 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) |
164
+ | 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) |
165
+ | 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
+ | 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
+ | 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) |
168
+
169
+ ## Permission pre-approvals
170
+
171
+ `init --harness` pre-approves *board-only bus I/O* so spawned workers never
172
+ stall on the bus itself (crewbus MCP server, hook/CLI commands mentioning
173
+ crewbus, board-path reads). All writes are additive JSON merges (same
174
+ pattern as hooks/MCP merges): user config is never overwritten, re-runs are
175
+ byte-identical. Harness permissions otherwise stay the user's — init
176
+ deliberately does NOT widen edits/writes outside the board, network access,
177
+ or unrelated commands/tools.
178
+
179
+ | Harness | Allowlist surface | What `init` writes | Deliberately NOT widened | Status |
180
+ |---|---|---|---|---|
181
+ | 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
+ | 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
+ | 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) |
184
+ | 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
+ | 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
+ | 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) |
187
+ | copilot | n/a — skipped | nothing (not an `init --harness` adapter) | all copilot approval policy | unverified (no adapter in this repo) |
188
+
189
+ Verification: `node test/crewbus.approvals-init.mjs` asserts the three
190
+ wired harnesses (entries written, re-run byte-identical, user config
191
+ preserved) and that the skipped harnesses gain no approval files. Re-verify
192
+ a row when its vendor changes the allowlist format.
@@ -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` |
@@ -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`)
@@ -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
  ```
package/docs/CREWS.md CHANGED
@@ -1,55 +1,55 @@
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 generic --cmd "node worker.js" \
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 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.