mixdog 0.9.66 → 0.9.68

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.9.66",
+  "version": "0.9.68",
   "private": false,
   "type": "module",
   "description": "Standalone mixdog coding-agent CLI/TUI workspace.",

package/src/runtime/agent/orchestrator/session/manager/session-lifecycle.mjs

@@ -395,6 +395,9 @@ export function createSession(opts) {
         // scheduler/daily-standup, webhook/github-push, lead/worker.
         sourceType: opts.sourceType || null,
         sourceName: opts.sourceName || null,
+        // Automation delivery mode ('app' | 'channel' | 'both'): the desktop
+        // sidebar hides channel-only runner sessions from Automations.
+        sourceDelivery: opts.sourceDelivery || null,
         // Provider-scoped unified cache key — one shard per provider,
         // shared across all roles / sources (agent/maintenance/mcp/
         // scheduler/webhook). Role or source-specific context must be

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

@@ -137,6 +137,7 @@ export function _sessionSummary(session) {
         agent: session.agent || null,
         sourceType: session.sourceType || null,
         sourceName: session.sourceName || null,
+        sourceDelivery: session.sourceDelivery || null,
         scopeKey: session.scopeKey || null,
         ownerSessionId: session.ownerSessionId || null,
         clientHostPid: _positiveNumber(session.clientHostPid, 0) || null,
@@ -152,6 +153,9 @@ export function _sessionSummary(session) {
         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,
     };
 }
 
@@ -184,6 +188,7 @@ function _normalizeSummaryRow(row) {
         preview: _cleanPreview(row.preview || ''),
         generation: typeof row.generation === 'number' ? row.generation : 0,
         implicitBashSessionId: row.implicitBashSessionId || null,
+        detachedReason: row.detachedReason || null,
     };
 }
 

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

@@ -31,6 +31,7 @@ function isLeadVisibleRow(row) {
         || sourceType === 'lead'
         || sourceType === 'cli'
         || sourceType === 'schedule'
+        || sourceType === 'webhook'
         || (!sourceType && !sourceName && owner !== 'agent');
 }
 
