# Relay Plans — Cross-Plan Reconciliation TODO

The 6 relay plans + `PLAN_RELAY_INDEX.md` were generated and hardened in parallel
(32-agent workflow: draft → security+architecture review → fix → re-review → global
consistency). Each plan passed its own review (4–8 blocking findings fixed each). The
**global consistency review then found 11 CRITICAL/HIGH cross-plan integration issues** —
all one root cause: **plans drifted their SHARED contracts locally during hardening
instead of routing changes through the frozen INDEX §4** (violating INDEX §2 rule 1).

These must be reconciled BEFORE any plan's implementation is dispatched, or the plans
will not compose (they'd type-mismatch / fail at integration). The fix is a
**reconciliation pass**: freeze the drifted/missing contracts at the INDEX coordination
point, then sync the consumer plans. Below, the 11 findings collapse into 6 concrete fixes.

---

## FIX 1 — `relay-contracts/` (W0) has no owning task  *(GLOBAL CRITICAL)*
Every plan imports `relay-contracts/` read-only and INDEX says it's "frozen before any
plan's W1", but **no plan contains a task to AUTHOR it** (Zod schemas + TS types + the
mux binary/CBOR codec). It's also where several still-unfrozen shapes must land.
- **Do:** add an INDEX-owned **W0 task** that builds `relay-contracts/`: §4 Zod schemas +
  inferred types, `encodeMuxFrame`/`decodeMuxFrame` (+ CBOR), `GoAwayReason`/`decodeGoAwayReason`,
  the amended §4.4 shapes (Fix 2), account/session/pairing TS types, INV8 version-table DDL.
  Freeze before dispatching any W1.

## FIX 2 — §4.4 E2E contract drift (single `sessionKey: CryptoKey` → evolved shape)  *(E2E HIGH, GLOBAL HIGH, FRONTEND HIGH)*
P4 (E2E) evolved to: `AeadKey` (not `CryptoKey`), **synchronous** `sealFrame`/`openFrame`,
`aad = directionLabel‖seq`, **direction-split `DirectionalKeys` (`c2h`/`h2c`)** wrapped in a
stateful `E2ESession` (`.seal()`/`.open()`/`.rederive()`), handshake via
`buildClientHandshake(ctx, hostId, aeadOffer)`. But INDEX §4.4, **P2 T15 `makeHostHello`
(returns `sessionKey: CryptoKey`)**, and **P6 T8 (raw SubtleCrypto AES-GCM, single key)**
still use the ORIGINAL shape → they can't type-check against what P4 exports.
- **Do:** land P4 §9 Q4's amendments into **INDEX §4.4 / relay-contracts** first
  (`AeadKey`, sync sigs, `DirectionalKeys` c2h/h2c, `aad=directionLabel‖seq`, `ReplayKeyParams`).
  Then update **P2 T15** → `HandshakeResult` carrying `DirectionalKeys`; **P6 T8/T9** →
  consume `E2ESession`/`buildClientHandshake`/`AeadKey`. Closes P6 §8 Q4 by construction.

