feat(bus): hop guards, per-role rate limit, reserved roles, inbox --peek (#344)

[mercurialsolo]

PR2 of the supervisor RFC (#342). Gating dependency — the supervisor lives on this fabric, and without these guards "leave it running overnight" ships an unbounded ping-pong burn loop and a hostile-cwd escalation intercept. Closes #344.

Why now

PR1 (#350) aligned defaults so cargo and brew users get the same binary. This PR makes that binary safe to leave running with the supervisor on top of it (#345 onward).

What ships

Hop guard

`messages` gains a `hop_count` column via idempotent migration. `publish` takes a new `parent_hop` arg and writes `parent_hop + 1`; values above `policy::DEFAULT_MAX_HOPS` (8) are refused with a structured error. `bus send` starts forwards at hop 1. Cap of 8 matches Claude Code's own Stop-hook 8-block runtime cap so the ninth attempt becomes an escalation event, not a silent retry.

Per-sender rate limit

New `src/bus/rate_limit.rs`. In-process token bucket keyed on `sender_role` — the bus MCP server is a single process, so cross-process coordination is unnecessary. Default 60 messages/minute per role, refilling continuously (no background timer). `Instant` is injected so tests drive the clock without sleeping. Anonymous sends bypass the limiter; the reserved-role guard shields the privileged endpoints.

Reserved roles

`store::upsert_role` validates the name against `policy::RESERVED_ROLES` (`supervisor`, `operator`) — case-insensitive. Addressing these roles stays open (escalations must work from any sender); only binding is locked down.

`read_inbox` peek mode

`ReadInboxArgs { peek: bool }` and new `store::peek_inbox`. Shares the SQL query with `drain_inbox` so the two paths never diverge on "what counts as pending." Supervisor uses this for exactly-once assignment: peek to decide, then drain at commit. CLI flag: `bus inbox --peek`. The Stop-hook path must still drain — leaving messages pending would redeliver them every turn boundary.

Divergence from the issue text

#344 originally said hop count would be a JSON body header (`x-hop: N`). I switched to a dedicated column — it keeps the body opaque (arbitrary user text) and the query/index trivial. The behavior the issue specifies (refuse forwards over the cap, log + escalate) is unchanged.

Verification

```
cargo check --features bus ✓
cargo clippy --features bus -- -D warnings ✓
cargo fmt --all -- --check ✓
cargo test --features bus 627 + 635 + 78 + 8 passed
```

Covered:

• `hop_count` round-trips through insert/drain
• peek twice returns same set; drain after peek still drains; peek after drain is empty
• reserved-role bind rejected with no partial write
• rate limiter: burst-to-capacity, refill-at-steady-state, per-role isolation, capacity-as-hard-ceiling
• hop validator: 0/max/over-max boundary cases

Out of scope (RFC §11 puts these in later milestones)

• Multi-process rate-limit coordination (single-process is correct for stdio MCP)
• Address-time ACLs (publishing to a reserved role stays open)
• In-flight loop detection beyond hop counting

Test plan

• Confirm `cargo install` on PR1's branch + this PR can run `claudectl bus inbox --peek` cleanly.
• Manually try `claudectl bus role bind supervisor /tmp` — should fail with the reserved-role error.
• Manually try `claudectl bus send supervisor 'test' --from anywhere` — should still succeed (addressing reserved roles stays open).

🤖 Generated with Claude Code