web-terminal/docs/PLAN_RELAY_TRANSPORT.md

# P1 — Tunnel & Mux Protocol + Relay Data Plane — Implementation Plan

> **Plan of record for the byte hot-loop.** Owns the native WS multiplexing protocol
> (frame codec, stream lifecycle, per-stream credit flow-control, 15s heartbeat, reconnection,
> graceful drain) between the host-agent and the **stateless** relay data plane; TLS termination;
> per-tenant **subdomain** routing (route by *authenticated session*, never the Host header);
> **opaque CIPHERTEXT forwarding** (parses zero terminal semantics); and the **v0.8 frp-based MVP
> scaffold** as an explicit stepping-stone toward the native mux.
>
> **Authoritative inputs** (do not reopen): [`EXPLORE_RELAY_SERVICE.md`](./EXPLORE_RELAY_SERVICE.md)
> §0 LOCKED DECISIONS, §3 (control/data split, multiplexing, routing, drain), §5 (MVP shortcuts);
> [`PLAN_RELAY_INDEX.md`](./PLAN_RELAY_INDEX.md) §3 (security invariants), §4 (**FROZEN SHARED
> CONTRACTS** — cited verbatim below, never redefined), §5 (P1 charter).
> Conventions follow [`PLAN.md`](./PLAN.md) / [`PLAN_VOICE_COMMANDS.md`](./PLAN_VOICE_COMMANDS.md):
> stable task IDs in dependency waves, disjoint `Owns:` per task, function-signature-level contracts,
> TDD (tests FIRST), explicit test cases incl. security/negative, per-task security notes.
> `PROGRESS_LOG.md` is **orchestrator-only** (subagents return a ready-to-paste entry, G1).

---

## 0. Scope & non-scope

**In scope (this plan, nothing else):**
- The **native WS mux** substrate: binary frame codec for the §4.1 frame format, per-stream state
  machine (`OPEN → (DATA | WINDOW_UPDATE)* → CLOSE`), **credit-based per-stream flow-control /
  backpressure** (WINDOW_UPDATE), 15s **PING/PONG heartbeat**, and **GOAWAY** graceful drain.
