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.
- package/CHANGELOG.md +16 -0
- package/README.md +690 -708
- package/bin/crewbus.js +49 -139
- package/bin/lib/identity.js +3 -25
- package/bin/lib/launch.js +68 -25
- package/bin/lib/qrcode.js +2971 -0
- package/bin/lib/relay.js +2 -13
- package/bin/lib/spawn.js +95 -41
- package/bin/lib/web.js +235 -20
- package/docs/CERT_READINESS.md +120 -120
- package/docs/COMPATIBILITY.md +192 -194
- package/docs/CONTROL_PLANE_SPEC.md +9 -11
- package/docs/CREWS.md +55 -55
- package/docs/DELIVERY.md +210 -210
- package/docs/HA.md +151 -151
- package/docs/LEAD_ASSIGN.md +74 -85
- package/docs/M1_CLI_DRAFT.md +2 -2
- package/docs/QUICKSTART.md +70 -70
- package/docs/SPLIT.md +82 -82
- package/docs/THREAT_MODEL.md +68 -69
- package/docs/VERSION_SKEW.md +57 -57
- package/documentation.html +10 -11
- package/examples/hermes-pairing.md +2 -2
- package/index.html +10 -11
- package/opencode/tools/dm-send.js +3 -12
- package/package.json +50 -50
- package/packages/client-runtime/README.md +40 -40
- package/packages/contracts/harness.json +93 -110
- package/packages/contracts/launch.json +1 -1
- package/docs/DESKTOP_SPIKE.md +0 -223
package/docs/COMPATIBILITY.md
CHANGED
|
@@ -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
|
|
17
|
-
| codex (Codex CLI) | SessionStart + Stop, `{"decision":"block","reason":"…"}` |
|
|
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-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
`
|
|
119
|
-
(`
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
`bin/crewbus.js:
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
(`bin/
|
|
131
|
-
|
|
132
|
-
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
|
165
|
-
|
|
|
166
|
-
|
|
|
167
|
-
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
|
183
|
-
|
|
|
184
|
-
|
|
|
185
|
-
|
|
|
186
|
-
|
|
|
187
|
-
|
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
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,
|
|
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
|
|
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
|
|
143
|
-
| codex | `exec --json` |
|
|
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
|
|
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:
|
|
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
|
-
|
|
|
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
|
|
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/
|
|
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
|
|
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.
|