@@ -49,6 +50,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);
@@ -78,6 +84,10 @@ function normalizedRow(row, heartbeatAt = 0) {
     return {
         id: row.id,
         updatedAt: positiveNumber(row.updatedAt, 0),
+        // Conversation-activity timestamp (mirror of listLeadSessions):
+        // detach/resume bookkeeping bumps updatedAt in bulk on restarts, so
+        // Recent must order by lastUsedAt or every restart reshuffles rows.
+        lastUsedAt: positiveNumber(row.lastUsedAt, 0),
         createdAt: positiveNumber(row.createdAt, 0),
         lastHeartbeatAt: positiveNumber(row.lastHeartbeatAt, 0),
         // Liveness comes from the .hb sidecar mtime alone: stored row fields
@@ -90,6 +100,7 @@ function normalizedRow(row, heartbeatAt = 0) {
         agent: row.agent || null,
         sourceType: row.sourceType || null,
         sourceName: row.sourceName || null,
+        sourceDelivery: row.sourceDelivery || null,
         scopeKey: row.scopeKey || null,
         ownerSessionId: row.ownerSessionId || null,
         clientHostPid: positiveNumber(row.clientHostPid, 0) || null,
@@ -105,6 +116,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,
     };
 }
 
@@ -112,6 +124,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({
@@ -153,7 +169,8 @@ function scanSessionFiles(heartbeatMtimes = sessionHeartbeatMtimes()) {
             // cold catalog; the authoritative runtime can reconcile it later.
         }
     }
-    return rows.sort((left, right) => (right.updatedAt || 0) - (left.updatedAt || 0));
+    return rows.sort((left, right) =>
+        (right.lastUsedAt || right.updatedAt || 0) - (left.lastUsedAt || left.updatedAt || 0));
 }
 
 export function listStoredSessionSummaries(options = {}) {
@@ -166,7 +183,8 @@ export function listStoredSessionSummaries(options = {}) {
             const rows = (Array.isArray(index.rows) ? index.rows : [])
                 .map((row) => normalizedRow(row, heartbeatMtimes.get(row?.id) || 0))
                 .filter((row) => row && isLeadVisibleRow(row))
-                .sort((left, right) => (right.updatedAt || 0) - (left.updatedAt || 0));
+                .sort((left, right) =>
+                    (right.lastUsedAt || right.updatedAt || 0) - (left.lastUsedAt || left.updatedAt || 0));
             if (rows.length > 0 || options.rebuildIfMissing === false) return rows;
         }
     } catch {

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

@@ -69,11 +69,12 @@ async function loadConfig({ freshSecrets = false } = {}) {
     // are no longer read. Done one-shots are dropped so they never re-arm.
     const scheduleEntries = (await listSchedules())
       .filter((s) => s.enabled !== false && s.status !== "done");
-    // `target` drives routing: 'channel' → non-interactive dispatch to the
-    // schedule's channel_id; 'session' → inject into the current (Lead)
-    // session. Mirrors the webhook model.
-    raw.nonInteractive = scheduleEntries.filter((s) => s.target === "channel");
-    raw.interactive = scheduleEntries.filter((s) => s.target === "session");
+    // Every schedule fires as a visible session run (runScheduleSession)
+    // through the non-interactive dispatch path; `target` only decides
+    // whether the RESULT is relayed to the schedule's channel. The legacy
+    // interactive bucket (Lead-session inject) is retired.
+    raw.nonInteractive = scheduleEntries;
+    raw.interactive = [];
     const accessChannels = { ...raw.access?.channels ?? {} };
     // voice config lives at the top level of mixdog-config.json (peer of
     // channels), so readSection("channels") never sees it. Pull it explicitly.
@@ -156,6 +157,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/owned-runtime.mjs

@@ -48,6 +48,11 @@ export function createOwnedRuntime({
   let _ownedRuntimeStopRequested = false;
   let bridgeOwnershipRefreshInFlight = null;
   let _memoryDrainTimer = null;
+  // Automation (scheduler + webhook server + relay tunnel) can outlive a
+  // failed/absent messaging backend: it is tracked separately so teardown and
+  // reload know it is running even while bridgeRuntimeConnected stays false.
+  let automationRunning = false;
+  let automationStartPromise = null;
   // Promise that resolves when the current startOwnedRuntime() run fully
   // settles (bridgeRuntimeStarting -> false). reloadRuntimeConfig awaits this
   // before issuing a restart so a backend swap that lands mid-start is not
@@ -133,6 +138,34 @@ function syncOwnedWebhookAndEventRuntime({ reload = false } = {}) {
     setWebhookServer(null);
   }
 }
+async function startAutomationRuntime() {
+  if (automationRunning) {
+    syncOwnedWebhookAndEventRuntime();
+    return;
+  }
+  if (automationStartPromise) return automationStartPromise;
+  if (!bridgeRuntimeStarting) _ownedRuntimeStopRequested = false;
+  const run = (async () => {
+    try {
+      const agentCfg = loadAgentConfig();
+      await initProviders(agentCfg.providers || {});
+    } catch (e) {
+      process.stderr.write(`mixdog: initProviders failed (non-fatal): ${e instanceof Error ? e.message : String(e)}\n`);
+    }
+    if (_ownedRuntimeStopRequested) return;
+    scheduler.start();
+    startSnapshotWriter(scheduler);
+    syncOwnedWebhookAndEventRuntime();
+    automationRunning = true;
+    process.stderr.write('mixdog: automation runtime up without messaging backend\n');
+  })();
+  automationStartPromise = run;
+  try {
+    return await run;
+  } finally {
+    if (automationStartPromise === run) automationStartPromise = null;
+  }
+}
 let _ownedRuntimeSelfHealing = false;
 // Explicit restore path for an already-connected owner. The 3s ownership tick
 // must not run this implicitly: re-binding status on every tick can move the
@@ -272,9 +305,14 @@ async function startOwnedRuntime(options = {}) {
       if (bindPersistedTranscriptTask) await bindPersistedTranscriptTask;
       return;
     }
-    scheduler.start();
-    startSnapshotWriter(scheduler);
+    // Reconnect after a degraded (automation-only) start must not double-arm
+    // the scheduler/snapshot timers; the webhook/event sync is idempotent.
+    if (!automationRunning) {
+      scheduler.start();
+      startSnapshotWriter(scheduler);
+    }
     syncOwnedWebhookAndEventRuntime();
+    automationRunning = true;
     if (restoreBinding) {
       if (bindPersistedTranscriptTask) await bindPersistedTranscriptTask;
       const pendingTranscriptPath = forwarder.transcriptPath;
@@ -303,6 +341,23 @@ async function startOwnedRuntime(options = {}) {
     try { releaseOwnedChannelLocks(instanceId); } catch {}
     try { clearActiveInstance(instanceId); } catch {}
     if (_memoryDrainTimer) { clearInterval(_memoryDrainTimer); _memoryDrainTimer = null; }
+    // DEGRADED MODE (automation decoupling): a messaging connect failure —
+    // packaged runtime without discord.js, bad token, gateway outage — must
+    // not take schedules/webhooks down with it. Start the automation runtime
+    // anyway; sends stay dead (bridgeRuntimeConnected=false) but session
+    // runs, the webhook server, and the relay tunnel work.
+    if (!_ownedRuntimeStopRequested) {
+      if (automationRunning) {
+        // Already degraded-started by an earlier attempt; this run was only a
+        // messaging reconnect retry — the finally below settles the start.
+        return;
+      }
+      try {
+        await startAutomationRuntime();
+      } catch (e3) {
+        process.stderr.write(`mixdog: degraded automation start failed: ${e3 instanceof Error ? e3.message : String(e3)}\n`);
+      }
+    }
   } finally {
     settleInFlightStart();
   }
@@ -318,12 +373,15 @@ async function stopOwnedRuntime(reason) {
   // during that window (bridgeRuntimeStarting=true, getBridgeRuntimeConnected()
   // still false) we still need to tear that partial state down — otherwise
   // the port stays bound and active-instance.json stays stale.
-  if (!getBridgeRuntimeConnected() && !bridgeRuntimeStarting) return;
+  if (!getBridgeRuntimeConnected() && !bridgeRuntimeStarting && !automationRunning && !automationStartPromise) return;
   // If a start is in flight (bridgeRuntimeStarting=true), signal the in-flight
   // startOwnedRuntime() to abort right after its getBackend().connect() resolves.
   // Without this the in-flight start re-marks connected and re-launches
   // scheduler/webhook/heartbeat after we tear them down here.
-  if (bridgeRuntimeStarting) _ownedRuntimeStopRequested = true;
+  if (bridgeRuntimeStarting || automationStartPromise) _ownedRuntimeStopRequested = true;
+  if (automationStartPromise) {
+    try { await automationStartPromise; } catch {}
+  }
   const wasConnected = getBridgeRuntimeConnected();
   stopServerTyping();
   // Release the transcript fs.watch handle plus the forwarder's debounce/retry
@@ -335,6 +393,7 @@ async function stopOwnedRuntime(reason) {
   scheduler.stop();
   stopSnapshotWriter();
   await stopWebhookAndEventRuntime();
+  automationRunning = false;
   releaseOwnedChannelLocks(instanceId);
   clearActiveInstance(instanceId);
   try {
@@ -462,13 +521,14 @@ async function reloadRuntimeConfig() {
   } else if (nextBackend !== previousBackend) {
     try { await nextBackend.disconnect?.(); } catch {}
   }
-  if (getBridgeRuntimeConnected()) {
+  if (getBridgeRuntimeConnected() || automationRunning) {
     syncOwnedWebhookAndEventRuntime({ reload: true });
   } else {
     await stopWebhookAndEventRuntime();
   }
 }
   return {
+    startAutomationRuntime,
     startOwnedRuntime,
     stopOwnedRuntime,
     refreshBridgeOwnership,

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

@@ -558,10 +558,10 @@ ${Scheduler.INSTANCE_UUID}`;
 `);
       return false;
     }
-    // target 'channel' (non-interactive) → dispatch to the schedule's
-    // channel_id, falling back to the resolved main channel. target 'session'
-    // (interactive) → inject into the Lead session with no channel id.
-    const channelId = type === "non-interactive"
+    // target 'channel' → relay the run result to the schedule's channel_id
+    // (falling back to the resolved main channel). target 'session' → no
+    // channel relay; the visible session run IS the surface.
+    const channelId = schedule.target === "channel"
       ? this.resolveChannel(schedule.channelId)
       : "";
     return await this.fireTimedPrompt(schedule, type, prompt, channelId, opts);
@@ -570,16 +570,8 @@ ${Scheduler.INSTANCE_UUID}`;
   async fireTimedPrompt(schedule, type, prompt, channelId, { awaitDispatch = false } = {}) {
     logSchedule(`firing ${schedule.name} (${type})
 `);
-    if (type === "interactive") {
-      if (this.injectFn) {
-        this.injectFn(channelId, schedule.name, " ", {
-          instruction: prompt,
-          type: "schedule"
-        });
-        return true;
-      }
-      return false;
-    }
+    // Legacy interactive Lead-session inject is retired: every schedule fire
+    // runs as its own visible session below (New-task parity, user decision).
     if (this.running.has(schedule.name)) return false;
     this.running.add(schedule.name);
     const presetId = schedule.model;
@@ -598,7 +590,7 @@ ${Scheduler.INSTANCE_UUID}`;
     const dispatch = runScheduleSession(schedule, { prompt })
       .then(({ result }) => {
         this.running.delete(schedule.name);
-        if (result && this.sendFn) {
+        if (result && channelId && this.sendFn) {
           this.sendFn(channelId, result).catch(
             (err) => process.stderr.write(`mixdog scheduler: ${schedule.name} relay failed: ${err}\n`)
           );

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/tool-dispatch.mjs

@@ -27,6 +27,7 @@ function createToolDispatch({
     refreshBridgeOwnership,
     bindPersistedTranscriptIfAny,
     rebindCurrentTranscript,
+    startChannelBridge,
     stopOwnedRuntime,
     reloadRuntimeConfig,
   } = lifecycle;
@@ -60,7 +61,11 @@ function createToolDispatch({
                 notifyRemoteAcquired?.();
               }
               try {
-                await refreshBridgeOwnership({ restoreBinding: true });
+                if (typeof startChannelBridge === 'function') {
+                  await startChannelBridge();
+                } else {
+                  await refreshBridgeOwnership({ restoreBinding: true });
+                }
                 // An already-connected owner returns early from
                 // startOwnedRuntime(), so rebind explicitly to follow the
                 // current (parent-chain) session transcript.

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;
+      }
+    },
+  };
+}