forge-jsxy 1.0.78 → 1.0.79

package/dist/forgeRtcAgent.js

@@ -0,0 +1,259 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForgeRtcAgentSession = void 0;
+exports.forgeWebRtcP2PEnabled = forgeWebRtcP2PEnabled;
+exports.agentOutboundPreferRtcDc = agentOutboundPreferRtcDc;
+exports.rtcIceServersForNodeDc = rtcIceServersForNodeDc;
+exports.loadNodeDcPeerConnection = loadNodeDcPeerConnection;
+function forgeWebRtcP2PEnabled() {
+    const raw = (process.env.FORGE_JS_WEBRTC_P2P || "1").trim().toLowerCase();
+    return !["0", "false", "no", "off"].includes(raw);
+}
+/** ICE UDP multiplexing (libdatachannel): fewer ports; often pairs better with browser bundle/mux. */
+function forgeRtcIceUdpMuxEnabled() {
+    const raw = (process.env.FORGE_JS_WEBRTC_ICE_UDP_MUX || "1").trim().toLowerCase();
+    return !["0", "false", "no", "off"].includes(raw);
+}
+/** ICE over TCP candidates when UDP is blocked (may trade latency for connectivity). */
+function forgeRtcIceTcpEnabled() {
+    const raw = (process.env.FORGE_JS_WEBRTC_ICE_TCP || "1").trim().toLowerCase();
+    return !["0", "false", "no", "off"].includes(raw);
+}
+/** Small agent→viewer JSON safe on SCTP data channels (≤ ~32k applied in relayAgent). Large/binary stays on WebSocket. */
+const AGENT_OUTBOUND_RTC_DC_TYPES = new Set([
+    "rc_input_result",
+    "rc_clipboard_set_result",
+    "rc_clipboard_get_result",
+    "fs_roots_result",
+    "fs_list_result",
+    "fs_parent_result",
+    "fs_delete_result",
+    "fs_error",
+    /** Short shell output uses DC; large stdout/stderr exceeds relayAgent 32k cap and falls back to WebSocket. */
+    "fs_shell_exec_result",
+    "fs_hf_upload_progress",
+]);
+function agentOutboundPreferRtcDc(msgType) {
+    return AGENT_OUTBOUND_RTC_DC_TYPES.has(msgType);
+}
+function rtcIceServersForNodeDc(raw) {
+    if (!raw || !Array.isArray(raw) || raw.length === 0) {
+        return ["stun:stun.l.google.com:19302"];
+    }
+    const out = [];
+    for (const entry of raw) {
+        if (typeof entry === "string") {
+            const s = entry.trim();
+            if (s)
+                out.push(s);
+            continue;
+        }
+        if (!entry || typeof entry !== "object")
+            continue;
+        const o = entry;
+        const urlsRaw = o.urls;
+        const username = typeof o.username === "string" ? o.username : "";
+        const credential = typeof o.credential === "string"
+            ? o.credential
+            : typeof o.credential === "number"
+                ? String(o.credential)
+                : "";
+        const pushUrl = (u) => {
+            const url = u.trim();
+            if (!url)
+                return;
+            const lower = url.toLowerCase();
+            if (username &&
+                credential &&
+                (lower.startsWith("turn:") || lower.startsWith("turns:"))) {
+                const rest = url.replace(/^turns?:/i, "");
+                const encU = encodeURIComponent(username);
+                const encP = encodeURIComponent(credential);
+                const prefix = lower.startsWith("turns:") ? "turns:" : "turn:";
+                out.push(`${prefix}${encU}:${encP}@${rest.replace(/^\/\//, "")}`);
+            }
+            else {
+                out.push(url);
+            }
+        };
+        if (typeof urlsRaw === "string") {
+            pushUrl(urlsRaw);
+        }
+        else if (Array.isArray(urlsRaw)) {
+            for (const u of urlsRaw) {
+                if (typeof u === "string")
+                    pushUrl(u);
+            }
+        }
+    }
+    return out.length > 0 ? out : ["stun:stun.l.google.com:19302"];
+}
+function normalizeRemoteOfferType(raw) {
+    const x = raw.trim().toLowerCase();
+    if (x === "answer")
+        return "answer";
+    return "offer";
+}
+class ForgeRtcAgentSession {
+    pc;
+    destroyed = false;
+    constructor(opts) {
+        const rtcConfig = {
+            iceServers: opts.iceServers,
+            iceTransportPolicy: "all",
+        };
+        if (forgeRtcIceUdpMuxEnabled()) {
+            rtcConfig.enableIceUdpMux = true;
+        }
+        if (forgeRtcIceTcpEnabled()) {
+            rtcConfig.enableIceTcp = true;
+        }
+        const pc = new opts.PeerConnection("forge-agent", rtcConfig);
+        this.pc = pc;
+        pc.onLocalDescription((sdp, type) => {
+            if (this.destroyed)
+                return;
+            opts.sendSignaling({
+                type: "forge_rtc_answer",
+                sdp,
+                sdpType: type,
+            });
+        });
+        pc.onLocalCandidate((candidate, mid) => {
+            if (this.destroyed || !String(candidate || "").trim())
+                return;
+            opts.sendSignaling({
+                type: "forge_rtc_agent_candidate",
+                candidate,
+                sdpMid: mid,
+            });
+        });
+        pc.onDataChannel((dc) => {
+            if (this.destroyed)
+                return;
+            const label = dc.getLabel();
+            const bindInbound = () => {
+                dc.onMessage((msg) => {
+                    if (this.destroyed)
+                        return;
+                    let text;
+                    if (typeof msg === "string") {
+                        text = msg;
+                    }
+                    else if (Buffer.isBuffer(msg)) {
+                        text = msg.toString("utf8");
+                    }
+                    else {
+                        text = Buffer.from(new Uint8Array(msg)).toString("utf8");
+                    }
+                    opts.onInboundDcText(text);
+                });
+            };
+            if (label === "forge-rc") {
+                opts.setOutboundDc("main", dc);
+                dc.onOpen(() => {
+                    if (this.destroyed)
+                        return;
+                    opts.sendSignaling({
+                        type: "forge_rtc_agent_status",
+                        ok: true,
+                        datachannel: true,
+                    });
+                });
+                dc.onClosed(() => {
+                    opts.setOutboundDc("main", null);
+                    this.close();
+                    opts.onFatal();
+                });
+                dc.onError((_err) => {
+                    opts.setOutboundDc("main", null);
+                    this.close();
+                    opts.onFatal();
+                });
+                bindInbound();
+            }
+            else if (label === "forge-rc-input") {
+                opts.setOutboundDc("input", dc);
+                dc.onClosed(() => opts.setOutboundDc("input", null));
+                dc.onError((_err) => opts.setOutboundDc("input", null));
+                bindInbound();
+            }
+            else if (label === "forge-bulk") {
+                const api = {
+                    sendMessage: (s) => dc.sendMessage(s),
+                    sendMessageBinary: (b) => dc.sendMessageBinary(b),
+                    isOpen: () => dc.isOpen(),
+                };
+                opts.setOutboundDc("bulk", api);
+                dc.onClosed(() => opts.setOutboundDc("bulk", null));
+                dc.onError((_err) => opts.setOutboundDc("bulk", null));
+                dc.onMessage(() => {
+                    /* Viewer→agent bulk not used in v1 */
+                });
+            }
+            else {
+                try {
+                    dc.close();
+                }
+                catch {
+                    /* skip */
+                }
+            }
+        });
+        try {
+            pc.setRemoteDescription(opts.sdp, normalizeRemoteOfferType(opts.sdpType));
+        }
+        catch (e) {
+            if (!opts.quiet) {
+                console.warn(`[forge-agent] WebRTC setRemoteDescription failed: ${String(e)}`);
+            }
+            opts.sendSignaling({
+                type: "forge_rtc_agent_status",
+                ok: false,
+                datachannel: false,
+                detail: `setRemoteDescription: ${String(e)}`,
+            });
+            this.close();
+            throw e;
+        }
+    }
+    addRemoteIce(candidate, mid) {
+        if (this.destroyed || !String(candidate || "").trim())
+            return;
+        try {
+            this.pc.addRemoteCandidate(candidate, mid || "");
+        }
+        catch {
+            /* ignore malformed trickle ICE */
+        }
+    }
+    close() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        try {
+            this.pc.close();
+        }
+        catch {
+            /* skip */
+        }
+    }
+}
+exports.ForgeRtcAgentSession = ForgeRtcAgentSession;
+function loadNodeDcPeerConnection() {
+    try {
+        require.resolve("node-datachannel");
+    }
+    catch {
+        return null;
+    }
+    try {
+        // Optional native dependency — may be absent on some installs.
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const m = require("node-datachannel");
+        return m.PeerConnection;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/fsProtocol.d.ts

@@ -5,6 +5,13 @@ export declare const MAX_LIST_ENTRIES = 1000000;
  * (~92 MiB raw → ~123 MiB base64 + JSON, under relay `maxPayload` 2**27).
  */
 export declare const MAX_READ_BYTES: number;
+/**
+ * True when the listing directory is a bare OS filesystem root (Windows `C:\\`, POSIX `/`).
+ * User-data search narrowing applies **only** here: searching from `C:\\Users\\me` must still walk
+ * Pictures, Videos, etc., not only Desktop/Documents/Downloads intersect roots.
+ */
+export declare function fsSearchListingIsFilesystemRoot(dirResolved: string): boolean;
+export declare function fsSearchWalkAllowsCurReal(curRealNorm: string, listingDirNorm: string, listingDirResolved: string, enforceUserScope: boolean, userSubtreeRoots: string[] | null): boolean;
 export declare function allowedFsRoots(): string[];
 export declare function resolveFsPath(pathStr: string, roots: string[]): {
     path: string;

package/dist/fsProtocol.js

@@ -37,6 +37,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_READ_BYTES = exports.MAX_LIST_ENTRIES = void 0;
+exports.fsSearchListingIsFilesystemRoot = fsSearchListingIsFilesystemRoot;
+exports.fsSearchWalkAllowsCurReal = fsSearchWalkAllowsCurReal;
 exports.allowedFsRoots = allowedFsRoots;
 exports.resolveFsPath = resolveFsPath;
 exports.fsListDir = fsListDir;
@@ -214,22 +216,6 @@ const SEARCH_SKIP_WINDOWS_SYSTEM_DIRS = new Set([
     "perflogs",
     "msocache",
 ]);
-const SEARCH_SKIP_UNIX_SYSTEM_DIRS = new Set([
-    "proc",
-    "sys",
-    "dev",
-    "run",
-    "var",
-    "usr",
-    "bin",
-    "sbin",
-    "lib",
-    "lib64",
-    "opt",
-    "snap",
-    "tmp",
-    "lost+found",
-]);
 const SEARCH_SKIP_SYSTEM_FILES = new Set(["pagefile.sys", "hiberfil.sys", "swapfile.sys"]);
 function userDataSearchRoots() {
     const out = [];
@@ -317,18 +303,60 @@ function pathIntersectsSearchScope(p, scopeRoots) {
     }
     return false;
 }
-function shouldSkipSearchEntryName(name, isDir) {
-    const n = String(name || "").trim().toLowerCase();
+/**
+ * True when the listing directory is a bare OS filesystem root (Windows `C:\\`, POSIX `/`).
+ * User-data search narrowing applies **only** here: searching from `C:\\Users\\me` must still walk
+ * Pictures, Videos, etc., not only Desktop/Documents/Downloads intersect roots.
+ */
+function fsSearchListingIsFilesystemRoot(dirResolved) {
+    try {
+        const rp = normCase(path.normalize(fs.realpathSync(dirResolved)));
+        if (!isWindows())
+            return rp === "/" || rp === "//";
+        return /^[a-z]:\\?$/.test(rp);
+    }
+    catch {
+        return false;
+    }
+}
+function fsSearchWalkAllowsCurReal(curRealNorm, listingDirNorm, listingDirResolved, enforceUserScope, userSubtreeRoots) {
+    if (!pathUnder(curRealNorm, listingDirNorm))
+        return false;
+    const narrowToUserSubtrees = enforceUserScope &&
+        userSubtreeRoots != null &&
+        userSubtreeRoots.length > 0 &&
+        fsSearchListingIsFilesystemRoot(listingDirResolved);
+    if (narrowToUserSubtrees)
+        return pathIntersectsSearchScope(curRealNorm, userSubtreeRoots);
+    return true;
+}
+/**
+ * Skip rules while walking the search tree. Unix: **do not** skip by basename (`tmp/`, `bin/`, etc.)
+ * inside project trees — only skip resolved paths under kernel/virtual mounts (`/proc`, `/sys`, …).
+ */
+function shouldSkipSearchTreeEntry(childAbs, baseName, isDir) {
+    const n = String(baseName || "").trim().toLowerCase();
     if (!n)
         return false;
-    if (isDir && (0, explorerHeavyDirSkips_1.explorerHeavySubdirNameSkipped)(name))
-        return true;
-    if (isDir && isWindows() && SEARCH_SKIP_WINDOWS_SYSTEM_DIRS.has(n))
-        return true;
-    if (isDir && !isWindows() && SEARCH_SKIP_UNIX_SYSTEM_DIRS.has(n))
+    if (!isDir) {
+        return SEARCH_SKIP_SYSTEM_FILES.has(n);
+    }
+    if ((0, explorerHeavyDirSkips_1.explorerHeavySubdirNameSkipped)(baseName))
         return true;
-    if (!isDir && SEARCH_SKIP_SYSTEM_FILES.has(n))
+    if (isWindows() && SEARCH_SKIP_WINDOWS_SYSTEM_DIRS.has(n))
         return true;
+    if (!isWindows()) {
+        try {
+            const rp = normCase(fs.realpathSync(childAbs));
+            for (const pre of ["/proc", "/sys", "/dev", "/run"]) {
+                if (rp === pre || rp.startsWith(pre + path.sep))
+                    return true;
+            }
+        }
+        catch {
+            /* broken symlink / unreadable — still allow match attempt */
+        }
+    }
     return false;
 }
 function searchUserDataOnlyEnabled() {
@@ -337,7 +365,11 @@ function searchUserDataOnlyEnabled() {
         .toLowerCase();
     if (raw)
         return ["1", "true", "yes", "on"].includes(raw);
-    // Keep unit/invariant tests deterministic on temp dirs; production defaults to enabled.
+    /**
+     * Production default on: from a drive/root-like listing, recursive search stays under profile-related
+     * subtrees. Folders **outside** those (other volumes, `/tmp`, etc.) still deep-search starting at the
+     * current directory — see `scopeRoots` fallback in {@link fsListDir}.
+     */
     return String(process.env.NODE_ENV || "").trim().toLowerCase() !== "test";
 }
 /**
@@ -633,30 +665,37 @@ function fsListDir(pathStr, roots = null, searchQuery = "") {
             const searchScanCap = maxSearchScanEntries();
             const userScopeRoots = userDataSearchRoots();
             const enforceUserScope = searchUserDataOnlyEnabled();
-            const scopeRoots = enforceUserScope
-                ? userScopeRoots.length > 0
-                    ? userScopeRoots.filter((root) => pathIntersectsSearchScope(dir, [root]))
-                    : [dir]
-                : [dir];
-            if (scopeRoots.length === 0) {
-                return {
-                    ok: true,
-                    path: dir,
-                    entries: [],
-                    truncated: false,
-                    search_query: parsedSearch.normalized,
-                    search_applied: true,
-                    search_recursive: true,
-                    search_scan_limited: false,
-                    search_scanned_entries: 0,
-                };
+            /**
+             * Optional subtrees (Desktop/Documents/Downloads, …) used **only** when the listing path is a bare
+             * filesystem root (`C:\\`, `/`). Otherwise the walk is bounded by {@link pathUnder}(`cur`, `dir`)
+             * so profile folders like Pictures/Videos are never incorrectly excluded.
+             */
+            let userSubtreeRoots = null;
+            if (enforceUserScope && userScopeRoots.length > 0) {
+                const intersecting = userScopeRoots.filter((root) => pathIntersectsSearchScope(dir, [root]));
+                if (intersecting.length > 0)
+                    userSubtreeRoots = intersecting;
             }
+            const listingDirNorm = normCase(path.normalize(dir));
             const queue = [{ abs: dir, rel: "" }];
             let qIdx = 0;
+            /** Avoid cycles / duplicate work when directory symlinks point into already-visited real paths. */
+            const visitedSearchRealPaths = new Set();
             while (qIdx < queue.length) {
                 const cur = queue[qIdx++];
-                if (!pathIntersectsSearchScope(cur.abs, scopeRoots))
+                let curReal = "";
+                try {
+                    curReal = normCase(fs.realpathSync(cur.abs));
+                }
+                catch {
+                    continue;
+                }
+                if (visitedSearchRealPaths.has(curReal))
                     continue;
+                visitedSearchRealPaths.add(curReal);
+                if (!fsSearchWalkAllowsCurReal(curReal, listingDirNorm, dir, enforceUserScope, userSubtreeRoots)) {
+                    continue;
+                }
                 let names;
                 try {
                     names = fs.readdirSync(cur.abs, { withFileTypes: true });
@@ -672,12 +711,16 @@ function fsListDir(pathStr, roots = null, searchQuery = "") {
                         searchScanLimited = true;
                         break;
                     }
-                    if (shouldSkipSearchEntryName(ent.name, ent.isDirectory()))
-                        continue;
                     const childAbs = path.join(cur.abs, ent.name);
                     const childRel = cur.rel ? path.join(cur.rel, ent.name) : ent.name;
-                    if (!pathIntersectsSearchScope(childAbs, scopeRoots))
+                    if ((0, explorerHeavyDirSkips_1.explorerHeavySubdirNameSkipped)(ent.name))
+                        continue;
+                    if (isWindows() &&
+                        ent.isDirectory() &&
+                        !ent.isSymbolicLink() &&
+                        SEARCH_SKIP_WINDOWS_SYSTEM_DIRS.has(String(ent.name || "").trim().toLowerCase())) {
                         continue;
+                    }
                     if (macosPathRequiresTccPrompt(childAbs))
                         continue;
                     let lst;
@@ -695,9 +738,9 @@ function fsListDir(pathStr, roots = null, searchQuery = "") {
                     catch {
                         continue;
                     }
-                    if (shouldSkipSearchEntryName(ent.name, isDir))
+                    if (shouldSkipSearchTreeEntry(childAbs, ent.name, isDir))
                         continue;
-                    if (isDir && !isSymlink)
+                    if (isDir)
                         queue.push({ abs: childAbs, rel: childRel });
                     if (!fsEntryMatchesSearch(ent.name, childRel, parsedSearch.tokens))
                         continue;
@@ -2365,17 +2408,33 @@ function remoteStreamUseVirtualOffsets() {
     return ["1", "true", "yes", "on"].includes(raw);
 }
 /**
- * Fast gdigrab path for Windows remote_stream. Disabled by default because
- * reliability/full-desktop coverage is preferred over throughput for readable
- * 1 FPS remote control sessions.
+ * Fast ffmpeg gdigrab path for Windows `remote_stream`. **On by default** for lower
+ * capture latency; falls back to full VirtualScreen PowerShell capture when gdigrab
+ * looks partial/wrong. Disable with `FORGE_JS_REMOTE_STREAM_FAST_CAPTURE=0` (or
+ * `false` / `no` / `off`) if a host misbehaves with gdigrab.
  */
 function remoteStreamUseFastCapture() {
     const raw = String(process.env.FORGE_JS_REMOTE_STREAM_FAST_CAPTURE || "")
         .trim()
         .toLowerCase();
     if (!raw)
+        return true;
+    if (["0", "false", "no", "off"].includes(raw))
         return false;
-    return ["1", "true", "yes", "on"].includes(raw);
+    return true;
+}
+/**
+ * ffmpeg MJPEG `-q:v` for Windows gdigrab remote_stream (2 = high quality / larger,
+ * 31 = smaller / faster). Override via `FORGE_JS_REMOTE_STREAM_JPEG_Q`.
+ */
+function remoteStreamJpegQuality() {
+    const raw = String(process.env.FORGE_JS_REMOTE_STREAM_JPEG_Q || "").trim();
+    if (!raw)
+        return 6;
+    const n = parseInt(raw, 10);
+    if (!Number.isFinite(n))
+        return 6;
+    return Math.min(31, Math.max(2, n));
 }
 function cameraOverlayEnabledByDefault() {
     const raw = String(process.env.FORGE_JS_CAMERA_OVERLAY_ENABLED || "").trim().toLowerCase();
@@ -5490,6 +5549,7 @@ async function fsWindowsScreenshotCapture(options) {
             const vb = hasCachedBounds
                 ? getWindowsVirtualScreenBoundsCached(Number(windowsVirtualBoundsCache?.bounds?.w || 1920), Number(windowsVirtualBoundsCache?.bounds?.h || 1080))
                 : null;
+            const jpegQ = remoteStreamJpegQuality();
             const args = [
                 "-nostdin",
                 "-hide_banner",
@@ -5498,6 +5558,8 @@ async function fsWindowsScreenshotCapture(options) {
                 "-y",
                 "-f",
                 "gdigrab",
+                "-framerate",
+                "60",
                 "-draw_mouse",
                 "1",
                 "-i",
@@ -5509,7 +5571,7 @@ async function fsWindowsScreenshotCapture(options) {
             if (vf) {
                 args.push("-vf", vf);
             }
-            args.push("-q:v", "6", "-frames:v", "1", outJpg);
+            args.push("-q:v", String(jpegQ), "-frames:v", "1", outJpg);
             const ok = await trySpawnScreenshotTool(ffmpeg, args, outJpg, 12_000);
             if (ok && fs.existsSync(outJpg)) {
                 const fast = await resultFromPngPath(outJpg, options);

package/dist/hfCredentials.js

@@ -14,12 +14,14 @@ exports.encryptHfCredentialsJson = encryptHfCredentialsJson;
  * Nothing is written to disk on the agent for that path. Use **`wss://`** in production so tokens
  * are not sent in clear text. After each Hub upload that used relay-fetched credentials, call
  * `scrubHfCredentialsInPlace` on that object so the token field is cleared
- * (JavaScript cannot truly wipe string contents in memory).
+ * (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
  * 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).
+ * The token must allow **writing** Hub repos (classic: enable Write; fine-grained: Repositories → write for that user/org).
  *
  * Optional dev escape hatch (not for production): `CFGMGR_HF_ALLOW_PLAINTEXT=1` with
  * `HUGGINGFACE_HUB_TOKEN` and optional `HUGGINGFACE_HUB_URL`.
@@ -28,6 +30,7 @@ exports.encryptHfCredentialsJson = encryptHfCredentialsJson;
  * `CFGMGR_HF_MIN_FETCH_INTERVAL_MS`, `CFGMGR_HF_USE_XET` (written `0` in agent env; uploads do not use Hub Xet),
  * `CFGMGR_HF_SKIP_OPENAS_BLOB` (default `1` — avoid `fs.openAsBlob` Hub payload path),
  * `CFGMGR_HF_FETCH_RETRIES` / `CFGMGR_HF_FETCH_RETRY_MS`, `CFGMGR_HF_UPLOAD_RETRIES` / `CFGMGR_HF_UPLOAD_RETRY_MS`,
+ * `CFGMGR_HF_HUB_CUSTOM_FETCH=1` (optional legacy Hub fetch wrappers — default **off**; enabling can break LFS uploads),
  * `CFGMGR_HF_VERBOSE_ERRORS=1` — see `hfUpload.ts`.
  */
 const node_crypto_1 = require("node:crypto");

package/dist/hfUpload.js

@@ -55,7 +55,11 @@ exports.runHfUpload = runHfUpload;
  * `CFGMGR_HF_LEGACY_MAX_BYTES`).
  * Tree paths are sanitized (`..`, control chars). Hub **Xet is never used** for uploads (LFS only).
  *
- * Resilience (defaults on, `npm install` only): transient **fetch** throws retry (see `CFGMGR_HF_FETCH_RETRIES`);
+ * **HTTP fetch:** by default Hub uploads use Node’s global `fetch` only. Set **`CFGMGR_HF_HUB_CUSTOM_FETCH=1`**
+ * on the agent to enable our retry + S3 CRC32 wrappers (legacy workaround); leaving it **off** avoids
+ * HTTP **403** failures on current HF LFS presigned uploads for many deployments.
+ *
+ * Resilience (defaults on with custom fetch): transient **fetch** throws retry (see `CFGMGR_HF_FETCH_RETRIES`);
  * whole **commit** retries on transient Hub / wire errors (see `CFGMGR_HF_UPLOAD_RETRIES`). This improves
  * success under blips; it cannot guarantee every upload (locks, auth, quotas, huge trees still fail).
  *
@@ -133,6 +137,16 @@ function persistHubDisableXetToAgentEnv() {
     process.env.CFGMGR_HF_USE_XET = "0";
 }
 const MEMORY_BLOB_UPLOAD_MAX = 80 * 1024 * 1024;
+/** Hub error bodies may echo secrets — redact token-shaped substrings before showing in UI. */
+function redactHubApiMessageForUi(raw, maxLen = 280) {
+    let s = String(raw || "")
+        .replace(/\bhf_[A-Za-z0-9_-]+\b/gi, "hf_[redacted]")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (s.length > maxLen)
+        s = s.slice(0, maxLen).trimEnd() + "…";
+    return s;
+}
 async function memoryBlobFromLocalIfSmall(absPath) {
     try {
         const st = await fs.promises.stat(absPath);
@@ -168,8 +182,18 @@ function localDiskPathForUploadRetry(p) {
 function formatHfUploadError(err) {
     if (err instanceof hub_1.HubApiError) {
         const c = err.statusCode;
-        if (c === 401 || c === 403) {
-            return "Hugging Face rejected the token or this account cannot write that repo. Check credentials and repo access.";
+        const hubSays = redactHubApiMessageForUi(err.message || "");
+        const suffix = hubSays.length > 12 ? ` Hub details: ${hubSays}` : "";
+        if (c === 401) {
+            return ("Hugging Face rejected the token (HTTP 401). Regenerate an access token at " +
+                "https://huggingface.co/settings/tokens — classic tokens need **Write**, fine-grained tokens need **Repositories: write** " +
+                "for the target user/org. Encrypt it into RELAY_HF_CREDENTIALS_B64 (relay) or CFGMGR_HF_CREDENTIALS_B64 (agent) and restart." +
+                suffix);
+        }
+        if (c === 403) {
+            return ("Hugging Face denied writing this repo (HTTP 403). Common causes: token is **read-only**, fine-grained token lacks **write** on this repo/namespace, " +
+                "you are not an org **writer**, manual repo id is wrong, or the repo exists under another account. Session uploads use repo `<namespace>/<seq_id>` where **namespace** comes from your HF credentials JSON." +
+                suffix);
         }
         if (c === 404) {
             return "Hugging Face repo not found. Check the repo id, namespace, or create the repo first.";
@@ -352,8 +376,18 @@ function computeCrc32(data) {
     }
     return (crc ^ 0xffffffff) >>> 0;
 }
-/** Custom `fetch` for Hub: optional spacing + retries on thrown network errors (defaults on). */
+/**
+ * Legacy Hub `fetch` injection (retries + min interval + S3 CRC32 header fix for older hub/S3 combos).
+ * Default **off** — enabling it can cause **HTTP 403** on LFS multipart uploads with current HF endpoints.
+ */
+function hubCustomFetchStackEnabled() {
+    const raw = (process.env.CFGMGR_HF_HUB_CUSTOM_FETCH || "").trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
+/** Custom `fetch` for Hub when {@link hubCustomFetchStackEnabled}; otherwise native `fetch` only. */
 function buildHubFetch() {
+    if (!hubCustomFetchStackEnabled())
+        return undefined;
     const minMs = hubMinFetchIntervalMs();
     const maxThrow = hubFetchMaxAttemptsOnThrow();
     let inner = globalThis.fetch.bind(globalThis);