docs: the fleet design, and a plan for its first phase

[adityak74]

Draft. Documentation only, no code touched, nothing here is implemented.

Two commits:

• the fleet design and its docs/DECISIONS.md entry: coordinator (a
  zorp-fleet crate) plus zorp-web worker pods, capability invocation as
  the unit of distribution, git remote per track as the state bus, checkpoint
  relay rules, per-worker tokens and sibling-call denial, a fleet-level rate
  limit cap, four phases, and three open questions deferred to Phases 2 and 3.
• an implementation plan for Phase 1 only, the worker contract.

Why the plan covers Phase 1 and not the rest

Phase 0 needs no code, and that checks out: Dockerfile and compose.yml
are both present today.

Phase 2 cannot be planned yet. The spec defers three open questions to it:
whether a worker blocks or parks while a checkpoint waits for a human, where
track remotes live, and whether zorp-fleet reuses zorp-web's session store
shape. Writing task level steps for the coordinator would mean deciding those
three inside a plan document, which is the wrong place for them. The spec's
own handoff says the checkpoint relay is the piece to brainstorm first.

Phase 1 stops cleanly on its own. After it, a human running several worker
pods by hand can ask each one whether it is busy and what it can run, and no
agent on any pod can reach another pod.

Two corrections to the spec, found by reading the code it describes

Neither changes the design. Both change what the work is, and both are
applied in the plan rather than edited into the spec, so the record shows what
was believed when the design was written.

1. /api/health and /api/capabilities already exist, registered at
   zorp-web/src/api.rs:106 and :113. The spec calls them two additions.
   health() returns {"status":"ok"} and nothing else, and capabilities()
   reports one capability. So the work is extending the payloads. An
   implementer who takes the spec literally and adds a second route on the
   same path makes axum panic at startup.
2. Per-worker tokens are already satisfied. Each zorp-web takes its own
   --token, so the fleet never had one shared secret to begin with. What is
   missing is a source fit for a mounted Secret, because a token in args is
   visible in ps on the node. The plan adds ZORP_WEB_TOKEN.

The plan's five tasks

1. /api/health says whether a turn is in flight. SessionState.running
   already exists, so this is a read and not new bookkeeping.
2. /api/capabilities says which features the binary was compiled with and
   which tools are attached, observed rather than declared.
3. Version the worker API. A constant plus a pinning test, deliberately not an
   /api/v1/ path prefix, which would break every call in web/src/api.ts
   and buy Phase 1 nothing.
4. A worker takes its token from the environment.
5. A worker cannot drive its siblings, extending the 2026-08-20 own-server
   denial from one port to a list of named peers.

Two judgment calls worth review: the versioning choice in task 3, and that
peer matching in task 5 is a lowercased substring. The matching is blunt on
purpose, because a false positive costs one denied command with a legible
reason and a false negative costs the boundary.

One acknowledged gap, flagged in the plan's self review: task 2 does not name
the exact call that builds the agent for tool listing, because that
construction lives in turn.rs and may move. The step says to read it and
mirror it, and not to invent a second registry.

https://claude.ai/code/session_01KGPVQ8wUG7h36zashWYCp4