crewbus 11.3.1 → 11.4.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/CHANGELOG.md +11 -0
- package/README.md +2 -2
- package/bin/lib/web.js +5 -4
- package/docs/APPROVALS.md +20 -61
- package/docs/ARCHITECTURE.md +113 -0
- package/docs/AUDIT_EXPORT.md +9 -104
- package/docs/CERT_READINESS.md +13 -120
- package/docs/COMPATIBILITY.md +65 -0
- package/docs/CONSOLIDATOR.md +8 -43
- package/docs/CONTROL_PLANE_SPEC.md +16 -340
- package/docs/CREWS.md +9 -54
- package/docs/DELIVERY.md +2 -0
- package/docs/EXPERIMENTS.md +7 -52
- package/docs/GROUPS.md +13 -109
- package/docs/HA.md +15 -151
- package/docs/IDENTITY.md +10 -162
- package/docs/ISOLATION.md +22 -39
- package/docs/LIMITS.md +12 -21
- package/docs/LONG_RUNS.md +10 -56
- package/docs/OIDC_TLS.md +8 -69
- package/docs/ORCHESTRATOR.md +8 -82
- package/docs/PAIRING.md +2 -0
- package/docs/QUICKSTART.md +10 -75
- package/docs/RBAC.md +10 -80
- package/docs/SECURITY.md +111 -0
- package/docs/SHARED_RESPONSIBILITY.md +8 -32
- package/docs/SPLIT.md +13 -82
- package/docs/STORAGE.md +9 -63
- package/docs/TENANCY.md +8 -74
- package/docs/THREAT_MODEL.md +16 -68
- package/docs/TROUBLESHOOTING.md +16 -27
- package/docs/VERIFIER.md +8 -50
- package/docs/VERSION_SKEW.md +13 -57
- package/docs/WHEN_NOT.md +11 -35
- package/documentation.html +198 -4
- package/index.html +4 -4
- package/package.json +1 -1
- package/packages/client-runtime/auth.js +7 -3
- package/packages/client-runtime/routes.js +3 -0
package/docs/GROUPS.md
CHANGED
|
@@ -1,109 +1,13 @@
|
|
|
1
|
-
# Groups
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
crewbus group create
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
```
|
|
15
|
-
|
|
16
|
-
`gather --batch` prints a telemetry footer
|
|
17
|
-
(`msgs, ~tokens (chars/4), contributing groups`) and the same fields in
|
|
18
|
-
`--json` (`contributingGroups`, `telemetry`).
|
|
19
|
-
|
|
20
|
-
## Replies carry artifacts
|
|
21
|
-
|
|
22
|
-
```sh
|
|
23
|
-
crewbus send --from e1 --to orchestrator --reply <brief-id> --artifact out/a1.json --body "done"
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
`--artifact <path-or-url>` (max 500 chars) is stored on the message and
|
|
27
|
-
shown by `inbox` / `gather` / `thread`.
|
|
28
|
-
|
|
29
|
-
## Verify, then record the result
|
|
30
|
-
|
|
31
|
-
```sh
|
|
32
|
-
crewbus ack --from orchestrator --id <reply-id> --verify "node test/check.mjs --input out/a1.json"
|
|
33
|
-
crewbus result record --group team-a --msg <reply-id> --artifact out/a1.json --from orchestrator
|
|
34
|
-
crewbus result show --group team-a
|
|
35
|
-
crewbus result list [--group team-a] [--json]
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
`results/<group>.json` holds ONE record
|
|
39
|
-
`{group, artifact, by, msgId, verifierOutput, at}` — first verified
|
|
40
|
-
result wins. Only verified messages are recordable: the ack marker
|
|
41
|
-
`acked/*/<msgId>.json` must carry `verified:true`, else recording fails
|
|
42
|
-
unless `--force` (which prints a warning to stderr).
|
|
43
|
-
|
|
44
|
-
## Race mode
|
|
45
|
-
|
|
46
|
-
```sh
|
|
47
|
-
crewbus race start --group team-a --batch <batch> [--timeout 60000] [--json]
|
|
48
|
-
crewbus race close --group team-a --from orchestrator [--kill]
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
`race start` reports the winner (recorded result whose `msgId` is in the
|
|
52
|
-
batch, else the first verified ack on a batch reply) or "no verified
|
|
53
|
-
result yet". `--timeout` polls instead of checking once; there is no
|
|
54
|
-
daemon. `race close` DMs "race closed by X" to every other member and,
|
|
55
|
-
with `--kill`, terminates their spawned pids.
|
|
56
|
-
|
|
57
|
-
## Status + telemetry
|
|
58
|
-
|
|
59
|
-
```sh
|
|
60
|
-
crewbus group status team-a [--json] # running (pid alive), replies, verified, spend
|
|
61
|
-
crewbus group telemetry team-a [--json] # {messages, tokensEst, wallClockMs, members, verifiedCount}
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
Spend = message count + wall-clock since the group `createdAt` +
|
|
65
|
-
token estimate (`chars/4` over member bodies+subjects). `createdAt` is
|
|
66
|
-
backfilled from the group file mtime for pre-existing groups.
|
|
67
|
-
|
|
68
|
-
## Attribution (agents in several groups)
|
|
69
|
-
|
|
70
|
-
- A reply attributes via its chain: `--reply <msg-id>` → root brief →
|
|
71
|
-
batch → group(s) whose members appear in the transcript.
|
|
72
|
-
- `gather --batch` shows `contributing groups` (groups with ≥1 message
|
|
73
|
-
from a member in the transcript).
|
|
74
|
-
- `result record` **requires `--group` explicitly** — there is no
|
|
75
|
-
auto-assign. When an agent is in several groups, the recorder decides
|
|
76
|
-
which group the result counts for.
|
|
77
|
-
|
|
78
|
-
## Cross-group collaboration
|
|
79
|
-
|
|
80
|
-
Groups share one board, so any member can already read anything. The
|
|
81
|
-
thing that decides whether groups actually collaborate is whether the
|
|
82
|
-
brief tells them the map. Since v10.0.x every `spawn` brief carries a
|
|
83
|
-
**Crew:** block (see `buildCrewContext` in `bin/lib/spawn.js`): your
|
|
84
|
-
group(s) + members + lane, the sibling groups of the same spawn +
|
|
85
|
-
members, their group channels, and the peer-DM norm. Groups from
|
|
86
|
-
unrelated concurrent briefs are deliberately NOT enumerated — they
|
|
87
|
-
collapse to a count (`N other groups exist on this board`), so
|
|
88
|
-
cross-task rosters stay discoverable (`crewbus group list`) without
|
|
89
|
-
becoming prompt noise or a misleading invitation. Conventions that
|
|
90
|
-
block assumes:
|
|
91
|
-
|
|
92
|
-
- **Peer-direct for questions.** `crewbus send --from you --to-group
|
|
93
|
-
<group> --subject "..." --body "..."` reaches every member of
|
|
94
|
-
another group. Ask the group that owns a thing first; the orchestrator is
|
|
95
|
-
for approvals (`--priority high`) and scope disputes only.
|
|
96
|
-
- **Channels are the shared read surface.** `crewbus channel tail
|
|
97
|
-
grp-<group>` shows a group's briefs + mirrored progress; reads need
|
|
98
|
-
no token. Channel *posting* is member-scoped (default-on, no flag):
|
|
99
|
-
a worker may post to `grp-<group>` only when it is a MEMBER of that
|
|
100
|
-
group — board channels and foreign groups are orchestrator-only
|
|
101
|
-
(see docs/RBAC.md).
|
|
102
|
-
- **Boot habit.** `crewbus agents` + `crewbus group list` once at
|
|
103
|
-
start, so a worker knows who else is here. A worker that never runs
|
|
104
|
-
a discovery command will work star-topology through the orchestrator — that
|
|
105
|
-
is a failure of the brief, not the worker.
|
|
106
|
-
- **Scope questions stay lanes-first.** "Stay in your lane" prevents
|
|
107
|
-
collisions; "DM the group that owns a thing" prevents silos. A
|
|
108
|
-
brief should name both the boundary *and* the bridge.
|
|
109
|
-
|
|
1
|
+
# Groups & Member-Scoped Channels
|
|
2
|
+
|
|
3
|
+
> **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
|
|
4
|
+
> - Interactive Single-Page Guide: [`documentation.html#layout`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#layout)
|
|
5
|
+
> - Canonical Markdown Reference: [`docs/ARCHITECTURE.md`](file:///C:/Users/Surface/Documents/crewbus/docs/ARCHITECTURE.md)
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Groups & Channels
|
|
10
|
+
|
|
11
|
+
- Group creation: `crewbus group create <name> --members a,b,c`.
|
|
12
|
+
- Scoped channels: `grp-<name>` channels permit postings only from members of that group.
|
|
13
|
+
- Context isolation: Task-scoped briefs include relevant groups only, preventing cross-task leaks.
|
package/docs/HA.md
CHANGED
|
@@ -1,151 +1,15 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
## Topology
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
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).
|
|
1
|
+
# High Availability & Relay Replication
|
|
2
|
+
|
|
3
|
+
> **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
|
|
4
|
+
> - Interactive Single-Page Guide: [`documentation.html#ha-sync`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#ha-sync)
|
|
5
|
+
> - Canonical Markdown Reference: [`docs/ARCHITECTURE.md`](file:///C:/Users/Surface/Documents/crewbus/docs/ARCHITECTURE.md)
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Active / Passive Relay Topology
|
|
10
|
+
|
|
11
|
+
- Single writer (Primary relay) handles writes (`POST /api/spawn`, sync push).
|
|
12
|
+
- Standby relays replicate from primary via pull (`--relay-interval 5s`).
|
|
13
|
+
- Standbys serve read endpoints (`GET /sync/manifest`, `/sync/file`, `/healthz`) locally; writes return 503 with `X-Relay-Role: standby`.
|
|
14
|
+
- Promotion: `crewbus relay promote --from orchestrator`. Split-brain prevention: ensure old primary stays down.
|
|
15
|
+
- Recommended transport: Tailscale / WireGuard private mesh.
|
package/docs/IDENTITY.md
CHANGED
|
@@ -1,166 +1,14 @@
|
|
|
1
|
-
# Identity
|
|
1
|
+
# Token-Bound Identity & Lifecycle
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
|
|
4
|
+
> - Interactive Single-Page Guide: [`documentation.html#identity-tokens`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#identity-tokens)
|
|
5
|
+
> - Canonical Markdown Reference: [`docs/SECURITY.md`](file:///C:/Users/Surface/Documents/crewbus/docs/SECURITY.md)
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
---
|
|
6
8
|
|
|
7
|
-
|
|
8
|
-
(`tokenHash` + `salt`). Plaintext tokens are printed **once** at mint and
|
|
9
|
-
never again. `--json` outputs and sync payloads strip secrets.
|
|
10
|
-
- `expiresAt` (ISO string or `null`) = token expiry. `null`/missing = never.
|
|
11
|
-
- `rotatedAt` (ISO) = last `token rotate` time.
|
|
12
|
-
- `service: true` = service account (non-expiring by default).
|
|
13
|
-
- `offboarded: true` = deprovisioned. DM files stay on disk for audit, but
|
|
14
|
-
sends as that name are refused.
|
|
15
|
-
- `revoked/<hashPrefix16>.json` = revocation list entries
|
|
16
|
-
`{tokenHash, target, revokedAt, by, reason?}`. Immutable, synced
|
|
17
|
-
copy-if-missing (tombstone-like: deleted copies resurrect on next sync,
|
|
18
|
-
so a revocation is never undone).
|
|
9
|
+
## Credential Management
|
|
19
10
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
crewbus
|
|
24
|
-
# -> prints: registered alice token abt-... (save it: CREWBUS_TOKEN=...)
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
- First claim wins. Save the token in your env/vault (`CREWBUS_TOKEN`).
|
|
28
|
-
- Concurrent first-claims are atomic: exactly one wins (exclusive file
|
|
29
|
-
create); losers fail loudly as a claimed name. Minting over an existing
|
|
30
|
-
record (legacy takeover, post-revoke re-claim) verifies the write won —
|
|
31
|
-
a loser prints nothing usable and must retry.
|
|
32
|
-
- With a TTL: `register --from alice --expires-in 24h` (durations reuse the
|
|
33
|
-
prune parser: `30`, `90s`, `15m`, `24h`, `7d`, `2w`; bare = seconds).
|
|
34
|
-
- Expired tokens fail loudly everywhere with re-register guidance:
|
|
35
|
-
`token for "alice" expired at ... — re-register to renew`.
|
|
36
|
-
|
|
37
|
-
## Service accounts (one per workload)
|
|
38
|
-
|
|
39
|
-
```
|
|
40
|
-
crewbus register --service deploy-bot
|
|
41
|
-
# or: crewbus register --from deploy-bot --service
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
- Non-expiring by default (`expiresAt: null`); pass `--expires-in` to bound it.
|
|
45
|
-
- Flagged `service:true`; excluded from `agents --active` unless you pass
|
|
46
|
-
`--include-services`.
|
|
47
|
-
- **One per workload, stored in a vault/env, never pasted in chat.**
|
|
48
|
-
|
|
49
|
-
## Rotation
|
|
50
|
-
|
|
51
|
-
```
|
|
52
|
-
crewbus token rotate --from alice [--expires-in 7d]
|
|
53
|
-
crewbus token status --from alice [--json]
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
- `rotate` mints a replacement; the old token dies immediately. Records
|
|
57
|
-
`rotatedAt`. `status` shows expiry/rotation state — never secrets.
|
|
58
|
-
|
|
59
|
-
## Mover (rename / team change)
|
|
60
|
-
|
|
61
|
-
1. Offboard the old name (orchestrator, token-checked):
|
|
62
|
-
`register --offboard old-name --from orchestrator`
|
|
63
|
-
2. Register the new name: `register --from new-name`
|
|
64
|
-
3. History stays: DMs to/from the old name remain on disk and in `--all`
|
|
65
|
-
dumps for audit.
|
|
66
|
-
|
|
67
|
-
## Leaver / revocation
|
|
68
|
-
|
|
69
|
-
```
|
|
70
|
-
# kill one identity's live tokens (identity stays, they must re-register):
|
|
71
|
-
crewbus token revoke --from orchestrator --target bob [--reason "laptop lost"]
|
|
72
|
-
|
|
73
|
-
# full deprovision (revokes tokens + marks offboarded, inbox preserved):
|
|
74
|
-
crewbus register --offboard bob --from orchestrator
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
- Revoked callers get: `token for "bob" is revoked — re-register...`.
|
|
78
|
-
- Offboarded callers get: `agent "bob" is offboarded — sends ... refused`.
|
|
79
|
-
- Re-register after revoke mints fresh (no dead token needed);
|
|
80
|
-
offboarded names stay refused until the orchestrator re-onboards them.
|
|
81
|
-
|
|
82
|
-
## Sync hygiene
|
|
83
|
-
|
|
84
|
-
- Agent docs sync as mutable LWW (`hlc`, `v`): `expiresAt`, `rotatedAt`,
|
|
85
|
-
`service`, `offboarded`, `revokedAt` replicate; secrets (`token`,
|
|
86
|
-
`tokenHash`, `salt`) are stripped on push, on `/sync/file` serve, and in
|
|
87
|
-
`mergeSyncedAgent` (local secrets win).
|
|
88
|
-
- `revoked/` syncs as immutable union (copy-if-missing), like tombstones.
|
|
89
|
-
|
|
90
|
-
## Token files (long-running agents)
|
|
91
|
-
|
|
92
|
-
A worker's token is printed **once** at mint and otherwise lives in session
|
|
93
|
-
env — after compaction/restart amnesia the worker is locked out of its own
|
|
94
|
-
claimed name (first-claim-wins: re-registering a claimed name fails). So a
|
|
95
|
-
long-running agent persists its token to a file it can re-read.
|
|
96
|
-
|
|
97
|
-
- **Convention:** `.crewbus/logs/<agent-name>.token` — raw token text
|
|
98
|
-
with a trailing newline, chmod `0600` best-effort. `<agent-name>` is the
|
|
99
|
-
sanitized agent name (lowercase, `[^a-z0-9_.-]` → `-`, max 40 chars).
|
|
100
|
-
Helpers: `tokenFilePath(root, name)`, `saveTokenFile(root, name, token)`
|
|
101
|
-
(mkdir recursive, write + chmod, returns path), `loadTokenFile(root, name)`
|
|
102
|
-
(trimmed string or `null`) in `bin/lib/tokenfile.js` (`root` = the
|
|
103
|
-
`.crewbus/` dir).
|
|
104
|
-
- **Who writes it:** the worker itself, right after register/mint, as
|
|
105
|
-
instructed by the spawn prompt. Exact one-liners (replace `<name>` and
|
|
106
|
-
`<token>`; run from the project dir so `.crewbus/` resolves):
|
|
107
|
-
|
|
108
|
-
POSIX:
|
|
109
|
-
|
|
110
|
-
```
|
|
111
|
-
printf '%s\n' '<token>' > .crewbus/logs/<name>.token && chmod 600 .crewbus/logs/<name>.token
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
PowerShell:
|
|
115
|
-
|
|
116
|
-
```powershell
|
|
117
|
-
Set-Content -Path .crewbus/logs/<name>.token -Value '<token>' -NoNewline:$false
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
- **Security trade-off, stated plainly:** per `docs/THREAT_MODEL.md`,
|
|
121
|
-
local-file access already equals control — anyone with shell access can
|
|
122
|
-
read/write `.crewbus/` directly, so a `0600` token file beside the logs
|
|
123
|
-
grants nothing the filesystem doesn't already grant. It is consistent with
|
|
124
|
-
that model, not an escalation. Even so: **never commit it, never post it**
|
|
125
|
-
(not in chat, mail, PRs, or logs), and `prune`/export must never include
|
|
126
|
-
`*.token`.
|
|
127
|
-
- **Recovery order:** token file first (`loadTokenFile`, i.e. read
|
|
128
|
-
`.crewbus/logs/<name>.token`), then `CREWBUS_TOKEN` env. Re-register
|
|
129
|
-
is **impossible** for claimed names (first-claim-wins rejects it), so there
|
|
130
|
-
is no third option — protect the file.
|
|
131
|
-
|
|
132
|
-
## Post-compaction identity recovery (`crewbus recover`)
|
|
133
|
-
|
|
134
|
-
Compaction amnesia used to mint throwaway identities (`unknown` on the board,
|
|
135
|
-
`logs/unknown.token` nobody owns). Two layers now stop that:
|
|
136
|
-
|
|
137
|
-
- **Sentinel names never mint:** `unknown`, `me`, `you` are reserved —
|
|
138
|
-
`register` and `send` refuse them loudly (`ensureSender` guards them, so
|
|
139
|
-
every write path is covered). They exist only for tools that forgot who
|
|
140
|
-
they are, to force the recovery path instead of a silent identity loss.
|
|
141
|
-
- **Read-only candidate ranking:** `crewbus recover [--session <id>]
|
|
142
|
-
[--cwd <dir>]` scans `agents/*.json` ∩ `logs/*.token` and prints scored
|
|
143
|
-
candidates (best first): session-id register binding +4, token-file
|
|
144
|
-
cross-check against the stored `tokenHash`/`salt` +3 (proof), token file
|
|
145
|
-
exists +1, `lastDir` cwd match +1. It never writes or mints; it prints the
|
|
146
|
-
exact resume commands (CREWBUS_AGENT, token-file path, `inbox --unacked
|
|
147
|
-
--digest`). Offboarded agents are excluded for privacy-critical boards.
|
|
148
|
-
|
|
149
|
-
```
|
|
150
|
-
crewbus: triage on [board …/sandbox-1/.crewbus]
|
|
151
|
-
proven pilg (role worker, score 9) — session id matches register binding;
|
|
152
|
-
token file cross-checks the stored hash; worked from this directory
|
|
153
|
-
resume as 'pilg': …
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
- **Rehydrators resolve before naming "unknown":** the compaction card
|
|
157
|
-
(opencode plugin + `crewbus-hook compact`) first checks its session↔agent
|
|
158
|
-
map, then `CREWBUS_AGENT`, then a lite board-side score (binding + token
|
|
159
|
-
file + cwd, no hash cross-check in the standalone copies). Only when all
|
|
160
|
-
miss does it print the `crewbus recover` instruction — never a "you are
|
|
161
|
-
unknown" blessing.
|
|
162
|
-
- **Bindings survive daily traffic:** register stores `sessionId`; later
|
|
163
|
-
sessionless sends/re-registers/orchestrator touches must NOT wipe it
|
|
164
|
-
(`mergeAgentDoc` deletes undefined patch keys — callers add `sessionId`
|
|
165
|
-
to the patch only when given). Heartbeats merge field-by-field and never
|
|
166
|
-
touch unrelated fields.
|
|
11
|
+
- Minted on first claim; stored in `agents/<name>.json` as salted SHA-256 hashes.
|
|
12
|
+
- Plaintext printed once at minting; never written to disk or synced across relays.
|
|
13
|
+
- Commands: `crewbus register <name>`, `crewbus token rotate --from <name>`, `crewbus token revoke <name>`.
|
|
14
|
+
- Post-compaction recovery: `crewbus recover [--session <id>]` recovers identity bindings without registering dummy accounts.
|
package/docs/ISOLATION.md
CHANGED
|
@@ -1,39 +1,22 @@
|
|
|
1
|
-
# Isolation
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
my-worker-image worker-entrypoint
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
## Egress blocked
|
|
27
|
-
|
|
28
|
-
`--network none` disables container egress: crews coordinate through the
|
|
29
|
-
board mount instead of the network. If a harness needs model API access,
|
|
30
|
-
prefer a proxy you control over full egress, and keep the board mount as
|
|
31
|
-
the only host write path.
|
|
32
|
-
|
|
33
|
-
## --auto and sandboxes
|
|
34
|
-
|
|
35
|
-
`--auto` selects each harness's fully-unattended mode (no permission
|
|
36
|
-
prompts) and requires loud confirmation (`--i-understand-danger` or an
|
|
37
|
-
interactive `yes`), plus prints a DANGER banner and warns when no
|
|
38
|
-
container/CI sandbox is detected (`CONTAINER`/`DOCKER`/`CI` unset).
|
|
39
|
-
Run `--auto` crews on isolated runners only.
|
|
1
|
+
# Container Isolation & Sandboxing
|
|
2
|
+
|
|
3
|
+
> **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
|
|
4
|
+
> - Interactive Single-Page Guide: [`documentation.html#container-isolation`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#container-isolation)
|
|
5
|
+
> - Canonical Markdown Reference: [`docs/SECURITY.md`](file:///C:/Users/Surface/Documents/crewbus/docs/SECURITY.md)
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Overview & Rules
|
|
10
|
+
|
|
11
|
+
- **spawn --isolate:** Attempts container isolation when Docker is available; warns when running unisolated without Docker.
|
|
12
|
+
- **Board as the ONLY mounted channel:** Mount ONLY the board directory read-write into the worker container; mount nothing else. The worker's cwd should be a checkout or worktree inside the isolation boundary.
|
|
13
|
+
```sh
|
|
14
|
+
docker run --rm --network none \
|
|
15
|
+
-v /path/to/.crewbus:/board:rw \
|
|
16
|
+
-e CREWBUS_DIR=/board \
|
|
17
|
+
-e CREWBUS_AGENT=worker-1 \
|
|
18
|
+
my-worker-image worker-entrypoint
|
|
19
|
+
```
|
|
20
|
+
- **Egress blocked:** `--network none` disables network egress; agents coordinate solely through the board mount.
|
|
21
|
+
- **--auto and sandboxes:** `--auto` selects fully-unattended execution (no permission prompts). It requires loud confirmation (`--i-understand-danger` or interactive prompt) and prints danger banners if no container/CI environment is detected (`CONTAINER`, `DOCKER`, `CI` unset).
|
|
22
|
+
- **--workdir-root:** Enforces that worker cwd cannot escape the designated root boundary.
|
package/docs/LIMITS.md
CHANGED
|
@@ -1,23 +1,14 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Scale Limits & Operational Budgets
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
> **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
|
|
4
|
+
> - Interactive Single-Page Guide: [`documentation.html#scale-limits`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#scale-limits)
|
|
5
|
+
> - Canonical Markdown Reference: [`docs/COMPATIBILITY.md`](file:///C:/Users/Surface/Documents/crewbus/docs/COMPATIBILITY.md)
|
|
5
6
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
-
|
|
12
|
-
|
|
13
|
-
-
|
|
14
|
-
- Per-worker budgets: `--budget-tokens N --budget-minutes M` are recorded
|
|
15
|
-
on the agent (`spawn-status` warns when the log-size token estimate or
|
|
16
|
-
elapsed time exceeds them; `budget` object in `--json`).
|
|
17
|
-
- Fan-out cost estimate: sends over 100 recipients print estimated files +
|
|
18
|
-
bytes and require `--yes` to proceed.
|
|
19
|
-
- Dead-man timeouts: `spawn --timeout 10m` records `deadlineAt`
|
|
20
|
-
(`30`, `90s`, `15m`, `24h`, `7d`, `2w` syntax); `spawn-status` flags
|
|
21
|
-
passed deadlines — reap with `spawn-kill`/`stop`.
|
|
22
|
-
- Global stop: `crewbus stop --all --from <you>` kills every spawned
|
|
23
|
-
worker truly (whole process tree: `taskkill /T /F` on Windows).
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Budgets & Ceilings
|
|
10
|
+
|
|
11
|
+
- **Broadcast fan-out:** `--to` supports up to 10,000 recipients.
|
|
12
|
+
- **Concurrent live workers:** `spawn` caps at 20 live boots per call; budget workers like compute processes.
|
|
13
|
+
- **Thread depth:** `MAX_FWD_DEPTH` is 16.
|
|
14
|
+
- **Rate limits:** 60 messages/minute per agent (override with `--no-rate-limit`).
|
package/docs/LONG_RUNS.md
CHANGED
|
@@ -1,60 +1,14 @@
|
|
|
1
|
-
# Long
|
|
1
|
+
# Long-Running Tasks Playbook
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
playbook: keep every session short and replaceable, keep all state on
|
|
7
|
-
the board.
|
|
3
|
+
> **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
|
|
4
|
+
> - Interactive Single-Page Guide: [`documentation.html#delivery`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#delivery)
|
|
5
|
+
> - Canonical Markdown Reference: [`docs/ARCHITECTURE.md`](file:///C:/Users/Surface/Documents/crewbus/docs/ARCHITECTURE.md)
|
|
8
6
|
|
|
9
|
-
|
|
7
|
+
---
|
|
10
8
|
|
|
11
|
-
|
|
12
|
-
and (on grok) the inbox skill. Re-run after every crewbus upgrade;
|
|
13
|
-
`doctor` stays green.
|
|
14
|
-
2. Tokens persist themselves: every register/mint/rotate writes
|
|
15
|
-
`.crewbus/logs/<agent>.token` (0600). Workers re-read it after any
|
|
16
|
-
restart or compaction instead of re-registering (re-registering a
|
|
17
|
-
claimed name fails). Truly lost it? The orchestrator runs `token revoke --target
|
|
18
|
-
<name>`, worker re-registers fresh. Never commit or post token files;
|
|
19
|
-
`prune`/export skip `*.token`.
|
|
20
|
-
3. Poll digest-first: `inbox --unacked --digest`, full reads only on
|
|
21
|
-
hits, `--grep`/`--priority` to narrow. A full dump every step will eat
|
|
22
|
-
any context window in days.
|
|
23
|
-
4. Bound every worker: `--budget-tokens/--budget-minutes`, `--timeout`
|
|
24
|
-
(dead-man `deadlineAt`), `--max-turns` where the harness supports it.
|
|
25
|
-
Unbounded workers are how 10-day tasks become 10-day contexts.
|
|
9
|
+
## Long Runs (Multi-Day Tasks)
|
|
26
10
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
-
|
|
30
|
-
|
|
31
|
-
thread replies: "done X / next Y"), replies, exits.
|
|
32
|
-
- Leads aggregate with `gather`, never by holding the whole crew's
|
|
33
|
-
context. The next wave respawns fresh with full windows and continues
|
|
34
|
-
from the latest checkpoints + inbox.
|
|
35
|
-
- Supervisors die too: `pool-resume` re-attaches pool supervision;
|
|
36
|
-
`respawn` reboots one dead worker in its same conversation.
|
|
37
|
-
- Push keeps everyone woke (Stop hooks, waiters, monitors); digest
|
|
38
|
-
polling keeps everyone cheap.
|
|
39
|
-
|
|
40
|
-
## Recovery ladder (tape this up)
|
|
41
|
-
|
|
42
|
-
| Symptom | Fix |
|
|
43
|
-
|---|---|
|
|
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
|
-
| 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 | Orchestrator `token revoke --target`, worker re-registers |
|
|
47
|
-
| Worker silent | `spawn-status`: no reply → read its log; re-brief or `respawn` |
|
|
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 orchestrator revive, workers untouched) |
|
|
50
|
-
| Primary relay down | `relay promote` on the standby (see `docs/HA.md`) |
|
|
51
|
-
|
|
52
|
-
## Bottom line
|
|
53
|
-
|
|
54
|
-
Don't run one agent for 10 days — run a board for 10 days. Persistent
|
|
55
|
-
peers or rotating pool waves, checkpoints every few steps, digest-first
|
|
56
|
-
polling, token files beside the logs, budgets on everything, and
|
|
57
|
-
compaction hooks that rehydrate identity. Sessions compact, processes
|
|
58
|
-
die, machines reboot; mail, briefs, checkpoints, and session ids survive
|
|
59
|
-
all three on disk. A cold session plus a warm board is a crew that never
|
|
60
|
-
sleeps.
|
|
11
|
+
- Rotate workers in waves; sessions are a cache, the board is the database.
|
|
12
|
+
- Use `--checkpoint` to preserve intermediate progress before risky actions.
|
|
13
|
+
- Poll digest-first: `crewbus inbox --from <you> --unacked --digest`.
|
|
14
|
+
- Re-brief replacement workers on surviving threads.
|