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.
- package/AGENTS.template.md +4 -4
- package/CHANGELOG.md +151 -0
- package/README.md +713 -706
- package/TEAM.template.md +1 -1
- package/bin/crewbus-hook.js +22 -5
- package/bin/crewbus-mcp.js +56 -48
- package/bin/crewbus.js +486 -355
- package/bin/lib/channels.js +1 -1
- package/bin/lib/export.js +1 -1
- package/bin/lib/groups.js +1 -5
- package/bin/lib/identity.js +92 -152
- package/bin/lib/launch.js +128 -30
- package/bin/lib/qrcode.js +2971 -0
- package/bin/lib/relay.js +26 -54
- package/bin/lib/spawn.js +241 -194
- package/bin/lib/store.js +2 -2
- package/bin/lib/web.js +277 -59
- package/claude-plugin/skills/crewbus/SKILL.md +1 -1
- package/docs/APPROVALS.md +8 -8
- package/docs/AUDIT_EXPORT.md +7 -7
- package/docs/CERT_READINESS.md +120 -120
- package/docs/COMPATIBILITY.md +196 -194
- package/docs/CONSOLIDATOR.md +6 -6
- package/docs/CONTROL_PLANE_SPEC.md +12 -14
- package/docs/CREWS.md +16 -13
- package/docs/DELIVERY.md +213 -210
- package/docs/GROUPS.md +8 -8
- package/docs/HA.md +151 -151
- package/docs/IDENTITY.md +6 -6
- package/docs/LEAD_ASSIGN.md +3 -85
- package/docs/LONG_RUNS.md +3 -3
- package/docs/M1_CLI_DRAFT.md +9 -9
- package/docs/ORCHESTRATOR.md +87 -0
- package/docs/PAIRING.md +7 -7
- package/docs/QUICKSTART.md +24 -13
- package/docs/RBAC.md +84 -73
- package/docs/SPLIT.md +82 -82
- package/docs/TENANCY.md +10 -10
- package/docs/THREAT_MODEL.md +68 -69
- package/docs/VERIFIER.md +10 -10
- package/docs/VERSION_SKEW.md +57 -57
- package/documentation.html +37 -29
- package/examples/hermes-pairing.md +3 -3
- package/examples/t3-pairing.md +1 -1
- package/index.html +13 -14
- package/opencode/plugins/dm-watch.js +1 -1
- package/opencode/tools/dm-send.js +4 -13
- package/package.json +75 -50
- package/packages/client-runtime/README.md +40 -40
- package/packages/contracts/harness.json +108 -111
- package/packages/contracts/launch.json +2 -3
- package/packages/contracts/pairing.json +3 -3
- package/docs/DESKTOP_SPIKE.md +0 -223
package/docs/HA.md
CHANGED
|
@@ -1,151 +1,151 @@
|
|
|
1
|
-
# HA relay (Phase 3): active/passive, no consensus
|
|
2
|
-
|
|
3
|
-
One writer, one (or more) read-replicas. There is **no consensus, no leader
|
|
4
|
-
election, no automatic conflict resolution beyond the existing sync merge**
|
|
5
|
-
(immutable mail = union-by-id, presence/cursors/groups/holds = HLC LWW,
|
|
6
|
-
tombstones suppress resurrected deletes). The standby is a normal board that
|
|
7
|
-
pulls from the primary with the regular sync engine and refuses writes.
|
|
8
|
-
|
|
9
|
-
## Topology
|
|
10
|
-
|
|
11
|
-
```
|
|
12
|
-
┌─────────────┐
|
|
13
|
-
writers ──────▶│ PRIMARY │◀────── writers
|
|
14
|
-
(sync push, │ serve │
|
|
15
|
-
spawn/kill) └──────┬──────┘
|
|
16
|
-
│ sync pull (standby-initiated, --relay-interval)
|
|
17
|
-
┌──────▼──────┐
|
|
18
|
-
readers ───────▶│ STANDBY │◀────── readers
|
|
19
|
-
(GET manifest/ │ serve │
|
|
20
|
-
file/wait) │ --standby │
|
|
21
|
-
└─────────────┘
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
- **Writes go to the primary only.** Sync clients need no changes: they push
|
|
25
|
-
to whichever relay URL they are configured with, and a standby answers
|
|
26
|
-
`503 {role: "standby", primary: <url>}` with an `X-Relay-Role: standby`
|
|
27
|
-
header so operators (and scripts) know where the writer is.
|
|
28
|
-
- **Reads scale out:** put a load balancer over primary + standbys for GET
|
|
29
|
-
paths (`/sync/manifest`, `/sync/file`, `/sync/wait`, `/api/events`,
|
|
30
|
-
`/healthz`). Never balance writes across relays — there is exactly one
|
|
31
|
-
writer.
|
|
32
|
-
- **Manual failover is recommended.** Auto-promote is opt-in (see below).
|
|
33
|
-
|
|
34
|
-
## Running a standby
|
|
35
|
-
|
|
36
|
-
Standby and primary **share the relay secret** (`--secret` /
|
|
37
|
-
`CREWBUS_SECRET`) so the standby can pull `/sync/*` from the primary.
|
|
38
|
-
Outbound TLS flags (`--insecure`, `--mtls-cert`/`--mtls-key`,
|
|
39
|
-
`--bearer`/`--oidc-token`) are honored for the upstream pull.
|
|
40
|
-
|
|
41
|
-
```
|
|
42
|
-
# primary (as before)
|
|
43
|
-
crewbus serve --port 8080 --secret "$RELAY_SECRET"
|
|
44
|
-
|
|
45
|
-
# standby: empty board that tracks the primary every 5s (default)
|
|
46
|
-
crewbus init --board /var/boards/replica.crewbus --harness
|
|
47
|
-
CREWBUS_DIR=/var/boards/replica.crewbus \
|
|
48
|
-
crewbus serve --port 8081 --secret "$RELAY_SECRET" \
|
|
49
|
-
--standby http://primary:8080 [--relay-interval 5]
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
### Transport note: Tailscale
|
|
53
|
-
|
|
54
|
-
Relays bind localhost; anything multi-machine needs a transport you
|
|
55
|
-
trust (see `SECURITY.md`: never face the open internet without a tunnel
|
|
56
|
-
on top). The boring, recommended answer is a mesh VPN like Tailscale:
|
|
57
|
-
run the relay commands above unchanged but address peers by tailnet name
|
|
58
|
-
(`--standby http://pi:8080`), and you get encrypted transport, stable
|
|
59
|
-
hostnames across reboots and DHCP churn, and NAT traversal for sync
|
|
60
|
-
peers behind home routers — with nothing ever exposed publicly. Keep
|
|
61
|
-
the relay secret + OIDC/TLS layers on anyway (defense in depth, and
|
|
62
|
-
the same setup works verbatim without the mesh). Tailscale is an
|
|
63
|
-
operator choice, never a dependency: crewbus ships zero network
|
|
64
|
-
code beyond its own HTTP relay.
|
|
65
|
-
|
|
66
|
-
While a standby, the server:
|
|
67
|
-
|
|
68
|
-
- pulls via `syncRound` on `--relay-interval` seconds (per-peer cursor in
|
|
69
|
-
`sync-state/`, same overlap logic as `sync --interval`);
|
|
70
|
-
- serves GET reads from its local (replicated) board;
|
|
71
|
-
- refuses `POST /sync/put`, `POST /api/spawn`, `POST /api/launch`,
|
|
72
|
-
`POST /api/kill`, and pair writes (`POST /api/pair/issue|exchange|revoke`)
|
|
73
|
-
with **503 + `X-Relay-Role: standby`** and a JSON `{error, role, primary}`
|
|
74
|
-
hint — checked *before* the relay secret, so load balancers and clients
|
|
75
|
-
get a clean signal without credentials (pair reads such as
|
|
76
|
-
`GET /api/pair/devices` still serve locally);
|
|
77
|
-
- records state in `<board>/relay.json`
|
|
78
|
-
(`role`, `primary`, `lastSyncOk`, `lagMs`, `consecFails`, `promotion`,
|
|
79
|
-
`promotedAt`, `fence`).
|
|
80
|
-
|
|
81
|
-
## Health + status
|
|
82
|
-
|
|
83
|
-
- `GET /healthz` (no auth — safe for load-balancer probes):
|
|
84
|
-
`{role, weight, workers, advertisedRoutes, primary, lagMs, lastSyncOk,
|
|
85
|
-
lastSyncErr, promotion, promotedAt, uptimeSec}` (`advertisedRoutes` from
|
|
86
|
-
`--advertise-routes`; `weight` from `--weight`; `workers` = live spawned
|
|
87
|
-
pids) with an `X-Relay-Role` header. Route reads to `role ==
|
|
88
|
-
"standby"` **or** the primary; shed a replica when `lagMs` exceeds your
|
|
89
|
-
SLO.
|
|
90
|
-
- `crewbus relay status [--json] [--board <path>]` prints the same state
|
|
91
|
-
from `relay.json` — works with no server running.
|
|
92
|
-
|
|
93
|
-
## Failover
|
|
94
|
-
|
|
95
|
-
**Manual (recommended):**
|
|
96
|
-
|
|
97
|
-
```
|
|
98
|
-
crewbus relay promote --board /var/boards/replica.crewbus [--fence <path-or-url>]
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
A running standby re-reads `relay.json` on every request and sync tick, so
|
|
102
|
-
promotion takes effect **without restart**: the next write is accepted and
|
|
103
|
-
the pull loop stops. Verify with `relay status` and `GET /healthz`.
|
|
104
|
-
|
|
105
|
-
**Automatic (opt-in):**
|
|
106
|
-
|
|
107
|
-
```
|
|
108
|
-
crewbus serve ... --standby http://primary:8080 --promote-on-miss 30
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
After N seconds with no successful pull, the standby promotes itself.
|
|
112
|
-
This is a liveness heuristic, not consensus.
|
|
113
|
-
|
|
114
|
-
## Split-brain risk + fencing guidance (read this before --promote-on-miss)
|
|
115
|
-
|
|
116
|
-
Two writers diverge: each accepts mail/spawns, and the sync merge reunites
|
|
117
|
-
only what its rules cover (mail unions cleanly; presence/cursors take HLC
|
|
118
|
-
LWW — the loser's state is silently dropped). **There is exactly one safe
|
|
119
|
-
configuration: at most one reachable writer.**
|
|
120
|
-
|
|
121
|
-
- Default to manual failover: kill (or firewall) the old primary, then
|
|
122
|
-
`relay promote` the standby. Dead primary + promoted standby = no split
|
|
123
|
-
brain, ever.
|
|
124
|
-
- If you use `--promote-on-miss`, also pass `--fence <path-or-url>`:
|
|
125
|
-
a shared lock both relays can reach. Promotion claims it; a fresh claim
|
|
126
|
-
by a *different* owner refuses the next promotion. A local path fence
|
|
127
|
-
works when both relays share a disk (writes `{owner, at}` JSON, 120s
|
|
128
|
-
freshness window); an HTTP(S) fence URL is liveness-checked via its own
|
|
129
|
-
`/healthz` (a live `primary` there refuses). Fencing is **best-effort**:
|
|
130
|
-
it raises the bar, it does not make concurrent writers impossible under
|
|
131
|
-
partitions. `relay promote --force` overrides it (log who forced, and
|
|
132
|
-
why).
|
|
133
|
-
- After failover, treat the old primary as **poisoned** until you rebuild
|
|
134
|
-
it as a fresh standby (re-`init` an empty board, point `--standby` at the
|
|
135
|
-
new primary). Never let the old primary serve writes again with its old
|
|
136
|
-
state while the promoted one is live.
|
|
137
|
-
- `relay.json` + `sync-state/` are local-only (never synced), so a
|
|
138
|
-
re-purposed board carries no stale role into its next life — but double
|
|
139
|
-
check `relay status` before opening writes.
|
|
140
|
-
|
|
141
|
-
## Limits (honest scope)
|
|
142
|
-
|
|
143
|
-
- No consensus / quorum / term numbers: partitions are resolved by operator
|
|
144
|
-
procedure, not by the software.
|
|
145
|
-
- Replication lag is pull-interval-bound (`--relay-interval`, default 5s);
|
|
146
|
-
a standby can serve reads up to `lagMs` stale — check `/healthz`.
|
|
147
|
-
- Fencing is advisory file/HTTP checks, not distributed locks.
|
|
148
|
-
- Audit forwarder state (`audit-spool/`) is per-relay: run
|
|
149
|
-
`--audit-forward` on the primary; a promoted standby starts forwarding
|
|
150
|
-
from its own spool (at-least-once may re-deliver events the old primary
|
|
151
|
-
already forwarded — SIEM dedup on `seq`+`board` covers it).
|
|
1
|
+
# HA relay (Phase 3): active/passive, no consensus
|
|
2
|
+
|
|
3
|
+
One writer, one (or more) read-replicas. There is **no consensus, no leader
|
|
4
|
+
election, no automatic conflict resolution beyond the existing sync merge**
|
|
5
|
+
(immutable mail = union-by-id, presence/cursors/groups/holds = HLC LWW,
|
|
6
|
+
tombstones suppress resurrected deletes). The standby is a normal board that
|
|
7
|
+
pulls from the primary with the regular sync engine and refuses writes.
|
|
8
|
+
|
|
9
|
+
## Topology
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
┌─────────────┐
|
|
13
|
+
writers ──────▶│ PRIMARY │◀────── writers
|
|
14
|
+
(sync push, │ serve │
|
|
15
|
+
spawn/kill) └──────┬──────┘
|
|
16
|
+
│ sync pull (standby-initiated, --relay-interval)
|
|
17
|
+
┌──────▼──────┐
|
|
18
|
+
readers ───────▶│ STANDBY │◀────── readers
|
|
19
|
+
(GET manifest/ │ serve │
|
|
20
|
+
file/wait) │ --standby │
|
|
21
|
+
└─────────────┘
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
- **Writes go to the primary only.** Sync clients need no changes: they push
|
|
25
|
+
to whichever relay URL they are configured with, and a standby answers
|
|
26
|
+
`503 {role: "standby", primary: <url>}` with an `X-Relay-Role: standby`
|
|
27
|
+
header so operators (and scripts) know where the writer is.
|
|
28
|
+
- **Reads scale out:** put a load balancer over primary + standbys for GET
|
|
29
|
+
paths (`/sync/manifest`, `/sync/file`, `/sync/wait`, `/api/events`,
|
|
30
|
+
`/healthz`). Never balance writes across relays — there is exactly one
|
|
31
|
+
writer.
|
|
32
|
+
- **Manual failover is recommended.** Auto-promote is opt-in (see below).
|
|
33
|
+
|
|
34
|
+
## Running a standby
|
|
35
|
+
|
|
36
|
+
Standby and primary **share the relay secret** (`--secret` /
|
|
37
|
+
`CREWBUS_SECRET`) so the standby can pull `/sync/*` from the primary.
|
|
38
|
+
Outbound TLS flags (`--insecure`, `--mtls-cert`/`--mtls-key`,
|
|
39
|
+
`--bearer`/`--oidc-token`) are honored for the upstream pull.
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
# primary (as before)
|
|
43
|
+
crewbus serve --port 8080 --secret "$RELAY_SECRET"
|
|
44
|
+
|
|
45
|
+
# standby: empty board that tracks the primary every 5s (default)
|
|
46
|
+
crewbus init --board /var/boards/replica.crewbus --harness opencode
|
|
47
|
+
CREWBUS_DIR=/var/boards/replica.crewbus \
|
|
48
|
+
crewbus serve --port 8081 --secret "$RELAY_SECRET" \
|
|
49
|
+
--standby http://primary:8080 [--relay-interval 5]
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
### Transport note: Tailscale
|
|
53
|
+
|
|
54
|
+
Relays bind localhost; anything multi-machine needs a transport you
|
|
55
|
+
trust (see `SECURITY.md`: never face the open internet without a tunnel
|
|
56
|
+
on top). The boring, recommended answer is a mesh VPN like Tailscale:
|
|
57
|
+
run the relay commands above unchanged but address peers by tailnet name
|
|
58
|
+
(`--standby http://pi:8080`), and you get encrypted transport, stable
|
|
59
|
+
hostnames across reboots and DHCP churn, and NAT traversal for sync
|
|
60
|
+
peers behind home routers — with nothing ever exposed publicly. Keep
|
|
61
|
+
the relay secret + OIDC/TLS layers on anyway (defense in depth, and
|
|
62
|
+
the same setup works verbatim without the mesh). Tailscale is an
|
|
63
|
+
operator choice, never a dependency: crewbus ships zero network
|
|
64
|
+
code beyond its own HTTP relay.
|
|
65
|
+
|
|
66
|
+
While a standby, the server:
|
|
67
|
+
|
|
68
|
+
- pulls via `syncRound` on `--relay-interval` seconds (per-peer cursor in
|
|
69
|
+
`sync-state/`, same overlap logic as `sync --interval`);
|
|
70
|
+
- serves GET reads from its local (replicated) board;
|
|
71
|
+
- refuses `POST /sync/put`, `POST /api/spawn`, `POST /api/launch`,
|
|
72
|
+
`POST /api/kill`, and pair writes (`POST /api/pair/issue|exchange|revoke`)
|
|
73
|
+
with **503 + `X-Relay-Role: standby`** and a JSON `{error, role, primary}`
|
|
74
|
+
hint — checked *before* the relay secret, so load balancers and clients
|
|
75
|
+
get a clean signal without credentials (pair reads such as
|
|
76
|
+
`GET /api/pair/devices` still serve locally);
|
|
77
|
+
- records state in `<board>/relay.json`
|
|
78
|
+
(`role`, `primary`, `lastSyncOk`, `lagMs`, `consecFails`, `promotion`,
|
|
79
|
+
`promotedAt`, `fence`).
|
|
80
|
+
|
|
81
|
+
## Health + status
|
|
82
|
+
|
|
83
|
+
- `GET /healthz` (no auth — safe for load-balancer probes):
|
|
84
|
+
`{role, weight, workers, advertisedRoutes, primary, lagMs, lastSyncOk,
|
|
85
|
+
lastSyncErr, promotion, promotedAt, uptimeSec}` (`advertisedRoutes` from
|
|
86
|
+
`--advertise-routes`; `weight` from `--weight`; `workers` = live spawned
|
|
87
|
+
pids) with an `X-Relay-Role` header. Route reads to `role ==
|
|
88
|
+
"standby"` **or** the primary; shed a replica when `lagMs` exceeds your
|
|
89
|
+
SLO.
|
|
90
|
+
- `crewbus relay status [--json] [--board <path>]` prints the same state
|
|
91
|
+
from `relay.json` — works with no server running.
|
|
92
|
+
|
|
93
|
+
## Failover
|
|
94
|
+
|
|
95
|
+
**Manual (recommended):**
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
crewbus relay promote --board /var/boards/replica.crewbus [--fence <path-or-url>]
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
A running standby re-reads `relay.json` on every request and sync tick, so
|
|
102
|
+
promotion takes effect **without restart**: the next write is accepted and
|
|
103
|
+
the pull loop stops. Verify with `relay status` and `GET /healthz`.
|
|
104
|
+
|
|
105
|
+
**Automatic (opt-in):**
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
crewbus serve ... --standby http://primary:8080 --promote-on-miss 30
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
After N seconds with no successful pull, the standby promotes itself.
|
|
112
|
+
This is a liveness heuristic, not consensus.
|
|
113
|
+
|
|
114
|
+
## Split-brain risk + fencing guidance (read this before --promote-on-miss)
|
|
115
|
+
|
|
116
|
+
Two writers diverge: each accepts mail/spawns, and the sync merge reunites
|
|
117
|
+
only what its rules cover (mail unions cleanly; presence/cursors take HLC
|
|
118
|
+
LWW — the loser's state is silently dropped). **There is exactly one safe
|
|
119
|
+
configuration: at most one reachable writer.**
|
|
120
|
+
|
|
121
|
+
- Default to manual failover: kill (or firewall) the old primary, then
|
|
122
|
+
`relay promote` the standby. Dead primary + promoted standby = no split
|
|
123
|
+
brain, ever.
|
|
124
|
+
- If you use `--promote-on-miss`, also pass `--fence <path-or-url>`:
|
|
125
|
+
a shared lock both relays can reach. Promotion claims it; a fresh claim
|
|
126
|
+
by a *different* owner refuses the next promotion. A local path fence
|
|
127
|
+
works when both relays share a disk (writes `{owner, at}` JSON, 120s
|
|
128
|
+
freshness window); an HTTP(S) fence URL is liveness-checked via its own
|
|
129
|
+
`/healthz` (a live `primary` there refuses). Fencing is **best-effort**:
|
|
130
|
+
it raises the bar, it does not make concurrent writers impossible under
|
|
131
|
+
partitions. `relay promote --force` overrides it (log who forced, and
|
|
132
|
+
why).
|
|
133
|
+
- After failover, treat the old primary as **poisoned** until you rebuild
|
|
134
|
+
it as a fresh standby (re-`init` an empty board, point `--standby` at the
|
|
135
|
+
new primary). Never let the old primary serve writes again with its old
|
|
136
|
+
state while the promoted one is live.
|
|
137
|
+
- `relay.json` + `sync-state/` are local-only (never synced), so a
|
|
138
|
+
re-purposed board carries no stale role into its next life — but double
|
|
139
|
+
check `relay status` before opening writes.
|
|
140
|
+
|
|
141
|
+
## Limits (honest scope)
|
|
142
|
+
|
|
143
|
+
- No consensus / quorum / term numbers: partitions are resolved by operator
|
|
144
|
+
procedure, not by the software.
|
|
145
|
+
- Replication lag is pull-interval-bound (`--relay-interval`, default 5s);
|
|
146
|
+
a standby can serve reads up to `lagMs` stale — check `/healthz`.
|
|
147
|
+
- Fencing is advisory file/HTTP checks, not distributed locks.
|
|
148
|
+
- Audit forwarder state (`audit-spool/`) is per-relay: run
|
|
149
|
+
`--audit-forward` on the primary; a promoted standby starts forwarding
|
|
150
|
+
from its own spool (at-least-once may re-deliver events the old primary
|
|
151
|
+
already forwarded — SIEM dedup on `seq`+`board` covers it).
|
package/docs/IDENTITY.md
CHANGED
|
@@ -58,8 +58,8 @@ crewbus token status --from alice [--json]
|
|
|
58
58
|
|
|
59
59
|
## Mover (rename / team change)
|
|
60
60
|
|
|
61
|
-
1. Offboard the old name (
|
|
62
|
-
`register --offboard old-name --from
|
|
61
|
+
1. Offboard the old name (orchestrator, token-checked):
|
|
62
|
+
`register --offboard old-name --from orchestrator`
|
|
63
63
|
2. Register the new name: `register --from new-name`
|
|
64
64
|
3. History stays: DMs to/from the old name remain on disk and in `--all`
|
|
65
65
|
dumps for audit.
|
|
@@ -68,16 +68,16 @@ crewbus token status --from alice [--json]
|
|
|
68
68
|
|
|
69
69
|
```
|
|
70
70
|
# kill one identity's live tokens (identity stays, they must re-register):
|
|
71
|
-
crewbus token revoke --from
|
|
71
|
+
crewbus token revoke --from orchestrator --target bob [--reason "laptop lost"]
|
|
72
72
|
|
|
73
73
|
# full deprovision (revokes tokens + marks offboarded, inbox preserved):
|
|
74
|
-
crewbus register --offboard bob --from
|
|
74
|
+
crewbus register --offboard bob --from orchestrator
|
|
75
75
|
```
|
|
76
76
|
|
|
77
77
|
- Revoked callers get: `token for "bob" is revoked — re-register...`.
|
|
78
78
|
- Offboarded callers get: `agent "bob" is offboarded — sends ... refused`.
|
|
79
79
|
- Re-register after revoke mints fresh (no dead token needed);
|
|
80
|
-
offboarded names stay refused until
|
|
80
|
+
offboarded names stay refused until the orchestrator re-onboards them.
|
|
81
81
|
|
|
82
82
|
## Sync hygiene
|
|
83
83
|
|
|
@@ -160,7 +160,7 @@ Compaction amnesia used to mint throwaway identities (`unknown` on the board,
|
|
|
160
160
|
miss does it print the `crewbus recover` instruction — never a "you are
|
|
161
161
|
unknown" blessing.
|
|
162
162
|
- **Bindings survive daily traffic:** register stores `sessionId`; later
|
|
163
|
-
sessionless sends/re-registers/
|
|
163
|
+
sessionless sends/re-registers/orchestrator touches must NOT wipe it
|
|
164
164
|
(`mergeAgentDoc` deletes undefined patch keys — callers add `sessionId`
|
|
165
165
|
to the patch only when given). Heartbeats merge field-by-field and never
|
|
166
166
|
touch unrelated fields.
|
package/docs/LEAD_ASSIGN.md
CHANGED
|
@@ -1,85 +1,3 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
This architecture is modeled after decentralized multi-agent coordination patterns (e.g. Minecraft multi-agent peer collaboration):
|
|
6
|
-
- **Peers** communicate directly, self-organize strategy, and write findings to shared ambient memory (the board / Workbench).
|
|
7
|
-
- An **Observer** (`lead`) monitors health, chases failures/timeouts, fail-closes approvals, and verifies claims against actual artifacts.
|
|
8
|
-
- The **Boss** sets the objective and monitors milestones asynchronously without micromanaging execution.
|
|
9
|
-
|
|
10
|
-
---
|
|
11
|
-
|
|
12
|
-
## 1. The Lane Model
|
|
13
|
-
|
|
14
|
-
| Lane | Actor | Authority & Responsibilities |
|
|
15
|
-
|---|---|---|
|
|
16
|
-
| **Boss** | User / Calling Session | • Sets the objective and mission parameters.<br>• Reads progress via dashboard, status commands, or milestone DMs.<br>• Resolves out-of-scope mission changes or irreconcilable disputes.<br>• Never routes routine peer messages. |
|
|
17
|
-
| **Lead** | Autonomous Board Coordinator (`lead`) | • **Observer Role**: Environment repairs, TTL chasing, respawn health (`spawn-status --all`, `respawn`).<br>• **Approvals**: Decides on irreversible/high-risk actions (`fail-closed`).<br>• **Verification**: Audits worker claims against actual files/logs before aggregating.<br>• **Milestones**: Relays aggregate outcomes back to the boss.<br>• *Never* settles peer strategy disputes or does workers' implementation tasks. |
|
|
18
|
-
| **Peers** | Worker Agents (`sec-1`, `sec-2`, ...) | • Own task strategy, execution, and local decisions.<br>• Direct peer-to-peer DMs for targeted cooperation and rescue calls.<br>• Post lessons and artifacts directly to the board Workbench.<br>• Checkpoint progress along threads.<br>• Consult groups first; escalate to lead only for scope/approvals. |
|
|
19
|
-
|
|
20
|
-
---
|
|
21
|
-
|
|
22
|
-
## 2. CLI Control: `--lead auto|board|none`
|
|
23
|
-
|
|
24
|
-
When spawning workers with `crewbus spawn`:
|
|
25
|
-
|
|
26
|
-
```sh
|
|
27
|
-
# Default: auto-assigns lead if a coding harness is present
|
|
28
|
-
crewbus spawn --from boss --count 3 --harness opencode --body "Implement feature X"
|
|
29
|
-
|
|
30
|
-
# Explicit board coordinator
|
|
31
|
-
crewbus spawn --from boss --count 3 --harness opencode --lead board --body "Implement feature X"
|
|
32
|
-
|
|
33
|
-
# Legacy star topology (replies pin directly to boss)
|
|
34
|
-
crewbus spawn --from boss --count 3 --harness generic --lead none --body "Run test suite"
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
### Modes:
|
|
38
|
-
- **`auto` (default)**:
|
|
39
|
-
- If any coding harness (`opencode`, `claude`, `codex`, `grok`, `antigravity`, `cursor`) is used: selects `board` mode.
|
|
40
|
-
- If all workers use `generic` harnesses (shell commands without an LLM harness): falls back to `none` mode.
|
|
41
|
-
- **`board`**:
|
|
42
|
-
- Auto-provisions or reuses the board's standing `lead` lane.
|
|
43
|
-
- Workers' brief prompts pin reply targets and approval requests to `--to lead`.
|
|
44
|
-
- Requires at least one coding harness to run the coordinator prompt; fails loudly if attempted with pure `generic` harnesses.
|
|
45
|
-
- **`none`**:
|
|
46
|
-
- Legacy star topology: replies and approvals pin directly to the spawner (`--to <from>`).
|
|
47
|
-
- No autonomous coordinator is provisioned.
|
|
48
|
-
|
|
49
|
-
---
|
|
50
|
-
|
|
51
|
-
## 3. Provisioning & Collision Rules
|
|
52
|
-
|
|
53
|
-
1. **First-Claim-Wins**:
|
|
54
|
-
- On a fresh board without a `lead` agent, `provisionAutoLead` mints the `lead` identity with `role: "lead"`.
|
|
55
|
-
- The token is saved to `logs/lead.token` according to the token-file convention.
|
|
56
|
-
2. **Reuse Standing Coordinators**:
|
|
57
|
-
- If an active coordinator is already running (live PID on the `lead` lane), subsequent `spawn` bursts reuse the standing coordinator rather than duplicating it.
|
|
58
|
-
- Workers from new bursts are transferred to the lead lane (`spawnedBy: "lead"`), preserving own-crew RBAC permissions for health tracking and `spawn-kill`.
|
|
59
|
-
3. **Offboarded Safety**:
|
|
60
|
-
- If the `lead` lane has been marked `offboarded: true` (deliberate teardown), auto-provisioning is skipped with a loud warning.
|
|
61
|
-
4. **Boss Detachment**:
|
|
62
|
-
- If `from === "lead"`, auto-provisioning skips into self-bootstrap mode to prevent recursion.
|
|
63
|
-
5. **Lead Revive (`crewbus spawn --count 0`)**:
|
|
64
|
-
- When the coordinator died (crash, reboot, budget reap), the crew still has
|
|
65
|
-
its briefs/threads on the board — but nobody triaging. `--count 0` boots
|
|
66
|
-
NOTHING except the auto-coordinator lane: zero worker boots, zero DMs
|
|
67
|
-
delivered; the mission text you pass becomes the coordinator's reminder
|
|
68
|
-
of what the crew was on about (worker threads and scope live on the board).
|
|
69
|
-
- Requires `--lead board` (the default under a coding harness); worker
|
|
70
|
-
operands (`--to`/`--to-file`/`--to-group`) are refused — this path has no
|
|
71
|
-
worker operands. A standing coordinator is reused, never duplicated;
|
|
72
|
-
an offboarded lane skips with a loud warning, same as any burst.
|
|
73
|
-
|
|
74
|
-
---
|
|
75
|
-
|
|
76
|
-
## 4. Prompt Engineering
|
|
77
|
-
|
|
78
|
-
- **Workers (`buildSpawnPrompt`)**:
|
|
79
|
-
- Directs completion summaries, checkpoints, and approval requests to `--to lead`.
|
|
80
|
-
- Informs the worker that the spawner stepped back to boss and reads progress via the lead.
|
|
81
|
-
- Reinforces peer-first habits: consult groups before escalating to the lead.
|
|
82
|
-
- **Coordinator (`buildCoordinatorPrompt`)**:
|
|
83
|
-
- Injected with the verbatim mission text from the boss.
|
|
84
|
-
- Lists worker brief IDs for easy threading and reply tracking.
|
|
85
|
-
- Enforces polling discipline (`listen` / `inbox --digest`), fail-closed approval timeouts, and maximum 2 respawn attempts per lane before escalating stalls to the boss.
|
|
1
|
+
# Moved
|
|
2
|
+
|
|
3
|
+
This guide moved to [ORCHESTRATOR.md](ORCHESTRATOR.md).
|
package/docs/LONG_RUNS.md
CHANGED
|
@@ -14,7 +14,7 @@ the board.
|
|
|
14
14
|
2. Tokens persist themselves: every register/mint/rotate writes
|
|
15
15
|
`.crewbus/logs/<agent>.token` (0600). Workers re-read it after any
|
|
16
16
|
restart or compaction instead of re-registering (re-registering a
|
|
17
|
-
claimed name fails). Truly lost it?
|
|
17
|
+
claimed name fails). Truly lost it? The orchestrator runs `token revoke --target
|
|
18
18
|
<name>`, worker re-registers fresh. Never commit or post token files;
|
|
19
19
|
`prune`/export skip `*.token`.
|
|
20
20
|
3. Poll digest-first: `inbox --unacked --digest`, full reads only on
|
|
@@ -43,10 +43,10 @@ the board.
|
|
|
43
43
|
|---|---|
|
|
44
44
|
| Post-compaction amnesia | Identity card is auto-injected (hook compact / opencode plugin); unknown who you are? run `crewbus recover` — read-only candidate ranking (session binding → token-file↔tokenHash → cwd), then follow the printed resume script |
|
|
45
45
|
| Landed as "unknown" | Sentinel names ("unknown"/"me"/"you") never mint (register/send refuse them). Run `crewbus recover [--session <id>]` to re-find your real identity; only then re-register your true name |
|
|
46
|
-
| Token lost entirely |
|
|
46
|
+
| Token lost entirely | Orchestrator `token revoke --target`, worker re-registers |
|
|
47
47
|
| Worker silent | `spawn-status`: no reply → read its log; re-brief or `respawn` |
|
|
48
48
|
| Supervisor gone | `pool-resume --id`; stale locks expire via TTL |
|
|
49
|
-
| Reboot | `doctor` → `spawn-status --all` (stale pids read dead, not running) → `respawn`/`pool-resume`; dead coordinator: `crewbus spawn --count 0 --body "<what the crew was on>"` (C9
|
|
49
|
+
| Reboot | `doctor` → `spawn-status --all` (stale pids read dead, not running) → `respawn`/`pool-resume`; dead coordinator: `crewbus spawn --count 0 --body "<what the crew was on>"` (C9 orchestrator revive, workers untouched) |
|
|
50
50
|
| Primary relay down | `relay promote` on the standby (see `docs/HA.md`) |
|
|
51
51
|
|
|
52
52
|
## Bottom line
|
package/docs/M1_CLI_DRAFT.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# M1 CLI draft — `launch` wizard, `harnesses`, `relay pair qr`, serve pairing flags
|
|
2
2
|
|
|
3
|
-
Status: SHIPPED (
|
|
3
|
+
Status: SHIPPED (orchestrator wired `cmdServe` 2026-10-06). Paste §1 into `bin/crewbus.js` USAGE and §2
|
|
4
4
|
into `README.md` after the spawn section ("Running workers (spawn)").
|
|
5
5
|
§1d is now live: `serve --advertise-routes --pair-qrcode` shipped in `cmdServe`;
|
|
6
6
|
`POST /api/launch` + `GET /api/harnesses` + `GET /api/routes` shipped in both
|
|
@@ -32,8 +32,8 @@ Flag verification (role-prompt list vs implementation):
|
|
|
32
32
|
| `--yes` | In shipped USAGE line; no separate consume in `cmdLaunch` (confirm lives in spawn delegation). Keep the token, do not invent semantics |
|
|
33
33
|
| `--permission full` | Needs `--i-understand-danger` (else plan invalid) |
|
|
34
34
|
| `harnesses [detect --json]` | Shipped (`cmdHarnesses`; `detect` optional, bare `harnesses` works) |
|
|
35
|
-
| `relay pair qr --from
|
|
36
|
-
| `serve --advertise-routes <url,url> --pair-qrcode` | SHIPPED in `cmdServe` (advertised at `relay.json`, `GET /healthz`, `GET /api/routes`; `--pair-qrcode` needs `--from
|
|
35
|
+
| `relay pair qr --from orchestrator [--label --ttl --routes --json]` | Shipped (`qr` branch of `cmdRelayPair`); prints `crewbus://pair` URL, secret in `#fragment` only |
|
|
36
|
+
| `serve --advertise-routes <url,url> --pair-qrcode` | SHIPPED in `cmdServe` (advertised at `relay.json`, `GET /healthz`, `GET /api/routes`; `--pair-qrcode` needs `--from orchestrator`, same mint + audit as `relay pair`) |
|
|
37
37
|
|
|
38
38
|
## 1. USAGE text blocks (paste-ready)
|
|
39
39
|
|
|
@@ -48,7 +48,7 @@ Flag verification (role-prompt list vs implementation):
|
|
|
48
48
|
the interactive confirm; --json prints the crewId/batch/workers shape.)
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
-
Notes for the
|
|
51
|
+
Notes for the orchestrator (do not paste): `--body-file <path>` is also accepted
|
|
52
52
|
(read into the brief before validation); `--target` is `local` (hardcoded —
|
|
53
53
|
fleet goes through `crew dispatch`); `--permission full` additionally
|
|
54
54
|
requires `--i-understand-danger`.
|
|
@@ -65,7 +65,7 @@ requires `--i-understand-danger`.
|
|
|
65
65
|
### 1c. `crewbus relay pair qr` (shipped — keep verbatim)
|
|
66
66
|
|
|
67
67
|
```text
|
|
68
|
-
crewbus relay pair qr --from
|
|
68
|
+
crewbus relay pair qr --from orchestrator [--label <device>] [--ttl 10m] [--routes <url,url>] [--json]
|
|
69
69
|
(prints the one-time crewbus://pair URL (secret in #fragment, never
|
|
70
70
|
query) alongside the plain pairing token. Scan/paste into the mobile
|
|
71
71
|
or desktop client to pair.)
|
|
@@ -128,7 +128,7 @@ crewbus launch --from alice --harness codex --count 1 \
|
|
|
128
128
|
Rules worth knowing: the brief caps at 8000 chars (`--body-file` for
|
|
129
129
|
anything long); `--to` and `--count` together warn (`--to` wins);
|
|
130
130
|
`--worktree` and `--branch` are exclusive; `--max-turns` applies to
|
|
131
|
-
claude/grok and `--allow-tools` to claude; cursor/antigravity
|
|
131
|
+
claude/grok and `--allow-tools` to claude; cursor/antigravity
|
|
132
132
|
cannot resume (one-shot briefs — the wizard warns, never fakes it);
|
|
133
133
|
`--target` is `local` (fleet placement stays `crew dispatch`).
|
|
134
134
|
|
|
@@ -154,11 +154,11 @@ frozen contracts and delegates to the existing spawn path, so no verified
|
|
|
154
154
|
row (adapter flags, session-id capture, resume commands, compaction,
|
|
155
155
|
approval pre-approvals) moves. No edit to `docs/COMPATIBILITY.md` —
|
|
156
156
|
no new harness, no flag change, no date to refresh. The one honest
|
|
157
|
-
surface to keep citing is the resume column: cursor/antigravity
|
|
157
|
+
surface to keep citing is the resume column: cursor/antigravity
|
|
158
158
|
report `resume: false` in `harnesses` output by design (see §2 wording
|
|
159
159
|
above), matching the existing "no" rows.
|
|
160
160
|
|
|
161
|
-
## 4. Paste checklist for the
|
|
161
|
+
## 4. Paste checklist for the orchestrator
|
|
162
162
|
|
|
163
163
|
1. USAGE: §1a–c already shipped in `bin/crewbus.js` — no paste needed.
|
|
164
164
|
§1d only after `cmdServe` gains `--advertise-routes`/`--pair-qrcode`.
|
|
@@ -167,7 +167,7 @@ above), matching the existing "no" rows.
|
|
|
167
167
|
3. COMPATIBILITY.md: no edit (per §3).
|
|
168
168
|
4. Never touched (per role): `bin/crewbus.js`, `package.json`, tests —
|
|
169
169
|
this draft only *adds* `docs/M1_CLI_DRAFT.md`.
|
|
170
|
-
UPDATE (
|
|
170
|
+
UPDATE (orchestrator, 2026-10-06): serve + web wiring landed after the draft —
|
|
171
171
|
`bin/crewbus.js` (`cmdServe` flags, `/api/routes`, `/api/harnesses`,
|
|
172
172
|
`/api/launch`, USAGE), `bin/lib/web.js` (`handleApiLaunch`,
|
|
173
173
|
`/api/harnesses`, `/api/routes`, `/api/launch`), `package.json`
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Orchestrator & Worker Lane Model
|
|
2
|
+
|
|
3
|
+
Crewbus separates **spawning** from **leading** with exactly two roles.
|
|
4
|
+
`spawn` provisions the board's single **orchestrator** and boots the workers;
|
|
5
|
+
the orchestrator owns the crew, while workers collaborate peer-to-peer.
|
|
6
|
+
|
|
7
|
+
- **Workers** communicate directly, self-organize strategy, and write
|
|
8
|
+
findings to shared ambient memory (the board / Workbench).
|
|
9
|
+
- The **orchestrator** monitors health, chases failures/timeouts, fail-closes
|
|
10
|
+
approvals, verifies claims against actual artifacts, and posts the aggregate.
|
|
11
|
+
- The **user/operator** runs `crewbus spawn` with a brief and a worker count.
|
|
12
|
+
There is no separate `boss`, `admin`, `lead`, or `auditor` identity.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## 1. The Lane Model
|
|
17
|
+
|
|
18
|
+
| Lane | Actor | Authority & Responsibilities |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| **Orchestrator** | Board control plane (`orchestrator`) | • Sets the mission from the user's brief.<br>• Observes health, TTLs, respawns (`spawn-status --all`, `respawn`).<br>• Decides irreversible/high-risk approvals (`fail-closed`).<br>• Audits worker claims against files/logs before aggregating.<br>• Posts the aggregate outcome on the board.<br>• *Never* does workers' implementation tasks. |
|
|
21
|
+
| **Workers** | Worker agents (`worker-1`, `worker-2`, ...) | • Own task strategy, execution, and local decisions.<br>• Direct peer-to-peer DMs for cooperation and rescue calls.<br>• Post lessons and artifacts directly to the board Workbench.<br>• Checkpoint progress along threads.<br>• Consult groups first; escalate to the orchestrator only for scope/approvals. |
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## 2. CLI: brief + count
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
# Default: provisions or reuses the board orchestrator
|
|
29
|
+
crewbus spawn "Implement feature X" --count 3 --harness opencode
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
There is no `--from` and no `--lead` flag. `spawn` runs as the board
|
|
33
|
+
orchestrator; `--body "..."` and a positional brief are equivalent.
|
|
34
|
+
|
|
35
|
+
### Architecture
|
|
36
|
+
|
|
37
|
+
- Auto-provisions or reuses the board's single `orchestrator` lane.
|
|
38
|
+
- Worker briefs pin reply targets and approval requests to `--to orchestrator`.
|
|
39
|
+
- The orchestrator runs persistently to monitor health and approvals.
|
|
40
|
+
- Crewbus requires a coding harness (`opencode`, `claude`, `codex`, `grok`,
|
|
41
|
+
`antigravity`, `cursor`, `qwen`).
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## 3. Provisioning & Collision Rules
|
|
46
|
+
|
|
47
|
+
1. **Single identity**
|
|
48
|
+
- `ensureOrchestrator` mints the `orchestrator` identity with
|
|
49
|
+
`role: "orchestrator"` when missing.
|
|
50
|
+
- The token is saved to `logs/orchestrator.token` (token-file convention).
|
|
51
|
+
- `crewbus orchestrator init` bootstraps explicitly; `orchestrator show`
|
|
52
|
+
reports the identity read-only.
|
|
53
|
+
|
|
54
|
+
2. **Reuse standing orchestrators**
|
|
55
|
+
- If a live, non-stale coordinator runs on the `orchestrator` lane,
|
|
56
|
+
subsequent `spawn` bursts reuse it rather than duplicating it.
|
|
57
|
+
- Workers from new bursts are transferred to the orchestrator
|
|
58
|
+
(`spawnedBy: "orchestrator"`), preserving own-crew permissions for
|
|
59
|
+
health tracking and `spawn-kill`.
|
|
60
|
+
|
|
61
|
+
3. **Offboarded lane**
|
|
62
|
+
- If the `orchestrator` lane has been marked `offboarded: true`,
|
|
63
|
+
auto-provisioning refuses silently to resurrect a deliberate teardown.
|
|
64
|
+
Re-onboard it explicitly before spawning again.
|
|
65
|
+
|
|
66
|
+
4. **Revive (`crewbus spawn --count 0`)**
|
|
67
|
+
- Boots NOTHING except the orchestrator lane: zero worker boots, zero DMs.
|
|
68
|
+
- The mission text you pass becomes the orchestrator's reminder of what the
|
|
69
|
+
crew was working on (worker threads and scope live on the board).
|
|
70
|
+
- Worker selectors (`--to`/`--to-file`/`--to-group`) are refused.
|
|
71
|
+
- A standing orchestrator is reused, never duplicated.
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## 4. Prompt Engineering
|
|
76
|
+
|
|
77
|
+
- **Workers (`buildSpawnPrompt`)**:
|
|
78
|
+
- Direct completion summaries, checkpoints, and approval requests to
|
|
79
|
+
`--to orchestrator`.
|
|
80
|
+
- Tell the worker that the orchestrator owns the crew.
|
|
81
|
+
- Reinforce peer-first habits: consult groups before escalating.
|
|
82
|
+
- **Orchestrator (`buildOrchestratorPrompt`)**:
|
|
83
|
+
- Injected with the verbatim user brief.
|
|
84
|
+
- Lists worker brief IDs for threading and reply tracking.
|
|
85
|
+
- Enforces polling discipline (`listen` / `inbox --digest`), fail-closed
|
|
86
|
+
approval timeouts, and maximum 2 respawn attempts per lane before posting
|
|
87
|
+
the stall on the board.
|