crewbus 11.3.1 → 11.5.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/docs/HA.md CHANGED
@@ -1,151 +1,15 @@
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).
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: joiner / mover / leaver (Phase 1a)
1
+ # Token-Bound Identity & Lifecycle
2
2
 
3
- Per-identity token lifecycle. Zero-dependency, file-backed, sync-aware.
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
- ## Model
7
+ ---
6
8
 
7
- - Each agent record (`agents/<name>.json`) stores **only** a salted hash
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
- ## Joiner (new human, agent, or workload)
21
-
22
- ```
23
- crewbus register --from alice
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 (crewbus §4.4)
2
-
3
- Don't force it; make it easy. The board directory is the ONLY channel that
4
- needs to cross the isolation boundary.
5
-
6
- ## spawn --isolate
7
-
8
- `spawn --isolate` attempts a container when `docker` is available and warns
9
- otherwise (never forces: without docker it runs unisolated with a warning).
10
-
11
- ## Board as the only mounted channel
12
-
13
- Mount ONLY the board read-write into the worker container; mount nothing
14
- else. The worker's cwd should be a checkout inside the isolation boundary
15
- (or a worktree), not your privileged tree.
16
-
17
- ```sh
18
- # board as the only shared channel, no other mounts (same shape on every OS)
19
- docker run --rm --network none \
20
- -v /path/to/.crewbus:/board:rw \
21
- -e CREWBUS_DIR=/board \
22
- -e CREWBUS_AGENT=worker-1 \
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
- # Loop / cost controls (crewbus §4.4)
1
+ # Scale Limits & Operational Budgets
2
2
 
3
- Pragmatic guards against runaway crews. All are documented, overridable,
4
- and cheap — none requires a daemon.
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
- - Send rate limit: 30/min per agent (token-bucket in `rate/<agent>.json`).
7
- Override per call with `--no-rate-limit`.
8
- - Thread hop counter: `fwd` depth field, max 5 (`--fwd N`; replies
9
- auto-increment from the parent). Deeper threads are refused — start a
10
- fresh brief instead.
11
- - Duplicate suppression: same `from`+`to`+`body` within 10s returns the
12
- existing id (`(deduped)`) instead of writing again — safe retries.
13
- - Default max-turns 50 for `claude`/`grok` spawns (override `--max-turns`).
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 runs: crews that outlive context
1
+ # Long-Running Tasks Playbook
2
2
 
3
- Models compact, sessions die, machines reboot. A 10-day task cannot live
4
- inside one context window — so don't put it there. The board is the
5
- memory; sessions are a cache. This guide is the rotation-over-endurance
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
- ## The setup checklist (once per project)
7
+ ---
10
8
 
11
- 1. `crewbus init --harness <name>` — hooks, MCP, compact rehydration,
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
- ## The wave pattern (how 10-day work actually runs)
28
-
29
- - Split the work into bounded batches. Boot a wave (`spawn --count`,
30
- `pool`), each worker checkpoints every few steps (`--checkpoint`
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.
package/docs/OIDC_TLS.md CHANGED
@@ -1,73 +1,12 @@
1
- # OIDC + TLS/mTLS (Phase 1c)
1
+ # TLS & OIDC Bearer Authentication
2
2
 
3
- Zero-dependency (Node 18+, `node:https` + `node:crypto` only — hand-rolled JWT
4
- verify with discovery + JWKS fetch, no npm packages). Windows/Linux/macOS.
3
+ > **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
4
+ > - Interactive Single-Page Guide: [`documentation.html#security`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#security)
5
+ > - Canonical Markdown Reference: [`docs/SECURITY.md`](file:///C:/Users/Surface/Documents/crewbus/docs/SECURITY.md)
5
6
 
6
- ## OIDC login (scriptable)
7
+ ---
7
8
 
8
- ```sh
9
- crewbus login --issuer <url> --client-id <id> --token <jwt> [--board <path>]
10
- ```
9
+ ## In-Box TLS & Tokens
11
10
 
12
- Validates your caller-provided JWT against the issuer's discovery document
13
- (`<issuer>/.well-known/openid-configuration`) + JWKS (`jwks_uri`), checking
14
- `iss` / `aud` (= `--client-id`) / `exp` with 60s clock-skew tolerance, then
15
- binds it to board identity `oidc-<sub>` (sub lowercased/sanitized, 35 chars +
16
- `oidc-` prefix), minting the local agent record linked to `sub`. No local
17
- token is minted or needed while the JWT is valid. JWKS/discovery responses are
18
- cached in-memory with a 10-minute TTL. Supported algs: RS256/384/512,
19
- ES256/384/512. The JWT is never logged.
20
-
21
- ## Relay accepts Bearer as a secret alternative
22
-
23
- ```sh
24
- crewbus serve --oidc-issuer <url> --oidc-audience <id> [...]
25
- ```
26
-
27
- Protected endpoints (`/sync/*`, `/api/spawn`, `/api/kill`) accept
28
- `Authorization: Bearer <jwt>` (verified as above) as an alternative to
29
- `--secret`/`CREWBUS_SECRET`. Identity is attached to the request
30
- (`req.oidc = {sub, iss}`); permission checks stay in the existing gates —
31
- this phase authenticates only. Clients pass the JWT explicitly:
32
-
33
- ```sh
34
- crewbus sync --with https://peer:port --bearer <jwt> [...]
35
- CREWBUS_OIDC_TOKEN=<jwt> crewbus sync --with https://peer:port [...]
36
- ```
37
-
38
- ## In-box TLS
39
-
40
- ```sh
41
- crewbus serve --tls-cert <pem> --tls-key <pem> [--tls-ca <pem>]
42
- crewbus sync --with https://peer:port [...]
43
- crewbus listen --with https://peer:port [...]
44
- ```
45
-
46
- `--tls-cert/--tls-key` switch the relay to `node:https` (same routes).
47
- `sync`/`listen` follow the URL protocol (`http:` or `https:`).
48
-
49
- Self-signed friendly (dev/test only):
50
-
51
- ```sh
52
- crewbus sync --with https://peer:port --insecure
53
- CREWBUS_INSECURE=1 crewbus sync --with https://peer:port [...]
54
- ```
55
-
56
- Skips peer-cert verification with a loud stderr warning. Never use with real
57
- credentials.
58
-
59
- ## mTLS relay-to-relay (opt-in)
60
-
61
- ```sh
62
- crewbus serve --mtls-ca <pem> [...] # (--tls-ca is an alias)
63
- crewbus sync --with https://peer:port --mtls-cert <pem> --mtls-key <pem>
64
- ```
65
-
66
- With a client-verify CA configured, the relay requires a verified client
67
- certificate on `/sync/*` only (401 otherwise); other routes are unaffected.
68
- Tunnel alternative stays fine: keep plain `http` and terminate TLS in front.
69
-
70
- ## Secrets hygiene
71
-
72
- Tokens/JWTs are never logged (errors name the failed check, never the
73
- credential) and the `web` dashboard never renders them.
11
+ - In-box TLS certificate generation for relay endpoints.
12
+ - Support for mTLS client certificates and OIDC Bearer JWTs for enterprise federated identity.