- The **stateless relay data-plane node**: TLS termination for inbound browser `wss://`, holding
  outbound agent mux tunnels, the WS-upgrade authorization edge (Origin **retained** + capability
  token **required**), **per-tenant subdomain routing** resolved from the authenticated principal,
  and the **opaque byte splice** browser-WS ↔ mux-stream ↔ (agent's) `ws://127.0.0.1:3000`.
- The **v0.8 frp scaffold**: `frps` config (wildcard vhost/subdomain routing) as the transport
  stepping-stone, contract-compatible with the native mux so the v0.9 swap reshapes nothing.

**Explicitly NOT in scope (owned by other plans — depend on their interfaces, never their files):**
- Accounts / host & routing registries / pairing issuance / cert authority / metering → **P3 CONTROL PLANE**.
- Ed25519 enrollment, agent dial-out client, `frpc` wrap, loopback forwarder, `npx …-agent pair` → **P2 AGENT**.
- Capability-token issuance/signing, mTLS cert verify, deny-by-default authz model, CI cross-tenant
  tripwire, revocation, audit log, rate-limits → **P5 AUTH & ISOLATION**. (P1 *enforces* these at the
  edge via injected interfaces; it does not *own* their logic.)
- E2E handshake + AEAD envelope → **P4 E2E** (rides P1 DATA frames as opaque ciphertext).
- Login / dashboard / browser-side crypto / client-side preview → **P6 FRONTEND**.

**Base app unchanged:** `src/`, `public/`, `protocol.ts`, the session model — **byte-for-byte
untouched**. P1 terminates at `ws://127.0.0.1:3000` where the agent (P2) is *just another local WS
client*. The single base-app touch-point (`ALLOWED_ORIGINS` gaining the subdomain) is applied at
**agent-install** time (P2), not by P1.

---

## 1. Security invariants this plan enforces

Per INDEX §3, P1 is a **primary owner** of **INV1, INV2, INV5, INV6, INV7, INV11, INV15** and
contributes to **INV9, INV12, INV13** (transport carries them). Mapping to enforcement points:

| INV | Where P1 enforces it | Task |
|---|---|---|
| **INV1** cross-tenant isolation — A can never reach B | `authorizeUpgrade` (thin adapter, FIX 6a) resolves the subdomain → `requestedHostId` and **delegates the `token.host == hostId` gate to P5's `onUpgrade`/`onReattach`**; Host header is a hint only, never the authority. No code path resolves a host by raw addr/port/user hostname. | T8 (→P5), T9, T13 |
| **INV2** relay handles only ciphertext | DATA payloads are copied **opaque**; the splice never decodes them; relay imports **no** xterm/ANSI parser. | T2, T10, T13 |
| **INV5** no plaintext/secret at rest | Data plane holds **no** durable buffers; per-connection allocation only, **no global mutable buffer pool**; nothing written to disk/Redis by P1 except metadata via P3. | T10, T13 |
| **INV6** deny-by-default authz on connect AND reattach | The deny-by-default **decision** is P5's (`onUpgrade`/`onReattach`, FIX 6a); `authorizeUpgrade` is a thin adapter that opens a stream **only** on P5's `{ok:true}` and passes every 401/403 through verbatim. Reattach flows the same P5 gate via `onReattach` (base-app `sessionId` re-authorized as a claim, not trusted). | T8 (→P5) |
| **INV7** stateless data plane | Node holds only in-RAM tunnel/stream maps; a crash loses nothing (agent reconnects + re-registers via P3). No DB-of-record on the node. | T9, T10, T11, T13 |
| **INV11** no terminal parsing in relay/agent | Static tripwire: relay/mux code has zero dependency on any terminal/ANSI parser; frames pass through opaque. | T2, T10, T13 |
| **INV15** capability token required on WS upgrade | The adapter extracts the token via the **frozen §4.3 FIX-5 subprotocol/cookie carriers only** (never the query string) and forwards it to P5, which enforces Origin/CSWSH + token validity + `aud`/`rights`. The relay echoes only `APP_SUBPROTOCOL` (`term.relay.v1`), never the token entry. | T8 (→P5) |
| **INV9** secrets validated at startup, never logged | `loadDataPlaneConfig` fails fast on missing TLS/CA/secret material; no secret ever logged. **Data-plane edge access logs MUST NOT include the raw upgrade `req.url`, the `Authorization` header, or the `Sec-WebSocket-Protocol` header value** (any of which can carry the capability token); log only `{subdomain, hostId, jti, decision, ts}`. | T1, T8, T10 |
| **INV12** fast revocation | **T14 subscribes to the frozen §4.2 `relay:revocations` bus** (FIX 4) and maps a `KillSignal` → immediate §4.1 teardown: host/account scope → `drainHost(reason=revoked)` RST+close (grace forced to 0, ≤ `REVOCATION_PUSH_BUDGET_MS`), global → node-wide GOAWAY+RST. Three-tier levers: `closeStream(hostId, {jti})` (single-device, see OQ6), `closeTunnel`/`drainHost(revoked)` (whole host, immediate), `operatorDrain`/`shutdown` (grace only for clean migration). P5 **publishes**; every P1 node **subscribes** (P1 never imports P5). | T6, T9, T10, T11, **T14** |
| **INV13** anti-replay/injection | P1 preserves per-message ordering and never reorders/dedups DATA (so P4's `seq`/nonce guarantees hold end-to-end); illegal frame transitions RST the stream. | T3, T6 |

---

## 2. Files & ownership (new package `term-relay/`, data-plane subtree only)

P1 and P3 co-inhabit `term-relay/` but own **disjoint subtrees** (INDEX §0). P1 owns `term-relay/mux/`
(the reusable protocol library, also imported by P2), `term-relay/data-plane/`, and
`term-relay/frp-scaffold/`. **Types** for §4.1 live in the INDEX-frozen `relay-contracts/`; P1 imports
them read-only and never redefines them. Files ≤ 400 lines typical, 800 hard max (`coding-style.md`).

| File | Action | Task | Phase |
|---|---|---|---|
| `term-relay/package.json`, `term-relay/tsconfig.json`, `term-relay/vitest.config.ts` | create — package skeleton (P1 seeds; P3 extends its own subtree) | T1 | v0.8 |
| `term-relay/data-plane/config.ts` | create — env → `DataPlaneConfig` (Zod, fail-fast, INV9) | T1 | v0.8 |
| `term-relay/mux/frame-codec.ts` | create — `encodeMuxFrame`/`decodeMuxFrame`/`decodeHeader` (§4.1) | T2 | spec v0.8 / live v0.9 |
| `term-relay/mux/type-bytes.ts` | create — `MuxFrameType ⇄ byte` + `flags` bit maps (§4.1) | T2 | v0.9 |
| `term-relay/mux/frame-guards.ts` | create — Zod boundary validation of OPEN/WINDOW_UPDATE/GOAWAY payloads (CBOR decode + `relay-contracts` schema) | T2 | v0.9 |
| `term-relay/mux/stream.ts` | create — pure stream state machine (`nextStreamState`, transitions) | T3 | v0.9 |
| `term-relay/mux/flow-control.ts` | create — credit-based `FlowController` (per-stream + link) | T4 | v0.9 |
| `term-relay/mux/heartbeat.ts` | create — 15s PING/PONG liveness (injectable timer) | T5 | v0.9 |
| `term-relay/mux/mux-session.ts` | create — multiplexer over one WS: demux, streams, flow, heartbeat, GOAWAY | T6 | v0.9 |
| `term-relay/data-plane/subdomain-router.ts` | create — `extractSubdomain` + `RouteResolver` interface (impl = P3) | T7 | v0.9 |
| `term-relay/data-plane/upgrade.ts` | create — `authorizeUpgrade` edge (Origin + capability token, INV1/6/15) | T8 | v0.9 |
| `term-relay/data-plane/agent-listener.ts` | create — accept agent dial-out, mTLS-verify (P5 iface), build `MuxSession`, register route (P3 iface) | T9 | v0.9 |
| `term-relay/data-plane/relay-node.ts` | create — stateless node: browser upgrade → openStream → **opaque splice** | T10 | v0.9 |
| `term-relay/data-plane/drain.ts` | create — GOAWAY graceful drain + `closeTunnel` for revocation (INV7/INV12) | T11 | v0.9 |
| `term-relay/data-plane/revocation-subscriber.ts` | create — subscribe `relay:revocations` (§4.2, FIX 4) → `KillSignal`→§4.1 CLOSE+RST/GOAWAY via T10/T11 (INV12) | T14 | v0.9 |
| `term-relay/frp-scaffold/frps.toml` | create — wildcard-subdomain vhost config (v0.8 substrate) | T12 | v0.8 |
| `term-relay/frp-scaffold/README.md` | create — VPS + wildcard DNS/TLS + `frps` runbook; retirement note | T12 | v0.8 |
| `term-relay/frp-scaffold/plugin-hook.ts` | create — thin frp server-plugin HTTP shim → delegates authz to P3 (no tenancy logic here) | T12 | v0.8 |
| `term-relay/test/**` (mux + data-plane + tripwire) | create — vitest unit/integration + INV tripwires | T2–T14 | per task |
| `relay-contracts/**` | **read-only** (INDEX-frozen §4.1 types) — P1 imports, never edits | — | — |

**Freeze rule:** T2's codec + T3–T5 pure modules export a stable surface consumed by T6, then T6 by
T9/T10; freeze each layer before the next consumes it (same discipline as PLAN_VOICE_COMMANDS §2).

---

## 3. Dependency waves

```
W0  package skeleton + config                         T1
      │
      ▼
W1  pure protocol leaves (all parallel)               T2 codec · T3 stream · T4 flow · T5 heartbeat
      │            (also parallel, separate lane)      T12 frp scaffold  ── v0.8, no dep on W1
      ▼
W2  mux session (assembles T2–T5)                      T6
      │
      ▼
W3  data-plane wiring (parallel where file-disjoint)  T7 router · T8 upgrade(→P5) · T9 agent-listener
      │                                                T10 relay-node (dep T6,T8,T9) · T11 drain (dep T6,T9)
      │                                                T14 revocation-subscriber (dep T10,T11) ── FIX 4
      ▼
W4  invariant tripwires + integration                 T13
```

**Cross-plan dependencies (interfaces, not files):**
- **T8** (FIX 6a) **delegates the authorization decision to P5** → injected `Authorizer` (`onUpgrade`/`onReattach`,
  §6a) consuming P5's frozen `UpgradeContext`/`AuthzOutcome`/`DpopContext`. T8 no longer imports a
  `CapabilityVerifier`/`OriginCheck` — P5 owns Origin/CSWSH + token verify + DPoP + rate + burn + audit.
- **T7/T8** depend on **P3**'s host registry read → injected `RouteResolver` (subdomain → `{hostId, accountId}`);
  T8 uses it only to name `requestedHostId` for the `UpgradeContext` (P5 makes the cross-tenant call).
- **T9** depends on **P5**'s mTLS peer-cert verify → injected `MtlsVerifier`; and **P3**'s Redis routing
  table write → injected `RouteRegistrar` (`route:{host_id}` heartbeat-TTL, §4.2).
- **T10** DATA path is contract-shared with **P2** (agent side of §4.1) and carries **P4**'s `E2EEnvelope`
  opaquely (§4.4) — P1 needs no P4 code (INV2).
- **T11** GOAWAY drain is invoked by **P3** node-drain coordination (`operatorDrain`/`shutdown`, grace honored); whole-host `closeTunnel`/`drainHost(reason=revoked)` (immediate, grace forced to 0) and single-device `closeStream(hostId, {jti})` are the levers.
- **T14** (FIX 4) **subscribes to the frozen §4.2 `relay:revocations` bus** — **P3/P5 publish** a `KillSignal`,
  every P1 node consumes it and drives T10/T11 teardown. The `KillSignal`/`RevocationScope`/channel constants
  live in `relay-contracts` (promoted out of `relay-auth`) so **P1 never imports P5** (DAG stays acyclic). P3
  OQ4's "control→node drain channel" reconciles to this exact channel.

In **v0.8**, the frp scaffold (T12) lets P2/P3 integrate against a real transport while T2–T14 are
built; the v0.9 native-mux swap is contract-compatible by construction (both speak §4.1 routing +
opaque byte forwarding), so nothing downstream reshapes.

---

## 4. Frozen shared contracts consumed (cited verbatim from INDEX §4 — NOT redefined)

P1 **imports** these from `relay-contracts/`; it must never re-declare them locally.

**§4.1 Mux frame (15-byte header)** — `version(1B)=0x01 · type(1B) · flags(1B: bit0 FIN, bit1 RST) ·
streamId(4B uint32, 0=link-level) · payloadLen(8B uint64 ≤ maxFrameBytes) · payload(var)`. Types:
`0x01 OPEN · 0x02 DATA · 0x03 CLOSE · 0x04 PING · 0x05 PONG · 0x06 WINDOW_UPDATE · 0x07 GOAWAY`.
Lifecycle `OPEN → (DATA | WINDOW_UPDATE)* → CLOSE`; illegal transition ⇒ **RST that stream, never the
tunnel**; `streamId` allocated by the **relay**, monotonic per tunnel, **never reused**.

```ts
// from relay-contracts (§4.1) — imported, frozen:
export type MuxFrameType = 'open' | 'data' | 'close' | 'ping' | 'pong' | 'windowUpdate' | 'goaway'
export interface MuxFrameHeader {
  readonly version: 1; readonly type: MuxFrameType; readonly fin: boolean; readonly rst: boolean
  readonly streamId: number; readonly payloadLen: number
}
export interface MuxOpen {
  readonly streamId: number; readonly subdomain: string; readonly requestPath: string
  readonly originHeader: string; readonly remoteAddrHash: string; readonly capabilityTokenRef: string
}
export function encodeMuxFrame(h: MuxFrameHeader, payload: Uint8Array): Uint8Array
export function decodeMuxFrame(buf: Uint8Array): { header: MuxFrameHeader; payload: Uint8Array }
```

- **§4.3 CapabilityToken** — the token **shape** T8 references (but does **not** itself verify — verification
  is delegated to P5, FIX 6a): `sub` (principal, from authenticated session, **never client**), `aud`
  (subdomain, Host-confusion guard, INV1), `host` (exact `host_id`, single host, never wildcard),
  `rights: ('attach'|'manage'|'kill')[]`, `iat`/`exp` (short TTL), `jti` (revocation lookup). P1 extracts the
  raw token at the edge and hands it to P5's `onUpgrade`/`onReattach`, which calls `verifyCapabilityToken(raw,
  expectedAud, now)` internally — T8 never calls it directly.
- **§4.3 WS-upgrade subprotocol wire format (FIX 5) — FROZEN, cited verbatim; T8's `extractCapabilityToken`
  MUST use these constants, never local literals**:
  ```ts
  // from relay-contracts (§4.3) — imported, frozen. Client opens:
  //   new WebSocket(url, [APP_SUBPROTOCOL, TOKEN_SUBPROTOCOL_PREFIX + base64url(rawToken)])
  export const APP_SUBPROTOCOL = 'term.relay.v1' as const          // the app subprotocol — the ONLY value ever accepted/echoed
  export const TOKEN_SUBPROTOCOL_PREFIX = 'term.token.' as const   // the token entry = this prefix + base64url(token)
  export function encodeTokenSubprotocol(rawToken: string): string // => 'term.token.' + base64url(rawToken)
  export function extractTokenFromSubprotocols(values: readonly string[]): string | null // strips prefix, base64url-decodes; null if absent
  ```
  **Echo rule (MUST):** read the token from the `term.token.<b64u>` entry via `extractTokenFromSubprotocols`,
  strip it before handing to P5, and the accepted/echoed `Sec-WebSocket-Protocol` in the handshake response
  **MUST be `APP_SUBPROTOCOL` (`'term.relay.v1'`), NEVER the token entry**. Query-string token transport is
  forbidden. (The earlier local literals `'term.relay.v1'`/`'term.token.'` in this plan are now these frozen
  constants — no local redefinition.)
- **§4.2 control→data-plane revocation teardown (FIX 4) — FROZEN, cited verbatim; consumed by T14**:
  ```ts
  // from relay-contracts (§4.2) — imported, frozen. P3/P5 PUBLISH; every P1 node SUBSCRIBES.
  export type RevocationScope =
    | { readonly kind: 'host'; readonly hostId: string }
    | { readonly kind: 'account'; readonly accountId: string }
    | { readonly kind: 'global' }
  export interface KillSignal {
    readonly scope: RevocationScope
    readonly at: number          // epoch seconds the revocation was issued
    readonly reason: string      // metadata only, ZERO payload (INV10)
  }
  export interface RevocationBus { publish(signal: KillSignal): Promise<void> }
  export const RELAY_REVOCATIONS_CHANNEL = 'relay:revocations' as const
  export const REVOCATION_PUSH_BUDGET_MS = 2000 as const
  ```
  P1 **subscribes** to `RELAY_REVOCATIONS_CHANNEL` and, per affected stream, injects a §4.1 `CLOSE`+`flags.RST`
  (host/account scope) or a link-level `GOAWAY` (global scope) using the **existing frozen §4.1 wire — no new
  frame type** — within `REVOCATION_PUSH_BUDGET_MS`. P5 stays socket-free (publishes only).
- **§4.2 data model** — consumed read-only via `RouteResolver`/`RouteRegistrar`: `hosts.host_id`
  (unguessable UUIDv4, never recycled), `hosts.subdomain` (stable), `route:{host_id} → {relayNodeId,
  updatedAt}` (Redis heartbeat-TTL, INV7). P1 **reads** `hostId`/`accountId`; it **writes** only the
  routing entry through P3's registrar.
- **§4.4 E2EEnvelope** — carried **inside** each DATA payload once E2E ships; P1 forwards it opaque and
  **never** derives keys or inspects `seq`/`nonce`/`ciphertext` (INV2). No P1 change at v0.10.

---

## 5. Task specifications

### W0

#### T1 · Package skeleton + data-plane config `[ ]`  — v0.8
- **Owns**: `term-relay/package.json`, `term-relay/tsconfig.json`, `term-relay/vitest.config.ts`,
  `term-relay/data-plane/config.ts`, `term-relay/test/config.test.ts`
- **Depends**: `relay-contracts/` exists (INDEX W0). · **Parallel-safe**: with T12.
- **Contract**:
  ```ts
  export interface DataPlaneConfig {
    readonly baseDomain: string          // e.g. 'term.example.com' — for extractSubdomain
    readonly bindHost: string            // default '0.0.0.0'
    readonly bindPort: number            // browser wss listener
    readonly agentBindPort: number       // agent dial-out listener
    readonly tlsCertPath: string; readonly tlsKeyPath: string   // relay's OWN server cert (browser-facing wss:)
    readonly agentCaCertPath: string     // CA/trust-anchor that MUST sign the agent's client cert on agentBindPort (mTLS root)
    readonly agentCaChainPath: string    // intermediate chain for agent-cert validation (rotation-safe; may equal agentCaCertPath if single-tier)
    readonly relayNodeId: string         // stable node id written into route:{host_id}
    readonly maxFrameBytes: number       // §4.1 payloadLen ceiling; default 1 MiB
    readonly initialWindowBytes: number  // §4.1 credit initial window; default 256 KiB
    readonly heartbeatIntervalMs: number // default 15_000
    readonly routeTtlMs: number          // Redis route TTL; default 45_000
  }
  export function loadDataPlaneConfig(env: NodeJS.ProcessEnv): DataPlaneConfig
  ```
- **Steps (TDD)**:
  1. **RED** `config.test.ts`: missing `TLS_CERT_PATH`/`TLS_KEY_PATH`/`BASE_DOMAIN` → `loadDataPlaneConfig` throws with a clear message (fail-fast, INV9); **missing `AGENT_CA_CERT_PATH` (the mTLS trust-anchor) → throws** — the agent-facing listener MUST NOT start without a CA to validate client certs against (else "mTLS" silently degrades to accept-any-cert, Finding-4 footgun); non-numeric `MAX_FRAME_BYTES` → throws; happy path returns typed frozen object; defaults applied.
  2. **GREEN** implement with a Zod schema (`z.coerce.number()` for ints, `z.string().min(1)` for paths). Return `Object.freeze(...)` (immutability). **Never log** cert/CA paths' contents; never log secrets.
- **Security note (INV9)**: startup MUST fail if TLS server material, the `AGENT_CA_CERT_PATH` mTLS trust-anchor, or `BASE_DOMAIN` is absent; no secret value is ever emitted to logs. The CA-path presence check is the config-level guarantee that T9 can wire TLS-layer `requestCert: true`/`rejectUnauthorized: true` (no accept-any-cert path exists).
- **Accept**: `npx vitest run config` green; `tsc --noEmit` clean.

### W1 — pure protocol leaves (all parallel, DOM-free, no `ws`/`pg`)

#### T2 · Mux frame codec `[ ]`  — spec written v0.8, becomes substrate v0.9
- **Owns**: `term-relay/mux/frame-codec.ts`, `term-relay/mux/type-bytes.ts`, `term-relay/mux/frame-guards.ts`, `term-relay/test/frame-codec.test.ts`
- **Depends**: `relay-contracts` §4.1 types. · **Parallel-safe**: T3–T5, T12.
- **Contract**:
  ```ts
  export const MUX_HEADER_BYTES = 15
  export const MUX_VERSION = 1 as const
  export const TYPE_TO_BYTE: Readonly<Record<MuxFrameType, number>>  // open→0x01 … goaway→0x07
  export const BYTE_TO_TYPE: ReadonlyMap<number, MuxFrameType>
  export function encodeMuxFrame(h: MuxFrameHeader, payload: Uint8Array): Uint8Array
  export function decodeHeader(buf: Uint8Array): MuxFrameHeader        // header-only peek (15B)
  export function decodeMuxFrame(buf: Uint8Array): { header: MuxFrameHeader; payload: Uint8Array }
  // CBOR-encoded typed payloads, validated at the boundary (coding-style: validate untrusted data):
  export function encodeOpen(open: MuxOpen): Uint8Array
  export function decodeOpen(payload: Uint8Array): MuxOpen             // Zod-guarded; throws on bad shape
  export function encodeWindowUpdate(credit: number): Uint8Array       // uint32
  export function decodeWindowUpdate(payload: Uint8Array): number
  export function encodeGoaway(lastStreamId: number, reason: number): Uint8Array
  export function decodeGoaway(payload: Uint8Array): { lastStreamId: number; reason: number }
  ```
- **Steps (TDD)**:
  1. **RED** `frame-codec.test.ts` (round-trip + adversarial):
     - round-trip each type; `encode∘decode === identity` for header fields incl. `fin`/`rst` bit packing.
     - `streamId=0` link-level frames decode with `streamId===0`.
     - `payloadLen` uses uint64 big-endian; a value > `Number.MAX_SAFE_INTEGER` → **throws** (safe-int guard, §4.1).
     - **negative**: truncated buffer (< 15B) → throws; `payloadLen` ≠ actual payload length → throws; unknown `type` byte (0x00, 0x08) → throws; `version ≠ 0x01` → throws; `payloadLen > maxFrameBytes` caller-check hook (codec exposes the raw length; the ceiling is enforced by T6 with config).
     - `decodeOpen` rejects a CBOR payload missing `subdomain`/`host`-scope fields (Zod) — **fuzz malformed CBOR → throws, never returns partial** (INV boundary validation).
  2. **GREEN** implement with `DataView` for the fixed header (big-endian) and `cbor-x` (or a tiny CBOR) for typed payloads; Zod-validate decoded OPEN/WINDOW_UPDATE/GOAWAY.
- **Security note (INV2/INV11)**: this module imports **no** terminal/ANSI parser; DATA payloads are handled as opaque `Uint8Array` and never inspected. `frame-guards.ts` validates *control* frames only (OPEN/WU/GOAWAY), never DATA content.
- **Accept**: `npx vitest run frame-codec` green; static check (T13) confirms no xterm/ansi import.

#### T3 · Stream state machine `[ ]`  — v0.9
- **Owns**: `term-relay/mux/stream.ts`, `term-relay/test/stream.test.ts`
- **Depends**: `relay-contracts` types. · **Parallel-safe**: T2/T4/T5.
- **Contract** (pure reducer — no I/O, no mutation of inputs):
  ```ts
  export type StreamState = 'idle' | 'open' | 'halfClosedLocal' | 'halfClosedRemote' | 'closed'
  export type StreamTransition = { readonly next: StreamState } | { readonly illegal: true }
  export function initialStreamState(): StreamState                     // 'idle'
  export function nextStreamState(
    current: StreamState, type: MuxFrameType, fin: boolean, dir: 'inbound' | 'outbound'
  ): StreamTransition
  export function isTerminal(s: StreamState): boolean
  ```
- **Steps (TDD)**:
  1. **RED** `stream.test.ts`: legal path `idle --OPEN--> open --DATA*--> open --CLOSE--> closed`; `DATA` with `fin` → half-closed in the sending direction; both-side FIN → `closed`. **Illegal (→ `{illegal:true}`, caller RSTs the stream):** DATA before OPEN; DATA after CLOSE; OPEN on an already-open streamId; any frame after `closed`. Direction matters (inbound FIN vs outbound FIN produce different half-closed states).
  2. **GREEN** implement as a total function returning a **new** state (never mutate).
- **Security note (INV13)**: illegal transitions are *rejected at the stream level* (RST one stream), never silently coerced — this is what lets P4's `seq` monotonicity mean something end-to-end.
- **Accept**: `npx vitest run stream` green; function < 50 lines.

#### T4 · Credit-based flow control `[ ]`  — v0.9
- **Owns**: `term-relay/mux/flow-control.ts`, `term-relay/test/flow-control.test.ts`
- **Depends**: none (pure). · **Parallel-safe**: T2/T3/T5.
- **Contract**:
  ```ts
  export const DEFAULT_INITIAL_WINDOW = 256 * 1024
  export const WINDOW_REPLENISH_THRESHOLD = 0.5   // emit WINDOW_UPDATE when half consumed
  export interface FlowController {
    registerStream(streamId: number, initialWindow: number): void
    releaseStream(streamId: number): void
    canSend(streamId: number, bytes: number): boolean   // false ⇒ backpressure (sender blocks)
    consumeSendCredit(streamId: number, bytes: number): void  // deduct on outbound DATA
    grantCredit(streamId: number, credit: number): void       // apply inbound WINDOW_UPDATE
    creditFor(streamId: number): number
    onDelivered(streamId: number, bytes: number): number      // returns credit to replenish (0 if < threshold)
  }
  export function createFlowController(): FlowController
  ```
- **Steps (TDD)**:
  1. **RED** `flow-control.test.ts`: `canSend` true until credit exhausted, then false; `consumeSendCredit` past window is rejected by `canSend` (never negative credit); `grantCredit` unblocks; `onDelivered` returns a replenish amount only once the threshold is crossed, else 0; unknown streamId → `canSend` false (deny-by-default), `creditFor` 0. Per-stream isolation: exhausting stream A's window does **not** affect stream B (**heavy `vim`/`top` redraw can't starve another stream**, §4.1).
  2. **GREEN** implement with a per-stream `Map<number, {window, sent, delivered}>`; immutable-style updates (replace the record).
- **Security note**: unknown/released streams are deny-by-default (no credit) — prevents send-after-close write amplification.
- **Accept**: `npx vitest run flow-control` green.

#### T5 · Heartbeat / liveness `[ ]`  — v0.9
- **Owns**: `term-relay/mux/heartbeat.ts`, `term-relay/test/heartbeat.test.ts`
- **Depends**: none. · **Parallel-safe**: T2–T4.
- **Contract** (timer injectable, per PLAN_VOICE_COMMANDS confirm-window pattern):
  ```ts
  export const HEARTBEAT_INTERVAL_MS = 15_000     // §4.1: PING every 15s
  export const HEARTBEAT_MISS_LIMIT = 3           // 3 missed PONGs ⇒ dead (~45s)
  export interface HeartbeatDeps {
    sendPing(token: Uint8Array): void
    onDead(): void
    now?: () => number
    schedule?: (fn: () => void, ms: number) => { cancel(): void }  // default setInterval-backed
  }
  export interface Heartbeat { start(): void; stop(): void; onPong(token: Uint8Array): void }
  export function createHeartbeat(deps: HeartbeatDeps): Heartbeat
  ```
- **Steps (TDD)**:
  1. **RED** with a fake scheduler: after `start`, a PING is sent every interval with a fresh 8-byte token; a matching `onPong` resets the miss counter; **3 intervals with no PONG → `onDead` fires exactly once** and no further PINGs; a PONG with a stale/unknown token does **not** reset the counter (prevents a spoofed/duplicated PONG from masking a dead link); `stop` cancels cleanly (no `onDead` after stop).
  2. **GREEN** implement with the injected scheduler; token = random 8 bytes (crypto RNG).
- **Security note (INV13-adjacent)**: PONG must echo the exact outstanding token; an unmatched token is ignored, so a replayed PONG can't keep a dead/hijacked tunnel "alive".
- **Accept**: `npx vitest run heartbeat` green.

### W2

#### T6 · Mux session (multiplexer over one WS) `[ ]`  — v0.9
- **Owns**: `term-relay/mux/mux-session.ts`, `term-relay/test/mux-session.test.ts`
- **Depends**: T2, T3, T4, T5. · **Parallel-safe**: with T7, T12.
- **Contract**:
  ```ts
  export interface MuxStreamHandle {
    readonly streamId: number
    writeData(payload: Uint8Array): boolean   // false ⇒ backpressured (buffered until WINDOW_UPDATE)
    close(rst?: boolean): void
  }
  export interface MuxSessionDeps {
    role: 'relay' | 'agent'
    sendWire(frame: Uint8Array): void          // write encoded frame to the underlying ws
    onOpen(open: MuxOpen, stream: MuxStreamHandle): void   // relay: n/a (relay opens); agent: dial :3000
    onData(streamId: number, payload: Uint8Array): void    // OPAQUE bytes (INV2) — never parsed
    onClose(streamId: number, rst: boolean): void
    onDead(): void
    maxFrameBytes: number
    initialWindowBytes: number
  }
  export interface MuxSession {
    openStream(open: MuxOpen): MuxStreamHandle   // relay-side: allocates monotonic streamId
    onWire(buf: Uint8Array): void                // feed inbound bytes: decode → dispatch
    drain(lastStreamId: number, reason: number): void   // send GOAWAY (T11)
    close(): void
  }
  export function createMuxSession(deps: MuxSessionDeps): MuxSession
  ```
- **Steps (TDD)**:
  1. **RED** `mux-session.test.ts` (two `MuxSession`s wired mouth-to-mouth via each other's `sendWire`):
     - relay `openStream(open)` → agent's `onOpen` fires with a fresh monotonic `streamId`; `streamId`s never reused within the session.
     - `writeData` on relay → agent `onData` receives **byte-identical** payload; a known plaintext marker in the payload is delivered verbatim and **never** inspected by the session (INV2).
     - **flow control**: fill a stream's window → `writeData` returns `false`; a WINDOW_UPDATE from the peer resumes flushing buffered data; stream A backpressure does not block stream B.
     - **heartbeat**: no PONG for `HEARTBEAT_MISS_LIMIT` intervals → `onDead`.
     - **lifecycle enforcement**: an inbound DATA for an unknown/closed streamId → session emits a **CLOSE with RST for that stream only**, the tunnel stays up (T3 illegal transition).
     - **frame ceiling**: an inbound frame with `payloadLen > maxFrameBytes` → RST that stream (or GOAWAY if link-level), never OOM.
  2. **GREEN** implement: incremental wire parser (buffer until a full 15B header + payload), `Map<streamId, streamCtx>` with T3 state + T4 credit, T5 heartbeat on streamId 0, GOAWAY handling.
- **Security note (INV2/INV5/INV11)**: DATA is copied opaque; buffers are **per-stream, per-session** (no global pool), freed on CLOSE — no cross-tenant buffer bleed possible. The session imports no terminal parser.
- **Accept**: `npx vitest run mux-session` green; file ≤ 400 lines (extract helpers if larger).

### W3 — data-plane wiring

#### T7 · Subdomain router `[ ]`  — v0.9
- **Owns**: `term-relay/data-plane/subdomain-router.ts`, `term-relay/test/subdomain-router.test.ts`
- **Depends**: T1 (config). · **Parallel-safe**: T8, T9, T11, T12.
- **Contract**:
  ```ts
  // RouteResolver is IMPLEMENTED BY P3 (control plane); P1 owns only the interface it depends on.
  export interface ResolvedHost { readonly hostId: string; readonly accountId: string; readonly subdomain: string }
  export interface RouteResolver { resolveSubdomain(subdomain: string): Promise<ResolvedHost | null> }
  export function extractSubdomain(hostHeader: string, baseDomain: string): string | null
  ```
- **Steps (TDD)**:
  1. **RED**: `extractSubdomain('alice.term.example.com', 'term.example.com')` → `'alice'`; a bare `baseDomain` → `null`; a **wildcard/confusion attempt** `'alice.term.example.com.evil.com'` → `null`; multi-label subdomain `'a.b.term.example.com'` → `null` (reject nested; single-label tenant only, INV1 Host-confusion guard); case-insensitive host; trailing dot tolerated.
  2. **GREEN** implement a strict suffix match returning the single leftmost label only.
- **Security note (INV1)**: `extractSubdomain` is a **hint** for candidate lookup; it is **never** the authority — T8 requires the capability token's `aud` to equal this subdomain and `token.host` to equal the resolver's `hostId`. Nested/confusing Host headers resolve to `null` (reject).
- **Accept**: `npx vitest run subdomain-router` green.

#### T8 · Upgrade authorization edge — **THIN ADAPTER over P5** `[ ]`  — v0.9  **(INV1/INV6/INV15 surface)**
> **FIX 6a — single-owner authorization.** The authorization **decision** (Origin/CSWSH + capability-token
> verify + DPoP proof-of-possession + single-use `jti` burn + pre-auth throttle + step-up + per-tenant rate +
> deny-by-default cross-tenant gate + audit) has **exactly one owner: P5** (`relay-auth/src/enforce/onUpgrade.ts`
> / `onReattach.ts`). **`authorizeUpgrade` holds NO independent authz logic** — it only (a) parses the upgrade
> (subdomain + FIX-5 token extraction + remoteAddr hash), (b) resolves the subdomain → `requestedHostId` via P3's
> `RouteResolver`, (c) builds P5's frozen `UpgradeContext` (incl. `dpop: DpopContext` + `activeSessionCount`),
> (d) calls the injected P5 `Authorizer`, and (e) maps the returned `AuthzOutcome` → a §4.1 `MuxOpen` (or a
> 401/403 close). Reattach flows the same gate via `onReattach` (base-app `sessionId` re-authorized as a claim).
- **Owns**: `term-relay/data-plane/upgrade.ts`, `term-relay/test/upgrade.test.ts`
- **Depends**: T2 (MuxOpen), T7 (resolver). **Cross-plan**: **P5 `Authorizer` = `onUpgrade`/`onReattach` + `UpgradeContext`/`AuthzOutcome`/`DpopContext` (§6a, imported read-only)**, P3 `RouteResolver`. · **Parallel-safe**: T9, T11.
- **Contract** (all P5 types imported from `relay-auth`, never redefined here):
  ```ts
  import { APP_SUBPROTOCOL, extractTokenFromSubprotocols } from 'relay-contracts'   // §4.3 FIX 5, frozen
  import type { UpgradeContext, AuthzOutcome, DpopContext } from 'relay-auth'       // §6a, P5-owned, frozen

  // P5 is the sole authorizer. P1 injects it; P1 supplies the ctx, P5 makes the decision.
  export interface Authorizer {
    onUpgrade(ctx: UpgradeContext, now: number): Promise<AuthzOutcome>
    onReattach(ctx: UpgradeContext & { sessionId: string }, now: number): Promise<AuthzOutcome>
  }
  export interface UpgradeRequest {
    readonly host: string; readonly origin: string | undefined
    readonly url: string                       // requestPath ONLY (opaque passthrough) — NEVER a token source
    readonly subprotocols: readonly string[]   // parsed Sec-WebSocket-Protocol values (FIX-5 token transport)
    readonly cookies: Readonly<Record<string, string>>  // parsed Cookie header (fallback token transport)
    readonly remoteAddr: string
    readonly dpop: DpopContext                 // FIX 6a: proof-of-possession material P5 needs (passed through, not inspected)
    readonly activeSessionCount: number        // FIX 6a: supplied for P5's per-tenant/step-up policy
    readonly sessionId?: string                // present ⇒ reattach path (→ onReattach); absent ⇒ onUpgrade
  }
  export type UpgradeDecision =
    | { readonly ok: true; readonly open: MuxOpen; readonly hostId: string; readonly acceptedSubprotocol: string }
    | { readonly ok: false; readonly status: 401 | 403 }
  // Token transport is FIXED, not free-form (FIX 5). Extract ONLY from the two allowed carriers via the
  // frozen §4.3 helper, NEVER from req.url query. Returns the opaque token string, or null if absent.
  export function extractCapabilityToken(req: UpgradeRequest): { token: string; via: 'subprotocol' | 'cookie' } | null
  export function authorizeUpgrade(req: UpgradeRequest, deps: {
    authorizer: Authorizer; resolver: RouteResolver
    baseDomain: string; now: () => number; remoteAddrSalt: string
    requiredRight: CapabilityRight   // 'attach' for a session upgrade
  }): Promise<UpgradeDecision>
  ```
- **Capability-token transport (FIX 5 — frozen §4.3, cited verbatim, INV15).** The browser's native `WebSocket`
  API cannot set arbitrary request headers, so the token rides one of exactly **two** carriers, in this order:
  1. **`Sec-WebSocket-Protocol` subprotocol (PREFERRED).** The client opens
     `new WebSocket(url, [APP_SUBPROTOCOL, encodeTokenSubprotocol(rawToken)])` — i.e.
     `['term.relay.v1', 'term.token.' + base64url(token)]`. `extractCapabilityToken` reads the token via the
     frozen `extractTokenFromSubprotocols(req.subprotocols)` (strips `TOKEN_SUBPROTOCOL_PREFIX`, base64url-decodes).
     The relay **MUST echo `acceptedSubprotocol = APP_SUBPROTOCOL` (`'term.relay.v1'`)** in the handshake response
     — **never** the `term.token.<b64u>` entry (echoing the token leaks the bearer secret). `UpgradeDecision.ok`
     therefore fixes `acceptedSubprotocol: 'term.relay.v1'` (non-nullable — the app subprotocol is always echoed).
  2. **Short-lived `HttpOnly; Secure; SameSite=Strict` cookie (FALLBACK).** Set by a prior authenticated
     HTTPS call (P6), scoped to the tenant subdomain, read from `req.cookies`. `HttpOnly` keeps it out of
     JS/`Referer`; `Secure` keeps it off plaintext; `SameSite=Strict` complements the retained Origin/CSWSH check.
  - **FORBIDDEN: the query string.** The token is a bearer-equivalent secret; `authorizeUpgrade` and
    `extractCapabilityToken` MUST NOT read any token from `req.url`. `req.url` carries **only** `requestPath`
    (opaque `?join=<id>` passthrough, never parsed for authz). Query-string tokens leak verbatim into
    reverse-proxy/CDN/frp access logs, browser history, and `Referer` headers.
- **Adapter logic (NO local authz decision — parse, delegate, map; INV6 deny-by-default lives in P5)**:
  ```
  subdomain = extractSubdomain(req.host, baseDomain);          if !subdomain    → 401   (unparseable Host, local)
  extracted = extractCapabilityToken(req);   // FIX-5 carriers only; NEVER req.url query
  if !extracted                                                                 → 401   (no token carrier present, local)
  resolved = await resolver.resolveSubdomain(subdomain);       if !resolved     → 403   (unknown subdomain, local)
  ctx: UpgradeContext = {
    capabilityRaw: extracted.token, originHeader: req.origin ?? '', expectedAud: subdomain,
    requestedHostId: resolved.hostId,           // P1 NAMES the host it resolved; P5 gates token.host against it (INV1)
    requiredRight, remoteAddrHash: hash(remoteAddrSalt, req.remoteAddr),
    activeSessionCount: req.activeSessionCount, dpop: req.dpop, principal: null /* P5 resolves from token */,
  }
  outcome = req.sessionId
    ? await authorizer.onReattach({ ...ctx, sessionId: req.sessionId }, now())   // P5 owns the decision
    : await authorizer.onUpgrade(ctx, now())
  if !outcome.ok                                                                 → { ok:false, status: outcome.status }
  open = { streamId: 0 /*allocated by MuxSession*/, subdomain, requestPath: pathOf(req.url),
           originHeader: req.origin ?? '', remoteAddrHash: ctx.remoteAddrHash,
           capabilityTokenRef: outcome.jti /* OQ5 RESOLVED — P5 §6a AuthzOutcome.ok now carries the verified jti */ }
  return { ok:true, open, hostId: outcome.hostId, acceptedSubprotocol: APP_SUBPROTOCOL }
  ```
  **`account_id`/`host_id` are derived by P5 from the signed token + registry — NEVER from client query/body/header (INV3).** The adapter passes `requestedHostId` (resolved from the subdomain), the raw token, Origin, and DPoP material to P5; **every accept/reject verdict is P5's**. `requestPath` is opaque passthrough the relay never parses for authz.
- **Steps (TDD)**:
  1. **RED** `upgrade.test.ts` (mock **P5 `authorizer`** + `resolver` — assert delegation, not local re-decision):
     - **delegation:** a happy `onUpgrade` (returns `{ok:true, hostId, principal, jti}`) → `{ok:true}`, `open.hostId === outcome.hostId`, `open.subdomain === 'alice'`, `acceptedSubprotocol === APP_SUBPROTOCOL`; assert `authorizer.onUpgrade` was called **exactly once** with a `UpgradeContext` carrying `expectedAud==='alice'`, `requestedHostId===resolved.hostId`, `requiredRight`, `dpop`, and `activeSessionCount` (proves ctx is fully populated).
     - **no local authz:** when P5 returns `{ok:false, status:401}` (foreign Origin / bad token / expired / aud-mismatch — all decided in P5), the adapter returns that status **verbatim** and opens **no** stream; the adapter contains no Origin/token/rights/cross-tenant branch of its own (assert by construction + coverage: every reject status originates from the `authorizer` mock).
     - **reattach:** `req.sessionId` present → `authorizer.onReattach` is called (not `onUpgrade`) with `{...ctx, sessionId}`; its `{ok:false}` maps straight through.
     - **token transport (FIX 5/INV15):** a token in `Sec-WebSocket-Protocol` (`['term.relay.v1','term.token.<b64u>']`) is extracted via `extractTokenFromSubprotocols` and forwarded as `ctx.capabilityRaw`, and `acceptedSubprotocol === 'term.relay.v1'` (the `term.token.` entry is **never** echoed); a token in `cookies['term_cap']` is accepted; **a token placed ONLY in the query string (`req.url = '/term?cap=<token>'`) → 401 and `authorizer.onUpgrade` is NEVER called** (spy count 0) — `extractCapabilityToken` never reads `req.url`, so no ctx is even built.
     - **cross-tenant is P5's (INV1):** the adapter forwards `requestedHostId = resolved.hostId` and the raw token; the 403 for `token.host !== hostId` is asserted at P5's `onUpgrade` (its own test), **not** re-implemented here — T8 only asserts the status is passed through.
     - **local parse failures only:** unparseable Host → 401 without calling the authorizer; unknown subdomain (`resolver` null) → 403 without calling the authorizer (nothing to authorize).
  2. **GREEN** implement thin: parse → resolve → build ctx → `await authorizer.onUpgrade/onReattach` → map. `hash` = HMAC-SHA256(salt, ip) truncated (audit-only, INV10). No decision branches beyond the three local parse guards above.
- **Security note**: FIX 6a makes this the **adapter**, not the gate — the "single hardest gate in P1" is now P5's `onUpgrade`/`onReattach`, so the decision cannot drift between two implementations. The adapter still enforces the FIX-5 transport (token only via subprotocol/cookie, never query; echo only `APP_SUBPROTOCOL`) and derives identity only from the signed token + registry via P5 (INV3). **Logging discipline (INV9):** the edge MUST NOT log `req.url`, the `Authorization` header, or the `Sec-WebSocket-Protocol` value (each can carry the bearer-equivalent token); it logs only `{subdomain, hostId, jti, decision, ts}`. P5 owns the *permanent CI cross-tenant tripwire*; T13 ships P1's data-plane-level assertion that the adapter never overrides a P5 deny.
- **Accept**: `npx vitest run upgrade` green; adapter has **zero** authz branches (delegation-only), verified by the "every reject originates from the authorizer mock" assertion.

#### T9 · Agent tunnel listener `[ ]`  — v0.9  **(INV4/INV7/INV12/INV14 surface)**
- **Owns**: `term-relay/data-plane/agent-listener.ts`, `term-relay/test/agent-listener.test.ts`
- **Depends**: T6 (MuxSession), T1 (config). **Cross-plan**: P5 `MtlsVerifier` (§ INV14), P3 `RouteRegistrar` (§4.2 `route:{host_id}`). · **Parallel-safe**: T8, T11.
- **Contract**:
  ```ts
  export interface MtlsVerifier {   // P5 impl — verifies the peer cert against the host registry pubkey
    verifyPeer(peerCert: Uint8Array): { hostId: string; accountId: string } | null
  }
  export interface RouteRegistrar {  // P3 impl — Redis route:{host_id} with heartbeat TTL (INV7)
    register(hostId: string, relayNodeId: string, ttlMs: number): Promise<void>
    heartbeat(hostId: string): Promise<void>
    deregister(hostId: string): Promise<void>
  }
  export interface AgentTunnel { readonly hostId: string; readonly session: MuxSession; closeTunnel(): void }
  export function createAgentListener(deps: {
    config: DataPlaneConfig; mtls: MtlsVerifier; registrar: RouteRegistrar
    onTunnel(t: AgentTunnel): void
  }): { attach(ws: WebSocketLike, peerCert: Uint8Array): void; tunnels(): ReadonlyMap<string, AgentTunnel> }
  ```
- **TLS-layer contract (two-tier defense, Finding-4):** the agent-facing TLS server on `agentBindPort`
  MUST be constructed with **`requestCert: true` AND `rejectUnauthorized: true`**, `ca` loaded from
  `config.agentCaCertPath` (+ `agentCaChainPath`). This makes the TLS handshake itself reject any
  connection that presents **no** client cert or a cert not chaining to our CA — **before** `attach()`
  or `verifyPeer()` is ever called. `verifyPeer` then runs only on a cert that has **already passed
  CA-chain validation**, and does the app-layer bind (cert pubkey → registry `agent_pubkey`, INV14/INV4).
  This is the explicit guard against the "send-any-cert, we check it ourselves after the fact" downgrade:
  presentation is enforced at the TLS layer, identity binding at the app layer — never one without the other.
- **Steps (TDD)**:
  1. **RED** `agent-listener.test.ts` (mock ws + mtls + registrar):
     - valid peer cert → `MuxSession` created, `registrar.register(hostId, nodeId, routeTtlMs)` called, tunnel indexed by `hostId`.
     - **TLS-layer enforcement (Finding-4):** a TLS handshake with **no client cert presented** is rejected at the TLS layer (`rejectUnauthorized`) — `attach()`/`verifyPeer()` are **never** invoked; assert the `attach` spy count is 0. Likewise a cert not chaining to `config.agentCaCertPath` → TLS reject, `attach` never called. Assert the TLS server options passed to the server factory are `{ requestCert: true, rejectUnauthorized: true, ca: <from agentCaCertPath/agentCaChainPath> }`.
     - **invalid/expired cert (`verifyPeer` → null) → the ws is closed, NO route registered** (INV14 — CA never binds an unknown pubkey; no shared secret path, INV4). (This is the app-layer check that runs *after* a cert has already passed CA-chain validation, e.g. cert chains to our CA but its pubkey is not in the host registry.)
     - heartbeat: every `heartbeatIntervalMs`, `registrar.heartbeat(hostId)` is called; on `onDead`/ws-close, `registrar.deregister(hostId)` runs and the tunnel is removed (**stateless — nothing durable survives**, INV7).
     - **revocation (INV12):** `closeTunnel()` tears down the ws + deregisters within the test tick.
     - reconnection: a second `attach` for the same `hostId` (agent reconnected on this node) replaces the prior tunnel and re-registers (latest wins; old one deregistered).
  2. **GREEN** implement; the node holds only an in-RAM `Map<hostId, AgentTunnel>` — **no DB of record** (INV7). Build the TLS server with `requestCert: true`, `rejectUnauthorized: true`, `ca` from the config CA paths; `attach` is only ever reached for a TLS-validated peer cert.
- **Security note (INV4/INV7/INV12/INV14)**: agent auth is **mTLS only**, enforced at **two tiers** — TLS-layer `requestCert`/`rejectUnauthorized` against `config.agentCaCertPath` guarantees a cert was presented *and* chains to our CA, then P5's `verifyPeer` binds that cert's pubkey to the registry `agent_pubkey`. No bearer/shared secret is ever accepted here; there is no code path that reaches `attach()` for an unauthenticated or no-cert peer. A node crash loses only the in-RAM map; agents reconnect and re-register (P3). `closeTunnel` is the revocation lever P5/P3 call to drop a live tunnel in seconds.
- **Accept**: `npx vitest run agent-listener` green.

#### T10 · Stateless relay node + opaque splice `[ ]`  — v0.9  **(INV2/INV5/INV7/INV11 core)**
- **Owns**: `term-relay/data-plane/relay-node.ts`, `term-relay/test/relay-node.test.ts`
- **Depends**: T6, T8, T9, T1. · **Parallel-safe**: T11 (disjoint file).
- **Contract**:
  ```ts
  export interface RelayNode {
    handleAgentTunnel(ws: WebSocketLike, peerCert: Uint8Array): void
    handleBrowserUpgrade(req: UpgradeRequest, ws: WebSocketLike): Promise<void>  // authorize → openStream → splice
    drain(reason: number): Promise<void>          // DRAIN_REASON value; delegates to T11
    closeTunnel(hostId: string): void             // WHOLE-host revocation lever (P5/P3) — kicks every device
    // SINGLE-device revocation (Finding-3): RST exactly the stream(s) opened under one capability token,
    // leaving every other device on the same host attached. Driven by P5's revoked:{jti} list (§4.2).
    // Returns the number of streams RST (0 if none matched — deny-by-default: unknown selector is a no-op).
    closeStream(hostId: string, selector: { readonly jti: string } | { readonly streamId: number }): number
  }
  export function createRelayNode(deps: {
    config: DataPlaneConfig; listener: ReturnType<typeof createAgentListener>
    authorize: (req: UpgradeRequest) => Promise<UpgradeDecision>   // = authorizeUpgrade bound to deps
  }): RelayNode
  ```
- **Splice (the byte hot-loop) — OPAQUE, zero parsing**:
  ```
  decision = await authorize(req);            if !decision.ok → ws.close(decision.status)   (INV6/INV15)
  tunnel = listener.tunnels().get(decision.hostId);  if !tunnel → ws.close(1013 /*try later*/)
  stream = tunnel.session.openStream(decision.open)                    // relay allocates streamId
  splices.add({ hostId: decision.hostId, streamId: stream.streamId,   // per-jti index for closeStream (Finding-3)
                jti: decision.open.capabilityTokenRef, ws, stream })
  ws.onMessage(bytes => stream.writeData(bytes))     // browser → agent : verbatim Uint8Array (INV2)
  stream via session.onData(id, bytes) → ws.send(bytes)   // agent → browser : verbatim (INV2)
  ws.onClose(() => { stream.close(); splices.remove(...) })
  stream.onClose(() => { ws.close(); splices.remove(...) })
  ```
  Buffers are **per-connection** (each `ws`↔`stream` pair) — **no global mutable buffer pool** (INV5, kills cross-tenant buffer bleed). The node never decodes DATA (INV2/INV11): a byte is a byte.
- **`closeStream` (single-device revocation, Finding-3/INV12)**: the node maintains an in-RAM splice
  index (`splices`) mapping `hostId → jti → {streamId, ws, stream}` (built at splice time above, torn down
  on close — still **stateless**, in-RAM only, INV7). `closeStream(hostId, {jti})` looks up every splice
  for that host+`jti`, calls `stream.close(/*rst*/ true)` (RSTs just those streams via the mux, tunnel
  stays up) and `ws.close(4403)` on each, removes them from the index, and returns the count. `{streamId}`
  is the same by exact stream. An unmatched selector RSTs nothing and returns 0 (deny-by-default no-op —
  never falls back to a broader kill). This is the primitive P5 calls when it adds a `jti` to
  `revoked:{jti}` (§4.2) to revoke **one shared device** while the legitimate owner's other devices
  (different `jti`s, latest-writer-wins sharing) stay attached.
- **Steps (TDD)**:
  1. **RED** `relay-node.test.ts` (in-memory ws pairs + a fake agent MuxSession):
     - browser upgrade authorized → a stream opens to the correct `hostId`'s tunnel; bytes typed at the browser arrive **byte-identical** at the agent side and vice-versa.
     - **INV2 ciphertext marker:** push a unique marker through; assert the relay-node code never inspects it and the marker is not retained in any node-level structure after CLOSE.
     - unauthorized upgrade (decision 401/403) → ws closed with the status; **no** stream opened, **no** tunnel touched.
     - no tunnel for the host (agent offline) → ws closed (1013), no crash.
     - **INV7 crash-survival:** drop the node's in-RAM maps (simulate crash) → no persisted state; a fresh node with a reconnected tunnel serves new upgrades; in-flight browser ws just reconnect (base-app backoff).
     - **INV1 isolation at the node:** an upgrade authorized for `hostA` can only ever reach `hostA`'s tunnel — there is no API to reach a tunnel by index/address; lookup is strictly `decision.hostId` (from the token, INV3).
     - **single-device revocation (Finding-3/INV12):** open two browser splices on the same host under two different `jti`s (`jtiA`, `jtiB` — the base-app multi-device sharing case); `closeStream(hostId, {jti: jtiA})` RSTs **only** `jtiA`'s stream and closes its ws (code 4403), returns `1`, while `jtiB`'s splice keeps flowing bytes bidirectionally (the legitimate owner's other device stays attached). Two splices under the **same** `jti` → both RST, returns `2`. `closeStream(hostId, {jti: 'unknown'})` → returns `0`, RSTs nothing (deny-by-default no-op, never widens to a whole-host kill). After a ws/stream closes normally, its splice-index entry is gone so a later `closeStream` for its `jti` returns `0` (no stale handle).
  2. **GREEN** implement thin; keep the file ≤ 300 lines (extract the splice helper / splice-index into a small module if needed). The splice index is in-RAM only (INV7).
- **Security note (INV2/INV5/INV7/INV11/INV12)**: the node is a **ciphertext-shuttle** — opaque splice, per-connection buffers, no durable state, no terminal parser. `closeStream` gives P5 a **surgical** revocation lever (RST exactly the streams under one revoked `jti`) so revoking a single compromised/shared device does **not** kick the owner's other devices — removing the "nuke everyone or nothing" false choice that would otherwise delay real revocation. This is the load-bearing "byte-shuttle → ciphertext-shuttle" upgrade.
- **Accept**: `npx vitest run relay-node` green.

#### T11 · Graceful drain + GOAWAY `[ ]`  — v0.9  **(INV7/INV12)**
- **Owns**: `term-relay/data-plane/drain.ts`, `term-relay/test/drain.test.ts`
- **Depends**: T6 (GOAWAY), T9 (tunnels). · **Parallel-safe**: T10 (disjoint file).
- **Contract**:
  ```ts
  export const DRAIN_REASON = { operatorDrain: 1, revoked: 2, shutdown: 3 } as const
  export type DrainReason = typeof DRAIN_REASON[keyof typeof DRAIN_REASON]
  export function drainNode(deps: {
    tunnels(): ReadonlyMap<string, AgentTunnel>
    registrar: RouteRegistrar
    reason: DrainReason
    inFlightGraceMs: number        // HONORED ONLY for operatorDrain/shutdown; FORCED to 0 for revoked (Finding-2)
  }): Promise<void>
  export function drainHost(hostId: string, deps: {
    tunnels(): ReadonlyMap<string, AgentTunnel>
    registrar: RouteRegistrar
    reason: DrainReason
    inFlightGraceMs: number        // HONORED ONLY for operatorDrain/shutdown; FORCED to 0 for revoked
  }): Promise<void>   // single-host (revocation / operator drain)
  ```
- **Grace-window rule (reason-differentiated, Finding-2/INV12):** the effective grace is
  `effectiveGraceMs = (reason === DRAIN_REASON.revoked) ? 0 : inFlightGraceMs`. A nonzero
  `inFlightGraceMs` is a *convenience for graceful operator drains/shutdowns only* (let an in-flight
  vim/paste flush before moving the host to another node). **`reason=revoked` is a security action against
  a compromised/malicious host or device** — it MUST force immediate teardown regardless of any caller-
  supplied `inFlightGraceMs`: RST every stream now, close the tunnel now, `registrar.deregister` now. This
  is what makes INV12's testable assertion ("its live tunnel drops within seconds") hold even when the
  operator-drain grace is tuned to tens of seconds.
- **Steps (TDD)**:
  1. **RED**:
     - `drainNode` with `reason=operatorDrain` sends **GOAWAY(lastStreamId, reason)** on streamId 0 to every tunnel; existing streams are allowed to finish within `inFlightGraceMs`, then tunnels close and routes are deregistered (P3). New `openStream` after GOAWAY is refused.
     - **`drainHost(hostId, {reason: DRAIN_REASON.revoked, inFlightGraceMs: N})` tears down all of that host's streams IMMEDIATELY regardless of N** (assert with a large N, e.g. 30_000): every stream is RST, the tunnel closes, and `registrar.deregister(hostId)` runs within the test tick — the grace window is **never** waited on. Same for `drainNode` with `reason=revoked` across all tunnels.
     - `drainHost` targets exactly one host and leaves siblings running (whole-host revocation, INV12).
  2. **GREEN** implement: compute `effectiveGraceMs` from `reason` before scheduling teardown; deregister via `registrar.deregister` so the ingress stops routing to this node/host.
- **Security note (INV12)**: `drainHost` is the whole-host revocation path — for `reason=revoked` it is GOAWAY + **immediate** RST + close + deregister (zero grace), dropping a compromised host's live tunnel within seconds; `operatorDrain`/`shutdown` keep a grace window purely for clean migration. **The customer's PTY survives** on their machine (base-app PTY≠WS decoupling); a relay-node bounce is invisible to the running Claude Code task (EXPLORE §3). For revoking **one shared device without kicking the others**, use T10's `RelayNode.closeStream` (per-`jti`), not a whole-host drain.
- **Accept**: `npx vitest run drain` green.

#### T14 · Revocation subscriber — `relay:revocations` → §4.1 teardown `[ ]`  — v0.9  **(INV12 data-plane teardown owner, FIX 4)**
> **FIX 4 — one control→data-plane teardown contract.** Fast revocation must tear down an **already-open**
> tunnel, not merely refuse the next connect. The frozen §4.2 bus (`RELAY_REVOCATIONS_CHANNEL` +
> `KillSignal`/`RevocationScope`, promoted into `relay-contracts` so P1 does **not** import P5 — DAG stays
> acyclic) is the **single** named channel: **P3/P5 PUBLISH, every P1 node SUBSCRIBES**. This task is P1's
> subscriber — the data-plane end of INV12. It injects **no new wire type**: it maps a `KillSignal` onto the
> existing §4.1 `CLOSE`+`flags.RST` (per stream) or link-level `GOAWAY` (global) via T10/T11's levers.
- **Owns**: `term-relay/data-plane/revocation-subscriber.ts`, `term-relay/test/revocation-subscriber.test.ts`
- **Depends**: T10 (`RelayNode.closeStream`/`closeTunnel`), T11 (`drainHost`/`drainNode`). **Cross-plan**: subscribes to a Redis pub/sub client (injected); the publisher is **P5** `revoke()` / **P3** (§4.2). · **Parallel-safe**: none in W3 (consumes T10+T11); runs after both freeze.
- **Contract** (frozen §4.2 types imported from `relay-contracts`, never redefined):
  ```ts
  import type { KillSignal, RevocationScope } from 'relay-contracts'
  import { RELAY_REVOCATIONS_CHANNEL, REVOCATION_PUSH_BUDGET_MS } from 'relay-contracts'   // 'relay:revocations', 2000

  export interface RevocationSubscriberDeps {
    subscribe(channel: string, onMessage: (raw: string) => void): { close(): void }  // injected Redis pub/sub
    node: Pick<RelayNode, 'closeTunnel'>                       // whole-host lever (T10)
    drainHost(hostId: string, reason: typeof DRAIN_REASON.revoked): Promise<void>     // immediate host teardown (T11)
    tunnels(): ReadonlyMap<string, AgentTunnel>               // to enumerate hosts for account/global scope
    routeResolver: RouteResolver                              // account → hostIds this node currently serves
    now: () => number
    onApplied?(signal: KillSignal, hostsAffected: number, elapsedMs: number): void   // budget/audit metadata only (INV10)
  }
  // Pure scope→hosts selector (testable in isolation): which of THIS node's live hosts a signal hits.
  export function hostsForScope(scope: RevocationScope, liveHosts: ReadonlyMap<string, AgentTunnel>,
                                accountOf: (hostId: string) => string): readonly string[]
  export function startRevocationSubscriber(deps: RevocationSubscriberDeps): { close(): void }
  ```
- **Mapping (KillSignal → §4.1 teardown, no new frame type)**:
  ```
  on message on RELAY_REVOCATIONS_CHANNEL:
    signal = parseKillSignal(raw)            // Zod-validate at the boundary; malformed → drop + count (no throw across the bus)
    switch signal.scope.kind:
      'host'    → drainHost(scope.hostId, DRAIN_REASON.revoked)   // GOAWAY? no — RST every stream now + close tunnel + deregister (T11, grace forced 0)
      'account' → for hostId in hostsForScope(scope, tunnels(), accountOf): drainHost(hostId, revoked)
      'global'  → for every tunnel: drainHost(hostId, revoked)    // link-level GOAWAY + RST all (node-wide)
    onApplied?(signal, hostsAffected, now()-startedAt)            // metadata only; MUST NOT log the reason string as payload (INV10)
  ```
  Every path uses **T11's `reason=revoked` immediate teardown (grace forced to 0)** so the §4.2
  `REVOCATION_PUSH_BUDGET_MS = 2000` budget is met. An unknown/absent host (already gone) is a **no-op**
  (deny-by-default: nothing to tear down, never a broader kill).
- **Steps (TDD)**:
  1. **RED** `revocation-subscriber.test.ts` (fake pub/sub + spy `drainHost`/`closeTunnel`, in-RAM tunnels):
     - a `{scope:{kind:'host',hostId:H}}` message → `drainHost(H, revoked)` called once **within `REVOCATION_PUSH_BUDGET_MS`** (assert with a fake clock); a host **not** on this node → no-op (0 calls).
     - `{scope:{kind:'account',accountId:A}}` → exactly the node's live hosts owned by A are torn down; a sibling host of another account keeps flowing (INV1 blast-radius contained to the account).
     - `{scope:{kind:'global'}}` → every live tunnel torn down (node-wide GOAWAY+RST).
     - **immediacy (INV12):** teardown does **not** wait any grace — assert `drainHost` is invoked with `reason=revoked` (grace forced to 0 per T11), even if the node's operator-drain grace is large.
     - **malformed signal** (bad JSON / missing `scope`) → dropped, counted, **no** teardown fired, subscriber stays alive (a poisoned message can't kill the bus or trigger a spurious kill).
     - **no payload leak (INV10):** `signal.reason` is never written to a data structure or log as content; only `{scope, hostsAffected, elapsedMs}` metadata is emitted via `onApplied`.
     - `close()` unsubscribes cleanly (no teardown after close).
  2. **GREEN** implement thin: `subscribe(RELAY_REVOCATIONS_CHANNEL, …)`, Zod-parse, `hostsForScope`, fan out to `drainHost(…, DRAIN_REASON.revoked)`. `hostsForScope` is a pure function (unit-tested standalone).
- **Security note (INV12/INV1/INV10)**: this closes the FIX-4 gap — P5/P3 publish a `KillSignal`, **every** P1 node reacts by RST-ing exactly the in-scope streams and dropping the tunnels **immediately** (grace 0), so a compromised host/account is off the data plane within the 2s budget **even for connections already open**. Scope selection is blast-radius-bounded (`host` ⊂ `account` ⊂ `global`); a host this node doesn't serve is a no-op (no cross-tenant reach, INV1). The `reason` string is metadata only — never forwarded as terminal payload (INV10). P1 **subscribes only**; it never publishes (P5 stays the sole revocation authority). **Single-device (per-`jti`) revocation** is a finer granularity than the frozen `KillSignal` scope expresses — see §9 OQ6.
- **Accept**: `npx vitest run revocation-subscriber` green; teardown latency assertion ≤ `REVOCATION_PUSH_BUDGET_MS`.

### W1-parallel lane — v0.8 scaffold

#### T12 · frp MVP scaffold (v0.8 stepping-stone) `[ ]`  — v0.8
- **Owns**: `term-relay/frp-scaffold/frps.toml`, `term-relay/frp-scaffold/README.md`, `term-relay/frp-scaffold/plugin-hook.ts`, `term-relay/test/plugin-hook.test.ts`
- **Depends**: none (independent lane). **Cross-plan**: P3 exposes an authz hook endpoint; P2 wraps `frpc` (agent side).
- **Deliverables**:
  - `frps.toml`: single-node `frps` on the VPS, **wildcard vhost** so `*.term.<domain>` routes by subdomain to the agent's proxy (EXPLORE §5.4); TLS terminated here or at Cloudflare in front (M6 scheme-following preserved end-to-end); `vhostHTTPSPort`/`subdomainHost` set to `BASE_DOMAIN`.
  - `plugin-hook.ts`: a **thin** HTTP server-plugin shim implementing frp's `Login`/`NewProxy`/`NewUserConn` hooks by **delegating** the decision to P3's control-plane authz endpoint (checks `agentToken`/`clientToken` hashes, subdomain ownership). **No tenancy logic lives here** — it forwards and enforces the deny-by-default answer.
  - `README.md`: the café-demo runbook — VPS + wildcard DNS (`*.term.<domain>`) + wildcard TLS (LetsEncrypt DNS-01) + `frps` + the P2 `frpc`-wrapped agent; **plus an explicit "retirement" section**: what each frp piece maps to in the native mux (frp yamux → §4.1 mux; frp subdomain vhost → T7 router; frp login plugin → T8 upgrade gate) so v0.9 is a swap, not a rewrite.
- **Steps (TDD)**:
  1. **RED** `plugin-hook.test.ts`: a `NewUserConn`/`Login` payload with an unknown token → hook returns **reject** (deny-by-default); a valid one whose subdomain the control plane owns → allow; the hook **forwards** to P3 and never decides tenancy itself; malformed payload (Zod) → reject.
  2. **GREEN** implement the shim (Zod-validate the frp hook body at the boundary).
- **Security note**: even the v0.8 scaffold keeps auth at the relay edge (the auth the base app never had, EXPLORE §5.5). The shared `clientToken`/`agentToken` gate is a **known, temporary** shortcut (INDEX v0.8) — it is replaced by capability tokens (T8) + mTLS (T9) + Passkey/pairing (P2/P3/P5) in v0.9/v0.10; the frame path is already designed so ciphertext (P4) drops into DATA without reshaping (INV2). **No plaintext terminal bytes are parsed even in v0.8** — frp forwards opaque TCP/WS streams (INV11).
- **Accept**: `npx vitest run plugin-hook` green; README runbook reproduces the café demo on one VPS.

### W4 — invariant tripwires & integration

#### T13 · P1 invariant tripwires + integration `[ ]`  — v0.9
- **Owns**: `term-relay/test/inv-tripwires.test.ts`, `term-relay/test/integration/data-plane.test.ts`
- **Depends**: T2–T11, T14. · **Parallel-safe**: none (integration convergence, like PLAN §W4).
- **Steps (tests)**:
  - **INV11 static:** assert the `term-relay/mux/**` and `term-relay/data-plane/**` dependency graph imports **no** xterm/ANSI/terminal parser (scan `import`s; fail if any match `/xterm|ansi|vt100|terminal-parser/i`).
  - **INV2 ciphertext:** end-to-end through a real `MuxSession` pair + `relay-node` splice, inject a unique plaintext marker; assert it appears **only** as opaque bytes in transit and is absent from every relay-side retained structure and from logs.
  - **INV1 cross-tenant (data-plane assertion, complements P5's permanent CI tripwire):** device authorized for host A → 403 when hitting host B's subdomain, on first connect **and** on reconnect/reattach.
  - **INV7 stateless:** kill a node mid-stream → no data at rest; reconnected tunnel on a new node serves fresh upgrades; PTY (base app) unaffected.
  - **INV6 deny-by-default (FIX 6a):** the `authorizeUpgrade` adapter opens a stream **only** on P5's `{ok:true}`; every P5 `{ok:false}` and every local parse-guard failure returns 401/403 with no stream opened — assert the adapter has no independent allow branch (a P5 deny is never overridden into an allow).
  - **INV13 ordering:** DATA frames are delivered in order and never reordered/deduped by the relay (so P4's `seq` holds); an illegal transition RSTs one stream, not the tunnel.
  - **INV12 revocation (Finding-2/Finding-3 + FIX 4):** end-to-end, a `KillSignal{scope:{kind:'host',hostId}}` published on `relay:revocations` is consumed by **T14** and tears down that host's live tunnel within `REVOCATION_PUSH_BUDGET_MS` (already-open streams, not just the next connect); an `account` scope tears down only that account's hosts on the node (siblings keep flowing, INV1); `closeStream(hostId, {jti})` drops exactly one shared device's stream while a sibling device (different `jti`) keeps flowing; `drainHost(hostId, {reason: revoked, inFlightGraceMs: large})` tears down the whole host **without** waiting the grace window (immediate), whereas `reason: operatorDrain` honors it.
  - **INV15 token transport (Finding-1):** a browser upgrade carrying the capability token **only** in the query string is rejected (401) end-to-end; a token via `Sec-WebSocket-Protocol` (or `HttpOnly` cookie) is accepted; assert no test log line contains the raw token, `req.url`, or the `Sec-WebSocket-Protocol` value (INV9 access-log discipline).
  - **INV14 mTLS presentation (Finding-4):** a simulated agent handshake with no client cert (or a cert not chaining to `agentCaCertPath`) is rejected at the TLS layer — `attach()`/`verifyPeer()` are never reached.
- **Accept**: `npx vitest run` (all `term-relay/` P1 tests) green; coverage ≥ 80% across mux + data-plane (`coding-style`/`testing.md`).

---

## 6. Security section (P1)

**Threat model:** the relay bridges full interactive shells for many tenants; a data-plane compromise
is worst-case RCE-shaped (EXPLORE §4). P1's job is to keep the node a **dumb ciphertext-shuttle** so it
*cannot* leak or inject what it *cannot* parse, and to make cross-tenant reach structurally impossible.

- **Cross-tenant isolation (INV1)** — the only path to a host is `authorizeUpgrade`, which (FIX 6a) resolves
  the subdomain → `requestedHostId` and **delegates the `token.host == hostId` gate to P5's `onUpgrade`/`onReattach`**
  — the decision has exactly one owner, so it cannot drift between two implementations. No code resolves a host
  by raw address/port/user hostname. Host header is a hint, never authority (`aud` guard + nested-subdomain
  rejection, T7; P5 owns the token/`aud` check). `host_id` is an unguessable, never-recycled UUIDv4 (§4.2).
  Fuzzed `host_id` guessing → 403 (P5 `onUpgrade`; T13 asserts the adapter passes it through).
- **Ciphertext-shuttle (INV2/INV11)** — DATA payloads are opaque `Uint8Array`; no module imports a
  terminal parser (static tripwire T13). E2E envelopes (§4.4) ride DATA unread; **no P1 change at v0.10**.
- **Deny-by-default authz (INV6) + capability token on upgrade (INV15)** — the full decision (Origin/CSWSH
  retained **AND** §4.3 token required, default reject, least-privilege rights, DPoP, single-use burn, rate,
  step-up, audit) is **owned solely by P5** (`onUpgrade`/`onReattach`, FIX 6a). P1's `authorizeUpgrade` is a
  **thin adapter**: it extracts the token via the frozen §4.3 FIX-5 carriers (subprotocol/cookie, never query),
  builds P5's `UpgradeContext` (incl. `dpop` + `activeSessionCount`), and opens a stream only on P5's `{ok:true}`.
- **`account_id`/`host_id` never client-supplied (INV3)** — identity derives only from the token +
  registry; `requestPath` query (`?join=…`) is opaque passthrough, never used for authz.
- **No shared secrets / mTLS (INV4/INV14)** — the agent listener accepts only mTLS-verified peers
  (P5 checks the cert against the registry **public** key); no bearer/shared-secret branch exists in v0.9+.
- **Stateless, no plaintext at rest (INV5/INV7)** — the node holds only in-RAM maps + per-connection
  buffers (no global pool → no buffer bleed); a crash persists nothing; P1 writes no shell bytes anywhere.
- **Fast revocation (INV12), FIX 4 single channel** — every P1 node **subscribes** to the frozen §4.2
  `relay:revocations` bus (T14); **P3/P5 publish** a `KillSignal`. On a `host`/`account`-scoped signal the
  subscriber tears down the in-scope tunnel(s) via `drainHost(reason=revoked)` — RST every stream + close +
  deregister **immediately (grace forced to 0, Finding-2)**, within `REVOCATION_PUSH_BUDGET_MS` — and on
  `global` a node-wide GOAWAY+RST. `operatorDrain`/`shutdown` keep a grace window only for clean migration.
  Single-device (per-`jti`) `closeStream` remains a T10 lever but currently has no bus scope (§9 OQ6). P1
  **subscribes only, never publishes** (P5 stays sole revocation authority; P1 does not import P5). The
  customer's PTY survives locally in every case.
- **Secrets (INV9)** — `loadDataPlaneConfig` fails fast on missing TLS server material, the
  `AGENT_CA_CERT_PATH` mTLS trust-anchor, or `BASE_DOMAIN`; **no `console.log`** in P1 (`code-review.md`);
  nothing secret is ever logged. **The capability token is bearer-equivalent**, so the data-plane edge
  access log excludes the raw upgrade `req.url`, the `Authorization` header, and the
  `Sec-WebSocket-Protocol` value — it records only `{subdomain, hostId, jti, decision, ts}` (Finding-1).
- **Anti-replay/injection carrier (INV13)** — P1 preserves DATA ordering and RSTs illegal stream
  transitions, so P4's per-message nonce + monotonic `seq` are meaningful end-to-end.

**v0.8 shortcut, stated honestly:** the frp scaffold uses a shared `clientToken`/`agentToken` gate at
the edge (INDEX v0.8). It is a **known temporary** posture, replaced by capability tokens + mTLS +
Passkey/pairing before the first paid signup (EXPLORE §7). Even in v0.8, frp forwards opaque streams —
**no terminal parsing** (INV11).

---

## 7. Verification

```bash
# --- pure protocol leaves ---
npx vitest run --dir term-relay frame-codec      # §4.1 codec round-trip + adversarial/fuzz
npx vitest run --dir term-relay stream           # stream state machine (legal + illegal transitions)
npx vitest run --dir term-relay flow-control     # credit windows, per-stream isolation, deny-by-default
npx vitest run --dir term-relay heartbeat        # 15s PING/PONG, miss→dead, stale-token ignored

# --- mux + data plane ---
npx vitest run --dir term-relay mux-session      # multiplex, backpressure, RST-one-stream, frame ceiling
npx vitest run --dir term-relay subdomain-router # extractSubdomain, Host-confusion rejection
npx vitest run --dir term-relay upgrade          # FIX 6a: adapter delegates to P5 onUpgrade/onReattach; FIX 5 token transport; zero local authz branches
npx vitest run --dir term-relay agent-listener   # INV4/INV7/INV14: mTLS-only, register/heartbeat/deregister
npx vitest run --dir term-relay relay-node       # INV2/INV5/INV7/INV11: opaque splice, per-conn buffers
npx vitest run --dir term-relay drain            # INV7/INV12: GOAWAY drain + per-host revocation
npx vitest run --dir term-relay revocation-subscriber  # INV12/FIX4: relay:revocations KillSignal → §4.1 CLOSE+RST/GOAWAY ≤ 2s

# --- v0.8 scaffold ---
npx vitest run --dir term-relay plugin-hook      # frp hook deny-by-default → delegates to P3

# --- invariant tripwires + integration + coverage ---
npx vitest run --dir term-relay inv-tripwires    # INV11 static import scan, INV2 marker, INV1 data-plane 403
npx vitest run --dir term-relay integration      # end-to-end data-plane splice through a MuxSession pair
npx vitest run --dir term-relay --coverage       # ≥ 80% across mux + data-plane (testing.md)
cd term-relay && npx tsc --noEmit                # types clean; relay-contracts imported read-only
grep -rEi 'xterm|ansi|vt100|terminal-parser' term-relay/mux term-relay/data-plane && echo FAIL || echo OK  # INV11
```

**Manual / deployment verification (v0.8 café demo, T12):** one VPS, wildcard DNS `*.term.<domain>`,
wildcard TLS (LetsEncrypt DNS-01 or Cloudflare in front), `frps` running, a P2 `frpc`-wrapped agent
paired on a laptop. From a phone browser open `alice.term.<domain>`, pass the `clientToken` gate, land
in the laptop shell — **no router/VPN/static-IP configured**. Confirm: (1) a relay-node restart does
**not** kill the running shell (PTY survives, INV7); (2) a foreign-Origin page cannot open the WS
(CSWSH retained); (3) all 212 base-app tests still pass (`npm test` in repo root) — the relay adds a
layer *underneath* the existing WebSocket, it does not modify `src/`.

---

## 8. Phasing summary

| Phase | P1 tasks | Deliverable |
|---|---|---|
| **v0.8 MVP** | T1 (config), T12 (frp scaffold), **T2 spec-written** | Café demo on frp; §4.1 frame format authored (not yet the substrate); auth at the relay edge (shared-token shortcut). |
| **v0.9 SaaS** | T2–T11, **T14**, T13 | Native WS mux **replaces frp**: §4.1 as the real substrate, per-stream flow control, 15s heartbeat, reconnection, GOAWAY drain, stateless node, subdomain routing by authenticated session, **upgrade gate as a thin adapter delegating to P5 `onUpgrade`/`onReattach` (FIX 6a)**, mTLS agent listener, opaque splice, and the **`relay:revocations` subscriber that turns a `KillSignal` into immediate §4.1 teardown (FIX 4)**. |
| **v0.10 E2E-hardening** | *(no P1 code change)* | DATA already carries P4's `E2EEnvelope` opaquely (INV2) — the frame path was designed so ciphertext drops in without reshaping. P1 only re-runs its INV2/INV13 tripwires against the E2E build. |

---

## 9. Open questions (for the orchestrator — do NOT guess, per CLAUDE.md subagent rule)

1. **CBOR dependency for typed control-frame payloads (OPEN/WINDOW_UPDATE/GOAWAY).** §4.1 says OPEN is
   "CBOR of MuxOpen". Confirm the shared CBOR lib choice (`cbor-x`?) and whether it belongs in
   `relay-contracts/` (so P2 agent + P1 relay share one encoder) or is P1-owned in `mux/`. Leaning:
   put the CBOR codec in `relay-contracts/` next to the frozen types so both sides import one impl.
2. **Where `encodeMuxFrame`/`decodeMuxFrame` physically live.** §4.1 lists the signatures under "P1
   owns" but the *types* are frozen in `relay-contracts/`. This plan puts the **binary codec impl** in
   `term-relay/mux/frame-codec.ts` (P1) and has P2 import it. Confirm P2 importing from `term-relay/mux/`
   is acceptable, or whether the codec should move into `relay-contracts/` to keep the agent from
   depending on the relay package. (Either is contract-compatible; it's a packaging call.)
3. **TLS termination boundary.** EXPLORE §3 allows terminating TLS at the relay **or** at Cloudflare in
   front. `DataPlaneConfig` carries cert/key paths for in-process termination; confirm the default
   deployment (in-process LetsEncrypt vs CF-in-front) so the T12 runbook picks one as primary.
4. **Ingress vs in-process routing at scale.** This plan keeps routing in-process on a single node
   (v0.8/v0.9, YAGNI per EXPLORE §7 v0.11). Confirm the Redis-routing-table + L7-ingress (Envoy/Traefik)
   split is deferred to a later multi-node plan and not P1's responsibility now.
5. **`AuthzOutcome` surfaces `jti` — RESOLVED (reconcile OQ5).** T8 is a thin adapter that no longer verifies
   the capability token (P5's `onUpgrade` does), so it cannot read `token.jti` itself — but `MuxOpen.capabilityTokenRef`
   (used by T10's per-`jti` splice index for single-device `closeStream`) needs it. P5 now adds `readonly jti: string`
   to the `ok` branch of `AuthzOutcome` (PLAN_RELAY_AUTH_ISOLATION.md T3), surfacing the *verified* token's jti; P1
   consumes `outcome.jti` read-only for `capabilityTokenRef`. No local redefinition of `AuthzOutcome` in P1.
6. **Single-device (per-`jti`) revocation vs the frozen `KillSignal` scope.** FIX 4 froze `RevocationScope` as
   `host | account | global` only — it has **no per-device/per-`jti` granularity**. But INV12 and T10's
   `closeStream(hostId, {jti})` still require revoking **one shared device while the owner's other devices stay
   attached**. The `relay:revocations` bus therefore cannot currently express single-device revocation; T14 only
   covers host/account/global. **Ask the INDEX owner** whether to (a) add a `{kind:'device'; hostId; jti}` arm to
   `RevocationScope` (then T14 routes it to `closeStream`), or (b) keep single-device revocation on a separate
   per-`jti` mechanism. Pending that decision, T10's `closeStream` remains but has no bus trigger. **Do NOT extend
   `RevocationScope` locally** — it must change at the INDEX coordination point (§4.2).