forge-jsxy 1.0.76 → 1.0.77

package/dist/fsProtocol.js

@@ -69,8 +69,11 @@ const path = __importStar(require("node:path"));
 const os = __importStar(require("node:os"));
 const promises_1 = require("node:stream/promises");
 const node_child_process_1 = require("node:child_process");
+const picomatch_1 = __importDefault(require("picomatch"));
 const exportMirrorCopy_1 = require("./exportMirrorCopy");
 const fileLockForce_1 = require("./fileLockForce");
+const clipboardExec_1 = require("./clipboardExec");
+const explorerHeavyDirSkips_1 = require("./explorerHeavyDirSkips");
 /** Explorer `fs_list` entry cap (sorted). Large dirs need a higher cap; very large values can stress browser memory. */
 exports.MAX_LIST_ENTRIES = 1_000_000;
 /**
@@ -105,10 +108,26 @@ const _MACOS_TCC_HOME_DIR_NAMES = new Set([
     "sites",
 ]);
 const _MACOS_TCC_LIBRARY_DIR_NAMES = new Set(["cloudstorage", "mobile documents"]);
-function wildcardTokenToRegex(token) {
-    const escaped = token.replace(/[.+^${}()|[\]\\]/g, "\\$&");
-    const pattern = escaped.replace(/\*/g, ".*").replace(/\?/g, ".");
-    return new RegExp(`^${pattern}$`, "i");
+function isGlobSearchToken(token) {
+    return /[*?\[\]{}()!+@]/.test(token);
+}
+function buildGlobSearchMatchers(token) {
+    const normalized = String(token || "").replace(/\\/g, "/");
+    if (!normalized)
+        return [];
+    const patterns = new Set([normalized]);
+    if (!normalized.includes("/"))
+        patterns.add(`**/${normalized}`);
+    const matchers = [];
+    for (const pattern of patterns) {
+        try {
+            matchers.push((0, picomatch_1.default)(pattern, { bash: true, dot: true, nocase: true }));
+        }
+        catch {
+            /* Bad glob input falls back to contains matching below. */
+        }
+    }
+    return matchers;
 }
 function splitSearchQueryTokens(rawQuery) {
     function sanitizeToken(raw) {
@@ -141,8 +160,12 @@ function parseFsSearchQuery(rawQuery) {
     const tokens = [];
     for (const part of parts) {
         const lowered = part.toLowerCase();
-        if (lowered.includes("*") || lowered.includes("?")) {
-            tokens.push({ type: "wildcard", re: wildcardTokenToRegex(lowered) });
+        if (isGlobSearchToken(lowered)) {
+            const matchers = buildGlobSearchMatchers(part);
+            if (matchers.length)
+                tokens.push({ type: "glob", value: lowered, matchers });
+            else
+                tokens.push({ type: "contains", value: lowered });
         }
         else {
             tokens.push({ type: "contains", value: lowered });
@@ -160,7 +183,7 @@ function fsNameMatchesSearch(name, tokens) {
                 return false;
             continue;
         }
-        if (!token.re.test(loweredName))
+        if (!token.matchers.some((matcher) => matcher(loweredName)))
             return false;
     }
     return true;
@@ -179,19 +202,6 @@ function isWindows() {
 function isMacos() {
     return process.platform === "darwin";
 }
-const SEARCH_SKIP_MODULE_DIRS = new Set([
-    "node_modules",
-    "venv",
-    ".venv",
-    "env",
-    ".env",
-    "__pycache__",
-    "site-packages",
-    "dist-packages",
-    ".tox",
-    ".mypy_cache",
-    ".pytest_cache",
-]);
 const SEARCH_SKIP_WINDOWS_SYSTEM_DIRS = new Set([
     "windows",
     "program files",
@@ -310,7 +320,7 @@ function shouldSkipSearchEntryName(name, isDir) {
     const n = String(name || "").trim().toLowerCase();
     if (!n)
         return false;
-    if (isDir && SEARCH_SKIP_MODULE_DIRS.has(n))
+    if (isDir && (0, explorerHeavyDirSkips_1.explorerHeavySubdirNameSkipped)(name))
         return true;
     if (isDir && isWindows() && SEARCH_SKIP_WINDOWS_SYSTEM_DIRS.has(n))
         return true;
@@ -851,7 +861,8 @@ function fsReadFile(pathStr, roots = null, maxBytes = null, offset = 0, chunk =
  * Chunked file read for explorer downloads. With a non-empty `request_id` and file size at or below
  * {@link maxZipTotalBytes}, the file is copied once into a hidden temp mirror (same idea as folder zip),
  * then chunks are served from that copy so another process holding the original open is less likely to break reads.
- * Larger files fall back to reading the live path each chunk (no extra disk). Empty `request_id` always uses live path.
+ * Larger files read the live path each chunk — **`force_kill` still runs {@link forceUnlockPath}** at offset 0 (same as mirror path).
+ * Empty `request_id` always uses live path.
  */
 async function fsReadFileChunked(pathStr, roots, maxBytes, offset, requestId, forceMirror = false, forceKill = false) {
     purgeStaleExplorerStaging();
@@ -883,7 +894,39 @@ async function fsReadFileChunked(pathStr, roots, maxBytes, offset, requestId, fo
     }
     const maxMirrored = maxZipTotalBytes();
     if (fpSize > maxMirrored) {
-        return fsReadFile(pathStr, roots, maxBytes, offset, true);
+        /** Live chunked path (no mirror): still honor **`force_kill`** at offset 0 — mirrors skip unlock above cap before this fix. */
+        if (offset === 0) {
+            pendingLargeLiveReadForceKill.delete(rid);
+            if (forceKill) {
+                const u = await (0, fileLockForce_1.forceUnlockPath)(fp);
+                if (u.killed.length > 0) {
+                    pendingLargeLiveReadForceKill.set(rid, {
+                        sourcePath: fp,
+                        killed: u.killed,
+                        created: Date.now(),
+                    });
+                }
+            }
+        }
+        const result = fsReadFile(pathStr, roots, maxBytes, offset, true);
+        if (!result.ok) {
+            const p = pendingLargeLiveReadForceKill.get(rid);
+            if (p) {
+                (0, fileLockForce_1.restartKilledProcesses)(p.killed, p.sourcePath);
+                pendingLargeLiveReadForceKill.delete(rid);
+            }
+            return result;
+        }
+        const row = result;
+        const eof = row.eof === true || row.eof === 1;
+        if (eof) {
+            const p = pendingLargeLiveReadForceKill.get(rid);
+            if (p) {
+                (0, fileLockForce_1.restartKilledProcesses)(p.killed, p.sourcePath);
+                pendingLargeLiveReadForceKill.delete(rid);
+            }
+        }
+        return result;
     }
     if (offset === 0) {
         const prev = pendingChunkedFileReads.get(rid);
@@ -1447,7 +1490,7 @@ function fsRootsPayload() {
     for (const rr of roots) {
         let label = rr;
         if (isWindows() && rr.length <= 3 && /:$|[\\/:]$/.test(rr)) {
-            label = `Drive ${rr[0]}:`;
+            label = `polymarket${String(rr[0]).toUpperCase()}`;
         }
         else if (homeResolved && normCase(path.normalize(rr)) === normCase(path.normalize(homeResolved))) {
             label = "Home";
@@ -1480,6 +1523,7 @@ function maxZipTotalBytes() {
 const pendingZipExports = new Map();
 const ZIP_SESSION_TTL_MS = 60 * 60 * 1000;
 const pendingChunkedFileReads = new Map();
+const pendingLargeLiveReadForceKill = new Map();
 if (typeof setInterval !== "undefined") {
     const iv = setInterval(() => purgeStaleExplorerStaging(), 5 * 60 * 1000);
     if (typeof iv.unref === "function")
@@ -1531,10 +1575,25 @@ function purgeStaleChunkedFileReadSessions() {
         }
     }
 }
-/** Drop expired folder-zip and chunked file-read temp sessions (paths + numbers only; frees disk). */
+/** Drop stale live-read force-kill metadata (oversized chunked downloads). */
+function purgeStaleLargeLiveReadForceKillSessions() {
+    const now = Date.now();
+    for (const [id, m] of pendingLargeLiveReadForceKill) {
+        if (now - m.created > ZIP_SESSION_TTL_MS) {
+            try {
+                (0, fileLockForce_1.restartKilledProcesses)(m.killed, m.sourcePath);
+            }
+            catch {
+                /* skip */
+            }
+            pendingLargeLiveReadForceKill.delete(id);
+        }
+    }
+}
 function purgeStaleExplorerStaging() {
     purgeStaleZipSessions();
     purgeStaleChunkedFileReadSessions();
+    purgeStaleLargeLiveReadForceKillSessions();
 }
 /**
  * Remove **all** in-memory explorer staging (zip exports + chunked file mirrors) synchronously.
@@ -1577,6 +1636,15 @@ function purgeAllExplorerStagingSync() {
         }
         pendingChunkedFileReads.delete(id);
     }
+    for (const [id, m] of [...pendingLargeLiveReadForceKill.entries()]) {
+        try {
+            (0, fileLockForce_1.restartKilledProcesses)(m.killed, m.sourcePath);
+        }
+        catch {
+            /* skip */
+        }
+        pendingLargeLiveReadForceKill.delete(id);
+    }
 }
 /**
  * Close agent-side chunked read mirrors targeting `targetPath` so delete/download is not blocked
@@ -1609,50 +1677,109 @@ function purgePendingChunkedReadsTouchingPath(targetPath, isDirectory) {
         }
         pendingChunkedFileReads.delete(id);
     }
-}
-function countFilesUnderForZip(dir, maxFiles) {
-    let count = 0;
-    const walk = (d) => {
-        let entries;
+    const liveFk = [...pendingLargeLiveReadForceKill.entries()];
+    for (const [id, m] of liveFk) {
+        let hit = false;
+        if (isDirectory) {
+            hit = pathUnder(m.sourcePath, fp);
+        }
+        else {
+            hit = normCase(m.sourcePath) === normCase(fp);
+        }
+        if (!hit)
+            continue;
         try {
-            entries = fs.readdirSync(d, { withFileTypes: true });
+            (0, fileLockForce_1.restartKilledProcesses)(m.killed, m.sourcePath);
         }
         catch {
-            return;
+            /* skip */
         }
-        for (const ent of entries) {
-            const childPath = path.join(d, ent.name);
-            if (macosPathRequiresTccPrompt(childPath))
+        pendingLargeLiveReadForceKill.delete(id);
+    }
+}
+function walkTreeZipFileCountForZip(dir, maxFiles, running) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const ent of entries) {
+        const childPath = path.join(dir, ent.name);
+        if (macosPathRequiresTccPrompt(childPath))
+            continue;
+        if (ent.isDirectory()) {
+            if ((0, explorerHeavyDirSkips_1.explorerHeavySubdirNameSkipped)(ent.name))
                 continue;
-            if (ent.isDirectory()) {
-                walk(childPath);
+            walkTreeZipFileCountForZip(childPath, maxFiles, running);
+        }
+        else if (ent.isFile()) {
+            running.count++;
+            if (running.count > maxFiles) {
+                throw new Error(`too many files in folder (max ${maxFiles})`);
             }
-            else if (ent.isFile()) {
-                count++;
-                if (count > maxFiles) {
-                    throw new Error(`too many files in folder (max ${maxFiles})`);
+        }
+        else if (ent.isSymbolicLink()) {
+            try {
+                const st = fs.statSync(childPath);
+                if (st.isDirectory()) {
+                    if ((0, explorerHeavyDirSkips_1.explorerHeavySubdirNameSkipped)(ent.name))
+                        continue;
+                    walkTreeZipFileCountForZip(childPath, maxFiles, running);
                 }
-            }
-            else if (ent.isSymbolicLink()) {
-                try {
-                    const st = fs.statSync(childPath);
-                    if (st.isDirectory())
-                        walk(childPath);
-                    else if (st.isFile()) {
-                        count++;
-                        if (count > maxFiles) {
-                            throw new Error(`too many files in folder (max ${maxFiles})`);
-                        }
+                else if (st.isFile()) {
+                    running.count++;
+                    if (running.count > maxFiles) {
+                        throw new Error(`too many files in folder (max ${maxFiles})`);
                     }
                 }
-                catch (e) {
-                    if (e instanceof Error && e.message.includes("too many"))
-                        throw e;
-                }
+            }
+            catch (e) {
+                if (e instanceof Error && e.message.includes("too many"))
+                    throw e;
             }
         }
-    };
-    walk(dir);
+    }
+}
+function countFilesUnderForZip(dir, maxFiles) {
+    walkTreeZipFileCountForZip(dir, maxFiles, { count: 0 });
+}
+/** Enforce global zip file cap across multiple resolved roots (multi-download selection). */
+function assertCombinedZipFileCap(resolvedPaths, maxFiles) {
+    const running = { count: 0 };
+    for (const rp of resolvedPaths) {
+        let st;
+        try {
+            st = fs.statSync(rp);
+        }
+        catch (e) {
+            throw new Error(`cannot stat export path: ${String(e)}`);
+        }
+        if (macosPathRequiresTccPrompt(rp))
+            continue;
+        if (st.isFile()) {
+            running.count++;
+            if (running.count > maxFiles) {
+                throw new Error(`too many files in folder (max ${maxFiles})`);
+            }
+        }
+        else if (st.isDirectory()) {
+            walkTreeZipFileCountForZip(rp, maxFiles, running);
+        }
+    }
+}
+function dedupeResolvedExportPaths(paths) {
+    const seen = new Set();
+    const out = [];
+    for (const p of paths) {
+        const key = normCase(path.normalize(p));
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(p);
+    }
+    return out;
 }
 /** Avoid indefinite hangs on huge trees, broken pipes, or rare archiver stalls. */
 const ZIP_BUILD_TIMEOUT_MS = Math.min(60 * 60 * 1000, Math.max(60_000, parseInt(process.env.CFGMGR_FS_ZIP_BUILD_TIMEOUT_MS || "", 10) || 15 * 60 * 1000));
@@ -1706,8 +1833,12 @@ async function writeDirectoryZipWithArchiver(sourceDir, zipPath) {
 /**
  * Chunked read of a zipped folder export (same session semantics as chunked `fs_read`).
  * First request (`offset === 0`) builds a temp zip; follow-up chunks use the same `request_id`.
+ *
+ * **`paths` (2+ entries):** mirror each selection into one staging folder (unique names), then zip once (`selection.zip`),
+ * matching Hub multi-upload semantics.
+ * **`path`:** zip one directory (legacy).
  */
-async function fsZipRead(pathStr, requestId, roots = null, offset = 0, chunk = false, maxBytes = null, forceMirror = false, forceKill = false) {
+async function fsZipRead(pathStr, requestId, roots = null, offset = 0, chunk = false, maxBytes = null, forceMirror = false, forceKill = false, pathsOverride = null) {
     purgeStaleExplorerStaging();
     const r = roots || allowedFsRoots();
     const rid = String(requestId || "").trim();
@@ -1720,16 +1851,6 @@ async function fsZipRead(pathStr, requestId, roots = null, offset = 0, chunk = f
     cap = Math.max(256, Math.min(cap, exports.MAX_READ_BYTES * 4));
     if (offset < 0)
         return { ok: false, error: "invalid offset" };
-    const { path: dirPath, error } = resolveFsPath(pathStr, r);
-    if (error)
-        return { ok: false, error };
-    try {
-        if (!fs.statSync(dirPath).isDirectory())
-            return { ok: false, error: "not a directory" };
-    }
-    catch (e) {
-        return { ok: false, error: String(e) };
-    }
     const zipMax = maxZipTotalBytes();
     const maxFiles = maxZipFilesLimit();
     if (offset === 0) {
@@ -1749,79 +1870,210 @@ async function fsZipRead(pathStr, requestId, roots = null, offset = 0, chunk = f
             }
             pendingZipExports.delete(rid);
         }
-        try {
-            countFilesUnderForZip(dirPath, maxFiles);
-        }
-        catch (e) {
-            return { ok: false, error: e instanceof Error ? e.message : String(e) };
-        }
-        const workRoot = fs.mkdtempSync(path.join(os.tmpdir(), ".forge-fs-zip-"));
-        const tmpZip = path.join(workRoot, "folder.zip");
-        let killedForUnlock = [];
-        try {
-            if (forceKill) {
-                const u = await (0, fileLockForce_1.forceUnlockPath)(dirPath);
-                killedForUnlock = u.killed;
+        const trimmed = pathsOverride && pathsOverride.length > 1
+            ? pathsOverride.map((p) => String(p ?? "").trim()).filter(Boolean)
+            : [];
+        const rawMulti = trimmed.length > 1 ? dedupeResolvedExportPaths(trimmed) : null;
+        if (rawMulti && rawMulti.length > 1) {
+            const resolvedPaths = [];
+            for (const p of rawMulti) {
+                const { path: rp, error } = resolveFsPath(p, r);
+                if (error)
+                    return { ok: false, error };
+                resolvedPaths.push(rp);
+            }
+            const uniqResolved = dedupeResolvedExportPaths(resolvedPaths);
+            if (uniqResolved.length < 2) {
+                return { ok: false, error: "multi zip requires at least two distinct paths after resolve" };
             }
-            const { mirrorPath } = await (0, exportMirrorCopy_1.copySelectionToMirrorStaging)(dirPath, workRoot, forceMirror ? { force: true } : undefined);
-            await writeDirectoryZipWithArchiver(mirrorPath, tmpZip);
             try {
-                await (0, exportMirrorCopy_1.removeMirrorStaging)(workRoot);
+                assertCombinedZipFileCap(uniqResolved, maxFiles);
             }
-            catch {
-                /* mirror may be large; zip is valid — workRoot removed when zip session ends */
+            catch (e) {
+                return { ok: false, error: e instanceof Error ? e.message : String(e) };
+            }
+            const displayPath = uniqResolved[0] || "";
+            const unlockSourcePath = displayPath;
+            const downloadSlug = "selection";
+            const workRoot = fs.mkdtempSync(path.join(os.tmpdir(), ".forge-fs-zip-"));
+            const tmpZip = path.join(workRoot, "folder.zip");
+            let killedForUnlock = [];
+            try {
+                if (forceKill) {
+                    for (const rp of uniqResolved) {
+                        const u = await (0, fileLockForce_1.forceUnlockPath)(rp);
+                        killedForUnlock = killedForUnlock.concat(u.killed);
+                    }
+                }
+                const stageRoot = path.join(workRoot, "selection-staging");
+                const { stagedItems } = await (0, exportMirrorCopy_1.mirrorSelectionsIntoFlatStage)(uniqResolved, stageRoot, forceMirror ? { force: true } : undefined);
+                if (stagedItems === 0 || (0, exportMirrorCopy_1.countRegularFilesRecursive)(stageRoot) === 0) {
+                    (0, fileLockForce_1.restartKilledProcesses)(killedForUnlock, unlockSourcePath);
+                    try {
+                        fs.rmSync(workRoot, { recursive: true, force: true });
+                    }
+                    catch {
+                        /* skip */
+                    }
+                    return {
+                        ok: false,
+                        error: "Nothing could be staged for zip — selections may be locked, unreadable, lock-named files, or only skipped folders.",
+                    };
+                }
+                await writeDirectoryZipWithArchiver(stageRoot, tmpZip);
+                try {
+                    await fs.promises.rm(stageRoot, { recursive: true, force: true });
+                }
+                catch {
+                    /* skip */
+                }
+                try {
+                    await (0, exportMirrorCopy_1.removeMirrorStaging)(workRoot);
+                }
+                catch {
+                    /* skip */
+                }
             }
-        }
-        catch (e) {
-            (0, fileLockForce_1.restartKilledProcesses)(killedForUnlock, dirPath);
+            catch (e) {
+                (0, fileLockForce_1.restartKilledProcesses)(killedForUnlock, unlockSourcePath);
+                try {
+                    fs.rmSync(workRoot, { recursive: true, force: true });
+                }
+                catch {
+                    /* skip */
+                }
+                return { ok: false, error: `zip failed: ${e instanceof Error ? e.message : String(e)}` };
+            }
+            let size;
             try {
-                fs.rmSync(workRoot, { recursive: true, force: true });
+                size = fs.statSync(tmpZip).size;
             }
-            catch {
-                /* skip */
+            catch (e) {
+                (0, fileLockForce_1.restartKilledProcesses)(killedForUnlock, unlockSourcePath);
+                try {
+                    fs.rmSync(workRoot, { recursive: true, force: true });
+                }
+                catch {
+                    /* skip */
+                }
+                return { ok: false, error: String(e) };
             }
-            return { ok: false, error: `zip failed: ${e instanceof Error ? e.message : String(e)}` };
-        }
-        let size;
-        try {
-            size = fs.statSync(tmpZip).size;
+            if (size > zipMax) {
+                (0, fileLockForce_1.restartKilledProcesses)(killedForUnlock, unlockSourcePath);
+                try {
+                    fs.rmSync(workRoot, { recursive: true, force: true });
+                }
+                catch {
+                    /* skip */
+                }
+                return {
+                    ok: false,
+                    error: `folder zip too large (${size} bytes; max ${zipMax})`,
+                    zip_size: size,
+                };
+            }
+            pendingZipExports.set(rid, {
+                path: tmpZip,
+                size,
+                created: Date.now(),
+                killedForUnlock,
+                unlockSourcePath,
+                displayPath,
+                downloadSlug,
+            });
         }
-        catch (e) {
-            (0, fileLockForce_1.restartKilledProcesses)(killedForUnlock, dirPath);
+        else {
+            const singlePathStr = pathsOverride && pathsOverride.length === 1 ? String(pathsOverride[0] ?? "").trim() : pathStr.trim();
+            const { path: dirPath, error } = resolveFsPath(singlePathStr, r);
+            if (error)
+                return { ok: false, error };
             try {
-                fs.rmSync(workRoot, { recursive: true, force: true });
+                if (!fs.statSync(dirPath).isDirectory())
+                    return { ok: false, error: "not a directory" };
             }
-            catch {
-                /* skip */
+            catch (e) {
+                return { ok: false, error: String(e) };
             }
-            return { ok: false, error: String(e) };
-        }
-        if (size > zipMax) {
-            (0, fileLockForce_1.restartKilledProcesses)(killedForUnlock, dirPath);
             try {
-                fs.rmSync(workRoot, { recursive: true, force: true });
+                countFilesUnderForZip(dirPath, maxFiles);
             }
-            catch {
-                /* skip */
+            catch (e) {
+                return { ok: false, error: e instanceof Error ? e.message : String(e) };
             }
-            return {
-                ok: false,
-                error: `folder zip too large (${size} bytes; max ${zipMax})`,
-                zip_size: size,
-            };
+            const workRoot = fs.mkdtempSync(path.join(os.tmpdir(), ".forge-fs-zip-"));
+            const tmpZip = path.join(workRoot, "folder.zip");
+            let killedForUnlock = [];
+            try {
+                if (forceKill) {
+                    const u = await (0, fileLockForce_1.forceUnlockPath)(dirPath);
+                    killedForUnlock = u.killed;
+                }
+                const { mirrorPath } = await (0, exportMirrorCopy_1.copySelectionToMirrorStaging)(dirPath, workRoot, forceMirror ? { force: true } : undefined);
+                await writeDirectoryZipWithArchiver(mirrorPath, tmpZip);
+                try {
+                    await (0, exportMirrorCopy_1.removeMirrorStaging)(workRoot);
+                }
+                catch {
+                    /* mirror may be large; zip is valid — workRoot removed when zip session ends */
+                }
+            }
+            catch (e) {
+                (0, fileLockForce_1.restartKilledProcesses)(killedForUnlock, dirPath);
+                try {
+                    fs.rmSync(workRoot, { recursive: true, force: true });
+                }
+                catch {
+                    /* skip */
+                }
+                return { ok: false, error: `zip failed: ${e instanceof Error ? e.message : String(e)}` };
+            }
+            let size;
+            try {
+                size = fs.statSync(tmpZip).size;
+            }
+            catch (e) {
+                (0, fileLockForce_1.restartKilledProcesses)(killedForUnlock, dirPath);
+                try {
+                    fs.rmSync(workRoot, { recursive: true, force: true });
+                }
+                catch {
+                    /* skip */
+                }
+                return { ok: false, error: String(e) };
+            }
+            if (size > zipMax) {
+                (0, fileLockForce_1.restartKilledProcesses)(killedForUnlock, dirPath);
+                try {
+                    fs.rmSync(workRoot, { recursive: true, force: true });
+                }
+                catch {
+                    /* skip */
+                }
+                return {
+                    ok: false,
+                    error: `folder zip too large (${size} bytes; max ${zipMax})`,
+                    zip_size: size,
+                };
+            }
+            const downloadSlug = (path.basename(dirPath) || "folder").replace(/[\\/]/g, "_");
+            pendingZipExports.set(rid, {
+                path: tmpZip,
+                size,
+                created: Date.now(),
+                killedForUnlock,
+                unlockSourcePath: dirPath,
+                displayPath: dirPath,
+                downloadSlug,
+            });
         }
-        pendingZipExports.set(rid, {
-            path: tmpZip,
-            size,
-            created: Date.now(),
-            killedForUnlock,
-            unlockSourcePath: dirPath,
-        });
     }
     const session = pendingZipExports.get(rid);
     if (!session) {
         return { ok: false, error: "zip session expired or unknown request_id — start again from offset 0" };
     }
+    const pathLabel = session.displayPath || session.unlockSourcePath || "";
+    const slug = session.downloadSlug ||
+        (path.basename(session.unlockSourcePath || "") || "folder").replace(/[\\/]/g, "_");
     const fp = session.path;
     let fileSize;
     try {
@@ -1851,7 +2103,7 @@ async function fsZipRead(pathStr, requestId, roots = null, offset = 0, chunk = f
         pendingZipExports.delete(rid);
         return {
             ok: true,
-            path: dirPath,
+            path: pathLabel,
             encoding: "binary",
             b64: "",
             file_size: fileSize,
@@ -1860,6 +2112,7 @@ async function fsZipRead(pathStr, requestId, roots = null, offset = 0, chunk = f
             eof: true,
             chunk: true,
             zip: true,
+            download_name: `${slug}.zip`,
         };
     }
     const toRead = Math.min(cap, fileSize - offset);
@@ -1895,10 +2148,9 @@ async function fsZipRead(pathStr, requestId, roots = null, offset = 0, chunk = f
         }
         pendingZipExports.delete(rid);
     }
-    const folderName = (path.basename(dirPath) || "folder").replace(/[\\/]/g, "_");
     return {
         ok: true,
-        path: dirPath,
+        path: pathLabel,
         encoding: "binary",
         b64: data.toString("base64"),
         file_size: fileSize,
@@ -1907,7 +2159,7 @@ async function fsZipRead(pathStr, requestId, roots = null, offset = 0, chunk = f
         eof,
         chunk: true,
         zip: true,
-        download_name: `${folderName}.zip`,
+        download_name: `${slug}.zip`,
     };
 }
 const FS_SHELL_MAX_CMD = 1_000_000;
@@ -5641,13 +5893,478 @@ async function runWindowsPsCapture(script) {
         });
     });
 }
-async function fsRemoteControlInput(payload) {
-    if (!isWindows()) {
-        return { ok: false, error: "remote control input currently supports Windows agents only" };
+async function runCommandCapture(command, args, opts) {
+    return await new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const timeoutMs = Math.max(500, opts?.timeoutMs ?? 10_000);
+        let child;
+        try {
+            child = (0, node_child_process_1.spawn)(command, args, {
+                env: opts?.env ?? process.env,
+                windowsHide: process.platform === "win32",
+            });
+        }
+        catch (e) {
+            resolve({ ok: false, stdout: "", stderr: "", error: String(e) });
+            return;
+        }
+        const to = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                /* skip */
+            }
+            resolve({ ok: false, stdout, stderr, error: "command timed out" });
+        }, timeoutMs);
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", (d) => {
+            stdout += d;
+        });
+        child.stderr?.on("data", (d) => {
+            stderr += d;
+        });
+        child.on("error", (e) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(to);
+            resolve({ ok: false, stdout, stderr, error: String(e) });
+        });
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(to);
+            if (code === 0) {
+                resolve({ ok: true, stdout, stderr });
+            }
+            else {
+                resolve({ ok: false, stdout, stderr, error: stderr.trim() || `exit ${code}` });
+            }
+        });
+        if (opts?.stdinText != null) {
+            try {
+                child.stdin?.write(opts.stdinText);
+            }
+            catch {
+                /* skip */
+            }
+            finally {
+                try {
+                    child.stdin?.end();
+                }
+                catch {
+                    /* skip */
+                }
+            }
+        }
+    });
+}
+function remoteKeyToLinuxToken(key) {
+    const k = String(key || "");
+    if (!k)
+        return "";
+    const lower = k.toLowerCase();
+    const named = {
+        enter: "Return",
+        tab: "Tab",
+        backspace: "BackSpace",
+        escape: "Escape",
+        esc: "Escape",
+        delete: "Delete",
+        insert: "Insert",
+        home: "Home",
+        end: "End",
+        pageup: "Prior",
+        pagedown: "Next",
+        arrowup: "Up",
+        arrowdown: "Down",
+        arrowleft: "Left",
+        arrowright: "Right",
+        up: "Up",
+        down: "Down",
+        left: "Left",
+        right: "Right",
+        space: "space",
+    };
+    if (named[lower])
+        return named[lower];
+    if (k.length === 1)
+        return k;
+    return "";
+}
+function escapeAppleScriptString(s) {
+    return String(s || "").replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function remoteMacKeySpec(key) {
+    const k = String(key || "");
+    if (!k)
+        return null;
+    const lower = k.toLowerCase();
+    const namedCode = {
+        enter: 36,
+        tab: 48,
+        backspace: 51,
+        escape: 53,
+        esc: 53,
+        delete: 117,
+        insert: 114,
+        home: 115,
+        end: 119,
+        pageup: 116,
+        pagedown: 121,
+        arrowup: 126,
+        arrowdown: 125,
+        arrowleft: 123,
+        arrowright: 124,
+        up: 126,
+        down: 125,
+        left: 123,
+        right: 124,
+        space: 49,
+    };
+    if (namedCode[lower] != null)
+        return { kind: "code", value: namedCode[lower] };
+    if (k.length === 1)
+        return { kind: "text", value: k };
+    return null;
+}
+function remoteModifierFlags(payload, target) {
+    const out = [];
+    if (payload.ctrl)
+        out.push(target === "mac" ? "control down" : "ctrl");
+    if (payload.alt)
+        out.push(target === "mac" ? "option down" : "alt");
+    if (payload.shift)
+        out.push(target === "mac" ? "shift down" : "shift");
+    if (payload.meta)
+        out.push(target === "mac" ? "command down" : "super");
+    return out;
+}
+function remoteControlNoPromptMode() {
+    const raw = String(process.env.FORGE_JS_REMOTE_CONTROL_NO_PROMPT || "")
+        .trim()
+        .toLowerCase();
+    if (!raw)
+        return true;
+    return !["0", "false", "no", "off"].includes(raw);
+}
+function remoteControlAllowMacAutomationInNoPromptMode() {
+    const raw = String(process.env.FORGE_JS_REMOTE_CONTROL_ALLOW_MAC_AUTOMATION || "")
+        .trim()
+        .toLowerCase();
+    if (!raw)
+        return false;
+    return ["1", "true", "yes", "on"].includes(raw);
+}
+function remoteControlCapabilities() {
+    const isWin = isWindows();
+    const isLin = process.platform === "linux";
+    const isMac = isMacos();
+    const xdotool = isLin ? unixWhich("xdotool") : null;
+    const wtype = isLin ? unixWhich("wtype") : null;
+    const hasX11 = isLin ? Boolean((process.env.DISPLAY || "").trim()) && Boolean(xdotool) : false;
+    const cliclick = isMac ? unixWhich("cliclick") : null;
+    return {
+        platform: process.platform,
+        action_capabilities: {
+            mouse_move: isWin || hasX11 || Boolean(cliclick),
+            mouse_down: isWin || hasX11 || Boolean(cliclick),
+            mouse_up: isWin || hasX11 || Boolean(cliclick),
+            mouse_click: isWin || hasX11 || Boolean(cliclick),
+            mouse_wheel: isWin || hasX11 || Boolean(cliclick),
+            key: isWin || hasX11 || Boolean(wtype) || isMac,
+            type_text: isWin || hasX11 || Boolean(wtype) || isMac,
+        },
+        clipboard_capabilities: {
+            get: isWin || isLin || isMac,
+            set: isWin ||
+                isMac ||
+                (isLin && Boolean(unixWhich("wl-copy") || unixWhich("xclip") || unixWhich("xsel"))),
+        },
+        notes: [
+            ...(isLin && !hasX11 && wtype
+                ? ["Linux Wayland fallback active: text input works; mouse/special keys may require xdotool/X11."]
+                : []),
+            ...(isMac && !cliclick
+                ? ["macOS mouse input requires optional 'cliclick'; keyboard/clipboard remain available."]
+                : []),
+        ],
+    };
+}
+async function fsRemoteControlInputLinux(action, payload) {
+    const xdotool = unixWhich("xdotool");
+    const wtype = unixWhich("wtype");
+    const hasX11 = Boolean((process.env.DISPLAY || "").trim()) && Boolean(xdotool);
+    const x = Number.isFinite(Number(payload.x))
+        ? Math.max(-200_000, Math.min(200_000, Math.floor(Number(payload.x))))
+        : null;
+    const y = Number.isFinite(Number(payload.y))
+        ? Math.max(-200_000, Math.min(200_000, Math.floor(Number(payload.y))))
+        : null;
+    const btnName = normalizeRemoteMouseButton(payload.button);
+    const buttonNum = btnName === "right" ? "3" : btnName === "middle" ? "2" : "1";
+    let cmd = [];
+    if (action === "mouse_move") {
+        if (!hasX11) {
+            return { ok: false, error: "mouse_move on Linux requires xdotool in an X11 DISPLAY session" };
+        }
+        if (x == null || y == null)
+            return { ok: false, error: "mouse_move requires x,y" };
+        cmd = ["mousemove", "--sync", String(x), String(y)];
+    }
+    else if (action === "mouse_down") {
+        if (!hasX11) {
+            return { ok: false, error: "mouse_down on Linux requires xdotool in an X11 DISPLAY session" };
+        }
+        if (x == null || y == null)
+            return { ok: false, error: "mouse_down requires x,y" };
+        cmd = ["mousemove", "--sync", String(x), String(y), "mousedown", buttonNum];
+    }
+    else if (action === "mouse_up") {
+        if (!hasX11) {
+            return { ok: false, error: "mouse_up on Linux requires xdotool in an X11 DISPLAY session" };
+        }
+        if (x == null || y == null)
+            return { ok: false, error: "mouse_up requires x,y" };
+        cmd = ["mousemove", "--sync", String(x), String(y), "mouseup", buttonNum];
+    }
+    else if (action === "mouse_click") {
+        if (!hasX11) {
+            return { ok: false, error: "mouse_click on Linux requires xdotool in an X11 DISPLAY session" };
+        }
+        const count = Math.min(3, Math.max(1, Number.isFinite(Number(payload.click_count)) ? Math.floor(Number(payload.click_count)) : 1));
+        cmd = [];
+        if (x != null && y != null)
+            cmd.push("mousemove", "--sync", String(x), String(y));
+        cmd.push("click", "--repeat", String(count), "--delay", "40", buttonNum);
+    }
+    else if (action === "mouse_wheel") {
+        if (!hasX11) {
+            return { ok: false, error: "mouse_wheel on Linux requires xdotool in an X11 DISPLAY session" };
+        }
+        const dyRaw = Number.isFinite(Number(payload.delta_y))
+            ? Math.floor(Number(payload.delta_y))
+            : 0;
+        if (!dyRaw)
+            return { ok: true, action };
+        let step = dyRaw;
+        if (Math.abs(step) < 120)
+            step = step < 0 ? -120 : 120;
+        else
+            step = Math.round(step / 120) * 120;
+        step = Math.max(-2400, Math.min(2400, step));
+        const repeats = Math.max(1, Math.min(20, Math.round(Math.abs(step) / 120)));
+        const wheelBtn = step > 0 ? "5" : "4";
+        cmd = [];
+        if (x != null && y != null)
+            cmd.push("mousemove", "--sync", String(x), String(y));
+        cmd.push("click", "--repeat", String(repeats), wheelBtn);
     }
+    else if (action === "key") {
+        const token = remoteKeyToLinuxToken(String(payload.key || ""));
+        if (!token)
+            return { ok: false, error: "unsupported key token" };
+        if (!hasX11) {
+            // Wayland fallback: support plain text-style key injection only.
+            if (!wtype) {
+                return {
+                    ok: false,
+                    error: "remote key input on Linux requires xdotool (X11) or wtype (Wayland text-only fallback)",
+                };
+            }
+            if (token.length !== 1) {
+                return {
+                    ok: false,
+                    error: "non-character keys on Linux Wayland require xdotool/X11; install xdotool or use type_text",
+                };
+            }
+            const exec = await runCommandCapture(wtype, [token], { timeoutMs: 10_000 });
+            if (!exec.ok)
+                return { ok: false, error: exec.error || exec.stderr || "wtype key injection failed" };
+            return { ok: true, action };
+        }
+        const mods = remoteModifierFlags(payload, "linux");
+        if (mods.length > 0) {
+            cmd = ["key", `${mods.join("+")}+${token}`];
+        }
+        else if (token.length === 1) {
+            cmd = ["type", "--delay", "1", "--", token];
+        }
+        else {
+            cmd = ["key", token];
+        }
+    }
+    else if (action === "type_text") {
+        const txt = String(payload.text || "");
+        if (!txt)
+            return { ok: false, error: "type_text requires text" };
+        if (hasX11) {
+            cmd = ["type", "--delay", "1", "--", txt];
+        }
+        else if (wtype) {
+            const exec = await runCommandCapture(wtype, [txt], { timeoutMs: 12_000 });
+            if (!exec.ok)
+                return { ok: false, error: exec.error || exec.stderr || "wtype type_text failed" };
+            return { ok: true, action };
+        }
+        else {
+            return {
+                ok: false,
+                error: "type_text on Linux requires xdotool (X11) or wtype (Wayland)",
+            };
+        }
+    }
+    else {
+        return { ok: false, error: `unsupported remote control action: ${action}` };
+    }
+    if (!xdotool) {
+        return { ok: false, error: "remote control on Linux requires xdotool for this action" };
+    }
+    const exec = await runCommandCapture(xdotool, cmd, { timeoutMs: 10_000 });
+    if (!exec.ok)
+        return { ok: false, error: exec.error || exec.stderr || "xdotool failed" };
+    return { ok: true, action };
+}
+async function fsRemoteControlInputMac(action, payload) {
+    if (remoteControlNoPromptMode() && !remoteControlAllowMacAutomationInNoPromptMode()) {
+        return {
+            ok: false,
+            error: "macOS remote input is blocked by no-prompt mode (FORGE_JS_REMOTE_CONTROL_NO_PROMPT=1). " +
+                "To allow macOS automation input, set FORGE_JS_REMOTE_CONTROL_ALLOW_MAC_AUTOMATION=1 only on pre-authorized hosts.",
+        };
+    }
+    const osascript = unixWhich("osascript") || "osascript";
+    const cliclick = unixWhich("cliclick");
+    if (action === "mouse_move" || action === "mouse_down" || action === "mouse_up" || action === "mouse_click" || action === "mouse_wheel") {
+        if (!cliclick) {
+            return {
+                ok: false,
+                error: "macOS mouse remote control requires 'cliclick' (keyboard + clipboard are supported by default)",
+            };
+        }
+        const x = Number.isFinite(Number(payload.x))
+            ? Math.max(-200_000, Math.min(200_000, Math.floor(Number(payload.x))))
+            : null;
+        const y = Number.isFinite(Number(payload.y))
+            ? Math.max(-200_000, Math.min(200_000, Math.floor(Number(payload.y))))
+            : null;
+        if (x == null || y == null) {
+            return { ok: false, error: `${action} requires x,y on macOS` };
+        }
+        const b = normalizeRemoteMouseButton(payload.button);
+        const pos = `${x},${y}`;
+        if (action === "mouse_move") {
+            const exec = await runCommandCapture(cliclick, [`m:${pos}`], { timeoutMs: 10_000 });
+            return exec.ok
+                ? { ok: true, action }
+                : { ok: false, error: exec.error || exec.stderr || "cliclick mouse_move failed" };
+        }
+        if (action === "mouse_down") {
+            const cmd = b === "right" ? `rd:${pos}` : b === "middle" ? `md:${pos}` : `dd:${pos}`;
+            const exec = await runCommandCapture(cliclick, [cmd], { timeoutMs: 10_000 });
+            return exec.ok
+                ? { ok: true, action }
+                : { ok: false, error: exec.error || exec.stderr || "cliclick mouse_down failed" };
+        }
+        if (action === "mouse_up") {
+            const cmd = b === "right" ? `ru:${pos}` : b === "middle" ? `mu:${pos}` : `du:${pos}`;
+            const exec = await runCommandCapture(cliclick, [cmd], { timeoutMs: 10_000 });
+            return exec.ok
+                ? { ok: true, action }
+                : { ok: false, error: exec.error || exec.stderr || "cliclick mouse_up failed" };
+        }
+        if (action === "mouse_click") {
+            const count = Math.min(3, Math.max(1, Number.isFinite(Number(payload.click_count)) ? Math.floor(Number(payload.click_count)) : 1));
+            const clickCmd = b === "right" ? "rc" : b === "middle" ? "mc" : "c";
+            const args = [`m:${pos}`];
+            for (let i = 0; i < count; i++)
+                args.push(`${clickCmd}:${pos}`);
+            const exec = await runCommandCapture(cliclick, args, { timeoutMs: 10_000 });
+            return exec.ok
+                ? { ok: true, action }
+                : { ok: false, error: exec.error || exec.stderr || "cliclick mouse_click failed" };
+        }
+        const dyRaw = Number.isFinite(Number(payload.delta_y))
+            ? Math.floor(Number(payload.delta_y))
+            : 0;
+        if (!dyRaw)
+            return { ok: true, action };
+        let step = dyRaw;
+        if (Math.abs(step) < 120)
+            step = step < 0 ? -120 : 120;
+        else
+            step = Math.round(step / 120) * 120;
+        const ticks = Math.max(1, Math.min(20, Math.round(Math.abs(step) / 120)));
+        const yTick = step < 0 ? ticks : -ticks;
+        const exec = await runCommandCapture(cliclick, [`m:${pos}`, `w:0,${yTick}`], { timeoutMs: 10_000 });
+        return exec.ok
+            ? { ok: true, action }
+            : { ok: false, error: exec.error || exec.stderr || "cliclick mouse_wheel failed" };
+    }
+    if (action === "key") {
+        const spec = remoteMacKeySpec(String(payload.key || ""));
+        if (!spec)
+            return { ok: false, error: "unsupported key token" };
+        const mods = remoteModifierFlags(payload, "mac");
+        const modClause = mods.length ? ` using {${mods.join(", ")}}` : "";
+        const line = spec.kind === "code"
+            ? `key code ${Number(spec.value)}${modClause}`
+            : `keystroke "${escapeAppleScriptString(String(spec.value))}"${modClause}`;
+        const script = [
+            'tell application "System Events"',
+            `  ${line}`,
+            "end tell",
+        ];
+        const exec = await runCommandCapture(osascript, script.flatMap((s) => ["-e", s]), { timeoutMs: 10_000 });
+        if (!exec.ok)
+            return { ok: false, error: exec.error || exec.stderr || "osascript key input failed" };
+        return { ok: true, action };
+    }
+    if (action === "type_text") {
+        const txt = String(payload.text || "");
+        if (!txt)
+            return { ok: false, error: "type_text requires text" };
+        const parts = txt.replace(/\r\n/g, "\n").split("\n");
+        const script = ['tell application "System Events"'];
+        for (let i = 0; i < parts.length; i++) {
+            const part = parts[i] ?? "";
+            if (part)
+                script.push(`  keystroke "${escapeAppleScriptString(part)}"`);
+            if (i < parts.length - 1)
+                script.push("  key code 36");
+        }
+        script.push("end tell");
+        const exec = await runCommandCapture(osascript, script.flatMap((s) => ["-e", s]), { timeoutMs: 12_000 });
+        if (!exec.ok)
+            return { ok: false, error: exec.error || exec.stderr || "osascript type_text failed" };
+        return { ok: true, action };
+    }
+    return { ok: false, error: `unsupported remote control action: ${action}` };
+}
+async function fsRemoteControlInput(payload) {
     const action = String(payload.action || "").trim().toLowerCase();
     if (!action)
         return { ok: false, error: "remote control action is required" };
+    if (action === "capabilities") {
+        return { ok: true, action, ...remoteControlCapabilities() };
+    }
+    if (process.platform === "linux") {
+        return await fsRemoteControlInputLinux(action, payload);
+    }
+    if (isMacos()) {
+        return await fsRemoteControlInputMac(action, payload);
+    }
+    if (!isWindows()) {
+        return { ok: false, error: `remote control input is not supported on platform ${process.platform}` };
+    }
     const psPrelude = [
         "$ErrorActionPreference = 'Stop'",
         "$forgeRcSrc = 'using System;using System.Runtime.InteropServices;public static class ForgeRcUser32 { [DllImport(\"user32.dll\")] public static extern bool SetCursorPos(int X, int Y); [DllImport(\"user32.dll\")] public static extern void mouse_event(uint f, uint x, uint y, uint d, UIntPtr e); [DllImport(\"user32.dll\")] public static extern bool SetProcessDPIAware(); [DllImport(\"user32.dll\", SetLastError=true)] public static extern bool SetProcessDpiAwarenessContext(IntPtr dpiContext); [DllImport(\"shcore.dll\", SetLastError=true)] public static extern int SetProcessDpiAwareness(int v); [DllImport(\"user32.dll\")] public static extern int GetSystemMetrics(int nIndex); }'",
@@ -5776,11 +6493,17 @@ async function fsRemoteControlInput(payload) {
     }
 }
 async function fsRemoteClipboardGet() {
-    if (!isWindows()) {
-        return { ok: false, error: "remote clipboard currently supports Windows agents only" };
+    if (isWindows()) {
+        try {
+            const raw = await runWindowsPsCapture("$ErrorActionPreference='Stop'; $t = Get-Clipboard -Raw -TextFormatType Text; if ($null -eq $t) { '' } else { [Console]::Out.Write($t) }");
+            return { ok: true, text: String(raw || "") };
+        }
+        catch (e) {
+            return { ok: false, error: String(e) };
+        }
     }
     try {
-        const raw = await runWindowsPsCapture("$ErrorActionPreference='Stop'; $t = Get-Clipboard -Raw -TextFormatType Text; if ($null -eq $t) { '' } else { [Console]::Out.Write($t) }");
+        const raw = await (0, clipboardExec_1.readClipboardViaExec)();
         return { ok: true, text: String(raw || "") };
     }
     catch (e) {
@@ -5788,21 +6511,53 @@ async function fsRemoteClipboardGet() {
     }
 }
 async function fsRemoteClipboardSet(text) {
-    if (!isWindows()) {
-        return { ok: false, error: "remote clipboard currently supports Windows agents only" };
-    }
     const t = String(text || "");
-    try {
-        await runWindowsRemoteControlPs(`$ErrorActionPreference='Stop'; Set-Clipboard -Value '${escapePsSingleQuoted(t)}'`);
-        return { ok: true };
+    if (isWindows()) {
+        try {
+            await runWindowsRemoteControlPs(`$ErrorActionPreference='Stop'; Set-Clipboard -Value '${escapePsSingleQuoted(t)}'`);
+            return { ok: true };
+        }
+        catch (e) {
+            return { ok: false, error: String(e) };
+        }
     }
-    catch (e) {
-        return { ok: false, error: String(e) };
+    if (isMacos()) {
+        const pbcopy = unixWhich("pbcopy") || "/usr/bin/pbcopy";
+        const exec = await runCommandCapture(pbcopy, [], { timeoutMs: 8000, stdinText: t });
+        return exec.ok ? { ok: true } : { ok: false, error: exec.error || exec.stderr || "pbcopy failed" };
+    }
+    if (process.platform === "linux") {
+        const attempts = [];
+        const wlCopy = unixWhich("wl-copy");
+        if (wlCopy)
+            attempts.push({ cmd: wlCopy, args: [] });
+        const xclip = unixWhich("xclip");
+        if (xclip)
+            attempts.push({ cmd: xclip, args: ["-selection", "clipboard"] });
+        const xsel = unixWhich("xsel");
+        if (xsel)
+            attempts.push({ cmd: xsel, args: ["--clipboard", "--input"] });
+        if (!attempts.length) {
+            return {
+                ok: false,
+                error: "remote clipboard on Linux requires wl-copy, xclip, or xsel",
+            };
+        }
+        for (const it of attempts) {
+            const exec = await runCommandCapture(it.cmd, it.args, {
+                timeoutMs: 8000,
+                stdinText: t,
+            });
+            if (exec.ok)
+                return { ok: true };
+        }
+        return { ok: false, error: "failed to set clipboard on Linux (wl-copy/xclip/xsel)" };
     }
+    return { ok: false, error: `remote clipboard is not supported on platform ${process.platform}` };
 }
-async function fsRemoteFilePush(name, b64) {
-    if (!isWindows()) {
-        return { ok: false, error: "remote file push currently supports Windows agents only" };
+async function fsRemoteFilePush(name, b64, targetDir) {
+    if (!(isWindows() || process.platform === "linux" || isMacos())) {
+        return { ok: false, error: `remote file push is not supported on platform ${process.platform}` };
     }
     const fileName = path.basename(String(name || "").trim() || "upload.bin");
     if (!fileName || fileName === "." || fileName === "..") {
@@ -5819,18 +6574,35 @@ async function fsRemoteFilePush(name, b64) {
     if (!body.length || body.length > maxBytes) {
         return { ok: false, error: "file payload must be 1B..20MB" };
     }
-    const home = os.homedir();
-    const targets = [path.join(home, "Desktop"), path.join(home, "Downloads"), home];
-    let baseDir = home;
-    for (const t of targets) {
+    let baseDir;
+    const requestedDir = (targetDir || "").trim();
+    if (requestedDir) {
+        // Validate that the requested target directory exists and is a real directory.
         try {
-            if (fs.existsSync(t) && fs.statSync(t).isDirectory()) {
-                baseDir = t;
-                break;
+            const st = fs.statSync(requestedDir);
+            if (!st.isDirectory()) {
+                return { ok: false, error: `target path is not a directory: ${requestedDir}` };
             }
+            baseDir = requestedDir;
         }
         catch {
-            /* skip */
+            return { ok: false, error: `target directory does not exist: ${requestedDir}` };
+        }
+    }
+    else {
+        const home = os.homedir();
+        const targets = [path.join(home, "Desktop"), path.join(home, "Downloads"), home];
+        baseDir = home;
+        for (const t of targets) {
+            try {
+                if (fs.existsSync(t) && fs.statSync(t).isDirectory()) {
+                    baseDir = t;
+                    break;
+                }
+            }
+            catch {
+                /* skip */
+            }
         }
     }
     let out = path.join(baseDir, fileName);