Fleet Dispatch Architecture¶

Superseded. This is the original single-file architecture doc, kept for existing links. The maintained, more complete version is technical/ARCHITECTURE.md — see README.md for the full two-track documentation index.

Flow¶

flowchart LR
  A[Operator CLI] --> B[Build canonical job JSON]
  B --> C[HMAC sign with fleet key]

  C --> D[enqueue: atomic write to OneDrive inbox]
  D --> E[serve/listen queue drain]
  E --> F{Verify HMAC}
  F -- invalid --> G[archive/rejected + reason]
  F -- valid --> H{Governor RED/BLACKOUT?}
  H -- non-critical --> I[defer: leave in inbox]
  H -- ok or critical --> J[move inbox to processing]
  J --> K[execute via IJobExecutor]
  K --> L[atomic result to outbox]
  L --> M[archive/done]
  M --> N[Operator results]

  C --> O[send: peer registry resolve]
  O --> P[HTTP POST peer /dispatch]
  P --> Q{Verify bearer + HMAC}
  Q -- invalid --> R[401]
  Q -- valid --> S{target is this PC?}
  S -- no --> T[400 no relay]
  S -- yes --> U{replay?}
  U -- yes --> V[409]
  U -- no --> W{Governor RED/BLACKOUT?}
  W -- non-critical --> X[503 deferred + tier]
  W -- ok or critical --> Y[execute via IJobExecutor]
  Y --> Z[atomic result to outbox + 200 result]

Storage¶

Dispatch root defaults to %OneDrive%\PC-Bootstrap\_shared\dispatch. Peer registry entries live in %USERPROFILE%\.claude\fleet-peers.json and %OneDrive%\PC-Bootstrap\_shared\peers.

Each target has:

<PC>/inbox
<PC>/processing
<PC>/outbox
<PC>/archive/done
<PC>/archive/rejected
<PC>/archive/consumed

Writes use temp files plus File.Move(..., overwrite: true). Paths are injectable through FleetDispatchPaths for tests and nonstandard deployments.

Signing¶

Canonical string:

id|createdAt|origin|target|lane|kind|cwd|timeoutSec|critical|payload

The listener recomputes HMAC-SHA256 over UTF-8 and compares hex signatures with CryptographicOperations.FixedTimeEquals.

Peer HTTP¶

fleet-dispatch serve binds HttpListener to the LAN IPv4 address and 127.0.0.1 only. It exposes:

GET /health: no auth, returns computer name, governor tier, and version.
POST /dispatch: requires max 256 KB body, X-Fleet-Auth, valid job HMAC, local target, replay check, and governor gate.

Bearer auth is lowercase hex SHA256(fleet key bytes) and uses fixed-time comparison. Results from direct peer jobs are also written to the target outbox so existing results collection still works.

Execution¶

IJobExecutor is the seam. Unit tests use fakes. Production uses RealJobExecutor:

claude -p <payload> --permission-mode bypassPermissions
pwsh -NoProfile -ExecutionPolicy Bypass -Command <payload>

Claude fallback is --dangerously-skip-permissions if installed CLI rejects the primary permission flag.