Part V · Contracts · Plate 04

Cortex client protocol

4. Cortex Supervisory Switchboard & Native Client Protocol (ADR-006, ADR-008)

The planned macOS and iOS apps (clients/macos, clients/ios) are specified native client designs, not shipped applications. Their protocol specifies exclusive communication with Cortex (cortexd on :4319 / :3333) over Tailscale or localhost using protocolVersion: 1; it does not establish client availability or a live deployment:

1. Challenge-Response Device Pairing (CX-XXXXXX):
   • POST /api/v1/pairing/request → issues a short-lived 6-character pairing code (CX-XXXXXX) held at the perimeter until approved by the owner principal (POST /api/v1/pairing/approve), issuing a bearer device token bound to a principal role (owner, collaborator, or viewer).
2. Single-RTT Bootstrap (GET /api/v1/bootstrap):
   • Returns { protocolVersion: 1, principal, executiveSeat, focusStack, seats, openEscalations, thalamusStatus, latestEntryId } in a single round-trip.
3. Cursor-Resumable Delta Stream (GET /ws?sinceEntryId=<cursor>):
   • Multiplexes live seat transcript deltas, focusStack transitions, raised-hand escalation cards, voice synthesis frames, and Thalamus cluster telemetry with gapless replay from sinceEntryId.
4. Exclusive $ Supervisory Control Prefix (ADR-005):
   • Operator commands prefixed with $ ($status, $focus <seat>, $up, $seat, $abort, $fork, $model, $sys1, $state) are intercepted deterministically by SupervisorySwitchboard without leaking into the focused seat's prompt.