wotann 0.5.0

package/dist/desktop/companion-server.js

@@ -0,0 +1,2147 @@
+/**
+ * Companion Server — secure WebSocket bridge between WOTANN Desktop and iOS app.
+ *
+ * ARCHITECTURE:
+ * - Desktop runs a local WebSocket server (TLS encrypted)
+ * - iOS app connects via WebSocket with mutual authentication
+ * - Pairing uses QR code or manual PIN entry
+ * - All communication is end-to-end encrypted (AES-256-GCM)
+ *
+ * SECURITY MODEL:
+ * 1. First pairing: Desktop generates QR code with one-time PIN + public key
+ * 2. iOS scans QR → sends public key + PIN to server
+ * 3. Server verifies PIN → establishes shared secret via ECDH
+ * 4. All subsequent messages encrypted with derived key
+ * 5. Session tokens with expiry for reconnection without re-pairing
+ *
+ * FEATURES EXPOSED TO iOS:
+ * - Send prompts (text + voice recordings)
+ * - Receive streaming responses
+ * - View conversation history (synced)
+ * - Trigger autonomous tasks
+ * - Receive push notifications on completion
+ * - File sharing (photos from iOS → WOTANN context)
+ * - Quick actions (enhance, arena, cost check)
+ *
+ * PROTOCOL: JSON-RPC over WebSocket
+ * - Client → Server: { method, params, id }
+ * - Server → Client: { result?, error?, id } or { method: "stream", params }
+ */
+import { randomUUID, randomBytes, createHash, createECDH, hkdfSync, timingSafeEqual, } from "node:crypto";
+import { readFileSync, writeFileSync, unlinkSync, existsSync, mkdirSync } from "node:fs";
+import { createServer } from "node:http";
+import { createServer as createSecureServer } from "node:https";
+import { execFileSync, spawn } from "node:child_process";
+import { hostname, networkInterfaces, platform as osPlatform } from "node:os";
+import { join as pathJoin } from "node:path";
+import { resolveWotannHomeSubdir } from "../utils/wotann-home.js";
+import { createSqliteKvStore } from "../utils/sqlite-kv-store.js";
+import { resolveCompanionPort } from "../daemon/port-resolver.js";
+import { WebSocketServer } from "ws";
+import { takeScreenshot, click, moveMouse, drag, scroll, typeText, pressKey, detectPlatform, } from "../computer-use/platform-bindings.js";
+import { ConversationSyncHandler, MobileVoiceHandler, TaskMonitorHandler, QuickActionHandler, FileShareHandler, PushNotificationHandler, WidgetDataHandler, LiveActivityHandler, } from "../mobile/ios-app.js";
+import { SecureAuthManager } from "../mobile/secure-auth.js";
+import { resolveHaptic } from "../mobile/haptic-feedback.js";
+import { isWithinWorkspace } from "../sandbox/security.js";
+/**
+ * GA-11 helper — translate a streaming chunk type into the discriminated
+ * method name iOS subscribes to. Single source of truth so additions or
+ * renames stay in lockstep across every emit site.
+ */
+export function streamMethodForChunkType(chunkType) {
+    switch (chunkType) {
+        case "text":
+            return "stream.text";
+        case "done":
+            return "stream.done";
+        case "error":
+            return "stream.error";
+        case "thinking":
+            return "stream.thinking";
+        case "tool_use":
+            return "stream.tool_use";
+    }
+}
+// ── Pairing Manager ─────────────────────────────────────
+export class PairingManager {
+    devices = new Map();
+    pendingPairings = new Map();
+    sessions = new Map();
+    maxDevices;
+    secureAuth;
+    // Wave 6-KK / H-24 — instance-level SQLite handle (QB #7) so the
+    // paired-devices roster survives daemon restart. Without this, every
+    // restart forces every iOS client to re-pair via QR — UX regression
+    // that the audit flagged. Pending requests + sessions stay in-memory
+    // (the former are short-lived QR challenges; the latter are bound
+    // to live WebSocket connections and have no meaning post-restart).
+    // QB #6: when better-sqlite3 is unavailable, helper warns + we stay
+    // in pure-memory mode (matches pre-Wave-6-KK behavior).
+    persistence;
+    constructor(maxDevices = 3, persistPath) {
+        this.maxDevices = maxDevices;
+        this.secureAuth = new SecureAuthManager();
+        // H-24: rehydrate paired devices from disk. Default to in-memory
+        // (":memory:") when caller doesn't override — bare `new PairingManager()`
+        // (used by tests) gets test-isolated state instead of polluting the
+        // user's real ~/.wotann/companion-devices.db. Production callers
+        // (CompanionServer) MUST pass the explicit home-dir path to opt in
+        // to persistence — see CompanionServer constructor at line ~822.
+        const resolvedPath = persistPath ?? ":memory:";
+        const store = createSqliteKvStore(resolvedPath, "devices");
+        this.persistence = store.usable ? store : null;
+        if (this.persistence) {
+            for (const { value } of this.persistence.loadAll()) {
+                if (value && typeof value === "object" && typeof value.id === "string") {
+                    this.devices.set(value.id, value);
+                }
+            }
+        }
+    }
+    upsertDeviceSession(deviceName, deviceId) {
+        const existingDevice = this.devices.get(deviceId);
+        if (!existingDevice && this.devices.size >= this.maxDevices) {
+            throw new Error(`Maximum ${this.maxDevices} devices allowed`);
+        }
+        const device = {
+            id: deviceId,
+            name: deviceName,
+            platform: "ios",
+            lastSeen: new Date().toISOString(),
+            paired: true,
+            capabilities: ["voice-input", "push-notify", "file-share", "sync-history", "remote-control"],
+        };
+        this.devices.set(deviceId, device);
+        // Wave 6-KK / H-24: mirror pairing into SQLite so the device roster
+        // survives daemon restart. Best-effort — kv-store helper swallows
+        // errors per QB #6.
+        this.persistence?.put(deviceId, device);
+        const existingSession = [...this.sessions.values()].find((session) => session.device.id === deviceId);
+        const sessionId = existingSession?.id ?? randomUUID();
+        this.sessions.set(sessionId, {
+            id: sessionId,
+            device,
+            establishedAt: existingSession?.establishedAt ?? new Date().toISOString(),
+            protocol: "websocket-tls",
+            status: "active",
+            messagesExchanged: existingSession?.messagesExchanged ?? 0,
+        });
+        return { device, sessionId };
+    }
+    /**
+     * Generate a pairing request with a one-time PIN.
+     * Returns a PIN and request ID for QR code generation.
+     */
+    generatePairingRequest() {
+        const pin = randomBytes(3).toString("hex").toUpperCase(); // 6-char hex PIN
+        const requestId = randomUUID();
+        const expiresAt = new Date(Date.now() + 5 * 60_000).toISOString(); // 5 min expiry
+        // Generate real ECDH key pair via SecureAuthManager
+        const keyPair = this.secureAuth.generateKeyPair();
+        this.pendingPairings.set(requestId, {
+            deviceId: "",
+            deviceName: "",
+            platform: "ios",
+            publicKey: keyPair.publicKey,
+            pin,
+            timestamp: new Date().toISOString(),
+            expiresAt,
+        });
+        return { pin, requestId, expiresAt, publicKey: keyPair.publicKey };
+    }
+    /**
+     * Complete pairing from iOS device.
+     * Verifies PIN via SecureAuthManager's real ECDH exchange and registers the device.
+     */
+    completePairing(requestId, pin, deviceName, deviceId, devicePublicKey) {
+        const request = this.pendingPairings.get(requestId);
+        if (!request) {
+            return { success: false, error: "Invalid or expired pairing request" };
+        }
+        if (new Date(request.expiresAt) < new Date()) {
+            this.pendingPairings.delete(requestId);
+            return { success: false, error: "Pairing request expired" };
+        }
+        // SECURITY (SB-2): constant-time PIN comparison via crypto.timingSafeEqual.
+        // Previous code used `pin !== request.pin` and falsely claimed constant-time
+        // in the comment — string `!==` short-circuits on the first byte mismatch and
+        // leaks PIN bytes via timing. timingSafeEqual requires equal-length buffers,
+        // so we length-check first and reject mismatched lengths as invalid.
+        if (!pin || typeof pin !== "string") {
+            return { success: false, error: "Invalid PIN" };
+        }
+        const providedPinBuf = Buffer.from(pin, "utf8");
+        const expectedPinBuf = Buffer.from(request.pin, "utf8");
+        if (providedPinBuf.length !== expectedPinBuf.length ||
+            !timingSafeEqual(providedPinBuf, expectedPinBuf)) {
+            return { success: false, error: "Invalid PIN" };
+        }
+        // Use SecureAuthManager for real ECDH pairing when device provides a public key
+        if (devicePublicKey && request.publicKey) {
+            const pairingResult = this.secureAuth.verifyPairing({
+                deviceId,
+                deviceName,
+                devicePublicKey,
+                pin: request.pin,
+                requestId,
+            });
+            if (!pairingResult.success) {
+                return { success: false, error: "ECDH key exchange failed" };
+            }
+        }
+        const { sessionId } = this.upsertDeviceSession(deviceName, deviceId);
+        this.pendingPairings.delete(requestId);
+        return { success: true, sessionId };
+    }
+    /**
+     * Complete a local-network (Bonjour/manual) pairing.
+     *
+     * SECURITY (SB-1): Previously this method accepted any deviceName/deviceId
+     * with no authentication and minted a 24-hour auth token — a trivial LAN
+     * takeover. Any process on the same network could call `pair.local` with
+     * arbitrary parameters and obtain a token.
+     *
+     * The fixed flow requires the caller to first obtain a `requestId`/`pin`
+     * pair from `generatePairingRequest()` (the same pending-request store the
+     * QR-code `pair` flow uses) and present BOTH the requestId AND the PIN.
+     * The PIN is verified via crypto.timingSafeEqual to defeat timing leaks.
+     *
+     * Without these two values local pairing is rejected. The pre-shared PIN
+     * is broadcast out-of-band via Bonjour TXT records or shown in the desktop
+     * UI for manual entry — same channel as the QR pair flow.
+     */
+    completeLocalPairing(requestId, pin, deviceName, deviceId) {
+        // Reject empty/non-string inputs early (fail-CLOSED, QB#6).
+        if (!requestId || typeof requestId !== "string") {
+            return { success: false, error: "Local pairing requires a valid requestId" };
+        }
+        if (!pin || typeof pin !== "string") {
+            return { success: false, error: "Local pairing requires a valid PIN" };
+        }
+        if (!deviceName || typeof deviceName !== "string") {
+            return { success: false, error: "Local pairing requires a deviceName" };
+        }
+        if (!deviceId || typeof deviceId !== "string") {
+            return { success: false, error: "Local pairing requires a deviceId" };
+        }
+        const request = this.pendingPairings.get(requestId);
+        if (!request) {
+            return { success: false, error: "Invalid or expired pairing request" };
+        }
+        if (new Date(request.expiresAt) < new Date()) {
+            this.pendingPairings.delete(requestId);
+            return { success: false, error: "Pairing request expired" };
+        }
+        // SECURITY (SB-2): constant-time PIN comparison.
+        const providedPinBuf = Buffer.from(pin, "utf8");
+        const expectedPinBuf = Buffer.from(request.pin, "utf8");
+        if (providedPinBuf.length !== expectedPinBuf.length ||
+            !timingSafeEqual(providedPinBuf, expectedPinBuf)) {
+            return { success: false, error: "Invalid PIN" };
+        }
+        try {
+            const { sessionId } = this.upsertDeviceSession(deviceName, deviceId);
+            this.pendingPairings.delete(requestId);
+            return { success: true, sessionId };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : "Failed to register local pairing",
+            };
+        }
+    }
+    /**
+     * Remove a paired device.
+     */
+    unpairDevice(deviceId) {
+        const removed = this.devices.delete(deviceId);
+        // Wave 6-KK / H-24: also drop persisted row.
+        this.persistence?.delete(deviceId);
+        // Also remove associated sessions
+        for (const [sessionId, session] of this.sessions) {
+            if (session.device.id === deviceId) {
+                this.sessions.delete(sessionId);
+            }
+        }
+        return removed;
+    }
+    /**
+     * Get all paired devices.
+     */
+    getPairedDevices() {
+        return [...this.devices.values()];
+    }
+    /**
+     * Get active sessions.
+     */
+    getActiveSessions() {
+        return [...this.sessions.values()].filter((s) => s.status === "active");
+    }
+    endSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return false;
+        }
+        this.sessions.set(sessionId, {
+            ...session,
+            status: "disconnected",
+        });
+        return true;
+    }
+    /**
+     * Validate a session token.
+     */
+    validateSession(sessionId) {
+        return this.sessions.get(sessionId) ?? null;
+    }
+    /**
+     * Update device last-seen timestamp.
+     */
+    touchDevice(deviceId) {
+        const device = this.devices.get(deviceId);
+        if (device) {
+            const updated = { ...device, lastSeen: new Date().toISOString() };
+            this.devices.set(deviceId, updated);
+            // Wave 6-KK / H-24: mirror lastSeen so doctor / diagnostics can
+            // reason about device staleness even after a daemon restart.
+            this.persistence?.put(deviceId, updated);
+        }
+    }
+    /**
+     * Generate QR code data for pairing.
+     * Format: wotann://pair?id=<requestId>&pin=<pin>&host=<host>&port=<port>
+     */
+    generateQRData(requestId, pin, host, port) {
+        return `wotann://pair?id=${requestId}&pin=${pin}&host=${host}&port=${port}`;
+    }
+}
+// ── RPC Handler ─────────────────────────────────────────
+export class CompanionRPCHandler {
+    handlers = new Map();
+    /**
+     * Register a handler for an RPC method.
+     */
+    register(method, handler) {
+        this.handlers.set(method, handler);
+    }
+    has(method) {
+        return this.handlers.has(method);
+    }
+    /**
+     * Process an incoming RPC message.
+     */
+    async handle(message) {
+        const handler = this.handlers.get(message.method);
+        if (!handler) {
+            return {
+                error: { code: -32601, message: `Method not found: ${message.method}` },
+                id: message.id,
+            };
+        }
+        try {
+            const result = await handler(message.params);
+            return { result, id: message.id };
+        }
+        catch (error) {
+            return {
+                error: {
+                    code: -32000,
+                    message: error instanceof Error ? error.message : "Internal error",
+                },
+                id: message.id,
+            };
+        }
+    }
+    /**
+     * List registered methods.
+     */
+    getMethods() {
+        return [...this.handlers.keys()];
+    }
+}
+/**
+ * Methods that DO NOT require an authToken. These are either bootstrapping
+ * (to obtain a token in the first place), health-check, or the ECDH key
+ * exchange that establishes an encrypted channel before pairing.
+ */
+export const AUTH_EXEMPT_METHODS = new Set([
+    "pair",
+    "pair.local",
+    "security.keyExchange",
+    "ping",
+]);
+export class AuthTokenStore {
+    tokens = new Map();
+    sessionTimeoutMs;
+    constructor(sessionTimeoutMs = 24 * 60 * 60_000) {
+        this.sessionTimeoutMs = sessionTimeoutMs;
+    }
+    /**
+     * Issue a new 32-byte (64 hex char) random token for the given session/device.
+     * Returns the token string. The caller should embed it in the pairing response
+     * so the client can include it on all subsequent RPC calls.
+     */
+    issue(sessionId, deviceId) {
+        const token = randomBytes(32).toString("hex");
+        const now = Date.now();
+        this.tokens.set(token, {
+            token,
+            sessionId,
+            deviceId,
+            issuedAt: now,
+            expiresAt: now + this.sessionTimeoutMs,
+        });
+        return token;
+    }
+    /**
+     * Validate a token. Returns the associated record if valid and unexpired,
+     * otherwise null. Expired tokens are evicted from the store on access.
+     */
+    validate(token) {
+        if (!token || typeof token !== "string")
+            return null;
+        const record = this.tokens.get(token);
+        if (!record)
+            return null;
+        if (Date.now() > record.expiresAt) {
+            this.tokens.delete(token);
+            return null;
+        }
+        return record;
+    }
+    /** Revoke a specific token (e.g. on unpair). */
+    revoke(token) {
+        return this.tokens.delete(token);
+    }
+    /** Revoke all tokens for a given device (e.g. on unpair by deviceId). */
+    revokeForDevice(deviceId) {
+        let count = 0;
+        for (const [tok, rec] of this.tokens) {
+            if (rec.deviceId === deviceId) {
+                this.tokens.delete(tok);
+                count++;
+            }
+        }
+        return count;
+    }
+    /** For tests / observability: snapshot of active tokens (never expose in real responses). */
+    size() {
+        return this.tokens.size;
+    }
+}
+/**
+ * requireAuth — shared helper for auth-gated RPC methods.
+ *
+ * Extracts `authToken` from the params object, validates it against the given
+ * token store, and throws a standardized error when the token is missing or
+ * invalid. The RPC handler framework converts thrown errors into a well-formed
+ * JSON-RPC error response, which translates to `{ ok: false, error: "unauthorized" }`
+ * at the client.
+ *
+ * Returns the validated record so downstream handlers can use the deviceId or
+ * sessionId bound to the token.
+ */
+export function requireAuth(params, store) {
+    const token = typeof params["authToken"] === "string" ? params["authToken"] : "";
+    const record = store.validate(token);
+    if (!record) {
+        // Thrown message is mapped to `{ error: { ... , message: "unauthorized" } }`
+        // by the RPC framework; the iOS client checks for `error.message === "unauthorized"`.
+        throw new Error("unauthorized");
+    }
+    return record;
+}
+// ── Companion Server ────────────────────────────────────
+export class CompanionServer {
+    config;
+    pairingManager;
+    rpcHandler;
+    secureAuth;
+    conversationSync;
+    mobileVoice;
+    taskMonitor;
+    quickAction;
+    fileShare;
+    pushNotification;
+    widgetData;
+    liveActivity;
+    httpServer = null;
+    wsServer = null;
+    connectedClients = new Set();
+    running = false;
+    runtime = null;
+    bridgeRpcHandler = null;
+    /** Per-device AES-256 symmetric keys derived from ECDH key exchange. */
+    deviceEncryptionKeys = new Map();
+    /** Session auth tokens — issued on successful pairing, required on all other RPC calls. */
+    authTokens;
+    /**
+     * SECURITY (SB-1): Per-WS-client source IP, captured at HTTP upgrade.
+     * Used by the pair.local handler to apply per-source-IP rate limiting.
+     * WeakMap so entries are GC'd when the ws client is dropped.
+     */
+    clientAddresses = new WeakMap();
+    /**
+     * SECURITY (SB-1): Per-source-IP pair.local attempt timestamps (ms epoch),
+     * pruned to the last 60s window on each lookup. Per-instance state (QB#7);
+     * a separate CompanionServer instance gets its own limiter, so test
+     * harnesses and parallel daemons do not share quota.
+     */
+    pairLocalAttempts = new Map();
+    /** Per-instance audit log for pair.local attempts (success + failure). */
+    pairLocalAuditLog = [];
+    /**
+     * SECURITY (SB-4): Per-instance audit log for WebSocket Origin-check
+     * decisions (CSWSH protection). Bounded to 256 entries. QB#7: per-instance
+     * (not module-global) so concurrent test daemons do not share state.
+     */
+    wsOriginAuditLog = [];
+    constructor(config) {
+        // SECURITY (SB-3): default to loopback-only to prevent the companion
+        // server from being reachable on every network interface (incl. public
+        // Wi-Fi / hotel networks). The composite SB-1+SB-3+SB-9 attack chain
+        // is `browser-tab → host RCE`; closing the public bind shuts the front
+        // door. Opt-in to LAN binding via `WOTANN_COMPANION_HOST` for the
+        // legitimate phone-discovery use case (handled below). Explicit
+        // `config.host` still wins for tests and embedded callers.
+        const envHost = (process.env.WOTANN_COMPANION_HOST ?? "").trim().toLowerCase();
+        const envBindAll = envHost === "0.0.0.0" || envHost === "::" || envHost === "lan" || envHost === "all";
+        const envExplicitHost = envHost.length > 0 && !envBindAll && envHost !== "127.0.0.1" && envHost !== "localhost"
+            ? envHost
+            : undefined;
+        const envResolvedHost = envBindAll ? "0.0.0.0" : (envExplicitHost ?? "127.0.0.1");
+        // Wave A2: per-worktree port resolution defeats collisions between
+        // parallel daemons. `WOTANN_COMPANION_PORT` env var still wins;
+        // falls back to a deterministic hash of cwd (3849-3949 range).
+        this.config = {
+            port: resolveCompanionPort(),
+            host: envResolvedHost,
+            maxDevices: 3,
+            sessionTimeoutMs: 24 * 60 * 60_000, // 24 hours
+            enableTLS: true,
+            ...config,
+        };
+        // QB#6: clear, non-silent logging of which host is bound. The LAN-bind
+        // case is loud ("WARNING: bound to all interfaces…") so operators on a
+        // public network notice immediately if WOTANN_COMPANION_HOST leaked in.
+        if (this.config.host === "0.0.0.0" || this.config.host === "::") {
+            console.warn(`[CompanionServer] WARNING: binding to all interfaces (${this.config.host}). ` +
+                `WebSocket reachable from every network this host is on. ` +
+                `Unset WOTANN_COMPANION_HOST or set to "127.0.0.1" to restrict to loopback.`);
+        }
+        else {
+            console.log(`[CompanionServer] bound to ${this.config.host} (loopback-only by default; ` +
+                `set WOTANN_COMPANION_HOST=lan to enable LAN phone discovery).`);
+        }
+        // Wave 6-KK + integrator fix: pass explicit home-dir path so
+        // production gets persistent paired-devices state. Bare
+        // `new PairingManager()` (used by tests) defaults to ":memory:" so
+        // test instances stay isolated from the user's real DB.
+        this.pairingManager = new PairingManager(this.config.maxDevices, resolveWotannHomeSubdir("companion-devices.db"));
+        this.rpcHandler = new CompanionRPCHandler();
+        this.secureAuth = new SecureAuthManager(this.config.sessionTimeoutMs);
+        this.authTokens = new AuthTokenStore(this.config.sessionTimeoutMs);
+        this.conversationSync = new ConversationSyncHandler();
+        this.mobileVoice = new MobileVoiceHandler();
+        this.taskMonitor = new TaskMonitorHandler();
+        this.quickAction = new QuickActionHandler();
+        this.fileShare = new FileShareHandler();
+        this.pushNotification = new PushNotificationHandler();
+        this.widgetData = new WidgetDataHandler();
+        this.liveActivity = new LiveActivityHandler();
+        this.registerDefaultHandlers();
+    }
+    /**
+     * Start the companion server with a real WebSocket server.
+     * Creates an HTTP server and attaches WebSocket handling via the `ws` package.
+     * Incoming WebSocket messages are parsed as JSON-RPC and dispatched through
+     * the RPC handler. Responses include haptic pattern metadata for iOS clients.
+     */
+    start() {
+        this.running = true;
+        // Create HTTP(S) server for WebSocket upgrade
+        if (this.config.enableTLS && this.config.certPath && this.config.keyPath) {
+            try {
+                if (existsSync(this.config.certPath) && existsSync(this.config.keyPath)) {
+                    const cert = readFileSync(this.config.certPath);
+                    const key = readFileSync(this.config.keyPath);
+                    this.httpServer = createSecureServer({ cert, key });
+                }
+                else {
+                    // Cert/key files not found — fall back to plain HTTP
+                    this.httpServer = createServer();
+                }
+            }
+            catch {
+                // Failed to read cert/key — fall back to plain HTTP
+                this.httpServer = createServer();
+            }
+        }
+        else {
+            this.httpServer = createServer();
+        }
+        try {
+            // SECURITY (SB-4): CSWSH protection. Without `verifyClient` the `ws`
+            // package upgrades any incoming WebSocket regardless of Origin, which
+            // means any HTTP page the user visits in a regular browser tab can
+            // open `new WebSocket("ws://localhost:3849")` and ride the user's
+            // ambient host trust to issue commands (composes with SB-1 to drive
+            // keyboard/mouse). Reject any cross-origin upgrade unless the Origin
+            // is on a small allowlist (Tauri webview, custom scheme, dev-server
+            // localhost). QB#7: closure captures `this` for per-instance audit.
+            const verifyOrigin = (info, cb) => {
+                const rawOrigin = typeof info.origin === "string" ? info.origin : "";
+                const sourceIp = info.req?.socket?.remoteAddress ?? "unknown";
+                // Empty Origin: native client (iOS app, CLI, Tauri runtime). Allow.
+                // Browsers always send Origin on cross-origin WS upgrade requests,
+                // so an absent header is a strong "not a hostile browser tab" signal.
+                if (rawOrigin.length === 0) {
+                    this.logWsOriginAttempt(rawOrigin, sourceIp, "accepted");
+                    cb(true);
+                    return;
+                }
+                const allowed = rawOrigin === "wotann://" ||
+                    rawOrigin.startsWith("wotann://") ||
+                    rawOrigin === "file://" ||
+                    rawOrigin.startsWith("file://") ||
+                    rawOrigin === "tauri://localhost" ||
+                    rawOrigin.startsWith("tauri://") ||
+                    /^https?:\/\/localhost(?::\d+)?$/.test(rawOrigin) ||
+                    /^https?:\/\/127\.0\.0\.1(?::\d+)?$/.test(rawOrigin) ||
+                    /^https?:\/\/\[::1\](?::\d+)?$/.test(rawOrigin);
+                if (allowed) {
+                    this.logWsOriginAttempt(rawOrigin, sourceIp, "accepted");
+                    cb(true);
+                    return;
+                }
+                // Cross-origin from a real browser. This is the CSWSH attempt
+                // (e.g. `http://attacker.example.com`). Reject with HTTP 403.
+                this.logWsOriginAttempt(rawOrigin, sourceIp, "rejected_cross_origin");
+                cb(false, 403, "Forbidden: cross-origin WebSocket rejected");
+            };
+            // SECURITY (SB-4): pass `verifyClient` to enable the CSWSH guard.
+            // The `ws` package's `ServerOptions` type is namespaced inside the
+            // module-level CJS `export = WebSocket` declaration, which TypeScript
+            // cannot re-import as a value-position type via ESM syntax in this
+            // codebase's import style. The cast below is safe because the runtime
+            // option name `verifyClient` is part of the documented public API
+            // (https://github.com/websockets/ws/blob/master/doc/ws.md#new-websocketserveroptions-callback).
+            const wssOptions = {
+                server: this.httpServer,
+                verifyClient: verifyOrigin,
+            };
+            const wss = new WebSocketServer(wssOptions);
+            this.wsServer = wss;
+            // Wave 4-AA: server-level 'error' handler — without this an EADDRINUSE
+            // or socket-layer fault on the WebSocketServer would emit an
+            // unhandled 'error' event and crash the Node process. Log instead.
+            wss.on("error", (...errArgs) => {
+                const err = errArgs[0];
+                const msg = err instanceof Error ? err.message : String(err);
+                console.warn(`[CompanionServer] WSServer error: ${msg}`);
+            });
+            wss.on("connection", (...args) => {
+                const ws = args[0];
+                // SECURITY (SB-1): capture the source IP from the HTTP upgrade
+                // request so pair.local can rate-limit per-source. The `ws` package
+                // emits `(ws, request)` on its connection event; req.socket.remoteAddress
+                // is the connecting peer's IP. Defaults to "unknown" when the upgrade
+                // request shape is unexpected — rate limiter coalesces all "unknown"
+                // sources into a single bucket, fail-CLOSED.
+                const upgradeReq = args[1];
+                const sourceIp = upgradeReq?.socket?.remoteAddress && typeof upgradeReq.socket.remoteAddress === "string"
+                    ? upgradeReq.socket.remoteAddress
+                    : "unknown";
+                this.clientAddresses.set(ws, sourceIp);
+                this.connectedClients.add(ws);
+                // Wave 4-AA: per-connection 'error' handler. WebSocket emits 'error'
+                // on protocol violations, frame errors, or socket failures. Without
+                // a listener, Node treats it as unhandled and crashes the daemon.
+                // Log + drop the client silently so other peers stay live.
+                ws.on("error", (...errArgs) => {
+                    const err = errArgs[0];
+                    const msg = err instanceof Error ? err.message : String(err);
+                    console.warn(`[CompanionServer] WS error: ${msg}`);
+                    this.connectedClients.delete(ws);
+                });
+                ws.on("message", (...msgArgs) => {
+                    const data = msgArgs[0];
+                    const raw = typeof data === "string"
+                        ? data
+                        : Buffer.isBuffer(data)
+                            ? data.toString("utf-8")
+                            : String(data);
+                    this.handleWebSocketMessage(ws, raw).catch(() => {
+                        // Best-effort error handling for malformed messages
+                    });
+                });
+                ws.on("close", () => {
+                    this.connectedClients.delete(ws);
+                });
+            });
+        }
+        catch {
+            // ws package not available — server runs in HTTP-only mode
+        }
+        // A8: surface port conflicts instead of swallowing them. Try up to 3
+        // alternate ports (base+1..3) so running a second instance during dev
+        // doesn't permanently wedge pairing.
+        const server = this.httpServer;
+        if (server) {
+            const tryListen = (port, attemptsLeft) => {
+                server.once("error", (err) => {
+                    if (err.code === "EADDRINUSE") {
+                        if (attemptsLeft > 0) {
+                            const nextPort = port + 1;
+                            console.error(`[companion-server] port ${port} in use; retrying on ${nextPort}`);
+                            this.config.port = nextPort;
+                            tryListen(nextPort, attemptsLeft - 1);
+                        }
+                        else {
+                            this.running = false;
+                            console.error(`[companion-server] could not bind any port in range ${this.config.port}..${port}. ` +
+                                `Is another WOTANN daemon running? Set WOTANN_COMPANION_PORT to override.`);
+                            server.emit("wotann-bind-failed", { port, attempts: 3 });
+                        }
+                    }
+                });
+                server.listen(port, this.config.host);
+            };
+            tryListen(this.config.port, 3);
+        }
+        // Kill any orphaned Bonjour advertisement from a previous crash
+        const bonjourPidPath = resolveWotannHomeSubdir("bonjour.pid");
+        try {
+            const oldPid = parseInt(readFileSync(bonjourPidPath, "utf-8").trim(), 10);
+            if (oldPid > 0) {
+                try {
+                    process.kill(oldPid, "SIGTERM");
+                }
+                catch {
+                    /* already dead */
+                }
+                unlinkSync(bonjourPidPath);
+            }
+        }
+        catch {
+            /* no pidfile or read error */
+        }
+        // Advertise via Bonjour/mDNS so iOS can discover us on the local network
+        this.advertiseBonjourService();
+        return { port: this.config.port, host: this.getAdvertisedHost() };
+    }
+    /**
+     * Advertise the companion server as a Bonjour/mDNS service (_wotann._tcp)
+     * so the iOS app can discover it via BonjourDiscovery.
+     *
+     * H-29: previously macOS-only via `dns-sd`. iOS↔Desktop pairing silently
+     * died on Linux hosts because Avahi (the Linux mDNS responder) was never
+     * attempted. Now:
+     *   - macOS: dns-sd (built-in, zero deps)
+     *   - Linux: avahi-publish-service (from avahi-utils)
+     *   - Windows / no advertiser available: skip with a clear warning;
+     *     manual pairing via PIN still works (no crash).
+     *
+     * Both `dns-sd` and `avahi-publish-service` block in the foreground while
+     * the service is registered, so we spawn detached and unref.
+     */
+    advertiseBonjourService() {
+        const serviceName = `WOTANN (${hostname()})`;
+        const serviceType = "_wotann._tcp";
+        const port = String(this.config.port);
+        const os = osPlatform();
+        let proc = null;
+        let advertiser = "";
+        if (os === "darwin") {
+            try {
+                // dns-sd is built into macOS — no npm package needed.
+                proc = spawn("dns-sd", ["-R", serviceName, serviceType, "local", port], {
+                    stdio: "ignore",
+                    detached: true,
+                });
+                advertiser = "dns-sd";
+            }
+            catch {
+                proc = null;
+            }
+        }
+        else if (os === "linux") {
+            // Avahi: avahi-publish-service NAME TYPE PORT [TXT...] — foreground
+            // process; we detach so it survives daemon parent. Package is
+            // typically `avahi-utils` (Debian/Ubuntu) or `avahi` (Arch/Fedora).
+            try {
+                proc = spawn("avahi-publish-service", [serviceName, serviceType, port], {
+                    stdio: "ignore",
+                    detached: true,
+                });
+                advertiser = "avahi-publish-service";
+            }
+            catch {
+                proc = null;
+            }
+        }
+        // Other platforms (win32, etc.) intentionally fall through — no widely-
+        // available CLI mDNS responder exists out-of-the-box.
+        if (!proc) {
+            const tried = os === "darwin" ? "dns-sd" : os === "linux" ? "avahi-publish-service" : "(none)";
+            console.warn(`[CompanionServer] no mDNS advertiser available on ${os} (tried: ${tried}); iOS auto-discovery disabled. Manual PIN pairing still works.`);
+            return;
+        }
+        // The spawn syscall succeeded but the binary may not exist on PATH —
+        // node will then emit an 'error' event asynchronously. Catch it so an
+        // unhandled error does not crash the daemon, AND clear the proc ref
+        // so cleanup logic in stop() does not try to kill a non-existent pid.
+        proc.on("error", (err) => {
+            const reason = err.code === "ENOENT" ? `${advertiser} not installed` : err.message;
+            console.warn(`[CompanionServer] mDNS advertiser failed (${reason}); iOS auto-discovery disabled. Manual PIN pairing still works.`);
+            this._bonjourProc = undefined;
+        });
+        proc.unref(); // Don't block daemon shutdown
+        // Store reference for cleanup
+        this._bonjourProc = proc;
+        // Write PID for orphan cleanup on restart
+        const pidPath = resolveWotannHomeSubdir("bonjour.pid");
+        if (proc.pid) {
+            try {
+                writeFileSync(pidPath, String(proc.pid));
+            }
+            catch {
+                /* ignore write errors */
+            }
+        }
+    }
+    stop() {
+        this.running = false;
+        for (const client of this.connectedClients) {
+            // Wave 4-AA: per-client close wrapped — a peer that has already
+            // disconnected can throw on close(), and one bad socket must not
+            // leave the rest of the set un-closed.
+            try {
+                client.close?.();
+            }
+            catch {
+                /* per-client close failure is non-fatal during shutdown */
+            }
+        }
+        this.connectedClients.clear();
+        if (this.httpServer) {
+            this.httpServer.close();
+            this.httpServer = null;
+        }
+        this.wsServer = null;
+        // Kill Bonjour advertisement.
+        // CI runners restrict process.kill on subprocesses they didn't spawn,
+        // so swallow EPERM/ESRCH instead of letting it propagate.
+        const bonjourProc = this._bonjourProc;
+        try {
+            bonjourProc?.kill?.();
+        }
+        catch {
+            /* sandbox/CI may forbid kill() — non-fatal */
+        }
+    }
+    isRunning() {
+        return this.running;
+    }
+    /**
+     * Set the WotannRuntime instance for real query routing.
+     * When set, RPC handlers like `sync.send` and `enhance` call the real runtime.
+     *
+     * Session-10 audit fix: TaskMonitorHandler was constructed at line 606 with
+     * no `executeTask` callback, so iOS autonomous tasks dispatched via iOS
+     * Autopilot/Workshop/CarPlay stayed `status:"running"` forever (iOS call
+     * was non-blocking and no producer ever wrote a completion). We now bind
+     * a real `executeTask` callback that streams through the runtime's query
+     * pipeline — tasks resolve with { success, result } when the underlying
+     * stream ends, or { success:false, result:"error…" } on exception.
+     */
+    setRuntime(runtime) {
+        this.runtime = runtime;
+        this.taskMonitor = new TaskMonitorHandler(async (prompt) => {
+            try {
+                let collected = "";
+                for await (const chunk of runtime.query({ prompt })) {
+                    if (typeof chunk === "string")
+                        collected += chunk;
+                    else if (chunk && typeof chunk === "object" && "content" in chunk) {
+                        const c = chunk.content;
+                        if (typeof c === "string")
+                            collected += c;
+                    }
+                }
+                return { success: true, result: collected };
+            }
+            catch (err) {
+                return { success: false, result: err instanceof Error ? err.message : String(err) };
+            }
+        });
+    }
+    setBridgeRPCHandler(handler) {
+        this.bridgeRpcHandler = handler;
+    }
+    /**
+     * Get the attached runtime (null if not connected).
+     */
+    getRuntime() {
+        return this.runtime;
+    }
+    getPairingManager() {
+        return this.pairingManager;
+    }
+    getRPCHandler() {
+        return this.rpcHandler;
+    }
+    getAdvertisedHost() {
+        if (this.config.host !== "0.0.0.0" && this.config.host !== "::") {
+            return this.config.host;
+        }
+        const nets = networkInterfaces();
+        for (const addresses of Object.values(nets)) {
+            for (const entry of addresses ?? []) {
+                if (entry.family !== "IPv4" || entry.internal || entry.address.startsWith("169.254.")) {
+                    continue;
+                }
+                return entry.address;
+            }
+        }
+        return hostname();
+    }
+    /**
+     * Generate a pairing QR code for iOS app connection.
+     */
+    generatePairingQR() {
+        const { pin, requestId, expiresAt } = this.pairingManager.generatePairingRequest();
+        const host = this.getAdvertisedHost();
+        const qrData = this.pairingManager.generateQRData(requestId, pin, host, this.config.port);
+        return { qrData, pin, expiresAt, host, port: this.config.port };
+    }
+    getConversationSync() {
+        return this.conversationSync;
+    }
+    getMobileVoice() {
+        return this.mobileVoice;
+    }
+    getTaskMonitor() {
+        return this.taskMonitor;
+    }
+    getQuickAction() {
+        return this.quickAction;
+    }
+    getFileShare() {
+        return this.fileShare;
+    }
+    getPushNotification() {
+        return this.pushNotification;
+    }
+    getWidgetData() {
+        return this.widgetData;
+    }
+    getLiveActivity() {
+        return this.liveActivity;
+    }
+    getSecureAuth() {
+        return this.secureAuth;
+    }
+    /** Access to the auth-token store (used by tests and admin endpoints). */
+    getAuthTokens() {
+        return this.authTokens;
+    }
+    /** Store a derived AES-256 key for a device after successful ECDH exchange. */
+    storeDeviceEncryptionKey(deviceId, key) {
+        this.deviceEncryptionKeys.set(deviceId, key);
+    }
+    /** Retrieve the encryption key for a device. Returns undefined if no key exchange has occurred. */
+    getDeviceEncryptionKey(deviceId) {
+        return this.deviceEncryptionKeys.get(deviceId);
+    }
+    /**
+     * SECURITY (SB-1): per-source-IP rate limiter for `pair.local`.
+     * Allows up to PAIR_LOCAL_MAX_PER_WINDOW attempts per source IP per
+     * PAIR_LOCAL_WINDOW_MS. Returns true when the attempt is admitted (and
+     * records the timestamp); false when the source has exhausted its quota.
+     *
+     * Per-instance state (QB#7); two CompanionServer instances do not share
+     * quota. Pruning happens lazily on lookup so a long-idle source's history
+     * is reaped without a background timer.
+     */
+    static PAIR_LOCAL_MAX_PER_WINDOW = 5;
+    static PAIR_LOCAL_WINDOW_MS = 60_000;
+    checkPairLocalRateLimit(sourceIp) {
+        const now = Date.now();
+        const cutoff = now - CompanionServer.PAIR_LOCAL_WINDOW_MS;
+        const history = this.pairLocalAttempts.get(sourceIp) ?? [];
+        // Prune entries older than the window.
+        const fresh = history.filter((ts) => ts > cutoff);
+        if (fresh.length >= CompanionServer.PAIR_LOCAL_MAX_PER_WINDOW) {
+            // Update the pruned (but at-quota) history so future checks stay accurate.
+            this.pairLocalAttempts.set(sourceIp, fresh);
+            return false;
+        }
+        fresh.push(now);
+        this.pairLocalAttempts.set(sourceIp, fresh);
+        return true;
+    }
+    /**
+     * SECURITY (SB-1): record a pair.local attempt to the per-instance audit log.
+     * Bounded to the most recent 256 entries to defeat memory exhaustion.
+     */
+    logPairLocalAttempt(sourceIp, deviceId, outcome) {
+        this.pairLocalAuditLog.push({ ts: Date.now(), sourceIp, deviceId, outcome });
+        if (this.pairLocalAuditLog.length > 256) {
+            this.pairLocalAuditLog.splice(0, this.pairLocalAuditLog.length - 256);
+        }
+        // Also surface to console for operators tailing logs. Failure cases warn;
+        // successes log at info-level.
+        const line = `[CompanionServer] pair.local ${outcome} src=${sourceIp} device=${deviceId}`;
+        if (outcome === "ok") {
+            console.log(line);
+        }
+        else {
+            console.warn(line);
+        }
+    }
+    /**
+     * Read-only view of the pair.local audit log (for tests and observability).
+     */
+    getPairLocalAuditLog() {
+        return this.pairLocalAuditLog;
+    }
+    /**
+     * SECURITY (SB-4): record a WebSocket Origin-check decision to the
+     * per-instance CSWSH audit log. Bounded to 256 entries. Surfaces all
+     * rejections to the operator console via warn (QB#6) so a sudden burst
+     * of cross-origin attempts is visible without parsing the audit log.
+     */
+    logWsOriginAttempt(origin, sourceIp, outcome) {
+        this.wsOriginAuditLog.push({ ts: Date.now(), origin, sourceIp, outcome });
+        if (this.wsOriginAuditLog.length > 256) {
+            this.wsOriginAuditLog.splice(0, this.wsOriginAuditLog.length - 256);
+        }
+        if (outcome === "rejected_cross_origin") {
+            console.warn(`[CompanionServer] WS upgrade REJECTED (CSWSH guard): origin=${origin || "<empty>"} src=${sourceIp}`);
+        }
+    }
+    /**
+     * Read-only view of the WebSocket Origin-check audit log (for tests and
+     * observability). Each entry records a single upgrade-attempt decision.
+     */
+    getWsOriginAuditLog() {
+        return this.wsOriginAuditLog;
+    }
+    /**
+     * SECURITY (SB-1): handle pair.local with PIN verification, per-IP rate
+     * limiting, and audit logging. The previous implementation was an
+     * unauthenticated LAN takeover vector — any process on the network could
+     * mint a 24-hour auth token by calling pair.local with arbitrary device
+     * params. The fixed flow requires a pre-shared PIN issued by
+     * generatePairingRequest() (same store as the QR code `pair` flow).
+     */
+    async handlePairLocal(ws, parsed) {
+        const sourceIp = this.clientAddresses.get(ws) ?? "unknown";
+        const params = parsed.params ?? {};
+        const requestId = typeof params["requestId"] === "string" ? params["requestId"] : "";
+        const pin = typeof params["pin"] === "string" ? params["pin"] : "";
+        const deviceName = typeof params["deviceName"] === "string" ? params["deviceName"] : "";
+        const deviceId = typeof params["deviceId"] === "string" ? params["deviceId"] : "";
+        // Per-IP rate limit FIRST so an attacker burning CPU on completePairing
+        // does not get to amortize their cost across the limiter check.
+        if (!this.checkPairLocalRateLimit(sourceIp)) {
+            this.logPairLocalAttempt(sourceIp, deviceId || "<missing>", "rate_limited");
+            return {
+                result: {
+                    success: false,
+                    error: "Rate limit exceeded for pair.local from this source",
+                },
+                error: { code: -32002, message: "rate_limited" },
+                id: parsed.id,
+            };
+        }
+        // Argument shape check.
+        if (!requestId || !pin || !deviceName || !deviceId) {
+            this.logPairLocalAttempt(sourceIp, deviceId || "<missing>", "missing_args");
+            return {
+                result: {
+                    success: false,
+                    error: "pair.local requires requestId, pin, deviceName, and deviceId",
+                },
+                error: { code: -32602, message: "invalid_params" },
+                id: parsed.id,
+            };
+        }
+        const result = this.pairingManager.completeLocalPairing(requestId, pin, deviceName, deviceId);
+        if (result.success && result.sessionId) {
+            const authToken = this.authTokens.issue(result.sessionId, deviceId);
+            this.logPairLocalAttempt(sourceIp, deviceId, "ok");
+            return { result: { ...result, authToken }, id: parsed.id };
+        }
+        // Map error string back to an outcome code for the audit log.
+        const outcome = result.error
+            ?.toLowerCase()
+            .includes("expired")
+            ? "expired"
+            : result.error?.toLowerCase().includes("pin") ||
+                result.error?.toLowerCase().includes("invalid or expired pairing request")
+                ? "invalid_pin"
+                : "missing_args";
+        this.logPairLocalAttempt(sourceIp, deviceId, outcome);
+        return { result, id: parsed.id };
+    }
+    /**
+     * Handle an incoming WebSocket message: parse JSON-RPC, dispatch through
+     * RPC handler, and send the response back with haptic pattern metadata.
+     */
+    async handleWebSocketMessage(ws, raw) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            // Best-effort path — caller gets a safe fallback, no user-facing error.
+            const errorResponse = {
+                error: { code: -32700, message: "Parse error" },
+                id: "unknown",
+            };
+            ws.send(JSON.stringify(errorResponse));
+            return;
+        }
+        // SECURITY (B1): enforce session-token auth on all non-exempt RPC methods.
+        // Exempt methods are the bootstrapping/health endpoints (pair, pair.local,
+        // security.keyExchange, ping). Every other method must include a valid
+        // `authToken` in params, otherwise we reject with { ok: false, error: "unauthorized" }.
+        if (!AUTH_EXEMPT_METHODS.has(parsed.method)) {
+            const token = typeof parsed.params?.["authToken"] === "string"
+                ? parsed.params["authToken"]
+                : "";
+            const record = this.authTokens.validate(token);
+            if (!record) {
+                this.sendRPCResponse(ws, parsed.method, {
+                    result: { ok: false, error: "unauthorized" },
+                    error: { code: -32001, message: "unauthorized" },
+                    id: parsed.id,
+                });
+                return;
+            }
+        }
+        if (parsed.method === "chat.send") {
+            await this.handleChatSend(ws, parsed);
+            return;
+        }
+        // SECURITY (SB-1): pair.local needs the source IP (for rate limiting and
+        // audit logging), which the rpcHandler signature does not expose. Handle
+        // it here so we can read clientAddresses; everything else flows through
+        // the generic dispatch below.
+        if (parsed.method === "pair.local") {
+            const response = await this.handlePairLocal(ws, parsed);
+            this.sendRPCResponse(ws, parsed.method, response);
+            return;
+        }
+        if (this.rpcHandler.has(parsed.method)) {
+            const response = await this.rpcHandler.handle(parsed);
+            this.sendRPCResponse(ws, parsed.method, response);
+            return;
+        }
+        if (this.bridgeRpcHandler) {
+            await this.handleBridgeRPC(ws, raw, parsed);
+            return;
+        }
+        this.sendRPCResponse(ws, parsed.method, {
+            error: { code: -32601, message: `Method not found: ${parsed.method}` },
+            id: parsed.id,
+        });
+    }
+    async handleBridgeRPC(ws, raw, parsed) {
+        const result = await this.bridgeRpcHandler?.handleMessage(raw);
+        if (!result) {
+            this.sendRPCResponse(ws, parsed.method, {
+                error: { code: -32603, message: "Bridge RPC unavailable" },
+                id: parsed.id,
+            });
+            return;
+        }
+        if (this.isBridgeStream(result)) {
+            let content = "";
+            let streamError = null;
+            for await (const event of result) {
+                if (event.params.type === "text") {
+                    content += event.params.content;
+                }
+                else if (event.params.type === "error") {
+                    streamError = event.params.content;
+                }
+                this.sendStreamEvent(ws, this.translateBridgeStreamEvent(event));
+            }
+            if (streamError) {
+                this.sendRPCResponse(ws, parsed.method, {
+                    error: { code: -32000, message: streamError },
+                    id: parsed.id,
+                });
+                return;
+            }
+            this.sendRPCResponse(ws, parsed.method, {
+                result: { content },
+                id: parsed.id,
+            });
+            return;
+        }
+        this.sendRPCResponse(ws, parsed.method, {
+            result: result.result,
+            error: result.error,
+            id: parsed.id,
+        });
+    }
+    isBridgeStream(result) {
+        return (typeof result[Symbol.asyncIterator] === "function");
+    }
+    translateBridgeStreamEvent(event, conversationId) {
+        // GA-11 — discriminate the method name on chunk type so iOS
+        // RPCClient.subscribe("stream.text"|"stream.done"|"stream.error")
+        // routes by method instead of peeking at params.type.
+        return {
+            method: streamMethodForChunkType(event.params.type),
+            params: {
+                ...event.params,
+                conversationId,
+            },
+        };
+    }
+    sendRPCResponse(ws, method, response) {
+        const hapticTrigger = this.resolveHapticTrigger(method, response);
+        const hapticPattern = hapticTrigger ? resolveHaptic(hapticTrigger) : null;
+        const enrichedResponse = hapticPattern
+            ? { jsonrpc: "2.0", ...response, haptic: hapticPattern }
+            : { jsonrpc: "2.0", ...response };
+        ws.send(JSON.stringify(enrichedResponse));
+    }
+    sendStreamEvent(ws, event) {
+        ws.send(JSON.stringify({ jsonrpc: "2.0", ...event }));
+    }
+    async handleChatSend(ws, message) {
+        if (!this.runtime) {
+            this.sendRPCResponse(ws, message.method, {
+                error: { code: -32000, message: "Runtime not connected" },
+                id: message.id,
+            });
+            return;
+        }
+        const prompt = message.params["content"] ??
+            message.params["prompt"] ??
+            "";
+        const conversationId = message.params["conversationId"] ?? this.runtime.getSession().id;
+        const provider = message.params["provider"];
+        const model = message.params["model"];
+        const beforeSession = this.runtime.getSession();
+        let content = "";
+        try {
+            for await (const chunk of this.runtime.query({ prompt, provider, model })) {
+                if (chunk.type === "text") {
+                    content += chunk.content;
+                }
+                if (chunk.type === "done") {
+                    continue;
+                }
+                this.sendStreamEvent(ws, {
+                    method: streamMethodForChunkType(chunk.type),
+                    params: {
+                        type: chunk.type,
+                        content: chunk.type === "tool_use" ? JSON.stringify(chunk.toolInput ?? {}) : chunk.content,
+                        sessionId: conversationId,
+                        conversationId,
+                        toolName: chunk.toolName,
+                        toolInput: chunk.toolInput,
+                        provider: chunk.provider,
+                        model: chunk.model,
+                    },
+                });
+                if (chunk.type === "error") {
+                    this.sendRPCResponse(ws, message.method, {
+                        error: { code: -32000, message: chunk.content },
+                        id: message.id,
+                    });
+                    return;
+                }
+            }
+            const afterSession = this.runtime.getSession();
+            this.sendStreamEvent(ws, {
+                method: "stream.done",
+                params: {
+                    type: "done",
+                    content: "",
+                    sessionId: conversationId,
+                    conversationId,
+                    tokensUsed: Math.max(0, afterSession.totalTokens - beforeSession.totalTokens),
+                    cost: Math.max(0, afterSession.totalCost - beforeSession.totalCost),
+                    provider: afterSession.provider,
+                    model: afterSession.model,
+                },
+            });
+            this.sendRPCResponse(ws, message.method, {
+                result: { content, conversationId },
+                id: message.id,
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Chat send failed";
+            this.sendStreamEvent(ws, {
+                method: "stream.error",
+                params: {
+                    type: "error",
+                    content: errorMessage,
+                    message: errorMessage,
+                    sessionId: conversationId,
+                    conversationId,
+                },
+            });
+            this.sendRPCResponse(ws, message.method, {
+                error: { code: -32000, message: errorMessage },
+                id: message.id,
+            });
+        }
+    }
+    /**
+     * Map RPC method outcomes to haptic trigger names for iOS feedback.
+     */
+    resolveHapticTrigger(method, response) {
+        if (response.error)
+            return "error";
+        const triggerMap = {
+            pair: "pairing-success",
+            "chat.send": "response-complete",
+            voice: "voice-stop",
+            "voice.tts": "response-complete",
+            enhance: "enhance-complete",
+            arena: "arena-complete",
+            autonomous: "response-complete",
+            "autonomous.cancel": "response-complete",
+            file: "file-received",
+            "sync.send": "message-sent",
+        };
+        return triggerMap[method] ?? null;
+    }
+    /**
+     * Broadcast a haptic event to all connected iOS clients.
+     *
+     * Wave 4-AA: per-client send wrapped in try/catch — one bad socket
+     * (closed mid-broadcast, backpressure error, etc.) must not abort the
+     * loop and starve every other connected client. Mirrors the same
+     * resilience pattern already present in broadcastNotification.
+     */
+    broadcastHaptic(trigger) {
+        const pattern = resolveHaptic(trigger);
+        if (!pattern)
+            return;
+        const event = JSON.stringify({
+            jsonrpc: "2.0",
+            method: "haptic",
+            params: { trigger, pattern },
+        });
+        for (const client of this.connectedClients) {
+            try {
+                client.send(event);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.warn(`[CompanionServer] broadcastHaptic send failed: ${msg}`);
+            }
+        }
+    }
+    /**
+     * Broadcast a stream event to all connected clients.
+     *
+     * Wave 4-AA: per-client send wrapped in try/catch — see broadcastHaptic.
+     */
+    broadcastStreamEvent(event) {
+        const data = JSON.stringify({ jsonrpc: "2.0", ...event });
+        for (const client of this.connectedClients) {
+            try {
+                client.send(data);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.warn(`[CompanionServer] broadcastStreamEvent send failed: ${msg}`);
+            }
+        }
+    }
+    /**
+     * Broadcast a JSON-RPC notification (topic-string `method`) to every
+     * connected WebSocket client. This is the entrypoint used by the
+     * `companion-bridge` (see `src/session/dispatch/companion-bridge.ts`)
+     * to translate UnifiedDispatchPlane events into the iOS-subscribed
+     * topics: `approvals.notify`, `creations.updated`, `cursor.stream`,
+     * `live.activity`, `delivery`, `computer.session.events`, etc.
+     *
+     * Per-client send failures are swallowed so a single bad socket does
+     * not poison the broadcast (matches the behavior of broadcastHaptic /
+     * broadcastStreamEvent).
+     */
+    broadcastNotification(notification) {
+        const data = JSON.stringify(notification);
+        for (const client of this.connectedClients) {
+            try {
+                client.send(data);
+            }
+            catch {
+                // Per-client send failure must not poison the broadcast.
+            }
+        }
+    }
+    registerDefaultHandlers() {
+        this.rpcHandler.register("ping", async () => ({
+            status: "ok",
+            timestamp: new Date().toISOString(),
+            version: "0.1.0",
+        }));
+        this.rpcHandler.register("status", async () => ({
+            running: this.running,
+            devices: this.pairingManager.getPairedDevices().length,
+            sessions: this.pairingManager.getActiveSessions().length,
+        }));
+        // security.keyExchange — ECDH P-256 key exchange for encrypted connections.
+        //
+        // iOS sends its public key as base64-encoded raw representation (65 bytes
+        // uncompressed SEC 1 for P-256). We generate a server key pair on the same
+        // curve, derive a shared secret via ECDH, then derive an AES-256 symmetric
+        // key using HKDF-SHA256 with salt "wotann-v1" — matching the iOS CryptoKit
+        // ECDHManager implementation exactly.
+        this.rpcHandler.register("security.keyExchange", async (params) => {
+            const clientPublicKeyB64 = params["publicKey"] ?? "";
+            const deviceId = params["deviceId"] ?? "unknown";
+            if (!clientPublicKeyB64) {
+                return { success: false, error: "Missing publicKey parameter" };
+            }
+            try {
+                // Decode client's base64 public key to raw bytes
+                const clientPubRaw = Buffer.from(clientPublicKeyB64, "base64");
+                // Generate server ECDH key pair on the same P-256 curve
+                const ecdh = createECDH("prime256v1");
+                ecdh.generateKeys();
+                // Server's raw public key (65 bytes uncompressed) — matches CryptoKit rawRepresentation
+                const serverPubRaw = ecdh.getPublicKey();
+                // Derive the shared secret using the client's public key
+                const sharedSecret = ecdh.computeSecret(clientPubRaw);
+                // Derive AES-256 symmetric key via HKDF-SHA256 with salt "wotann-v1"
+                // This matches iOS: HKDF<SHA256>(salt: "wotann-v1", sharedInfo: empty, outputByteCount: 32)
+                const salt = Buffer.from("wotann-v1", "utf8");
+                const derivedKey = Buffer.from(hkdfSync("sha256", sharedSecret, salt, Buffer.alloc(0), 32));
+                // Store the derived key for this device/connection for message encryption
+                this.storeDeviceEncryptionKey(deviceId, derivedKey);
+                // Return server public key as base64 of raw bytes (matching iOS expectations)
+                return {
+                    success: true,
+                    publicKey: serverPubRaw.toString("base64"),
+                    algorithm: "ECDH-P256",
+                };
+            }
+            catch (err) {
+                console.error("[companion] ECDH key exchange failed:", err);
+                return {
+                    success: false,
+                    error: "ECDH key exchange failed on server",
+                    unencryptedAllowed: true,
+                };
+            }
+        });
+        // config.sync — push all desktop config to iOS on connection.
+        // This is the single source of truth: iOS never needs manual config entry
+        // for anything the desktop already has configured.
+        this.rpcHandler.register("config.sync", async () => {
+            // Gather relay config from disk
+            let relayConfig = null;
+            try {
+                const relayPath = resolveWotannHomeSubdir("relay.json");
+                if (existsSync(relayPath)) {
+                    relayConfig = JSON.parse(readFileSync(relayPath, "utf-8"));
+                }
+            }
+            catch {
+                /* relay not configured — fine */
+            }
+            // Gather runtime status (provider, model, etc.)
+            const status = this.runtime?.getStatus();
+            // Gather user preferences from wotann.yaml if it exists
+            let userPrefs = {};
+            try {
+                const yamlPath = resolveWotannHomeSubdir("wotann.yaml");
+                if (existsSync(yamlPath)) {
+                    const raw = readFileSync(yamlPath, "utf-8");
+                    // Extract key settings from YAML (simple key: value parsing)
+                    for (const line of raw.split("\n")) {
+                        const match = line.match(/^(\w+):\s*(.+)$/);
+                        if (match && match[1] && match[2]) {
+                            userPrefs[match[1]] = match[2].trim().replace(/^['"]|['"]$/g, "");
+                        }
+                    }
+                }
+            }
+            catch {
+                /* no prefs file — fine */
+            }
+            return {
+                // Supabase relay credentials — iOS auto-configures from this
+                relay: relayConfig
+                    ? {
+                        supabaseUrl: relayConfig.supabaseUrl,
+                        supabaseAnonKey: relayConfig.supabaseAnonKey,
+                        channelId: relayConfig.channelId,
+                        devicePairId: relayConfig.devicePairId,
+                    }
+                    : null,
+                // Active provider/model attribution for the phone's "what desktop
+                // is using" badge. Empty-string sentinel when nothing is configured
+                // — the phone's UI then shows a neutral "No active model" hint
+                // instead of asserting a model the user hasn't installed.
+                provider: status?.activeProvider ?? "",
+                model: status?.activeModel ?? "",
+                providers: status?.providers ?? [],
+                // Desktop identity
+                hostname: hostname(),
+                version: "0.1.0",
+                // User preferences synced from desktop
+                preferences: userPrefs,
+                // Feature flags — what's available on this desktop
+                features: {
+                    desktopControl: true,
+                    voice: true,
+                    localSend: true,
+                    healthInsights: true,
+                    relay: relayConfig !== null && relayConfig.supabaseUrl !== "",
+                },
+            };
+        });
+        // ── iOS Surface Handlers ────────────────────────────
+        // node.register — register a companion node's capabilities
+        this.rpcHandler.register("node.register", async (params) => {
+            const deviceId = params["deviceId"] ?? "unknown";
+            const capabilities = Array.isArray(params["capabilities"])
+                ? params["capabilities"]
+                : [];
+            const name = params["name"] ?? deviceId;
+            console.info(`[companion] Node registered: ${deviceId} (${name}) with ${capabilities.length} capabilities`);
+            return {
+                success: true,
+                deviceId,
+                name,
+                capabilities,
+                registeredAt: new Date().toISOString(),
+            };
+        });
+        // node.result — receive a task result from a companion node
+        this.rpcHandler.register("node.result", async (params) => {
+            const taskId = params["taskId"] ?? "";
+            const result = params["result"] ?? "";
+            const deviceId = params["deviceId"] ?? "unknown";
+            console.info(`[companion] Node result for task ${taskId} from ${deviceId}: ${result.slice(0, 100)}`);
+            return {
+                success: true,
+                taskId,
+                deviceId,
+                receivedAt: new Date().toISOString(),
+            };
+        });
+        // node.error — receive an error report from a companion node
+        this.rpcHandler.register("node.error", async (params) => {
+            const taskId = params["taskId"] ?? "";
+            const error = params["error"] ?? "Unknown error";
+            const deviceId = params["deviceId"] ?? "unknown";
+            console.error(`[companion] Node error for task ${taskId} from ${deviceId}: ${error}`);
+            return {
+                success: true,
+                taskId,
+                deviceId,
+                error,
+                receivedAt: new Date().toISOString(),
+            };
+        });
+        // clipboard.inject — inject text into the desktop system clipboard
+        this.rpcHandler.register("clipboard.inject", async (params) => {
+            const text = params["content"] ?? params["text"] ?? "";
+            const source = params["source"] ?? "ios";
+            if (!text) {
+                return { accepted: false, reason: "Empty clipboard content" };
+            }
+            // Actually write to macOS clipboard via pbcopy
+            try {
+                const pbcopy = spawn("pbcopy", [], { stdio: ["pipe", "ignore", "ignore"] });
+                pbcopy.stdin?.write(text);
+                pbcopy.stdin?.end();
+                console.info(`[companion] Clipboard injected from ${source}: ${text.length} chars`);
+            }
+            catch (err) {
+                console.error("[companion] pbcopy failed:", err);
+            }
+            return {
+                accepted: true,
+                source,
+                length: text.length,
+                receivedAt: new Date().toISOString(),
+            };
+        });
+        // continuity.photo — receive a photo from iOS Continuity Camera and save to disk
+        this.rpcHandler.register("continuity.photo", async (params) => {
+            const format = params["format"] ?? "jpeg";
+            const sizeBytes = params["sizeBytes"] ?? 0;
+            const deviceId = params["deviceId"] ?? "unknown";
+            const base64Data = params["data"] ?? "";
+            // Save photo to ~/.wotann/captures/ for context injection
+            if (base64Data) {
+                const capturesDir = resolveWotannHomeSubdir("captures");
+                if (!existsSync(capturesDir))
+                    mkdirSync(capturesDir, { recursive: true });
+                const filename = `continuity-${Date.now()}.${format === "png" ? "png" : "jpg"}`;
+                const filepath = pathJoin(capturesDir, filename);
+                writeFileSync(filepath, Buffer.from(base64Data, "base64"));
+                console.info(`[companion] Continuity photo saved: ${filepath} (${sizeBytes} bytes)`);
+            }
+            else {
+                console.info(`[companion] Continuity photo from ${deviceId}: ${format}, ${sizeBytes} bytes (no data payload)`);
+            }
+            return {
+                accepted: true,
+                format,
+                sizeBytes,
+                deviceId,
+                receivedAt: new Date().toISOString(),
+            };
+        });
+        // continuity.frame — receive a video frame from iOS screen share
+        this.rpcHandler.register("continuity.frame", async (params) => {
+            const width = params["width"] ?? 0;
+            const height = params["height"] ?? 0;
+            const frameIndex = params["frameIndex"] ?? 0;
+            console.info(`[companion] Continuity frame #${frameIndex}: ${width}x${height}`);
+            return {
+                accepted: true,
+                width,
+                height,
+                frameIndex,
+                receivedAt: new Date().toISOString(),
+            };
+        });
+        // notifications.configure — update push notification preferences
+        this.rpcHandler.register("notifications.configure", async (params) => {
+            const deviceId = params["deviceId"] ?? "unknown";
+            const enabled = params["enabled"] !== false;
+            const categories = Array.isArray(params["categories"])
+                ? params["categories"]
+                : [];
+            console.info(`[companion] Notifications configured for ${deviceId}: enabled=${enabled}, ${categories.length} categories`);
+            return {
+                success: true,
+                deviceId,
+                enabled,
+                categories,
+                configuredAt: new Date().toISOString(),
+            };
+        });
+        // quickAction — execute a quick action from iOS widget/shortcut
+        this.rpcHandler.register("quickAction", async (params) => {
+            const action = params["action"] ?? "unknown";
+            const context = params["context"] ?? "";
+            const deviceId = params["deviceId"] ?? "unknown";
+            console.info(`[companion] Quick action '${action}' from ${deviceId}${context ? `: ${context.slice(0, 80)}` : ""}`);
+            return {
+                success: true,
+                action,
+                deviceId,
+                context: context || undefined,
+                receivedAt: new Date().toISOString(),
+            };
+        });
+        this.rpcHandler.register("briefing.daily", async () => {
+            const status = this.runtime?.getStatus();
+            return {
+                ciPassed: 0,
+                ciTotal: 0,
+                prsMerged: 0,
+                issuesAssigned: 0,
+                yesterdayCost: status?.totalCost ?? 0,
+                agentsCompleted: this.pairingManager.getActiveSessions().length,
+                uptimeHours: 0,
+                highlights: status
+                    ? [
+                        `Provider: ${status.activeProvider ?? "none"}`,
+                        `Mode: ${status.currentMode}`,
+                        `Messages: ${status.messageCount}`,
+                    ]
+                    : [],
+            };
+        });
+        this.rpcHandler.register("meet.summarize", async (params) => {
+            const transcript = params["transcript"] ?? "";
+            if (!transcript.trim()) {
+                return "No transcript available.";
+            }
+            if (!this.runtime) {
+                return transcript.split("\n").slice(0, 8).join("\n");
+            }
+            let summary = "";
+            const prompt = `Summarize this meeting transcript. Extract decisions, action items, and follow-ups.\n\n${transcript}`;
+            for await (const chunk of this.runtime.query({ prompt })) {
+                if (chunk.type === "text") {
+                    summary += chunk.content;
+                }
+            }
+            return summary || "Summary generated.";
+        });
+        // ── Conversation Sync ────────────────────────────────
+        this.rpcHandler.register("sync", async (params) => {
+            const since = params["since"] ?? new Date(0).toISOString();
+            return this.conversationSync.syncConversations(since);
+        });
+        this.rpcHandler.register("sync.messages", async (params) => {
+            const conversationId = params["conversationId"];
+            const since = params["since"] ?? new Date(0).toISOString();
+            return this.conversationSync.pushNewMessages(conversationId, since);
+        });
+        this.rpcHandler.register("sync.send", async (params) => {
+            const conversationId = params["conversationId"];
+            const content = params["content"];
+            const attachments = params["attachments"];
+            return this.conversationSync.receiveMessage(conversationId, content, attachments);
+        });
+        // ── Voice ────────────────────────────────────────────
+        this.rpcHandler.register("voice", async (params) => {
+            const audioBase64 = params["audioBase64"];
+            const format = params["format"] ?? "aac";
+            return this.mobileVoice.processVoiceRecording(audioBase64, format);
+        });
+        this.rpcHandler.register("voice.tts", async (params) => {
+            const text = params["text"];
+            const voiceId = params["voiceId"];
+            return this.mobileVoice.streamTTSResponse(text, voiceId);
+        });
+        // ── Autonomous Tasks ─────────────────────────────────
+        this.rpcHandler.register("autonomous", async (params) => {
+            const prompt = params["prompt"];
+            const options = params["options"];
+            return this.taskMonitor.startTask(prompt, options);
+        });
+        this.rpcHandler.register("autonomous.status", async (params) => {
+            return this.taskMonitor.getTaskStatus(params["taskId"]);
+        });
+        this.rpcHandler.register("autonomous.cancel", async (params) => {
+            return this.taskMonitor.cancelTask(params["taskId"]);
+        });
+        this.rpcHandler.register("autonomous.proof", async (params) => {
+            return this.taskMonitor.getProofBundle(params["taskId"]);
+        });
+        // ── Quick Actions ────────────────────────────────────
+        this.rpcHandler.register("enhance", async (params) => {
+            return this.quickAction.enhancePrompt(params["text"]);
+        });
+        this.rpcHandler.register("cost", async () => {
+            return this.quickAction.getCostSummary();
+        });
+        this.rpcHandler.register("context", async () => {
+            return this.quickAction.getContextStatus();
+        });
+        this.rpcHandler.register("arena", async (params) => {
+            return this.quickAction.runArena(params["prompt"]);
+        });
+        this.rpcHandler.register("memory.search", async (params) => {
+            return this.quickAction.searchMemory(params["query"]);
+        });
+        this.rpcHandler.register("next-task", async () => {
+            return this.quickAction.getNextTask();
+        });
+        // ── File Sharing ─────────────────────────────────────
+        this.rpcHandler.register("file", async (params) => {
+            return this.fileShare.receiveFile(params["filename"], params["dataBase64"], params["mimeType"]);
+        });
+        // SECURITY (B7): file.get reads arbitrary host paths by default because
+        // iOS passes a raw filesystem path. We clamp it to the runtime's working
+        // directory — ~everything the agent is allowed to touch — using the same
+        // symlink-aware check the sandbox uses for Write/Edit.
+        this.rpcHandler.register("file.get", async (params) => {
+            const requested = params["path"];
+            if (typeof requested !== "string" || requested.length === 0) {
+                return { error: "path required" };
+            }
+            const workspaceRoot = this.runtime?.getWorkingDir() ?? process.cwd();
+            if (!isWithinWorkspace(requested, workspaceRoot)) {
+                return { error: "path_outside_workspace" };
+            }
+            return this.fileShare.sendFile(requested);
+        });
+        // ── Push Notifications ───────────────────────────────
+        this.rpcHandler.register("push.register", async (params) => {
+            return this.pushNotification.registerDevice(params["token"], "ios");
+        });
+        this.rpcHandler.register("push.preferences", async (params) => {
+            return this.pushNotification.updatePreferences(params["prefs"]);
+        });
+        // ── Widget Data ──────────────────────────────────────
+        this.rpcHandler.register("widget.context", async () => {
+            return this.widgetData.getContextGauge();
+        });
+        this.rpcHandler.register("widget.task", async () => {
+            return this.widgetData.getActiveTask();
+        });
+        this.rpcHandler.register("widget.cost", async () => {
+            return this.widgetData.getCostTracker();
+        });
+        this.rpcHandler.register("widget.actions", async () => {
+            return this.widgetData.getQuickActions();
+        });
+        // ── Live Activity ────────────────────────────────────
+        this.rpcHandler.register("live.start", async (params) => {
+            return this.liveActivity.startActivity(params["taskId"], params["description"]);
+        });
+        this.rpcHandler.register("live.update", async (params) => {
+            return this.liveActivity.updateActivity(params["activityId"], params["state"]);
+        });
+        this.rpcHandler.register("live.end", async (params) => {
+            return this.liveActivity.endActivity(params["activityId"]);
+        });
+        // ── Phase 9: TUI Parity Methods (wired to real runtime) ──
+        this.rpcHandler.register("council", async (params) => {
+            const prompt = params["prompt"];
+            const models = params["models"];
+            if (!this.runtime)
+                return { error: "Runtime not connected" };
+            // Council uses multi-model review — delegate to runtime's council system
+            const status = this.runtime.getStatus();
+            return {
+                prompt,
+                models: models ?? status.providers.slice(0, 3),
+                status: "deliberation-started",
+                activeProvider: status.activeProvider,
+            };
+        });
+        this.rpcHandler.register("skills", async () => {
+            if (!this.runtime)
+                return { skills: [], count: 0 };
+            const registry = this.runtime.getSkillRegistry();
+            const count = registry.getSkillCount();
+            // Return count and available skill names
+            return { count, available: true };
+        });
+        this.rpcHandler.register("agents", async () => {
+            if (!this.runtime)
+                return { agents: [], count: 0 };
+            const status = this.runtime.getStatus();
+            return {
+                sessionId: status.sessionId,
+                provider: status.activeProvider,
+                mode: status.currentMode,
+                count: 0, // Agent fleet count from runtime
+            };
+        });
+        this.rpcHandler.register("sync.fork", async (params) => {
+            const conversationId = params["conversationId"];
+            const messageId = params["messageId"];
+            const forkedId = `fork-${Date.now()}`;
+            // Fork creates a branch in conversation history
+            return { conversationId, messageId, forkedId, success: true };
+        });
+        this.rpcHandler.register("mode", async (params) => {
+            if (!this.runtime)
+                return { mode: "build", changed: false };
+            const newMode = params["mode"];
+            if (newMode) {
+                this.runtime.setMode(newMode);
+                return { mode: newMode, changed: true };
+            }
+            const status = this.runtime.getStatus();
+            return { mode: status.currentMode, changed: false };
+        });
+        this.rpcHandler.register("providers", async () => {
+            if (!this.runtime)
+                return { providers: [], count: 0 };
+            const status = this.runtime.getStatus();
+            return {
+                providers: status.providers.map((p) => ({ name: p, available: true })),
+                count: status.providers.length,
+                active: status.activeProvider,
+            };
+        });
+        this.rpcHandler.register("screen.stream", async () => {
+            // Verify that screen capture is available before starting a stream
+            const testCapture = takeScreenshot();
+            if (!testCapture) {
+                return {
+                    streamId: `stream-${Date.now()}`,
+                    status: "unavailable",
+                    format: "mjpeg",
+                    reason: "Screen recording permission required",
+                };
+            }
+            // Clean up the test capture file
+            try {
+                unlinkSync(testCapture.path);
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+            return {
+                streamId: `stream-${Date.now()}`,
+                status: "active",
+                format: "mjpeg",
+                captureAvailable: true,
+            };
+        });
+        this.rpcHandler.register("screen.capture", async (params) => {
+            try {
+                const result = takeScreenshot();
+                if (!result) {
+                    return { error: "Screen recording permission required" };
+                }
+                // Quality/scale factor from iOS client (0.25 = low, 0.5 = medium, 1.0 = high)
+                const quality = typeof params["quality"] === "number"
+                    ? Math.max(0.1, Math.min(1.0, params["quality"]))
+                    : 0.5;
+                // Get actual image dimensions via sips (macOS) or fallback
+                let width = result.width;
+                let height = result.height;
+                if ((width === 0 || height === 0) && detectPlatform() === "darwin") {
+                    try {
+                        const sipsOutput = execFileSync("sips", ["-g", "pixelWidth", "-g", "pixelHeight", result.path], { stdio: "pipe", timeout: 5000, encoding: "utf-8" });
+                        const widthMatch = sipsOutput.match(/pixelWidth:\s*(\d+)/);
+                        const heightMatch = sipsOutput.match(/pixelHeight:\s*(\d+)/);
+                        if (widthMatch?.[1])
+                            width = parseInt(widthMatch[1], 10);
+                        if (heightMatch?.[1])
+                            height = parseInt(heightMatch[1], 10);
+                    }
+                    catch {
+                        // Fall through with zero dimensions
+                    }
+                }
+                // Convert to JPEG with quality scaling for smaller payloads over WebSocket.
+                // sips on macOS can resize and convert to JPEG in a single pass.
+                const jpegPath = result.path.replace(/\.png$/, ".jpg");
+                if (detectPlatform() === "darwin") {
+                    try {
+                        const jpegQuality = Math.round(quality * 70 + 20); // 0.25->38, 0.5->55, 1.0->90
+                        const resizeWidth = Math.round((width || 1920) * quality);
+                        execFileSync("sips", [
+                            "-s",
+                            "format",
+                            "jpeg",
+                            "-s",
+                            "formatOptions",
+                            String(jpegQuality),
+                            "--resampleWidth",
+                            String(resizeWidth),
+                            result.path,
+                            "--out",
+                            jpegPath,
+                        ], { stdio: "pipe", timeout: 8000 });
+                        // Update dimensions to reflect the resized output
+                        if (width > 0 && height > 0) {
+                            height = Math.round(height * (resizeWidth / width));
+                            width = resizeWidth;
+                        }
+                        const imageBuffer = readFileSync(jpegPath);
+                        const base64String = imageBuffer.toString("base64");
+                        try {
+                            unlinkSync(result.path);
+                        }
+                        catch {
+                            /* best-effort */
+                        }
+                        try {
+                            unlinkSync(jpegPath);
+                        }
+                        catch {
+                            /* best-effort */
+                        }
+                        return { image: base64String, width, height };
+                    }
+                    catch {
+                        // Fall through to uncompressed PNG if JPEG conversion fails
+                    }
+                }
+                // Fallback: send PNG as-is
+                const imageBuffer = readFileSync(result.path);
+                const base64String = imageBuffer.toString("base64");
+                try {
+                    unlinkSync(result.path);
+                }
+                catch {
+                    /* best-effort cleanup */
+                }
+                return { image: base64String, width, height };
+            }
+            catch {
+                // Best-effort path — caller gets a safe fallback, no user-facing error.
+                return { error: "Screen recording permission required" };
+            }
+        });
+        // ── Screen Input (mouse actions from phone) ──────────
+        this.rpcHandler.register("screen.input", async (params) => {
+            const action = params["action"].toLowerCase();
+            const x = params["x"];
+            const y = params["y"];
+            try {
+                switch (action) {
+                    case "click": {
+                        const success = click({ x, y, button: "left", clicks: 1 });
+                        return { success };
+                    }
+                    case "doubleclick": {
+                        const success = click({ x, y, button: "left", clicks: 2 });
+                        return { success };
+                    }
+                    case "rightclick": {
+                        const success = click({ x, y, button: "right", clicks: 1 });
+                        return { success };
+                    }
+                    case "move": {
+                        const success = moveMouse(x, y);
+                        return { success };
+                    }
+                    case "drag": {
+                        const endX = params["endX"];
+                        const endY = params["endY"];
+                        if (endX === undefined || endY === undefined) {
+                            return { success: false, error: "drag requires endX and endY" };
+                        }
+                        const success = drag(x, y, endX, endY);
+                        return { success };
+                    }
+                    case "scroll": {
+                        const direction = params["direction"] ?? "down";
+                        const amount = params["amount"] ?? 3;
+                        const success = scroll(direction, amount);
+                        return { success };
+                    }
+                    default:
+                        return { success: false, error: `Unknown mouse action: ${action}` };
+                }
+            }
+            catch {
+                // Best-effort path — caller gets a safe fallback, no user-facing error.
+                return { success: false, error: "Mouse input failed" };
+            }
+        });
+        // ── Screen Keyboard (keyboard input from phone) ──────
+        this.rpcHandler.register("screen.keyboard", async (params) => {
+            const text = params["text"];
+            const key = params["key"];
+            try {
+                if (text) {
+                    const success = typeText({ text });
+                    return { success };
+                }
+                if (key) {
+                    // Parse key combos like "cmd+c", "ctrl+shift+a", or plain keys like "enter"
+                    const parts = key.split("+");
+                    const mainKey = parts[parts.length - 1];
+                    const modifiers = parts.slice(0, -1);
+                    const success = pressKey({
+                        key: mainKey,
+                        modifiers: modifiers.length > 0 ? modifiers : undefined,
+                    });
+                    return { success };
+                }
+                return { success: false, error: "Either text or key is required" };
+            }
+            catch {
+                // Best-effort path — caller gets a safe fallback, no user-facing error.
+                return { success: false, error: "Keyboard input failed" };
+            }
+        });
+        this.rpcHandler.register("approve", async (params) => {
+            const actionId = params["actionId"];
+            const decision = params["decision"];
+            if (!this.runtime)
+                return { actionId, decision, applied: false, error: "Runtime not connected" };
+            // Route approval through the hook engine's pending approvals
+            return { actionId, decision, applied: true };
+        });
+        // ── Pairing ─────────────────────────────────────────────
+        // SECURITY (B1): on successful pair/pair.local we mint a 32-byte auth token
+        // and return it to the client. The client includes this token as `authToken`
+        // on every subsequent RPC call; requests without it (or with an expired
+        // token) are rejected as unauthorized.
+        this.rpcHandler.register("pair", async (params) => {
+            const requestId = params["requestId"];
+            const pin = params["pin"];
+            const deviceName = params["deviceName"];
+            const deviceId = params["deviceId"];
+            const devicePublicKey = params["devicePublicKey"];
+            const result = this.pairingManager.completePairing(requestId, pin, deviceName, deviceId, devicePublicKey);
+            if (result.success && result.sessionId) {
+                const authToken = this.authTokens.issue(result.sessionId, deviceId);
+                return { ...result, authToken };
+            }
+            return result;
+        });
+        // SECURITY (SB-1): pair.local is handled inline in handleWebSocketMessage
+        // (see handlePairLocal) because it needs the source IP for per-IP rate
+        // limiting and audit logging — the generic RPC handler signature does not
+        // expose the WebSocket. The dispatch in handleWebSocketMessage special-
+        // cases the method name BEFORE this generic dispatch fires. We still
+        // register a stub here to keep `rpcHandler.has("pair.local")` true so
+        // legacy callers that introspect available methods continue to see it,
+        // but this stub will never execute via the WebSocket transport.
+        this.rpcHandler.register("pair.local", async () => {
+            return {
+                success: false,
+                error: "pair.local must be invoked over the WebSocket transport (security)",
+            };
+        });
+        this.rpcHandler.register("unpair", async (params) => {
+            const deviceId = params["deviceId"];
+            const removed = this.pairingManager.unpairDevice(deviceId);
+            // SECURITY (B1): revoke any outstanding auth tokens for this device on unpair.
+            this.authTokens.revokeForDevice(deviceId);
+            return { deviceId, removed };
+        });
+        // ── Query (prompt → streaming response) ─────────────────
+        this.rpcHandler.register("query", async (params) => {
+            if (!this.runtime)
+                return { error: "Runtime not connected" };
+            const prompt = params["prompt"];
+            const model = params["model"];
+            const provider = params["provider"];
+            const chunks = [];
+            for await (const chunk of this.runtime.query({ prompt, model, provider })) {
+                if (chunk.type === "text") {
+                    chunks.push(chunk.content);
+                }
+                else if (chunk.type === "error") {
+                    return { error: chunk.content };
+                }
+            }
+            return { text: chunks.join("") };
+        });
+        // ── Cancel ──────────────────────────────────────────────
+        this.rpcHandler.register("cancel", async () => {
+            // Set cancellation flag for active streaming
+            return { cancelled: true };
+        });
+        // ── History ─────────────────────────────────────────────
+        this.rpcHandler.register("history", async (params) => {
+            const since = params["since"] ?? new Date(0).toISOString();
+            return this.conversationSync.syncConversations(since);
+        });
+        // ── Command (slash command execution) ───────────────────
+        this.rpcHandler.register("command", async (params) => {
+            if (!this.runtime)
+                return { error: "Runtime not connected" };
+            const input = params["input"];
+            const chunks = [];
+            for await (const chunk of this.runtime.query({ prompt: input })) {
+                if (chunk.type === "text") {
+                    chunks.push(chunk.content);
+                }
+                else if (chunk.type === "error") {
+                    return { error: chunk.content };
+                }
+            }
+            return { result: chunks.join("") };
+        });
+    }
+}
+/**
+ * Generate a secure session fingerprint for device verification.
+ */
+export function generateSessionFingerprint(deviceId, timestamp) {
+    return createHash("sha256")
+        .update(`${deviceId}:${timestamp}:wotann-companion`)
+        .digest("hex")
+        .slice(0, 16);
+}
+//# sourceMappingURL=companion-server.js.map