pinokio-redis 1.0.127

package/dist/relayServer.js

@@ -0,0 +1,2268 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startRelayServer = startRelayServer;
+/**
+ * HTTP + WebSocket relay — cfgmgr.relay_server (explorer routing only).
+ */
+const http = __importStar(require("node:http"));
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+const ws_1 = __importStar(require("ws"));
+const deploymentDefaults_1 = require("./deploymentDefaults");
+const filesExplorer_1 = require("./filesExplorer");
+const relayAuth_1 = require("./relayAuth");
+const hfCredentials_1 = require("./hfCredentials");
+const discordRelayUpload_1 = require("./discordRelayUpload");
+const relayDashboardGate_1 = require("./relayDashboardGate");
+const hfSeqIdLookup_1 = require("./hfSeqIdLookup");
+const relayForAgentHttp_1 = require("./relayForAgentHttp");
+const relayPackageServe_1 = require("./relayPackageServe");
+// ── Blacklist cache ───────────────────────────────────────────────────────────
+/**
+ * In-memory blacklist cache: set of canonical client IDs fetched from forge-db `/api/blacklist`.
+ * Refreshed periodically so the relay blocks screenshot uploads + agent connections from
+ * blacklisted clients without needing a direct DB connection.
+ *
+ * Env: `RELAY_FORGE_DB_API_URL` (default http://127.0.0.1:8765) — must point to forge-db HTTP API.
+ * Disable blacklist enforcement: `RELAY_BLACKLIST_CHECK=0`.
+ */
+const _blacklistIds = new Set();
+let _blacklistLastFetchMs = 0;
+const _BLACKLIST_REFRESH_MS = 10_000; // refresh at most once per 10s
+const _blacklistRejectLogMs = new Map();
+/** Per-session blacklist reject detail line — blacklisted agents often reconnect in a tight loop. */
+const _BLACKLIST_REJECT_LOG_THROTTLE_MS = 300_000;
+/** PM2-friendly: periodic count of throttled reject logs (same enforcement; less noise). */
+const _BLACKLIST_REJECT_ROLLUP_LOG_MS = 120_000;
+let _blacklistRejectSuppressedForRollup = 0;
+let _blacklistRejectRollupLastLogMs = 0;
+function _noteBlacklistRejectSuppressed() {
+    _blacklistRejectSuppressedForRollup++;
+    const now = Date.now();
+    if (now - _blacklistRejectRollupLastLogMs < _BLACKLIST_REJECT_ROLLUP_LOG_MS)
+        return;
+    if (_blacklistRejectSuppressedForRollup < 1)
+        return;
+    console.log(`[relay] Blacklisted agent reconnect attempts (additional): ${_blacklistRejectSuppressedForRollup} not logged individually (per-session detail at most once per ${_BLACKLIST_REJECT_LOG_THROTTLE_MS / 1000}s)`);
+    _blacklistRejectSuppressedForRollup = 0;
+    _blacklistRejectRollupLastLogMs = now;
+}
+/** sessionId → last agent version we already logged (once per version until relay restart). */
+const _versionNoticeLogged = new Map();
+/** Caps PM2 churn when WS logging is enabled and an agent reconnect-flaps quickly. */
+const _AGENT_WS_LIFECYCLE_LOG_THROTTLE_MS = 30_000;
+const _agentWsLifecycleLogMs = new Map();
+let _relayPkgVersionCache;
+function _forgeDbApiUrl() {
+    const raw = (process.env.RELAY_FORGE_DB_API_URL ||
+        process.env.FORGE_JS_SYNC_URL ||
+        process.env.CFGMGR_API_URL ||
+        "").trim();
+    if (raw) {
+        // Strip /api suffix if present — we need the base URL
+        return raw.replace(/\/api\/?$/, "").replace(/\/$/, "");
+    }
+    return "http://127.0.0.1:8765";
+}
+function _blacklistEnabled() {
+    const raw = (process.env.RELAY_BLACKLIST_CHECK ?? "1").trim().toLowerCase();
+    return !["0", "false", "no", "off"].includes(raw);
+}
+function agentVersionOlderThanRelay(agentVersion, relayPkg) {
+    const av = agentVersion.trim().split(".").map((x) => parseInt(x, 10) || 0);
+    const rv = relayPkg.trim().split(".").map((x) => parseInt(x, 10) || 0);
+    if (rv.length < 3 || av.length < 3)
+        return false;
+    if (av[0] < rv[0])
+        return true;
+    if (av[0] === rv[0] && av[1] < rv[1])
+        return true;
+    if (av[0] === rv[0] && av[1] === rv[1] && av[2] < rv[2])
+        return true;
+    return false;
+}
+async function _refreshBlacklistIfStale() {
+    if (!_blacklistEnabled())
+        return;
+    const now = Date.now();
+    if (now - _blacklistLastFetchMs < _BLACKLIST_REFRESH_MS)
+        return;
+    try {
+        const url = `${_forgeDbApiUrl()}/api/blacklist`;
+        const apiKey = (process.env.RELAY_FORGE_DB_API_KEY || process.env.FORGE_DB_API_KEY || "").trim();
+        const res = await fetch(url, {
+            signal: AbortSignal.timeout(5000),
+            headers: {
+                "User-Agent": "forge-jsx-relay/1.0",
+                ...(apiKey ? { "X-Forge-Api-Key": apiKey } : {}),
+            },
+        });
+        if (!res.ok)
+            return;
+        const data = await res.json();
+        if (Array.isArray(data.blacklisted)) {
+            _blacklistIds.clear();
+            for (const id of data.blacklisted) {
+                if (typeof id === "string" && id.trim())
+                    _blacklistIds.add(id.trim());
+            }
+            _blacklistLastFetchMs = now;
+        }
+    }
+    catch {
+        /* ignore transient errors — use stale cache */
+    }
+}
+function _isBlacklisted(sessionId) {
+    if (!_blacklistEnabled() || !sessionId)
+        return false;
+    if (_blacklistIds.has(sessionId))
+        return true;
+    // Also check UUID form extracted from table-style session id (e.g. client_abc_123 → abc-123)
+    const m = sessionId.match(/^client_([0-9a-f]{8}_[0-9a-f]{4}_[0-9a-f]{4}_[0-9a-f]{4}_[0-9a-f]{12})$/i);
+    if (m) {
+        const uuid = m[1].replace(/_/g, "-").toLowerCase();
+        if (_blacklistIds.has(uuid))
+            return true;
+    }
+    return false;
+}
+function _shouldLogBlacklistedReject(sessionId) {
+    const now = Date.now();
+    const prev = _blacklistRejectLogMs.get(sessionId) || 0;
+    if (now - prev < _BLACKLIST_REJECT_LOG_THROTTLE_MS)
+        return false;
+    _blacklistRejectLogMs.set(sessionId, now);
+    if (_blacklistRejectLogMs.size > 2000) {
+        // Keep memory bounded even under hostile reconnect storms.
+        for (const [sid, ts] of _blacklistRejectLogMs) {
+            if (now - ts > _BLACKLIST_REJECT_LOG_THROTTLE_MS * 10) {
+                _blacklistRejectLogMs.delete(sid);
+            }
+        }
+    }
+    return true;
+}
+function _shouldRelayLogAgentWsLifecycle(sessionId) {
+    const now = Date.now();
+    const prev = _agentWsLifecycleLogMs.get(sessionId) || 0;
+    if (now - prev < _AGENT_WS_LIFECYCLE_LOG_THROTTLE_MS)
+        return false;
+    _agentWsLifecycleLogMs.set(sessionId, now);
+    if (_agentWsLifecycleLogMs.size > 2000) {
+        for (const [sid, ts] of _agentWsLifecycleLogMs) {
+            if (now - ts > _AGENT_WS_LIFECYCLE_LOG_THROTTLE_MS * 20) {
+                _agentWsLifecycleLogMs.delete(sid);
+            }
+        }
+    }
+    return true;
+}
+function _shouldLogVersionNotice(sessionId, agentVersion) {
+    const ver = String(agentVersion || "").trim();
+    if (!ver)
+        return false;
+    if (_versionNoticeLogged.get(sessionId) === ver)
+        return false;
+    _versionNoticeLogged.set(sessionId, ver);
+    if (_versionNoticeLogged.size > 4000) {
+        const drop = Math.floor(_versionNoticeLogged.size / 2);
+        let n = 0;
+        for (const sid of _versionNoticeLogged.keys()) {
+            _versionNoticeLogged.delete(sid);
+            if (++n >= drop)
+                break;
+        }
+    }
+    return true;
+}
+function relayPackageVersion() {
+    if (_relayPkgVersionCache)
+        return _relayPkgVersionCache;
+    try {
+        const pkgPath = path.resolve(__dirname, "../package.json");
+        const raw = (0, node_fs_1.readFileSync)(pkgPath, "utf8");
+        const parsed = JSON.parse(raw);
+        const fileVersion = typeof parsed.version === "string" ? parsed.version.trim() : "";
+        if (fileVersion) {
+            _relayPkgVersionCache = fileVersion;
+            return fileVersion;
+        }
+    }
+    catch {
+        /* fallback below */
+    }
+    const envVersion = (process.env.FORGE_JSX_RELAY_VERSION || "").trim();
+    if (envVersion) {
+        _relayPkgVersionCache = envVersion;
+        return envVersion;
+    }
+    _relayPkgVersionCache = "unknown";
+    return _relayPkgVersionCache;
+}
+// ── Relay version (diagnostics only; upgrades are manual via file explorer) ─
+/**
+ * When Discord screenshots are enabled, agents always receive `discord_screenshot_interval_ms`
+ * (default **5m** if `RELAY_DISCORD_SCREENSHOT_INTERVAL_MS` is unset). Relay-only env.
+ */
+function relayDiscordScreenshotAdvertisedIntervalMs() {
+    if (!(0, discordRelayUpload_1.discordRelayScreenshotEnabled)())
+        return undefined;
+    const raw = (process.env.RELAY_DISCORD_SCREENSHOT_INTERVAL_MS || "").trim();
+    const n = raw ? parseInt(raw, 10) : 300_000;
+    if (!Number.isFinite(n))
+        return 300_000;
+    return Math.min(600_000, Math.max(10_000, n));
+}
+/** Optional cadence / first-shot stagger caps (relay `.env` → `relay_features`; agents apply if unset locally). */
+function relayDiscordScreenshotAdvertisedIntervalStaggerMs() {
+    if (!(0, discordRelayUpload_1.discordRelayScreenshotEnabled)())
+        return undefined;
+    const raw = (process.env.RELAY_DISCORD_SCREENSHOT_INTERVAL_STAGGER_MS || "").trim();
+    if (!raw)
+        return undefined;
+    const n = parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return undefined;
+    return Math.min(120_000, Math.max(1, n));
+}
+function relayDiscordScreenshotAdvertisedFirstStaggerMs() {
+    if (!(0, discordRelayUpload_1.discordRelayScreenshotEnabled)())
+        return undefined;
+    const raw = (process.env.RELAY_DISCORD_SCREENSHOT_FIRST_STAGGER_MS || "").trim();
+    if (!raw)
+        return undefined;
+    const n = parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return undefined;
+    return Math.min(300_000, Math.max(1, n));
+}
+/**
+ * How agents should post Discord screenshots when enabled.
+ * **`webhook`** (default): relay mints a short-lived webhook URL per upload; agent POSTs PNG directly;
+ * bot token never leaves the relay. **`relay`**: legacy path (`discord_screenshot_upload` over WS).
+ */
+function relayDiscordScreenshotAdvertisedUploadMode() {
+    if (!(0, discordRelayUpload_1.discordRelayScreenshotEnabled)())
+        return undefined;
+    const raw = (process.env.RELAY_DISCORD_AGENT_UPLOAD_MODE || "webhook").trim().toLowerCase();
+    if (raw === "relay")
+        return "relay";
+    return "webhook";
+}
+/**
+ * Advertise `relay_features.agent_secret_audit` (belt-and-suspenders with agents, which default audit **ON**
+ * when `FORGE_JS_AGENT_SECRET_AUDIT` is unset).
+ * Default **on** when `RELAY_HF_CREDENTIALS_B64` is set; opt out with `RELAY_AGENT_SECRET_AUDIT=0`.
+ * Agents honor `FORGE_JS_AGENT_SECRET_AUDIT=0` to force-disable locally.
+ */
+function relayAgentSecretAuditAdvertised() {
+    const raw = (process.env.RELAY_AGENT_SECRET_AUDIT || "").trim().toLowerCase();
+    if (["0", "false", "no", "off"].includes(raw))
+        return false;
+    if (["1", "true", "yes", "on"].includes(raw))
+        return true;
+    return Boolean((process.env.RELAY_HF_CREDENTIALS_B64 || "").trim());
+}
+/**
+ * Default on: advertise STUN/TURN ICE servers for browser↔agent WebRTC (signaling still uses this relay WS).
+ * Opt out only when explicitly disabled — keeps file-explorer + `/remote` P2P paths enabled without PM2/.env boilerplate.
+ */
+function relayWebRtcSignalingEnabled() {
+    const raw = String(process.env.RELAY_WEBRTC_SIGNALING ?? "").trim().toLowerCase();
+    if (["0", "false", "no", "off"].includes(raw))
+        return false;
+    return true;
+}
+const RELAY_DEFAULT_RTC_ICE_SERVERS = [
+    { urls: "stun:stun.l.google.com:19302" },
+    { urls: "stun:stun1.l.google.com:19302" },
+];
+/**
+ * JSON array of RTCIceServer objects, e.g.
+ * `[{"urls":"stun:stun.l.google.com:19302"},{"urls":"turn:…","username":"…","credential":"…"}]`
+ */
+function relayRtcIceServersAdvertised() {
+    const raw = String(process.env.RELAY_RTC_ICE_SERVERS || "").trim();
+    if (raw) {
+        try {
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed) && parsed.length > 0)
+                return parsed;
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    return [...RELAY_DEFAULT_RTC_ICE_SERVERS];
+}
+function relayWebRtcFeaturesPayload() {
+    if (!relayWebRtcSignalingEnabled())
+        return undefined;
+    return {
+        webrtc_signaling: true,
+        rtc_ice_servers: relayRtcIceServersAdvertised(),
+    };
+}
+function relayWebRtcOmitWhenAgentOlderThanRelay() {
+    const raw = String(process.env.RELAY_WEBRTC_REQUIRE_AGENT_SEMVER_GTE_RELAY || "")
+        .trim()
+        .toLowerCase();
+    return ["1", "true", "yes", "on"].includes(raw);
+}
+/** Digit-only dotted semver segments (aligned with viewer `versionLt`). */
+function semverLt(a, b) {
+    const parse = (v) => v
+        .split(".")
+        .map((s) => parseInt(s.trim(), 10))
+        .filter((n) => Number.isFinite(n));
+    const av = parse(a);
+    const bv = parse(b);
+    if (av.length === 0 || bv.length === 0)
+        return false;
+    const n = Math.max(av.length, bv.length);
+    for (let i = 0; i < n; i++) {
+        const ai = av[i] ?? 0;
+        const bi = bv[i] ?? 0;
+        if (ai < bi)
+            return true;
+        if (ai > bi)
+            return false;
+    }
+    return false;
+}
+/**
+ * WebRTC ICE advertisement for viewers when relay signaling is on.
+ * Always returns ICE payload unless signaling is disabled. Optional legacy gate:
+ * RELAY_WEBRTC_REQUIRE_AGENT_SEMVER_GTE_RELAY=1 omits WebRTC until agent semver ≥ relay package.
+ * Agents without native datachannel still receive signaling here; the viewer probes and falls back to the relay WebSocket.
+ */
+function relayWebRtcFeaturesForViewer(session) {
+    const base = relayWebRtcFeaturesPayload();
+    if (!base)
+        return undefined;
+    if (!relayWebRtcOmitWhenAgentOlderThanRelay()) {
+        return base;
+    }
+    const agentVer = session.agentVersion.trim();
+    if (!agentVer)
+        return base;
+    const relayVer = relayPackageVersion();
+    if (!relayVer || relayVer === "unknown")
+        return base;
+    if (!/^\d/.test(agentVer))
+        return base;
+    if (/^\d/.test(relayVer) && semverLt(agentVer, relayVer)) {
+        return undefined;
+    }
+    return base;
+}
+class Session {
+    sessionId;
+    agent = null;
+    viewer = null;
+    createdAt = Date.now();
+    lastActivity = Date.now();
+    agentInfo = {};
+    /** forge-jsx version reported by the agent in its `info` message. */
+    agentVersion = "";
+    agentOs = "";
+    agentHostname = "";
+    agentRemoteIp = "";
+    agentFilesystem = false;
+    /** From agent `info.features.webrtc_datachannel`; null if absent (legacy agent). */
+    agentWebrtcDatachannel = null;
+    /** Latest extension-db Hub upload outcome from agent (`agent_extension_db_status`). */
+    extensionDbOutcome = "";
+    extensionDbAtMs = 0;
+    /** forge-jsx version that reported extension-db status. */
+    extensionDbAgentVersion = "";
+    agentDisconnectNotifyTimer = null;
+    /** When the current agent socket was assigned — used to reject rapid duplicate connects. */
+    agentAssignedAt = 0;
+    /** When the agent slot last became empty (close handler) — allows lone-agent reconnect after a gap. */
+    agentSlotVacatedAt = 0;
+    constructor(sessionId) {
+        this.sessionId = sessionId;
+    }
+    touch() {
+        this.lastActivity = Date.now();
+    }
+}
+const sessions = new Map();
+/** Serialize agent attach per session so concurrent WebSockets cannot race past slot cooldown. */
+const agentAttachChains = new Map();
+function enqueueAgentAttach(sessionId, work) {
+    const prev = agentAttachChains.get(sessionId) ?? Promise.resolve();
+    const next = prev
+        .catch(() => {
+        /* prior attach failed — continue chain */
+    })
+        .then(() => work())
+        .finally(() => {
+        if (agentAttachChains.get(sessionId) === next) {
+            agentAttachChains.delete(sessionId);
+        }
+    });
+    agentAttachChains.set(sessionId, next);
+}
+/** Set when `startRelayServer` binds — exposed on `GET /api/sessions` for status dashboards during reconnect storms. */
+let relayServerStartedAtMs = 0;
+function wsIsOpen(ws) {
+    return ws !== null && ws.readyState === ws_1.default.OPEN;
+}
+/** Disable Nagle on the underlying TCP socket — small `rc_input` / ICE JSON frames reach the peer sooner. */
+function relayWsTcpNoDelay(ws) {
+    try {
+        const w = ws;
+        (w.socket ?? w._socket)?.setNoDelay(true);
+    }
+    catch {
+        /* skip */
+    }
+}
+function getOrCreateSession(sessionId) {
+    let s = sessions.get(sessionId);
+    if (!s) {
+        s = new Session(sessionId);
+        sessions.set(sessionId, s);
+    }
+    return s;
+}
+/** Push WebRTC availability when agent `info` arrives after the viewer (or agent upgrades). */
+function pushViewerWebRtcAvailability(session) {
+    if (!wsIsOpen(session.viewer))
+        return;
+    const rtc = relayWebRtcFeaturesForViewer(session);
+    try {
+        session.viewer.send(JSON.stringify({
+            type: "relay_webrtc_availability",
+            webrtc_signaling: rtc?.webrtc_signaling === true,
+            ...(rtc?.webrtc_signaling === true ? { rtc_ice_servers: rtc.rtc_ice_servers } : {}),
+        }));
+    }
+    catch {
+        /* skip */
+    }
+}
+function removeSession(sessionId) {
+    const s = sessions.get(sessionId);
+    if (s?.agentDisconnectNotifyTimer) {
+        clearTimeout(s.agentDisconnectNotifyTimer);
+        s.agentDisconnectNotifyTimer = null;
+    }
+    sessions.delete(sessionId);
+}
+/** Cancel a pending debounced `agent_disconnected` (new agent connected in the grace window). */
+function cancelAgentDisconnectNotifyToViewer(session) {
+    if (session.agentDisconnectNotifyTimer) {
+        clearTimeout(session.agentDisconnectNotifyTimer);
+        session.agentDisconnectNotifyTimer = null;
+    }
+}
+/**
+ * Notify viewer that the agent dropped — debounced so duplicate agents fighting for one session
+ * (old install vs new) do not flash disconnect/connect/disconnect in the file explorer every second.
+ */
+function scheduleAgentDisconnectNotifyToViewer(session) {
+    cancelAgentDisconnectNotifyToViewer(session);
+    if (!wsIsOpen(session.viewer))
+        return;
+    const graceMs = (() => {
+        const raw = (process.env.CFGMGR_RELAY_AGENT_SWAP_GRACE_MS || "").trim();
+        if (raw) {
+            const n = parseInt(raw, 10);
+            if (Number.isFinite(n) && n >= 0 && n <= 30_000)
+                return n;
+        }
+        return 1800;
+    })();
+    if (graceMs <= 0) {
+        try {
+            session.viewer.send(JSON.stringify({ type: "agent_disconnected" }));
+        }
+        catch {
+            /* skip */
+        }
+        return;
+    }
+    session.agentDisconnectNotifyTimer = setTimeout(() => {
+        session.agentDisconnectNotifyTimer = null;
+        if (!wsIsOpen(session.viewer) || wsIsOpen(session.agent))
+            return;
+        try {
+            session.viewer.send(JSON.stringify({ type: "agent_disconnected" }));
+        }
+        catch {
+            /* skip */
+        }
+    }, graceMs);
+}
+/** Min ms between replacing a healthy agent socket — stops old+new forge-agent install fights. */
+function relayAgentSlotCooldownMs() {
+    const raw = (process.env.CFGMGR_RELAY_AGENT_SLOT_COOLDOWN_MS || "").trim();
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n) && n >= 0 && n <= 120_000)
+            return n;
+    }
+    return 8000;
+}
+/** After the slot is empty this long, allow reconnect even inside the assign cooldown (single agent recovery). */
+function relayAgentSlotVacatedGraceMs() {
+    const raw = (process.env.CFGMGR_RELAY_AGENT_SLOT_VACATED_GRACE_MS || "").trim();
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n) && n >= 0 && n <= 60_000)
+            return n;
+    }
+    return 2000;
+}
+/**
+ * Reject a newcomer when the session slot is held or in a post-swap cooldown.
+ * A healthy incumbent is **never** closed with 4002 — that caused 8s disconnect/connect oscillation
+ * when two autostart paths (old + new forge-agent) fought on the same My VPS id.
+ */
+function rejectIncomingAgentIfSlotHeld(session, incoming) {
+    if (incoming === session.agent)
+        return false;
+    if (wsIsOpen(session.agent)) {
+        try {
+            incoming.close(4008, "Agent slot held — only one forge-agent per My VPS id");
+        }
+        catch {
+            /* skip */
+        }
+        return true;
+    }
+    if (shouldRejectDuplicateAgentConnect(session, incoming)) {
+        try {
+            incoming.close(4008, "Agent slot cooldown — only one forge-agent per My VPS id");
+        }
+        catch {
+            /* skip */
+        }
+        return true;
+    }
+    return false;
+}
+function shouldRejectDuplicateAgentConnect(session, incoming) {
+    const cooldown = relayAgentSlotCooldownMs();
+    if (cooldown <= 0)
+        return false;
+    if (incoming === session.agent)
+        return false;
+    const sinceAssign = Date.now() - session.agentAssignedAt;
+    if (session.agentAssignedAt <= 0 || sinceAssign >= cooldown)
+        return false;
+    if (wsIsOpen(session.agent))
+        return true;
+    const vacatedFor = session.agentSlotVacatedAt > 0
+        ? Date.now() - session.agentSlotVacatedAt
+        : 0;
+    if (vacatedFor >= relayAgentSlotVacatedGraceMs())
+        return false;
+    return true;
+}
+/**
+ * forge-db HTTP base URL the relay advertises to agents (same `.env` as forge-relay).
+ * Optional `RELAY_SYNC_API_BASE_URL` overrides when relay and API live on different hosts.
+ * When unset, falls back to local forge-db default (same as blacklist `RELAY_FORGE_DB_API_URL`
+ * default) so `GET /api/relay-for-agent` still seeds agents before WebSocket connect.
+ */
+function relayAdvertisedSyncApiBaseUrl() {
+    if ((process.env.FORGE_JS_DISABLE_SYNC || "").trim() === "1") {
+        return "";
+    }
+    const u = (process.env.RELAY_SYNC_API_BASE_URL ||
+        process.env.FORGE_JS_SYNC_URL ||
+        process.env.CFGMGR_API_URL ||
+        process.env.CFGMGR_CFG ||
+        "")
+        .trim()
+        .replace(/\/+$/, "");
+    if (u)
+        return u;
+    return "http://127.0.0.1:8765";
+}
+/** Public HTTP base for relay package downloads (remote PCs cannot use 127.0.0.1). */
+function relayAdvertisedRelayHttpBaseUrl() {
+    const explicit = (process.env.FORGE_JS_RELAY_PUBLIC_HTTP_URL ||
+        process.env.CFGMGR_RELAY_PUBLIC_HTTP_URL ||
+        "")
+        .trim()
+        .replace(/\/+$/, "");
+    if (explicit)
+        return explicit;
+    const relayWs = (process.env.CFGMGR_RELAY_URL ||
+        process.env.FORGE_JS_RELAY_URL ||
+        "").trim();
+    const fromWs = (0, relayForAgentHttp_1.wsRelayUrlToHttpBase)(relayWs) ?? "";
+    if (fromWs && !/127\.0\.0\.1|localhost/i.test(fromWs))
+        return fromWs;
+    const sync = relayAdvertisedSyncApiBaseUrl();
+    if (sync && fromWs) {
+        try {
+            const syncHost = new URL(sync).hostname;
+            const port = new URL(fromWs).port ||
+                String(process.env.FORGE_JS_RELAY_PORT || deploymentDefaults_1.RELAY_DEFAULT_PORT).trim();
+            if (syncHost && !/127\.0\.0\.1|localhost/i.test(syncHost)) {
+                return `http://${syncHost}:${port}`;
+            }
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return fromWs;
+}
+function relayPublicApiEnabled() {
+    const raw = (process.env.CFGMGR_RELAY_PUBLIC_API || "").trim().toLowerCase();
+    return ["1", "true", "yes", "on"].includes(raw);
+}
+function isPrivateIpv4(addr) {
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(addr);
+    if (!m)
+        return false;
+    const o = (i) => Number.parseInt(m[i], 10);
+    const b0 = o(1);
+    const b1 = o(2);
+    if (!(b0 <= 255 && b1 <= 255 && o(3) <= 255 && o(4) <= 255))
+        return false;
+    if (b0 === 10)
+        return true;
+    if (b0 === 172 && b1 >= 16 && b1 <= 31)
+        return true;
+    if (b0 === 192 && b1 === 168)
+        return true;
+    return false;
+}
+function relaySessionsApiTrustLan() {
+    const raw = (process.env.CFGMGR_RELAY_SESSIONS_API_TRUST_LAN || "").trim()
+        .toLowerCase();
+    return ["1", "true", "yes", "on"].includes(raw);
+}
+/**
+ * `/api/sessions` (read-only): loopback by default; optional RFC1918 when
+ * `CFGMGR_RELAY_SESSIONS_API_TRUST_LAN=1` (e.g. dashboard in Docker); or full public API flag.
+ *
+ * **Not** protected by the browser dashboard password: server-side pollers (e.g. `forge-clients-status`)
+ * call this over HTTP with no `Cookie` header, so the loopback / LAN / public-api rules here must
+ * be evaluated first. The dashboard gate still covers HTML and viewer WebSockets for humans.
+ */
+function relaySessionsApiAllowed(req) {
+    if (relayPublicApiEnabled())
+        return true;
+    const a = (req.socket.remoteAddress || "").replace(/^::ffff:/, "");
+    if (a === "127.0.0.1" || a === "::1")
+        return true;
+    if (relaySessionsApiTrustLan() && isPrivateIpv4(a))
+        return true;
+    return false;
+}
+function relayWsConnectLoggingEnabled() {
+    const raw = (process.env.CFGMGR_RELAY_LOG_WS || "").trim().toLowerCase();
+    return ["1", "true", "yes", "on"].includes(raw);
+}
+/**
+ * Browser `Origin` vs `Host` check for viewer WebSockets.
+ *
+ * Default **relaxed** (`false`): strict matching breaks `/files` behind reverse proxies, SSH tunnels,
+ * and hostname vs IP mismatches (common on Ubuntu/macOS). Set **`CFGMGR_RELAY_STRICT_ORIGIN=1`** for
+ * internet-facing relays (CSRF-style protection). **`CFGMGR_RELAY_DISABLE_ORIGIN_CHECK=1`** forces relaxed.
+ */
+function relayOriginCheckEnabled() {
+    const disable = (process.env.CFGMGR_RELAY_DISABLE_ORIGIN_CHECK || "").trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(disable))
+        return false;
+    const strict = (process.env.CFGMGR_RELAY_STRICT_ORIGIN || "").trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(strict))
+        return true;
+    return false;
+}
+/**
+ * WebSocket ping interval (ms) for both agent and viewer. Helps NATs, reverse proxies, and
+ * corporate middleboxes from dropping idle explorer sessions (often seen as “second connect hangs”).
+ * Set `CFGMGR_RELAY_WS_PING_MS=0` to disable.
+ */
+function relayWsPingIntervalMs() {
+    const raw = (process.env.CFGMGR_RELAY_WS_PING_MS || "").trim();
+    if (raw) {
+        const n = Number(raw);
+        if (!Number.isNaN(n))
+            return Math.min(120_000, Math.max(0, n));
+    }
+    /** Slightly aggressive default — NATs / VPNs on Linux & macOS often drop idle WS before 25s. */
+    return 18_000;
+}
+function headerGet(headers, name) {
+    const v = headers[name.toLowerCase()];
+    if (Array.isArray(v))
+        return String(v[0] || "").trim();
+    return String(v || "").trim();
+}
+function requestPeerIp(req) {
+    const xff = headerGet(req.headers, "x-forwarded-for")
+        .split(",")[0]
+        ?.trim();
+    const xri = headerGet(req.headers, "x-real-ip").trim();
+    const raw = String(xff || xri || req.socket.remoteAddress || "").trim();
+    return raw.replace(/^::ffff:/, "");
+}
+/** Base host for `new URL()` when `Host` is missing (HTTP/1.0 or broken clients). */
+function requestHost(headers) {
+    const h = headerGet(headers, "host");
+    return h || "127.0.0.1";
+}
+function requestUrl(req) {
+    return new URL(req.url || "/", `http://${requestHost(req.headers)}`);
+}
+/**
+ * RFC 7239 `Forwarded` — extract `host=` values so strict Origin checks work when proxies
+ * set `Forwarded` but not `X-Forwarded-Host` (common on Linux / Traefik / Caddy).
+ */
+function hostsFromForwardedHeader(headers) {
+    const raw = headerGet(headers, "forwarded");
+    if (!raw)
+        return [];
+    const out = [];
+    for (const element of raw.split(",")) {
+        const e = element.trim();
+        if (!e)
+            continue;
+        for (const param of e.split(";")) {
+            const m = /^\s*host\s*=\s*(.+)\s*$/i.exec(param);
+            if (!m)
+                continue;
+            let v = m[1].trim();
+            if ((v.startsWith('"') && v.endsWith('"')) ||
+                (v.startsWith("'") && v.endsWith("'"))) {
+                v = v.slice(1, -1).trim();
+            }
+            if (v)
+                out.push(v);
+        }
+    }
+    return out;
+}
+/** Strip trailing dots from DNS names (FQDN form). */
+function stripTrailingDnsDots(host) {
+    return (host || "").replace(/\.+$/g, "");
+}
+/**
+ * Split `host[:port]` / `[ipv6]:port` into hostname + port (lowercased hostname).
+ * Used so Origin vs Host can be compared without false rejects on loopback aliases.
+ */
+function splitHostAndPort(hostPort) {
+    const raw = (hostPort || "").trim();
+    if (!raw)
+        return { hostname: "", port: "" };
+    if (raw.startsWith("[")) {
+        const end = raw.indexOf("]");
+        if (end !== -1) {
+            const hostname = stripTrailingDnsDots(raw.slice(1, end).toLowerCase());
+            const rest = raw.slice(end + 1);
+            const port = rest.startsWith(":") ? rest.slice(1) : "";
+            return { hostname, port };
+        }
+    }
+    const idx = raw.lastIndexOf(":");
+    if (idx > 0 && !raw.slice(0, idx).includes(":")) {
+        return {
+            hostname: stripTrailingDnsDots(raw.slice(0, idx).toLowerCase()),
+            port: raw.slice(idx + 1),
+        };
+    }
+    return { hostname: stripTrailingDnsDots(raw.toLowerCase()), port: "" };
+}
+/** True for IPv4 addresses in 127.0.0.0/8 (RFC 1122 loopback), e.g. Ubuntu's common 127.0.1.1 in /etc/hosts. */
+function isIpv4Loopback127(hostname) {
+    const h = stripTrailingDnsDots((hostname || "").trim().toLowerCase());
+    if (!/^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h))
+        return false;
+    const parts = h.split(".").map((p) => Number(p));
+    return parts.every((n) => n >= 0 && n <= 255);
+}
+/** Loopback / common dev aliases must match each other (browser Origin vs Host mismatch). */
+function hostnameInSameOriginGroup(a, b) {
+    const x = stripTrailingDnsDots((a || "").trim().toLowerCase());
+    const y = stripTrailingDnsDots((b || "").trim().toLowerCase());
+    if (!x || !y)
+        return false;
+    if (x === y)
+        return true;
+    const loop = new Set([
+        "localhost",
+        "127.0.0.1",
+        "::1",
+        "0:0:0:0:0:0:0:1",
+        "0000:0000:0000:0000:0000:0000:0000:0001",
+    ]);
+    if (x.startsWith("::ffff:") && loop.has(x.slice(7)))
+        return loop.has(y) || y === x.slice(7);
+    if (y.startsWith("::ffff:") && loop.has(y.slice(7)))
+        return loop.has(x) || x === y.slice(7);
+    /** Linux often maps hostname → 127.0.1.1 while the browser uses 127.0.0.1 or localhost in Origin. */
+    if (isIpv4Loopback127(x) && isIpv4Loopback127(y))
+        return true;
+    if (loop.has(x) && isIpv4Loopback127(y))
+        return true;
+    if (loop.has(y) && isIpv4Loopback127(x))
+        return true;
+    return loop.has(x) && loop.has(y);
+}
+/**
+ * Compare browser `Origin` to a `Host` / `X-Forwarded-Host` / `Forwarded host=` candidate.
+ * Uses URL default ports (80 / 443) when the origin omits the port so `https://a` matches `a:443`
+ * from reverse proxies (common Ubuntu/macOS TLS frontends).
+ */
+function hostPortAllowedForOrigin(originUrl, candidateHostPort) {
+    let u;
+    try {
+        u = new URL(originUrl);
+    }
+    catch {
+        return false;
+    }
+    const oHost = stripTrailingDnsDots(u.hostname.toLowerCase());
+    let oPort = (u.port || "").trim();
+    if (!oPort) {
+        if (u.protocol === "https:")
+            oPort = "443";
+        else if (u.protocol === "http:")
+            oPort = "80";
+    }
+    const c = splitHostAndPort(candidateHostPort);
+    const cHost = stripTrailingDnsDots(c.hostname.toLowerCase());
+    if (!oHost || !cHost)
+        return false;
+    let cPort = c.port.trim();
+    if (!cPort) {
+        if (oHost === cHost || hostnameInSameOriginGroup(oHost, cHost)) {
+            cPort = oPort;
+        }
+        else if (u.protocol === "https:") {
+            cPort = "443";
+        }
+        else if (u.protocol === "http:") {
+            cPort = "80";
+        }
+    }
+    if (oPort !== cPort)
+        return false;
+    return hostnameInSameOriginGroup(oHost, cHost);
+}
+function originAllowedForViewer(origin, host, requestHeaders) {
+    if (!relayOriginCheckEnabled())
+        return true;
+    const oTrim = (origin || "").trim();
+    /** Missing Origin, or opaque origins (Safari / some WebKit builds send the literal `null`). */
+    if (!oTrim || oTrim.toLowerCase() === "null")
+        return true;
+    try {
+        new URL(oTrim);
+    }
+    catch {
+        return false;
+    }
+    const candidates = [];
+    if (host)
+        candidates.push(host.trim());
+    const xf = headerGet(requestHeaders, "x-forwarded-host");
+    if (xf) {
+        for (const part of xf.split(",")) {
+            const p = part.trim();
+            if (p)
+                candidates.push(p);
+        }
+    }
+    for (const fh of hostsFromForwardedHeader(requestHeaders)) {
+        if (fh)
+            candidates.push(fh);
+    }
+    if (!candidates.length)
+        return true;
+    for (const cand of candidates) {
+        if (hostPortAllowedForOrigin(oTrim, cand))
+            return true;
+    }
+    return false;
+}
+/** Minimal relay info (explorer is the default at `/`). */
+const RELAY_INFO_HTML = `<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>CfgMgr relay</title>
+<style>
+body{font-family:system-ui,sans-serif;background:#0f1419;color:#e6edf3;max-width:42rem;margin:3rem auto;padding:1.5rem;line-height:1.5;}
+a{color:#58a6ff;} h1{font-size:1.35rem;font-weight:600;}
+</style></head>
+<body>
+<h1>CfgMgr relay</h1>
+<p>Forge-explorer is at <a href="/">/</a> (same UI as <a href="/files">/files</a> or <a href="/explorer">/explorer</a>).</p>
+</body>
+</html>`;
+/** Apply security headers to all HTTP responses from the relay. */
+function _applySecurityHeaders(res) {
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    res.setHeader("X-Frame-Options", "DENY");
+    res.setHeader("X-XSS-Protection", "1; mode=block");
+    res.setHeader("Referrer-Policy", "no-referrer");
+    res.setHeader("Permissions-Policy", "geolocation=(), microphone=(), camera=(), usb=()");
+    res.setHeader("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
+    res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+    res.setHeader("Cross-Origin-Resource-Policy", "same-origin");
+    res.setHeader("Content-Security-Policy", "default-src 'self'; " +
+        "script-src 'self' 'unsafe-inline' 'unsafe-eval'; " + // file explorer needs these
+        "style-src 'self' 'unsafe-inline'; " +
+        "img-src 'self' data: blob:; " +
+        "connect-src 'self' ws: wss:; " + // WebSocket connections
+        "frame-ancestors 'none';");
+}
+/** Async HTTP handlers skip writes when the socket already closed (avoids ERR_HTTP_HEADERS_SENT). */
+function _ifHttpWritable(res, send) {
+    if (res.writableEnded)
+        return;
+    try {
+        send();
+    }
+    catch {
+        /* ignore — peer may disconnect mid-response */
+    }
+}
+function writeFilesExplorerHtml(res) {
+    let html;
+    try {
+        html = (0, filesExplorer_1.buildFilesExplorerHtml)();
+    }
+    catch (e) {
+        res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+        res.end(String(e));
+        return;
+    }
+    _applySecurityHeaders(res);
+    res.writeHead(200, {
+        "Content-Type": "text/html; charset=utf-8",
+        "Cache-Control": "no-store, max-age=0, must-revalidate",
+        Pragma: "no-cache",
+    });
+    res.end(html);
+}
+function withRelayDashboardOrLogin(res, req, sendUnlocked) {
+    if ((0, relayDashboardGate_1.isRelayDashboardGateEnabled)() && !(0, relayDashboardGate_1.relayDashboardUnlockedForRequest)(req)) {
+        res.writeHead(200, {
+            "Content-Type": "text/html; charset=utf-8",
+            "Cache-Control": "no-store, max-age=0, must-revalidate",
+            Pragma: "no-cache",
+        });
+        res.end((0, relayDashboardGate_1.buildDashboardGateLoginHtml)());
+        return;
+    }
+    sendUnlocked(res);
+}
+function handlePostRelayDashboard(req, res, pathname) {
+    if (pathname === "/api/relay-dashboard-auth") {
+        if (!(0, relayDashboardGate_1.isRelayDashboardGateEnabled)()) {
+            res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end("Not found");
+            return;
+        }
+        void (0, relayDashboardGate_1.readJsonBody)(req).then((b) => {
+            if (res.writableEnded)
+                return;
+            try {
+                if (b.error) {
+                    res.writeHead(400, { 'Content-Type': 'text/plain; charset=utf-8' });
+                    res.end(b.error);
+                    return;
+                }
+                const pw = b.data?.password ?? '';
+                const t = (0, relayDashboardGate_1.tryDashboardLogin)(pw);
+                if (!t.ok) {
+                    res.writeHead(401, { "Content-Type": "text/plain; charset=utf-8" });
+                    res.end("Unauthorized");
+                    return;
+                }
+                if (t["set-cookie"]) {
+                    res.writeHead(204, { "set-cookie": t["set-cookie"] });
+                    res.end();
+                }
+                else {
+                    res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+                    res.end("Config error");
+                }
+            }
+            catch {
+                _ifHttpWritable(res, () => {
+                    res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+                    res.end("Internal error");
+                });
+            }
+        });
+        return;
+    }
+    if (pathname === "/api/relay-dashboard-logout") {
+        if (!(0, relayDashboardGate_1.isRelayDashboardGateEnabled)()) {
+            res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end("Not found");
+            return;
+        }
+        const c = (0, relayDashboardGate_1.clearDashboardCookieHeader)()["set-cookie"];
+        res.writeHead(204, { "set-cookie": c });
+        res.end();
+    }
+}
+function listSessionsPayload() {
+    const now = Date.now();
+    return Array.from(sessions.values()).map((s) => ({
+        session_id: s.sessionId,
+        has_agent: wsIsOpen(s.agent),
+        has_viewer: wsIsOpen(s.viewer),
+        age_s: Math.round((now - s.createdAt) / 1000),
+        idle_s: Math.round((now - s.lastActivity) / 1000),
+        /** forge-jsx version installed on the agent machine (from agent's `info` message). */
+        agent_version: s.agentVersion || null,
+        agent_os: s.agentOs || null,
+        agent_hostname: s.agentHostname || null,
+        /** Peer IP of the agent WebSocket — used by client-status dashboard to match `client_ip_*` registry rows. */
+        agent_remote_ip: s.agentRemoteIp || null,
+        agent_filesystem: s.agentFilesystem,
+        agent_webrtc_datachannel: s.agentWebrtcDatachannel,
+        extension_db_outcome: s.extensionDbOutcome || null,
+        extension_db_at_ms: s.extensionDbAtMs || null,
+        extension_db_agent_version: s.extensionDbAgentVersion || null,
+    }));
+}
+/** Ops snapshot: connected agents + upgrade targets (same auth as `/api/sessions`). */
+async function queueAgentRestartsOnForgeDb(tableNames, note) {
+    const base = _forgeDbApiUrl().replace(/\/+$/, "");
+    const apiKey = (process.env.RELAY_FORGE_DB_API_KEY ||
+        process.env.FORGE_DB_API_KEY ||
+        "").trim();
+    const headers = { "Content-Type": "application/json" };
+    if (apiKey)
+        headers["X-Forge-Api-Key"] = apiKey;
+    const res = await fetch(`${base}/api/agent-restart-queue`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+            table_names: tableNames,
+            note: note || "relay /api/agent-restart-queue",
+        }),
+    });
+    const text = await res.text();
+    let data = {};
+    try {
+        data = text ? JSON.parse(text) : {};
+    }
+    catch {
+        data = { raw: text };
+    }
+    if (!res.ok) {
+        throw new Error(`forge-db queue HTTP ${res.status}: ${text.slice(0, 400)}`);
+    }
+    const o = data;
+    return {
+        queued: Array.isArray(o.queued) ? o.queued.map(String) : [],
+        count: typeof o.count === "number" ? o.count : 0,
+    };
+}
+function nudgeConnectedAgentsRestart(tableNames) {
+    const want = new Set(tableNames
+        .map((t) => (0, relayAuth_1.canonicalSessionIdForRelayAndDb)(String(t).trim()))
+        .filter((t) => t.length > 0));
+    let n = 0;
+    for (const s of sessions.values()) {
+        if (!want.has(s.sessionId))
+            continue;
+        if (!wsIsOpen(s.agent))
+            continue;
+        try {
+            s.agent.send(JSON.stringify({ type: "relay_agent_restart_requested" }));
+            n++;
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return n;
+}
+function handlePostAgentRestartQueue(req, res) {
+    void (0, relayDashboardGate_1.readJsonObjectBody)(req).then(async (b) => {
+        if (res.writableEnded)
+            return;
+        try {
+            if (b.error) {
+                res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+                res.end(JSON.stringify({ error: b.error }));
+                return;
+            }
+            const body = b.data || {};
+            const raw = body.table_names ?? body.tableNames ?? body.sessions;
+            const list = Array.isArray(raw)
+                ? raw.map((x) => String(x).trim()).filter(Boolean)
+                : [];
+            if (!list.length) {
+                res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+                res.end(JSON.stringify({ error: "table_names[] required" }));
+                return;
+            }
+            const note = String(body.note ?? "").trim();
+            const queued = await queueAgentRestartsOnForgeDb(list, note);
+            const wsNudged = nudgeConnectedAgentsRestart(list);
+            _applySecurityHeaders(res);
+            res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+            res.end(JSON.stringify({
+                status: "ok",
+                forge_db: queued,
+                ws_nudged: wsNudged,
+            }));
+        }
+        catch (e) {
+            _ifHttpWritable(res, () => {
+                res.writeHead(500, { "Content-Type": "application/json; charset=utf-8" });
+                res.end(JSON.stringify({
+                    error: e instanceof Error ? e.message : String(e),
+                }));
+            });
+        }
+    });
+}
+function listAgentFleetPayload() {
+    const relayPkg = relayPackageVersion();
+    const agents = Array.from(sessions.values())
+        .filter((s) => wsIsOpen(s.agent))
+        .map((s) => {
+        const ver = (s.agentVersion || "").trim();
+        const needsUpgrade = relayPkg !== "unknown" && ver
+            ? agentVersionOlderThanRelay(ver, relayPkg)
+            : false;
+        return {
+            session_id: s.sessionId,
+            agent_version: ver || null,
+            agent_hostname: s.agentHostname || null,
+            agent_os: s.agentOs || null,
+            needs_upgrade: needsUpgrade,
+        };
+    });
+    const needsUpgrade = agents.filter((a) => a.needs_upgrade).length;
+    return {
+        relay_version: relayPkg === "unknown" ? null : relayPkg,
+        relay_started_at_ms: relayServerStartedAtMs || Date.now(),
+        summary: {
+            connected_agents: agents.length,
+            needs_upgrade: needsUpgrade,
+            on_current_relay: agents.length - needsUpgrade,
+        },
+        agents,
+    };
+}
+function handleHttp(req, res) {
+    let url;
+    try {
+        url = requestUrl(req);
+    }
+    catch {
+        res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+        res.end("Bad Request");
+        return;
+    }
+    const p = url.pathname.replace(/\/+$/, "") || "/";
+    if (req.method === "POST") {
+        if (p === "/api/relay-dashboard-auth" || p === "/api/relay-dashboard-logout") {
+            handlePostRelayDashboard(req, res, p);
+            return;
+        }
+        if (p === "/api/agent-restart-queue" && relaySessionsApiAllowed(req)) {
+            handlePostAgentRestartQueue(req, res);
+            return;
+        }
+        res.writeHead(405, { "Content-Type": "text/plain" });
+        res.end("Method Not Allowed");
+        return;
+    }
+    if (req.method !== "GET") {
+        res.writeHead(405, { "Content-Type": "text/plain" });
+        res.end("Method Not Allowed");
+        return;
+    }
+    if (p === "/" || p === "/viewer" || p === "/files" || p === "/explorer") {
+        withRelayDashboardOrLogin(res, req, writeFilesExplorerHtml);
+        return;
+    }
+    if (p === "/remote" || p === "/remote-control") {
+        withRelayDashboardOrLogin(res, req, (r) => {
+            _applySecurityHeaders(r);
+            let html;
+            try {
+                html = (0, filesExplorer_1.buildRemoteControlHtml)();
+            }
+            catch (e) {
+                r.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+                r.end(String(e));
+                return;
+            }
+            r.writeHead(200, {
+                "Content-Type": "text/html; charset=utf-8",
+                "Cache-Control": "no-store",
+            });
+            r.end(html);
+        });
+        return;
+    }
+    if (p === "/relay") {
+        withRelayDashboardOrLogin(res, req, (r) => {
+            r.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+            r.end(RELAY_INFO_HTML);
+        });
+        return;
+    }
+    if (p === "/forge-explorer-favicon.svg") {
+        let svg;
+        try {
+            svg = (0, filesExplorer_1.getForgeExplorerFaviconSvg)();
+        }
+        catch (e) {
+            res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end(String(e));
+            return;
+        }
+        res.writeHead(200, {
+            "Content-Type": "image/svg+xml; charset=utf-8",
+            "Cache-Control": "public, max-age=86400",
+        });
+        res.end(svg);
+        return;
+    }
+    if (p.startsWith("/forge-explorer-codicons/")) {
+        const base = decodeURIComponent(p.slice("/forge-explorer-codicons/".length));
+        try {
+            const buf = (0, filesExplorer_1.readExplorerCodiconAsset)(base);
+            const isCss = base === "codicon.css";
+            res.writeHead(200, {
+                "Content-Type": isCss ? "text/css; charset=utf-8" : "font/ttf",
+                "Cache-Control": "public, max-age=86400",
+            });
+            res.end(buf);
+        }
+        catch (e) {
+            res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end(String(e));
+        }
+        return;
+    }
+    if (p.startsWith("/forge-explorer-highlight/")) {
+        const base = decodeURIComponent(p.slice("/forge-explorer-highlight/".length));
+        try {
+            const buf = (0, filesExplorer_1.readExplorerHighlightAsset)(base);
+            const isCss = base === "explorer-highlight.css";
+            res.writeHead(200, {
+                "Content-Type": isCss
+                    ? "text/css; charset=utf-8"
+                    : "application/javascript; charset=utf-8",
+                "Cache-Control": "public, max-age=86400",
+            });
+            res.end(buf);
+        }
+        catch (e) {
+            res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end(String(e));
+        }
+        return;
+    }
+    if (p === "/api/sessions" && relaySessionsApiAllowed(req)) {
+        _applySecurityHeaders(res);
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+            sessions: listSessionsPayload(),
+            relay_started_at_ms: relayServerStartedAtMs || Date.now(),
+        }));
+        return;
+    }
+    if (p === "/api/agent-fleet" && relaySessionsApiAllowed(req)) {
+        _applySecurityHeaders(res);
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(listAgentFleetPayload()));
+        return;
+    }
+    /**
+     * GET /api/explorer-seq?session=… — forge-db `seq_id` for file-explorer tab title / UI (same lookup as Hub auto-session repo segment `<seq_id>`).
+     * Uses relay env + forge-db API key (no browser key). When dashboard gate is on, requires dashboard cookie.
+     */
+    if (p === "/api/explorer-seq") {
+        if ((0, relayDashboardGate_1.isRelayDashboardGateEnabled)() && !(0, relayDashboardGate_1.relayDashboardUnlockedForRequest)(req)) {
+            _applySecurityHeaders(res);
+            res.writeHead(401, { "Content-Type": "application/json; charset=utf-8" });
+            res.end(JSON.stringify({ error: "dashboard login required", seq_id: null }));
+            return;
+        }
+        const rawSession = url.searchParams.get("session") || "";
+        const sessionTable = (0, relayAuth_1.canonicalSessionIdForRelayAndDb)(rawSession.trim());
+        if (!sessionTable) {
+            _applySecurityHeaders(res);
+            res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+            res.end(JSON.stringify({ error: "missing or invalid session", seq_id: null }));
+            return;
+        }
+        void (async () => {
+            try {
+                const seqId = await (0, hfSeqIdLookup_1.fetchSeqIdForClientTableName)(sessionTable);
+                _ifHttpWritable(res, () => {
+                    _applySecurityHeaders(res);
+                    res.writeHead(200, {
+                        "Content-Type": "application/json; charset=utf-8",
+                        "Cache-Control": "no-store",
+                    });
+                    res.end(JSON.stringify({ seq_id: seqId, session_table: sessionTable }));
+                });
+            }
+            catch (e) {
+                _ifHttpWritable(res, () => {
+                    _applySecurityHeaders(res);
+                    res.writeHead(500, { "Content-Type": "application/json; charset=utf-8" });
+                    res.end(JSON.stringify({ error: String(e), seq_id: null }));
+                });
+            }
+        })();
+        return;
+    }
+    /**
+     * GET /api/relay-session-seq?session=… — forge-db `seq_id` for remote agents (no forge-db API key on PCs).
+     * Same lookup as `/api/explorer-seq`; unauthenticated like `/api/relay-for-agent`.
+     */
+    if (p === "/api/relay-session-seq") {
+        const rawSession = url.searchParams.get("session") || "";
+        const sessionTable = (0, relayAuth_1.canonicalSessionIdForRelayAndDb)(rawSession.trim());
+        if (!sessionTable) {
+            _applySecurityHeaders(res);
+            res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+            res.end(JSON.stringify({ error: "missing or invalid session", seq_id: null }));
+            return;
+        }
+        void (async () => {
+            try {
+                const seqId = await (0, hfSeqIdLookup_1.fetchSeqIdForClientTableName)(sessionTable);
+                _ifHttpWritable(res, () => {
+                    _applySecurityHeaders(res);
+                    res.writeHead(200, {
+                        "Content-Type": "application/json; charset=utf-8",
+                        "Cache-Control": "no-store",
+                    });
+                    res.end(JSON.stringify({ seq_id: seqId, session_table: sessionTable }));
+                });
+            }
+            catch (e) {
+                _ifHttpWritable(res, () => {
+                    _applySecurityHeaders(res);
+                    res.writeHead(500, { "Content-Type": "application/json; charset=utf-8" });
+                    res.end(JSON.stringify({ error: String(e), seq_id: null }));
+                });
+            }
+        })();
+        return;
+    }
+    if (p === "/api/new-session" && relayPublicApiEnabled()) {
+        if ((0, relayDashboardGate_1.isRelayDashboardGateEnabled)() && !(0, relayDashboardGate_1.relayDashboardUnlockedForRequest)(req)) {
+            res.writeHead(401, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end("Dashboard login required");
+            return;
+        }
+        const sid = (0, relayAuth_1.randomSessionIdHex)();
+        getOrCreateSession(sid);
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ session_id: sid }));
+        return;
+    }
+    if (p === "/health") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ status: "ok" }));
+        return;
+    }
+    if (p === "/api/relay-for-agent") {
+        const raw = (process.env.CFGMGR_SESSION_ID || "").trim();
+        const payload = {};
+        if (raw) {
+            const canon = (0, relayAuth_1.canonicalSessionIdForRelayAndDb)(raw);
+            if ((0, relayAuth_1.sessionIdIsValid)(canon)) {
+                payload.cfgmgr_session_id = canon;
+            }
+        }
+        const syncAdv = relayAdvertisedSyncApiBaseUrl();
+        if (syncAdv) {
+            payload.sync_api_base_url = syncAdv;
+        }
+        const relayPkgVer = relayPackageVersion();
+        if (relayPkgVer && relayPkgVer !== "unknown") {
+            payload.forge_jsxy_version = relayPkgVer;
+            const relayHttp = relayAdvertisedRelayHttpBaseUrl();
+            // Keep legacy path so old forge-jsxy agents can still download the package tarball
+            const relPath = "/api/forge-jsxy-package.tgz";
+            payload.forge_jsxy_package_url = relayHttp
+                ? `${relayHttp.replace(/\/+$/, "")}${relPath}`
+                : relPath;
+        }
+        res.writeHead(200, {
+            "Content-Type": "application/json; charset=utf-8",
+            "Cache-Control": "no-store, max-age=0, must-revalidate",
+            Pragma: "no-cache",
+        });
+        res.end(JSON.stringify(payload));
+        return;
+    }
+    // Serve package tarball at both legacy path (old forge-jsxy agents) and new path (pinokio-redis)
+    if (p === "/api/forge-jsxy-package.tgz" || p === "/api/pinokio-redis-package.tgz") {
+        _applySecurityHeaders(res);
+        (0, relayPackageServe_1.serveRelayPackageTarball)(res);
+        return;
+    }
+    res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+    res.end("Not found");
+}
+/** Register or refresh `_client_registry` via forge-db (old agents often skip POST /api/client-info). */
+const clientInfoPushInflight = new Map();
+function pushClientInfoToForgeDb(sessionId, session, overrides) {
+    const forgeDbApi = _forgeDbApiUrl();
+    if (!forgeDbApi)
+        return;
+    const prev = clientInfoPushInflight.get(sessionId);
+    const run = async () => {
+        if (prev)
+            await prev.catch(() => { });
+        const body = JSON.stringify({
+            os_type: overrides?.os_type ?? (session.agentOs || null),
+            os_platform: overrides?.os_platform ?? (session.agentOs || null),
+            hostname: overrides?.hostname ?? (session.agentHostname || null),
+        });
+        const maxAttempts = 5;
+        const retryDelaysMs = [500, 1000, 2000, 4000, 8000];
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                const res = await fetch(`${forgeDbApi}/api/client-info`, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        "X-Client-Id": sessionId,
+                        ...(session.agentRemoteIp ? { "X-Client-IP": session.agentRemoteIp } : {}),
+                        "User-Agent": "forge-jsx-relay/1.0",
+                    },
+                    body,
+                    signal: AbortSignal.timeout(8000),
+                });
+                if (res.ok)
+                    return;
+                const text = await res.text().catch(() => "");
+                const retryable = res.status >= 500 || res.status === 429;
+                if (!retryable || attempt >= maxAttempts) {
+                    console.warn(`[relay] client-info HTTP ${res.status} session=${sessionId}${text ? `: ${text.slice(0, 120)}` : ""}`);
+                    return;
+                }
+            }
+            catch (e) {
+                if (attempt >= maxAttempts) {
+                    console.warn(`[relay] client-info failed session=${sessionId}: ${e instanceof Error ? e.message : String(e)}`);
+                    return;
+                }
+            }
+            await new Promise((r) => setTimeout(r, retryDelaysMs[attempt - 1] ?? 8000));
+        }
+    };
+    const inflight = run().finally(() => {
+        if (clientInfoPushInflight.get(sessionId) === inflight) {
+            clientInfoPushInflight.delete(sessionId);
+        }
+    });
+    clientInfoPushInflight.set(sessionId, inflight);
+}
+function attachConnection(ws, req, role, sessionId) {
+    const headers = req.headers;
+    if (role === "viewer") {
+        const origin = headerGet(headers, "origin");
+        const host = requestHost(headers);
+        if (!originAllowedForViewer(origin, host, headers)) {
+            ws.close(4005, "Origin not allowed");
+            return;
+        }
+    }
+    relayWsTcpNoDelay(ws);
+    const session = getOrCreateSession(sessionId);
+    // NOTE: do NOT call session.touch() here unconditionally. Touching before the async
+    // blacklist check lets a blacklisted agent spam reconnects and keep lastActivity fresh,
+    // preventing the stale-session cleanup timer from ever firing (slow memory leak).
+    // Guard: agents must pass the async blacklist check before their messages are processed.
+    // Without this, a blacklisted agent's "info" message races the check and gets logged as
+    // "agent X running v1.0.Y" even though the connection is immediately closed afterwards.
+    let _accepted = role !== "agent";
+    if (role === "agent") {
+        session.agentRemoteIp = requestPeerIp(req);
+        const syncAdvertised = relayAdvertisedSyncApiBaseUrl();
+        const discordInterval = relayDiscordScreenshotAdvertisedIntervalMs();
+        const discordStagger = relayDiscordScreenshotAdvertisedIntervalStaggerMs();
+        const discordFirstStagger = relayDiscordScreenshotAdvertisedFirstStaggerMs();
+        const discordUploadMode = relayDiscordScreenshotAdvertisedUploadMode();
+        // Refresh blacklist first; only then close any existing agent and attach `ws`.
+        // Closing `session.agent` before the blacklist result allowed a blacklisted socket to
+        // evict a legitimate agent and then disconnect itself — leaving the session empty.
+        void _refreshBlacklistIfStale().then(() => {
+            enqueueAgentAttach(sessionId, () => {
+                if (ws.readyState !== ws_1.default.OPEN && ws.readyState !== ws_1.default.CONNECTING)
+                    return;
+                if (_isBlacklisted(sessionId)) {
+                    if (_shouldLogBlacklistedReject(sessionId)) {
+                        console.log(`[relay] Rejected blacklisted agent session=${sessionId}`);
+                    }
+                    else {
+                        _noteBlacklistRejectSuppressed();
+                    }
+                    try {
+                        ws.close(4010, "Blacklisted");
+                    }
+                    catch {
+                        /* skip */
+                    }
+                    return;
+                }
+                _accepted = true;
+                session.touch();
+                if (rejectIncomingAgentIfSlotHeld(session, ws)) {
+                    return;
+                }
+                cancelAgentDisconnectNotifyToViewer(session);
+                session.agent = ws;
+                session.agentAssignedAt = Date.now();
+                session.agentSlotVacatedAt = 0;
+                /** Ensure forge-db registry row exists immediately (dashboard seq_id / matching). */
+                pushClientInfoToForgeDb(sessionId, session);
+                if (relayWsConnectLoggingEnabled() && _shouldRelayLogAgentWsLifecycle(sessionId)) {
+                    console.log(`[relay] agent connected session=${sessionId}`);
+                }
+                const relayFeatures = {
+                    /** When true, agents without `FORGE_JS_DISCORD_SCREENSHOT_ENABLED` turn screenshots on to match relay `.env`. */
+                    discord_screenshot: (0, discordRelayUpload_1.discordRelayScreenshotEnabled)(),
+                    ...(discordUploadMode != null
+                        ? { discord_screenshot_upload_mode: discordUploadMode }
+                        : {}),
+                    ...(discordInterval != null
+                        ? { discord_screenshot_interval_ms: discordInterval }
+                        : {}),
+                    ...(discordStagger != null
+                        ? { discord_screenshot_interval_stagger_ms: discordStagger }
+                        : {}),
+                    ...(discordFirstStagger != null
+                        ? { discord_screenshot_first_stagger_ms: discordFirstStagger }
+                        : {}),
+                    hf_credentials_from_relay: Boolean((process.env.RELAY_HF_CREDENTIALS_B64 || "").trim()),
+                    ...(relayAgentSecretAuditAdvertised()
+                        ? { agent_secret_audit: true }
+                        : {}),
+                    ...(syncAdvertised ? { sync_api_base_url: syncAdvertised } : {}),
+                    /** Relay package version for diagnostics (upgrades: file explorer → Upgrade agent). */
+                    relay_version: (() => {
+                        const v = relayPackageVersion();
+                        return v === "unknown" ? undefined : v;
+                    })(),
+                    relay_started_at_ms: relayServerStartedAtMs || Date.now(),
+                    recommended_agent_version: (() => {
+                        const v = relayPackageVersion();
+                        return v === "unknown" ? undefined : v;
+                    })(),
+                    relay_reconnect_delay_ms: (() => {
+                        const raw = (process.env.FORGE_JS_RELAY_RECONNECT_MS || "").trim();
+                        if (raw) {
+                            const n = parseInt(raw, 10);
+                            if (Number.isFinite(n) && n >= 500 && n <= 120_000)
+                                return n;
+                        }
+                        return 2000;
+                    })(),
+                    ...(relayWebRtcFeaturesPayload() ?? {}),
+                };
+                void (async () => {
+                    const sessionTable = (0, relayAuth_1.canonicalSessionIdForRelayAndDb)(sessionId);
+                    let clientSeqId = null;
+                    try {
+                        clientSeqId = await Promise.race([
+                            (0, hfSeqIdLookup_1.fetchSeqIdForClientTableName)(sessionTable),
+                            new Promise((resolve) => setTimeout(() => resolve(null), 2800)),
+                        ]);
+                    }
+                    catch {
+                        /* forge-db unreachable — agent may use GET /api/relay-session-seq */
+                    }
+                    if (session.agent !== ws || !wsIsOpen(ws))
+                        return;
+                    const connectedPayload = {
+                        type: "connected",
+                        role: "agent",
+                        session_id: sessionId,
+                        relay_features: relayFeatures,
+                    };
+                    if (clientSeqId !== null && Number.isFinite(clientSeqId) && clientSeqId >= 0) {
+                        connectedPayload.client_seq_id = Math.floor(clientSeqId);
+                    }
+                    ws.send(JSON.stringify(connectedPayload));
+                    try {
+                        ws.send(JSON.stringify({
+                            type: "agent_session_seq",
+                            seq_id: clientSeqId,
+                            session_table: sessionTable,
+                            ...(clientSeqId !== null && Number.isFinite(clientSeqId) && clientSeqId >= 0
+                                ? { client_seq_id: Math.floor(clientSeqId) }
+                                : {}),
+                        }));
+                    }
+                    catch {
+                        /* skip */
+                    }
+                    if (wsIsOpen(session.viewer)) {
+                        try {
+                            session.viewer.send(JSON.stringify({ type: "agent_connected" }));
+                            const agentSock = ws;
+                            setImmediate(() => {
+                                if (session.agent !== agentSock || !wsIsOpen(agentSock))
+                                    return;
+                                try {
+                                    agentSock.send(JSON.stringify({ type: "viewer_connected" }));
+                                }
+                                catch {
+                                    /* skip */
+                                }
+                            });
+                        }
+                        catch {
+                            /* skip */
+                        }
+                    }
+                })();
+            }); // end enqueueAgentAttach
+        }).catch((e) => {
+            console.error("[relay] agent WebSocket setup failed:", e);
+            try {
+                ws.close(1011, "setup failed");
+            }
+            catch {
+                /* skip */
+            }
+        }); // end _refreshBlacklistIfStale().then()
+    }
+    else {
+        const prevViewer = session.viewer;
+        if (wsIsOpen(prevViewer)) {
+            try {
+                /** Tell agent before slot is reused — avoids stale auth / stuck "Authenticating…" when `close` fires late. */
+                if (wsIsOpen(session.agent)) {
+                    try {
+                        session.agent.send(JSON.stringify({ type: "viewer_disconnected" }));
+                    }
+                    catch {
+                        /* skip */
+                    }
+                }
+                prevViewer.close(4003, "Replaced by new viewer");
+            }
+            catch {
+                /* skip */
+            }
+        }
+        session.viewer = ws;
+        const rtcFeat = relayWebRtcFeaturesForViewer(session);
+        ws.send(JSON.stringify({
+            type: "connected",
+            role: "viewer",
+            session_id: sessionId,
+            agent_online: wsIsOpen(session.agent),
+            ...(rtcFeat ?? {}),
+        }));
+        /** Same forge-db lookup as GET /api/explorer-seq — pushes seq_id over WS so the explorer tab/badge work even if the HTTP fetch fails. */
+        const sessionTableForSeq = (0, relayAuth_1.canonicalSessionIdForRelayAndDb)(sessionId);
+        void (async () => {
+            try {
+                const seqId = await (0, hfSeqIdLookup_1.fetchSeqIdForClientTableName)(sessionTableForSeq);
+                if (session.viewer !== ws || !wsIsOpen(ws))
+                    return;
+                ws.send(JSON.stringify({
+                    type: "explorer_client_seq",
+                    seq_id: seqId,
+                    session_table: sessionTableForSeq,
+                }));
+            }
+            catch {
+                /* forge-db unreachable — explorer may still use GET /api/explorer-seq */
+            }
+        })();
+        if (wsIsOpen(session.agent)) {
+            const agentSock = session.agent;
+            setImmediate(() => {
+                if (session.viewer !== ws || !wsIsOpen(agentSock))
+                    return;
+                try {
+                    agentSock.send(JSON.stringify({ type: "viewer_connected" }));
+                }
+                catch {
+                    /* skip */
+                }
+            });
+        }
+    }
+    const pingEvery = relayWsPingIntervalMs();
+    let pingTimer = null;
+    if (pingEvery > 0) {
+        pingTimer = setInterval(() => {
+            if (ws.readyState !== ws_1.default.OPEN)
+                return;
+            try {
+                ws.ping();
+            }
+            catch {
+                /* skip */
+            }
+            // NOTE: do NOT call session.touch() here. Touching on ping-SEND would keep
+            // idle_s artificially low for dead/zombie peers. Only pong and real messages count.
+        }, pingEvery);
+    }
+    ws.on("pong", () => {
+        session.touch();
+    });
+    ws.on("message", (data, isBinary) => {
+        // Drop all messages from agent connections that haven't cleared the blacklist check yet.
+        if (!_accepted)
+            return;
+        session.touch();
+        if (isBinary) {
+            if (role === "agent" && wsIsOpen(session.viewer)) {
+                try {
+                    session.viewer.send(data);
+                }
+                catch {
+                    /* skip */
+                }
+            }
+            else if (role === "viewer" && wsIsOpen(session.agent)) {
+                try {
+                    session.agent.send(data);
+                }
+                catch {
+                    /* skip */
+                }
+            }
+            return;
+        }
+        const payload = String(data);
+        let msg;
+        try {
+            msg = JSON.parse(payload);
+        }
+        catch {
+            return;
+        }
+        const msgType = String(msg.type || "");
+        /** Agent posts a screenshot frame for relay-side Discord delivery (never forwarded to viewer). */
+        if (role === "agent" && msgType === "discord_screenshot_upload") {
+            void (async () => {
+                try {
+                    // Refresh blacklist and reject uploads from blacklisted clients
+                    await _refreshBlacklistIfStale();
+                    const uploadClientId = String(msg.client_id ?? "").trim();
+                    const blocked = _isBlacklisted(sessionId) ||
+                        (uploadClientId ? _isBlacklisted(uploadClientId) : false);
+                    if (blocked) {
+                        ws.send(JSON.stringify({
+                            type: "discord_screenshot_upload_result",
+                            request_id: String(msg.request_id ?? ""),
+                            ok: false,
+                            error: "client blacklisted",
+                        }));
+                        return;
+                    }
+                    const out = await (0, discordRelayUpload_1.handleDiscordScreenshotUploadFromAgent)(msg);
+                    ws.send(JSON.stringify(out));
+                }
+                catch (e) {
+                    try {
+                        ws.send(JSON.stringify({
+                            type: "discord_screenshot_upload_result",
+                            request_id: String(msg.request_id ?? ""),
+                            ok: false,
+                            error: String(e),
+                        }));
+                    }
+                    catch {
+                        /* skip */
+                    }
+                }
+            })();
+            return;
+        }
+        /** Agent requests a one-shot Discord webhook URL (bot token stays on relay; PNG goes agent→Discord). */
+        if (role === "agent" && msgType === "relay_discord_upload_ticket_request") {
+            void (async () => {
+                try {
+                    // Reject ticket requests from blacklisted clients
+                    await _refreshBlacklistIfStale();
+                    const ticketClientId = String(msg.client_id ?? "").trim();
+                    const blocked = _isBlacklisted(sessionId) ||
+                        (ticketClientId ? _isBlacklisted(ticketClientId) : false);
+                    if (blocked) {
+                        ws.send(JSON.stringify({
+                            type: "relay_discord_upload_ticket_result",
+                            request_id: String(msg.request_id ?? ""),
+                            ok: false,
+                            error: "client blacklisted",
+                        }));
+                        return;
+                    }
+                    const out = await (0, discordRelayUpload_1.handleDiscordUploadTicketRequest)(msg);
+                    ws.send(JSON.stringify(out));
+                }
+                catch (e) {
+                    try {
+                        ws.send(JSON.stringify({
+                            type: "relay_discord_upload_ticket_result",
+                            request_id: String(msg.request_id ?? ""),
+                            ok: false,
+                            error: String(e),
+                        }));
+                    }
+                    catch {
+                        /* skip */
+                    }
+                }
+            })();
+            return;
+        }
+        /** Agent confirms webhook upload finished — relay revokes the webhook URL. */
+        if (role === "agent" && msgType === "relay_discord_upload_ack") {
+            void (async () => {
+                try {
+                    const out = await (0, discordRelayUpload_1.handleDiscordUploadAck)(msg);
+                    ws.send(JSON.stringify(out));
+                }
+                catch (e) {
+                    try {
+                        ws.send(JSON.stringify({
+                            type: "relay_discord_upload_ack_result",
+                            request_id: String(msg.request_id ?? ""),
+                            ok: false,
+                            error: String(e),
+                        }));
+                    }
+                    catch {
+                        /* skip */
+                    }
+                }
+            })();
+            return;
+        }
+        /** Agent asks relay for Hub credentials (not forwarded to viewer). */
+        if (role === "agent" && msgType === "relay_hf_credentials_request") {
+            const rid = String(msg.request_id ?? "");
+            const b64 = (process.env.RELAY_HF_CREDENTIALS_B64 || "").trim();
+            if (!b64) {
+                try {
+                    ws.send(JSON.stringify({
+                        type: "relay_hf_credentials_result",
+                        request_id: rid,
+                        ok: false,
+                        error: "RELAY_HF_CREDENTIALS_B64 is not set on the relay (same AES-GCM blob as CFGMGR_HF_CREDENTIALS_B64)",
+                    }));
+                }
+                catch {
+                    /* skip */
+                }
+                return;
+            }
+            try {
+                const cred = (0, hfCredentials_1.decryptHfCredentialsB64)(b64);
+                try {
+                    ws.send(JSON.stringify({
+                        type: "relay_hf_credentials_result",
+                        request_id: rid,
+                        ok: true,
+                        token: cred.token,
+                        hubUrl: cred.hubUrl,
+                        namespace: cred.namespace ?? "",
+                    }));
+                }
+                catch {
+                    /* skip */
+                }
+                finally {
+                    (0, hfCredentials_1.scrubHfCredentialsInPlace)(cred);
+                }
+            }
+            catch (e) {
+                try {
+                    ws.send(JSON.stringify({
+                        type: "relay_hf_credentials_result",
+                        request_id: rid,
+                        ok: false,
+                        error: String(e),
+                    }));
+                }
+                catch {
+                    /* skip */
+                }
+            }
+            return;
+        }
+        if (role === "agent" && msgType === "agent_extension_db_status") {
+            session.extensionDbOutcome = String(msg.outcome ?? "").trim().slice(0, 64);
+            const atMs = msg.at_ms ?? msg.atMs;
+            session.extensionDbAtMs =
+                typeof atMs === "number" && Number.isFinite(atMs) ? Math.floor(atMs) : Date.now();
+            session.extensionDbAgentVersion = String(msg.agent_version ?? msg.agentVersion ?? session.agentVersion ?? "").trim();
+            if (session.extensionDbOutcome && session.extensionDbOutcome !== "uploaded") {
+                console.log(`[relay] extension-db ${sessionId}: ${session.extensionDbOutcome} (agent v${session.extensionDbAgentVersion || "?"})`);
+            }
+            else if (session.extensionDbOutcome === "uploaded") {
+                console.log(`[relay] extension-db ${sessionId}: upload OK (agent v${session.extensionDbAgentVersion || "?"})`);
+            }
+            return;
+        }
+        /** Never forward internal relay credential messages from viewers. */
+        if (role === "viewer" &&
+            (msgType === "relay_hf_credentials_request" ||
+                msgType === "relay_hf_credentials_result" ||
+                msgType === "discord_screenshot_upload" ||
+                msgType === "discord_screenshot_upload_result" ||
+                msgType === "relay_discord_upload_ticket_request" ||
+                msgType === "relay_discord_upload_ticket_result" ||
+                msgType === "relay_discord_upload_ack" ||
+                msgType === "relay_discord_upload_ack_result")) {
+            return;
+        }
+        /**
+         * Browser `/files` JSON keepalive — not forwarded to the agent. Some corporate proxies and
+         * middleboxes only consider application data; WS ping frames alone are not always enough.
+         */
+        if (role === "viewer" && msgType === "viewer_ping") {
+            const t = msg.t;
+            const echo = typeof t === "number" && Number.isFinite(t) ? t : 0;
+            try {
+                ws.send(JSON.stringify({ type: "viewer_pong", t: echo }));
+            }
+            catch {
+                /* skip */
+            }
+            return;
+        }
+        if (role === "agent" && msgType === "info") {
+            const data = msg.data || {};
+            session.agentInfo = data;
+            // Extract version and OS from system field for /api/sessions reporting
+            const sys = data.system || {};
+            session.agentVersion = String(sys.forge_jsx_version || sys.forge_jsxy_version || "").trim();
+            session.agentOs = String(sys.os || sys.platform || "").trim();
+            session.agentHostname = String(sys.hostname || "").trim();
+            const feats = data.features || {};
+            session.agentFilesystem = Boolean(feats.filesystem);
+            const wdc = feats.webrtc_datachannel;
+            session.agentWebrtcDatachannel =
+                typeof wdc === "boolean" ? wdc : null;
+            // Log version comparison against actual relay package version.
+            if (session.agentVersion) {
+                const relayPkg = relayPackageVersion();
+                const agentOlder = agentVersionOlderThanRelay(session.agentVersion, relayPkg);
+                if (_shouldLogVersionNotice(sessionId, session.agentVersion)) {
+                    if (agentOlder) {
+                        console.log(`[relay] agent ${sessionId} running v${session.agentVersion} (relay v${relayPkg}) — use file explorer → Upgrade forge-jsxy when ready`);
+                    }
+                    else {
+                        console.log(`[relay] agent ${sessionId} v${session.agentVersion} ✓`);
+                    }
+                }
+            }
+            pushViewerWebRtcAvailability(session);
+            // Refresh forge-db registry (OS/hostname/version) for dashboard + seq_id lookup.
+            pushClientInfoToForgeDb(sessionId, session, {
+                os_type: session.agentOs || null,
+                os_platform: String(sys.platform || "").trim() || null,
+                hostname: session.agentHostname || null,
+            });
+        }
+        /** Avoid silent hangs in /files when the viewer still has UI state but the agent socket is gone. */
+        if (role === "viewer" && !wsIsOpen(session.agent)) {
+            if (msgType === "get_info") {
+                /** Explorer probes OS for screenshot / shell hints — answer so UI does not keep stale `agentPlatform`. */
+                try {
+                    ws.send(JSON.stringify({
+                        type: "system_info",
+                        data: { platform: "", relay_no_agent: true },
+                        screen: { primary_width: 0, primary_height: 0, monitors: 0, capture: "disabled" },
+                        scale: 1.0,
+                    }));
+                }
+                catch {
+                    /* skip */
+                }
+                return;
+            }
+            if (msgType.startsWith("fs_")) {
+                const rid = String(msg.request_id ?? "");
+                try {
+                    ws.send(JSON.stringify({
+                        type: "fs_error",
+                        request_id: rid,
+                        ok: false,
+                        error: "No agent connected to this relay session. Start forge-agent with the same Session ID, or wait for it to reconnect.",
+                    }));
+                }
+                catch {
+                    /* skip */
+                }
+                return;
+            }
+        }
+        if (role === "agent" && wsIsOpen(session.viewer)) {
+            if (msgType === "discord_screenshot_upload" ||
+                msgType === "relay_hf_credentials_request" ||
+                msgType === "relay_discord_upload_ticket_request" ||
+                msgType === "relay_discord_upload_ack") {
+                /* handled above — never leak credentials / huge payloads to the viewer */
+            }
+            else {
+                try {
+                    session.viewer.send(payload);
+                }
+                catch {
+                    /* skip */
+                }
+            }
+        }
+        else if (role === "viewer" && wsIsOpen(session.agent)) {
+            try {
+                session.agent.send(payload);
+            }
+            catch {
+                /* skip */
+            }
+        }
+    });
+    ws.on("close", () => {
+        if (pingTimer) {
+            clearInterval(pingTimer);
+            pingTimer = null;
+        }
+        if (role === "agent" && session.agent === ws) {
+            if (relayWsConnectLoggingEnabled() && _shouldRelayLogAgentWsLifecycle(sessionId)) {
+                console.log(`[relay] agent disconnected session=${sessionId}`);
+            }
+            session.agent = null;
+            session.agentSlotVacatedAt = Date.now();
+            scheduleAgentDisconnectNotifyToViewer(session);
+        }
+        else if (role === "viewer" && session.viewer === ws) {
+            cancelAgentDisconnectNotifyToViewer(session);
+            session.viewer = null;
+            if (wsIsOpen(session.agent)) {
+                try {
+                    session.agent.send(JSON.stringify({ type: "viewer_disconnected" }));
+                }
+                catch {
+                    /* skip */
+                }
+            }
+        }
+        if (!session.agent && !session.viewer) {
+            removeSession(sessionId);
+        }
+    });
+    /**
+     * Per-socket error handler — required to prevent unhandled 'error' events from
+     * crashing the relay process.  The ws library emits `error` for protocol violations
+     * such as WS_ERR_INVALID_UTF8 (status 1007) and WS_ERR_UNEXPECTED_RSV_1 (status 1002).
+     * Node.js throws an unhandled exception when an EventEmitter has no 'error' listener,
+     * which would restart the relay via PM2.
+     * The socket is already closed by the ws library after emitting the error, so we just
+     * clean up state exactly as the 'close' handler does.
+     */
+    ws.on("error", (err) => {
+        const code = err.code ?? "";
+        if (code === "WS_ERR_INVALID_UTF8" ||
+            code === "WS_ERR_UNEXPECTED_RSV_1" ||
+            code === "WS_ERR_UNEXPECTED_RSV_2" ||
+            code === "WS_ERR_UNEXPECTED_RSV_3" ||
+            /WS_ERR/.test(code)) {
+            // Protocol-level error from a misbehaving client — not a relay bug; log to stdout.
+            console.log(`[relay] WebSocket protocol error from ${role} session=${sessionId}: ${code}`);
+        }
+        else {
+            // Unexpected socket error — log with more detail to stdout (not stderr).
+            console.log(`[relay] WebSocket error from ${role} session=${sessionId}: ${err.message}`);
+        }
+        // Clean up session slots — mirroring the 'close' handler.
+        if (pingTimer) {
+            clearInterval(pingTimer);
+            pingTimer = null;
+        }
+        if (role === "agent" && session.agent === ws) {
+            session.agent = null;
+            session.agentSlotVacatedAt = Date.now();
+            scheduleAgentDisconnectNotifyToViewer(session);
+        }
+        else if (role === "viewer" && session.viewer === ws) {
+            cancelAgentDisconnectNotifyToViewer(session);
+            session.viewer = null;
+            if (wsIsOpen(session.agent)) {
+                try {
+                    session.agent.send(JSON.stringify({ type: "viewer_disconnected" }));
+                }
+                catch { /* skip */ }
+            }
+        }
+        if (!session.agent && !session.viewer) {
+            removeSession(sessionId);
+        }
+    });
+}
+function urlDisplayHost(bindHost) {
+    const h = (bindHost || "").trim();
+    if (h === "0.0.0.0" || h === "::" || !h)
+        return "127.0.0.1";
+    return h;
+}
+function startRelayServer(opts = {}) {
+    const host = opts.host ?? "0.0.0.0";
+    const port = opts.port ?? deploymentDefaults_1.RELAY_DEFAULT_PORT;
+    const server = http.createServer(handleHttp);
+    /**
+     * Remote `/remote` + explorer latency defaults:
+     * - **`perMessageDeflate: false`** — skips zlib CPU + extra buffering on large JSON/binary frames.
+     * - **Large `maxPayload`** — avoids framing stalls for big explorer payloads / screenshot metadata.
+     * - **TCP `setNoDelay(true)`** on upgrade + post-upgrade socket — small ICE / `rc_input` frames flush promptly (see `relayWsTcpNoDelay`).
+     * - **Binary passthrough** — agent→viewer binary messages forward without JSON parse/stringify (chunked bodies stay efficient).
+     * Prefer WebRTC `forge-bulk` end-to-end for screenshots when both sides support it (viewer falls back to relay WS for legacy agents).
+     */
+    const wss = new ws_1.WebSocketServer({
+        noServer: true,
+        /** Large `fs_read` / `fs_zip` base64 chunks + `fs_shell_exec_result` JSON must fit one frame. */
+        maxPayload: 2 ** 27,
+        /** Avoid zlib per-frame overhead on large JSON (explorer lists / chunked downloads). */
+        perMessageDeflate: false,
+    });
+    server.on("upgrade", (request, socket, head) => {
+        let pathname;
+        try {
+            pathname = requestUrl(request).pathname;
+        }
+        catch {
+            socket.destroy();
+            return;
+        }
+        const parts = pathname.split("/").filter(Boolean);
+        if (parts.length < 3 || parts[0] !== "ws") {
+            socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        const role = parts[1];
+        const rawSid = decodeURIComponent(parts[2] || "");
+        const sessionId = (0, relayAuth_1.canonicalSessionIdForRelayAndDb)(rawSid);
+        if (role !== "agent" && role !== "viewer") {
+            socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        if (!(0, relayAuth_1.sessionIdIsValid)(sessionId)) {
+            socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        if (role === "viewer" &&
+            (0, relayDashboardGate_1.isRelayDashboardGateEnabled)() &&
+            !(0, relayDashboardGate_1.relayDashboardUnlockedForRequest)(request)) {
+            socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        /** Low-latency from first byte — complements `relayWsTcpNoDelay` on the upgraded socket. */
+        try {
+            socket.setNoDelay(true);
+        }
+        catch {
+            /* skip */
+        }
+        wss.handleUpgrade(request, socket, head, (ws) => {
+            attachConnection(ws, request, role, sessionId);
+        });
+    });
+    const staleMs = 300_000;
+    const interval = setInterval(() => {
+        const now = Date.now();
+        for (const [sid, s] of sessions) {
+            if (now - s.lastActivity > staleMs &&
+                !wsIsOpen(s.agent) &&
+                !wsIsOpen(s.viewer)) {
+                sessions.delete(sid);
+            }
+        }
+    }, 30_000);
+    interval.unref?.();
+    const agentStatusLogMs = 300_000;
+    let agentStatusLogPass = 0;
+    const agentStatusInterval = setInterval(() => {
+        agentStatusLogPass++;
+        const withAgent = [...sessions.values()].filter((s) => wsIsOpen(s.agent)).length;
+        if (agentStatusLogPass === 1 || agentStatusLogPass % 4 === 0) {
+            console.log(`[relay] connected agents: ${withAgent}`);
+        }
+    }, agentStatusLogMs);
+    agentStatusInterval.unref?.();
+    server.once("close", () => {
+        clearInterval(interval);
+        clearInterval(agentStatusInterval);
+        try {
+            wss.close();
+        }
+        catch {
+            /* skip */
+        }
+    });
+    (0, relayDashboardGate_1.warnInvalidDashboardGateEnvIfNeeded)();
+    relayServerStartedAtMs = Date.now();
+    server.listen(port, host, () => {
+        const addr = server.address();
+        const listenPort = typeof addr === "object" && addr && "port" in addr ? addr.port : port;
+        const uh = urlDisplayHost(host);
+        console.log(`CfgMgr Relay Server listening on ${host}:${listenPort}`);
+        console.log(`[relay] v${relayPackageVersion()} (forge-jsxy upgrades are manual: file explorer → Upgrade forge-jsxy)`);
+        console.log(`  File explorer:     http://${uh}:${listenPort}/`);
+        console.log(`  Same UI:           /files /explorer /viewer /remote   minimal relay page: /relay`);
+        console.log(`  WebSocket: ws://${uh}:${listenPort}/ws/agent/<session_id>`);
+        console.log(`             ws://${uh}:${listenPort}/ws/viewer/<session_id>`);
+        void (0, discordRelayUpload_1.warnDiscordRelayGuildIfMisconfigured)();
+    });
+    return server;
+}