feat: W1 batch — config, protocol, ring-buffer, origin, mock-pty (TDD)

Parallel module-builder subagents, disjoint file ownership, shared tree:
- T4 src/config.ts        — loadConfig+M1 origins (32 tests)
- T5 src/protocol.ts      — parse/serialize+SESSION_ID_RE+M7 (60 tests)
- T6 src/session/ring-buffer.ts — byte-accurate, no UTF-8/ANSI split+M2 (15 tests)
- T7 src/http/origin.ts   — host+port match, undefined rejected (12 tests)
- T3 test/helpers/mock-pty.ts — IPty double w/ emitData/emitExit (9 tests)

Verified by orchestrator: tsc --noEmit clean; full suite 128 tests pass.

src/protocol.ts

@@ -0,0 +1,158 @@
+/**
+ * src/protocol.ts — WebSocket message codec + validation (T5, pure functions)
+ *
+ * Invariant #3 (ARCHITECTURE §8): parseClientMessage NEVER throws.
+ * All invalid input flows through ParseResult.ok=false.
+ *
+ * Imports only from src/types.ts (frozen shared contract, T2).
+ */
+
+import type { ClientMessage, ServerMessage, ParseResult } from './types.js'
+
+// ─── SESSION_ID_RE (M7) ───────────────────────────────────────────────────────
+
+/**
+ * UUID v4 pattern.
+ *   - 8-4-4-4-12 hex groups
+ *   - version nibble must be '4'
+ *   - variant nibble must be 8, 9, a, or b  (10xx in binary)
+ *
+ * M7: strings like "abc123" must be rejected; crypto.randomUUID() values must pass.
+ */
+export const SESSION_ID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+// ─── Type whitelist ───────────────────────────────────────────────────────────
+
+const ALLOWED_TYPES = new Set<string>(['attach', 'input', 'resize'])
+
+// ─── parseClientMessage ───────────────────────────────────────────────────────
+
+/**
+ * Parse and validate a raw WS text frame as a ClientMessage.
+ *
+ * Steps (ARCHITECTURE §3.2 / TECH_DOC §5.3):
+ *  1. JSON.parse — bad JSON → ok=false
+ *  2. Must be a plain object (not null, array, etc.)
+ *  3. type must be in whitelist {'attach','input','resize'}
+ *  4. Per-type field validation:
+ *     - resize: cols and rows are integers in [1, 1000]
+ *     - input:  data is a string (passed through verbatim, invariant #9)
+ *     - attach: sessionId is null OR a string matching SESSION_ID_RE (M7)
+ *
+ * NEVER throws — all errors return { ok: false, error: <message> }.
+ */
+export function parseClientMessage(raw: string): ParseResult {
+  // Step 1: JSON parse
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return { ok: false, error: 'invalid JSON' }
+  }
+
+  // Step 2: Must be a plain object
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { ok: false, error: 'message must be a JSON object' }
+  }
+
+  const obj = parsed as Record<string, unknown>
+
+  // Step 3: type whitelist
+  const type = obj['type']
+  if (typeof type !== 'string' || !ALLOWED_TYPES.has(type)) {
+    return { ok: false, error: `unknown or missing type: ${String(type)}` }
+  }
+
+  // Step 4: per-type validation
+  if (type === 'resize') {
+    return validateResize(obj)
+  }
+
+  if (type === 'input') {
+    return validateInput(obj)
+  }
+
+  // type === 'attach'
+  return validateAttach(obj)
+}
+
+// ─── Per-type validators ──────────────────────────────────────────────────────
+
+function validateResize(obj: Record<string, unknown>): ParseResult {
+  const { cols, rows } = obj
+
+  if (!isValidDimension(cols)) {
+    return {
+      ok: false,
+      error: `resize.cols must be an integer in [1, 1000], got ${String(cols)}`,
+    }
+  }
+
+  if (!isValidDimension(rows)) {
+    return {
+      ok: false,
+      error: `resize.rows must be an integer in [1, 1000], got ${String(rows)}`,
+    }
+  }
+
+  return {
+    ok: true,
+    message: { type: 'resize', cols: cols as number, rows: rows as number },
+  }
+}
+
+function isValidDimension(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= 1000
+}
+
+function validateInput(obj: Record<string, unknown>): ParseResult {
+  const { data } = obj
+
+  if (typeof data !== 'string') {
+    return { ok: false, error: `input.data must be a string, got ${typeof data}` }
+  }
+
+  // Invariant #9: data passed through verbatim, no content filtering
+  return { ok: true, message: { type: 'input', data } }
+}
+
+function validateAttach(obj: Record<string, unknown>): ParseResult {
+  const { sessionId } = obj
+
+  // sessionId must be explicitly present as null or a UUID v4 string (M7)
+  if (!Object.prototype.hasOwnProperty.call(obj, 'sessionId')) {
+    return { ok: false, error: 'attach.sessionId field is required' }
+  }
+
+  if (sessionId === null) {
+    return { ok: true, message: { type: 'attach', sessionId: null } }
+  }
+
+  if (typeof sessionId !== 'string') {
+    return {
+      ok: false,
+      error: `attach.sessionId must be null or a UUID v4 string, got ${typeof sessionId}`,
+    }
+  }
+
+  if (!SESSION_ID_RE.test(sessionId)) {
+    return {
+      ok: false,
+      error: `attach.sessionId is not a valid UUID v4: ${sessionId}`,
+    }
+  }
+
+  return { ok: true, message: { type: 'attach', sessionId } }
+}
+
+// ─── serialize ────────────────────────────────────────────────────────────────
+
+/**
+ * Serialize a ServerMessage to a JSON text frame.
+ *
+ * Internal trusted data — JSON.stringify directly (ARCHITECTURE §3.2).
+ */
+export function serialize(msg: ServerMessage): string {
+  return JSON.stringify(msg)
+}