mixdog 0.9.65 → 0.9.67

package/src/runtime/agent/orchestrator/session/store-summary-index.mjs

@@ -36,25 +36,67 @@ function _isPreviewNoise(text) {
     return isSessionPreviewNoise(text);
 }
 
-function _sessionPreview(session) {
-    const messages = Array.isArray(session?.messages) ? session.messages : [];
-    for (const m of messages) {
-        if (m?.role !== 'user') continue;
-        const raw = _messageText(m.content);
-        if (_isPreviewNoise(raw)) continue;
-        const text = _cleanPreview(raw);
-        if (text) return text;
-    }
-    return '';
+const sessionMessageProjectionMemo = new WeakMap();
+
+function _previewFromMessage(message) {
+    if (message?.role !== 'user') return '';
+    const raw = _messageText(message.content);
+    if (_isPreviewNoise(raw)) return '';
+    return _cleanPreview(raw);
 }
 
-function _sessionMessageCount(session) {
+function _sessionMessageProjection(session) {
     const messages = Array.isArray(session?.messages) ? session.messages : [];
+    const cached = session && typeof session === 'object'
+        ? sessionMessageProjectionMemo.get(session)
+        : null;
+    let start = 0;
     let count = 0;
-    for (const m of messages) {
-        if (m && (m.role === 'user' || m.role === 'assistant')) count++;
+    let preview = '';
+    let previewMessage = null;
+    const canAppend = cached
+        && messages.length >= cached.length
+        && (cached.length === 0 || messages[cached.length - 1] === cached.lastMessage);
+    if (canAppend) {
+        start = cached.length;
+        count = cached.count;
+        preview = cached.preview;
+        previewMessage = cached.previewMessage;
+        // The first real user message is stable in normal append-only session
+        // flow, but refresh it cheaply so an in-place content scrub still
+        // invalidates the cached title source without rescanning the transcript.
+        if (previewMessage) {
+            const refreshed = _previewFromMessage(previewMessage);
+            if (refreshed) preview = refreshed;
+            else {
+                start = 0;
+                count = 0;
+                preview = '';
+                previewMessage = null;
+            }
+        }
     }
-    return count;
+    for (let index = start; index < messages.length; index += 1) {
+        const message = messages[index];
+        if (message && (message.role === 'user' || message.role === 'assistant')) count += 1;
+        if (!preview) {
+            const candidate = _previewFromMessage(message);
+            if (candidate) {
+                preview = candidate;
+                previewMessage = message;
+            }
+        }
+    }
+    if (session && typeof session === 'object') {
+        sessionMessageProjectionMemo.set(session, {
+            length: messages.length,
+            lastMessage: messages[messages.length - 1] || null,
+            count,
+            preview,
+            previewMessage,
+        });
+    }
+    return { count, preview };
 }
 
 function _positiveNumber(value, fallback = 0) {
@@ -79,9 +121,14 @@ function _desktopSessionSummary(value, cwd = null) {
 
 export function _sessionSummary(session) {
     if (!session?.id) return null;
+    const messageProjection = _sessionMessageProjection(session);
     return {
         id: String(session.id),
         updatedAt: _positiveNumber(session.updatedAt, Date.now()),
+        // Conversation activity is intentionally separate from lifecycle
+        // bookkeeping. Resume/detach saves can advance updatedAt without a
+        // user-visible turn and must not reshuffle Recent session lists.
+        lastUsedAt: _positiveNumber(session.lastUsedAt, 0),
         createdAt: _positiveNumber(session.createdAt, 0),
         lastHeartbeatAt: _positiveNumber(session.lastHeartbeatAt, 0),
         closed: session.closed === true,
@@ -101,10 +148,13 @@ export function _sessionSummary(session) {
         task_id: session.task_id || session.taskId || null,
         permission: session.permission || null,
         toolPermission: session.toolPermission || null,
-        messageCount: _sessionMessageCount(session),
-        preview: _sessionPreview(session),
+        messageCount: messageProjection.count,
+        preview: messageProjection.preview,
         generation: typeof session.generation === 'number' ? session.generation : 0,
         implicitBashSessionId: session.implicitBashSessionId || null,
+        // Lifecycle provenance for catalog filters: resume-machinery scratch
+        // forks (detachedReason='cli-resume') must never surface in Recent.
+        detachedReason: session.detachedReason || null,
     };
 }
 
@@ -113,6 +163,7 @@ function _normalizeSummaryRow(row) {
     return {
         id: row.id,
         updatedAt: _positiveNumber(row.updatedAt, 0),
+        lastUsedAt: _positiveNumber(row.lastUsedAt, 0),
         createdAt: _positiveNumber(row.createdAt, 0),
         lastHeartbeatAt: _positiveNumber(row.lastHeartbeatAt, 0),
         closed: row.closed === true,
@@ -136,6 +187,7 @@ function _normalizeSummaryRow(row) {
         preview: _cleanPreview(row.preview || ''),
         generation: typeof row.generation === 'number' ? row.generation : 0,
         implicitBashSessionId: row.implicitBashSessionId || null,
+        detachedReason: row.detachedReason || null,
     };
 }
 
@@ -173,6 +225,12 @@ const _pendingUpserts = new Map(); // id → summary row (latest wins)
 const _pendingRemovals = new Set(); // ids to drop (upsert/removal are mutually exclusive per id)
 let _summaryRetryTimer = null;
 let _summaryFlushScheduled = false;
+let _summaryFlushInflight = 0;
+
+export function _hasUnsettledSummaryOps() {
+    return _pendingUpserts.size > 0 || _pendingRemovals.size > 0
+        || _summaryFlushScheduled || _summaryFlushInflight > 0;
+}
 
 function _scheduleSummaryRetry() {
     if (_summaryRetryTimer) return;
@@ -206,6 +264,7 @@ export function _flushPendingSummaryOps({ sync = false } = {}) {
     _pendingRemovals.clear();
     const mutate = (cur) => {
             const index = _normalizeSummaryIndex(cur);
+            const existingById = new Map(index.rows.map((row) => [row.id, row]));
             let changed = false;
             const rows = index.rows.filter((r) => {
                 if (removals.has(r.id) || upserts.has(r.id)) { changed = true; return false; }
@@ -214,7 +273,7 @@ export function _flushPendingSummaryOps({ sync = false } = {}) {
             for (const row of upserts.values()) {
                 const cleanRow = _normalizeSummaryRow(row);
                 if (!cleanRow) continue;
-                const existing = index.rows.find((r) => r.id === cleanRow.id) || null;
+                const existing = existingById.get(cleanRow.id) || null;
                 if (existing && JSON.stringify(existing) === JSON.stringify(cleanRow)) {
                     rows.push(existing);
                     continue;
@@ -248,12 +307,18 @@ export function _flushPendingSummaryOps({ sync = false } = {}) {
         } catch { requeue(); }
         return;
     }
+    _summaryFlushInflight++;
     updateJsonAtomic(summaryIndexPath(), mutate, { compact: true, lock: true, timeoutMs: SUMMARY_LOCK_TIMEOUT_MS })
-        .catch(() => { requeue(); });
+        .catch(() => { requeue(); })
+        .finally(() => { _summaryFlushInflight--; });
 }
 
 export function _upsertSessionSummary(session) {
     const row = _sessionSummary(session);
+    _upsertSessionSummaryRow(row);
+}
+
+export function _upsertSessionSummaryRow(row) {
     if (!row) return;
     _pendingRemovals.delete(row.id);
     _pendingUpserts.set(row.id, row);

package/src/runtime/agent/orchestrator/session/store-summary-reader.mjs

@@ -20,6 +20,10 @@ const LEAD_OWNERS = new Set(['cli', 'user', 'mixdog', 'legacy']);
 function isLeadVisibleRow(row) {
     const owner = String(row.owner || 'user').trim().toLowerCase();
     if (owner && !LEAD_OWNERS.has(owner)) return false;
+    // Mirror listLeadSessions: a previewless zero-message row is an unusable
+    // scratch (desktop boot leftovers, crashed first turns) — resuming it
+    // shows an empty conversation, so the catalog hides it.
+    if (!row.preview && row.messageCount === 0) return false;
     const sourceType = String(row.sourceType || '').trim().toLowerCase();
     const sourceName = String(row.sourceName || '').trim().toLowerCase();
     const agent = String(row.agent || '').trim().toLowerCase();
@@ -45,6 +49,11 @@ function cleanText(value, maximum = 240) {
     return String(value || '')
         .replace(/<system-reminder>[\s\S]*?<\/system-reminder>/gi, ' ')
         .replace(/<mcp-instructions>[\s\S]*?<\/mcp-instructions>/gi, ' ')
+        // Session-context envelope (mirror of session-text.mjs
+        // stripSessionDisplayEnvelope): the "# Session / Cwd / Model /
+        // Workflow" header must never become a Recent title.
+        .replace(/^\s*# Session\r?\n(?:(?:Cwd|Model|Workflow):[^\r\n]*(?:\r?\n|$))+(?:\r?\n)?/i, ' ')
+        .replace(/^\s*#\s*Session\s+Cwd:\s+\S+(?:\s+Model:[^\r\n]*?)?(?:\s+Workflow:\s+\S+)?\s*/i, ' ')
         .replace(/\s+/g, ' ')
         .trim()
         .slice(0, maximum);
@@ -101,6 +110,7 @@ function normalizedRow(row, heartbeatAt = 0) {
         preview: cleanText(row.preview),
         generation: typeof row.generation === 'number' ? row.generation : 0,
         implicitBashSessionId: row.implicitBashSessionId || null,
+        detachedReason: row.detachedReason || null,
     };
 }
 
@@ -108,6 +118,10 @@ function rowFromSession(session, heartbeatAt = 0) {
     const messages = Array.isArray(session?.messages) ? session.messages : [];
     const preview = messages
         .filter((message) => message?.role === 'user')
+        // Cold-path mirror of isSessionPreviewNoise's synthetic skips: compact
+        // handoffs and runtime notices must not become session titles.
+        .filter((message) => !/^\s*(?:a previous model worked on this task|re-attached after compaction\b|reference files:\s|\[mixdog-runtime\]|the async (?:agent|shell) task\b)/i
+            .test(messageText(message.content)))
         .map((message) => cleanText(messageText(message.content)))
         .find(Boolean) || '';
     return normalizedRow({

package/src/runtime/agent/orchestrator/session/store.mjs

@@ -34,6 +34,7 @@ import {
     _removeSessionSummary,
     _pruneSummaryIndexIds,
     _flushPendingSummaryOps,
+    _hasUnsettledSummaryOps,
 } from './store-summary-index.mjs';
 // Facade re-export: summary-index API moved to store-summary-index.mjs; keep
 // prior importers of store.mjs unchanged.
@@ -68,6 +69,9 @@ export { saveSessionAsync, saveSessionAsyncDeferred } from './store/save-worker.
 
 /** Module-level map tracking in-flight saves per session ID to prevent concurrent write corruption. */
 const _savePending = new Map();
+// Disk mtime of the summary index at the last time it was read into (or
+// refreshed as) the in-memory cache base — cross-process staleness detector.
+let _summaryIndexMtimeSeen = 0;
 
 
 /**
@@ -836,7 +840,12 @@ function _overlayUnpersistedSummaryRows(rows, invalidStorageIds = new Set()) {
 function rebuildSessionSummaryIndex() {
     _ensureSummaryCacheDataDir();
     const { rows } = _scanStoredSessionSummaryRows();
-    return _setSummaryRowsCache(_writeSummaryIndex(rows));
+    const indexedRows = _writeSummaryIndex(rows);
+    // This process just authored the new cache base. Remember its mtime so the
+    // next local save cannot mistake the rebuild for a cross-process update
+    // and replace a newer in-memory row with the just-obsoleted sidecar.
+    try { _summaryIndexMtimeSeen = statSync(summaryIndexPath()).mtimeMs || 0; } catch { /* stat only */ }
+    return _setSummaryRowsCache(indexedRows);
 }
 
 export function listStoredSessionSummaries(options = {}) {
@@ -867,7 +876,30 @@ export function listStoredSessionSummaries(options = {}) {
             return [];
         }
     }
-    if (_summaryRowsCache !== null) return _cachedSummaryRows().slice();
+    if (_summaryRowsCache !== null) {
+        // A local session save has already updated the in-memory cache but its
+        // non-blocking sidecar merge may still be queued/in flight. Re-reading
+        // the older sidecar in that window would temporarily erase the new row.
+        if (_hasUnsettledSummaryOps()) return _cachedSummaryRows().slice();
+        // Cross-process freshness: another live process (terminal CLI owning a
+        // session this surface only views) advances messageCount/updatedAt by
+        // rewriting the summary index FILE — an in-memory cache that never
+        // looks back at disk serves frozen rows forever (user: the unread dot
+        // never fired for terminal-owned growth). One stat per call; when the
+        // index advanced, re-read the cheap index JSON as the new cache base
+        // (local optimistic overlays stay applied on top).
+        let diskMtime = 0;
+        try { diskMtime = statSync(summaryIndexPath()).mtimeMs || 0; } catch { /* no index yet */ }
+        if (diskMtime <= _summaryIndexMtimeSeen) return _cachedSummaryRows().slice();
+        try {
+            const raw = JSON.parse(readFileSync(summaryIndexPath(), 'utf-8'));
+            if (Number(raw?.version) === SESSION_SUMMARY_INDEX_VERSION) {
+                _summaryIndexMtimeSeen = diskMtime;
+                return _setSummaryRowsCache(_normalizeSummaryIndex(raw).rows).slice();
+            }
+        } catch { /* torn concurrent write — keep serving the cache; retry next call */ }
+        return _cachedSummaryRows().slice();
+    }
 
     let indexedRows = [];
     let p;
@@ -879,6 +911,9 @@ export function listStoredSessionSummaries(options = {}) {
             const raw = JSON.parse(readFileSync(p, 'utf-8'));
             hasIndex = Number(raw?.version) === SESSION_SUMMARY_INDEX_VERSION;
             if (hasIndex) indexedRows = _normalizeSummaryIndex(raw).rows;
+            if (hasIndex) {
+                try { _summaryIndexMtimeSeen = statSync(p).mtimeMs || 0; } catch { /* stat only */ }
+            }
         }
     } catch { /* unreadable/malformed sidecar falls through to rebuild */ }
 

package/src/runtime/channels/lib/config.mjs

@@ -156,6 +156,13 @@ const HEADLESS_BACKEND = {
   }
 };
 function createBackend(config) {
+  // Channels-module toggle is MESSAGING-ONLY: automation (scheduler/webhooks)
+  // keeps the worker alive, so a disabled module runs the headless backend
+  // instead of blocking the whole runtime.
+  if (config.enabled === false) {
+    process.stderr.write("mixdog: channels messaging disabled; channel runtime running in headless mode\n");
+    return HEADLESS_BACKEND;
+  }
   // Single-backend select: exactly one backend is constructed based on
   // config.backend (discord|telegram). The two are mutually exclusive.
   if (config.backend === "telegram") {

package/src/runtime/channels/lib/status-snapshot.mjs

@@ -3,7 +3,7 @@
  *
  * Writes <DATA_DIR>/channels/status-snapshot.json every 10 seconds so that
  * setup-server can read cross-process state (cron next-fire, deferred count,
- * Discord unread, ngrok tunnel URL) without IPC.
+ * Discord unread, relay hook URL) without IPC.
  *
  * Atomic write: tmp → rename so readers never see a partial file.
  *
@@ -13,10 +13,10 @@
  */
 
 import * as fs from 'fs';
-import * as http from 'http';
 import * as path from 'path';
 import { DATA_DIR } from './config.mjs';
 import { writeJsonAtomicSync } from '../../shared/atomic-file.mjs';
+import { readHookPublicBase } from './webhook/relay-tunnel.mjs';
 
 const SNAPSHOT_DIR  = path.join(DATA_DIR, 'channels');
 const SNAPSHOT_PATH = path.join(SNAPSHOT_DIR, 'status-snapshot.json');
@@ -79,30 +79,6 @@ export function recordFetchedMessages(channelId, channelLabel, messages, options
   });
 }
 
-// ── Ngrok tunnel URL probe ───────────────────────────────────────────────────
-async function probeNgrokUrl() {
-  return new Promise((resolve) => {
-    const timer = setTimeout(() => { try { req && req.destroy(); } catch {} resolve(null); }, 400);
-    let req;
-    try {
-      req = http.get('http://127.0.0.1:4040/api/tunnels', (res) => {
-        clearTimeout(timer);
-        let body = '';
-        res.on('data', d => { body += d; });
-        res.on('end', () => {
-          try {
-            const parsed = JSON.parse(body);
-            const tunnel = (parsed.tunnels || []).find(t => t.public_url);
-            resolve(tunnel ? tunnel.public_url : null);
-          } catch { resolve(null); }
-        });
-      });
-      req.on('error', () => { clearTimeout(timer); resolve(null); });
-      req.setTimeout(400, () => { clearTimeout(timer); try { req.destroy(); } catch {} resolve(null); });
-    } catch { clearTimeout(timer); resolve(null); }
-  });
-}
-
 // ── Snapshot computation ─────────────────────────────────────────────────────
 // The legacy HH:MM / everyNm / hourly next-fire fallback was removed: the
 // scheduler accepts cron expressions exclusively (scheduler.mjs:68), so the
@@ -172,8 +148,8 @@ async function computeSnapshot(scheduler) {
     totalUnread += entry.unseenCount;
   }
 
-  // ── Ngrok tunnel URL ───────────────────────────────────────────────────────
-  const tunnelUrl = await probeNgrokUrl();
+  // ── Relay hook URL (identity file read; assigned on first tunnel start) ────
+  const hookPublicUrl = readHookPublicBase();
 
   return {
     writtenAt: now,
@@ -188,8 +164,8 @@ async function computeSnapshot(scheduler) {
       unread: unreadList,
       totalUnread,
     },
-    ngrok: {
-      tunnelUrl,
+    hook: {
+      publicUrl: hookPublicUrl,
     },
   };
 }

package/src/runtime/channels/lib/webhook/relay-tunnel.mjs

@@ -0,0 +1,203 @@
+// Relay-backed public webhook tunnel — the ngrok child process replacement.
+//
+// The channel worker keeps ONE outbound WebSocket to the Mixdog relay
+// (apps/relay/server.mjs `/hookleg`). Inbound requests on
+//   https://<relay>/hook/<deviceId>/webhook/<name>
+// arrive over that leg as JSON frames and are replayed against the LOCAL
+// webhook HTTP server; the response returns verbatim. Endpoint HMAC
+// verification stays local — the relay never inspects payloads. Works out
+// of the box: no binary, no authtoken, no reserved domain.
+import * as http from "http";
+import { randomBytes, randomUUID } from "crypto";
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import WebSocket from "ws";
+import { DATA_DIR } from "../config.mjs";
+import { logWebhook } from "./log.mjs";
+
+/** Packaged default mirrors the desktop pairing relay. */
+const DEFAULT_RELAY_URL = "wss://192-255-139-161.sslip.io";
+const MAX_TUNNEL_BODY_BYTES = 1024 * 1024;
+const HEARTBEAT_MS = 25_000;
+const LOCAL_TIMEOUT_MS = 25_000;
+
+export function resolveHookRelayUrl(env = process.env) {
+  const raw = String(env.MIXDOG_RELAY_URL || "").trim();
+  const flag = raw.toLowerCase();
+  if (flag === "0" || flag === "false" || flag === "off") return null;
+  return raw || DEFAULT_RELAY_URL;
+}
+
+export function hookIdentityPath() {
+  return join(DATA_DIR, "relay-hook-device.json");
+}
+
+// Stable per-install identity (trust-on-first-use at the relay, mirroring
+// the desktop leg). The secret never leaves this machine except toward the
+// relay; the deviceId doubles as the public URL path segment.
+export function loadOrCreateHookIdentity() {
+  const path = hookIdentityPath();
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof parsed.deviceId === "string" && /^[0-9a-f-]{8,64}$/.test(parsed.deviceId)
+      && typeof parsed.deviceSecret === "string" && parsed.deviceSecret.length >= 16) {
+      return { deviceId: parsed.deviceId, deviceSecret: parsed.deviceSecret };
+    }
+  } catch { /* first run */ }
+  const identity = { deviceId: randomUUID(), deviceSecret: randomBytes(24).toString("hex") };
+  try {
+    mkdirSync(DATA_DIR, { recursive: true });
+    writeFileSync(path, JSON.stringify(identity, null, 2), "utf8");
+  } catch (err) {
+    logWebhook(`hook tunnel: identity persist failed — ${err?.message || err}`);
+  }
+  return identity;
+}
+
+export function hookPublicBase(relayUrl, deviceId) {
+  const url = new URL(relayUrl);
+  url.protocol = url.protocol === "wss:" ? "https:" : "http:";
+  url.pathname = `/hook/${deviceId}`;
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}
+
+/** Public base URL for status surfaces; null until the first tunnel start
+ *  persisted an identity (no identity is ever created here). */
+export function readHookPublicBase(env = process.env) {
+  const relayUrl = resolveHookRelayUrl(env);
+  if (!relayUrl) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(hookIdentityPath(), "utf8"));
+    if (typeof parsed.deviceId === "string" && parsed.deviceId) {
+      return hookPublicBase(relayUrl, parsed.deviceId);
+    }
+  } catch { /* tunnel has not started yet */ }
+  return null;
+}
+
+export function startHookTunnel({ relayUrl, getLocalPort }) {
+  const { deviceId, deviceSecret } = loadOrCreateHookIdentity();
+  let socket = null;
+  let closed = false;
+  let retryMs = 1_000;
+  let reconnectTimer = null;
+  let announced = false;
+
+  const scheduleReconnect = () => {
+    if (closed) return;
+    reconnectTimer = setTimeout(connect, retryMs);
+    reconnectTimer.unref?.();
+    retryMs = Math.min(30_000, retryMs * 2);
+  };
+
+  const respond = (ws, id, status, headers, bodyBuffer) => {
+    if (ws.readyState !== WebSocket.OPEN) return;
+    try {
+      ws.send(JSON.stringify({
+        type: "http-response",
+        id,
+        status,
+        headers: headers || {},
+        body: bodyBuffer && bodyBuffer.length ? bodyBuffer.toString("base64") : "",
+      }));
+    } catch { /* relay vanished; it times the request out */ }
+  };
+
+  const forwardToLocal = (frame, ws) => {
+    const port = getLocalPort();
+    if (!port) {
+      respond(ws, frame.id, 503, { "content-type": "application/json" },
+        Buffer.from('{"error":"webhook server not listening"}'));
+      return;
+    }
+    const body = frame.body ? Buffer.from(String(frame.body), "base64") : null;
+    const request = http.request({
+      host: "127.0.0.1",
+      port,
+      method: typeof frame.method === "string" ? frame.method : "GET",
+      path: typeof frame.path === "string" && frame.path.startsWith("/") ? frame.path : "/",
+      headers: frame.headers && typeof frame.headers === "object" ? frame.headers : {},
+      timeout: LOCAL_TIMEOUT_MS,
+    }, (response) => {
+      const chunks = [];
+      let total = 0;
+      response.on("data", (chunk) => {
+        total += chunk.length;
+        if (total <= MAX_TUNNEL_BODY_BYTES) chunks.push(chunk);
+      });
+      response.on("end", () => respond(ws, frame.id, response.statusCode || 502,
+        { "content-type": response.headers["content-type"] || "application/json" },
+        Buffer.concat(chunks)));
+      response.on("error", () => respond(ws, frame.id, 502, {}, null));
+    });
+    request.on("timeout", () => request.destroy(new Error("local webhook timeout")));
+    request.on("error", (err) => respond(ws, frame.id, 502, { "content-type": "application/json" },
+      Buffer.from(JSON.stringify({ error: String(err?.message || err) }))));
+    if (body && body.length) request.write(body);
+    request.end();
+  };
+
+  const connect = () => {
+    if (closed) return;
+    const target = new URL(relayUrl);
+    target.pathname = "/hookleg";
+    target.search = `device=${encodeURIComponent(deviceId)}&secret=${encodeURIComponent(deviceSecret)}`;
+    let ws;
+    try {
+      ws = new WebSocket(target.toString(), { maxPayload: 8 * 1024 * 1024 });
+    } catch (err) {
+      logWebhook(`hook tunnel: dial failed — ${err?.message || err}`);
+      scheduleReconnect();
+      return;
+    }
+    socket = ws;
+    // NAT paths silently drop idle sockets; protocol pings keep the leg warm
+    // and detect a half-dead link so the reconnect loop restores it.
+    let alive = true;
+    ws.on("pong", () => { alive = true; });
+    const heartbeat = setInterval(() => {
+      if (ws.readyState !== WebSocket.OPEN) return;
+      if (!alive) { try { ws.terminate(); } catch { /* close reconnects */ } return; }
+      alive = false;
+      try { ws.ping(); } catch { /* close reconnects */ }
+    }, HEARTBEAT_MS);
+    heartbeat.unref?.();
+    ws.on("open", () => {
+      retryMs = 1_000;
+      if (!announced) {
+        announced = true;
+        logWebhook(`hook tunnel up: ${hookPublicBase(relayUrl, deviceId)}`);
+      }
+    });
+    ws.on("message", (raw) => {
+      alive = true;
+      let frame;
+      try { frame = JSON.parse(String(raw)); } catch { return; }
+      if (frame?.type !== "http" || typeof frame.id !== "string") return;
+      forwardToLocal(frame, ws);
+    });
+    ws.on("error", () => { /* surfaced as close */ });
+    ws.on("close", () => {
+      clearInterval(heartbeat);
+      if (socket === ws) socket = null;
+      scheduleReconnect();
+    });
+  };
+
+  connect();
+  return {
+    deviceId,
+    publicBase: hookPublicBase(relayUrl, deviceId),
+    close() {
+      if (closed) return;
+      closed = true;
+      if (reconnectTimer) clearTimeout(reconnectTimer);
+      if (socket) {
+        try { socket.terminate(); } catch { /* already gone */ }
+        socket = null;
+      }
+    },
+  };
+}