vibeteam 0.6.2 → 0.7.0

package/dist/server/server/index.js

@@ -12,7 +12,7 @@ import { createServer } from 'http';
 import { WebSocketServer, WebSocket } from 'ws';
 import { watch } from 'chokidar';
 import { readFileSync, writeFileSync, existsSync, appendFileSync, mkdirSync, unlinkSync, statSync, readdirSync } from 'fs';
-import { exec, execFile, spawn } from 'child_process';
+import { exec, execFile, execFileSync, spawn } from 'child_process';
 import { dirname, resolve, join, extname } from 'path';
 import { hostname, tmpdir } from 'os';
 import { StringDecoder } from 'string_decoder';
@@ -79,6 +79,7 @@ const TMUX_SESSION = process.env.VIBETEAM_TMUX_SESSION ?? DEFAULTS.TMUX_SESSION;
 const SESSIONS_FILE = resolve(expandHome(process.env.VIBETEAM_SESSIONS_FILE ?? DEFAULTS.SESSIONS_FILE));
 const TILES_FILE = resolve(expandHome(process.env.VIBETEAM_TILES_FILE ?? '~/.vibeteam/data/tiles.json'));
 const VOICE_CONFIG_FILE = resolve(expandHome(process.env.VIBETEAM_VOICE_CONFIG_FILE ?? '~/.vibeteam/data/voice-config.json'));
+const RELAY_STATE_FILE = resolve(expandHome(process.env.VIBETEAM_RELAY_STATE_FILE ?? '~/.vibeteam/data/relay-state.json'));
 /** Time before a "working" session auto-transitions to idle (failsafe for missed events) */
 const WORKING_TIMEOUT_MS = 300_000; // 5 minutes (increased to accommodate long Claude thinking periods)
 /** Maximum request body size (1MB) - prevents DoS via memory exhaustion */
@@ -110,9 +111,10 @@ const DEEPGRAM_API_KEY_ENV = 'DEEPGRAM_API_KEY';
 const OPENROUTER_API_KEY_ENV = 'OPENROUTER_API_KEY';
 const VOICE_CLEANUP_MODEL_ENV = 'VOICE_CLEANUP_MODEL';
 const VOICE_CUSTOM_VOCAB_ENV = 'VOICE_CUSTOM_VOCAB';
+const DEEPGRAM_LANGUAGE_ENV = 'DEEPGRAM_LANGUAGE';
 /** Deepgram transcription settings */
 const DEEPGRAM_MODEL = process.env.DEEPGRAM_MODEL?.trim() || 'nova-3';
-const DEEPGRAM_LANGUAGE = process.env.DEEPGRAM_LANGUAGE?.trim() || 'multi';
+const DEEPGRAM_LANGUAGE_DEFAULT = 'multi';
 const VOICE_CLEANUP_MODEL_DEFAULT = 'google/gemini-2.5-flash';
 /**
  * Validate WebSocket origin header to prevent CSRF attacks.
@@ -3204,6 +3206,11 @@ let voiceCleanupModel = VOICE_CLEANUP_MODEL_DEFAULT;
 /** Custom vocabulary array (effective; from file > env). Populated lazily by
  *  getCustomVocabulary() when the cleanup pass runs. */
 let voiceCustomVocab = [];
+/** Deepgram transcription language (effective; from file > env > default).
+ *  'multi' = auto-detect (Nova-3 multilingual). Codes like 'pt-BR', 'en-US'
+ *  force a specific language — important for users whose accent or short
+ *  utterances confuse the auto-detector and end up transcribed as English. */
+let voiceLanguage = DEEPGRAM_LANGUAGE_DEFAULT;
 /** Track whether each effective value came from the persisted config UI vs
  *  the env var fallback. Used by `/voice/config` GET so the UI can show
  *  "set via UI" / "set via env" / "unset" without leaking the actual key. */
@@ -3212,6 +3219,7 @@ let voiceConfigSource = {
     openrouter: 'unset',   // 'file' | 'env' | 'unset'
     model: 'default',      // 'file' | 'env' | 'default'
     customVocab: 'unset',  // 'file' | 'env' | 'unset'
+    language: 'default',   // 'file' | 'env' | 'default'
 };
 /** Lazy-instantiated OpenAI client pointed at OpenRouter (one shared instance,
  *  rebuilt whenever the API key changes). */
