@blockrun/franklin 3.16.4 → 3.18.0

package/dist/agent/context.js

@@ -150,7 +150,17 @@ RULES (violations will produce garbage output):
 6. End with: "Reply to any? Give me the number."
 7. Do NOT auto-post. Do NOT explain how the social system works.
 
-When checking notifications/mentions: Use SearchX with mode="notifications". One call, done.`;
+When the user pastes a specific tweet URL (https://x.com/<user>/status/<id>): Call SearchX with the URL as the query. The tool auto-detects URL mode and reads the post directly. Do NOT search for the URL as a keyword (always returns empty), and do NOT try WebFetch on x.com.
+
+When checking notifications/mentions: Use SearchX with mode="notifications". One call, done.
+
+If SearchX returns empty or "no article extracted" on a URL/query you believe SHOULD have content (you can see the page in the browser, or the user confirms it exists), DO NOT give up — drop down to the BrowserX primitive and drive the browser yourself:
+  1. BrowserX action="snapshot" → see what's on screen right now
+  2. BrowserX action="scroll" dy=600 → trigger lazy-render / load more
+  3. BrowserX action="snapshot" again → re-inspect after scroll
+  4. BrowserX action="click" ref=<id> → follow a permalink (refs come from the last snapshot)
+  5. BrowserX action="open" url=<other> → try a different URL (e.g. /search?q=… or a profile page)
+BrowserX shares the logged-in X session with SearchX, so authentication is already handled. Use BrowserX only for read/navigation; replies still go through PostToX with explicit user confirmation.`;
 }
 function getMissingAccessSection() {
     return `# Missing Access

package/dist/agent/error-classifier.js

@@ -184,6 +184,21 @@ export function classifyAgentError(message) {
             suggestion: 'Tool schema rejected by this model. Try /model to switch to a more permissive model (e.g. sonnet), or upgrade Franklin.',
         };
     }
+    // Unknown / typo'd model id — gateway returns HTTP 400 with a body like
+    // "Unknown model: moonshot/kimi-k2". Without this branch the error falls
+    // through to the catch-all 'unknown' category and shows the user a bare
+    // "Type: Unknown" with no actionable next step.
+    if (includesAny(err, [
+        'unknown model',
+        'model not found',
+        'model does not exist',
+        'no such model',
+    ])) {
+        return {
+            category: 'schema', label: 'Schema', isTransient: false, maxRetries: 0,
+            suggestion: 'The gateway rejected the model id (unknown / typo). Use /model to pick a valid one, or upgrade Franklin if a fallback chain references a stale id.',
+        };
+    }
     if (includesAny(err, [
         '500',
         '502',

package/dist/agent/loop.js

@@ -341,6 +341,13 @@ export function looksLikeStalledIntent(text) {
     const trimmed = text.trim();
     if (trimmed.length < 24)
         return false;
+    // If the final non-empty line is a short question to the user, the model is
+    // explicitly deferring ("Which would you prefer?", "Want me to proceed?") —
+    // that's a handoff, not a stall. Avoid re-invoking on another model and
+    // billing twice for what is in fact correct behavior.
+    const lastLine = trimmed.split(/\n+/).map(s => s.trim()).filter(Boolean).pop() ?? '';
+    if (lastLine.length > 0 && lastLine.length <= 120 && /[?？]\s*$/.test(lastLine))
+        return false;
     // Look at the last ~400 chars only — intent-to-act lives near the end.
     const tail = trimmed.slice(-400).toLowerCase();
     // Strong "I'm about to do something" markers near the tail.
@@ -1336,7 +1343,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                         // Excludes nvidia/* and *-coder-* — they're the source population.
                         const TOOL_USE_FALLBACK_MODELS = [
                             'anthropic/claude-haiku-4.5',
-                            'moonshot/kimi-k2',
+                            'moonshot/kimi-k2.6',
                             'openai/gpt-5',
                             'anthropic/claude-sonnet-4.6',
                         ];

package/dist/agent/permissions.js

@@ -33,10 +33,10 @@ function isCommonDevCommand(cmd) {
     return COMMON_DEV_PATTERNS.some(p => p.test(trimmed));
 }
 // ─── Default Rules ─────────────────────────────────────────────────────────
-const READ_ONLY_TOOLS = new Set(['Read', 'Glob', 'Grep', 'WebSearch', 'Task', 'AskUser', 'ActivateTool', 'ImageGen', 'TradingSignal', 'TradingMarket', 'SearchX']);
+const READ_ONLY_TOOLS = new Set(['Read', 'Glob', 'Grep', 'WebSearch', 'Task', 'AskUser', 'ActivateTool', 'ImageGen', 'TradingSignal', 'TradingMarket', 'SearchX', 'BrowserX']);
 const DESTRUCTIVE_TOOLS = new Set(['Write', 'Edit', 'Bash']);
 const DEFAULT_RULES = {
-    allow: ['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch', 'Task', 'AskUser', 'ActivateTool', 'ImageGen', 'TradingSignal', 'TradingMarket', 'SearchX'],
+    allow: ['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch', 'Task', 'AskUser', 'ActivateTool', 'ImageGen', 'TradingSignal', 'TradingMarket', 'SearchX', 'BrowserX'],
     deny: [],
     ask: ['Write', 'Edit', 'Bash', 'Agent', 'PostToX'],
 };

package/dist/agent/tool-guard.js

@@ -183,6 +183,13 @@ export class SessionToolGuard {
     startTurn() {
         this.turn++;
         this.webSearchesThisTurn = 0;
+        // The per-tool circuit breaker exists to stop a model from burning a
+        // whole turn re-attacking a wall. It must NOT outlive the user turn that
+        // earned the failures — a fresh prompt is a fresh intent. Without this
+        // reset, three failed Bash calls (e.g. `franklin social login x` on a
+        // host without the right env) permanently disable Bash for the rest of
+        // the session, even on completely unrelated follow-ups.
+        this.toolErrorCounts.clear();
         for (const family of this.searchFamilies) {
             family.turnSearches = 0;
         }
@@ -233,6 +240,32 @@ export class SessionToolGuard {
         const cmd = String(invocation.input.command ?? '').trim();
         if (!cmd)
             return null;
+        // Reject interactive franklin subcommands that require the human at the
+        // keyboard (they spawn a non-headless Chrome and wait for the user to
+        // close it). If the agent runs them via Bash they block until timeout,
+        // burn a tool-failure strike, and contribute nothing. Tell the agent to
+        // ask the user to run them in a separate terminal instead.
+        if (/^\s*franklin\s+social\s+(login|setup)\b/.test(cmd)) {
+            return {
+                output: 'Blocked: `franklin social login` / `franklin social setup` are INTERACTIVE — ' +
+                    'they open a Chrome window the human must drive and close. They cannot run from ' +
+                    'an agent Bash call (they will hang then time out). ' +
+                    'Ask the user to run this in their own terminal, then continue once they say it is done.',
+                isError: true,
+            };
+        }
+        // `franklin social run` is a batch poster/replier that loops over the
+        // user's configured search_queries — it is not the right tool for
+        // "read this specific tweet" or "draft replies to one post". Steer the
+        // agent to SearchX (now URL-aware) instead.
+        if (/^\s*franklin\s+social\s+run\b/.test(cmd)) {
+            return {
+                output: 'Blocked: `franklin social run` is a batch reply loop over the user\'s configured ' +
+                    'queries, not a single-tweet reader. Use the SearchX tool instead — pass a tweet URL ' +
+                    'as the query to read one post, or use mode="search"/"notifications" for discovery.',
+                isError: true,
+            };
+        }
         // Reject blocking poll-loops in foreground bash. A single bash call with
         // `sleep N` inside a for/while/until loop blocks the agent for the full
         // duration — the UI repeats the same status line and the user almost

package/dist/panel/html.js

@@ -410,6 +410,63 @@ a:hover { text-decoration:underline; }
 .btn-danger { background:oklch(0.65 0.20 25 / 18%); color:var(--danger); border-color:oklch(0.65 0.20 25 / 35%); }
 .btn-danger:hover { background:oklch(0.65 0.20 25 / 30%); }
 
+.nav-badge {
+  margin-left:auto; font-size:10px; font-weight:700; letter-spacing:0.3px;
+  padding:2px 7px; border-radius:8px;
+  background:oklch(0.65 0.20 25 / 22%); color:var(--danger);
+  border:1px solid oklch(0.65 0.20 25 / 35%);
+}
+.nav-badge.warn { background:oklch(0.78 0.14 85 / 22%); color:var(--gold); border-color:oklch(0.78 0.14 85 / 35%); }
+
+.phone-list { display:flex; flex-direction:column; gap:10px; }
+.phone-row {
+  display:grid; grid-template-columns:auto 1fr auto; gap:14px; align-items:center;
+  padding:14px 16px; background:var(--bg-card); border:1px solid var(--border);
+  border-radius:var(--radius); transition:border-color 0.15s, background 0.15s;
+}
+.phone-row:hover { background:var(--bg-card-hover); }
+.phone-row.warn { border-color:oklch(0.78 0.14 85 / 50%); }
+.phone-row.crit { border-color:oklch(0.65 0.20 25 / 55%); }
+.phone-row.expired { opacity:0.65; border-color:oklch(0.65 0.20 25 / 45%); }
+.phone-icon-bubble {
+  width:36px; height:36px; border-radius:10px; display:grid; place-items:center;
+  background:oklch(0.68 0.16 260 / 18%); color:var(--brand);
+}
+.phone-main { display:flex; flex-direction:column; gap:3px; min-width:0; }
+.phone-num {
+  font-family:var(--mono); font-size:15px; font-weight:600; color:var(--text);
+  letter-spacing:0.02em;
+}
+.phone-meta { font-size:12px; color:var(--text-muted); display:flex; gap:10px; flex-wrap:wrap; }
+.phone-meta .chip {
+  display:inline-flex; align-items:center; gap:4px;
+  padding:2px 7px; border-radius:6px; background:oklch(0 0 0 / 25%);
+  font-size:10.5px; letter-spacing:0.5px; text-transform:uppercase; font-weight:700;
+}
+.phone-meta .chip.green { color:var(--success); background:oklch(0.65 0.18 145 / 18%); }
+.phone-meta .chip.amber { color:var(--gold);    background:oklch(0.78 0.14 85 / 20%); }
+.phone-meta .chip.red   { color:var(--danger);  background:oklch(0.65 0.20 25 / 20%); }
+.phone-row .phone-actions { display:flex; align-items:center; gap:6px; }
+.phone-row.expired .phone-num { text-decoration:line-through; }
+
+.phone-empty {
+  padding:24px; text-align:center; border:1px dashed var(--border);
+  border-radius:var(--radius); color:var(--text-muted); font-size:13px;
+  line-height:1.6;
+}
+.phone-empty strong { color:var(--text); font-weight:600; display:block; margin-bottom:6px; font-size:14px; }
+
+.phone-buy-form { display:flex; gap:8px; flex-wrap:wrap; align-items:center; margin-top:10px; }
+.phone-buy-form select, .phone-buy-form input {
+  padding:7px 10px; background:oklch(0 0 0 / 35%); color:var(--text);
+  border:1px solid var(--border); border-radius:7px; font-size:13px;
+  font-family:var(--mono);
+}
+.phone-buy-form input { width:120px; }
+.phone-status { font-size:12px; color:var(--text-muted); }
+.phone-status.ok  { color:var(--success); }
+.phone-status.err { color:var(--danger); }
+
 @media (max-width:768px) {
   body { flex-direction:column; }
   .sidebar { width:100%; min-width:100%; flex-direction:row; padding:8px; overflow-x:auto; border-right:none; border-bottom:1px solid var(--border); }
@@ -455,6 +512,11 @@ a:hover { text-decoration:underline; }
       <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M3 3v18h18"/><path d="M7 14l4-4 4 4 5-5"/></svg>
       Markets
     </button>
+    <button class="nav-item" data-tab="phone">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M22 16.92v3a2 2 0 0 1-2.18 2 19.79 19.79 0 0 1-8.63-3.07 19.5 19.5 0 0 1-6-6 19.79 19.79 0 0 1-3.07-8.67A2 2 0 0 1 4.11 2h3a2 2 0 0 1 2 1.72 12.84 12.84 0 0 0 .7 2.81 2 2 0 0 1-.45 2.11L8.09 9.91a16 16 0 0 0 6 6l1.27-1.27a2 2 0 0 1 2.11-.45 12.84 12.84 0 0 0 2.81.7A2 2 0 0 1 22 16.92z"/></svg>
+      Phone
+      <span class="nav-badge" id="phone-nav-badge" style="display:none"></span>
+    </button>
     <button class="nav-item" data-tab="sessions">
       <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg>
       Sessions
@@ -677,6 +739,46 @@ a:hover { text-decoration:underline; }
     </div>
   </div>
 
+  <!-- Phone & Voice -->
+  <div class="tab" id="tab-phone">
+    <div class="content-header">
+      <h2>Phone &amp; Voice</h2>
+      <p>Numbers your wallet owns. Leases run 30 days &mdash; renew before they expire or set auto-renew.</p>
+    </div>
+
+    <div class="card" style="margin-bottom:16px">
+      <div style="display:flex;align-items:center;justify-content:space-between;gap:12px;flex-wrap:wrap;">
+        <h3 style="margin:0">Your numbers</h3>
+        <div style="display:flex;gap:8px;align-items:center">
+          <span class="phone-status" id="phone-list-status"></span>
+          <button class="btn btn-ghost" id="phone-refresh-btn" title="Refetch from BlockRun ($0.001)">Refresh</button>
+        </div>
+      </div>
+      <div id="phone-list" style="margin-top:12px">
+        <div class="phone-empty">Loading&hellip;</div>
+      </div>
+    </div>
+
+    <div class="card">
+      <h3 style="margin:0 0 6px">Add another number</h3>
+      <p class="wallet-hint">
+        $5 USDC for a fresh number, bound to your wallet for 30 days. <strong>This adds
+        a new number alongside any you already own &mdash; nothing is replaced.</strong>
+        Use it as caller ID for outbound AI voice calls, or (soon) to receive inbound calls.
+        Multiple numbers are fine; release any you no longer need to stop paying renewals on them.
+      </p>
+      <div class="phone-buy-form">
+        <select id="phone-buy-country">
+          <option value="US">United States (+1)</option>
+          <option value="CA">Canada (+1)</option>
+        </select>
+        <input id="phone-buy-areacode" placeholder="Area code (opt)" maxlength="6" />
+        <button class="btn btn-warn" id="phone-buy-btn">Buy for $5</button>
+        <span class="phone-status" id="phone-buy-status"></span>
+      </div>
+    </div>
+  </div>
+
   <!-- Learnings -->
   <div class="tab" id="tab-learnings">
     <div class="content-header">
@@ -1544,6 +1646,307 @@ document.addEventListener('visibilitychange', () => {
 
 document.getElementById('tasks-refresh-btn')?.addEventListener('click', fetchTasks);
 
+// ─── Phone & Voice ──────────────────────────────────────────────────────
+// Renders the user's wallet-owned numbers, days-remaining countdown,
+// renew / release / auto-renew controls, and the buy form. Drives the
+// sidebar nav badge so users with an expiring number see it even from
+// the Overview tab. Notification ladder uses the Notifications API,
+// dedupe-keyed in sessionStorage so we don't spam the user every open.
+
+const phoneState = { data: null, countdownTimer: null };
+
+function formatPhoneNumber(e164) {
+  // E.164 → human, for display only. Keep raw value for actions.
+  if (!e164) return '—';
+  const m = String(e164).match(/^\\+1(\\d{3})(\\d{3})(\\d{4})$/);
+  if (m) return '+1 (' + m[1] + ') ' + m[2] + '-' + m[3];
+  return e164;
+}
+
+function daysLeft(expiresAt) {
+  const expiry = new Date(expiresAt).getTime();
+  if (isNaN(expiry)) return 0;
+  return Math.floor((expiry - Date.now()) / 86400000);
+}
+
+function phoneTier(days) {
+  if (days < 0) return 'expired';
+  if (days <= 2) return 'crit';
+  if (days <= 7) return 'warn';
+  return 'ok';
+}
+
+function phoneChipClass(tier) {
+  if (tier === 'expired' || tier === 'crit') return 'red';
+  if (tier === 'warn') return 'amber';
+  return 'green';
+}
+
+function phoneCountdownLabel(days) {
+  if (days < 0) return 'expired ' + Math.abs(days) + 'd ago';
+  if (days === 0) return 'expires today';
+  if (days === 1) return '1 day left';
+  return days + ' days left';
+}
+
+function updatePhoneNavBadge(numbers) {
+  const badge = document.getElementById('phone-nav-badge');
+  if (!badge) return;
+  let worst = 999;
+  let anyExpired = false;
+  numbers.forEach(n => {
+    const d = daysLeft(n.expires_at);
+    if (d < 0) anyExpired = true;
+    if (d < worst) worst = d;
+  });
+  if (anyExpired) {
+    badge.textContent = '!'; badge.className = 'nav-badge'; badge.style.display = '';
+  } else if (worst <= 2) {
+    badge.textContent = worst + 'd'; badge.className = 'nav-badge'; badge.style.display = '';
+  } else if (worst <= 7) {
+    badge.textContent = worst + 'd'; badge.className = 'nav-badge warn'; badge.style.display = '';
+  } else {
+    badge.style.display = 'none';
+  }
+}
+
+function maybeNotifyExpiry(numbers) {
+  if (typeof Notification === 'undefined') return;
+  if (Notification.permission !== 'granted') return;
+  numbers.forEach(n => {
+    const d = daysLeft(n.expires_at);
+    let mark = null;
+    if (d < 0) mark = 'expired';
+    else if (d <= 1) mark = 't1';
+    else if (d <= 3) mark = 't3';
+    else if (d <= 7) mark = 't7';
+    if (!mark) return;
+    const key = 'phone:notify:' + n.phone_number + ':' + mark;
+    if (sessionStorage.getItem(key)) return;
+    sessionStorage.setItem(key, '1');
+    const human = formatPhoneNumber(n.phone_number);
+    const title = 'Franklin: ' + human;
+    const body = mark === 'expired'
+      ? 'This number has expired. Provision a new one in the Phone tab.'
+      : (mark === 't1'
+        ? 'Expires in 1 day. Click to renew for $5.'
+        : (mark === 't3'
+          ? 'Expires in 3 days. Click to renew for $5.'
+          : 'Expires in a week. Renew when convenient.'));
+    try {
+      const notif = new Notification(title, { body, tag: key });
+      notif.onclick = () => {
+        try { window.focus(); } catch (e) {}
+        location.hash = 'phone';
+        activateTab('phone');
+        notif.close();
+      };
+    } catch (e) { /* ignore */ }
+  });
+}
+
+function renderPhoneNumbers(data) {
+  const list = document.getElementById('phone-list');
+  if (!list) return;
+  const numbers = (data && data.numbers) || [];
+  updatePhoneNavBadge(numbers);
+
+  if (!numbers.length) {
+    list.innerHTML = '<div class="phone-empty">' +
+      '<strong>No numbers yet</strong>' +
+      'Provision a number below to give Franklin a phone identity. ' +
+      'Numbers cost $5 for a 30-day lease and are bound to your wallet.' +
+      '</div>';
+    return;
+  }
+
+  const html = numbers.map(n => {
+    const d = daysLeft(n.expires_at);
+    const tier = phoneTier(d);
+    const chipCls = phoneChipClass(tier);
+    const rowCls = tier === 'ok' ? '' : (' ' + tier);
+    const human = formatPhoneNumber(n.phone_number);
+    const renewBtn = tier === 'expired'
+      ? ''
+      : '<button class="btn btn-warn" data-phone-renew="' + n.phone_number + '">Renew $5</button>';
+    const releaseLabel = tier === 'expired' ? 'Remove' : 'Release';
+    return ''
+      + '<div class="phone-row' + rowCls + '">'
+      + '  <div class="phone-icon-bubble">'
+      + '    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">'
+      + '      <path d="M22 16.92v3a2 2 0 0 1-2.18 2 19.79 19.79 0 0 1-8.63-3.07 19.5 19.5 0 0 1-6-6 19.79 19.79 0 0 1-3.07-8.67A2 2 0 0 1 4.11 2h3a2 2 0 0 1 2 1.72 12.84 12.84 0 0 0 .7 2.81 2 2 0 0 1-.45 2.11L8.09 9.91a16 16 0 0 0 6 6l1.27-1.27a2 2 0 0 1 2.11-.45 12.84 12.84 0 0 0 2.81.7A2 2 0 0 1 22 16.92z"/>'
+      + '    </svg>'
+      + '  </div>'
+      + '  <div class="phone-main">'
+      + '    <div class="phone-num">' + human + '</div>'
+      + '    <div class="phone-meta">'
+      + '      <span class="chip">' + (n.chain || '—') + '</span>'
+      + '      <span class="chip ' + chipCls + '">' + phoneCountdownLabel(d) + '</span>'
+      + '    </div>'
+      + '  </div>'
+      + '  <div class="phone-actions">'
+      +      renewBtn
+      + '    <button class="btn btn-ghost" data-phone-release="' + n.phone_number + '" title="' + releaseLabel + ' this number">' + releaseLabel + '</button>'
+      + '  </div>'
+      + '</div>';
+  }).join('');
+
+  list.innerHTML = html;
+
+  list.querySelectorAll('[data-phone-renew]').forEach(btn => {
+    btn.addEventListener('click', () => renewPhoneNumber(btn.getAttribute('data-phone-renew')));
+  });
+  list.querySelectorAll('[data-phone-release]').forEach(btn => {
+    btn.addEventListener('click', () => releasePhoneNumber(btn.getAttribute('data-phone-release')));
+  });
+
+  maybeNotifyExpiry(numbers);
+}
+
+async function loadPhone(opts) {
+  const force = !!(opts && opts.force);
+  const statusEl = document.getElementById('phone-list-status');
+  if (statusEl) statusEl.textContent = force ? 'Refreshing…' : 'Loading…';
+  try {
+    const url = '/api/phone/numbers';
+    const r = force
+      ? await fetch('/api/phone/numbers/refresh', { method: 'POST' })
+      : await fetch(url);
+    const data = await r.json();
+    if (!r.ok) {
+      if (statusEl) { statusEl.textContent = data.error || 'Failed to load'; statusEl.className = 'phone-status err'; }
+      const list = document.getElementById('phone-list');
+      if (list) list.innerHTML = '<div class="phone-empty"><strong>Could not load numbers</strong>' + (data.error || 'Unknown error') + '</div>';
+      return;
+    }
+    phoneState.data = data;
+    renderPhoneNumbers(data);
+    if (statusEl) {
+      statusEl.className = 'phone-status';
+      statusEl.textContent = data.fromCache
+        ? 'Cached ' + new Date(data.fetchedAt).toLocaleTimeString()
+        : 'Synced ' + new Date(data.fetchedAt || Date.now()).toLocaleTimeString();
+    }
+  } catch (err) {
+    if (statusEl) { statusEl.textContent = 'Network error'; statusEl.className = 'phone-status err'; }
+  }
+}
+
+async function renewPhoneNumber(num) {
+  const statusEl = document.getElementById('phone-list-status');
+  if (statusEl) { statusEl.textContent = 'Renewing ' + formatPhoneNumber(num) + '…'; statusEl.className = 'phone-status'; }
+  try {
+    const r = await fetch('/api/phone/numbers/renew', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ phoneNumber: num }),
+    });
+    const data = await r.json();
+    if (!r.ok) {
+      if (statusEl) { statusEl.textContent = data.error || 'Renew failed'; statusEl.className = 'phone-status err'; }
+      return;
+    }
+    // Clear dedupe keys so a renewed number can re-notify if it expires again later
+    Object.keys(sessionStorage).filter(k => k.startsWith('phone:notify:' + num + ':')).forEach(k => sessionStorage.removeItem(k));
+    if (statusEl) { statusEl.textContent = 'Renewed — new expiry ' + new Date(data.expires_at).toLocaleDateString(); statusEl.className = 'phone-status ok'; }
+    await loadPhone({});
+  } catch (err) {
+    if (statusEl) { statusEl.textContent = 'Network error'; statusEl.className = 'phone-status err'; }
+  }
+}
+
+async function releasePhoneNumber(num) {
+  if (!confirm('Release ' + formatPhoneNumber(num) + '? This permanently gives up the number and cannot be undone.')) return;
+  const statusEl = document.getElementById('phone-list-status');
+  if (statusEl) { statusEl.textContent = 'Releasing…'; statusEl.className = 'phone-status'; }
+  try {
+    const r = await fetch('/api/phone/numbers/release', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ phoneNumber: num }),
+    });
+    const data = await r.json();
+    if (!r.ok) {
+      if (statusEl) { statusEl.textContent = data.error || 'Release failed'; statusEl.className = 'phone-status err'; }
+      return;
+    }
+    if (statusEl) { statusEl.textContent = 'Released ' + formatPhoneNumber(num); statusEl.className = 'phone-status ok'; }
+    await loadPhone({});
+  } catch (err) {
+    if (statusEl) { statusEl.textContent = 'Network error'; statusEl.className = 'phone-status err'; }
+  }
+}
+
+async function buyPhoneNumber() {
+  const country = (document.getElementById('phone-buy-country') || {}).value || 'US';
+  const areaCode = ((document.getElementById('phone-buy-areacode') || {}).value || '').trim();
+  const statusEl = document.getElementById('phone-buy-status');
+  const btn = document.getElementById('phone-buy-btn');
+  const existingCount = ((phoneState.data && phoneState.data.numbers) || []).filter(n => daysLeft(n.expires_at) >= 0).length;
+  const intro = existingCount > 0
+    ? 'You already own ' + existingCount + ' active number' + (existingCount === 1 ? '' : 's') + '. This will ADD a new number — nothing is replaced.\\n\\n'
+    : '';
+  if (!confirm(intro + 'Buy a new phone number for $5? It will be charged from your wallet immediately and last 30 days.')) return;
+  if (statusEl) { statusEl.textContent = 'Provisioning…'; statusEl.className = 'phone-status'; }
+  if (btn) btn.disabled = true;
+  try {
+    const r = await fetch('/api/phone/numbers/buy', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ country, areaCode: areaCode || undefined }),
+    });
+    const data = await r.json();
+    if (!r.ok) {
+      if (statusEl) { statusEl.textContent = data.error || 'Purchase failed'; statusEl.className = 'phone-status err'; }
+      return;
+    }
+    if (statusEl) { statusEl.textContent = 'Got ' + formatPhoneNumber(data.phone_number); statusEl.className = 'phone-status ok'; }
+    await loadPhone({});
+  } catch (err) {
+    if (statusEl) { statusEl.textContent = 'Network error'; statusEl.className = 'phone-status err'; }
+  } finally {
+    if (btn) btn.disabled = false;
+  }
+}
+
+function startPhoneCountdown() {
+  if (phoneState.countdownTimer) return;
+  // Re-render every minute so countdown chips age in place. Cheap — no
+  // network, just DOM. Pauses when tab not visible (see visibilitychange).
+  phoneState.countdownTimer = setInterval(() => {
+    if (document.visibilityState !== 'visible') return;
+    if (phoneState.data) renderPhoneNumbers(phoneState.data);
+  }, 60000);
+}
+
+function stopPhoneCountdown() {
+  if (phoneState.countdownTimer) {
+    clearInterval(phoneState.countdownTimer);
+    phoneState.countdownTimer = null;
+  }
+}
+
+document.querySelector('[data-tab="phone"]')?.addEventListener('click', () => {
+  // Ask once for notification permission when the user first opens the tab.
+  // We never auto-prompt on page load — that would be annoying.
+  if (typeof Notification !== 'undefined' && Notification.permission === 'default') {
+    Notification.requestPermission().catch(() => {});
+  }
+  loadPhone({});
+  startPhoneCountdown();
+});
+
+document.addEventListener('tab:deactivated', (e) => {
+  if (e.detail && e.detail.name === 'phone') stopPhoneCountdown();
+});
+
+document.getElementById('phone-refresh-btn')?.addEventListener('click', () => loadPhone({ force: true }));
+document.getElementById('phone-buy-btn')?.addEventListener('click', buyPhoneNumber);
+
+// Prime the nav badge so an expiring number is visible even before the user
+// clicks into the Phone tab. Cached read — no network cost.
+loadPhone({});
+
 loadOverview();
 loadSessions();
 loadMarkets();