## FIX 3 — recoverable content-key (`K_content`/`hostContentSecret`) has no wiring or delivery  *(E2E HIGH, GLOBAL HIGH)*
The LOCKED "ciphertext ring-buffer survives reconnect" decision (EXPLORE §0 dec.2 / §4c)
needs a **recoverable** key: live frames use the ephemeral `h2c` key, but replay/preview
frames must use `K_content` derived from a host-scoped `hostContentSecret`. Problems:
(a) P2 never calls `sealReplayFrame`; P6 T9 never calls `openReplayCiphertext` → T10/T11
ship as unconsumed library code; (b) `hostContentSecret` has **no delivery** — P2 T4 and
P3 T8 `EnrollResult` return only `{hostId, subdomain, cert, caChain}`.
- **Do:** add `hostContentSecret` (wrapped to the agent's identity) to the **§4.5 enrollment
  contract + `EnrollResult`**; assign minting/wrapping to **P3 or P5 at BIND**, receipt/keystore
  to **P2**. Add consumer tasks: **P2** seals every replay-bound host→client output with
  `sealReplayFrame`; **P6 T9** decrypts via `openReplayCiphertext`/`deriveContentKey`. Extend
  T10/T11's merge gate to include this wiring.

## FIX 4 — INV12 revocation teardown has 3 incompatible descriptions + no P1 subscriber  *(AUTH HIGH, GLOBAL CRITICAL)*
P5 T10 publishes `KillSignal` on Redis pub/sub `relay:revocations` and asserts "P1
subscribes and injects §4.1 RST/GOAWAY". P3 T13 pushes over an unowned "control→node
channel (OQ4)". P1 T10/T11 imply P5 calls it directly. **`relay:revocations` + `KillSignal`
are NOT in INDEX §4.2** (only `route:{host_id}` / `revoked:{jti}` are), and **P1 has no
subscriber task**; `KillSignal` is defined P5-locally (would force P1→P5 import, against DAG).
- **Do:** freeze ONE control→data-plane teardown contract in **INDEX §4** — `relay:revocations`
  pub/sub + `KillSignal` shape, promoted into `relay-contracts`. Assign **P1** an explicit task
  that subscribes and turns `KillSignal` → §4.1 CLOSE+RST/GOAWAY via `closeStream`/`closeTunnel`.
  Reconcile **P3 OQ4** drain channel to the same named channel.

## FIX 5 — capability-token WS subprotocol wire format diverges  *(FRONTEND HIGH)*
P6 T4: `new WebSocket(url, ["relay.capability.v1", token])` (raw token). P1
`extractCapabilityToken`: `['term.relay.v1', 'term.token.' + base64url(token)]` (prefixed +
encoded, relay strips before verify; must echo only the app subprotocol). Neither is in
INDEX §4.3 → invented independently and diverged → real upgrade 401s while isolated tests pass.
- **Do:** freeze the exact app-subprotocol string + `term.token.` prefix + base64url encoding +
  "accepted subprotocol must be the app one, never the token" rule in **INDEX §4.3**. Update
  **P6 T4/T8** verbatim + assert `ws.protocol === 'term.relay.v1'` after open (tear down otherwise).

## FIX 6 — two more single-owner violations  *(GLOBAL HIGH ×2)*
- **6a. WS-upgrade auth implemented twice.** P1 T8 `authorizeUpgrade` re-implements the
  decision (Origin+token+cross-tenant+rights) while P5 T12 `onUpgrade` is the real gate
  (adds DPoP PoP, single-use burn, pre-auth throttle, step-up, per-tenant rate, audit).
  → Make **P1 T8 a thin adapter that DELEGATES to P5 `onUpgrade`/`onReattach`**; add DPoP +
  `activeSessionCount` to P1's `UpgradeRequest`. Authorization DECISION has exactly one owner (P5).
- **6b. `deviceAuthProof` verifier has 3 signatures + ambiguous home.** P5 T2 owns
  `verifyDeviceAuthProof(proof, expectedAccountId, transcriptHash, now)`; P4 T8 consumes an
  injected `verifyDeviceProof(proof, {clientEphPub, clientNonce})`; P2 T15 imports it from
  `relay-e2e` (wrong package). → **P5 owns** issuance+verification (binding to
  `{clientEphPub, clientNonce}` per P4 Q3); **P4 consumes as injected dep**; **P2 gets it via
  P4's host-handshake wiring** (fix the import). Unify the binding param across P2/P4/P5.

---

## Reconciliation pass shape (recommended)
1. **Amend `PLAN_RELAY_INDEX.md`** (single agent) — land Fixes 1,2,3,4,5,6 contract decisions
   into §4 (+ the W0 relay-contracts task). This is the coordination point; do it first.
2. **Sync consumer plans** (parallel, file-disjoint): P1 TRANSPORT (Fix 4 subscriber, 6a
   delegate, 5 confirm), P2 AGENT (Fix 2 DirectionalKeys, 3 seal+receive secret, 6b import),
   P3 CONTROLPLANE (Fix 3 EnrollResult, 4 OQ4 reconcile), P6 FRONTEND (Fix 2 T8/T9, 3 T9, 5 T4/T8).
   P4/P5 mostly already correct — minor confirmations.
3. **Re-run the global consistency review** to confirm zero residual contract drift.

Effort: ~7 agents (1 index + ~5 consumer syncs + 1 re-review) — far smaller than the
generation workflow. Do it as its own step, ideally in a fresh conversation (read this file
+ the 7 plan docs).