@@ -3250,6 +3258,7 @@ function writeVoiceConfigFile(config) {
         if (config.deepgramApiKey) clean.deepgramApiKey = String(config.deepgramApiKey);
         if (config.openrouterApiKey) clean.openrouterApiKey = String(config.openrouterApiKey);
         if (config.voiceCleanupModel) clean.voiceCleanupModel = String(config.voiceCleanupModel);
+        if (config.voiceLanguage) clean.voiceLanguage = String(config.voiceLanguage);
         if (Array.isArray(config.customVocabulary)) {
             clean.customVocabulary = config.customVocabulary
                 .map(s => String(s).trim())
@@ -3278,6 +3287,7 @@ function reloadVoiceConfig() {
     const envOpenRouter = process.env[OPENROUTER_API_KEY_ENV]?.trim() || null;
     const envModel = process.env[VOICE_CLEANUP_MODEL_ENV]?.trim() || null;
     const envVocabRaw = process.env[VOICE_CUSTOM_VOCAB_ENV]?.trim() || null;
+    const envLanguage = process.env[DEEPGRAM_LANGUAGE_ENV]?.trim() || null;
 
     deepgramApiKey = file.deepgramApiKey || envDeepgram;
     voiceConfigSource.deepgram = file.deepgramApiKey ? 'file' : (envDeepgram ? 'env' : 'unset');
@@ -3288,6 +3298,9 @@ function reloadVoiceConfig() {
     voiceCleanupModel = file.voiceCleanupModel || envModel || VOICE_CLEANUP_MODEL_DEFAULT;
     voiceConfigSource.model = file.voiceCleanupModel ? 'file' : (envModel ? 'env' : 'default');
 
+    voiceLanguage = file.voiceLanguage || envLanguage || DEEPGRAM_LANGUAGE_DEFAULT;
+    voiceConfigSource.language = file.voiceLanguage ? 'file' : (envLanguage ? 'env' : 'default');
+
     if (Array.isArray(file.customVocabulary) && file.customVocabulary.length) {
         voiceCustomVocab = file.customVocabulary;
         voiceConfigSource.customVocab = 'file';
@@ -3322,7 +3335,7 @@ function reloadVoiceConfig() {
         }
     }
 
-    log(`[voice-config] effective: deepgram=${voiceConfigSource.deepgram}, openrouter=${voiceConfigSource.openrouter}, model=${voiceCleanupModel} (${voiceConfigSource.model}), vocab=${voiceCustomVocab.length} (${voiceConfigSource.customVocab})`);
+    log(`[voice-config] effective: deepgram=${voiceConfigSource.deepgram}, openrouter=${voiceConfigSource.openrouter}, model=${voiceCleanupModel} (${voiceConfigSource.model}), language=${voiceLanguage} (${voiceConfigSource.language}), vocab=${voiceCustomVocab.length} (${voiceConfigSource.customVocab})`);
 }
 
 /** Backwards-compat shim — still called from server startup. */
@@ -5409,6 +5422,22 @@ function startVoiceSession(ws, payload = {}) {
         // output) — falls back to no-context cleanup if not provided.
         const sessionId = typeof payload?.sessionId === 'string' ? payload.sessionId : null;
         const tmuxSession = typeof payload?.tmuxSession === 'string' ? payload.tmuxSession : null;
+        // Diagnostic info from the client — what mimeType / sample rate /
+        // platform produced this audio. Critical for debugging the "Deepgram
+        // multi auto-detect picks English on mobile audio" failure mode,
+        // which we suspect correlates with iOS Safari's mp4/aac path vs
+        // desktop Chrome's webm/opus. Logged but never required.
+        const audioInfo = payload?.audioInfo && typeof payload.audioInfo === 'object'
+            ? payload.audioInfo
+            : null;
+        if (audioInfo) {
+            const sr = typeof audioInfo.sampleRate === 'number' ? audioInfo.sampleRate : '?';
+            const ch = typeof audioInfo.channelCount === 'number' ? audioInfo.channelCount : '?';
+            const ua = typeof audioInfo.ua === 'string' ? audioInfo.ua.slice(0, 100) : '';
+            log(`[voice] start lang=${voiceLanguage} mime=${audioInfo.mimeType || '?'} sr=${sr} ch=${ch} ua="${ua}"`);
+        } else {
+            log(`[voice] start lang=${voiceLanguage} (no client audioInfo)`);
+        }
         // Accumulate FINAL transcripts here; the post-processor runs once on
         // voice_stop with the full utterance so cleanup has the full sentence.
         const finalParts = [];
@@ -5416,12 +5445,16 @@ function startVoiceSession(ws, payload = {}) {
         const deepgram = createClient(deepgramApiKey);
         // model: nova-3 + language: 'multi' lets Deepgram auto-detect the
         // language per utterance — important for users who code-switch
-        // (PT-BR + EN). Encoding/sample_rate are intentionally omitted —
-        // browsers default to webm/opus from MediaRecorder and Deepgram
-        // auto-detects from the WebM container header.
+        // (PT-BR + EN). Auto-detect can fail on short utterances or unusual
+        // accents and silently fall back to English transcription, so the
+        // user can override `language` via Settings (persisted in
+        // voice-config.json) to force a specific BCP-47 code like 'pt-BR'.
+        // Encoding/sample_rate are intentionally omitted — browsers default
+        // to webm/opus from MediaRecorder (or mp4/aac on iOS Safari) and
+        // Deepgram auto-detects the codec from the container header.
         const connection = deepgram.listen.live({
             model: DEEPGRAM_MODEL,
-            language: DEEPGRAM_LANGUAGE,
+            language: voiceLanguage,
             smart_format: true,
             interim_results: true,
             // utterance_end_ms: silence threshold for the UtteranceEnd event.
@@ -5440,12 +5473,42 @@ function startVoiceSession(ws, payload = {}) {
         connection.on(LiveTranscriptionEvents.Transcript, (data) => {
             const transcript = data.channel?.alternatives?.[0]?.transcript;
             if (!transcript) return;
+            // Nova-3 multilingual returns the per-utterance detected language.
+            // The exact field varies across SDK / API versions, so probe the
+            // documented spots: `channel.languages[0]` (current), top-level
+            // `detected_language`, and `alternatives[0].languages[0]` (older).
+            // Surfacing this to the client lets the user SEE when auto-detect
+            // is misclassifying their audio (the suspected mobile bug).
+            const detectedLanguage = (Array.isArray(data.channel?.languages) && data.channel.languages[0])
+                || data.detected_language
+                || (Array.isArray(data.channel?.alternatives?.[0]?.languages) && data.channel.alternatives[0].languages[0])
+                || null;
+            if (data.is_final) {
+                log(`[voice-final] lang=${detectedLanguage || 'unknown'} text="${transcript.slice(0, 80)}"`);
+                finalParts.push(transcript);
+            }
             ws.send(JSON.stringify({
                 type: 'voice_transcript',
-                payload: { transcript, isFinal: !!data.is_final }
+                payload: { transcript, isFinal: !!data.is_final, detectedLanguage }
             }));
-            if (data.is_final) {
-                finalParts.push(transcript);
+        });
+        connection.on(LiveTranscriptionEvents.Metadata, (data) => {
+            // Deepgram sends a Metadata event after Open with model + audio
+            // format info (and again on close with usage stats). Log it once
+            // — it tells us EXACTLY what codec/sample-rate Deepgram thinks
+            // it's processing, which is the smoking gun for codec-related
+            // language-detection failures.
+            try {
+                const summary = {
+                    request_id: data.request_id,
+                    model_info: data.model_info,
+                    sha256: data.sha256,
+                    duration: data.duration,
+                    channels: data.channels,
+                };
+                log(`[voice-deepgram-metadata] ${JSON.stringify(summary)}`);
+            } catch {
+                log(`[voice-deepgram-metadata] (unloggable)`);
             }
         });
         connection.on(LiveTranscriptionEvents.UtteranceEnd, () => {
@@ -5578,20 +5641,22 @@ function captureRecentPaneOutput(tmuxSession, lineCount = 30) {
 }
 
 const VOICE_CLEANUP_SYSTEM_PROMPT =
-`You are a voice transcription post-processor for VibeTeam, a tool for managing AI coding agents. The user just dictated something into a terminal session.
+`You are a near-verbatim transcription formatter for VibeTeam (a CLI for managing AI coding agents). The user dictated text that will be inserted into a chat input. Your only job is to add formatting — NEVER edit content.
+
+DO:
+1. Add capitalization (sentence starts, proper nouns).
+2. Add punctuation (.,?!) only where natural pauses make it obvious. When unsure, leave it out.
+3. Fix obvious phonetic misspellings of NAMES (people, files, commands, products) that appear in CONTEXT below — and ONLY names. Example: "v8 team" → "VibeTeam" if VibeTeam is in CONTEXT. Never replace common words.
 
-Your job:
-- Remove filler words (um, uh, like, sabe, tipo) unless they carry meaning
-- Fix grammar, capitalization, punctuation, and obvious typos
-- When the transcript contains a close misspelling of a name or term from the CONTEXT below, correct the spelling (e.g. "v8 team" → "VibeTeam")
-- Preserve the speaker's intent, tone, and language (PT-BR, EN, etc) exactly
-- For programming terms, technical commands, and file names: keep them as the user said them, just fix obvious spelling mistakes
+DO NOT:
+- Drop ANY words. Keep "uh", "um", "tipo", "sabe", "like", "então" — every word the user said stays. The transcript is precious; let the user delete what they don't want.
+- Paraphrase, summarize, or shorten. The output's word count should be within ±2 words of the input (only changes are name corrections from CONTEXT).
+- Translate. PT-BR stays PT-BR, EN stays EN. Mixed-language input is preserved as-is.
+- Preserve self-corrections and repetitions verbatim. If the user said "vou testar agora agora", keep both "agora"s. If they said "abre o, abre o arquivo", keep both fragments.
+- Insert words/names from CONTEXT — context is reference only, never source.
+- Add quotation marks unless the user clearly delimited a quoted phrase.
 
-Hard rules:
-- Return ONLY the cleaned transcript text, nothing else
-- Never insert words or names from CONTEXT that the speaker did NOT say — context is for spelling correction only
-- Never change the meaning of what was said
-- If the transcript is empty or unintelligible, return exactly: EMPTY`;
+OUTPUT: Only the formatted transcript. No prefix, no explanation, no markdown. If the input is empty or pure silence, output exactly: EMPTY`;
 
 /**
  * Run the contextual cleanup pass on a raw Deepgram transcript via OpenRouter.
@@ -5642,7 +5707,11 @@ async function voicePostProcess(ws, rawTranscript, sessionId, tmuxSession) {
                 { role: 'user', content: userMessage },
             ],
             temperature: 0,
-            max_tokens: 600,
+            // 2000 covers ~1500 words of cleaned PT-BR / EN text — enough for
+            // a 3–5 minute monologue. The previous 600-token cap silently
+            // truncated long dictations, so the user's last sentences would
+            // simply disappear from the output.
+            max_tokens: 2000,
         });
         const cleaned = (completion.choices?.[0]?.message?.content ?? '').trim();
         const text = cleaned === 'EMPTY' ? '' : cleaned;
@@ -5664,6 +5733,203 @@ async function voicePostProcess(ws, rawTranscript, sessionId, tmuxSession) {
         }
     }
 }
+
+// ============================================================================
+// API usage discovery — Claude (OAuth) / Deepgram / OpenRouter balance.
+// Each function caches its successful result so we don't re-do expensive
+// keychain enumerations on every poll.
+// ============================================================================
+
+/** Memoized after first successful lookup so we skip the dump-keychain
+ *  enumeration on subsequent calls. */
+let _claudeCredsCache = null;
+
+/**
+ * Find the user's Claude Code OAuth credentials object across the various
+ * places Claude Code has stored them over time:
+ *   1. ~/.claude/.credentials.json (older installs)
+ *   2. Keychain entry "Claude Code-credentials" (older format)
+ *   3. Keychain entry "Claude Code-credentials-<suffix>" (current format —
+ *      the suffix is per-install)
+ *
+ * Returns the parsed credentials object (with `claudeAiOauth.accessToken`)
+ * or null if nothing is found.
+ */
+async function findClaudeOAuthCredentials() {
+    if (_claudeCredsCache) {
+        // Tokens expire — re-validate by re-reading the cached source.
+        try {
+            const { readFileSync } = await import('fs');
+            const { execFileSync } = await import('child_process');
+            if (_claudeCredsCache.kind === 'file') {
+                const data = JSON.parse(readFileSync(_claudeCredsCache.path, 'utf8'));
+                if (data?.claudeAiOauth?.accessToken) return data;
+            } else if (_claudeCredsCache.kind === 'keychain') {
+                const out = execFileSync('security',
+                    ['find-generic-password', '-s', _claudeCredsCache.service, '-w'],
+                    { encoding: 'utf8', timeout: 5000 }).trim();
+                const data = JSON.parse(out);
+                if (data?.claudeAiOauth?.accessToken) return data;
+            }
+        } catch { /* fall through to fresh lookup */ }
+        _claudeCredsCache = null; // cached source no longer valid
+    }
+
+    const { readFileSync } = await import('fs');
+    const { join } = await import('path');
+    const { homedir } = await import('os');
+    const { execFileSync } = await import('child_process');
+
+    // Method 1: file at ~/.claude/.credentials.json
+    try {
+        const credPath = join(homedir(), '.claude', '.credentials.json');
+        const data = JSON.parse(readFileSync(credPath, 'utf8'));
+        if (data?.claudeAiOauth?.accessToken) {
+            _claudeCredsCache = { kind: 'file', path: credPath };
+            return data;
+        }
+    } catch { /* missing or unreadable — try keychain */ }
+
+    if (process.platform !== 'darwin') return null;
+
+    // Method 2: try the unsuffixed keychain entry (older format)
+    const candidates = ['Claude Code-credentials'];
+
+    // Method 3: enumerate suffixed entries via dump-keychain (slow, only on
+    // first miss). We just collect "Claude Code-credentials-<anything>" svc
+    // names. login.keychain-db is unlocked at login so this doesn't prompt.
+    try {
+        const dump = execFileSync('security', ['dump-keychain'],
+            { encoding: 'utf8', timeout: 10000, maxBuffer: 16 * 1024 * 1024 });
+        const seen = new Set(candidates);
+        for (const m of dump.matchAll(/"svce"<blob>="(Claude Code-credentials-[^"]+)"/g)) {
+            if (!seen.has(m[1])) {
+                seen.add(m[1]);
+                candidates.push(m[1]);
+            }
+        }
+    } catch { /* dump failed, only try the unsuffixed candidate */ }
+
+    for (const service of candidates) {
+        try {
+            const out = execFileSync('security',
+                ['find-generic-password', '-s', service, '-w'],
+                { encoding: 'utf8', timeout: 5000 }).trim();
+            const data = JSON.parse(out);
+            if (data?.claudeAiOauth?.accessToken) {
+                _claudeCredsCache = { kind: 'keychain', service };
+                return data;
+            }
+        } catch { /* try next */ }
+    }
+    return null;
+}
+
+/** Cached Deepgram balance fetch. Cache TTL 5 min, exponential backoff on
+ *  rate limit. Resolves to { ok, balance, currency, projectName, error }. */
+let _deepgramUsageCache = { data: null, timestamp: 0, ttl: 300_000, backoff: 0 };
+async function fetchDeepgramUsage() {
+    const cache = _deepgramUsageCache;
+    const now = Date.now();
+    if (cache.data && (now - cache.timestamp) < cache.ttl + cache.backoff) {
+        return { ...cache.data, cached: true };
+    }
+    if (!deepgramApiKey) {
+        return { ok: false, error: 'DEEPGRAM_API_KEY not configured' };
+    }
+    try {
+        // 1. List projects to discover the project_id.
+        const projectsRes = await fetch('https://api.deepgram.com/v1/projects', {
+            headers: { Authorization: `Token ${deepgramApiKey}` },
+        });
+        if (!projectsRes.ok) {
+            if (projectsRes.status === 429) cache.backoff = Math.min((cache.backoff || 60_000) * 2, 600_000);
+            const status = projectsRes.status;
+            return {
+                ok: false,
+                error: `Deepgram projects HTTP ${status}`,
+                hint: status === 401 ? 'API key invalid — re-paste it in Settings → Voice'
+                    : status === 403 ? 'API key missing scopes — see hint below'
+                    : null,
+            };
+        }
+        const projectsData = await projectsRes.json();
+        const project = projectsData.projects?.[0];
+        if (!project?.project_id) return { ok: false, error: 'No Deepgram project found' };
+
+        // 2. Get balances for that project.
+        const balancesRes = await fetch(
+            `https://api.deepgram.com/v1/projects/${project.project_id}/balances`,
+            { headers: { Authorization: `Token ${deepgramApiKey}` } }
+        );
+        if (!balancesRes.ok) {
+            if (balancesRes.status === 429) cache.backoff = Math.min((cache.backoff || 60_000) * 2, 600_000);
+            const status = balancesRes.status;
+            // 403 = key works for transcription but lacks billing:read scope.
+            // Default Deepgram keys are member-level; admin scope is opt-in
+            // when creating the key. We can't fix this without the user
+            // creating a new key — point them at the console.
+            return {
+                ok: false,
+                error: `Deepgram balances HTTP ${status}`,
+                hint: status === 403
+                    ? 'Default API keys can\'t read billing — check console.deepgram.com directly, or create a new key with billing:read scope'
+                    : null,
+                consoleUrl: 'https://console.deepgram.com',
+            };
+        }
+        const balData = await balancesRes.json();
+        // Sum across all balance buckets (free trial, paid top-ups, etc).
+        const total = (balData.balances || []).reduce((acc, b) => acc + (typeof b.amount === 'number' ? b.amount : 0), 0);
+        const currency = balData.balances?.[0]?.units || 'usd';
+        const result = { ok: true, balance: total, currency, projectName: project.name };
+        cache.data = result;
+        cache.timestamp = now;
+        cache.backoff = 0;
+        return result;
+    } catch (err) {
+        return { ok: false, error: err.message || String(err) };
+    }
+}
+
+/** Cached OpenRouter credits fetch. */
+let _openrouterUsageCache = { data: null, timestamp: 0, ttl: 300_000, backoff: 0 };
+async function fetchOpenRouterUsage() {
+    const cache = _openrouterUsageCache;
+    const now = Date.now();
+    if (cache.data && (now - cache.timestamp) < cache.ttl + cache.backoff) {
+        return { ...cache.data, cached: true };
+    }
+    if (!openrouterApiKey) {
+        return { ok: false, error: 'OPENROUTER_API_KEY not configured' };
+    }
+    try {
+        const res = await fetch('https://openrouter.ai/api/v1/credits', {
+            headers: { Authorization: `Bearer ${openrouterApiKey}` },
+        });
+        if (!res.ok) {
+            if (res.status === 429) cache.backoff = Math.min((cache.backoff || 60_000) * 2, 600_000);
+            return { ok: false, error: `OpenRouter HTTP ${res.status}` };
+        }
+        const data = await res.json();
+        const totalCredits = data?.data?.total_credits ?? 0;
+        const totalUsage = data?.data?.total_usage ?? 0;
+        const result = {
+            ok: true,
+            totalCredits,
+            totalUsage,
+            remaining: Math.max(0, totalCredits - totalUsage),
+            currency: 'usd',
+        };
+        cache.data = result;
+        cache.timestamp = now;
+        cache.backoff = 0;
+        return result;
+    } catch (err) {
+        return { ok: false, error: err.message || String(err) };
+    }
+}
+
 /**
  * Link a Claude Code session ID to a managed session
  */
@@ -5983,6 +6249,289 @@ function hashAuthToken(token) {
     return createHash('sha256').update(token).digest('hex');
 }
 
+// ---- Local pairing flow (relay-independent fallback) ----
+//
+// The Fly relay's /pair endpoint enforces 10 codes/IP/hour. When a user
+// burns through that (e.g. backend restart loses the relay session and
+// they retry pairing), they're locked out for up to an hour.
+//
+// This local flow gives the same security model as the relay — 6-digit
+// code, 5-minute TTL, single-use, brute-force-rate-limited — but the
+// code-issuance side is loopback-only, so an external attacker can't
+// trigger code creation. Mobile claims via Funnel-accessible /pair-claim.
+//
+// State is in-memory only (codes are intentionally short-lived).
+const localPairCodes = new Map(); // code -> { createdAt }
+const LOCAL_PAIR_TTL_MS = 5 * 60 * 1000;
+const pairClaimAttempts = new Map(); // ip -> { count, windowStart }
+const PAIR_CLAIM_WINDOW_MS = 5 * 60 * 1000;
+const PAIR_CLAIM_MAX_PER_WINDOW = 60;
+
+function generateLocalPairCode() {
+    return String(Math.floor(Math.random() * 1_000_000)).padStart(6, '0');
+}
+function pruneLocalPairCodes() {
+    const cutoff = Date.now() - LOCAL_PAIR_TTL_MS;
+    for (const [code, entry] of localPairCodes) {
+        if (entry.createdAt < cutoff) localPairCodes.delete(code);
+    }
+}
+function getRequestIP(req) {
+    const xff = req.headers['x-forwarded-for'];
+    if (typeof xff === 'string' && xff.length) return xff.split(',')[0].trim();
+    return req.socket?.remoteAddress || 'unknown';
+}
+function checkPairClaimRateLimit(ip) {
+    const now = Date.now();
+    const entry = pairClaimAttempts.get(ip);
+    if (!entry || now - entry.windowStart > PAIR_CLAIM_WINDOW_MS) {
+        pairClaimAttempts.set(ip, { count: 1, windowStart: now });
+        return true;
+    }
+    if (entry.count >= PAIR_CLAIM_MAX_PER_WINDOW) return false;
+    entry.count++;
+    return true;
+}
+function isLoopbackRequest(req) {
+    const ra = req.socket?.remoteAddress || '';
+    return ra === '127.0.0.1' || ra === '::1' || ra === '::ffff:127.0.0.1';
+}
+
+// ---- Relay state persistence + auto-reconnect ----
+//
+// Without persistence, every backend restart loses the relay sessionToken
+// and orphans the mobile in its relay room. The mobile then sees its
+// relay-status pill go red and the user has to re-pair from desktop —
+// which is impossible if the user is mobile-only.
+//
+// With persistence + auto-reconnect:
+//   - Backend writes its relay sessionToken to disk on every successful
+//     'paired' event.
+//   - On boot, if a token exists on disk, backend opens a WS to the relay
+//     with `?token=<saved>&role=host`. Relay re-creates the room (or
+//     finds the existing one with the mobile still connected) and re-
+//     emits 'paired'.
+//   - On unexpected close, exponential backoff retry up to 30s.
+//
+// Net effect: backend can restart freely, mobile stays connected.
+
+function readRelayState() {
+    try {
+        if (!existsSync(RELAY_STATE_FILE)) return null;
+        const raw = readFileSync(RELAY_STATE_FILE, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    } catch { return null; }
+}
+function writeRelayState(state) {
+    try {
+        const dir = dirname(RELAY_STATE_FILE);
+        if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+        writeFileSync(RELAY_STATE_FILE, JSON.stringify(state, null, 2), { mode: 0o600 });
+    } catch (e) {
+        log(`[relay] failed to persist state: ${e.message || e}`);
+    }
+}
+function clearRelayState() {
+    try {
+        if (existsSync(RELAY_STATE_FILE)) unlinkSync(RELAY_STATE_FILE);
+    } catch { /* ignore */ }
+}
+
+let _relayReconnectAttempts = 0;
+let _relayReconnectTimer = null;
+function scheduleRelayAutoReconnect() {
+    if (_relayReconnectTimer) return; // already scheduled
+    const saved = readRelayState();
+    if (!saved?.sessionToken) {
+        log(`[relay] no saved sessionToken on disk; auto-reconnect skipped`);
+        return;
+    }
+    const delay = Math.min(30_000, 1000 * Math.pow(2, _relayReconnectAttempts));
+    _relayReconnectAttempts++;
+    log(`[relay] auto-reconnect in ${delay}ms (attempt ${_relayReconnectAttempts})`);
+    _relayReconnectTimer = setTimeout(() => {
+        _relayReconnectTimer = null;
+        connectRelayWithSavedToken();
+    }, delay);
+    _relayReconnectTimer.unref?.();
+}
+function connectRelayWithSavedToken() {
+    if (relayWs && relayWs.readyState <= 1) {
+        log(`[relay] auto-reconnect: WS already exists; skipping`);
+        return;
+    }
+    const saved = readRelayState();
+    if (!saved?.sessionToken) {
+        log(`[relay] no saved sessionToken; cannot auto-reconnect`);
+        return;
+    }
+    const relayUrl = saved.relayUrl || 'wss://vibeteam-relay.fly.dev/connect';
+    const url = `${relayUrl}?token=${encodeURIComponent(saved.sessionToken)}&role=host`;
+    log(`[relay] auto-reconnecting with saved sessionToken`);
+    try {
+        const ws = new WebSocket(url);
+        relayWs = ws; // claim slot immediately so concurrent calls bail
+        setupRelayHostWs(ws, { reconnect: true });
+    } catch (e) {
+        log(`[relay] auto-reconnect threw: ${e.message || e}`);
+        relayWs = null;
+        scheduleRelayAutoReconnect();
+    }
+}
+
+// Shared handler for the host's outbound WS to the relay. Used by both
+// the user-initiated /relay/start-pairing and /relay/connect endpoints AND
+// by the auto-reconnect path. Encapsulates: open, paired, waiting, ping,
+// mobile_disconnected, relay_message, host_info emission, sessionToken
+// persistence, and close→reconnect.
+function setupRelayHostWs(ws, { reconnect = false } = {}) {
+    ws.on('open', () => {
+        log(`[relay] ${reconnect ? 'auto-reconnect' : 'connect'}: WS opened`);
+        relayConnected = true;
+        _relayReconnectAttempts = 0;
+        broadcast({ type: 'relay_status', payload: { connected: true } });
+    });
+
+    ws.on('message', (data) => {
+        let msg;
+        try { msg = JSON.parse(data.toString()); }
+        catch { return; }
+
+        if (msg.type === 'paired') {
+            relaySessionToken = msg.payload?.sessionToken;
+            // Persist immediately so a crash before next save still survives.
+            if (relaySessionToken) {
+                writeRelayState({ sessionToken: relaySessionToken, relayUrl: 'wss://vibeteam-relay.fly.dev/connect', updatedAt: Date.now() });
+            }
+            log(`[relay] paired with mobile${reconnect ? ' (after auto-reconnect)' : ''}`);
+
+            // Idempotent: only register a NEW device on the FIRST 'paired'
+            // event for this WS. Mobile reconnects re-emit 'paired' without
+            // implying a new device — same currentRelayDeviceId carries
+            // through, no orphan rows.
+            if (!currentRelayDeviceId) {
+                const revokedIds = enforceMaxDevicesBeforePairing();
+                const { id: deviceId, token: authToken } = registerDevice({ name: 'Mobile Device' });
+                currentRelayDeviceId = deviceId;
+                sendRelayEnvelope('auth_grant', {
+                    deviceId,
+                    authToken,
+                    issuedAt: Date.now(),
+                    funnelHost: getFunnelHostname(),
+                });
+                broadcast({ type: 'devices_changed', payload: { devices: listDevicesSafe() } });
+                broadcast({ type: 'device_paired', payload: { deviceId, revokedIds, name: 'Mobile Device' } });
+            }
+
+            // Always send host_info, even on reconnect. This is the channel
+            // by which an EXISTING paired mobile (whose deviceAuth predates
+            // the funnelHost feature) gets backfilled with the Funnel
+            // address. New mobile JS handles this envelope by updating
+            // localStorage; old JS ignores it harmlessly.
+            sendRelayEnvelope('host_info', {
+                funnelHost: getFunnelHostname(),
+                serverVersion: VERSION,
+            });
+
+            broadcast({ type: 'relay_status', payload: { connected: true, paired: true, deviceId: currentRelayDeviceId } });
+            // Push current state (mobile may have just reconnected with stale store).
+            sendToRelay({ type: 'sessions', payload: getSessions() });
+            sendToRelay({ type: 'projects', payload: projectsManager.getProjects() });
+            return;
+        }
+        if (msg.type === 'waiting') {
+            if (msg.payload?.sessionToken) {
+                relaySessionToken = msg.payload.sessionToken;
+                writeRelayState({ sessionToken: relaySessionToken, relayUrl: 'wss://vibeteam-relay.fly.dev/connect', updatedAt: Date.now() });
+            }
+            broadcast({ type: 'relay_status', payload: { connected: true, paired: false, waiting: true } });
+            return;
+        }
+        if (msg.type === 'ping') {
+            if (ws.readyState === 1) {
+                try { ws.send(JSON.stringify({ type: 'pong', from: 'host', timestamp: Date.now(), seq: 0 })); } catch {}
+            }
+            return;
+        }
+        if (msg.type === 'mobile_disconnected') {
+            broadcast({ type: 'relay_status', payload: { connected: true, paired: false } });
+            return;
+        }
+        if (msg.type === 'relay_message' && msg.payload) {
+            handleRelayRequest(msg.payload, ws);
+            return;
+        }
+        if (msg.type === 'error') {
+            // Token rejected by relay (expired, invalid, etc) — clear state
+            // so we don't keep retrying with a bad token. User must re-pair.
+            log(`[relay] error from relay: ${msg.payload?.message || 'unknown'}`);
+            if (reconnect && /token/i.test(msg.payload?.message || '')) {
+                clearRelayState();
+                _relayReconnectAttempts = 0; // give up
+            }
+            return;
+        }
+    });
+
+    ws.on('close', (code) => {
+        log(`[relay] WS closed (code=${code})`);
+        relayWs = null;
+        relayConnected = false;
+        // DELIBERATELY keep relaySessionToken + currentRelayDeviceId in
+        // memory and on disk — this is what enables the auto-reconnect to
+        // pick up where we left off.
+        broadcast({ type: 'relay_status', payload: { connected: false } });
+        scheduleRelayAutoReconnect();
+    });
+
+    ws.on('error', (err) => {
+        log(`[relay] WS error: ${err.message || err}`);
+    });
+}
+
+// ---- Funnel hostname auto-discovery ----
+//
+// At pairing time we tell the mobile what `host:port` reaches this backend
+// over the public internet via Tailscale Funnel. The mobile stores it
+// alongside its deviceAuth, and from then on it can hit the backend
+// directly from ANY origin (vibing.team, localhost dev tab on another box,
+// etc) — no more relay dependency for read paths or WS.
+//
+// Discovery: parse `tailscale serve status` and find a `(Funnel on)`
+// entry whose proxy points at our PORT. Returns "host:port" or null
+// when Funnel isn't set up. Cached on first call (you'd have to reload
+// the backend to pick up a serve config change).
+let _funnelHostnameCache; // undefined = not probed, null = no funnel, string = host:port
+function getFunnelHostname() {
+    if (_funnelHostnameCache !== undefined) return _funnelHostnameCache;
+    try {
+        const out = execFileSync('tailscale', ['serve', 'status'], { encoding: 'utf8', timeout: 2000 });
+        const lines = out.split('\n');
+        const headerRe = /^https:\/\/([^\s:]+):(\d+)\s+\(Funnel on\)/;
+        const proxyRe = /\|--\s*\/\s*proxy\s+http:\/\/127\.0\.0\.1:(\d+)/;
+        for (let i = 0; i < lines.length; i++) {
+            const m = lines[i].match(headerRe);
+            if (!m) continue;
+            // Look at the next few lines for the proxy target
+            for (let j = i + 1; j < Math.min(i + 4, lines.length); j++) {
+                const pm = lines[j].match(proxyRe);
+                if (pm && parseInt(pm[1], 10) === PORT) {
+                    _funnelHostnameCache = `${m[1]}:${m[2]}`;
+                    log(`[funnel] discovered hostname=${_funnelHostnameCache} → backend:${PORT}`);
+                    return _funnelHostnameCache;
+                }
+            }
+        }
+        _funnelHostnameCache = null;
+        return null;
+    } catch (e) {
+        // tailscale not installed / not running / serve not configured — no funnel
+        _funnelHostnameCache = null;
+        return null;
+    }
+}
+
 function loadDevices() {
     try {
         if (!existsSync(DEVICES_FILE)) return;
@@ -6125,6 +6674,38 @@ function getRequireConfirmation() {
     }
 }
 
+function getMaxDevices() {
+    try {
+        const settings = readGlobalSettings();
+        const v = settings.remoteControl?.maxDevices;
+        if (typeof v === 'number' && v >= 1 && v <= 10) return Math.floor(v);
+    } catch { /* ignore */ }
+    return 2; // default: phone + backup
+}
+
+// Enforce max-devices policy: if registering a new device would exceed the
+// configured max, auto-revoke the oldest unrevoked device first. Returns the
+// list of revoked device IDs so the caller can include them in the
+// notification broadcast.
+function enforceMaxDevicesBeforePairing() {
+    const max = getMaxDevices();
+    const unrevoked = Array.from(devices.values())
+        .filter(d => !d.revoked)
+        .sort((a, b) => a.lastSeen - b.lastSeen); // oldest first
+    const surplus = unrevoked.length - (max - 1); // leave room for the about-to-be-registered device
+    if (surplus <= 0) return [];
+    const revokedIds = [];
+    for (let i = 0; i < surplus && i < unrevoked.length; i++) {
+        const d = unrevoked[i];
+        d.revoked = true;
+        d.revokedAt = Date.now();
+        d.revokedReason = 'max_devices_exceeded';
+        revokedIds.push(d.id);
+    }
+    saveDevices();
+    return revokedIds;
+}
+
 function describeDestructiveAction(method, path) {
     if (method === 'DELETE' && /^\/projects\//.test(path)) return 'Delete project';
     if (method === 'DELETE' && /^\/sessions\//.test(path)) return 'Delete agent session';
@@ -6195,6 +6776,7 @@ const RELAY_PATH_ALLOWLIST = [
     /^\/themes(\/|\?|$)/,
     /^\/settings(\/|\?|$)/,
     /^\/usage(\/|\?|$)/,
+    /^\/ideation(\/|\?|$)/,
     /^\/health$/,
 ];
 
@@ -6395,11 +6977,13 @@ function handleClientMessage(ws, message) {
 // ============================================================================
 async function handleHttpRequest(req, res) {
     const origin = req.headers.origin;
-    // CORS headers - only allow specific origins
+    // CORS headers - only allow specific origins. Allow Authorization header
+    // so mobile clients can send their device token over Tailscale Funnel
+    // (direct backend path, bypassing the Fly relay).
     if (origin && isOriginAllowed(origin)) {
         res.setHeader('Access-Control-Allow-Origin', origin);
         res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
-        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
     }
     if (req.method === 'OPTIONS') {
         // Preflight: reject if origin not allowed
@@ -6412,6 +6996,65 @@ async function handleHttpRequest(req, res) {
         res.end();
         return;
     }
+
+    // Bearer-token auth for direct mobile access via Tailscale Funnel.
+    // The backend is exposed publicly on Funnel:8443, so any path that
+    // mobile reaches MUST require a valid device token. Localhost requests
+    // (desktop on the same machine) bypass this gate — they connect via
+    // 127.0.0.1 and don't have an Origin header set to a remote hostname.
+    //
+    // Strategy:
+    //   - If request has Authorization: Bearer <token> AND token is valid
+    //     → mark req as remote-authenticated, allow through.
+    //   - If request comes from localhost (no remote origin) → allow through
+    //     unauthenticated (legacy desktop behavior).
+    //   - Otherwise → 401.
+    const authHeader = req.headers['authorization'];
+    let isRemoteAuthed = false;
+    if (typeof authHeader === 'string' && authHeader.startsWith('Bearer ')) {
+        const token = authHeader.slice(7).trim();
+        const device = validateAuthToken(token);
+        if (device) {
+            req.__authedDevice = device;
+            isRemoteAuthed = true;
+        }
+    }
+
+    // Reject remote requests without valid bearer token. We use Host header
+    // (harder to spoof for actual remote requests) plus the Tailscale Funnel
+    // marker as the trust boundary:
+    //   - Tailscale-Funnel-Request: ?1 → public-internet via Funnel, REQUIRE auth
+    //   - Host other than localhost/127.0.0.1 → reached us via something
+    //     remote-ish (Tailscale Serve, LAN), REQUIRE auth
+    //   - Otherwise localhost desktop → allow (legacy behavior)
+    const hostHeader = (req.headers['host'] || '').split(':')[0].toLowerCase();
+    const isFunnelRequest = req.headers['tailscale-funnel-request'] === '?1';
+    const isLocalHost = hostHeader === 'localhost' || hostHeader === '127.0.0.1' || hostHeader === '::1' || hostHeader === '0.0.0.0' || hostHeader === '';
+    const isRemoteRequest = isFunnelRequest || !isLocalHost;
+    if (isRemoteRequest && !isRemoteAuthed) {
+        // Allow these public paths to be reached without auth:
+        //   - /health (status check)
+        //   - /relay/start-pairing, /relay/connect (pairing UI on desktop fetches)
+        //   - /relay/disconnect (admin)
+        //   - /relay/status
+        //   - / and SPA static assets (handled later in the file)
+        const path = (req.url || '').split('?')[0];
+        const PUBLIC_PATHS = [
+            /^\/health$/,
+            /^\/relay\/(start-pairing|connect|disconnect|status)$/,
+            /^\/pair-claim$/, // mobile claims a host-issued local code; the code IS the auth
+            /^\/api\/docs/, // API docs UI
+            /^\/$/,
+            /\.(js|css|html|svg|png|jpg|ico|woff2?|ttf|map|json|webp|mp3)$/i,
+            /^\/(?:assets|models|sounds)\//,
+            /^\/favicon/,
+        ];
+        if (!PUBLIC_PATHS.some((rx) => rx.test(path))) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Authentication required' }));
+            return;
+        }
+    }
     if (req.method === 'POST' && req.url === '/event') {
         collectRequestBody(req).then(body => {
             try {
@@ -6580,6 +7223,7 @@ async function handleHttpRequest(req, res) {
             deepgram: { set: !!deepgramApiKey, source: voiceConfigSource.deepgram },
             openrouter: { set: !!openrouterApiKey, source: voiceConfigSource.openrouter },
             cleanupModel: { value: voiceCleanupModel, source: voiceConfigSource.model },
+            language: { value: voiceLanguage, source: voiceConfigSource.language },
             customVocabulary: { value: voiceCustomVocab, source: voiceConfigSource.customVocab },
         }));
         return;
@@ -6607,6 +7251,7 @@ async function handleHttpRequest(req, res) {
                 apply('deepgramApiKey', String);
                 apply('openrouterApiKey', String);
                 apply('voiceCleanupModel', String);
+                apply('voiceLanguage', String);
                 apply('customVocabulary', (v) => Array.isArray(v) ? v : String(v).split(/[\n,]+/));
 
                 if (!writeVoiceConfigFile(next)) {
@@ -7934,6 +8579,24 @@ async function handleHttpRequest(req, res) {
         try { mkdirSync(_usageCacheDir, { recursive: true }); } catch {}
         global._usageCache = { data: _diskData, timestamp: _diskTimestamp, ttl: 300000, backoff: 0, path: _usageCachePath };
     }
+    // Deepgram balance: returns { ok, balance, currency } or
+    // { ok: false, error, hint }. 200 with ok:false for "expected" failures
+    // (no key, missing scope) so the UI can render a friendly state without
+    // lighting up a 5xx error.
+    if (req.method === 'GET' && req.url === '/usage/deepgram') {
+        const result = await fetchDeepgramUsage();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(result));
+        return;
+    }
+    // OpenRouter credits: returns { ok, totalCredits, totalUsage, remaining }
+    // or { ok: false, error }. Same caching strategy as Deepgram.
+    if (req.method === 'GET' && req.url === '/usage/openrouter') {
+        const result = await fetchOpenRouterUsage();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(result));
+        return;
+    }
     if (req.method === 'GET' && req.url === '/usage') {
         const cache = global._usageCache;
         const now = Date.now();
@@ -7954,31 +8617,13 @@ async function handleHttpRequest(req, res) {
         }
 
         try {
-            // Get OAuth token - try credentials file first (Keychain's security -w truncates large JSON),
-            // then fall back to Keychain
-            const { readFileSync } = await import('fs');
-            const { join } = await import('path');
-            const { homedir } = await import('os');
-            let tokenData;
-
-            // Method 1: Read from ~/.claude/.credentials.json (most reliable)
-            try {
-                const credPath = join(homedir(), '.claude', '.credentials.json');
-                tokenData = JSON.parse(readFileSync(credPath, 'utf8'));
-            } catch (_fileErr) {
-                // Method 2: Fall back to macOS Keychain
-                try {
-                    const { execFileSync } = await import('child_process');
-                    const keychainResult = execFileSync(
-                        'security',
-                        ['find-generic-password', '-s', 'Claude Code-credentials', '-w'],
-                        { encoding: 'utf8', timeout: 5000 }
-                    ).trim();
-                    tokenData = JSON.parse(keychainResult);
-                } catch (_keychainErr) {
-                    // ignore, handled below
-                }
-            }
+            // Locate the user's Claude Code OAuth token. Recent Claude Code
+            // versions store it in macOS Keychain under a per-install service
+            // name like "Claude Code-credentials-ba6ac817" (suffix is unique
+            // per install) — the unsuffixed entry is now used for plugin
+            // OAuth (mcpOAuth schema) and DOESN'T contain claudeAiOauth.
+            // We cache the resolved service name in memory once found.
+            const tokenData = await findClaudeOAuthCredentials();
 
             if (!tokenData) {
                 res.writeHead(401, { 'Content-Type': 'application/json' });
@@ -9421,98 +10066,14 @@ Explore the project structure and key files to understand what it does, then out
                 }
 
                 try {
+                    // User-initiated re-pair — clear any prior persistent
+                    // state so a stale token doesn't fight with the new one.
+                    clearRelayState();
+                    currentRelayDeviceId = null;
                     const url = `${relayUrl}?code=${encodeURIComponent(code)}&role=host`;
                     const ws = new WebSocket(url);
-
-                    ws.on('open', () => {
-                        console.log('[relay] Connected to relay server');
-                        relayConnected = true;
-                        broadcast({ type: 'relay_status', payload: { connected: true } });
-                    });
-
-                    ws.on('message', (data) => {
-                        try {
-                            const msg = JSON.parse(data.toString());
-
-                            // Handle relay control messages
-                            if (msg.type === 'paired') {
-                                relaySessionToken = msg.payload?.sessionToken;
-                                console.log('[relay] Paired with mobile device');
-
-                                // Issue per-device auth token. The mobile keeps this token
-                                // and must include it in every relay_message payload.
-                                // The token is plaintext on this single delivery only;
-                                // we store SHA-256 hash + revocation flag locally.
-                                const { id: deviceId, token: authToken } = registerDevice({
-                                    name: 'Mobile Device',
-                                });
-                                currentRelayDeviceId = deviceId;
-
-                                // Send the grant to mobile through the relay
-                                sendRelayEnvelope('auth_grant', {
-                                    deviceId,
-                                    authToken,
-                                    issuedAt: Date.now(),
-                                });
-
-                                broadcast({ type: 'relay_status', payload: { connected: true, paired: true, deviceId } });
-                                broadcast({ type: 'devices_changed', payload: { devices: listDevicesSafe() } });
-
-                                // Send current state to mobile via relay
-                                const sessionsData = getSessions();
-                                sendToRelay({ type: 'sessions', payload: sessionsData });
-
-                                // Send projects
-                                sendToRelay({ type: 'projects', payload: projectsManager.getProjects() });
-                                return;
-                            }
-
-                            if (msg.type === 'waiting') {
-                                console.log('[relay] Waiting for mobile device to connect...');
-                                if (msg.payload?.sessionToken) {
-                                    relaySessionToken = msg.payload.sessionToken;
-                                }
-                                broadcast({ type: 'relay_status', payload: { connected: true, paired: false, waiting: true } });
-                                return;
-                            }
-
-                            if (msg.type === 'ping') {
-                                if (ws.readyState === 1) {
-                                    ws.send(JSON.stringify({ type: 'pong', from: 'host', timestamp: Date.now(), seq: 0 }));
-                                }
-                                return;
-                            }
-
-                            if (msg.type === 'mobile_disconnected') {
-                                console.log('[relay] Mobile device disconnected');
-                                broadcast({ type: 'relay_status', payload: { connected: true, paired: false } });
-                                return;
-                            }
-
-                            // Handle relay_message from mobile (REST-over-relay)
-                            if (msg.type === 'relay_message' && msg.payload) {
-                                handleRelayRequest(msg.payload, ws);
-                                return;
-                            }
-                        } catch (e) {
-                            console.error('[relay] Error processing message:', e);
-                        }
-                    });
-
-                    ws.on('close', () => {
-                        console.log('[relay] Disconnected from relay server');
-                        relayWs = null;
-                        relayConnected = false;
-                        relaySessionToken = null;
-                        currentRelayDeviceId = null;
-                        broadcast({ type: 'relay_status', payload: { connected: false } });
-                    });
-
-                    ws.on('error', (err) => {
-                        console.error('[relay] WebSocket error:', err.message);
-                    });
-
                     relayWs = ws;
+                    setupRelayHostWs(ws, { reconnect: false });
                     res.writeHead(200, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({ success: true, message: 'Connecting to relay...' }));
                 } catch (err) {
@@ -9556,66 +10117,17 @@ Explore the project structure and key files to understand what it does, then out
                     relayWs = null;
                 }
 
-                // 3. Open WS as host with this code (mirrors /relay/connect logic)
+                // 3. Open WS as host with this code (uses shared handler).
                 try {
+                    // User-initiated re-pair — wipe any prior persistent
+                    // state so the next 'paired' event installs the new
+                    // sessionToken cleanly.
+                    clearRelayState();
+                    currentRelayDeviceId = null;
                     const url = `${relayUrl}?code=${encodeURIComponent(code)}&role=host`;
                     const ws = new WebSocket(url);
-
-                    ws.on('open', () => {
-                        console.log('[relay] start-pairing: host WS opened');
-                        relayConnected = true;
-                        broadcast({ type: 'relay_status', payload: { connected: true } });
-                    });
-
-                    ws.on('message', (data) => {
-                        try {
-                            const msg = JSON.parse(data.toString());
-
-                            if (msg.type === 'paired') {
-                                relaySessionToken = msg.payload?.sessionToken;
-                                console.log('[relay] start-pairing: paired with mobile');
-                                const { id: deviceId, token: authToken } = registerDevice({ name: 'Mobile Device' });
-                                currentRelayDeviceId = deviceId;
-                                sendRelayEnvelope('auth_grant', { deviceId, authToken, issuedAt: Date.now() });
-                                broadcast({ type: 'relay_status', payload: { connected: true, paired: true, deviceId } });
-                                broadcast({ type: 'devices_changed', payload: { devices: listDevicesSafe() } });
-                                sendToRelay({ type: 'sessions', payload: getSessions() });
-                                sendToRelay({ type: 'projects', payload: projectsManager.getProjects() });
-                                return;
-                            }
-                            if (msg.type === 'waiting') {
-                                if (msg.payload?.sessionToken) relaySessionToken = msg.payload.sessionToken;
-                                broadcast({ type: 'relay_status', payload: { connected: true, paired: false, waiting: true } });
-                                return;
-                            }
-                            if (msg.type === 'ping') {
-                                if (ws.readyState === 1) ws.send(JSON.stringify({ type: 'pong', from: 'host', timestamp: Date.now(), seq: 0 }));
-                                return;
-                            }
-                            if (msg.type === 'mobile_disconnected') {
-                                broadcast({ type: 'relay_status', payload: { connected: true, paired: false } });
-                                return;
-                            }
-                            if (msg.type === 'relay_message' && msg.payload) {
-                                handleRelayRequest(msg.payload, ws);
-                                return;
-                            }
-                        } catch (e) {
-                            console.error('[relay] start-pairing: error processing message:', e);
-                        }
-                    });
-
-                    ws.on('close', () => {
-                        relayWs = null;
-                        relayConnected = false;
-                        relaySessionToken = null;
-                        currentRelayDeviceId = null;
-                        broadcast({ type: 'relay_status', payload: { connected: false } });
-                    });
-
-                    ws.on('error', (err) => console.error('[relay] start-pairing WS error:', err.message));
                     relayWs = ws;
-
+                    setupRelayHostWs(ws, { reconnect: false });
                     res.writeHead(200, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({ code, expiresIn, relayUrl, relayApiUrl }));
                 } catch (err) {
@@ -9643,6 +10155,16 @@ Explore the project structure and key files to understand what it does, then out
     }
 
     if (req.method === 'POST' && req.url === '/relay/disconnect') {
+        // User-initiated disconnect — clear persisted state too so the
+        // auto-reconnect loop doesn't immediately rebuild the connection
+        // we just tore down. (The close handler in setupRelayHostWs would
+        // otherwise see the saved token and reconnect.)
+        clearRelayState();
+        _relayReconnectAttempts = 0;
+        if (_relayReconnectTimer) {
+            clearTimeout(_relayReconnectTimer);
+            _relayReconnectTimer = null;
+        }
         if (relayWs) {
             try { relayWs.close(); } catch {}
             relayWs = null;
@@ -9695,6 +10217,86 @@ Explore the project structure and key files to understand what it does, then out
         return;
     }
 
+    // POST /local/pair-init — host-only (loopback). Generates a 6-digit
+    // single-use code that the mobile can claim via /pair-claim within 5
+    // min. Use this when the Fly relay is unreachable or rate-limited.
+    if (req.method === 'POST' && req.url === '/local/pair-init') {
+        if (!isLoopbackRequest(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Local pairing must be initiated from the host machine (loopback only)' }));
+            return;
+        }
+        pruneLocalPairCodes();
+        const code = generateLocalPairCode();
+        localPairCodes.set(code, { createdAt: Date.now() });
+        log(`[local-pair] issued code (5 min ttl)`);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ code, expiresInSec: Math.floor(LOCAL_PAIR_TTL_MS / 1000) }));
+        return;
+    }
+
+    // POST /pair-claim — Funnel-accessible. Body: { code }. The code IS
+    // the authorization (mirrors the relay /pair model). Brute-force-
+    // resistant via per-IP rate limit on attempts (60 / 5 min) and the
+    // codes themselves being short-lived + single-use.
+    if (req.method === 'POST' && req.url === '/pair-claim') {
+        const ip = getRequestIP(req);
+        if (!checkPairClaimRateLimit(ip)) {
+            log(`[local-pair] rate-limit ip=${ip}`);
+            res.writeHead(429, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Too many attempts. Try again in a few minutes.' }));
+            return;
+        }
+        collectRequestBody(req).then(body => {
+            try {
+                pruneLocalPairCodes();
+                const parsed = JSON.parse(body || '{}');
+                const code = typeof parsed.code === 'string' ? parsed.code.trim() : '';
+                if (!/^\d{6}$/.test(code)) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Invalid code format — must be 6 digits' }));
+                    return;
+                }
+                const entry = localPairCodes.get(code);
+                if (!entry) {
+                    res.writeHead(404, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Code not found or expired' }));
+                    return;
+                }
+                // Burn first so a slow second claim races and the code can't
+                // be replayed from an HTTP log.
+                localPairCodes.delete(code);
+                const revokedIds = enforceMaxDevicesBeforePairing();
+                const ua = req.headers['user-agent'] || null;
+                const { id: deviceId, token: authToken } = registerDevice({
+                    name: 'Mobile Device (local)',
+                    userAgent: ua,
+                });
+                broadcast({ type: 'devices_changed', payload: { devices: listDevicesSafe() } });
+                broadcast({ type: 'device_paired', payload: { deviceId, revokedIds, name: 'Mobile Device (local)' } });
+                log(`[local-pair] claimed ip=${ip} device=${deviceId}`);
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    deviceId,
+                    authToken,
+                    issuedAt: Date.now(),
+                    // Tell the mobile how to reach this backend directly via
+                    // the public internet (Tailscale Funnel). Lets the mobile
+                    // skip the Fly relay for read paths + WS, even when
+                    // loaded from vibing.team. null when Funnel isn't set up.
+                    funnelHost: getFunnelHostname(),
+                }));
+            } catch (e) {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: e.message || 'Invalid request' }));
+            }
+        }).catch(() => {
+            res.writeHead(413, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Request body too large' }));
+        });
+        return;
+    }
+
     // DELETE /devices/:id — revoke a device's auth token
     {
         const m = req.url && req.method === 'DELETE' && req.url.match(/^\/devices\/([a-zA-Z0-9_-]+)$/);
@@ -9723,6 +10325,38 @@ Explore the project structure and key files to understand what it does, then out
         }
     }
 
+    // POST /devices/cleanup — hard-delete revoked + stale devices
+    // Body: { keep?: number } — keep this many most-recently-used unrevoked
+    // devices (default 5). Everything else is removed from disk.
+    if (req.method === 'POST' && req.url === '/devices/cleanup') {
+        collectRequestBody(req).then(body => {
+            try {
+                const { keep = 5 } = (body ? JSON.parse(body) : {}) || {};
+                const all = Array.from(devices.values());
+                const unrevoked = all.filter(d => !d.revoked).sort((a, b) => b.lastSeen - a.lastSeen);
+                const keepIds = new Set(unrevoked.slice(0, Math.max(1, keep)).map(d => d.id));
+                let removed = 0;
+                for (const d of all) {
+                    if (!keepIds.has(d.id)) {
+                        devices.delete(d.id);
+                        removed++;
+                    }
+                }
+                saveDevices();
+                broadcast({ type: 'devices_changed', payload: { devices: listDevicesSafe() } });
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: true, removed, kept: keepIds.size }));
+            } catch (e) {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: e.message }));
+            }
+        }).catch(() => {
+            res.writeHead(413, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Body too large' }));
+        });
+        return;
+    }
+
     // POST /devices/:id/rename — rename a device
     {
         const m = req.url && req.method === 'POST' && req.url.match(/^\/devices\/([a-zA-Z0-9_-]+)\/rename$/);
@@ -9924,8 +10558,19 @@ function main() {
     watchEventsFile();
     // Create HTTP server
     const httpServer = createServer(handleHttpRequest);
-    // Create WebSocket server
-    const wss = new WebSocketServer({ server: httpServer });
+    // Create WebSocket server. handleProtocols echoes the first offered
+    // subprotocol back to the client — required because mobile clients
+    // pass `vibeteam-auth.<token>` as a subprotocol to authenticate the
+    // upgrade. Without echoing, browsers treat the missing
+    // Sec-WebSocket-Protocol response header as a handshake failure and
+    // close the connection.
+    const wss = new WebSocketServer({
+        server: httpServer,
+        handleProtocols: (protocols /* Set<string> */) => {
+            for (const p of protocols) return p;
+            return false;
+        },
+    });
 
     // WebSocket ping/pong heartbeat: detects "zombie" connections where TCP
     // is dead but Node's `ws` library still reports readyState === OPEN. Without
@@ -9954,6 +10599,36 @@ function main() {
             ws.close(1008, 'Origin not allowed');
             return;
         }
+        // Auth gate for remote-ish connections. We can't trust the TCP
+        // socket's remoteAddress here because Tailscale Funnel proxies
+        // through tailscaled on 127.0.0.1 — it would falsely look like
+        // loopback. Instead mirror the HTTP gate (line ~6740): if the
+        // request came in via Funnel OR the Origin's hostname isn't
+        // localhost, treat it as remote and require deviceAuth via the
+        // Sec-WebSocket-Protocol subprotocol "vibeteam-auth.<token>"
+        // (only header browsers allow on a WS connection).
+        const isFunnelRequest = req.headers['tailscale-funnel-request'] === '?1';
+        let originHost = '';
+        try { originHost = origin ? new URL(origin).hostname.toLowerCase() : ''; } catch {}
+        const isLocalOrigin = originHost === 'localhost' || originHost === '127.0.0.1' || originHost === '::1' || originHost === '0.0.0.0' || originHost === '';
+        const requireAuth = isFunnelRequest || !isLocalOrigin;
+        if (requireAuth) {
+            const proto = ws.protocol || '';
+            if (!proto.startsWith('vibeteam-auth.')) {
+                log(`[ws-auth] Rejected remote WS without auth subprotocol from ${origin}`);
+                ws.close(1008, 'Authentication required (vibeteam-auth.<token> subprotocol)');
+                return;
+            }
+            const token = proto.slice('vibeteam-auth.'.length);
+            const device = validateAuthToken(token);
+            if (!device) {
+                log(`[ws-auth] Invalid token from ${origin}`);
+                ws.close(1008, 'Invalid auth token');
+                return;
+            }
+            ws.deviceId = device.id; // for downstream use / debugging
+            log(`[ws-auth] Accepted device=${device.id} origin=${origin}${isFunnelRequest ? ' via=funnel' : ''}`);
+        }
         ws.isAlive = true;
         ws.on('pong', markAlive);
         clients.add(ws);
@@ -10054,6 +10729,19 @@ function main() {
         log(`  Health: http://localhost:${PORT}/health`);
         log(`  Stats: http://localhost:${PORT}/stats`);
         log(`  Sessions: http://localhost:${PORT}/sessions`);
+        // Restore relay session if we shut down cleanly. The relay accepts
+        // host reconnect with a 24h sessionToken — if the saved token is
+        // still valid, the mobile transparently re-pairs with no user
+        // interaction. If the token is gone or rejected, we silently fall
+        // back to "needs pairing" (relay-status pill goes red on mobile).
+        const savedRelay = readRelayState();
+        if (savedRelay?.sessionToken) {
+            log(`[relay] found saved sessionToken on disk; attempting auto-reconnect`);
+            // Slight delay so the listen log lines stay ordered + log() is
+            // ready before reconnect noise.
+            setTimeout(connectRelayWithSavedToken, 500).unref();
+        }
+
         // Start token polling after server is ready
         startTokenPolling();
         // Start permission prompt polling