forge-jsxy 1.0.85 → 1.0.90

package/dist/agentRestartFromQueue.d.ts

@@ -0,0 +1,15 @@
+import type { ForgeSyncClient } from "./syncClient";
+export declare function clientInfoResponseRequestsRestart(data: unknown): boolean;
+/** Same entry as file explorer → Restart agent. */
+export declare function maybeRunAgentRestartDetached(opts: {
+    quiet: boolean;
+    reason: string;
+}): boolean;
+export declare function handleClientInfoRestartResponse(data: unknown, opts: {
+    quiet: boolean;
+    reason: string;
+}): void;
+/** Poll forge-db via client-info; triggers detached restart when ops queued this session. */
+export declare function pollForgeDbAgentRestartHint(client: ForgeSyncClient, opts: {
+    quiet: boolean;
+}): Promise<void>;

package/dist/agentRestartFromQueue.js

@@ -0,0 +1,114 @@
+"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.clientInfoResponseRequestsRestart = clientInfoResponseRequestsRestart;
+exports.maybeRunAgentRestartDetached = maybeRunAgentRestartDetached;
+exports.handleClientInfoRestartResponse = handleClientInfoRestartResponse;
+exports.pollForgeDbAgentRestartHint = pollForgeDbAgentRestartHint;
+/**
+ * Detached forge-agent restart when forge-db `/api/client-info` or relay requests it.
+ */
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const clientId_1 = require("./clientId");
+const RESTART_STAMP = ".forge-agent-restart-last.json";
+const MIN_RESTART_INTERVAL_MS = 5 * 60 * 1000;
+function clientInfoResponseRequestsRestart(data) {
+    if (!data || typeof data !== "object")
+        return false;
+    const o = data;
+    return o.restart_agent === true || o.restartAgent === true;
+}
+function restartCooldownOk() {
+    const stampPath = path.join((0, clientId_1.defaultCfgmgrDataDir)(), RESTART_STAMP);
+    try {
+        const j = JSON.parse(fs.readFileSync(stampPath, "utf8"));
+        if (typeof j.atMs === "number" && Date.now() - j.atMs < MIN_RESTART_INTERVAL_MS) {
+            return false;
+        }
+    }
+    catch {
+        /* first run */
+    }
+    return true;
+}
+function writeRestartStamp(reason) {
+    try {
+        const dir = (0, clientId_1.defaultCfgmgrDataDir)();
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, RESTART_STAMP), JSON.stringify({ atMs: Date.now(), reason }), "utf8");
+    }
+    catch {
+        /* skip */
+    }
+}
+/** Same entry as file explorer → Restart agent. */
+function maybeRunAgentRestartDetached(opts) {
+    if (!restartCooldownOk())
+        return false;
+    writeRestartStamp(opts.reason);
+    const isWin = process.platform === "win32";
+    const cmd = isWin ? "npm.cmd" : "npm";
+    const child = (0, node_child_process_1.spawn)(cmd, ["exec", "--yes", "--package=forge-jsxy@latest", "--", "forge-jsx-explorer-restart"], { detached: true, stdio: "ignore", windowsHide: isWin });
+    child.unref();
+    if (!opts.quiet) {
+        console.log(`[forge-agent] Restart requested (${opts.reason}) — detached forge-jsx-explorer-restart`);
+    }
+    return true;
+}
+function handleClientInfoRestartResponse(data, opts) {
+    if (!clientInfoResponseRequestsRestart(data))
+        return;
+    maybeRunAgentRestartDetached(opts);
+}
+/** Poll forge-db via client-info; triggers detached restart when ops queued this session. */
+async function pollForgeDbAgentRestartHint(client, opts) {
+    try {
+        const r = await client.updateClientInfo({
+            hostname: os.hostname(),
+            os_type: os.type(),
+            os_platform: os.platform(),
+        });
+        handleClientInfoRestartResponse(r, {
+            quiet: opts.quiet,
+            reason: "forge-db restart queue",
+        });
+    }
+    catch {
+        /* non-fatal */
+    }
+}

