beehaven 0.8.16

package/dist/relay.js

@@ -0,0 +1,2723 @@
+// ============================================================================
+// Beehaven Office - Cloud Relay
+// Persistent WebSocket connection to Cloudflare Durable Object relay.
+// Falls back to legacy HTTP POST for old Cloud Function endpoints.
+// ============================================================================
+import { existsSync, readFileSync, statSync, writeFileSync, mkdirSync, readdirSync, rmSync, chmodSync, } from 'fs';
+import { homedir, hostname, platform } from 'os';
+import { devModeAvailable, devModeRefusal } from './build-channel.js';
+import { join, dirname, resolve, sep } from 'path';
+import { execSync, execFileSync } from 'child_process';
+import WebSocket from 'ws';
+import { logger } from './logger.js';
+import { TerminalBlockParser } from './terminal/block-parser.js';
+import { writeIntegration, cleanupIntegration } from './terminal/shell-integration.js';
+import { transformPath } from './daemon-path-transform.js';
+import { relayUrlFromConfig } from './relay-presets.js';
+// Daemon Omni (Claude Agent SDK) loader removed (destroy-the-treehouse).
+/** Sensitive env vars to strip from PTY sessions */
+const SENSITIVE_ENV_PATTERNS = [
+    'AWS_SECRET_ACCESS_KEY',
+    'AWS_SESSION_TOKEN',
+    'GITHUB_TOKEN',
+    'GH_TOKEN',
+    'DATABASE_URL',
+    'ANTHROPIC_API_KEY',
+    'OPENAI_API_KEY',
+    'SENDGRID_API_KEY',
+    'FIREBASE_TOKEN',
+    'GOOGLE_APPLICATION_CREDENTIALS',
+    'STRIPE_SECRET_KEY',
+    'TWILIO_AUTH_TOKEN',
+    'NPM_TOKEN',
+    'DOCKER_PASSWORD',
+    'KUBECONFIG',
+    'MAILGUN_API_KEY',
+    'RESEND_API_KEY',
+    'OPENROUTER_API_KEY',
+    'ENCRYPTION_KEY',
+    'R2_SIGNING_KEY',
+    'WEBHOOK_SECRET',
+];
+const SENSITIVE_ENV_SUFFIXES = ['_KEY', '_SECRET', '_TOKEN', '_PASSWORD', '_CREDENTIALS', '_AUTH'];
+/** Allowed endpoint patterns for WebSocket relay */
+const ENDPOINT_WHITELIST = [/\.clearly\.sh$/, /\.workers\.dev$/];
+const CONFIG_DIR = join(homedir(), '.beehaven');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+// Daemon relay endpoint. The Mac app sets `BEEHAVEN_RELAY_URL` when
+// spawning daemon-entry.js so dev builds dial staging while production
+// builds dial prod. Anyone running the CLI directly can also override
+// this for local relay/staging iteration without rebuilding the Mac
+// bundle. Falls back to prod when unset.
+export const CLEARLY_RELAY_URL = typeof process !== 'undefined' &&
+    typeof process.env !== 'undefined' &&
+    typeof process.env.BEEHAVEN_RELAY_URL === 'string' &&
+    process.env.BEEHAVEN_RELAY_URL.length > 0
+    ? process.env.BEEHAVEN_RELAY_URL
+    : 'wss://relay.clearly.sh';
+/** Legacy Cloud Function URL — used as fallback when config.endpoint is this */
+const LEGACY_RELAY_URL = 'https://us-central1-clearly-9bd39.cloudfunctions.net/beehiveRelay';
+/** Flush interval — how often projects/docs buffer is sent to the cloud */
+const FLUSH_INTERVAL_MS = 5_000;
+/** Debounce for state sync — immediate-ish but coalesces rapid updates */
+const STATE_DEBOUNCE_MS = 200;
+export class Relay {
+    config = null;
+    connected = false;
+    /** True when stop()/unconfigure() was called — suppresses auto-reconnect
+     *  on the ws close handler. Cleared when start() is called again. */
+    stopped = false;
+    tier = 'free';
+    profile = null;
+    deviceId;
+    // ── WebSocket ─────────────────────────────────────────────────────────
+    ws = null;
+    wsConnecting = false;
+    reconnectAttempts = 0;
+    reconnectTimer = null;
+    /** Watchdog timer + the moment we first noticed we were disconnected. If the
+     *  relay stays down past the threshold, the watchdog forces a HARD reconnect
+     *  (terminate any zombie socket + reset backoff + redial). This is the
+     *  self-heal a HEADLESS / orphaned daemon needs — it has no Mac-app tray
+     *  parent to restart it, so a wedged WS (e.g. a half-open socket after system
+     *  sleep) would otherwise leave it "stuck reconnecting" forever. */
+    supervisorTimer = null;
+    disconnectedSince = null;
+    /** Request-response correlation — pending promises keyed by rid */
+    pendingRequests = new Map();
+    // ── Intervals ─────────────────────────────────────────────────────────
+    heartbeatInterval = null;
+    flushInterval = null;
+    stateDebounceTimer = null;
+    wsPingInterval = null;
+    wsWakeDetector = null;
+    lastTickAt = Date.now();
+    awaitingPong = false;
+    /** Consecutive app-level pings sent without a pong back, while the event
+     *  loop was NOT stalled. The home DO's edge auto-pong goes briefly silent
+     *  while its isolate cold-starts, so a SINGLE miss is normal and must not
+     *  sever the socket — terminating on the first miss turned one DO
+     *  cold-start into a relay reconnect that forced ANOTHER cold-start (a
+     *  self-feeding churn loop). Reset on every pong / stall; terminate only
+     *  once it reaches MAX_MISSED_PONGS. */
+    missedPongs = 0;
+    /** How many consecutive un-stalled missed pongs (~15s each) to tolerate
+     *  before declaring the relay socket dead. 2 ⇒ ~30s of genuine silence,
+     *  long enough to ride out a home-DO cold-start, short enough to recover
+     *  a truly dead peer quickly. (The web HiveClient uses 3; the relay's
+     *  reconnect is heavier — it cold-starts the DO — so 2 keeps it tighter.) */
+    MAX_MISSED_PONGS = 2;
+    /** Timestamp of the last APP-LEVEL pong ({"type":"pong"}). The keep-alive now
+     *  heartbeats with the app-level {"type":"ping"} the edge auto-answers
+     *  (the home DO's setWebSocketAutoResponse pairs ping→pong). A protocol-level
+     *  ws.ping() is NOT auto-ponged once the DO hibernates, which produced false
+     *  "No pong" reconnects; this app-level pong is the hibernation-safe signal. */
+    appPongAt = 0;
+    /** When the 15s pong-watchdog last actually ran. If the gap since the
+     *  previous run is far larger than the interval, the event loop was
+     *  frozen (App Nap / heavy work / brief sleep) and a "missed" pong is an
+     *  artifact of that freeze — not a dead peer. Used to suppress the
+     *  false-positive terminate that was dropping healthy daemon sockets. */
+    lastPongCheckAt = Date.now();
+    /** Disposer for the ~/.claude/.credentials.json watcher. Set on
+     *  first WS open; cleared + re-set on reconnects. The watcher
+     *  fires canvas-credential-detected to the worker when the user
+     *  completes the plan-SDK OAuth flow via `claude setup-token`. */
+    credentialsWatcherDispose = null;
+    // ── Flush buffer ──────────────────────────────────────────────────────
+    buffer = { events: [], docs: [] };
+    /** Per-project sync details for UI */
+    projectSyncDetails = new Map();
+    /** Timestamp of most recent successful sync */
+    lastSyncAt = 0;
+    /** Stats for logging */
+    stats = { sent: 0, failed: 0, batches: 0 };
+    /** Callback when profile updates from heartbeat (only fires on change) */
+    onProfileUpdate = null;
+    lastProfileJson = '';
+    /** Callback when a browse-files request arrives from the web UI */
+    onBrowseFiles = null;
+    /** Callback when a file has been teleported from web to local filesystem */
+    onFileTeleported = null;
+    /** Callback when cloud bee status update arrives */
+    onBeeStatus = null;
+    /** Callback when cloud bee emits a thought */
+    onBeeThought = null;
+    /** Callback to route fetch requests to local app buildings */
+    onLocalAppFetch = null;
+    /**
+     * Callback to route cross-hive RPC requests from the cloud workspace
+     * to a loaded local hive (#74). The cloud DO emits
+     * `daemon-rpc-request { requestId, hive, action, input }`; the
+     * daemon's local app manager looks up `hive` (default instance id),
+     * invokes `building.call(action, input)`, and the relay sends back
+     * `daemon-rpc-response { requestId, ok, result?, error? }`.
+     */
+    onDaemonRpcRequest = null;
+    /** Callback when a broadcast message arrives from the DO (forwarded to IPC clients) */
+    onBroadcast = null;
+    /** Fires every time the WebSocket transitions to OPEN — initial
+     *  connect AND every reconnect after sleep / network blip. Use
+     *  this to re-pull anything the daemon caches from the cloud
+     *  (avatar settings, profile, …) so missed broadcasts during
+     *  the offline window self-heal on the next reconnect. */
+    onConnected = null;
+    /** Callback when a file-changed broadcast arrives (cloud → local file sync) */
+    onFileChanged = null;
+    /** Callback when PTY produces output (for local IPC forwarding) */
+    onPtyOutput = null;
+    /** Number of web viewers currently watching (set by DO viewer-count message) */
+    viewerCount = 0;
+    /** Session events pending batch delivery (legacy HTTP mode only) */
+    sessionEventBatch = new Map();
+    /** Active PTY sessions: sessionId → pty process */
+    ptySessions = new Map();
+    /** Per-session OSC-133 block parsers: sessionId → TerminalBlockParser */
+    ptyParsers = new Map();
+    /** A managed PTY buffers input until its OSC-633 shell integration has printed its first prompt, so
+     *  the FIRST command runs WITH markers → a terminal-block is emitted (not swallowed by the shell-init
+     *  race). ptyReady = sessions past that point; ptyInputQueue = input typed before then; ptyReadyTimers
+     *  = the no-integration fallback flush. */
+    ptyReady = new Set();
+    ptyInputQueue = new Map();
+    ptyReadyTimers = new Map();
+    constructor() {
+        this.config = Relay.loadConfig();
+        // Desktop hosts inject the anonymous install id so workspace RPCs can be joined back to the
+        // Mac funnel. Standalone CLI keeps the existing machine-scoped fallback. Both are bounded and
+        // never carry a username, path, serial number or account credential.
+        this.deviceId = process.env.BEEHAVEN_DEVICE_ID || `${hostname()}-${platform()}`;
+    }
+    /**
+     * Start watching ~/.claude/.credentials.json for OAuth completion.
+     * Idempotent — calling repeatedly disposes the prior watcher.
+     * Dynamically imports the credential-store module so the relay
+     * startup path stays light.
+     */
+    _startCredentialsWatcher() {
+        // Dispose any prior watcher (reconnect scenario).
+        if (this.credentialsWatcherDispose) {
+            try {
+                this.credentialsWatcherDispose();
+            }
+            catch {
+                /* idempotent */
+            }
+            this.credentialsWatcherDispose = null;
+        }
+        // Claude credentials-file watcher removed with the daemon Claude Code
+        // integration (destroy-the-treehouse).
+    }
+    // ── Config ────────────────────────────────────────────────────────────
+    /** Load relay config from ~/.beehaven/config.json */
+    static loadConfig() {
+        if (!existsSync(CONFIG_FILE))
+            return null;
+        try {
+            const raw = readFileSync(CONFIG_FILE, 'utf8');
+            const parsed = JSON.parse(raw);
+            let token = parsed.token;
+            if (parsed.tokenStorage === 'keychain') {
+                try {
+                    // Use execSync to call macOS keychain directly (require() fails in ESM)
+                    token =
+                        execSync('security find-generic-password -s "beehaven" -a "daemon-token" -w', {
+                            encoding: 'utf8',
+                            timeout: 3000,
+                            stdio: ['pipe', 'pipe', 'ignore'],
+                        }).trim() || parsed.token;
+                }
+                catch {
+                    token = parsed.token;
+                }
+            }
+            /**
+             * ⚠⚠ THE DIAL TARGET IS RESOLVED, NEVER READ RAW — `endpoint` OR `relayUrl`.
+             *
+             * This line was `if (!token || !parsed.endpoint) return null`, and it is the ONLY reader in
+             * the codebase that demanded `endpoint` specifically. Everything else goes through
+             * `relayUrlFromConfig`, whose own docstring calls `relayUrl` a supported alias — so a config
+             * carrying only `relayUrl` was well-formed to every other surface and invisible to this one.
+             *
+             * ⚠ THE FAILURE IS TOTAL AND SILENT. `null` here means `isConfigured()` is false, so the
+             * daemon never dials the relay at all: the tray reads "agent offline", the avatar's menu says
+             * "Could not reach the daemon", and `refreshIdToken` — which starts by calling this — returns
+             * false and logs "Token refresh failed — will retry in 5 minutes". THREE unrelated-looking
+             * symptoms, one missing key, and none of them names it.
+             *
+             * ⚠⚠ AND `beehaven login` WROTE EXACTLY THAT CONFIG. It spreads `...existing` and never emits
+             * a dial target, so it PRESERVES `endpoint` when one is already there and cannot create one.
+             * After `logout` (which deletes `endpoint` by name) or on a fresh install where the Mac app's
+             * `install()` had not yet run, signing in from the terminal produced a config with valid
+             * tokens, a correct `relayUrl`, and no way to connect. Measured: adding the one key to a live
+             * broken config took `relayConnected` from false to true with no other change.
+             *
+             * ⚠ FIXING IT HERE rather than only at the writer is what makes it SELF-HEALING: every config
+             * already on a user's disk starts working on the next daemon start, with no migration.
+             */
+            const endpoint = relayUrlFromConfig(parsed);
+            if (!token || !endpoint)
+                return null;
+            return { token, endpoint, refreshToken: parsed.refreshToken };
+        }
+        catch {
+            return null;
+        }
+    }
+    isConfigured() {
+        return this.config !== null;
+    }
+    /**
+     * True iff we actually have a live transport to the cloud relay.
+     *
+     * For WebSocket mode we prefer `ws.readyState === OPEN` over the cached
+     * `.connected` flag — the flag is event-driven and can drift stale if an
+     * open/close event is missed (e.g. after system sleep or a silent reconnect
+     * race), which made `beehaven rpc` report "Not connected to cloud" while
+     * the WebSocket was genuinely up. For HTTP-heartbeat mode we fall back to
+     * the flag since there's no socket to inspect.
+     */
+    isConnected() {
+        if (this.useWebSocket) {
+            return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+        }
+        return this.connected;
+    }
+    getTier() {
+        return this.tier;
+    }
+    getProfile() {
+        return this.profile;
+    }
+    /** Whether any web clients are watching the office (set by DO viewer-count) */
+    get hasViewers() {
+        return this.viewerCount > 0;
+    }
+    /** Configure relay with a new token */
+    configure(token, endpoint) {
+        this.config = { token, endpoint: endpoint || CLEARLY_RELAY_URL };
+    }
+    /** Clear relay configuration */
+    unconfigure() {
+        this.stop();
+        this.config = null;
+        this.profile = null;
+        this.connected = false;
+        this.tier = 'free';
+    }
+    /** Get sync status for UI display */
+    getSyncStatus() {
+        return {
+            connected: this.connected,
+            sent: this.stats.sent,
+            failed: this.stats.failed,
+            lastSyncAt: this.lastSyncAt,
+        };
+    }
+    // ── Endpoint Detection ────────────────────────────────────────────────
+    /** Whether this endpoint uses WebSocket (new Cloudflare relay) */
+    get useWebSocket() {
+        if (!this.config)
+            return false;
+        const ep = this.config.endpoint;
+        return ep.startsWith('wss://') || ep.includes('relay.clearly.sh') || ep.includes('workers.dev');
+    }
+    /** Get the WebSocket base URL (without auth params) */
+    wsBase() {
+        if (!this.config)
+            return '';
+        let base = this.config.endpoint;
+        if (base.startsWith('https://'))
+            base = base.replace('https://', 'wss://');
+        if (!base.startsWith('wss://'))
+            base = `wss://${base}`;
+        return base.replace(/\/$/, '');
+    }
+    /** Get the HTTPS base URL for ticket exchange */
+    ticketUrl() {
+        if (!this.config)
+            return '';
+        const base = this.wsBase();
+        return base.replace('wss://', 'https://').replace('ws://', 'http://') + '/auth/ticket';
+    }
+    /** Exchange relay token for a single-use ticket (30s TTL) */
+    async fetchTicket() {
+        if (!this.config)
+            return null;
+        try {
+            let resp = await fetch(this.ticketUrl(), {
+                method: 'POST',
+                headers: { Authorization: `Bearer ${this.config.token}` },
+                signal: AbortSignal.timeout(10_000),
+            });
+            // Token may have expired — try refreshing and retrying once
+            if (resp.status === 401 || resp.status === 403) {
+                console.log('[relay] Ticket fetch failed (auth) — refreshing token');
+                const refreshed = await this.refreshIdToken();
+                if (refreshed && this.config) {
+                    resp = await fetch(this.ticketUrl(), {
+                        method: 'POST',
+                        headers: { Authorization: `Bearer ${this.config.token}` },
+                        signal: AbortSignal.timeout(10_000),
+                    });
+                }
+            }
+            if (!resp.ok)
+                return null;
+            const data = await resp.json();
+            return data.ticket;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Get the HTTP URL for one-shot requests (verifyToken, building, etc.) */
+    httpUrl(endpoint) {
+        const ep = endpoint || this.config?.endpoint || '';
+        if (ep.startsWith('wss://'))
+            return ep.replace('wss://', 'https://').replace(/\/$/, '') + '/relay';
+        if (ep.startsWith('https://') &&
+            (ep.includes('relay.clearly.sh') || ep.includes('workers.dev')))
+            return ep.replace(/\/$/, '') + '/relay';
+        return ep; // Legacy Cloud Function URL
+    }
+    // ── Lifecycle ─────────────────────────────────────────────────────────
+    /** Start the relay — connects via WebSocket or legacy HTTP */
+    async start() {
+        if (!this.config)
+            return;
+        // Re-enable auto-reconnect in case a previous stop() set it.
+        this.stopped = false;
+        // Validate endpoint against whitelist
+        try {
+            const endpointHost = new URL(this.config.endpoint.replace('wss://', 'https://').replace('ws://', 'http://')).hostname;
+            const allowed = ENDPOINT_WHITELIST.some((re) => re.test(endpointHost)) || endpointHost === 'localhost';
+            if (!allowed) {
+                console.error(`[relay] Endpoint rejected: ${endpointHost} not in whitelist`);
+                return;
+            }
+        }
+        catch {
+            console.error('[relay] Invalid endpoint URL');
+            return;
+        }
+        if (this.useWebSocket) {
+            await this.connectWs();
+            this.startSupervisor();
+        }
+        else {
+            // Legacy HTTP mode
+            const ok = await this.sendHeartbeatHttp();
+            this.connected = ok;
+            if (!ok) {
+                console.log('[relay] Failed to connect — check token and endpoint');
+                this.scheduleReconnect();
+                return;
+            }
+            console.log(`[relay] Connected to Clearly (tier: ${this.tier})`);
+            this.heartbeatInterval = setInterval(() => this.sendHeartbeatHttp(), 30_000);
+            this.flushInterval = setInterval(() => this.flush(), FLUSH_INTERVAL_MS);
+        }
+    }
+    /** Stop the relay — close WebSocket, flush remaining buffer */
+    stop() {
+        // Set BEFORE terminate(): the ws close handler checks this to
+        // suppress auto-reconnect on intentional shutdown.
+        this.stopped = true;
+        if (this.heartbeatInterval)
+            clearInterval(this.heartbeatInterval);
+        if (this.flushInterval)
+            clearInterval(this.flushInterval);
+        if (this.stateDebounceTimer)
+            clearTimeout(this.stateDebounceTimer);
+        if (this.wsPingInterval)
+            clearInterval(this.wsPingInterval);
+        if (this.wsWakeDetector)
+            clearInterval(this.wsWakeDetector);
+        if (this.supervisorTimer)
+            clearInterval(this.supervisorTimer);
+        this.supervisorTimer = null;
+        this.disconnectedSince = null;
+        this.heartbeatInterval = null;
+        this.flushInterval = null;
+        this.stateDebounceTimer = null;
+        this.wsPingInterval = null;
+        this.wsWakeDetector = null;
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+        // Reject pending requests
+        for (const [, pending] of this.pendingRequests) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error('Relay stopped'));
+        }
+        this.pendingRequests.clear();
+        // Kill all PTY sessions
+        for (const [sid, ptyProcess] of this.ptySessions) {
+            try {
+                ptyProcess.kill();
+            }
+            catch { }
+            cleanupIntegration(sid);
+        }
+        this.ptySessions.clear();
+        this.ptyParsers.clear();
+        // Close WebSocket — use terminate() to avoid hanging on graceful close handshake
+        if (this.ws) {
+            try {
+                this.ws.terminate();
+            }
+            catch { }
+            this.ws = null;
+        }
+        this.connected = false;
+        this.wsConnecting = false;
+        // Final flush (fire-and-forget)
+        this.flush();
+    }
+    // ── WebSocket ─────────────────────────────────────────────────────────
+    /** Establish WebSocket connection to the Cloudflare relay.
+     *  Resolves when the connection opens (or immediately on failure). */
+    async connectWs() {
+        if (!this.config || this.wsConnecting)
+            return;
+        this.wsConnecting = true;
+        // Re-read the persisted token first. The Mac app (or a prior refresh)
+        // may have written a fresh idToken while we were looping; without this
+        // we'd keep dialing with the stale in-memory copy and never self-heal
+        // short of a full daemon restart.
+        try {
+            const fresh = Relay.loadConfig();
+            if (fresh?.token && this.config)
+                this.config.token = fresh.token;
+        }
+        catch { }
+        // Use ?token= directly — ticket exchange is unreliable across Cloudflare isolates.
+        // The ?token= path is the server's fallback for non-browser clients (CLI, daemon).
+        // If token is expired, try refreshing first.
+        let token = this.config.token;
+        // Quick expiry check — decode JWT exp without verification
+        let expiredNoRefresh = false;
+        try {
+            const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64').toString());
+            const nowSec = Date.now() / 1000;
+            if (payload.exp && nowSec > payload.exp - 60) {
+                console.log('[relay] Token near/at expiry — refreshing before connect');
+                const refreshed = await this.refreshIdToken();
+                if (refreshed && this.config)
+                    token = this.config.token;
+                else if (payload.exp && nowSec > payload.exp)
+                    expiredNoRefresh = true;
+            }
+        }
+        catch { }
+        // If the token is already expired AND refresh failed, dialing would just
+        // get rejected — spinning the reconnect loop forever with a dead
+        // credential (the classic "daemon stuck reconnecting" state). Back off
+        // and wait for a fresh token (e.g. the Mac app re-minting one) instead.
+        if (expiredNoRefresh) {
+            console.warn('[relay] Token expired and refresh failed — backing off without dialing. Reopen the Clearly Dev Mac app to re-authenticate.');
+            this.wsConnecting = false;
+            if (this.config && !this.stopped)
+                this.scheduleReconnect();
+            return;
+        }
+        // The daemon holds ONE socket — to the user's HIVE (`/my/hive/ws`, the per-user
+        // multiplexer). The hive opens a server-side portal to the caller's CANONICAL workspace
+        // (no `workspaceId` → the hive resolves it from `building_assignments`) and pipes it
+        // transparently, so every workspace RPC (canvas-invoke, actions, table sync) round-trips
+        // exactly as before — plus the daemon shares the same socket the web app uses. (Plain
+        // synchronous URL — no pre-connect HTTP hop — so nothing can stall the dial.)
+        const params = new URLSearchParams({
+            token,
+            client: process.env.BEEHAVEN_CLIENT || 'daemon',
+            clientType: process.env.BEEHAVEN_CLIENT_TYPE || 'daemon',
+            wsType: 'workspace',
+        });
+        if (this.deviceId)
+            params.set('deviceId', String(this.deviceId).slice(0, 64));
+        const url = `${this.wsBase()}/my/hive/ws?${params.toString()}`;
+        const ws = new WebSocket(url);
+        // Wait for open or first error/close before resolving
+        await new Promise((resolve) => {
+            const done = () => {
+                resolve();
+            };
+            ws.on('open', () => {
+                this.ws = ws;
+                this.wsConnecting = false;
+                this.connected = true;
+                this.reconnectAttempts = 0;
+                console.log(`[relay] WebSocket connected to ${this.config.endpoint}`);
+                // Notify subscribers that the WebSocket is open so they
+                // can pull fresh state. Wrapped because the callback
+                // might do RPCs that throw — we never want a subscriber
+                // error to crash the open handler.
+                try {
+                    this.onConnected?.();
+                }
+                catch (err) {
+                    console.warn(`[relay] onConnected callback threw: ${err?.message ?? err}`);
+                }
+                // Send heartbeat to get profile + trigger TTL extension
+                this.wsSend({ type: 'heartbeat', deviceId: this.deviceId });
+                // Announce environment so the bee agent knows about /local/
+                this.wsSend({
+                    type: 'daemon-hello',
+                    root: homedir(),
+                    os: platform(),
+                    shell: process.env.SHELL?.split('/').pop() || 'bash',
+                    hostname: hostname(),
+                });
+                // Announce presence
+                this.wsSend({ type: 'presence', online: true, deviceId: this.deviceId, tier: this.tier });
+                // Start the ~/.claude/.credentials.json watcher — when
+                // the user completes the plan-SDK OAuth flow via
+                // `claude setup-token`, the CLI writes the file and our
+                // watcher fires canvas-credential-detected back to the
+                // worker, which flips the credential row + broadcasts to
+                // web clients. Idempotent across reconnects — calling
+                // start more than once just no-ops because the prior
+                // watcher object is replaced on each call.
+                this._startCredentialsWatcher();
+                // Start flush interval
+                if (this.flushInterval)
+                    clearInterval(this.flushInterval);
+                this.flushInterval = setInterval(() => this.flush(), FLUSH_INTERVAL_MS);
+                // JSON heartbeat removed — was waking the home DO every 20s.
+                // Daemon liveness is already driven by WS connection state:
+                // `Workspace.onDisconnect` clears `daemonEnvs` + removes the
+                // session, and `deriveDaemonList()` reads only from currently
+                // connected sessions. No time-based prune exists, so the
+                // per-20s refresh was pure DO-wake cost with no signal value.
+                //
+                // The one-shot heartbeat on connect (line 421) still fires
+                // once so the server gets the initial profile snapshot.
+                // Heartbeat with the APP-LEVEL {type:'ping'} the edge auto-answers:
+                // the home DO's setWebSocketAutoResponse pairs {type:'ping'} →
+                // {type:'pong'} and replies AT THE EDGE without waking the DO. A
+                // protocol-level ws.ping() is NOT auto-ponged once the DO
+                // hibernates — that mismatch was the false "No pong" reconnect.
+                if (this.heartbeatInterval) {
+                    clearInterval(this.heartbeatInterval);
+                    this.heartbeatInterval = null;
+                }
+                // WebSocket-level ping every 15s — detects dead connections faster than TCP timeout
+                if (this.wsPingInterval)
+                    clearInterval(this.wsPingInterval);
+                this.awaitingPong = false;
+                this.missedPongs = 0;
+                this.lastPongCheckAt = Date.now();
+                this.wsPingInterval = setInterval(() => {
+                    if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+                        return;
+                    // Stall guard: if this 15s interval itself ran far late, the
+                    // event loop was frozen (macOS App Nap on the backgrounded
+                    // daemon, heavy sync work, or a brief sleep). A pong we
+                    // "didn't receive" is then an artifact of that freeze, not a
+                    // dead peer — terminating here was the false-positive that
+                    // severed healthy daemon sockets (close 1006) every few
+                    // minutes. Reset and re-probe instead of killing the socket.
+                    const sinceLast = Date.now() - this.lastPongCheckAt;
+                    this.lastPongCheckAt = Date.now();
+                    if (sinceLast > 30_000) {
+                        logger.warn('relay', `Ping interval ran ${(sinceLast / 1000).toFixed(0)}s late (event-loop stall) — re-probing, not terminating`);
+                        this.awaitingPong = true;
+                        this.missedPongs = 0; // the gap was OUR freeze, not a dead peer — don't count it
+                        try {
+                            this.ws.send(JSON.stringify({ type: 'ping' }));
+                        }
+                        catch { }
+                        return;
+                    }
+                    if (this.awaitingPong) {
+                        // Pinged last cycle, no pong this cycle, loop NOT stalled.
+                        // Don't sever on the first miss: the home DO's edge
+                        // auto-pong goes briefly silent while its isolate
+                        // cold-starts, and terminating here forced a relay
+                        // reconnect that triggered ANOTHER cold-start — a
+                        // self-feeding churn loop that reconnected every client
+                        // (web + mac-app) each cycle. Re-ping and only declare
+                        // the peer dead after MAX_MISSED_PONGS consecutive
+                        // un-stalled misses (~30s of genuine silence).
+                        this.missedPongs++;
+                        if (this.missedPongs >= this.MAX_MISSED_PONGS) {
+                            logger.warn('relay', `No pong after ${this.missedPongs} pings (~${this.missedPongs * 15}s silent) — connection dead, reconnecting`);
+                            try {
+                                this.ws.terminate();
+                            }
+                            catch { }
+                            return;
+                        }
+                        // Tolerated miss — re-probe and give it one more cycle.
+                        try {
+                            this.ws.send(JSON.stringify({ type: 'ping' }));
+                        }
+                        catch { }
+                        return;
+                    }
+                    this.awaitingPong = true;
+                    this.missedPongs = 0;
+                    try {
+                        this.ws.send(JSON.stringify({ type: 'ping' }));
+                    }
+                    catch { }
+                }, 15_000);
+                // Detect system wake — a >35s gap between 5s ticks means EITHER
+                // the system slept (socket dead) OR the process was merely
+                // throttled / the event loop stalled (macOS App Nap on the
+                // backgrounded daemon) — in which case the socket is still
+                // ALIVE. Blind-terminating here was severing healthy
+                // connections every few minutes (close 1006) and forcing
+                // reconnect churn. Verify first: ping, and only drop if no pong
+                // comes back within a short grace.
+                this.lastTickAt = Date.now();
+                if (this.wsWakeDetector)
+                    clearInterval(this.wsWakeDetector);
+                this.wsWakeDetector = setInterval(() => {
+                    const now = Date.now();
+                    const drift = now - this.lastTickAt;
+                    this.lastTickAt = now;
+                    if (drift > 35_000 && this.ws && this.ws.readyState === WebSocket.OPEN) {
+                        const sock = this.ws;
+                        logger.warn('relay', `Timer drift ${(drift / 1000).toFixed(0)}s — verifying liveness before reconnect`);
+                        const probeAt = Date.now();
+                        try {
+                            sock.send(JSON.stringify({ type: 'ping' }));
+                        }
+                        catch { }
+                        setTimeout(() => {
+                            // Alive iff the edge auto-ponged our app-level ping AFTER
+                            // this probe — the hibernation-safe signal (a protocol-
+                            // level pong never arrives once the home DO hibernates).
+                            if (this.appPongAt >= probeAt) {
+                                logger.info('relay', 'Alive after drift (throttle, not sleep) — keeping connection');
+                                return;
+                            }
+                            // Only terminate the socket we probed, and only if
+                            // it's still the current one (not already replaced).
+                            if (sock === this.ws && sock.readyState === WebSocket.OPEN) {
+                                logger.warn('relay', 'No pong after drift probe — connection dead, reconnecting');
+                                try {
+                                    sock.terminate();
+                                }
+                                catch { }
+                            }
+                        }, 8_000);
+                    }
+                }, 5_000);
+                done();
+            });
+            ws.on('error', () => {
+                done();
+            });
+        });
+        ws.on('pong', () => {
+            this.awaitingPong = false;
+            this.missedPongs = 0;
+        });
+        ws.on('message', (data) => {
+            try {
+                const msg = JSON.parse(data.toString());
+                // App-level heartbeat pong — the edge's setWebSocketAutoResponse
+                // answers our {type:'ping'} with {type:'pong'} WITHOUT waking the
+                // home DO, so this is the hibernation-safe liveness signal. (The
+                // protocol-level ws.on('pong') never fires once the DO hibernates;
+                // the edge auto-pongs only this app-level pair, not RFC 6455 frames.)
+                if (msg && msg.type === 'pong') {
+                    this.awaitingPong = false;
+                    this.missedPongs = 0;
+                    this.appPongAt = Date.now();
+                    return;
+                }
+                this.handleMessage(msg).catch(() => {
+                    /* message handling error */
+                });
+            }
+            catch {
+                /* malformed message */
+            }
+        });
+        ws.on('close', (code, reason) => {
+            // Record the close code the daemon observed. 1006 (no close frame)
+            // = abrupt sever — either our own terminate() or an edge drop;
+            // 1000/1001 = graceful. Pairs with the server's
+            // sdk-diag.webSocketClose so a drop is visible from both ends
+            // (this lands in daemon.log; console.log here would go to /dev/null).
+            const reasonStr = (() => {
+                try {
+                    return reason?.toString?.() ?? '';
+                }
+                catch {
+                    return '';
+                }
+            })();
+            logger.warn('relay', `WS closed code=${code ?? '?'} reason="${reasonStr.slice(0, 80)}" wasConnected=${this.connected}`);
+            this.ws = null;
+            this.wsConnecting = false;
+            this.connected = false;
+            if (this.flushInterval)
+                clearInterval(this.flushInterval);
+            if (this.heartbeatInterval)
+                clearInterval(this.heartbeatInterval);
+            if (this.wsPingInterval)
+                clearInterval(this.wsPingInterval);
+            if (this.wsWakeDetector)
+                clearInterval(this.wsWakeDetector);
+            this.flushInterval = null;
+            this.heartbeatInterval = null;
+            this.wsPingInterval = null;
+            this.wsWakeDetector = null;
+            // Reject pending requests
+            for (const [, pending] of this.pendingRequests) {
+                clearTimeout(pending.timer);
+                pending.reject(new Error('WebSocket closed'));
+            }
+            this.pendingRequests.clear();
+            // Always schedule reconnect while we're still configured and not
+            // stopped. Previous guard `if (wasConnected)` broke the chain: if
+            // a reconnect attempt failed to open, the new ws's close handler
+            // saw connected=false and skipped scheduling — leaving us stuck
+            // forever with no WS and no pending retry. The `stopped` flag is
+            // set synchronously in stop()/unconfigure(), so intentional
+            // shutdowns still skip the reconnect.
+            if (this.config && !this.stopped) {
+                this.scheduleReconnect();
+            }
+        });
+        ws.on('error', (err) => {
+            if (this.wsConnecting) {
+                // Connection failed — close handler will trigger reconnect
+                this.wsConnecting = false;
+            }
+            // Avoid noisy logs for expected connection errors
+            if (err.message && !err.message.includes('ECONNREFUSED')) {
+                console.error(`[relay] WebSocket error: ${err.message}`);
+            }
+        });
+    }
+    /** Handle an incoming WebSocket message from the DO */
+    async handleMessage(msg) {
+        const type = msg.type;
+        // Handle request-response correlation (rid for legacy, requestId for workspace actions)
+        const correlationId = msg.requestId ?? msg.rid;
+        if (correlationId && this.pendingRequests.has(correlationId)) {
+            const pending = this.pendingRequests.get(correlationId);
+            clearTimeout(pending.timer);
+            this.pendingRequests.delete(correlationId);
+            pending.resolve(msg);
+            return;
+        }
+        switch (type) {
+            case 'welcome':
+                console.log(`[relay] Connected to Clearly (tier: ${msg.tier})`);
+                if (msg.tier)
+                    this.tier = msg.tier;
+                break;
+            case 'heartbeat-ack': {
+                if (msg.tier)
+                    this.tier = msg.tier;
+                const profileData = msg.profile;
+                if (profileData) {
+                    this.profile = {
+                        displayName: profileData.displayName || 'Clearly User',
+                        username: profileData.username,
+                        photoURL: profileData.photoURL,
+                        email: profileData.email,
+                        subscriptionPlan: profileData.subscriptionPlan || 'free',
+                        subscriptionStatus: profileData.subscriptionStatus,
+                        shareTerminal: profileData.shareTerminal,
+                        shareTelemetry: profileData.shareTelemetry,
+                    };
+                    const json = JSON.stringify(this.profile);
+                    if (json !== this.lastProfileJson) {
+                        this.lastProfileJson = json;
+                        this.onProfileUpdate?.(this.profile);
+                    }
+                }
+                break;
+            }
+            case 'browse-files': {
+                const path = msg.path;
+                const rid = msg.rid;
+                if (path && rid && this.onBrowseFiles) {
+                    this.onBrowseFiles(path, rid);
+                }
+                break;
+            }
+            case 'file-teleport-delivery': {
+                const fileId = msg.fileId;
+                const fileName = msg.fileName;
+                const size = msg.size;
+                const contentType = msg.contentType;
+                const downloadUrl = msg.downloadUrl;
+                const targetDir = msg.targetDir;
+                const uploadUrl = msg.uploadUrl;
+                const publicUrl = msg.publicUrl;
+                const localPath = msg.localPath;
+                // Reverse teleport: upload local file TO R2
+                if (uploadUrl && localPath) {
+                    this.handleUploadLocalFile(localPath, uploadUrl, publicUrl || '', contentType, undefined)
+                        .then(() => {
+                        // Send ack with publicUrl so canvas can update the block
+                        this.wsSend({
+                            type: 'file-teleport-ack',
+                            fileId,
+                            status: 'completed',
+                            localPath,
+                            publicUrl,
+                        });
+                    })
+                        .catch((err) => {
+                        this.wsSend({
+                            type: 'file-teleport-ack',
+                            fileId,
+                            status: 'failed',
+                            error: err.message,
+                        });
+                    });
+                    break;
+                }
+                this.handleFileTeleport(fileId, fileName, size, contentType, downloadUrl, targetDir);
+                break;
+            }
+            case 'upload-local-file-delivery': {
+                const filePath = msg.filePath;
+                const uploadUrl = msg.uploadUrl;
+                const publicUrl = msg.publicUrl;
+                const contentType = msg.contentType;
+                const rid = msg.rid;
+                this.handleUploadLocalFile(filePath, uploadUrl, publicUrl, contentType, rid);
+                break;
+            }
+            case 'agent-tool-exec': {
+                const toolId = msg.toolId;
+                const sessionId = msg.sessionId;
+                const toolName = msg.toolName;
+                const args = msg.args;
+                // `root` (optional) = the cloud agent's bound working folder. When
+                // present, executeAgentTool JAILS every path/cwd arg to it. (#local-folder)
+                const root = msg.root;
+                this.executeAgentTool(toolId, sessionId, toolName, args, root);
+                break;
+            }
+            // ── PTY Terminal Sessions ───────────────────────────────────────
+            case 'pty-start': {
+                const sid = msg.sessionId;
+                // Idempotent: the web client re-sends pty-start on EVERY submit so a command
+                // auto-re-binds after a daemon restart. If this session is already live, reuse it —
+                // never re-spawn or count it against the session limit.
+                if (this.ptySessions.has(sid))
+                    break;
+                const ALLOWED_SHELLS = [
+                    '/bin/zsh',
+                    '/bin/bash',
+                    '/bin/sh',
+                    '/usr/bin/zsh',
+                    '/usr/bin/bash',
+                ];
+                const MAX_PTY_SESSIONS = 5;
+                if (this.ptySessions.size >= MAX_PTY_SESSIONS) {
+                    console.warn(`[relay] PTY session limit reached (${MAX_PTY_SESSIONS})`);
+                    this.wsSend({ type: 'pty-exit', sessionId: msg.sessionId, exitCode: 1 });
+                    break;
+                }
+                const cols = msg.cols || 80;
+                const rows = msg.rows || 24;
+                const cwd = msg.cwd || homedir();
+                const requestedShell = msg.shell || process.env.SHELL || '/bin/zsh';
+                const shell = ALLOWED_SHELLS.includes(requestedShell) ? requestedShell : '/bin/zsh';
+                this.ptyStart(sid, shell, cols, rows, cwd);
+                break;
+            }
+            case 'pty-input': {
+                const sid = msg.sessionId;
+                const data = msg.data;
+                // Queue until the shell integration is live (see ptyStart) so the first command isn't swallowed
+                // by the init race; write directly once ready (or if this session isn't buffered).
+                if (this.ptyReady.has(sid) || !this.ptyInputQueue.has(sid))
+                    this.ptySessions.get(sid)?.write(data);
+                else
+                    this.ptyInputQueue.get(sid).push(data);
+                break;
+            }
+            case 'pty-resize': {
+                const sid = msg.sessionId;
+                const cols = msg.cols;
+                const rows = msg.rows;
+                this.ptySessions.get(sid)?.resize(cols, rows);
+                break;
+            }
+            case 'pty-kill': {
+                const sid = msg.sessionId;
+                const pty = this.ptySessions.get(sid);
+                if (pty) {
+                    pty.kill();
+                    this.ptySessions.delete(sid);
+                }
+                this.ptyParsers.delete(sid);
+                this._cleanupPtyReady(sid);
+                cleanupIntegration(sid);
+                break;
+            }
+            case 'viewer-count': {
+                this.viewerCount = msg.count || 0;
+                break;
+            }
+            case 'pong':
+                break;
+            case 'agent-status': {
+                this.onBeeStatus?.(msg);
+                break;
+            }
+            case 'bee-thought': {
+                this.onBeeThought?.(msg.thought);
+                break;
+            }
+            case 'local-app-fetch': {
+                const { buildingType, buildingId, url, method, headers, body, rid } = msg;
+                if (this.onLocalAppFetch) {
+                    this.onLocalAppFetch(buildingType, buildingId, url || 'http://local/', method || 'GET', headers || {}, body)
+                        .then((result) => {
+                        this.wsSend({ type: 'local-app-fetch-result', rid, ...result });
+                    })
+                        .catch((err) => {
+                        this.wsSend({ type: 'local-app-fetch-result', rid, status: 500, body: err.message });
+                    });
+                }
+                else {
+                    this.wsSend({
+                        type: 'local-app-fetch-result',
+                        rid,
+                        status: 503,
+                        body: 'Local app not available',
+                    });
+                }
+                break;
+            }
+            // #74 — cross-hive RPC from the cloud Workspace.
+            //   IN:  { type: 'daemon-rpc-request', requestId, hive, action, input }
+            //   OUT: { type: 'daemon-rpc-response', requestId, ok, result?, error? }
+            // The workspace's `_daemonRpc(hive, action, input)` opens a
+            // pending promise keyed on requestId and resolves it when
+            // it sees a matching response back through the same relay.
+            // Fires before any cloud-driven cross-hive call (clipImport,
+            // brandSync, projectCreate, clipSearch, etc).
+            case 'daemon-rpc-request': {
+                const requestId = msg?.requestId;
+                const hive = msg?.hive;
+                const action = msg?.action;
+                const input = msg?.input ?? {};
+                if (!requestId || !hive || !action) {
+                    this.wsSend({
+                        type: 'daemon-rpc-response',
+                        requestId: requestId ?? 'unknown',
+                        ok: false,
+                        error: 'malformed daemon-rpc-request: requestId, hive, action all required',
+                    });
+                    break;
+                }
+                if (!this.onDaemonRpcRequest) {
+                    this.wsSend({
+                        type: 'daemon-rpc-response',
+                        requestId,
+                        ok: false,
+                        error: 'daemon-rpc handler not wired (onDaemonRpcRequest is null) — daemon may need a restart',
+                    });
+                    break;
+                }
+                const startedAt = Date.now();
+                this.onDaemonRpcRequest(hive, action, input)
+                    .then((result) => {
+                    const elapsed = Date.now() - startedAt;
+                    this.wsSend({
+                        type: 'daemon-rpc-response',
+                        requestId,
+                        ok: true,
+                        result,
+                        elapsedMs: elapsed,
+                    });
+                })
+                    .catch((err) => {
+                    const elapsed = Date.now() - startedAt;
+                    this.wsSend({
+                        type: 'daemon-rpc-response',
+                        requestId,
+                        ok: false,
+                        error: String(err?.message ?? err).slice(0, 500),
+                        elapsedMs: elapsed,
+                    });
+                });
+                break;
+            }
+            case 'error':
+                console.error(`[relay] Server error: ${msg.message}`);
+                if (msg.code === 'auth_failed') {
+                    console.error('[relay] Token rejected — sign in from the Clearly Dev Mac app tray');
+                    this.connected = false;
+                }
+                break;
+            case 'file-changed': {
+                this.onFileChanged?.(msg);
+                break;
+            }
+            default:
+                // Forward unhandled messages as broadcasts (IPC clients may want them)
+                this.onBroadcast?.(msg);
+                break;
+        }
+    }
+    /** Send a message over WebSocket. Callers waiting for a reply must check the result. */
+    wsSend(msg) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return false;
+        try {
+            this.ws.send(JSON.stringify(msg));
+            this.stats.sent++;
+            return true;
+        }
+        catch {
+            this.stats.failed++;
+            return false;
+        }
+    }
+    /** Send a message and wait for a response with matching requestId */
+    sendRequest(msg, timeout = 10_000) {
+        return new Promise((resolve, reject) => {
+            if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+                return reject(new Error('WebSocket not connected'));
+            }
+            const requestId = Math.random().toString(36).slice(2) + Date.now().toString(36);
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(requestId);
+                const action = msg.type === 'agent-invoke' ? msg.action : msg.type;
+                reject(new Error(`Request timeout after ${timeout}ms (action=${action}, requestId=${requestId}); outcome unknown`));
+            }, timeout);
+            this.pendingRequests.set(requestId, { resolve, reject, timer });
+            // Send both rid (legacy) and requestId (workspace actions) for compatibility
+            if (!this.wsSend({ ...msg, rid: requestId, requestId })) {
+                clearTimeout(timer);
+                this.pendingRequests.delete(requestId);
+                reject(new Error(`WebSocket send failed (requestId=${requestId}); send was not confirmed`));
+            }
+        });
+    }
+    // ── Reconnection ──────────────────────────────────────────────────────
+    /**
+     * Reconnect with exponential backoff + jitter.
+     *
+     * Backoff: 1s → 2s → 4s → 8s → 16s → 32s → 60s (capped). Jitter adds
+     * 0-25% of the base delay so a fleet of clients reconnecting after a
+     * server outage doesn't synchronize into a thundering herd. The cap
+     * keeps idle daemons polling at most once a minute.
+     *
+     * Single-flight: a reconnect already scheduled is a no-op. The timer
+     * is cleared on successful connect (reconnectAttempts → 0) and on
+     * stop().
+     */
+    scheduleReconnect() {
+        if (this.reconnectTimer)
+            return;
+        const baseDelay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), 60_000);
+        // Add 0-25% random jitter — `delay * (1 + 0..0.25)` keeps the
+        // floor at the exponential value so we never reconnect FASTER
+        // than the backoff intends, only slower.
+        const jitter = Math.random() * 0.25 * baseDelay;
+        const delay = Math.round(baseDelay + jitter);
+        this.reconnectAttempts++;
+        console.log(`[relay] Reconnecting in ${(delay / 1000).toFixed(1)}s (attempt ${this.reconnectAttempts})`);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            if (this.useWebSocket) {
+                this.connectWs();
+            }
+            else {
+                this.reconnectLegacy();
+            }
+        }, delay);
+    }
+    /** Start the relay health watchdog (idempotent). Every 30s: if we've been
+     *  disconnected past `maxDownMs`, force a HARD reconnect. The self-heal a
+     *  headless/orphaned daemon needs (no Mac-app tray to restart it) — a wedged
+     *  WS (half-open zombie socket after sleep) otherwise sticks "reconnecting"
+     *  forever, which `beehaven restart` had to fix by hand. */
+    startSupervisor(maxDownMs = 120_000) {
+        if (this.supervisorTimer)
+            return;
+        this.supervisorTimer = setInterval(() => {
+            if (this.stopped)
+                return;
+            if (this.connected) {
+                this.disconnectedSince = null;
+                return;
+            }
+            if (this.disconnectedSince == null) {
+                this.disconnectedSince = Date.now();
+                return;
+            }
+            if (Date.now() - this.disconnectedSince > maxDownMs) {
+                console.warn(`[relay] Watchdog: relay down ${Math.round((Date.now() - this.disconnectedSince) / 1000)}s — forcing hard reconnect`);
+                this.disconnectedSince = Date.now();
+                this.forceReconnect();
+            }
+        }, 30_000);
+    }
+    /** Hard reconnect: drop any (possibly zombie) socket, clear pending reconnect
+     *  state, reset the backoff so the next dial is immediate, then redial. */
+    forceReconnect() {
+        try {
+            this.ws?.terminate();
+        }
+        catch { }
+        this.ws = null;
+        this.connected = false;
+        this.wsConnecting = false;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.reconnectAttempts = 0;
+        if (this.useWebSocket)
+            this.connectWs();
+        else
+            this.reconnectLegacy();
+    }
+    async reconnectLegacy() {
+        const ok = await this.sendHeartbeatHttp();
+        if (ok) {
+            this.connected = true;
+            this.reconnectAttempts = 0;
+            console.log(`[relay] Reconnected (tier: ${this.tier})`);
+            if (this.heartbeatInterval)
+                clearInterval(this.heartbeatInterval);
+            this.heartbeatInterval = setInterval(() => this.sendHeartbeatHttp(), 30_000);
+            if (this.flushInterval)
+                clearInterval(this.flushInterval);
+            this.flushInterval = setInterval(() => this.flush(), FLUSH_INTERVAL_MS);
+        }
+        else {
+            this.scheduleReconnect();
+        }
+    }
+    // ── Public API ───────────────────────────────────────────────────────
+    /** Send a raw Claude Code hook event to the DO for processing */
+    sendRawEvent(event) {
+        if (!this.config || !this.connected)
+            return;
+        if (this.useWebSocket) {
+            this.wsSend({ type: 'raw-event', event });
+        }
+        else {
+            this.buffer.events.push(event);
+        }
+    }
+    /** Send system telemetry, git status, and agent metrics */
+    sendTelemetry(data) {
+        if (!this.config || !this.connected)
+            return;
+        if (this.useWebSocket) {
+            this.wsSend({ type: 'telemetry', ...data });
+        }
+    }
+    /**
+     * Announce local app capabilities to cloud. The `apps` field carries
+     * the Omni-agent catalog — compact metadata for every installed .app
+     * on the machine, so the cloud agent knows which apps and which
+     * recipes are available when reasoning about what to do for the user.
+     */
+    sendLocalAppStatus(status) {
+        this.wsSend({ type: 'local-app-status', ...status });
+    }
+    /**
+     * Advertise this daemon as a BEEHIVE in the distributed hive mesh.
+     *
+     * The Home DO's `case 'swarm-register'` upserts a durable node row (keyed by
+     * this stable deviceId) + maps deviceId → this live session, which is how the
+     * swarm knows the node is online and how the queen targets a dispatch at it.
+     * Re-sent on connect, whenever capabilities change, and on a periodic cadence
+     * (see daemon.ts `registerBeehive`) so it also serves as the beehive's
+     * keepalive and self-heals after a DO hibernation dropped the live map.
+     *
+     *   role         'queen' (orchestrator) | 'worker' (executor)
+     *   kind         'local-mac' | 'headless' | 'cloud-container'
+     *   capabilities the hive/building names this node can run (dispatch match keys)
+     */
+    sendSwarmRegister(opts) {
+        if (!this.connected)
+            return;
+        this.wsSend({
+            type: 'swarm-register',
+            deviceId: this.deviceId,
+            role: opts.role,
+            kind: opts.kind,
+            capabilities: opts.capabilities,
+            hostname: hostname(),
+            os: platform(),
+            root: homedir(),
+        });
+    }
+    /** Start periodic token self-refresh (every 50 min, for headless/long-running daemons) */
+    tokenRefreshTimer = null;
+    startTokenRefresh() {
+        if (this.tokenRefreshTimer)
+            return;
+        const REFRESH_INTERVAL = 50 * 60 * 1000;
+        const doRefresh = async () => {
+            const ok = await this.refreshIdToken();
+            if (!ok) {
+                console.log('[relay] Token refresh failed — will retry in 5 minutes');
+                setTimeout(doRefresh, 5 * 60 * 1000);
+            }
+        };
+        // Initial refresh after a short delay (gives time for first connection)
+        setTimeout(doRefresh, 30_000);
+        this.tokenRefreshTimer = setInterval(doRefresh, REFRESH_INTERVAL);
+    }
+    /** Refresh the auth token via the relay's /auth/refresh endpoint.
+     *  Sends the stored refresh token to the relay Worker, which handles
+     *  the Firebase token exchange server-side. */
+    async refreshIdToken() {
+        const cfg = Relay.loadConfig();
+        if (!cfg?.refreshToken) {
+            return false;
+        }
+        try {
+            const base = this.wsBase().replace('wss://', 'https://').replace('ws://', 'http://');
+            const resp = await fetch(`${base}/auth/refresh`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ refreshToken: cfg.refreshToken }),
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (!resp.ok) {
+                return false;
+            }
+            const data = (await resp.json());
+            if (!data.token)
+                return false;
+            // Update config + keychain with the fresh tokens. Both must
+            // be in sync — Relay.loadConfig() reads from keychain when
+            // tokenStorage='keychain', so a stale keychain after a
+            // successful in-memory refresh would cause every subsequent
+            // daemon restart to dial the WebSocket with an expired
+            // idToken and burn another refresh round-trip.
+            try {
+                const raw = readFileSync(CONFIG_FILE, 'utf8');
+                const config = JSON.parse(raw);
+                config.token = data.token;
+                if (data.refreshToken)
+                    config.refreshToken = data.refreshToken;
+                writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+                try {
+                    chmodSync(CONFIG_FILE, 0o600);
+                }
+                catch { }
+                // Mirror to keychain via `security` so the next daemon
+                // launch's loadConfig reads a fresh idToken. execSync
+                // avoids importing keychain.ts (which is ESM-only and
+                // would create circular import drama).
+                if (config.tokenStorage === 'keychain') {
+                    try {
+                        execSync(`security delete-generic-password -s beehaven -a daemon-token`, {
+                            stdio: 'ignore',
+                        });
+                    }
+                    catch { } // entry didn't exist; fine
+                    execSync(`security add-generic-password -s beehaven -a daemon-token -w '${data.token.replace(/'/g, "'\\''")}'`, { stdio: ['ignore', 'ignore', 'pipe'] });
+                }
+            }
+            catch { }
+            // Update in-memory config
+            if (this.config) {
+                this.config.token = data.token;
+            }
+            console.log('[relay] Token refreshed successfully');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Queue docs for next flush */
+    uploadDocs(project, projectRoot) {
+        if (!this.config || !this.connected)
+            return;
+        const DOC_FILES = ['README.md', 'CLAUDE.md', 'package.json'];
+        const docs = [];
+        for (const name of DOC_FILES) {
+            const filePath = join(projectRoot, name);
+            if (!existsSync(filePath))
+                continue;
+            try {
+                const content = readFileSync(filePath, 'utf8');
+                if (content.length > 500_000)
+                    continue;
+                docs.push({ name, content });
+            }
+            catch {
+                continue;
+            }
+        }
+        if (docs.length > 0) {
+            this.buffer.docs.push({ project, docs });
+        }
+    }
+    // ── Commands (web → local) ────────────────────────────────────────────
+    // DISABLED: Programmatic Claude orchestration not permitted — Anthropic credential use policy
+    // https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use
+    // /** Commands arrive over WebSocket — no polling needed */
+    // ── Hook Events (local → web) ────────────────────────────────────────
+    /** Send a hook event to the web client — immediate over WebSocket */
+    sendHookEvent(webSessionId, event) {
+        if (!this.config || !this.connected)
+            return;
+        if (this.useWebSocket) {
+            this.wsSend({
+                type: 'hook-events',
+                sessionId: webSessionId,
+                events: [
+                    {
+                        hook_event_name: event.hook_event_name,
+                        tool_name: event.tool_name,
+                        tool_input: event.tool_input,
+                        error: event.error,
+                        prompt: event.prompt,
+                        agent_type: event.agent_type,
+                        message: event.message,
+                        task_subject: event.task_subject,
+                        timestamp: event.timestamp,
+                    },
+                ],
+            });
+        }
+    }
+    // ── File Browser (web → daemon → web) ────────────────────────────────
+    /** Send browse-files result back to the web client via DO */
+    sendBrowseFilesResult(path, entries, rid, error) {
+        if (!this.connected)
+            return;
+        this.wsSend({
+            type: 'browse-files-result',
+            path,
+            entries,
+            error,
+            rid,
+        });
+    }
+    // ── Session Events (local → web) ─────────────────────────────────────
+    /** Send a session event — immediate over WebSocket, batched for legacy HTTP */
+    sendSessionEvent(sessionId, event) {
+        if (!this.config || !this.connected) {
+            return;
+        }
+        if (this.useWebSocket) {
+            this.wsSend({ type: 'session-events', sessionId, events: [event] });
+        }
+        else {
+            const batch = this.sessionEventBatch.get(sessionId) || [];
+            batch.push(event);
+            this.sessionEventBatch.set(sessionId, batch);
+        }
+    }
+    // ── One-off Requests ──────────────────────────────────────────────────
+    /** Verify a token by sending a heartbeat (always uses HTTP) */
+    async verifyToken(token, endpoint) {
+        const url = this.httpUrl(endpoint);
+        try {
+            const resp = await fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+                body: JSON.stringify({ type: 'heartbeat', deviceId: this.deviceId }),
+                signal: AbortSignal.timeout(10000),
+            });
+            if (!resp.ok)
+                return null;
+            const json = await resp.json();
+            if (!json.ok)
+                return null;
+            return json.profile || { verified: true };
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Delete the relay session server-side (used on uninstall) */
+    async deleteSession(token, endpoint) {
+        const t = token || this.config?.token;
+        if (!t)
+            return;
+        const url = this.httpUrl(endpoint);
+        try {
+            await fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${t}` },
+                body: JSON.stringify({ type: 'delete-session', deviceId: this.deviceId }),
+                signal: AbortSignal.timeout(5000),
+            });
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    /** Upload a session transcript to Cloud Storage */
+    async uploadTranscript(transcriptPath, sessionId, project) {
+        if (!this.config || !this.connected)
+            return;
+        if (!existsSync(transcriptPath))
+            return;
+        try {
+            const fileSize = statSync(transcriptPath).size;
+            if (fileSize > 10 * 1024 * 1024)
+                return; // Skip > 10MB
+            let uploadUrl = null;
+            if (this.useWebSocket) {
+                const resp = await this.sendRequest({
+                    type: 'get-upload-url',
+                    path: `transcripts/${sessionId}.jsonl`,
+                    contentType: 'application/x-ndjson',
+                });
+                uploadUrl = resp?.uploadUrl || null;
+            }
+            else {
+                const resp = await this.postHttp({
+                    type: 'get-upload-url',
+                    path: `transcripts/${sessionId}.jsonl`,
+                    contentType: 'application/x-ndjson',
+                });
+                uploadUrl = resp?.uploadUrl || null;
+            }
+            if (!uploadUrl)
+                return;
+            const content = readFileSync(transcriptPath);
+            const uploadResp = await fetch(uploadUrl, {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/x-ndjson' },
+                body: content,
+                signal: AbortSignal.timeout(30_000),
+            });
+            if (uploadResp.ok) {
+                this.lastSyncAt = Date.now();
+                if (project) {
+                    const existing = this.projectSyncDetails.get(project);
+                    if (existing) {
+                        existing.transcriptUploaded = true;
+                        existing.lastSyncAt = Date.now();
+                    }
+                }
+                console.log(`[relay] Transcript uploaded: ${sessionId} (${(fileSize / 1024).toFixed(0)}KB)`);
+            }
+        }
+        catch (err) {
+            console.error(`[relay] Transcript upload error: ${err.message}`);
+        }
+    }
+    /** Upload a saved session JSON file to R2 storage */
+    async uploadSession(sessionPath, sessionId) {
+        if (!this.config || !this.connected)
+            return false;
+        if (!existsSync(sessionPath))
+            return false;
+        try {
+            const fileSize = statSync(sessionPath).size;
+            if (fileSize > 5 * 1024 * 1024)
+                return false;
+            let uploadUrl = null;
+            if (this.useWebSocket) {
+                const resp = await this.sendRequest({
+                    type: 'get-upload-url',
+                    path: `sessions/${sessionId}.json`,
+                    contentType: 'application/json',
+                });
+                uploadUrl = resp?.uploadUrl || null;
+            }
+            else {
+                const resp = await this.postHttp({
+                    type: 'get-upload-url',
+                    path: `sessions/${sessionId}.json`,
+                    contentType: 'application/json',
+                });
+                uploadUrl = resp?.uploadUrl || null;
+            }
+            if (!uploadUrl)
+                return false;
+            const content = readFileSync(sessionPath);
+            const uploadResp = await fetch(uploadUrl, {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/json' },
+                body: content,
+                signal: AbortSignal.timeout(30_000),
+            });
+            if (uploadResp.ok) {
+                this.lastSyncAt = Date.now();
+                return true;
+            }
+            return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Fetch building state (always uses HTTP) */
+    async getBuilding() {
+        if (!this.config)
+            return null;
+        try {
+            const resp = await this.postHttp({ type: 'building' });
+            return resp?.building || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Claim a desk in a building (always uses HTTP) */
+    async selectDesk(floor, desk) {
+        if (!this.config)
+            return false;
+        try {
+            const resp = await this.postHttp({ type: 'claim-desk', floor, desk });
+            return resp?.ok === true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // ── Folder Sync ───────────────────────────────────────────────────────
+    async syncFileUpload(brandId, relativePath, content, hash) {
+        if (!this.config || !this.connected)
+            return;
+        try {
+            const contentType = this.getMimeType(relativePath);
+            let uploadUrl = null;
+            if (this.useWebSocket) {
+                const resp = await this.sendRequest({
+                    type: 'get-upload-url',
+                    path: `projects/${brandId}/assets/${relativePath}`,
+                    contentType,
+                });
+                uploadUrl = resp?.uploadUrl || null;
+            }
+            else {
+                const result = await this.postHttp({
+                    type: 'get-upload-url',
+                    path: `projects/${brandId}/assets/${relativePath}`,
+                    contentType,
+                });
+                uploadUrl = result?.uploadUrl || null;
+            }
+            if (!uploadUrl)
+                return;
+            await fetch(uploadUrl, {
+                method: 'PUT',
+                headers: { 'Content-Type': contentType },
+                body: new Uint8Array(content),
+                signal: AbortSignal.timeout(30_000),
+            });
+            const fileMsg = {
+                type: 'file-sync',
+                brandId,
+                action: 'upsert',
+                file: {
+                    path: relativePath,
+                    hash,
+                    size: content.length,
+                    storagePath: `projects/${brandId}/assets/${relativePath}`,
+                },
+            };
+            if (this.useWebSocket) {
+                this.wsSend(fileMsg);
+            }
+            else {
+                await this.postHttp(fileMsg);
+            }
+            this.lastSyncAt = Date.now();
+        }
+        catch (err) {
+            console.error(`[relay] File upload failed (${relativePath}): ${err.message}`);
+        }
+    }
+    // ── Security helpers for cloud-driven local file transfer ────────────
+    // The cloud→daemon WS dispatches on msg.type with NO per-message auth, so
+    // these handlers must assume a frame may be hostile (injected agent /
+    // compromised relay). Restrict transfer endpoints + protected paths.
+    static isAllowedTransferUrl(rawUrl) {
+        try {
+            const u = new URL(rawUrl);
+            if (u.protocol !== 'https:')
+                return false;
+            const h = u.hostname.toLowerCase();
+            return [
+                /(^|\.)r2\.cloudflarestorage\.com$/,
+                /(^|\.)r2\.dev$/,
+                /(^|\.)clearly\.sh$/,
+                /(^|\.)clearly-sh\.pages\.dev$/,
+            ].some((re) => re.test(h));
+        }
+        catch {
+            return false;
+        }
+    }
+    static isSensitivePath(p) {
+        const s = String(p || '');
+        return [
+            /\/\.ssh\//,
+            /\/\.aws\//,
+            /\/\.config\/gcloud\//,
+            /\/\.gnupg\//,
+            /\/\.beehaven\//,
+            /\/Library\/LaunchAgents\//,
+            /\/Library\/LaunchDaemons\//,
+            /id_rsa|id_ed25519/,
+            /\.pem$|\.key$|\.p12$/,
+            /(^|\/)\.env(\.|$)/,
+            /(^|\/)\.(zshrc|zshenv|zprofile|bashrc|bash_profile|profile)$/,
+        ].some((re) => re.test(s));
+    }
+    /** Read a local file and upload it to R2 via presigned URL */
+    async handleUploadLocalFile(filePath, uploadUrl, publicUrl, contentType, rid) {
+        try {
+            const { readFileSync, statSync } = await import('fs');
+            const resolved = filePath.startsWith('~') ? join(homedir(), filePath.slice(1)) : filePath;
+            // SECURITY: only upload to Clearly R2, and never read credential/key
+            // material — otherwise an injected frame exfiltrates local secrets.
+            if (!Relay.isAllowedTransferUrl(uploadUrl))
+                throw new Error('upload destination not allowed');
+            if (Relay.isSensitivePath(resolved))
+                throw new Error('refusing to read protected path');
+            const stat = statSync(resolved);
+            const data = readFileSync(resolved);
+            console.log(`[relay] Uploading local file to R2: ${resolved} (${(stat.size / 1024).toFixed(0)}KB)`);
+            const resp = await fetch(uploadUrl, {
+                method: 'PUT',
+                headers: { 'Content-Type': contentType },
+                body: data,
+            });
+            if (!resp.ok) {
+                throw new Error(`R2 upload failed: ${resp.status} ${resp.statusText}`);
+            }
+            console.log(`[relay] Local file uploaded successfully: ${publicUrl}`);
+            this.wsSend({
+                type: 'upload-local-file-result',
+                rid,
+                filePath,
+                publicUrl,
+                status: 'completed',
+                size: stat.size,
+            });
+        }
+        catch (err) {
+            console.error(`[relay] Failed to upload local file: ${err.message}`);
+            this.wsSend({
+                type: 'upload-local-file-result',
+                rid,
+                filePath,
+                publicUrl,
+                status: 'failed',
+                error: err.message,
+            });
+        }
+    }
+    /** Download a teleported file from R2 and save to local filesystem */
+    async handleFileTeleport(fileId, fileName, size, contentType, downloadUrl, targetDir) {
+        try {
+            // SECURITY: confine writes to the teleport root and only download
+            // from Clearly R2. Previously an arbitrary absolute targetDir let a
+            // cloud frame write ~/.zshrc, ~/Library/LaunchAgents, etc. → RCE.
+            if (!Relay.isAllowedTransferUrl(downloadUrl))
+                throw new Error('download source not allowed');
+            const teleportRoot = join(homedir(), 'Downloads', 'clearly-teleport');
+            // Honor a caller subdir only if it's a simple alnum name (cannot
+            // escape the root); an arbitrary absolute targetDir is ignored.
+            const sub = String(targetDir || '').replace(/[^a-z0-9_-]/gi, '');
+            const baseDir = sub ? join(teleportRoot, sub) : teleportRoot;
+            const safeName = fileName.replace(/\.\./g, '').replace(/[/\\]/g, '_');
+            const savePath = join(baseDir, safeName);
+            // Ensure directory exists
+            mkdirSync(dirname(savePath), { recursive: true });
+            // Check if file already exists with matching size — skip re-download
+            if (existsSync(savePath)) {
+                const existing = statSync(savePath);
+                if (size > 0 && Math.abs(existing.size - size) / size < 0.01) {
+                    console.log(`[relay] File already exists, skipping download: ${savePath} (${(existing.size / 1024).toFixed(0)}KB)`);
+                    this.wsSend({
+                        type: 'file-teleport-ack',
+                        fileId,
+                        status: 'completed',
+                        localPath: savePath,
+                    });
+                    this.onFileTeleported?.({
+                        fileId,
+                        fileName,
+                        localPath: savePath,
+                        size: existing.size,
+                        contentType,
+                    });
+                    return;
+                }
+                console.log(`[relay] File exists but size differs (local: ${existing.size}, remote: ${size}), re-downloading`);
+            }
+            // Stream download from R2 presigned URL
+            const resp = await fetch(downloadUrl, {
+                signal: AbortSignal.timeout(300_000), // 5 min timeout for large files
+            });
+            if (!resp.ok) {
+                throw new Error(`Download failed: ${resp.status} ${resp.statusText}`);
+            }
+            // Read as buffer and write to disk
+            const buffer = Buffer.from(await resp.arrayBuffer());
+            writeFileSync(savePath, buffer);
+            console.log(`[relay] File teleported: ${savePath} (${(buffer.length / 1024).toFixed(0)}KB)`);
+            // Send ack back to web
+            this.wsSend({
+                type: 'file-teleport-ack',
+                fileId,
+                status: 'completed',
+                localPath: savePath,
+            });
+            // Notify callback
+            this.onFileTeleported?.({
+                fileId,
+                fileName,
+                localPath: savePath,
+                size: buffer.length,
+                contentType,
+            });
+        }
+        catch (err) {
+            console.error(`[relay] File teleport failed (${fileName}): ${err.message}`);
+            this.wsSend({
+                type: 'file-teleport-ack',
+                fileId,
+                status: 'failed',
+                error: err.message,
+            });
+        }
+    }
+    // ── Agent Tool Execution (bee agent → local machine) ────────────────
+    /** Execute a tool call from the bee agent on the local filesystem */
+    async executeAgentTool(toolId, sessionId, toolName, args, root) {
+        const startMs = Date.now();
+        // Audit log
+        const sanitizedPath = args?.path ? String(args.path).slice(0, 200) : '';
+        console.log(`[agent-tool] ${toolName} ${sanitizedPath}`);
+        // ── JAIL to the bound working folder (#local-folder Phase 2.5) ───────────
+        // When the cloud agent is scoped to a folder, the DO sends `root`; confine
+        // every path/cwd arg to it (lexical, strict) so an out-of-folder read /
+        // write / edit / exec is REFUSED — including prompt-injected ones (a repo
+        // file telling the model to read ~/Documents). Upstream reads are ungated,
+        // so this is the real scope boundary; isSensitivePath + the HIVE_DEV_MODE
+        // bash gate still apply on top. No `root` (other callers) → skip, so
+        // existing behavior is unchanged. NOTE: lexical only — a symlink inside the
+        // folder pointing out is not resolved (realpath hardening = follow-up).
+        if (root && typeof root === 'string' && args && typeof args === 'object') {
+            const confine = (field) => {
+                const v = args[field];
+                if (typeof v !== 'string' || !v)
+                    return null;
+                const r = transformPath(v, { compositionCwd: root, outOfScopePolicy: 'strict' });
+                if (r.absolutePath === null)
+                    return r.reason || `${field} is outside the working folder`;
+                args[field] = r.absolutePath;
+                return null;
+            };
+            // Default a missing directory to the folder root (else ls/grep/bash fall
+            // back to $HOME — outside the jail).
+            if ((toolName === 'ls' || toolName === 'grep') && !args.path)
+                args.path = root;
+            if (toolName === 'bash' && !args.cwd)
+                args.cwd = root;
+            let scopeErr = null;
+            if (['read', 'write', 'edit', 'ls', 'grep'].includes(toolName))
+                scopeErr = confine('path');
+            else if (toolName === 'glob')
+                scopeErr = confine('pattern') || confine('path');
+            else if (toolName === 'bash')
+                scopeErr = confine('cwd');
+            if (scopeErr) {
+                this.wsSend({
+                    type: 'agent-tool-exec-result',
+                    toolId,
+                    sessionId,
+                    result: '',
+                    error: `Refused: ${scopeErr}. This agent is scoped to ${root} — stay inside it, or ask the user to re-point the working folder.`,
+                    durationMs: Date.now() - startMs,
+                });
+                return;
+            }
+        }
+        // SECURITY: bash / workspace-exec are arbitrary local command execution.
+        // The cloud→daemon channel is unauthenticated per message, so gate the
+        // RCE primitives behind explicit Developer Mode (HIVE_DEV_MODE=1).
+        /**
+         * ⚠ THE SAME PREDICATE THE DAEMON USES. This tested `HIVE_DEV_MODE !== '1'` while the daemon
+         * accepted `'true'` as well, so `HIVE_DEV_MODE=true` produced a daemon in developer mode whose
+         * relay path still refused `bash` — a split nothing reports, and which reads as a broken gate.
+         * It also means a RELEASED build cannot unlock local command execution at all.
+         */
+        if ((toolName === 'bash' || toolName === 'workspace-exec') && !devModeAvailable()) {
+            this.wsSend({
+                type: 'agent-tool-exec-result',
+                toolId,
+                sessionId,
+                result: '',
+                error: `tool '${toolName}' requires Developer Mode. ${devModeRefusal()}`,
+                durationMs: Date.now() - startMs,
+            });
+            return;
+        }
+        try {
+            let result;
+            switch (toolName) {
+                case 'read':
+                    result = this.agentRead(args);
+                    break;
+                case 'write':
+                    result = this.agentWrite(args);
+                    break;
+                case 'edit':
+                    result = this.agentEdit(args);
+                    break;
+                case 'glob':
+                    result = this.agentGlob(args);
+                    break;
+                case 'ls':
+                    result = this.agentLs(args);
+                    break;
+                case 'grep':
+                    result = this.agentGrep(args);
+                    break;
+                case 'bash':
+                    result = this.agentBash(args);
+                    break;
+                case 'workspace-init':
+                    result = this.workspaceInit(args);
+                    break;
+                case 'workspace-sync':
+                    result = await this.workspaceSync(args);
+                    break;
+                case 'workspace-exec':
+                    result = this.workspaceExec(args);
+                    break;
+                case 'workspace-upload':
+                    result = await this.workspaceUpload(args);
+                    break;
+                default:
+                    result = `Unknown tool: ${toolName}`;
+            }
+            this.wsSend({
+                type: 'agent-tool-exec-result',
+                toolId,
+                sessionId,
+                result,
+                durationMs: Date.now() - startMs,
+            });
+        }
+        catch (err) {
+            this.wsSend({
+                type: 'agent-tool-exec-result',
+                toolId,
+                sessionId,
+                result: '',
+                error: err.message || String(err),
+                durationMs: Date.now() - startMs,
+            });
+        }
+    }
+    agentRead(args) {
+        const filePath = args.path;
+        if (!filePath)
+            return 'Error: path is required';
+        if (Relay.isSensitivePath(filePath))
+            return 'Error: refusing to read protected path';
+        if (!existsSync(filePath))
+            return `File not found: ${filePath}`;
+        const stat = statSync(filePath);
+        if (stat.isDirectory())
+            return `Error: ${filePath} is a directory, not a file`;
+        if (stat.size > 5 * 1024 * 1024)
+            return `Error: File too large (${Math.round(stat.size / 1024)}KB). Max 5MB.`;
+        const text = readFileSync(filePath, 'utf8');
+        const lines = text.split('\n');
+        const offset = Math.max(0, (args.offset || 1) - 1);
+        const limit = args.limit || lines.length;
+        const slice = lines.slice(offset, offset + limit);
+        const numbered = slice
+            .map((line, i) => {
+            const lineNum = String(offset + i + 1).padStart(6, ' ');
+            return `${lineNum}\t${line}`;
+        })
+            .join('\n');
+        return numbered.length > 50_000 ? numbered.slice(0, 50_000) + '\n... (truncated)' : numbered;
+    }
+    agentWrite(args) {
+        const filePath = args.path;
+        const content = args.content;
+        if (!filePath || content === undefined)
+            return 'Error: path and content are required';
+        if (Relay.isSensitivePath(filePath))
+            return 'Error: refusing to write protected path';
+        const dir = dirname(filePath);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(filePath, content, 'utf8');
+        return `File written: ${filePath} (${content.length} bytes)`;
+    }
+    agentEdit(args) {
+        const filePath = args.path;
+        const oldStr = args.old_string;
+        const newStr = args.new_string;
+        if (!filePath || !oldStr || newStr === undefined)
+            return 'Error: path, old_string, and new_string are required';
+        if (Relay.isSensitivePath(filePath))
+            return 'Error: refusing to edit protected path';
+        if (!existsSync(filePath))
+            return `File not found: ${filePath}`;
+        const text = readFileSync(filePath, 'utf8');
+        const occurrences = text.split(oldStr).length - 1;
+        if (occurrences === 0)
+            return `Error: old_string not found in ${filePath}`;
+        if (occurrences > 1)
+            return `Error: old_string appears ${occurrences} times — must be unique`;
+        const newText = text.replace(oldStr, newStr);
+        writeFileSync(filePath, newText, 'utf8');
+        return `File edited: ${filePath} (1 replacement)`;
+    }
+    agentGlob(args) {
+        let pattern = args.pattern || args.path;
+        if (!pattern)
+            return 'Error: pattern is required';
+        // Normalize double slashes (e.g. /home/user//* → /home/user/*)
+        pattern = pattern.replace(/\/\//g, '/');
+        const globStart = pattern.search(/[*?{[]/);
+        const baseDir = globStart >= 0 ? pattern.slice(0, pattern.lastIndexOf('/', globStart) + 1) || '.' : pattern;
+        if (!existsSync(baseDir))
+            throw new Error(`Directory not found: ${baseDir}`);
+        const matches = [];
+        const globRegex = this.patternToRegex(pattern);
+        this.walkDir(baseDir, matches, globRegex, 500, 8);
+        return matches.length > 0
+            ? `Found ${matches.length} files:\n${matches.join('\n')}`
+            : `No files matching "${pattern}"`;
+    }
+    agentLs(args) {
+        const dirPath = args.path || homedir();
+        if (!existsSync(dirPath))
+            throw new Error(`Directory not found: ${dirPath}`);
+        const stat = statSync(dirPath);
+        if (!stat.isDirectory())
+            throw new Error(`Not a directory: ${dirPath}`);
+        try {
+            const entries = readdirSync(dirPath, { withFileTypes: true });
+            const lines = [];
+            for (const entry of entries) {
+                if (entry.name.startsWith('.'))
+                    continue; // skip hidden files
+                const fullPath = join(dirPath, entry.name);
+                if (entry.isDirectory()) {
+                    lines.push(`${entry.name}/`);
+                }
+                else {
+                    try {
+                        const fstat = statSync(fullPath);
+                        const sizeStr = fstat.size > 1024 ? `${Math.round(fstat.size / 1024)}KB` : `${fstat.size}B`;
+                        lines.push(`${entry.name}  (${sizeStr})`);
+                    }
+                    catch {
+                        lines.push(entry.name);
+                    }
+                }
+            }
+            if (lines.length === 0)
+                return `Empty directory: ${dirPath}`;
+            return lines.join('\n');
+        }
+        catch (err) {
+            throw new Error(`Failed to read directory ${dirPath}: ${err.message}`);
+        }
+    }
+    agentGrep(args) {
+        const pattern = args.pattern;
+        const searchPath = args.path || homedir();
+        if (!pattern)
+            return 'Error: pattern is required';
+        try {
+            const output = execFileSync('grep', ['-rn', '--include=*', pattern, searchPath], {
+                cwd: searchPath,
+                timeout: 30_000,
+                maxBuffer: 1024 * 1024,
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            return output.length > 50_000 ? output.slice(0, 50_000) + '\n... (truncated)' : output;
+        }
+        catch (err) {
+            // grep returns exit code 1 when no matches found
+            if (err.status === 1)
+                return `No matches for "${pattern}" in ${searchPath}`;
+            const stderr = err.stderr ? String(err.stderr).slice(0, 2000) : '';
+            return stderr || err.message || 'grep failed';
+        }
+    }
+    agentBash(args) {
+        const command = args.command;
+        if (!command)
+            return 'Error: command is required';
+        let cwd = args.cwd || homedir();
+        // Resolve virtual /local/ prefix from cloud agent
+        if (cwd.startsWith('/local/')) {
+            cwd = cwd.slice('/local'.length); // /local/Users/foo → /Users/foo
+        }
+        // If path doesn't exist, try resolving relative to $HOME
+        // (handles /Documents → ~/Documents, /projects → ~/projects, etc.)
+        if (!existsSync(cwd) && cwd.startsWith('/')) {
+            const asHome = join(homedir(), cwd);
+            if (existsSync(asHome)) {
+                cwd = asHome;
+            }
+        }
+        if (!existsSync(cwd)) {
+            return `Error: working directory does not exist: ${cwd} (also tried ${join(homedir(), cwd)})`;
+        }
+        const timeout = Math.min(args.timeout || 30_000, 120_000);
+        try {
+            const output = execSync(command, {
+                cwd,
+                timeout,
+                maxBuffer: 1024 * 1024,
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+                env: { ...process.env, TERM: 'dumb' },
+            });
+            return output.length > 50_000 ? output.slice(0, 50_000) + '\n... (truncated)' : output;
+        }
+        catch (err) {
+            const stderr = err.stderr ? String(err.stderr).slice(0, 2000) : '';
+            const stdout = err.stdout ? String(err.stdout).slice(0, 2000) : '';
+            const output = stdout || stderr || err.message || 'Command failed';
+            return `Exit code ${err.status || 1}\n${output}`;
+        }
+    }
+    // ── PTY Terminal ────────────────────────────────────────────────────
+    /** Mark a managed PTY ready (its shell integration is live) and flush any input typed before then. */
+    _markPtyReady(sessionId) {
+        if (this.ptyReady.has(sessionId))
+            return;
+        this.ptyReady.add(sessionId);
+        const timer = this.ptyReadyTimers.get(sessionId);
+        if (timer) {
+            clearTimeout(timer);
+            this.ptyReadyTimers.delete(sessionId);
+        }
+        const queued = this.ptyInputQueue.get(sessionId);
+        this.ptyInputQueue.delete(sessionId);
+        const pty = this.ptySessions.get(sessionId);
+        if (pty && queued)
+            for (const d of queued) {
+                try {
+                    pty.write(d);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+    }
+    /** Drop a PTY's readiness / queue / timer state (on kill or exit). */
+    _cleanupPtyReady(sessionId) {
+        const timer = this.ptyReadyTimers.get(sessionId);
+        if (timer)
+            clearTimeout(timer);
+        this.ptyReadyTimers.delete(sessionId);
+        this.ptyInputQueue.delete(sessionId);
+        this.ptyReady.delete(sessionId);
+    }
+    /** Spawn a PTY session with node-pty (optional dependency) */
+    async ptyStart(sessionId, shell, cols, rows, cwd) {
+        try {
+            // @ts-ignore — optional native dependency
+            const pty = await import('node-pty');
+            // Resolve virtual /local/ prefix from cloud agent
+            let resolvedCwd = cwd;
+            if (resolvedCwd?.startsWith('/local/')) {
+                resolvedCwd = resolvedCwd.slice('/local'.length);
+            }
+            // Try resolving relative to $HOME if absolute path doesn't exist
+            if (resolvedCwd && !existsSync(resolvedCwd) && resolvedCwd.startsWith('/')) {
+                const asHome = join(homedir(), resolvedCwd);
+                if (existsSync(asHome))
+                    resolvedCwd = asHome;
+            }
+            if (!resolvedCwd || !existsSync(resolvedCwd)) {
+                resolvedCwd = homedir();
+            }
+            // Filter sensitive environment variables before passing to PTY
+            const filteredEnv = { ...process.env };
+            for (const key of Object.keys(filteredEnv)) {
+                if (SENSITIVE_ENV_PATTERNS.includes(key) ||
+                    SENSITIVE_ENV_SUFFIXES.some((s) => key.endsWith(s))) {
+                    delete filteredEnv[key];
+                }
+            }
+            // Inject OSC-633 shell integration (sources the user's real rc first,
+            // then adds prompt markers) so we can slice the stream into blocks.
+            const integ = writeIntegration(sessionId, shell);
+            // A canvas prompt-bar shell session is `prompt-shell-<compositionId>`. Expose that
+            // composition id to the PTY so an interactive `claude` launched inside it inherits
+            // CLEARLY_CANVAS_COMPOSITION — its UserPromptSubmit/PostToolUse/Stop hooks then post
+            // prompt→tool→response blocks onto THIS composition (and stay silent elsewhere).
+            const canvasComp = sessionId.startsWith('prompt-shell-')
+                ? sessionId.slice('prompt-shell-'.length)
+                : '';
+            const ptyProcess = pty.spawn(shell, integ.args, {
+                name: 'xterm-256color',
+                cols,
+                rows,
+                cwd: resolvedCwd,
+                env: {
+                    ...filteredEnv,
+                    ...integ.env,
+                    ...(canvasComp && canvasComp !== 'scratch'
+                        ? { CLEARLY_CANVAS_COMPOSITION: canvasComp }
+                        : {}),
+                },
+            });
+            this.ptySessions.set(sessionId, ptyProcess);
+            // Block parser — fed the SAME bytes as pty-output (it never consumes them,
+            // so the live xterm is unaffected); emits a terminal-block per completed
+            // command, which the DO mints as a canvas frame.
+            const parser = new TerminalBlockParser((block) => {
+                this.wsSend({ type: 'terminal-block', sessionId, ...block });
+            });
+            this.ptyParsers.set(sessionId, parser);
+            // Buffer input until the OSC-633 integration prints its first prompt (marker A/B) — the first
+            // command otherwise races the shell's rc-sourcing and runs with no markers → no terminal-block.
+            // Fallback: flush after a grace period if no marker ever arrives (integration absent).
+            this.ptyInputQueue.set(sessionId, []);
+            this.ptyReady.delete(sessionId);
+            this.ptyReadyTimers.set(sessionId, setTimeout(() => this._markPtyReady(sessionId), 2500));
+            ptyProcess.onData((data) => {
+                this.wsSend({ type: 'pty-output', sessionId, data });
+                this.onPtyOutput?.({ type: 'pty-output', sessionId, data });
+                try {
+                    parser.write(data);
+                }
+                catch {
+                    /* parsing must never break the live stream */
+                }
+                if (!this.ptyReady.has(sessionId) && /\x1b\]633;[AB]/.test(data))
+                    this._markPtyReady(sessionId);
+            });
+            ptyProcess.onExit(({ exitCode }) => {
+                this.ptySessions.delete(sessionId);
+                this.ptyParsers.delete(sessionId);
+                this._cleanupPtyReady(sessionId);
+                cleanupIntegration(sessionId);
+                this.wsSend({ type: 'pty-exit', sessionId, exitCode });
+                this.onPtyOutput?.({ type: 'pty-exit', sessionId, exitCode });
+            });
+            console.log(`[relay] PTY started: ${sessionId} (${shell}, ${cols}x${rows}, ${cwd})`);
+        }
+        catch (err) {
+            console.error(`[relay] PTY start failed: ${err.message}`);
+            this.wsSend({ type: 'pty-exit', sessionId, exitCode: 1 });
+        }
+    }
+    // ── Workspace Sync (Tier 2) ─────────────────────────────────────────
+    /** Workspace state — maps workspaceId to temp dir path */
+    workspaces = new Map();
+    /** Auto-clean stale workspaces every 5 minutes */
+    cleanupWorkspacesIfNeeded() {
+        const now = Date.now();
+        for (const [id, ws] of this.workspaces) {
+            if (now - ws.lastUsed > 10 * 60_000) {
+                // Clean up temp dir
+                try {
+                    rmSync(ws.path, { recursive: true, force: true });
+                }
+                catch {
+                    /* ignore */
+                }
+                this.workspaces.delete(id);
+            }
+        }
+    }
+    workspaceInit(args) {
+        const workspaceId = String(args.workspaceId ?? '').replace(/[^a-zA-Z0-9_-]/g, '');
+        if (!workspaceId)
+            return JSON.stringify({
+                error: 'workspaceId is required (alphanumeric, hyphens, underscores only)',
+            });
+        this.cleanupWorkspacesIfNeeded();
+        const existing = this.workspaces.get(workspaceId);
+        if (existing && existsSync(existing.path)) {
+            existing.lastUsed = Date.now();
+            // Scan existing files for manifest
+            const files = this.scanWorkspaceFiles(existing.path);
+            return JSON.stringify({ path: existing.path, existingFiles: files });
+        }
+        // Create new workspace
+        const tmpDir = join(homedir(), '.beehaven', 'workspaces', workspaceId);
+        mkdirSync(tmpDir, { recursive: true });
+        this.workspaces.set(workspaceId, { path: tmpDir, lastUsed: Date.now() });
+        return JSON.stringify({ path: tmpDir, existingFiles: [] });
+    }
+    async workspaceSync(args) {
+        const workspaceId = args.workspaceId;
+        const files = args.files;
+        if (!workspaceId || !files)
+            return JSON.stringify({ synced: 0, errors: ['Missing args'] });
+        const ws = this.workspaces.get(workspaceId);
+        if (!ws)
+            return JSON.stringify({ synced: 0, errors: ['Workspace not found'] });
+        ws.lastUsed = Date.now();
+        let synced = 0;
+        const errors = [];
+        // Download files in parallel (max 5 concurrent)
+        const CONCURRENCY = 5;
+        for (let i = 0; i < files.length; i += CONCURRENCY) {
+            const batch = files.slice(i, i + CONCURRENCY);
+            await Promise.all(batch.map(async (f) => {
+                try {
+                    // H1: Reject path traversal
+                    if (!f.relativePath ||
+                        f.relativePath.includes('..') ||
+                        f.relativePath.startsWith('/')) {
+                        errors.push(`${f.relativePath}: rejected (path traversal)`);
+                        return;
+                    }
+                    // H4: Reject non-HTTPS download URLs and internal IPs
+                    try {
+                        const dlUrl = new URL(f.downloadUrl);
+                        if (dlUrl.protocol !== 'https:') {
+                            errors.push(`${f.relativePath}: rejected (non-HTTPS URL)`);
+                            return;
+                        }
+                        if (/^(127\.|10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.|169\.254\.|0\.)/.test(dlUrl.hostname) ||
+                            dlUrl.hostname === 'localhost') {
+                            errors.push(`${f.relativePath}: rejected (internal URL)`);
+                            return;
+                        }
+                    }
+                    catch {
+                        errors.push(`${f.relativePath}: rejected (invalid URL)`);
+                        return;
+                    }
+                    const resp = await fetch(f.downloadUrl);
+                    if (!resp.ok) {
+                        errors.push(`${f.relativePath}: HTTP ${resp.status}`);
+                        return;
+                    }
+                    const buffer = Buffer.from(await resp.arrayBuffer());
+                    const filePath = join(ws.path, f.relativePath);
+                    /**
+                     * ⚠⚠ THIS CONTAINMENT CHECK WAS `require('path').resolve(...)` AND THREW EVERY TIME.
+                     * The package is ESM, so `require` is not defined; the throw was caught by this loop's
+                     * own `catch` and reported as a per-file error, meaning `workspaceSync` has never
+                     * written a single file. It failed CLOSED — the write is below this line — so the cost
+                     * was a dead feature rather than an escape. Same trap as the IPC socket chmod.
+                     *
+                     * ⚠ AND THE COMPARISON WAS A BARE PREFIX MATCH. `startsWith(ws.path)` accepts a sibling
+                     * whose name merely begins the same way — a workspace at `/w/app` would admit writes
+                     * resolved into `/w/app-evil`. Comparing against the path plus a separator is what
+                     * makes it a DIRECTORY test rather than a string test.
+                     */
+                    const root = resolve(ws.path);
+                    const resolved = resolve(filePath);
+                    if (resolved !== root && !resolved.startsWith(root + sep)) {
+                        errors.push(`${f.relativePath}: rejected (path escape)`);
+                        return;
+                    }
+                    mkdirSync(dirname(filePath), { recursive: true });
+                    writeFileSync(filePath, buffer);
+                    synced++;
+                }
+                catch (err) {
+                    errors.push(`${f.relativePath}: ${err.message}`);
+                }
+            }));
+        }
+        return JSON.stringify({ synced, errors });
+    }
+    workspaceExec(args) {
+        const workspaceId = args.workspaceId;
+        const command = args.command;
+        const cwdRelative = args.cwd || '.';
+        const timeout = Math.min(args.timeout || 60_000, 120_000);
+        const extraEnv = args.env || {};
+        const ws = this.workspaces.get(workspaceId);
+        if (!ws)
+            return JSON.stringify({
+                stdout: '',
+                stderr: 'Workspace not found',
+                exitCode: 1,
+                changedFiles: [],
+            });
+        ws.lastUsed = Date.now();
+        const cwd = join(ws.path, cwdRelative);
+        if (!existsSync(cwd))
+            mkdirSync(cwd, { recursive: true });
+        // Snapshot file state before execution
+        const filesBefore = this.scanWorkspaceFiles(ws.path);
+        const beforeMap = new Map(filesBefore.map((f) => [f.relativePath, f.size]));
+        let stdout = '';
+        let stderr = '';
+        let exitCode = 0;
+        try {
+            stdout = execSync(command, {
+                cwd,
+                timeout,
+                maxBuffer: 2 * 1024 * 1024, // 2MB for workspace commands
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+                env: { ...process.env, ...extraEnv, TERM: 'dumb' },
+            });
+            if (stdout.length > 50_000)
+                stdout = stdout.slice(0, 50_000) + '\n... (truncated)';
+        }
+        catch (err) {
+            exitCode = err.status || 1;
+            stderr =
+                (err.stderr ? String(err.stderr).slice(0, 5000) : '') ||
+                    (err.stdout ? String(err.stdout).slice(0, 5000) : '') ||
+                    err.message ||
+                    'Command failed';
+            stdout = err.stdout ? String(err.stdout).slice(0, 50_000) : '';
+        }
+        // Diff filesystem to find changed files
+        const filesAfter = this.scanWorkspaceFiles(ws.path);
+        const changedFiles = [];
+        for (const f of filesAfter) {
+            const beforeSize = beforeMap.get(f.relativePath);
+            if (beforeSize === undefined || beforeSize !== f.size) {
+                changedFiles.push(f);
+            }
+        }
+        return JSON.stringify({ stdout, stderr, exitCode, changedFiles });
+    }
+    async workspaceUpload(args) {
+        const workspaceId = args.workspaceId;
+        const files = args.files;
+        if (!workspaceId || !files)
+            return JSON.stringify({ uploaded: 0, errors: ['Missing args'] });
+        const ws = this.workspaces.get(workspaceId);
+        if (!ws)
+            return JSON.stringify({ uploaded: 0, errors: ['Workspace not found'] });
+        ws.lastUsed = Date.now();
+        let uploaded = 0;
+        const errors = [];
+        const CONCURRENCY = 5;
+        for (let i = 0; i < files.length; i += CONCURRENCY) {
+            const batch = files.slice(i, i + CONCURRENCY);
+            await Promise.all(batch.map(async (f) => {
+                try {
+                    const filePath = join(ws.path, f.relativePath);
+                    if (!existsSync(filePath)) {
+                        errors.push(`${f.relativePath}: not found`);
+                        return;
+                    }
+                    const content = readFileSync(filePath);
+                    const resp = await fetch(f.uploadUrl, {
+                        method: 'PUT',
+                        body: content,
+                        headers: { 'Content-Type': 'application/octet-stream' },
+                    });
+                    if (!resp.ok) {
+                        errors.push(`${f.relativePath}: upload HTTP ${resp.status}`);
+                        return;
+                    }
+                    uploaded++;
+                }
+                catch (err) {
+                    errors.push(`${f.relativePath}: ${err.message}`);
+                }
+            }));
+        }
+        return JSON.stringify({ uploaded, errors });
+    }
+    /** Scan all files in workspace, returning relative paths and sizes */
+    scanWorkspaceFiles(rootDir, maxFiles = 500) {
+        const files = [];
+        const walk = (dir, depth) => {
+            if (depth > 10 || files.length >= maxFiles)
+                return;
+            try {
+                const entries = readdirSync(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (files.length >= maxFiles)
+                        return;
+                    if (entry.name === 'node_modules' || entry.name === '.git')
+                        continue;
+                    const fullPath = join(dir, entry.name);
+                    if (entry.isDirectory()) {
+                        walk(fullPath, depth + 1);
+                    }
+                    else {
+                        const stat = statSync(fullPath);
+                        const relativePath = fullPath.slice(rootDir.length + 1);
+                        files.push({ relativePath, size: stat.size });
+                    }
+                }
+            }
+            catch {
+                /* permission denied */
+            }
+        };
+        walk(rootDir, 0);
+        return files;
+    }
+    /** Walk a directory recursively, collecting paths that match the regex */
+    walkDir(dir, results, regex, maxResults, maxDepth, depth = 0) {
+        if (depth > maxDepth || results.length >= maxResults)
+            return;
+        try {
+            const entries = readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (results.length >= maxResults)
+                    return;
+                if (entry.name.startsWith('.') || entry.name === 'node_modules')
+                    continue;
+                const fullPath = join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    this.walkDir(fullPath, results, regex, maxResults, maxDepth, depth + 1);
+                }
+                else if (regex.test(fullPath)) {
+                    results.push(fullPath);
+                }
+            }
+        }
+        catch {
+            /* permission denied or similar */
+        }
+    }
+    /** Convert a glob pattern to a regex */
+    patternToRegex(pattern) {
+        const escaped = pattern
+            .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+            .replace(/\*\*/g, '{{GLOBSTAR}}')
+            .replace(/\*/g, '[^/]*')
+            .replace(/\?/g, '[^/]')
+            .replace(/\{\{GLOBSTAR\}\}/g, '.*');
+        return new RegExp(`^${escaped}$`);
+    }
+    async syncFileDelete(brandId, relativePath) {
+        if (!this.config || !this.connected)
+            return;
+        try {
+            const msg = { type: 'file-sync', brandId, action: 'delete', file: { path: relativePath } };
+            if (this.useWebSocket) {
+                this.wsSend(msg);
+            }
+            else {
+                await this.postHttp(msg);
+            }
+        }
+        catch (err) {
+            console.error(`[relay] File delete failed (${relativePath}): ${err.message}`);
+        }
+    }
+    async updateBrandSync(brandId, data) {
+        if (!this.config)
+            return;
+        try {
+            const msg = { type: 'brand-sync', brandId, ...data };
+            if (this.useWebSocket) {
+                this.wsSend(msg);
+            }
+            else {
+                await this.postHttp(msg);
+            }
+        }
+        catch (err) {
+            console.error(`[relay] Brand sync update failed: ${err.message}`);
+        }
+    }
+    /**
+     * ⚠⚠ `project-list`, NOT `list-projects` — THE LATTER IS NOT A REGISTERED ACTION.
+     *
+     * Measured 2026-09-04: `beehaven link` answered *"No projects found in your Clearly account.
+     * Create a project at https://clearly.sh first."* against a workspace holding **50 live
+     * projects**. The daemon was answering *"Unknown action: list-projects. Did you mean: … "* the
+     * whole time, and the bare `catch { return null }` below turned that into an empty list, which
+     * `link` reports as "you have none".
+     *
+     * ⚠ THIRD INSTANCE OF ONE PATTERN IN ONE SESSION — `remember`, `recall` and now this: an action
+     * renamed, the caller left pointing at the old name, and the failure rendered as a confident
+     * empty answer rather than an error. A verb that cannot tell "nothing matched" from "the call
+     * failed" will always report the first.
+     *
+     * ⚠ THE CATCH NO LONGER SWALLOWS. It returns `null` for a genuine failure and `[]` only when the
+     * workspace really has no projects — two different answers, so the caller can say which happened.
+     */
+    async listProjects() {
+        if (!this.config)
+            return null;
+        try {
+            const resp = this.useWebSocket
+                ? await this.sendRequest({ type: 'project-list', limit: 500 })
+                : await this.postHttp({ type: 'project-list', limit: 500 });
+            // ⚠ An `{ error }` comes back as a VALUE on this transport — it never throws.
+            if (!resp || resp.error)
+                return null;
+            return Array.isArray(resp.projects) ? resp.projects : [];
+        }
+        catch {
+            return null;
+        }
+    }
+    getMimeType(filePath) {
+        const ext = filePath.split('.').pop()?.toLowerCase() || '';
+        const types = {
+            png: 'image/png',
+            jpg: 'image/jpeg',
+            jpeg: 'image/jpeg',
+            gif: 'image/gif',
+            webp: 'image/webp',
+            svg: 'image/svg+xml',
+            avif: 'image/avif',
+            ico: 'image/x-icon',
+            bmp: 'image/bmp',
+            woff: 'font/woff',
+            woff2: 'font/woff2',
+            ttf: 'font/ttf',
+            otf: 'font/otf',
+            json: 'application/json',
+            css: 'text/css',
+            md: 'text/markdown',
+            pdf: 'application/pdf',
+            yaml: 'text/yaml',
+            yml: 'text/yaml',
+            txt: 'text/plain',
+            scss: 'text/x-scss',
+            less: 'text/x-less',
+        };
+        return types[ext] || 'application/octet-stream';
+    }
+    // ── Internals ─────────────────────────────────────────────────────────
+    /** Flush buffer — sends accumulated events + docs */
+    async flush() {
+        if (!this.config)
+            return;
+        const { events, docs } = this.buffer;
+        const hasData = events.length > 0 || docs.length > 0;
+        if (!hasData && this.sessionEventBatch.size === 0)
+            return;
+        // Snapshot and clear buffer
+        const payload = {};
+        if (events.length > 0)
+            payload.events = events.slice(0, 20);
+        if (docs.length > 0)
+            payload.docs = docs;
+        this.buffer = { events: [], docs: [] };
+        let ok = false;
+        if (hasData) {
+            if (this.useWebSocket) {
+                this.wsSend({ type: 'batch-sync', ...payload });
+                ok = this.connected;
+            }
+            else {
+                const resp = await this.postHttp({ type: 'batch', ...payload });
+                ok = !!resp;
+            }
+        }
+        if (ok) {
+            this.stats.batches++;
+            this.lastSyncAt = Date.now();
+        }
+        // Legacy mode: flush session event batch
+        if (!this.useWebSocket) {
+            await this.flushSessionEventBatch();
+        }
+    }
+    /** Flush batched session events via HTTP (legacy mode only) */
+    async flushSessionEventBatch() {
+        if (!this.config || this.sessionEventBatch.size === 0)
+            return;
+        const sessionIds = [...this.sessionEventBatch.keys()];
+        for (const sessionId of sessionIds) {
+            const events = this.sessionEventBatch.get(sessionId);
+            if (!events || events.length === 0) {
+                this.sessionEventBatch.delete(sessionId);
+                continue;
+            }
+            const batch = events.splice(0, 50);
+            const resp = await this.postHttp({ type: 'session-events', sessionId, events: batch });
+            if (!resp) {
+                const remaining = this.sessionEventBatch.get(sessionId) || [];
+                this.sessionEventBatch.set(sessionId, [...batch, ...remaining]);
+            }
+            const current = this.sessionEventBatch.get(sessionId);
+            if (current && current.length === 0)
+                this.sessionEventBatch.delete(sessionId);
+        }
+    }
+    /** Send heartbeat via HTTP (legacy mode) */
+    async sendHeartbeatHttp() {
+        try {
+            const resp = await this.postHttp({ type: 'heartbeat', deviceId: this.deviceId });
+            if (!resp)
+                return false;
+            if (resp.tier)
+                this.tier = resp.tier;
+            const profileData = resp.profile;
+            if (profileData) {
+                this.profile = {
+                    displayName: profileData.displayName || 'Clearly User',
+                    username: profileData.username,
+                    photoURL: profileData.photoURL,
+                    email: profileData.email,
+                    subscriptionPlan: profileData.subscriptionPlan || 'free',
+                    subscriptionStatus: profileData.subscriptionStatus,
+                    shareTerminal: profileData.shareTerminal,
+                    shareTelemetry: profileData.shareTelemetry,
+                };
+                const json = JSON.stringify(this.profile);
+                if (json !== this.lastProfileJson) {
+                    this.lastProfileJson = json;
+                    this.onProfileUpdate?.(this.profile);
+                }
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Single POST to the relay endpoint (legacy HTTP mode) */
+    async postHttp(data) {
+        if (!this.config)
+            return null;
+        try {
+            const resp = await fetch(this.httpUrl(), {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.config.token}`,
+                },
+                body: JSON.stringify(data),
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (!resp.ok) {
+                this.stats.failed++;
+                if (resp.status === 401) {
+                    console.error('[relay] Token rejected — sign in from the Clearly Dev Mac app tray');
+                    this.connected = false;
+                }
+                else if (resp.status === 429) {
+                    console.warn('[relay] Rate limited — backing off');
+                }
+                return null;
+            }
+            this.stats.sent++;
+            return await resp.json();
+        }
+        catch (err) {
+            this.stats.failed++;
+            if (err.name !== 'AbortError') {
+                console.error(`[relay] POST error: ${err.message}`);
+            }
+            if (this.stats.failed > 5 && this.connected) {
+                this.connected = false;
+                this.scheduleReconnect();
+            }
+            return null;
+        }
+    }
+}