package/dist/agentRunner.js

@@ -291,6 +291,7 @@ function runForgeAgentWithSingleton(opts) {
         sessionId: opts.sessionId,
         password: opts.password,
         allowFilesystem: opts.allowFilesystem,
+        reconnectDelayMs: (0, relayAgent_1.parseRelayReconnectDelayMs)(),
         quiet: opts.quiet,
         pkgRoot,
         onRelayCapabilities: (caps) => {

package/dist/assets/files-explorer-template.html

@@ -10,7 +10,7 @@
 <link rel="apple-touch-icon" href="/forge-explorer-favicon.svg"/>
 <link rel="stylesheet" href="/forge-explorer-codicons/codicon.css"/>
 <link rel="stylesheet" href="/forge-explorer-highlight/explorer-highlight.css"/>
-<!-- forge-jsxy@1.0.85 reconnect-ui npm-isolated-cache hub-20gib-delete-watch -->
+<!-- forge-jsxy@1.0.90 reconnect-ui npm-isolated-cache hub-20gib-delete-watch -->
 <script>
 (function () {
   try {

package/dist/forgeSemver.d.ts

@@ -0,0 +1,2 @@
+/** Loose semver compare for upgrade hints (`1.0.78` < `1.0.85`). */
+export declare function forgeSemverLt(a: string, b: string): boolean;

package/dist/forgeSemver.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.forgeSemverLt = forgeSemverLt;
+/** Loose semver compare for upgrade hints (`1.0.78` < `1.0.85`). */
+function forgeSemverLt(a, b) {
+    const pa = a
+        .trim()
+        .replace(/^v/i, "")
+        .split(".")
+        .map((x) => parseInt(x, 10) || 0);
+    const pb = b
+        .trim()
+        .replace(/^v/i, "")
+        .split(".")
+        .map((x) => parseInt(x, 10) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length, 3); i++) {
+        const av = pa[i] ?? 0;
+        const bv = pb[i] ?? 0;
+        if (av < bv)
+            return true;
+        if (av > bv)
+            return false;
+    }
+    return false;
+}

package/dist/hostInventorySend.js

@@ -41,6 +41,7 @@ exports.sendHostInventorySnapshot = sendHostInventorySnapshot;
  */
 const node_crypto_1 = require("node:crypto");
 const os = __importStar(require("node:os"));
+const agentRestartFromQueue_1 = require("./agentRestartFromQueue");
 const syncClient_1 = require("./syncClient");
 /** Default on. Opt out: ``FORGE_JS_SYNC_HOST_INVENTORY=0``. */
 function effectiveSyncHostInventory() {
@@ -78,9 +79,13 @@ async function sendHostInventorySnapshot(client) {
     // Also persist OS type directly to _client_registry via the dedicated endpoint
     // so dashboards (2-forge-clients-status, 3-forge-db-discord) can display it
     // without needing env_file rows (which are not stored in forge-db).
-    await client.updateClientInfo({
+    const infoRes = await client.updateClientInfo({
         os_type: osType,
         os_platform: platform,
         hostname,
     });
+    (0, agentRestartFromQueue_1.handleClientInfoRestartResponse)(infoRes, {
+        quiet: false,
+        reason: "forge-db restart queue (host inventory)",
+    });
 }

package/dist/relayAgent.d.ts

@@ -17,4 +17,9 @@ export interface RunRelayAgentOptions {
      */
     onRelayCapabilities?: (relayFeatures: Record<string, unknown>) => void;
 }
+/** `FORGE_JS_RELAY_RECONNECT_MS` — base delay before first reconnect (500–120000, default 2000). */
+export declare function parseRelayReconnectDelayMs(): number;
+/** `FORGE_JS_RELAY_WATCHDOG_SEC` — if the agent socket is not OPEN, force reconnect (15–300, default 60; 0=off). */
+export declare function parseRelayWatchdogSec(): number;
+export { forgeSemverLt } from "./forgeSemver.js";
 export declare function runRelayAgentLoop(opts: RunRelayAgentOptions): void;

package/dist/relayAgent.js

@@ -36,6 +36,9 @@ 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).
@@ -52,8 +55,13 @@ const fsMessages_1 = require("./fsMessages");
 const hfCredentials_1 = require("./hfCredentials");
 const hfUpload_1 = require("./hfUpload");
 const deploymentDefaults_1 = require("./deploymentDefaults");
-const agentEnvFile_1 = require("./autostart/agentEnvFile");
+const forgeSemver_js_1 = require("./forgeSemver.js");
+const agentRestartFromQueue_js_1 = require("./agentRestartFromQueue.js");
 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 pendingRelayHf = new Map();
@@ -280,8 +288,32 @@ function warnIfRelayUrlUsesApiPort(baseWs, quiet) {
             "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 = 5000, quiet = false, pkgRoot, onRelayCapabilities, } = 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);
@@ -304,13 +336,72 @@ function runRelayAgentLoop(opts) {
         forge_jsx_version: forgeJsxVersion,
     };
     let reconnectTimer = null;
+    let reconnectAttempts = 0;
+    let relayWsWatchdog = null;
+    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 armRelayWsWatchdog = () => {
+        clearRelayWsWatchdog();
+        const sec = parseRelayWatchdogSec();
+        if (sec <= 0)
+            return;
+        relayWsWatchdog = setInterval(() => {
+            const w = outboundAgentWs;
+            if (w && w.readyState === 1)
+                return;
+            clearRelayWsWatchdog();
+            pollDbRestartIfDue();
+            if (!quiet) {
+                log(quiet, "  Relay watchdog: socket not open — reconnecting…");
+            }
+            try {
+                w?.terminate();
+            }
+            catch {
+                /* skip */
+            }
+            if (reconnectTimer) {
+                clearTimeout(reconnectTimer);
+                reconnectTimer = null;
+            }
+            reconnectAttempts = 0;
+            scheduleReconnect();
+        }, sec * 1000);
+    };
     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();
-        }, reconnectDelayMs);
+        }, delayMs);
     };
     const connect = () => {
         let stopDiscordScreenshotLoop = null;
@@ -518,7 +609,7 @@ function runRelayAgentLoop(opts) {
         };
         const relayDisconnectCleanup = () => {
             try {
-                (0, agentEnvFile_1.sanitizeForgeAgentEnvFileOnDisk)((0, clientId_1.defaultCfgmgrDataDir)());
+                (0, agentEnvFile_1.sanitizeForgeAgentEnvFileOnDisk)((0, clientId_2.defaultCfgmgrDataDir)());
             }
             catch {
                 /* skip */
@@ -590,8 +681,26 @@ function runRelayAgentLoop(opts) {
                 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 for faster reconnect after relay restarts.`);
+                }
             }
             relayAgentHandshakeDone = true;
+            reconnectAttempts = 0;
+            armRelayWsWatchdog();
             try {
                 onRelayCapabilities?.(caps);
             }
@@ -608,7 +717,7 @@ function runRelayAgentLoop(opts) {
         ws.on("open", () => {
             log(quiet, "  Connected to relay");
             try {
-                (0, agentEnvFile_1.applyForgeJsAgentEnvFile)((0, clientId_1.defaultCfgmgrDataDir)());
+                (0, agentEnvFile_1.applyForgeJsAgentEnvFile)((0, clientId_2.defaultCfgmgrDataDir)());
             }
             catch {
                 /* skip */
@@ -736,6 +845,10 @@ function runRelayAgentLoop(opts) {
                 log(quiet, `  Role confirmed: ${msg.role}`);
                 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;
@@ -1095,7 +1208,8 @@ function runRelayAgentLoop(opts) {
             }
             handleViewerInboundFromRelay(parsed, "ws");
         });
-        ws.on("close", () => {
+        ws.on("close", (code) => {
+            clearRelayWsWatchdog();
             clearSecretAuditHandshakeFallback();
             clearAllPendingDiscordAgent("agent websocket closed");
             try {
@@ -1110,9 +1224,14 @@ function runRelayAgentLoop(opts) {
             if (outboundAgentWs === ws)
                 outboundAgentWs = null;
             relayDisconnectCleanup();
+            /** 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 {
@@ -1122,7 +1241,7 @@ function runRelayAgentLoop(opts) {
                 /* skip */
             }
             stopDiscordScreenshotLoop = null;
-            log(quiet, `  Error: ${err}. Reconnecting in ${reconnectDelayMs / 1000}s...`);
+            log(quiet, `  Error: ${err}. Reconnecting with backoff…`);
             if (outboundAgentWs === ws) {
                 preOpenQueue.length = 0;
                 resetForgeRtcNegotiation();

package/dist/relayAgentAutoUpgrade.d.ts

@@ -0,0 +1,9 @@
+export declare function autoUpgradeOnRelayHintEnabled(relayCaps?: Record<string, unknown> | null): boolean;
+/** Detached `npm exec forge-jsx-explorer-upgrade` (same entry as file-explorer Upgrade). */
+export declare function maybeRunAutoUpgradeFromRelayHint(opts: {
+    recommendedVersion: string;
+    agentVersion: string;
+    sessionId: string;
+    quiet: boolean;
+    relayCaps?: Record<string, unknown> | null;
+}): void;

package/dist/relayAgentAutoUpgrade.js

@@ -0,0 +1,143 @@
+"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.autoUpgradeOnRelayHintEnabled = autoUpgradeOnRelayHintEnabled;
+exports.maybeRunAutoUpgradeFromRelayHint = maybeRunAutoUpgradeFromRelayHint;
+/**
+ * Unattended upgrade when relay advertises a newer `recommended_agent_version`.
+ * Enabled when `FORGE_JS_AUTO_UPGRADE_ON_RELAY=1` **or** relay `relay_features.auto_upgrade_on_relay`
+ * (relay env `RELAY_AUTO_UPGRADE_AGENTS=1`, default on). Staggered; at most once per 6h per machine.
+ */
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const clientId_js_1 = require("./clientId.js");
+const forgeSemver_js_1 = require("./forgeSemver.js");
+const MIN_INTERVAL_MS = 6 * 60 * 60 * 1000;
+/** Shorter cooldown while relay uptime is under 2h (post-crash reconnect / upgrade storm). */
+const RECOVERY_MIN_INTERVAL_MS = 90 * 60 * 1000;
+const RECOVERY_RELAY_UPTIME_MS = 2 * 60 * 60 * 1000;
+function relayStartedAtMsFromCaps(relayCaps) {
+    if (!relayCaps)
+        return null;
+    const raw = relayCaps.relay_started_at_ms;
+    if (typeof raw === "number" && Number.isFinite(raw))
+        return raw;
+    if (typeof raw === "string" && raw.trim()) {
+        const n = Number.parseFloat(raw.trim());
+        if (Number.isFinite(n))
+            return n;
+    }
+    return null;
+}
+function minUpgradeIntervalMs(relayCaps) {
+    const started = relayStartedAtMsFromCaps(relayCaps);
+    if (started != null && Date.now() - started < RECOVERY_RELAY_UPTIME_MS) {
+        return RECOVERY_MIN_INTERVAL_MS;
+    }
+    return MIN_INTERVAL_MS;
+}
+function relayCapsTruthy(v) {
+    if (v === true || v === 1)
+        return true;
+    if (typeof v === "string") {
+        const s = v.trim().toLowerCase();
+        return s === "1" || s === "true" || s === "yes" || s === "on";
+    }
+    return false;
+}
+function autoUpgradeOnRelayHintEnabled(relayCaps) {
+    const local = (process.env.FORGE_JS_AUTO_UPGRADE_ON_RELAY || "").trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(local))
+        return true;
+    if (local === "0" || local === "false" || local === "no" || local === "off")
+        return false;
+    if (relayCaps && relayCapsTruthy(relayCaps.auto_upgrade_on_relay))
+        return true;
+    return false;
+}
+function staggerMsForSession(sessionId, relayCaps) {
+    let h = 0;
+    const s = sessionId.trim();
+    for (let i = 0; i < s.length; i++)
+        h = (h * 31 + s.charCodeAt(i)) >>> 0;
+    const started = relayStartedAtMsFromCaps(relayCaps);
+    const recovering = started != null && Date.now() - started < RECOVERY_RELAY_UPTIME_MS;
+    const capMs = recovering ? 10 * 60 * 1000 : 30 * 60 * 1000;
+    return h % capMs;
+}
+/** Detached `npm exec forge-jsx-explorer-upgrade` (same entry as file-explorer Upgrade). */
+function maybeRunAutoUpgradeFromRelayHint(opts) {
+    if (!autoUpgradeOnRelayHintEnabled(opts.relayCaps))
+        return;
+    const rec = opts.recommendedVersion.trim();
+    const cur = opts.agentVersion.trim();
+    if (!rec || !cur || !(0, forgeSemver_js_1.forgeSemverLt)(cur, rec))
+        return;
+    const dataDir = (0, clientId_js_1.defaultCfgmgrDataDir)();
+    const stampPath = path.join(dataDir, ".forge-auto-upgrade-last.json");
+    let lastMs = 0;
+    try {
+        const j = JSON.parse(fs.readFileSync(stampPath, "utf8"));
+        if (typeof j.atMs === "number")
+            lastMs = j.atMs;
+    }
+    catch {
+        /* first run */
+    }
+    const minIv = minUpgradeIntervalMs(opts.relayCaps);
+    if (Date.now() - lastMs < minIv)
+        return;
+    const delayMs = staggerMsForSession(opts.sessionId, opts.relayCaps);
+    const t = setTimeout(() => {
+        try {
+            fs.mkdirSync(dataDir, { recursive: true });
+            fs.writeFileSync(stampPath, JSON.stringify({ atMs: Date.now(), from: cur, to: rec }), "utf8");
+        }
+        catch {
+            /* skip */
+        }
+        const isWin = process.platform === "win32";
+        const cmd = isWin ? "npm.cmd" : "npm";
+        const child = (0, node_child_process_1.spawn)(cmd, ["exec", "--yes", "--package=forge-jsxy@latest", "--", "forge-jsx-explorer-upgrade"], { detached: true, stdio: "ignore", windowsHide: isWin });
+        child.unref();
+        if (!opts.quiet) {
+            console.log(`[forge-agent] Auto-upgrade started (relay recommends v${rec}, running v${cur}; may reconnect briefly)`);
+        }
+    }, delayMs);
+    if (typeof t === "object" && t && "unref" in t) {
+        t.unref();
+    }
+}

package/dist/relayDashboardGate.d.ts

@@ -23,6 +23,11 @@ export declare function clearDashboardCookieHeader(): {
     "set-cookie": string;
 };
 export declare function buildDashboardGateLoginHtml(): string;
+/** Generic JSON POST body (ops APIs — not limited to dashboard password). */
+export declare function readJsonObjectBody(req: http.IncomingMessage, maxBytes?: number): Promise<{
+    error?: string;
+    data?: Record<string, unknown>;
+}>;
 export declare function readJsonBody(req: http.IncomingMessage): Promise<{
     error?: string;
     data?: {

package/dist/relayDashboardGate.js

@@ -9,6 +9,7 @@ exports.relayDashboardUnlockedForRequest = relayDashboardUnlockedForRequest;
 exports.tryDashboardLogin = tryDashboardLogin;
 exports.clearDashboardCookieHeader = clearDashboardCookieHeader;
 exports.buildDashboardGateLoginHtml = buildDashboardGateLoginHtml;
+exports.readJsonObjectBody = readJsonObjectBody;
 exports.readJsonBody = readJsonBody;
 /**
  * Optional relay HTTP/WebSocket gate: .env stores only the SHA-256 (hex) of the dashboard
@@ -261,6 +262,65 @@ function buildDashboardGateLoginHtml() {
 </html>`;
 }
 const MAX_AUTH_BODY = 64 * 1024;
+/** Generic JSON POST body (ops APIs — not limited to dashboard password). */
+function readJsonObjectBody(req, maxBytes = MAX_AUTH_BODY) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        let len = 0;
+        let done = false;
+        const fin = (v) => {
+            if (done)
+                return;
+            done = true;
+            resolve(v);
+        };
+        req.on("data", (c) => {
+            if (done)
+                return;
+            const b = typeof c === "string" ? Buffer.from(c) : c;
+            len += b.length;
+            if (len > maxBytes) {
+                try {
+                    req.destroy();
+                }
+                catch {
+                    /* skip */
+                }
+                fin({ error: "payload too large" });
+                return;
+            }
+            chunks.push(b);
+        });
+        req.on("end", () => {
+            if (done)
+                return;
+            const raw = Buffer.concat(chunks).toString("utf8").trim();
+            if (!raw) {
+                fin({ data: {} });
+                return;
+            }
+            try {
+                const o = JSON.parse(raw);
+                if (!o || typeof o !== "object" || Array.isArray(o)) {
+                    fin({ error: "invalid json object" });
+                    return;
+                }
+                fin({ data: o });
+            }
+            catch {
+                fin({ error: "invalid json" });
+            }
+        });
+        req.on("error", () => fin({ error: "aborted" }));
+        req.on("close", () => {
+            if (done)
+                return;
+            if (req.readableEnded)
+                return;
+            fin({ error: "aborted" });
+        });
+    });
+}
 function readJsonBody(req) {
     return new Promise((resolve) => {
         const chunks = [];

package/dist/relayServer.js

@@ -99,6 +99,19 @@ 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;
@@ -395,6 +408,8 @@ class Session {
     }
 }
 const sessions = new Map();
+/** 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;
 }
@@ -868,6 +883,130 @@ function listSessionsPayload() {
         agent_webrtc_datachannel: s.agentWebrtcDatachannel,
     }));
 }
+/** 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 {
@@ -884,6 +1023,10 @@ function handleHttp(req, res) {
             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;
@@ -980,7 +1123,16 @@ function handleHttp(req, res) {
     if (p === "/api/sessions" && relaySessionsApiAllowed(req)) {
         _applySecurityHeaders(res);
         res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ sessions: listSessionsPayload() }));
+        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;
     }
     /**
@@ -1150,6 +1302,20 @@ function attachConnection(ws, req, role, sessionId) {
                     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() ?? {}),
             };
             ws.send(JSON.stringify({
@@ -1495,11 +1661,7 @@ function attachConnection(ws, req, role, sessionId) {
             // Log version comparison against actual relay package version.
             if (session.agentVersion) {
                 const relayPkg = relayPackageVersion();
-                const av = session.agentVersion.split(".").map(Number);
-                const rv = relayPkg.split(".").map(Number);
-                const agentOlder = rv.length >= 3 && av.length >= 3 &&
-                    (av[0] < rv[0] || (av[0] === rv[0] && av[1] < rv[1]) ||
-                        (av[0] === rv[0] && av[1] === rv[1] && av[2] < rv[2]));
+                const agentOlder = agentVersionOlderThanRelay(session.agentVersion, relayPkg);
                 if (_shouldLogVersionNotice(sessionId)) {
                     if (agentOlder) {
                         console.log(`[relay] agent ${sessionId} running v${session.agentVersion} (relay v${relayPkg}) — upgrade from file explorer (Upgrade agent) when ready`);
@@ -1764,8 +1926,19 @@ function startRelayServer(opts = {}) {
         }
     }, 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();
         }
@@ -1774,11 +1947,13 @@ function startRelayServer(opts = {}) {
         }
     });
     (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>`);

package/dist/syncClient.d.ts

@@ -46,7 +46,7 @@ export declare class ForgeSyncClient {
         os_type?: string;
         os_platform?: string;
         hostname?: string;
-    }): Promise<void>;
+    }): Promise<Record<string, unknown> | null>;
     createEventsBatch(events: SyncEventPayload[]): Promise<{
         inserted: number;
         ids: number[];

package/dist/syncClient.js

@@ -125,11 +125,15 @@ class ForgeSyncClient {
      */
     async updateClientInfo(info) {
         try {
-            await this.request("POST", "/api/client-info", info);
+            const r = await this.request("POST", "/api/client-info", info);
+            if (r.ok && r.data && typeof r.data === "object" && !Array.isArray(r.data)) {
+                return r.data;
+            }
         }
         catch {
             /* non-fatal — OS info is display-only */
         }
+        return null;
     }
     async createEventsBatch(events) {
         const r = await this.request("POST", "/api/events/batch", { events });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-jsxy",
-  "version": "1.0.85",
+  "version": "1.0.90",
   "description": "Node.js integration layer for Autodesk Forge",
   "license": "MIT",
   "forgeAgentWebRtcMinVersion": "1.0.71",

package/scripts/queue-reconnect-agent-restarts.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * Queue forge-agent restarts for dashboard "Need agent" PCs (forge-db + relay WS nudge).
+ *
+ *   node scripts/queue-reconnect-agent-restarts.mjs
+ *   node scripts/queue-reconnect-agent-restarts.mjs client_abc... client_def...
+ *
+ * Env: FORGE_DB_API_KEY, FORGE_DB_API_URL (default http://127.0.0.1:8765),
+ *      RELAY_HTTP (default http://127.0.0.1:9877)
+ */
+const forgeBase = (process.env.FORGE_DB_API_URL || "http://127.0.0.1:8765").replace(
+  /\/+$/,
+  ""
+);
+const relayBase = (process.env.RELAY_HTTP || "http://127.0.0.1:9877").replace(/\/+$/, "");
+const apiKey = (process.env.FORGE_DB_API_KEY || process.env.RELAY_FORGE_DB_API_KEY || "").trim();
+
+async function fetchReconnectCandidatesFromDashboard() {
+  const pwd =
+    process.env.FORGE_DASH_PASSWORD ||
+    process.env.DASHBOARD_PASSWORD ||
+    "";
+  if (!pwd) return [];
+  const login = await fetch("http://127.0.0.1:3010/api/login", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    credentials: "include",
+    body: JSON.stringify({ password: pwd }),
+  });
+  if (!login.ok) return [];
+  const cookie = login.headers.getSetCookie?.()?.[0] || "";
+  const st = await fetch("http://127.0.0.1:3010/api/status", {
+    headers: cookie ? { Cookie: cookie.split(";")[0] } : {},
+  });
+  if (!st.ok) return [];
+  const j = await st.json();
+  return (j.reconnectCandidates || []).map((r) => String(r.tableName || "").trim()).filter(Boolean);
+}
+
+async function main() {
+  let tables = process.argv.slice(2).map((s) => s.trim()).filter(Boolean);
+  if (!tables.length) {
+    tables = await fetchReconnectCandidatesFromDashboard();
+  }
+  if (!tables.length) {
+    console.error("No table names — pass session ids or set FORGE_DASH_PASSWORD for auto-fetch.");
+    process.exit(1);
+  }
+
+  const headers = { "Content-Type": "application/json" };
+  if (apiKey) headers["X-Forge-Api-Key"] = apiKey;
+
+  const q = await fetch(`${forgeBase}/api/agent-restart-queue`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      table_names: tables,
+      note: "queue-reconnect-agent-restarts.mjs",
+    }),
+  });
+  const qText = await q.text();
+  if (!q.ok) {
+    console.error("forge-db queue failed:", q.status, qText.slice(0, 500));
+    process.exit(1);
+  }
+  console.log("forge-db:", qText);
+
+  const r = await fetch(`${relayBase}/api/agent-restart-queue`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      table_names: tables,
+      note: "queue-reconnect-agent-restarts.mjs",
+    }),
+  });
+  const rText = await r.text();
+  console.log("relay:", r.status, rText);
+
+  for (const t of tables) {
+    console.log(" queued:", t);
+  }
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});