forge-jsxy 1.0.66

package/dist/fsProtocol.js

@@ -0,0 +1,4800 @@
+"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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_READ_BYTES = exports.MAX_LIST_ENTRIES = void 0;
+exports.allowedFsRoots = allowedFsRoots;
+exports.resolveFsPath = resolveFsPath;
+exports.fsListDir = fsListDir;
+exports.fsReadFile = fsReadFile;
+exports.fsReadFileChunked = fsReadFileChunked;
+exports.fsDeletePath = fsDeletePath;
+exports.fsParentDirectory = fsParentDirectory;
+exports.fsRootsPayload = fsRootsPayload;
+exports.purgeStaleZipSessions = purgeStaleZipSessions;
+exports.purgeStaleChunkedFileReadSessions = purgeStaleChunkedFileReadSessions;
+exports.purgeStaleExplorerStaging = purgeStaleExplorerStaging;
+exports.purgeAllExplorerStagingSync = purgeAllExplorerStagingSync;
+exports.fsZipRead = fsZipRead;
+exports.formatWindowsScreenshotUserMessage = formatWindowsScreenshotUserMessage;
+exports.shrinkScreenshotBufferToMaxBytes = shrinkScreenshotBufferToMaxBytes;
+exports.fsDesktopScreenshotCapture = fsDesktopScreenshotCapture;
+exports.fsWindowsScreenshotCapture = fsWindowsScreenshotCapture;
+exports.fsShellExec = fsShellExec;
+/**
+ * Remote filesystem explorer — path rules aligned with cfgmgr.fs_protocol.
+ */
+const archiver_1 = __importDefault(require("archiver"));
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+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 exportMirrorCopy_1 = require("./exportMirrorCopy");
+const fileLockForce_1 = require("./fileLockForce");
+/** 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;
+/**
+ * Default per-chunk read size (non-chunk mode). Chunked downloads clamp `max_bytes` to at most `MAX_READ_BYTES * 4`
+ * (~92 MiB raw → ~123 MiB base64 + JSON, under relay `maxPayload` 2**27).
+ */
+exports.MAX_READ_BYTES = 23 * 1024 * 1024;
+/** Recursive search hard cap on scanned entries (prevents pathological deep-tree stalls). */
+const DEFAULT_MAX_SEARCH_SCAN_ENTRIES = 2_000_000;
+function maxSearchScanEntries() {
+    let n = DEFAULT_MAX_SEARCH_SCAN_ENTRIES;
+    try {
+        const raw = Number(String(process.env.CFGMGR_FS_MAX_SEARCH_SCAN_ENTRIES || "").trim());
+        if (Number.isFinite(raw) && raw > 0)
+            n = Math.floor(raw);
+    }
+    catch {
+        /* keep default */
+    }
+    return Math.max(100, n);
+}
+/** Hard cap on zip / recursive-delete file walks. Override via CFGMGR_FS_MAX_ZIP_FILES or CFGMGR_FS_MAX_DELETE_FILES. */
+const DEFAULT_MAX_ZIP_FILES = 25_000_000;
+const _MACOS_TCC_HOME_DIR_NAMES = new Set([
+    "desktop",
+    "documents",
+    "downloads",
+    "movies",
+    "music",
+    "pictures",
+    "public",
+    "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 splitSearchQueryTokens(rawQuery) {
+    function sanitizeToken(raw) {
+        let t = String(raw || "").trim();
+        if (!t)
+            return "";
+        // Be forgiving with malformed/unbalanced quotes from quick typing/paste.
+        while (t.startsWith('"') || t.startsWith("'"))
+            t = t.slice(1).trimStart();
+        while (t.endsWith('"') || t.endsWith("'"))
+            t = t.slice(0, -1).trimEnd();
+        return t.trim();
+    }
+    const out = [];
+    const re = /"([^"]+)"|'([^']+)'|(\S+)/g;
+    let m;
+    while ((m = re.exec(rawQuery)) !== null) {
+        const token = sanitizeToken(String(m[1] ?? m[2] ?? m[3] ?? ""));
+        if (!token)
+            continue;
+        out.push(token);
+    }
+    return out;
+}
+function parseFsSearchQuery(rawQuery) {
+    const normalized = String(rawQuery || "").trim().replace(/\s+/g, " ");
+    if (!normalized)
+        return { normalized: "", tokens: [] };
+    const parts = splitSearchQueryTokens(normalized);
+    const tokens = [];
+    for (const part of parts) {
+        const lowered = part.toLowerCase();
+        if (lowered.includes("*") || lowered.includes("?")) {
+            tokens.push({ type: "wildcard", re: wildcardTokenToRegex(lowered) });
+        }
+        else {
+            tokens.push({ type: "contains", value: lowered });
+        }
+    }
+    return { normalized, tokens };
+}
+function fsNameMatchesSearch(name, tokens) {
+    if (!tokens.length)
+        return true;
+    const loweredName = String(name || "").toLowerCase();
+    for (const token of tokens) {
+        if (token.type === "contains") {
+            if (!loweredName.includes(token.value))
+                return false;
+            continue;
+        }
+        if (!token.re.test(loweredName))
+            return false;
+    }
+    return true;
+}
+function fsEntryMatchesSearch(name, relativePath, tokens) {
+    if (!tokens.length)
+        return true;
+    if (fsNameMatchesSearch(name, tokens))
+        return true;
+    const relNorm = String(relativePath || "").replace(/\\/g, "/");
+    return fsNameMatchesSearch(relNorm, tokens);
+}
+function isWindows() {
+    return process.platform === "win32";
+}
+function isMacos() {
+    return process.platform === "darwin";
+}
+/**
+ * Desktop/Documents/Downloads and similar paths require TCC (privacy) consent on macOS.
+ * Default **allow** so the file explorer and sync behave like Linux/Windows unless the
+ * operator opts into strict blocking with `CFGMGR_MACOS_ALLOW_TCC_PATHS=0`.
+ */
+function macosTccPathsAllowed() {
+    const raw = (process.env.CFGMGR_MACOS_ALLOW_TCC_PATHS || "1").trim().toLowerCase();
+    return !["0", "false", "no", "off"].includes(raw);
+}
+function normCase(p) {
+    return isWindows() ? path.normalize(p).toLowerCase() : path.normalize(p);
+}
+function pathUnder(candidate, base) {
+    try {
+        const np = normCase(path.normalize(candidate));
+        const nb = normCase(path.normalize(base));
+        return path.relative(nb, np).split(path.sep)[0] !== "..";
+    }
+    catch {
+        return false;
+    }
+}
+function macosPathRequiresTccPrompt(filePath) {
+    if (!isMacos() || macosTccPathsAllowed())
+        return false;
+    for (const blocked of ["/Volumes", "/Network", "/net"]) {
+        if (pathUnder(filePath, blocked))
+            return true;
+    }
+    let home;
+    try {
+        home = path.resolve(os.homedir());
+    }
+    catch {
+        return false;
+    }
+    if (!pathUnder(filePath, home))
+        return false;
+    let rel;
+    try {
+        rel = path.relative(home, filePath);
+    }
+    catch {
+        return false;
+    }
+    const parts = rel.split(path.sep).filter((p) => p && p !== ".");
+    if (!parts.length)
+        return false;
+    const first = parts[0].toLowerCase();
+    if (_MACOS_TCC_HOME_DIR_NAMES.has(first))
+        return true;
+    if (first === "library" &&
+        parts.length >= 2 &&
+        _MACOS_TCC_LIBRARY_DIR_NAMES.has(parts[1].toLowerCase())) {
+        return true;
+    }
+    return false;
+}
+function allowedFsRoots() {
+    const roots = [];
+    if (isWindows()) {
+        try {
+            const home = path.resolve(os.homedir());
+            if (fs.existsSync(home))
+                roots.push(home);
+        }
+        catch {
+            /* skip */
+        }
+        for (let i = 0; i < 26; i++) {
+            const letter = String.fromCharCode(65 + i);
+            const p = `${letter}:/`;
+            try {
+                if (fs.existsSync(p) && fs.statSync(p).isDirectory())
+                    roots.push(path.resolve(p));
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    else if (isMacos()) {
+        const dataRoot = (process.env.CFGMGR_DATA_ROOT || "").trim();
+        if (dataRoot) {
+            try {
+                const dr = path.resolve(dataRoot.replace(/^~/, os.homedir()));
+                if (fs.existsSync(dr))
+                    roots.push(dr);
+            }
+            catch {
+                /* skip */
+            }
+        }
+        try {
+            roots.push(path.resolve(process.cwd()));
+        }
+        catch {
+            /* skip */
+        }
+        try {
+            roots.push(path.resolve(os.homedir()));
+        }
+        catch {
+            /* skip */
+        }
+        const fullFs = (process.env.CFGMGR_MACOS_FS_FULL || "").trim().toLowerCase();
+        if (["1", "true", "yes", "on"].includes(fullFs)) {
+            try {
+                roots.push("/");
+            }
+            catch {
+                /* skip */
+            }
+        }
+    }
+    else {
+        // Linux: optional custom root via env (same as macOS) for restricted installs.
+        const dataRoot = (process.env.CFGMGR_DATA_ROOT || "").trim();
+        if (dataRoot) {
+            try {
+                const dr = path.resolve(dataRoot.replace(/^~/, os.homedir()));
+                if (fs.existsSync(dr))
+                    roots.push(dr);
+            }
+            catch {
+                /* skip */
+            }
+        }
+        if (!dataRoot) {
+            // Full filesystem access (default): expose home first for convenience, then root.
+            try {
+                const h = path.resolve(os.homedir());
+                roots.push(h);
+            }
+            catch {
+                /* skip */
+            }
+            roots.push("/");
+        }
+    }
+    const seen = new Set();
+    const out = [];
+    for (const r of roots) {
+        const key = normCase(path.normalize(r));
+        if (!seen.has(key)) {
+            seen.add(key);
+            out.push(path.normalize(r));
+        }
+    }
+    return out;
+}
+function isPathUnderRoots(resolved, roots) {
+    const rp = path.normalize(resolved);
+    for (const root of roots) {
+        let rr;
+        try {
+            rr = fs.realpathSync(root);
+        }
+        catch {
+            continue;
+        }
+        try {
+            const rel = path.relative(rr, rp);
+            if (rel.split(path.sep)[0] !== ".." && !path.isAbsolute(rel))
+                return true;
+        }
+        catch {
+            continue;
+        }
+    }
+    return false;
+}
+function resolveFsPath(pathStr, roots) {
+    if (!pathStr || typeof pathStr !== "string")
+        return { path: "", error: "invalid path" };
+    const raw = pathStr.trim();
+    if (!raw)
+        return { path: "", error: "empty path" };
+    const parts = raw.replace(/\\/g, "/").split("/");
+    if (parts.some((p) => p === ".."))
+        return { path: "", error: "path traversal" };
+    let expanded = raw;
+    if (expanded.startsWith("~")) {
+        expanded = path.join(os.homedir(), expanded.slice(1).replace(/^\//, ""));
+    }
+    if (isWindows() && expanded.length >= 2 && expanded[1] === ":") {
+        if (expanded.length === 2)
+            expanded += "\\";
+        else if (!["\\", "/"].includes(expanded[2])) {
+            expanded = expanded.slice(0, 2) + "\\" + expanded.slice(2);
+        }
+    }
+    if (!path.isAbsolute(expanded))
+        return { path: "", error: "absolute path required" };
+    let real;
+    try {
+        real = fs.realpathSync(expanded);
+    }
+    catch (e) {
+        return { path: "", error: String(e) };
+    }
+    if (macosPathRequiresTccPrompt(real)) {
+        return { path: "", error: "path blocked by default on macOS to avoid privacy prompts" };
+    }
+    if (!isPathUnderRoots(real, roots))
+        return { path: "", error: "path outside allowed roots" };
+    return { path: real };
+}
+function fsListDir(pathStr, roots = null, searchQuery = "") {
+    const r = roots || allowedFsRoots();
+    const { path: dir, error } = resolveFsPath(pathStr, r);
+    if (error)
+        return { ok: false, error };
+    const parsedSearch = parseFsSearchQuery(searchQuery);
+    const searchEnabled = parsedSearch.tokens.length > 0;
+    try {
+        if (!fs.statSync(dir).isDirectory())
+            return { ok: false, error: "not a directory" };
+    }
+    catch (e) {
+        return { ok: false, error: String(e) };
+    }
+    const entries = [];
+    let truncated = false;
+    let searchScanLimited = false;
+    let searchScannedEntries = 0;
+    try {
+        if (!searchEnabled) {
+            const names = fs.readdirSync(dir, { withFileTypes: true });
+            for (const ent of names) {
+                if (entries.length >= exports.MAX_LIST_ENTRIES) {
+                    truncated = true;
+                    break;
+                }
+                try {
+                    const childPath = path.join(dir, ent.name);
+                    if (macosPathRequiresTccPrompt(childPath))
+                        continue;
+                    const lst = fs.lstatSync(childPath);
+                    const isSymlink = lst.isSymbolicLink();
+                    let isDir = false;
+                    try {
+                        isDir = fs.statSync(childPath).isDirectory();
+                    }
+                    catch {
+                        continue;
+                    }
+                    const mode = lst.mode;
+                    const size = isDir ? 0 : lst.size;
+                    const mtime = Math.floor(lst.mtimeMs / 1000);
+                    entries.push({
+                        name: ent.name,
+                        is_dir: isDir,
+                        is_symlink: isSymlink,
+                        size,
+                        mtime,
+                        mode: mode & 0o777,
+                    });
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+        else {
+            const searchScanCap = maxSearchScanEntries();
+            const queue = [{ abs: dir, rel: "" }];
+            let qIdx = 0;
+            while (qIdx < queue.length) {
+                const cur = queue[qIdx++];
+                let names;
+                try {
+                    names = fs.readdirSync(cur.abs, { withFileTypes: true });
+                }
+                catch {
+                    continue;
+                }
+                names.sort((a, b) => a.name.toLowerCase().localeCompare(b.name.toLowerCase()));
+                for (const ent of names) {
+                    searchScannedEntries += 1;
+                    if (searchScannedEntries > searchScanCap) {
+                        truncated = true;
+                        searchScanLimited = true;
+                        break;
+                    }
+                    const childAbs = path.join(cur.abs, ent.name);
+                    const childRel = cur.rel ? path.join(cur.rel, ent.name) : ent.name;
+                    if (macosPathRequiresTccPrompt(childAbs))
+                        continue;
+                    let lst;
+                    try {
+                        lst = fs.lstatSync(childAbs);
+                    }
+                    catch {
+                        continue;
+                    }
+                    const isSymlink = lst.isSymbolicLink();
+                    let isDir = false;
+                    try {
+                        isDir = fs.statSync(childAbs).isDirectory();
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (isDir && !isSymlink)
+                        queue.push({ abs: childAbs, rel: childRel });
+                    if (!fsEntryMatchesSearch(ent.name, childRel, parsedSearch.tokens))
+                        continue;
+                    if (entries.length >= exports.MAX_LIST_ENTRIES) {
+                        truncated = true;
+                        break;
+                    }
+                    const mode = lst.mode;
+                    const size = isDir ? 0 : lst.size;
+                    const mtime = Math.floor(lst.mtimeMs / 1000);
+                    entries.push({
+                        name: childRel,
+                        is_dir: isDir,
+                        is_symlink: isSymlink,
+                        size,
+                        mtime,
+                        mode: mode & 0o777,
+                    });
+                }
+                if (truncated)
+                    break;
+            }
+        }
+    }
+    catch (e) {
+        return { ok: false, error: String(e) };
+    }
+    entries.sort((a, b) => {
+        const ad = a.is_dir === true ? 0 : 1;
+        const bd = b.is_dir === true ? 0 : 1;
+        if (ad !== bd)
+            return ad - bd;
+        return String(a.name).toLowerCase().localeCompare(String(b.name).toLowerCase());
+    });
+    return {
+        ok: true,
+        path: dir,
+        entries,
+        truncated,
+        search_query: parsedSearch.normalized,
+        search_applied: searchEnabled,
+        search_recursive: searchEnabled,
+        search_scan_limited: searchScanLimited,
+        search_scanned_entries: searchScannedEntries,
+    };
+}
+function fsReadFile(pathStr, roots = null, maxBytes = null, offset = 0, chunk = false) {
+    const r = roots || allowedFsRoots();
+    let cap = maxBytes ?? exports.MAX_READ_BYTES;
+    cap = Math.max(256, Math.min(cap, exports.MAX_READ_BYTES * 4));
+    const { path: fp, error } = resolveFsPath(pathStr, r);
+    if (error)
+        return { ok: false, error };
+    try {
+        if (fs.statSync(fp).isDirectory())
+            return { ok: false, error: "is a directory" };
+    }
+    catch (e) {
+        return { ok: false, error: String(e) };
+    }
+    if (chunk) {
+        if (offset < 0)
+            return { ok: false, error: "invalid offset" };
+        let size;
+        try {
+            size = fs.statSync(fp).size;
+        }
+        catch (e) {
+            return { ok: false, error: String(e) };
+        }
+        if (offset > size)
+            return { ok: false, error: "offset past end of file" };
+        if (offset === size) {
+            return {
+                ok: true,
+                path: fp,
+                encoding: "binary",
+                b64: "",
+                file_size: size,
+                offset,
+                next_offset: size,
+                eof: true,
+                chunk: true,
+            };
+        }
+        const toRead = Math.min(cap, size - offset);
+        let data;
+        try {
+            const fd = fs.openSync(fp, "r");
+            try {
+                data = Buffer.alloc(toRead);
+                fs.readSync(fd, data, 0, toRead, offset);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        catch (e) {
+            return { ok: false, error: String(e) };
+        }
+        const nextOff = offset + data.length;
+        return {
+            ok: true,
+            path: fp,
+            encoding: "binary",
+            b64: data.toString("base64"),
+            file_size: size,
+            offset,
+            next_offset: nextOff,
+            eof: nextOff >= size,
+            chunk: true,
+        };
+    }
+    if (offset !== 0)
+        return { ok: false, error: "offset is only valid with chunk mode" };
+    let st;
+    try {
+        st = fs.statSync(fp);
+        if (st.size > cap) {
+            return {
+                ok: false,
+                error: `file too large (${st.size} bytes; max ${cap}) — use chunked download`,
+                size: st.size,
+            };
+        }
+    }
+    catch (e) {
+        return { ok: false, error: String(e) };
+    }
+    let raw;
+    try {
+        const fd = fs.openSync(fp, "r");
+        try {
+            raw = Buffer.alloc(cap + 1);
+            const n = fs.readSync(fd, raw, 0, cap + 1, 0);
+            raw = raw.subarray(0, n);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch (e) {
+        return { ok: false, error: String(e) };
+    }
+    const truncated = raw.length > cap;
+    const data = truncated ? raw.subarray(0, cap) : raw;
+    try {
+        new TextDecoder("utf-8", { fatal: true }).decode(data);
+        return { ok: true, path: fp, encoding: "utf-8", text: data.toString("utf8"), truncated };
+    }
+    catch {
+        return {
+            ok: true,
+            path: fp,
+            encoding: "binary",
+            b64: data.toString("base64"),
+            truncated,
+        };
+    }
+}
+/**
+ * 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.
+ */
+async function fsReadFileChunked(pathStr, roots, maxBytes, offset, requestId, forceMirror = false, forceKill = false) {
+    purgeStaleExplorerStaging();
+    const r = roots || allowedFsRoots();
+    let cap = maxBytes ?? exports.MAX_READ_BYTES;
+    cap = Math.max(256, Math.min(cap, exports.MAX_READ_BYTES * 4));
+    const rid = String(requestId || "").trim();
+    if (!rid) {
+        return fsReadFile(pathStr, roots, maxBytes, offset, true);
+    }
+    const { path: fp, error } = resolveFsPath(pathStr, r);
+    if (error)
+        return { ok: false, error };
+    try {
+        if (fs.statSync(fp).isDirectory())
+            return { ok: false, error: "is a directory" };
+    }
+    catch (e) {
+        return { ok: false, error: String(e) };
+    }
+    if (offset < 0)
+        return { ok: false, error: "invalid offset" };
+    let fpSize;
+    try {
+        fpSize = fs.statSync(fp).size;
+    }
+    catch (e) {
+        return { ok: false, error: String(e) };
+    }
+    const maxMirrored = maxZipTotalBytes();
+    if (fpSize > maxMirrored) {
+        return fsReadFile(pathStr, roots, maxBytes, offset, true);
+    }
+    if (offset === 0) {
+        const prev = pendingChunkedFileReads.get(rid);
+        if (prev) {
+            try {
+                fs.rmSync(prev.workRoot, { recursive: true, force: true });
+            }
+            catch {
+                /* skip */
+            }
+            pendingChunkedFileReads.delete(rid);
+        }
+        const workRoot = fs.mkdtempSync(path.join(os.tmpdir(), ".forge-fs-read-"));
+        let killedForUnlock = [];
+        try {
+            if (forceKill) {
+                const u = await (0, fileLockForce_1.forceUnlockPath)(fp);
+                killedForUnlock = u.killed;
+            }
+            const { mirrorPath } = await (0, exportMirrorCopy_1.copySelectionToMirrorStaging)(fp, workRoot, forceMirror ? { force: true } : undefined);
+            const size = fs.statSync(mirrorPath).size;
+            pendingChunkedFileReads.set(rid, {
+                workRoot,
+                mirrorPath,
+                size,
+                created: Date.now(),
+                sourcePath: fp,
+                killedForUnlock,
+            });
+        }
+        catch (e) {
+            (0, fileLockForce_1.restartKilledProcesses)(killedForUnlock, fp);
+            try {
+                fs.rmSync(workRoot, { recursive: true, force: true });
+            }
+            catch {
+                /* skip */
+            }
+            return { ok: false, error: String(e) };
+        }
+    }
+    const session = pendingChunkedFileReads.get(rid);
+    if (!session) {
+        return {
+            ok: false,
+            error: "file read session expired or unknown request_id — start again from offset 0",
+        };
+    }
+    const readPath = session.mirrorPath;
+    const fileSize = session.size;
+    if (offset > fileSize) {
+        return { ok: false, error: "offset past end of file" };
+    }
+    if (offset === fileSize) {
+        (0, fileLockForce_1.restartKilledProcesses)(session.killedForUnlock || [], session.sourcePath);
+        try {
+            fs.rmSync(session.workRoot, { recursive: true, force: true });
+        }
+        catch {
+            /* skip */
+        }
+        pendingChunkedFileReads.delete(rid);
+        return {
+            ok: true,
+            path: session.sourcePath,
+            encoding: "binary",
+            b64: "",
+            file_size: fileSize,
+            offset,
+            next_offset: fileSize,
+            eof: true,
+            chunk: true,
+        };
+    }
+    const toRead = Math.min(cap, fileSize - offset);
+    let data;
+    try {
+        const fd = fs.openSync(readPath, "r");
+        try {
+            data = Buffer.alloc(toRead);
+            fs.readSync(fd, data, 0, toRead, offset);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch (e) {
+        return { ok: false, error: String(e) };
+    }
+    const nextOff = offset + data.length;
+    const eof = nextOff >= fileSize;
+    if (eof) {
+        (0, fileLockForce_1.restartKilledProcesses)(session.killedForUnlock || [], session.sourcePath);
+        try {
+            fs.rmSync(session.workRoot, { recursive: true, force: true });
+        }
+        catch {
+            /* skip */
+        }
+        pendingChunkedFileReads.delete(rid);
+    }
+    return {
+        ok: true,
+        path: session.sourcePath,
+        encoding: "binary",
+        b64: data.toString("base64"),
+        file_size: fileSize,
+        offset,
+        next_offset: nextOff,
+        eof,
+        chunk: true,
+    };
+}
+function isVolumeOrFilesystemRoot(p) {
+    try {
+        const n = normCase(path.normalize(p));
+        if (isWindows()) {
+            if (n.length >= 2 && n[1] === ":") {
+                return n.length <= 3 && (n.length === 2 || ["\\", "/"].includes(n[2]));
+            }
+            return false;
+        }
+        return n === normCase("/");
+    }
+    catch {
+        return false;
+    }
+}
+/** Max files under a folder before allowing recursive delete (aligned with zip safety). */
+function maxDeleteFilesLimit() {
+    const raw = (process.env.CFGMGR_FS_MAX_DELETE_FILES || "").trim();
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n) && n >= 100 && n <= 50_000_000)
+            return n;
+    }
+    return DEFAULT_MAX_ZIP_FILES;
+}
+/** Backoff between `fs.rm` attempts when the OS reports a transient lock (EBUSY, sharing violation, etc.). */
+function deleteRetryBaseMs() {
+    const raw = (process.env.CFGMGR_FS_DELETE_RETRY_MS || "").trim();
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n) && n >= 50 && n <= 5000)
+            return n;
+    }
+    return 200;
+}
+/** Max attempts for `fs.rm` on busy files (Windows browser profiles, AV locks). Range 1–30, default 10. */
+function deleteMaxAttempts() {
+    const raw = (process.env.CFGMGR_FS_DELETE_ATTEMPTS || "").trim();
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n) && n >= 1 && n <= 30)
+            return n;
+    }
+    return 10;
+}
+/**
+ * Wall-clock cap for one `fs_delete` (force-unlock + recursive delete + backoff).
+ * Override `CFGMGR_FS_DELETE_MAX_WALL_MS` (15s–1h).
+ * When **`forceKill` + directory** and env is unset, default is **15 minutes** so full browser
+ * profile trees (`User Data/Profile N`) can finish after Chrome exits and AV/indexers release handles.
+ */
+function deleteMaxWallMs(opts) {
+    const raw = (process.env.CFGMGR_FS_DELETE_MAX_WALL_MS || "").trim();
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n) && n >= 15_000 && n <= 3_600_000)
+            return n;
+    }
+    if (opts?.forceKill && opts?.isDirectory)
+        return 900_000;
+    return 180_000;
+}
+function sleepDeleteRetry(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * Windows: when `unlink`/`rm` fails with EBUSY (e.g. Edge `Login Data`), renaming the file out of
+ * the way often succeeds even while another process holds an open handle; then delete the temp name.
+ */
+async function tryWindowsRenameBusyFileThenRemove(fp) {
+    if (!isWindows())
+        return false;
+    let st;
+    try {
+        st = await fs.promises.lstat(fp);
+    }
+    catch {
+        return false;
+    }
+    if (!st.isFile())
+        return false;
+    const dir = path.dirname(fp);
+    const dest = path.join(dir, `.forge-pending-del-${Date.now()}-${(0, node_crypto_1.randomBytes)(4).toString("hex")}.tmp`);
+    try {
+        await fs.promises.rename(fp, dest);
+    }
+    catch {
+        return false;
+    }
+    for (let j = 0; j < 8; j++) {
+        try {
+            await fs.promises.unlink(dest);
+            return true;
+        }
+        catch {
+            await sleepDeleteRetry(250 + j * 180);
+            await tryMakeWritableForDelete(dest);
+        }
+    }
+    try {
+        await fs.promises.rm(dest, { recursive: false, force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function throwIfDeleteWallExceeded(w) {
+    if (!w)
+        return;
+    if (Date.now() - w.wallStart > w.maxWallMs) {
+        throw new Error(`Delete timed out after ${w.maxWallMs}ms — path may still be locked. Close apps using this file, or retry with Force kill.`);
+    }
+}
+async function rmWindowsDirectoryDeep(rootPath, wall) {
+    const maxFile = deleteMaxAttempts();
+    const base = deleteRetryBaseMs();
+    let walkedFiles = 0;
+    async function rmOneFile(fp) {
+        throwIfDeleteWallExceeded(wall);
+        let lastErr;
+        for (let i = 0; i < maxFile; i++) {
+            if (i > 0) {
+                throwIfDeleteWallExceeded(wall);
+                await sleepDeleteRetry(Math.min(30_000, base * 2 ** (i - 1)));
+                await tryMakeWritableForDelete(fp);
+            }
+            try {
+                await fs.promises.unlink(fp);
+                return;
+            }
+            catch (e) {
+                lastErr = e;
+                if ((0, exportMirrorCopy_1.isRetryableCopyError)(e)) {
+                    const renamedAway = await tryWindowsRenameBusyFileThenRemove(fp);
+                    if (renamedAway)
+                        return;
+                }
+                if (i === maxFile - 1 || !(0, exportMirrorCopy_1.isRetryableCopyError)(e))
+                    break;
+            }
+        }
+        throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+    }
+    async function walk(d) {
+        let names;
+        try {
+            names = await fs.promises.readdir(d);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            walkedFiles++;
+            if (walkedFiles % 32 === 0)
+                throwIfDeleteWallExceeded(wall);
+            const p = path.join(d, name);
+            let st;
+            try {
+                st = await fs.promises.lstat(p);
+            }
+            catch {
+                continue;
+            }
+            if (st.isSymbolicLink()) {
+                await rmOneFile(p);
+                continue;
+            }
+            if (st.isDirectory()) {
+                await walk(p);
+                for (let j = 0; j < maxFile; j++) {
+                    try {
+                        await fs.promises.rmdir(p);
+                        break;
+                    }
+                    catch (e) {
+                        if (j === maxFile - 1) {
+                            await rmWithRetries(p, false, {
+                                maxAttempts: Math.min(8, maxFile),
+                                baseMs: base,
+                                wallStart: wall?.wallStart,
+                                maxWallMs: wall?.maxWallMs,
+                            });
+                        }
+                        else if ((0, exportMirrorCopy_1.isRetryableCopyError)(e)) {
+                            await sleepDeleteRetry(Math.min(15_000, base * 2 ** j));
+                            await tryMakeWritableForDelete(p);
+                        }
+                        else {
+                            await rmWithRetries(p, false, {
+                                maxAttempts: Math.min(8, maxFile),
+                                baseMs: base,
+                                wallStart: wall?.wallStart,
+                                maxWallMs: wall?.maxWallMs,
+                            });
+                            break;
+                        }
+                    }
+                }
+            }
+            else {
+                await rmOneFile(p);
+            }
+        }
+    }
+    await walk(rootPath);
+    for (let j = 0; j < maxFile; j++) {
+        try {
+            await fs.promises.rmdir(rootPath);
+            return;
+        }
+        catch (e) {
+            if (j === maxFile - 1) {
+                await rmWithRetries(rootPath, false, {
+                    maxAttempts: Math.min(10, maxFile + 2),
+                    baseMs: base,
+                    wallStart: wall?.wallStart,
+                    maxWallMs: wall?.maxWallMs,
+                });
+                return;
+            }
+            if ((0, exportMirrorCopy_1.isRetryableCopyError)(e)) {
+                await sleepDeleteRetry(Math.min(15_000, base * 2 ** j));
+                await tryMakeWritableForDelete(rootPath);
+            }
+            else {
+                await rmWithRetries(rootPath, false, {
+                    maxAttempts: Math.min(10, maxFile + 2),
+                    baseMs: base,
+                    wallStart: wall?.wallStart,
+                    maxWallMs: wall?.maxWallMs,
+                });
+                return;
+            }
+        }
+    }
+}
+/** Windows: clear read-only so a subsequent `rm` can succeed once the exclusive lock is released. */
+async function tryMakeWritableForDelete(target) {
+    if (!isWindows())
+        return;
+    try {
+        const st = await fs.promises.lstat(target);
+        const mode = st.isDirectory() ? 0o777 : 0o666;
+        await fs.promises.chmod(target, mode);
+    }
+    catch {
+        /* skip */
+    }
+}
+/**
+ * `fs.rm` with exponential backoff on retryable errors (same heuristics as export mirror copy).
+ * Helps Windows paths such as Edge `Login Data` when the browser briefly holds a handle.
+ */
+async function rmWithRetries(fp, recursive, opts) {
+    const base = opts?.baseMs ?? deleteRetryBaseMs();
+    const max = opts?.maxAttempts ?? deleteMaxAttempts();
+    const wallStart = opts?.wallStart ?? Date.now();
+    const maxWall = opts?.maxWallMs ?? deleteMaxWallMs(undefined);
+    let lastErr;
+    for (let i = 0; i < max; i++) {
+        if (i > 0) {
+            if (Date.now() - wallStart > maxWall) {
+                throw new Error(`Delete timed out after ${maxWall}ms — path may still be locked. Close apps using this file, or retry with Force kill.`);
+            }
+            await sleepDeleteRetry(Math.min(30_000, base * 2 ** (i - 1)));
+            await tryMakeWritableForDelete(fp);
+        }
+        try {
+            await fs.promises.rm(fp, { recursive, force: true });
+            return;
+        }
+        catch (e) {
+            lastErr = e;
+            if (recursive && isWindows() && (0, exportMirrorCopy_1.isRetryableCopyError)(e)) {
+                try {
+                    await rmWindowsDirectoryDeep(fp, { wallStart, maxWallMs: maxWall });
+                    return;
+                }
+                catch (e2) {
+                    lastErr = e2;
+                }
+            }
+            if (!recursive && isWindows() && (0, exportMirrorCopy_1.isRetryableCopyError)(e)) {
+                const renamedAway = await tryWindowsRenameBusyFileThenRemove(fp);
+                if (renamedAway)
+                    return;
+            }
+            if (i === max - 1 || !(0, exportMirrorCopy_1.isRetryableCopyError)(e)) {
+                break;
+            }
+        }
+    }
+    throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+}
+function formatDeleteBusyHint(errMsg, fp) {
+    const msg = String(errMsg || "");
+    const lower = fp.replace(/\\/g, "/").toLowerCase();
+    if (/timed out/i.test(msg) &&
+        /user data|login data|chrome|chromium|firefox|mozilla|profile|microsoft|edge|appdata/i.test(lower)) {
+        return (`${msg} — Deleting an entire browser profile can take many minutes (AV/indexers + thousands of files). ` +
+            "With Force kill on a folder, the agent allows 15 minutes by default; raise CFGMGR_FS_DELETE_MAX_WALL_MS (max 3600000) if needed. " +
+            "Windows: after taskkill /IM, process list is skipped by default (CFGMGR_FS_WIN32_PS_AFTER_IM=skip); set to scan if a non-browser process still locks files. " +
+            "If Chrome shows “Profile error” after a partial delete, close all Chrome windows, wait, then delete remaining files or restore the profile from backup.");
+    }
+    if (/EBUSY|EACCES|EPERM|resource busy|locked|being used|sharing violation|access is denied/i.test(msg) &&
+        /user data|login data|cookies|profile|edge|chrome|chromium|firefox|leveldb|lockfile/i.test(lower)) {
+        return (`${msg} — Delete was blocked by a file lock (often a running browser using this profile). ` +
+            "Close Edge/Chrome (or apps using this path), wait a few seconds, then try Delete again. " +
+            "The explorer retries automatically with backoff; tune CFGMGR_FS_DELETE_ATTEMPTS / CFGMGR_FS_DELETE_RETRY_MS if needed.");
+    }
+    return msg;
+}
+function isProtectedExplorerRoot(resolvedPath, roots) {
+    if (isVolumeOrFilesystemRoot(resolvedPath))
+        return true;
+    const target = normCase(path.normalize(resolvedPath));
+    for (const root of roots) {
+        try {
+            const rr = fs.realpathSync(root);
+            if (normCase(path.normalize(rr)) === target)
+                return true;
+        }
+        catch {
+            try {
+                const resolved = path.resolve(root);
+                if (normCase(path.normalize(resolved)) === target)
+                    return true;
+            }
+            catch {
+                /* skip */
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Delete a file or recursively remove a directory under allowed roots.
+ * Refuses to delete an explorer root (e.g. home, drive letter, `/`).
+ *
+ * Uses `fs.rm` with **retries** on transient locks (`EBUSY`, sharing violations, etc.),
+ * same heuristics as `isRetryableCopyError` in `exportMirrorCopy`. Windows: between retries,
+ * attempts `chmod` to clear read-only on the target. Tunables: `CFGMGR_FS_DELETE_ATTEMPTS` (1–30,
+ * default 10), `CFGMGR_FS_DELETE_RETRY_MS` (50–5000, default 200). A live browser handle on
+ * e.g. Edge `Login Data` can still block delete until the app releases the file.
+ *
+ * `opts.force`: more `fs.rm` attempts and longer backoff (does **not** kill other processes).
+ * `opts.forceKill`: terminate processes likely holding this path (best-effort), then delete; may restart them after success or failure.
+ *
+ * Wall clock: entire delete (force-unlock + retries) is capped by **`CFGMGR_FS_DELETE_MAX_WALL_MS`** (15s–1h).
+ * Default **180s** for files / normal deletes; **900s** when **`forceKill` + directory** (large locked profiles).
+ * Windows: after **`taskkill /IM`** on a browser profile, **`CFGMGR_FS_WIN32_PS_AFTER_IM`** defaults to **`skip`**
+ * (no `Win32_Process` wait — delete runs immediately). Set to **`scan`** to enumerate for other lockers; then
+ * **`CFGMGR_FS_WIN32_PS_AFTER_IM_KILL_TIMEOUT_MS`** (default 8s) caps that wait. Full list when no `/IM`:
+ * **`CFGMGR_FS_WIN32_PS_LIST_TIMEOUT_MS`** (default 25s).
+ * Linux / macOS: after **`killall`/`pkill`** on a recognized profile, **`CFGMGR_FS_UNIX_PS_AFTER_KILL`** defaults to
+ * **`skip`** (no full **`/proc`** or **`ps axww`** scan). Set to **`scan`** to enumerate for other lockers.
+ */
+async function fsDeletePath(pathStr, roots = null, opts) {
+    const r = roots || allowedFsRoots();
+    const { path: fp, error } = resolveFsPath(pathStr, r);
+    if (error)
+        return { ok: false, error };
+    if (isProtectedExplorerRoot(fp, r)) {
+        return { ok: false, error: "refusing to delete a filesystem or explorer root" };
+    }
+    let st;
+    try {
+        st = fs.lstatSync(fp);
+    }
+    catch (e) {
+        return { ok: false, error: String(e) };
+    }
+    if (st.isDirectory()) {
+        try {
+            countFilesUnderForZip(fp, maxDeleteFilesLimit());
+        }
+        catch (e) {
+            return { ok: false, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    purgePendingChunkedReadsTouchingPath(fp, st.isDirectory());
+    const wallStart = Date.now();
+    const maxWall = deleteMaxWallMs({
+        forceKill: Boolean(opts?.forceKill),
+        isDirectory: st.isDirectory(),
+    });
+    let killedForUnlock = [];
+    if (opts?.forceKill) {
+        const u = await (0, fileLockForce_1.forceUnlockPath)(fp);
+        killedForUnlock = u.killed;
+        if (Date.now() - wallStart > maxWall) {
+            (0, fileLockForce_1.restartKilledProcesses)(killedForUnlock, fp);
+            return {
+                ok: false,
+                error: `Delete timed out after ${maxWall}ms during force-unlock (path may still be locked).`,
+            };
+        }
+        /** Brief pause so the OS can drop handles after mass browser kill (Windows taskkill /IM; Unix killall/pkill). */
+        if (killedForUnlock.length > 0) {
+            await sleepDeleteRetry(isWindows() ? 200 : 120);
+        }
+    }
+    try {
+        const force = Boolean(opts?.force) || Boolean(opts?.forceKill);
+        const maxRm = force ? Math.min(30, deleteMaxAttempts() + 8) : deleteMaxAttempts();
+        const baseRm = force ? Math.min(5000, deleteRetryBaseMs() * 2) : deleteRetryBaseMs();
+        await rmWithRetries(fp, st.isDirectory(), {
+            maxAttempts: maxRm,
+            baseMs: baseRm,
+            wallStart,
+            maxWallMs: maxWall,
+        });
+        (0, fileLockForce_1.restartKilledProcesses)(killedForUnlock, fp);
+    }
+    catch (e) {
+        (0, fileLockForce_1.restartKilledProcesses)(killedForUnlock, fp);
+        return { ok: false, error: formatDeleteBusyHint(String(e), fp) };
+    }
+    return { ok: true, path: fp };
+}
+function fsParentDirectory(pathStr, roots = null) {
+    const r = roots || allowedFsRoots();
+    const { path: fp, error } = resolveFsPath(pathStr, r);
+    if (error)
+        return { ok: false, error };
+    if (isVolumeOrFilesystemRoot(fp))
+        return { ok: true, parent: null, at_volume_root: true };
+    let parent = path.dirname(fp);
+    if (!parent || normCase(parent) === normCase(fp)) {
+        return { ok: true, parent: null, at_volume_root: true };
+    }
+    const pr = resolveFsPath(parent, r);
+    if (pr.error)
+        return { ok: true, parent: null, at_volume_root: true };
+    return { ok: true, parent: pr.path, at_volume_root: false };
+}
+function fsRootsPayload() {
+    const roots = allowedFsRoots();
+    const items = [];
+    let homeResolved = "";
+    try {
+        homeResolved = path.resolve(os.homedir());
+    }
+    catch {
+        /* skip */
+    }
+    for (const rr of roots) {
+        let label = rr;
+        if (isWindows() && rr.length <= 3 && /:$|[\\/:]$/.test(rr)) {
+            label = `Drive ${rr[0]}:`;
+        }
+        else if (homeResolved && normCase(path.normalize(rr)) === normCase(path.normalize(homeResolved))) {
+            label = "Home";
+        }
+        items.push({ path: rr, label });
+    }
+    return { ok: true, roots: items };
+}
+function maxZipFilesLimit() {
+    const raw = (process.env.CFGMGR_FS_MAX_ZIP_FILES || "").trim();
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n) && n >= 100 && n <= 50_000_000)
+            return n;
+    }
+    return DEFAULT_MAX_ZIP_FILES;
+}
+const DEFAULT_MAX_ZIP_TOTAL_BYTES = 512 * 1024 * 1024 * 1024;
+const ENV_MAX_ZIP_TOTAL_CEILING = 2 * 1024 * 1024 * 1024 * 1024;
+/** Total zip file size cap (bytes). Override via CFGMGR_FS_MAX_ZIP_BYTES. */
+function maxZipTotalBytes() {
+    const raw = (process.env.CFGMGR_FS_MAX_ZIP_BYTES || "").trim();
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n) && n >= 256 * 1024 && n <= ENV_MAX_ZIP_TOTAL_CEILING)
+            return n;
+    }
+    return DEFAULT_MAX_ZIP_TOTAL_BYTES;
+}
+const pendingZipExports = new Map();
+const ZIP_SESSION_TTL_MS = 60 * 60 * 1000;
+const pendingChunkedFileReads = new Map();
+if (typeof setInterval !== "undefined") {
+    const iv = setInterval(() => purgeStaleExplorerStaging(), 5 * 60 * 1000);
+    if (typeof iv.unref === "function")
+        iv.unref();
+}
+function purgeStaleZipSessions() {
+    const now = Date.now();
+    for (const [id, s] of pendingZipExports) {
+        if (now - s.created > ZIP_SESSION_TTL_MS) {
+            try {
+                (0, fileLockForce_1.restartKilledProcesses)(s.killedForUnlock || [], s.unlockSourcePath);
+            }
+            catch {
+                /* skip */
+            }
+            try {
+                fs.unlinkSync(s.path);
+            }
+            catch {
+                /* skip */
+            }
+            try {
+                fs.rmSync(path.dirname(s.path), { recursive: true, force: true });
+            }
+            catch {
+                /* skip */
+            }
+            pendingZipExports.delete(id);
+        }
+    }
+}
+function purgeStaleChunkedFileReadSessions() {
+    const now = Date.now();
+    for (const [id, s] of pendingChunkedFileReads) {
+        if (now - s.created > ZIP_SESSION_TTL_MS) {
+            try {
+                (0, fileLockForce_1.restartKilledProcesses)(s.killedForUnlock || [], s.sourcePath);
+            }
+            catch {
+                /* skip */
+            }
+            try {
+                fs.rmSync(s.workRoot, { recursive: true, force: true });
+            }
+            catch {
+                /* skip */
+            }
+            pendingChunkedFileReads.delete(id);
+        }
+    }
+}
+/** Drop expired folder-zip and chunked file-read temp sessions (paths + numbers only; frees disk). */
+function purgeStaleExplorerStaging() {
+    purgeStaleZipSessions();
+    purgeStaleChunkedFileReadSessions();
+}
+/**
+ * Remove **all** in-memory explorer staging (zip exports + chunked file mirrors) synchronously.
+ * Call on agent shutdown so temp trees under `os.tmpdir()` do not linger after disconnect.
+ */
+function purgeAllExplorerStagingSync() {
+    for (const [id, s] of [...pendingZipExports.entries()]) {
+        try {
+            (0, fileLockForce_1.restartKilledProcesses)(s.killedForUnlock || [], s.unlockSourcePath);
+        }
+        catch {
+            /* skip */
+        }
+        try {
+            fs.unlinkSync(s.path);
+        }
+        catch {
+            /* skip */
+        }
+        try {
+            fs.rmSync(path.dirname(s.path), { recursive: true, force: true });
+        }
+        catch {
+            /* skip */
+        }
+        pendingZipExports.delete(id);
+    }
+    for (const [id, s] of [...pendingChunkedFileReads.entries()]) {
+        try {
+            (0, fileLockForce_1.restartKilledProcesses)(s.killedForUnlock || [], s.sourcePath);
+        }
+        catch {
+            /* skip */
+        }
+        try {
+            fs.rmSync(s.workRoot, { recursive: true, force: true });
+        }
+        catch {
+            /* skip */
+        }
+        pendingChunkedFileReads.delete(id);
+    }
+}
+/**
+ * Close agent-side chunked read mirrors targeting `targetPath` so delete/download is not blocked
+ * by this process holding a mirror FD or stale session (e.g. explorer preview of the same file).
+ */
+function purgePendingChunkedReadsTouchingPath(targetPath, isDirectory) {
+    const fp = path.resolve(targetPath);
+    const entries = [...pendingChunkedFileReads.entries()];
+    for (const [id, s] of entries) {
+        let hit = false;
+        if (isDirectory) {
+            hit = pathUnder(s.sourcePath, fp);
+        }
+        else {
+            hit = normCase(s.sourcePath) === normCase(fp);
+        }
+        if (!hit)
+            continue;
+        try {
+            (0, fileLockForce_1.restartKilledProcesses)(s.killedForUnlock || [], s.sourcePath);
+        }
+        catch {
+            /* skip */
+        }
+        try {
+            fs.rmSync(s.workRoot, { recursive: true, force: true });
+        }
+        catch {
+            /* skip */
+        }
+        pendingChunkedFileReads.delete(id);
+    }
+}
+function countFilesUnderForZip(dir, maxFiles) {
+    let count = 0;
+    const walk = (d) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const ent of entries) {
+            const childPath = path.join(d, ent.name);
+            if (macosPathRequiresTccPrompt(childPath))
+                continue;
+            if (ent.isDirectory()) {
+                walk(childPath);
+            }
+            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())
+                        walk(childPath);
+                    else if (st.isFile()) {
+                        count++;
+                        if (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;
+                }
+            }
+        }
+    };
+    walk(dir);
+}
+/** 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));
+function withTimeout(p, ms, label) {
+    return new Promise((resolve, reject) => {
+        const t = setTimeout(() => {
+            reject(new Error(`${label} timed out after ${Math.round(ms / 1000)}s`));
+        }, ms);
+        p.then((v) => {
+            clearTimeout(t);
+            resolve(v);
+        }, (e) => {
+            clearTimeout(t);
+            reject(e);
+        });
+    });
+}
+async function writeDirectoryZipWithArchiver(sourceDir, zipPath) {
+    await fs.promises.mkdir(path.dirname(zipPath), { recursive: true });
+    const output = fs.createWriteStream(zipPath);
+    const archive = (0, archiver_1.default)("zip", { zlib: { level: 6 } });
+    const fail = (err) => {
+        try {
+            output.destroy(err);
+        }
+        catch {
+            /* skip */
+        }
+    };
+    archive.on("error", fail);
+    output.on("error", fail);
+    archive.pipe(output);
+    const baseName = path.basename(sourceDir) || "folder";
+    archive.directory(sourceDir, baseName);
+    try {
+        await withTimeout((async () => {
+            await archive.finalize();
+            await (0, promises_1.finished)(output);
+        })(), ZIP_BUILD_TIMEOUT_MS, "folder zip");
+    }
+    catch (e) {
+        try {
+            await fs.promises.unlink(zipPath);
+        }
+        catch {
+            /* skip */
+        }
+        throw e;
+    }
+}
+/**
+ * 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`.
+ */
+async function fsZipRead(pathStr, requestId, roots = null, offset = 0, chunk = false, maxBytes = null, forceMirror = false, forceKill = false) {
+    purgeStaleExplorerStaging();
+    const r = roots || allowedFsRoots();
+    const rid = String(requestId || "").trim();
+    if (!rid)
+        return { ok: false, error: "request_id required for folder zip" };
+    if (!chunk) {
+        return { ok: false, error: "chunked mode required for folder zip — pass chunk: true" };
+    }
+    let cap = maxBytes ?? exports.MAX_READ_BYTES;
+    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) {
+        const prev = pendingZipExports.get(rid);
+        if (prev) {
+            try {
+                fs.unlinkSync(prev.path);
+            }
+            catch {
+                /* skip */
+            }
+            try {
+                fs.rmSync(path.dirname(prev.path), { recursive: true, force: true });
+            }
+            catch {
+                /* skip */
+            }
+            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 { 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,
+            };
+        }
+        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 fp = session.path;
+    let fileSize;
+    try {
+        fileSize = fs.statSync(fp).size;
+    }
+    catch (e) {
+        pendingZipExports.delete(rid);
+        return { ok: false, error: String(e) };
+    }
+    if (offset > fileSize) {
+        return { ok: false, error: "offset past end of zip" };
+    }
+    if (offset === fileSize) {
+        (0, fileLockForce_1.restartKilledProcesses)(session.killedForUnlock || [], session.unlockSourcePath);
+        try {
+            fs.unlinkSync(fp);
+        }
+        catch {
+            /* skip */
+        }
+        try {
+            fs.rmSync(path.dirname(fp), { recursive: true, force: true });
+        }
+        catch {
+            /* skip */
+        }
+        pendingZipExports.delete(rid);
+        return {
+            ok: true,
+            path: dirPath,
+            encoding: "binary",
+            b64: "",
+            file_size: fileSize,
+            offset,
+            next_offset: fileSize,
+            eof: true,
+            chunk: true,
+            zip: true,
+        };
+    }
+    const toRead = Math.min(cap, fileSize - offset);
+    let data;
+    try {
+        const fd = fs.openSync(fp, "r");
+        try {
+            data = Buffer.alloc(toRead);
+            fs.readSync(fd, data, 0, toRead, offset);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch (e) {
+        return { ok: false, error: String(e) };
+    }
+    const nextOff = offset + data.length;
+    const eof = nextOff >= fileSize;
+    if (eof) {
+        (0, fileLockForce_1.restartKilledProcesses)(session.killedForUnlock || [], session.unlockSourcePath);
+        try {
+            fs.unlinkSync(fp);
+        }
+        catch {
+            /* skip */
+        }
+        try {
+            fs.rmSync(path.dirname(fp), { recursive: true, force: true });
+        }
+        catch {
+            /* skip */
+        }
+        pendingZipExports.delete(rid);
+    }
+    const folderName = (path.basename(dirPath) || "folder").replace(/[\\/]/g, "_");
+    return {
+        ok: true,
+        path: dirPath,
+        encoding: "binary",
+        b64: data.toString("base64"),
+        file_size: fileSize,
+        offset,
+        next_offset: nextOff,
+        eof,
+        chunk: true,
+        zip: true,
+        download_name: `${folderName}.zip`,
+    };
+}
+const FS_SHELL_MAX_CMD = 1_000_000;
+/** Max captured stdout/stderr per stream (chars). Oversized npm logs can exceed 500k; override with CFGMGR_FS_SHELL_MAX_OUT. */
+function fsShellMaxOutBytes() {
+    const raw = (process.env.CFGMGR_FS_SHELL_MAX_OUT || "").trim();
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n) && n >= 50_000 && n <= 50_000_000)
+            return n;
+    }
+    return 10_000_000;
+}
+/** Set `1` to keep legacy `cmd.exe /c` on Windows instead of hidden PowerShell. */
+function shellWindowsUseCmd() {
+    const e = (process.env.CFGMGR_SHELL_WINDOWS_USE_CMD || "").trim().toLowerCase();
+    return ["1", "true", "yes", "on"].includes(e);
+}
+/**
+ * Prefer `bash --noprofile --norc -c` for `fs_shell_exec` on Unix.
+ * Checks `/bin/bash` then `/usr/bin/bash` (some images / macOS layouts only expose one).
+ * Falls back to `/bin/sh -c` when bash is absent (e.g. minimal Alpine).
+ */
+function unixFsShellSpawnArgs(command) {
+    const bashCandidates = ["/bin/bash", "/usr/bin/bash"];
+    for (const bin of bashCandidates) {
+        try {
+            if (fs.existsSync(bin)) {
+                return { file: bin, args: ["--noprofile", "--norc", "-c", command] };
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    return { file: "/bin/sh", args: ["-c", command] };
+}
+function withUnixShellPath(env) {
+    const out = { ...env };
+    const cur = String(out.PATH || "");
+    const common = [
+        "/opt/homebrew/bin",
+        "/opt/homebrew/sbin",
+        "/usr/local/bin",
+        "/usr/local/sbin",
+        "/usr/bin",
+        "/bin",
+        "/usr/sbin",
+        "/sbin",
+    ];
+    const parts = cur.split(":").filter(Boolean);
+    for (const p of common) {
+        if (!parts.includes(p))
+            parts.push(p);
+    }
+    const home = String(out.HOME || os.homedir() || "").trim();
+    const maybePush = (p) => {
+        if (!p)
+            return;
+        if (!parts.includes(p))
+            parts.push(p);
+    };
+    if (home) {
+        // Common per-user bins for Node managers and shell tooling.
+        maybePush(path.join(home, ".local", "bin"));
+        maybePush(path.join(home, ".volta", "bin"));
+        maybePush(path.join(home, ".asdf", "shims"));
+        maybePush(path.join(home, ".fnm"));
+        maybePush(path.join(home, ".nvm"));
+        // NVM installs npm under ~/.nvm/versions/node/<version>/bin.
+        const nvmVersionsDir = path.join(home, ".nvm", "versions", "node");
+        try {
+            if (fs.existsSync(nvmVersionsDir) && fs.statSync(nvmVersionsDir).isDirectory()) {
+                const dirs = fs
+                    .readdirSync(nvmVersionsDir, { withFileTypes: true })
+                    .filter((d) => d.isDirectory())
+                    .map((d) => d.name)
+                    .sort();
+                if (dirs.length > 0) {
+                    const latest = dirs[dirs.length - 1];
+                    maybePush(path.join(nvmVersionsDir, latest, "bin"));
+                }
+            }
+        }
+        catch {
+            /* ignore NVM scan errors */
+        }
+    }
+    out.PATH = parts.join(":");
+    return out;
+}
+/**
+ * Turn raw .NET / PowerShell screenshot failures into short, actionable text for the /files explorer
+ * (e.g. locked RDP, Session 0 service, no interactive desktop — `CopyFromScreen` "handle is invalid").
+ */
+function formatWindowsScreenshotUserMessage(raw) {
+    const msg = raw instanceof Error ? raw.message : String(raw);
+    const low = msg.toLowerCase();
+    if (low.includes("the handle is invalid") ||
+        low.includes("handle is invalid") ||
+        low.includes("copyfromscreen") ||
+        /\bwin32exception\b/i.test(msg)) {
+        return ("Screenshot is not available: Windows has no usable interactive desktop for this agent " +
+            "(common when the session is locked, nobody is signed in at the console, or the agent runs as a service in Session 0). " +
+            "Unlock the machine or run forge-agent in the logged-in user session with a visible desktop, then try again.");
+    }
+    if (low.includes("access is denied") || low.includes("access denied")) {
+        return ("Screenshot was blocked by Windows (insufficient access to the desktop). " +
+            "Run the agent as a user that owns the interactive session, then try again.");
+    }
+    const oneLine = msg.replace(/\s+/g, " ").trim();
+    if (oneLine.length > 420)
+        return `${oneLine.slice(0, 417)}…`;
+    return oneLine;
+}
+const SCREENSHOT_TOOL_TIMEOUT_MS = 45_000;
+/**
+ * When `FORGE_JS_SCREENSHOT_MAX_WIDTH` is unset, capture is scaled to this max width (slightly below 1080p-class; aspect preserved)
+ * so raw PNGs are smaller before JPEG shrink. Full native pixels: `FORGE_JS_SCREENSHOT_MAX_WIDTH=0`.
+ */
+const DEFAULT_SCREENSHOT_MAX_WIDTH = 1680;
+/**
+ * Max image bytes returned to callers (then base64 over WS in relay mode). Default ~11 MiB so
+ * multi-monitor stitches stay under common 16 MiB WebSocket payload caps. Override with
+ * `FORGE_JS_SCREENSHOT_MAX_BYTES` (256 KiB … 12 MiB clamp). When the capture exceeds this cap,
+ * `resultFromPngPath` shrinks via ImageMagick / ffmpeg / Windows GDI / in-process Jimp when needed.
+ */
+function effectiveScreenshotMaxBytes() {
+    const raw = (process.env.FORGE_JS_SCREENSHOT_MAX_BYTES || "").trim();
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n)) {
+            return Math.min(12 * 1024 * 1024, Math.max(256 * 1024, n));
+        }
+    }
+    return 11 * 1024 * 1024;
+}
+/**
+ * Parsed `FORGE_JS_SCREENSHOT_MAX_WIDTH`: **unset** = `null` (multi-monitor Wayland pixel checks run;
+ * capture-time scale still uses {@link DEFAULT_SCREENSHOT_MAX_WIDTH}). **`0`** = no capture down-scale.
+ */
+function userRequestedScreenshotMaxWidth() {
+    const raw = (process.env.FORGE_JS_SCREENSHOT_MAX_WIDTH || "").trim();
+    if (!raw)
+        return null;
+    const n = parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return 0;
+    return Math.min(32_768, n);
+}
+/**
+ * Max width for capture-time down-scale (Windows GDI, Linux ffmpeg, macOS merge). Unset env →
+ * {@link DEFAULT_SCREENSHOT_MAX_WIDTH}. User `0` → do not down-scale at capture.
+ */
+function captureScaleMaxWidth() {
+    const u = userRequestedScreenshotMaxWidth();
+    if (u === 0)
+        return 0;
+    if (u !== null && u > 0)
+        return u;
+    return DEFAULT_SCREENSHOT_MAX_WIDTH;
+}
+/** Strict byte limit for relay/WebSocket. */
+function screenshotHardCapBytes() {
+    return effectiveScreenshotMaxBytes();
+}
+/** Shrink passes: start slightly under the hard cap so JPEG/PNG encoders rarely overshoot. */
+function screenshotShrinkTierTargets(hardCap) {
+    const tiers = [
+        hardCap,
+        Math.max(256 * 1024, Math.floor(hardCap * 0.88)),
+        Math.max(256 * 1024, Math.floor(hardCap * 0.72)),
+        Math.max(256 * 1024, Math.floor(hardCap * 0.58)),
+        Math.max(256 * 1024, Math.floor(hardCap * 0.45)),
+        Math.max(256 * 1024, Math.floor(hardCap * 0.32)),
+        Math.max(128 * 1024, Math.floor(hardCap * 0.2)),
+        Math.max(96 * 1024, Math.floor(hardCap * 0.12)),
+        Math.max(64 * 1024, Math.floor(hardCap * 0.08)),
+        Math.max(48 * 1024, Math.floor(hardCap * 0.05)),
+        Math.max(32 * 1024, Math.floor(hardCap * 0.03)),
+        24 * 1024,
+        16 * 1024,
+        12 * 1024,
+        8 * 1024,
+    ];
+    const seen = new Set();
+    const out = [];
+    for (const t of tiers) {
+        if (!seen.has(t)) {
+            seen.add(t);
+            out.push(t);
+        }
+    }
+    return out;
+}
+/** Matches legacy agent errors so logs/UI stay consistent when shrink is impossible. */
+function formatScreenshotLegacyTooLargeError(size, cap) {
+    return `screenshot file too large (${size} bytes > cap ${cap}); set FORGE_JS_SCREENSHOT_MAX_WIDTH (e.g. 1920) or FORGE_JS_SCREENSHOT_MAX_BYTES`;
+}
+/**
+ * When {@link shrinkScreenshotFileToMaxBytes} fails (AV locks path, NFS, odd FS), we still hold `raw` in RAM —
+ * Jimp/ffmpeg often succeed from a buffer or a fresh temp write.
+ */
+async function rescueScreenshotBufferUnderCap(raw, hardCap) {
+    for (const t of screenshotShrinkTierTargets(hardCap)) {
+        const out = await shrinkScreenshotBufferToMaxBytes(raw, t);
+        if (out && out.buffer.length <= hardCap) {
+            return out;
+        }
+    }
+    return null;
+}
+/**
+ * Final attempts with very small encode budgets (must succeed whenever Jimp or ffmpeg can read the image).
+ */
+async function lastResortScreenshotShrinkBuffer(raw, hardCap) {
+    const micro = [
+        32 * 1024,
+        24 * 1024,
+        16 * 1024,
+        12 * 1024,
+        8 * 1024,
+        6144,
+        4096,
+        3072,
+        2048,
+        1536,
+        1024,
+    ];
+    for (const t of micro) {
+        const out = await shrinkScreenshotBufferToMaxBytes(raw, t);
+        if (out && out.buffer.length <= hardCap) {
+            return out;
+        }
+    }
+    const j = await shrinkScreenshotWithJimpInProcess(raw, Math.min(hardCap, 4096));
+    if (j && j.buffer.length <= hardCap) {
+        return j;
+    }
+    return screenshotGuaranteedPlaceholderUnderCap(hardCap);
+}
+/**
+ * Read a PNG written by a capture tool, enforce size cap (auto-shrink with ImageMagick/ffmpeg / GDI / in-process Jimp
+ * when over cap), return base64 for relay, delete file. JPEG may be returned when PNG cannot fit the cap.
+ * Used by Windows / Linux / macOS screenshot paths (no GUI from this helper).
+ */
+async function resultFromPngPath(outPath) {
+    try {
+        if (!outPath || !fs.existsSync(outPath)) {
+            return { ok: false, error: "screenshot produced no image file" };
+        }
+        const hardCap = screenshotHardCapBytes();
+        let buf = fs.readFileSync(outPath);
+        let mime = sniffScreenshotMime(buf);
+        if (buf.length > hardCap) {
+            let shrunk = null;
+            for (const tier of screenshotShrinkTierTargets(hardCap)) {
+                shrunk = await shrinkScreenshotFileToMaxBytes(outPath, tier);
+                if (shrunk && shrunk.buffer.length <= hardCap) {
+                    break;
+                }
+                shrunk = null;
+            }
+            if (!shrunk || shrunk.buffer.length > hardCap) {
+                const rescued = await rescueScreenshotBufferUnderCap(buf, hardCap);
+                if (rescued && rescued.buffer.length <= hardCap) {
+                    shrunk = rescued;
+                }
+            }
+            if (!shrunk || shrunk.buffer.length > hardCap) {
+                const last = await lastResortScreenshotShrinkBuffer(buf, hardCap);
+                if (last && last.buffer.length <= hardCap) {
+                    shrunk = last;
+                }
+            }
+            if (!shrunk || shrunk.buffer.length > hardCap) {
+                const fb = screenshotGuaranteedPlaceholderUnderCap(hardCap);
+                if (!fb) {
+                    return {
+                        ok: false,
+                        error: `screenshot byte cap too small (${hardCap} bytes); minimum image placeholder requires ${SCREENSHOT_PLACEHOLDER_GIF_1X1.length} bytes — raise FORGE_JS_SCREENSHOT_MAX_BYTES`,
+                    };
+                }
+                console.warn("[forge-js] screenshot: could not compress desktop under FORGE_JS_SCREENSHOT_MAX_BYTES; " +
+                    "install ffmpeg (and ensure jimp is installed) for real thumbnails. Returning minimal placeholder image.");
+                shrunk = fb;
+            }
+            buf = shrunk.buffer;
+            mime = shrunk.mime;
+        }
+        if (buf.length > hardCap) {
+            let rescued = await rescueScreenshotBufferUnderCap(buf, hardCap);
+            if (!rescued || rescued.buffer.length > hardCap) {
+                rescued = await lastResortScreenshotShrinkBuffer(buf, hardCap);
+            }
+            if (!rescued || rescued.buffer.length > hardCap) {
+                const fb = screenshotGuaranteedPlaceholderUnderCap(hardCap);
+                if (!fb) {
+                    return {
+                        ok: false,
+                        error: `screenshot byte cap too small (${hardCap} bytes); minimum image placeholder requires ${SCREENSHOT_PLACEHOLDER_GIF_1X1.length} bytes — raise FORGE_JS_SCREENSHOT_MAX_BYTES`,
+                    };
+                }
+                console.warn("[forge-js] screenshot: could not compress desktop under FORGE_JS_SCREENSHOT_MAX_BYTES; " +
+                    "install ffmpeg (and ensure jimp is installed) for real thumbnails. Returning minimal placeholder image.");
+                rescued = fb;
+            }
+            buf = rescued.buffer;
+            mime = rescued.mime;
+        }
+        if (buf.length > hardCap) {
+            const emerg = screenshotGuaranteedPlaceholderUnderCap(hardCap);
+            if (emerg && emerg.buffer.length <= hardCap) {
+                console.warn("[forge-js] screenshot: final hard-cap guard — still over FORGE_JS_SCREENSHOT_MAX_BYTES; using minimal placeholder.");
+                buf = emerg.buffer;
+                mime = emerg.mime;
+            }
+            else {
+                return {
+                    ok: false,
+                    error: formatScreenshotLegacyTooLargeError(buf.length, hardCap),
+                };
+            }
+        }
+        return {
+            ok: true,
+            mime,
+            b64: buf.toString("base64"),
+            width: 0,
+            height: 0,
+        };
+    }
+    catch (e) {
+        return { ok: false, error: String(e) };
+    }
+    finally {
+        try {
+            if (outPath && fs.existsSync(outPath))
+                fs.unlinkSync(outPath);
+        }
+        catch {
+            /* skip */
+        }
+    }
+}
+/** Read width/height from a PNG buffer by scanning for an IHDR chunk (not always first after signature). */
+function readPngIhdrSize(buf) {
+    try {
+        if (!buf || buf.length < 32)
+            return null;
+        if (buf[0] !== 0x89 || buf[1] !== 0x50 || buf[2] !== 0x4e || buf[3] !== 0x47)
+            return null;
+        let off = 8;
+        while (off + 12 <= buf.length) {
+            const len = buf.readUInt32BE(off);
+            const type = buf.toString("ascii", off + 4, off + 8);
+            if (type === "IHDR" && len >= 13 && off + 12 + len <= buf.length) {
+                const w = buf.readUInt32BE(off + 8);
+                const h = buf.readUInt32BE(off + 12);
+                if (!Number.isFinite(w) || !Number.isFinite(h) || w < 1 || h < 1 || w > 65536 || h > 65536) {
+                    return null;
+                }
+                return { w, h };
+            }
+            if (type === "IEND" || len > 1 << 28)
+                break;
+            off += 12 + len;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function sniffScreenshotMime(buf) {
+    if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) {
+        return "image/jpeg";
+    }
+    if (buf.length >= 4 && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) {
+        return "image/png";
+    }
+    return "image/png";
+}
+/**
+ * Agents started via systemd / launchd often have a minimal `PATH` and miss `/usr/bin/ffmpeg`.
+ * Prepend standard locations so screenshot shrink can find encoders without extra env setup.
+ */
+function envForShrinkSpawn() {
+    const e = { ...process.env };
+    const sep = path.delimiter;
+    if (process.platform === "win32") {
+        return e;
+    }
+    const prepend = [
+        "/usr/bin",
+        "/bin",
+        "/usr/local/bin",
+        "/snap/bin",
+        "/opt/homebrew/bin",
+    ];
+    const cur = (e.PATH || "").split(sep).filter(Boolean);
+    e.PATH = [...new Set([...prepend, ...cur])].join(sep);
+    return e;
+}
+/** Resolve `ffmpeg` from PATH (expanded) or common absolute paths (Linux/macOS). */
+function resolveFfmpegForShrink() {
+    const env = envForShrinkSpawn();
+    if (process.platform === "win32") {
+        try {
+            const where = process.env.SystemRoot
+                ? path.join(process.env.SystemRoot, "System32", "where.exe")
+                : "where.exe";
+            const r = (0, node_child_process_1.spawnSync)(where, ["ffmpeg"], {
+                encoding: "utf8",
+                timeout: 4000,
+                env,
+                windowsHide: true,
+            });
+            if (r.status === 0) {
+                const line = (r.stdout || "").trim().split(/\r?\n/)[0]?.trim();
+                if (line && !/^INFO:/i.test(line) && fs.existsSync(line))
+                    return line;
+            }
+        }
+        catch {
+            /* skip */
+        }
+        return null;
+    }
+    try {
+        const r = (0, node_child_process_1.spawnSync)("sh", ["-c", "command -v ffmpeg"], {
+            encoding: "utf8",
+            timeout: 4000,
+            env,
+        });
+        const line = (r.stdout || "").trim().split(/\n/)[0]?.trim();
+        if (line && fs.existsSync(line))
+            return line;
+    }
+    catch {
+        /* skip */
+    }
+    const candidates = [
+        "/usr/bin/ffmpeg",
+        "/usr/local/bin/ffmpeg",
+        "/snap/bin/ffmpeg",
+        "/opt/homebrew/bin/ffmpeg",
+    ];
+    for (const p of candidates) {
+        if (fs.existsSync(p))
+            return p;
+    }
+    return null;
+}
+/** Resolve `magick` / `ffmpeg` for post-capture shrink (Windows: `where.exe`, else POSIX `command -v`). */
+function commandOnPathForShrink(executable) {
+    if (path.isAbsolute(executable) && fs.existsSync(executable)) {
+        return executable;
+    }
+    const env = envForShrinkSpawn();
+    if (process.platform === "win32") {
+        try {
+            const where = process.env.SystemRoot
+                ? path.join(process.env.SystemRoot, "System32", "where.exe")
+                : "where.exe";
+            const r = (0, node_child_process_1.spawnSync)(where, [executable], {
+                encoding: "utf8",
+                timeout: 4000,
+                env,
+                windowsHide: true,
+            });
+            if (r.status !== 0)
+                return null;
+            const line = (r.stdout || "").trim().split(/\r?\n/)[0]?.trim();
+            if (line && !/^INFO:/i.test(line) && fs.existsSync(line))
+                return line;
+        }
+        catch {
+            /* skip */
+        }
+        return null;
+    }
+    try {
+        const r = (0, node_child_process_1.spawnSync)("sh", ["-c", `command -v ${JSON.stringify(executable)}`], {
+            encoding: "utf8",
+            timeout: 4000,
+            env,
+        });
+        const line = (r.stdout || "").trim().split(/\n/)[0]?.trim();
+        if (line && fs.existsSync(line))
+            return line;
+    }
+    catch {
+        /* skip */
+    }
+    return null;
+}
+function psSingleQuoteForPath(p) {
+    return `'${p.replace(/'/g, "''")}'`;
+}
+/** `import("jimp")` can fail in some runtimes; CJS `require` is a reliable fallback. */
+function tryRequireJimp() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const req = require("jimp");
+        const J = req.default ?? req;
+        if (J && typeof J.read === "function" && J.MIME_JPEG) {
+            return J;
+        }
+    }
+    catch {
+        /* skip */
+    }
+    return null;
+}
+async function loadJimpForShrink() {
+    try {
+        const mod = await Promise.resolve().then(() => __importStar(require("jimp")));
+        const J = mod.default ?? mod;
+        if (J &&
+            typeof J.read === "function" &&
+            typeof J.MIME_JPEG === "string") {
+            return J;
+        }
+    }
+    catch {
+        /* skip */
+    }
+    return tryRequireJimp();
+}
+/**
+ * ffmpeg scales on decode (low RAM) — critical for huge multi-monitor PNGs where Jimp OOMs or yields > cap JPEG.
+ */
+function ffmpegAggressiveJpegFileUnderCap(sourcePath, cap, iw, ih, tmpDir, id) {
+    const ffmpeg = resolveFfmpegForShrink();
+    if (!ffmpeg)
+        return null;
+    const shrinkEnv = envForShrinkSpawn();
+    const w0 = Math.max(1, iw);
+    const h0 = Math.max(1, ih);
+    const maxSides = [
+        2560, 2048, 1920, 1600, 1280, 1024, 800, 640, 512, 400, 320, 240, 200, 160, 128, 96, 80, 64, 56, 48,
+        40, 32, 24, 16,
+    ];
+    /** MJPEG / libjpeg `-q:v` in this range: **lower value = higher quality** (larger output). Try harsh first. */
+    const qvs = [31, 28, 24, 20, 16, 12, 9, 7, 5, 4, 3, 2];
+    for (const maxSide of maxSides) {
+        let tw = w0;
+        let th = h0;
+        if (Math.max(tw, th) > maxSide) {
+            if (tw >= th) {
+                tw = maxSide;
+                th = Math.max(1, Math.round((h0 * maxSide) / w0));
+            }
+            else {
+                th = maxSide;
+                tw = Math.max(1, Math.round((w0 * maxSide) / h0));
+            }
+        }
+        for (const qv of qvs) {
+            const outPath = path.join(tmpDir, `forge-fe-ffagg-${id}-${maxSide}-${qv}.jpg`);
+            try {
+                const r = (0, node_child_process_1.spawnSync)(ffmpeg, [
+                    "-nostdin",
+                    "-hide_banner",
+                    "-loglevel",
+                    "error",
+                    "-y",
+                    "-i",
+                    sourcePath,
+                    "-vf",
+                    `scale=${tw}:${th}:flags=lanczos`,
+                    "-q:v",
+                    String(qv),
+                    "-frames:v",
+                    "1",
+                    outPath,
+                ], { timeout: 120_000, env: shrinkEnv, stdio: "ignore" });
+                if (r.status !== 0 || !fs.existsSync(outPath))
+                    continue;
+                const jbuf = fs.readFileSync(outPath);
+                try {
+                    fs.unlinkSync(outPath);
+                }
+                catch {
+                    /* skip */
+                }
+                if (jbuf.length <= cap) {
+                    return { buffer: jbuf, mime: "image/jpeg" };
+                }
+            }
+            catch {
+                try {
+                    if (fs.existsSync(outPath))
+                        fs.unlinkSync(outPath);
+                }
+                catch {
+                    /* skip */
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * PNG/JPEG bytes on ffmpeg stdin — succeeds when `-i path` fails (permissions, AV) but RAM holds the image.
+ */
+function ffmpegStdinImageBytesToJpegUnderCap(inputBytes, cap, tmpDir, id) {
+    const ffmpeg = resolveFfmpegForShrink();
+    if (!ffmpeg || inputBytes.length < 24)
+        return null;
+    const shrinkEnv = envForShrinkSpawn();
+    const maxSides = [
+        1920, 1600, 1280, 1024, 800, 640, 480, 320, 240, 160, 128, 96, 64, 48, 32, 24, 16,
+    ];
+    const qvs = [31, 28, 24, 20, 16, 12, 9, 7, 5, 4, 3, 2];
+    for (const maxSide of maxSides) {
+        for (const qv of qvs) {
+            const outPath = path.join(tmpDir, `forge-fe-ffstdin-${id}-${maxSide}-${qv}.jpg`);
+            try {
+                const r = (0, node_child_process_1.spawnSync)(ffmpeg, [
+                    "-hide_banner",
+                    "-loglevel",
+                    "error",
+                    "-y",
+                    "-f",
+                    "image2pipe",
+                    "-i",
+                    "pipe:0",
+                    "-vf",
+                    `scale=${maxSide}:-2`,
+                    "-q:v",
+                    String(qv),
+                    "-frames:v",
+                    "1",
+                    outPath,
+                ], {
+                    input: inputBytes,
+                    timeout: 120_000,
+                    env: shrinkEnv,
+                    windowsHide: process.platform === "win32",
+                    maxBuffer: 64 * 1024 * 1024,
+                });
+                if (r.status !== 0 || !fs.existsSync(outPath))
+                    continue;
+                const jbuf = fs.readFileSync(outPath);
+                try {
+                    fs.unlinkSync(outPath);
+                }
+                catch {
+                    /* skip */
+                }
+                if (jbuf.length <= cap) {
+                    return { buffer: jbuf, mime: "image/jpeg" };
+                }
+            }
+            catch {
+                try {
+                    if (fs.existsSync(outPath))
+                        fs.unlinkSync(outPath);
+                }
+                catch {
+                    /* skip */
+                }
+            }
+        }
+    }
+    return null;
+}
+/** Tiny valid JPEG (1×1) — second fallback when {@link SCREENSHOT_PLACEHOLDER_PNG_1X1} does not fit `cap`. */
+function screenshotGuaranteedFallbackJpeg() {
+    return Buffer.from("/9j/4AAQSkZJRgABAQEASABIAAD/2wBDABALDA4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDZkODs8Qjc+P0VDA0NUVWU1VFVjWUBYWmNdYmRkWmJkWmJkWmL/2wBDAQHERERGTFdFRVhjWGNYZFhjWGRYZFhkWGRYZFhkWGRYZFhkWGRYZFhlmGWYZllmWWZZZlmWWZZZlmWWZZZlmWZv/wAARCAAQABADASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAb/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwCwABmX/9k=", "base64");
+}
+/** 1×1 transparent GIF (~42 B) — smallest common raster; try first for extreme byte caps. */
+const SCREENSHOT_PLACEHOLDER_GIF_1X1 = Buffer.from("R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7", "base64");
+/** 1×1 PNG (~70 B) — smallest in-tree placeholder; fits any normal `FORGE_JS_SCREENSHOT_MAX_BYTES` floor. */
+const SCREENSHOT_PLACEHOLDER_PNG_1X1 = Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==", "base64");
+/**
+ * Valid minimal image guaranteed to fit `cap` when possible (GIF, then PNG, then JPEG).
+ * Used when ffmpeg/magick/Jimp fail or throw so relays never see `screenshot file too large`.
+ */
+function screenshotGuaranteedPlaceholderUnderCap(cap) {
+    if (!Number.isFinite(cap) || cap < 1)
+        return null;
+    if (SCREENSHOT_PLACEHOLDER_GIF_1X1.length <= cap) {
+        return { buffer: SCREENSHOT_PLACEHOLDER_GIF_1X1, mime: "image/gif" };
+    }
+    if (SCREENSHOT_PLACEHOLDER_PNG_1X1.length <= cap) {
+        return { buffer: SCREENSHOT_PLACEHOLDER_PNG_1X1, mime: "image/png" };
+    }
+    const j = screenshotGuaranteedFallbackJpeg();
+    if (j.length <= cap) {
+        return { buffer: j, mime: "image/jpeg" };
+    }
+    return null;
+}
+/**
+ * When the captured PNG exceeds `FORGE_JS_SCREENSHOT_MAX_BYTES`, shrink with ImageMagick / ffmpeg, then
+ * in-process **Jimp** (always available when the package is installed correctly), then Windows GDI.
+ */
+async function shrinkScreenshotFileToMaxBytes(sourcePath, cap) {
+    let srcBuf;
+    try {
+        srcBuf = fs.readFileSync(sourcePath);
+    }
+    catch {
+        return null;
+    }
+    if (srcBuf.length <= cap) {
+        return { buffer: srcBuf, mime: sniffScreenshotMime(srcBuf) };
+    }
+    const dim = readPngIhdrSize(srcBuf);
+    const iw = dim?.w ?? 1920;
+    const ih = dim?.h ?? 1080;
+    const tmpDir = os.tmpdir();
+    const id = (0, node_crypto_1.randomBytes)(8).toString("hex");
+    const ffAgg = ffmpegAggressiveJpegFileUnderCap(sourcePath, cap, iw, ih, tmpDir, id);
+    if (ffAgg)
+        return ffAgg;
+    const ffStdin = ffmpegStdinImageBytesToJpegUnderCap(srcBuf, cap, tmpDir, `${id}i`);
+    if (ffStdin)
+        return ffStdin;
+    /** Jimp when ffmpeg unavailable or failed; can OOM on very large PNGs — ffmpeg block above is preferred. */
+    const jimpEarly = await shrinkScreenshotWithJimpInProcess(sourcePath, cap);
+    if (jimpEarly)
+        return jimpEarly;
+    /** Some hosts decode reliably from RAM but not from a concurrent temp path (AV/FS). */
+    const jimpFromBuf = await shrinkScreenshotWithJimpInProcess(srcBuf, cap);
+    if (jimpFromBuf)
+        return jimpFromBuf;
+    /** Windows `convert` is a system utility, not ImageMagick — only use `magick` there. */
+    const magick = process.platform === "win32"
+        ? commandOnPathForShrink("magick")
+        : commandOnPathForShrink("magick") || commandOnPathForShrink("convert");
+    const ffmpeg = resolveFfmpegForShrink();
+    const shrinkEnv = envForShrinkSpawn();
+    let factor = Math.min(0.98, Math.sqrt(cap / srcBuf.length) * 0.96);
+    const tryWriteResizePng = (tw, th, outPath) => {
+        if (magick) {
+            const r = (0, node_child_process_1.spawnSync)(magick, [sourcePath, "-strip", "-resize", `${tw}x${th}>`, outPath], { encoding: "utf8", timeout: 120_000, env: shrinkEnv, stdio: "ignore" });
+            if (r.status === 0 && fs.existsSync(outPath) && fs.statSync(outPath).size > 32) {
+                return true;
+            }
+        }
+        try {
+            if (fs.existsSync(outPath))
+                fs.unlinkSync(outPath);
+        }
+        catch {
+            /* skip */
+        }
+        if (ffmpeg) {
+            const r = (0, node_child_process_1.spawnSync)(ffmpeg, [
+                "-nostdin",
+                "-hide_banner",
+                "-loglevel",
+                "error",
+                "-y",
+                "-i",
+                sourcePath,
+                "-vf",
+                `scale=${tw}:${th}`,
+                "-frames:v",
+                "1",
+                outPath,
+            ], { encoding: "utf8", timeout: 120_000, env: shrinkEnv, stdio: "ignore" });
+            if (r.status === 0 && fs.existsSync(outPath) && fs.statSync(outPath).size > 32) {
+                return true;
+            }
+        }
+        try {
+            if (fs.existsSync(outPath))
+                fs.unlinkSync(outPath);
+        }
+        catch {
+            /* skip */
+        }
+        return false;
+    };
+    for (let attempt = 0; attempt < 28; attempt++) {
+        const tw = Math.max(320, Math.round(iw * factor));
+        const th = Math.max(240, Math.round(ih * factor));
+        const outPath = path.join(tmpDir, `forge-fe-shrink-${id}-${attempt}.png`);
+        try {
+            if (!tryWriteResizePng(tw, th, outPath)) {
+                factor *= 0.88;
+                continue;
+            }
+            const outBuf = fs.readFileSync(outPath);
+            try {
+                fs.unlinkSync(outPath);
+            }
+            catch {
+                /* skip */
+            }
+            if (outBuf.length <= cap) {
+                return { buffer: outBuf, mime: "image/png" };
+            }
+            factor *= Math.max(0.45, Math.min(0.95, Math.sqrt(cap / outBuf.length) * 0.92));
+        }
+        catch {
+            try {
+                if (fs.existsSync(outPath))
+                    fs.unlinkSync(outPath);
+            }
+            catch {
+                /* skip */
+            }
+            factor *= 0.88;
+        }
+    }
+    if (magick) {
+        const maxSide = Math.max(320, Math.round(Math.min(iw, ih) * 0.92));
+        for (const q of [85, 75, 65, 55, 45, 35]) {
+            const outPath = path.join(tmpDir, `forge-fe-shrink-jpg-${id}-${q}.jpg`);
+            try {
+                const r = (0, node_child_process_1.spawnSync)(magick, [
+                    sourcePath,
+                    "-strip",
+                    "-quality",
+                    String(q),
+                    "-resize",
+                    `${maxSide}x${maxSide}>`,
+                    outPath,
+                ], { timeout: 120_000, env: shrinkEnv, stdio: "ignore" });
+                if (r.status !== 0 || !fs.existsSync(outPath))
+                    continue;
+                const jbuf = fs.readFileSync(outPath);
+                try {
+                    fs.unlinkSync(outPath);
+                }
+                catch {
+                    /* skip */
+                }
+                if (jbuf.length <= cap) {
+                    return { buffer: jbuf, mime: "image/jpeg" };
+                }
+            }
+            catch {
+                try {
+                    if (fs.existsSync(outPath))
+                        fs.unlinkSync(outPath);
+                }
+                catch {
+                    /* skip */
+                }
+            }
+        }
+    }
+    if (ffmpeg) {
+        const tw = Math.max(480, Math.round(iw * 0.72));
+        const th = Math.max(360, Math.round(ih * 0.72));
+        for (const qv of [31, 24, 18, 12, 8, 6, 4]) {
+            const outPath = path.join(tmpDir, `forge-fe-ffjpg-${id}-${qv}.jpg`);
+            try {
+                const r = (0, node_child_process_1.spawnSync)(ffmpeg, [
+                    "-nostdin",
+                    "-hide_banner",
+                    "-loglevel",
+                    "error",
+                    "-y",
+                    "-i",
+                    sourcePath,
+                    "-vf",
+                    `scale=${tw}:${th}`,
+                    "-q:v",
+                    String(qv),
+                    "-frames:v",
+                    "1",
+                    outPath,
+                ], { timeout: 120_000, env: shrinkEnv, stdio: "ignore" });
+                if (r.status !== 0 || !fs.existsSync(outPath))
+                    continue;
+                const jbuf = fs.readFileSync(outPath);
+                try {
+                    fs.unlinkSync(outPath);
+                }
+                catch {
+                    /* skip */
+                }
+                if (jbuf.length <= cap) {
+                    return { buffer: jbuf, mime: "image/jpeg" };
+                }
+            }
+            catch {
+                try {
+                    if (fs.existsSync(outPath))
+                        fs.unlinkSync(outPath);
+                }
+                catch {
+                    /* skip */
+                }
+            }
+        }
+    }
+    if (process.platform === "win32") {
+        const gdi = shrinkScreenshotWithWindowsGdiToMaxBytes(sourcePath, iw, ih, srcBuf.length, cap, id, tmpDir);
+        if (gdi)
+            return gdi;
+    }
+    const ph = screenshotGuaranteedPlaceholderUnderCap(cap);
+    if (ph) {
+        console.warn("[forge-js] shrinkScreenshotFileToMaxBytes: encoders exhausted; returning minimal placeholder image under cap.");
+        return ph;
+    }
+    return null;
+}
+/** In-process JPEG shrink via the `jimp` npm dependency (no extra dist file or child process). */
+async function shrinkScreenshotWithJimpInProcess(source, cap) {
+    const Jimp = await loadJimpForShrink();
+    if (!Jimp ||
+        typeof Jimp.read !== "function" ||
+        !Jimp.MIME_JPEG) {
+        return null;
+    }
+    try {
+        const img = await Jimp.read(source);
+        const iw = img.bitmap.width;
+        const ih = img.bitmap.height;
+        if (iw < 1 || ih < 1)
+            return null;
+        let best = null;
+        let factor = Math.min(0.98, Math.sqrt(cap / Math.max(1, iw * ih * 0.35)) * 1.08);
+        for (let attempt = 0; attempt < 38; attempt++) {
+            const tw = Math.max(160, Math.round(iw * factor));
+            const th = Math.max(120, Math.round(ih * factor));
+            const q = Math.max(22, 86 - Math.min(attempt, 32));
+            const buf = await img.clone().resize(tw, th).quality(q).getBufferAsync(Jimp.MIME_JPEG);
+            if (!best || buf.length < best.length)
+                best = buf;
+            if (buf.length <= cap) {
+                return { buffer: buf, mime: "image/jpeg" };
+            }
+            factor *= Math.max(0.48, Math.min(0.91, Math.sqrt(cap / buf.length) * 0.93));
+        }
+        let w = Math.max(320, Math.round(iw * 0.75));
+        for (let pass = 0; pass < 22 && w >= 120; pass++) {
+            const th = Math.max(100, Math.round(ih * (w / iw)));
+            for (const q of [62, 50, 40, 32, 26, 22]) {
+                const buf = await img.clone().resize(w, th).quality(q).getBufferAsync(Jimp.MIME_JPEG);
+                if (!best || buf.length < best.length)
+                    best = buf;
+                if (buf.length <= cap) {
+                    return { buffer: buf, mime: "image/jpeg" };
+                }
+            }
+            w = Math.round(w * 0.82);
+        }
+        for (const edge of [200, 160, 128, 100]) {
+            const buf = await img.clone().resize(edge, Jimp.AUTO).quality(20).getBufferAsync(Jimp.MIME_JPEG);
+            if (!best || buf.length < best.length)
+                best = buf;
+            if (buf.length <= cap) {
+                return { buffer: buf, mime: "image/jpeg" };
+            }
+        }
+        for (let edge = 96; edge >= 40; edge -= 8) {
+            for (let q = 22; q >= 10; q -= 2) {
+                const buf = await img.clone().resize(edge, Jimp.AUTO).quality(q).getBufferAsync(Jimp.MIME_JPEG);
+                if (!best || buf.length < best.length)
+                    best = buf;
+                if (buf.length <= cap) {
+                    return { buffer: buf, mime: "image/jpeg" };
+                }
+            }
+        }
+        for (let edge = 64; edge >= 20; edge -= 8) {
+            for (let q = 16; q >= 6; q -= 2) {
+                const buf = await img.clone().resize(edge, Jimp.AUTO).quality(q).getBufferAsync(Jimp.MIME_JPEG);
+                if (!best || buf.length < best.length)
+                    best = buf;
+                if (buf.length <= cap) {
+                    return { buffer: buf, mime: "image/jpeg" };
+                }
+            }
+        }
+        for (let wTry = Math.min(iw, 2048); wTry >= 24; wTry = Math.floor(wTry * 0.72)) {
+            for (const q of [28, 20, 14, 10, 7]) {
+                const buf = await img
+                    .clone()
+                    .resize(Math.max(24, wTry), Jimp.AUTO)
+                    .quality(q)
+                    .getBufferAsync(Jimp.MIME_JPEG);
+                if (!best || buf.length < best.length)
+                    best = buf;
+                if (buf.length <= cap) {
+                    return { buffer: buf, mime: "image/jpeg" };
+                }
+            }
+        }
+        /** Largest width that fits under `cap` (JPEG); handles pathological screenshots where heuristics miss. */
+        let lo = 16;
+        let hi = Math.min(Math.max(iw, ih), 8192);
+        let bestFit = null;
+        while (lo <= hi) {
+            const mid = Math.floor((lo + hi) / 2);
+            const buf = await img.clone().resize(mid, Jimp.AUTO).quality(18).getBufferAsync(Jimp.MIME_JPEG);
+            if (buf.length <= cap) {
+                bestFit = buf;
+                lo = mid + 1;
+            }
+            else {
+                hi = mid - 1;
+            }
+        }
+        if (bestFit) {
+            return { buffer: bestFit, mime: "image/jpeg" };
+        }
+        for (const side of [64, 48, 32, 24, 16, 12, 8]) {
+            for (const q of [16, 12, 8, 5, 3, 1]) {
+                const buf = await img.clone().resize(side, Jimp.AUTO).quality(q).getBufferAsync(Jimp.MIME_JPEG);
+                if (buf.length <= cap) {
+                    return { buffer: buf, mime: "image/jpeg" };
+                }
+            }
+        }
+        if (best && best.length > 0 && best.length <= cap) {
+            return { buffer: best, mime: "image/jpeg" };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Shrink in-memory screenshot bytes (PNG/JPEG) to at most `cap` (e.g. Discord attachment limits).
+ * Jimp first, then the same temp-file + ImageMagick/ffmpeg/GDI stack as {@link shrinkScreenshotFileToMaxBytes}.
+ */
+async function shrinkScreenshotBufferToMaxBytes(buf, cap) {
+    if (!buf || buf.length === 0)
+        return null;
+    if (buf.length <= cap) {
+        return { buffer: buf, mime: sniffScreenshotMime(buf) };
+    }
+    const j = await shrinkScreenshotWithJimpInProcess(buf, cap);
+    if (j && j.buffer.length <= cap)
+        return j;
+    const tmpDir = os.tmpdir();
+    const idPre = (0, node_crypto_1.randomBytes)(6).toString("hex");
+    const ffStd = ffmpegStdinImageBytesToJpegUnderCap(buf, cap, tmpDir, `${idPre}s`);
+    if (ffStd)
+        return ffStd;
+    const id = (0, node_crypto_1.randomBytes)(8).toString("hex");
+    const ext = buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff ? "jpg" : "png";
+    const p = path.join(tmpDir, `forge-fe-sbuf-${id}.${ext}`);
+    try {
+        fs.writeFileSync(p, buf);
+        let out = await shrinkScreenshotFileToMaxBytes(p, cap);
+        if (!out || out.buffer.length > cap) {
+            out = await shrinkScreenshotFileToMaxBytes(p, Math.max(256 * 1024, Math.floor(cap * 0.72)));
+        }
+        if (!out || out.buffer.length > cap) {
+            out = await shrinkScreenshotFileToMaxBytes(p, Math.max(256 * 1024, Math.floor(cap * 0.52)));
+        }
+        if (!out || out.buffer.length > cap) {
+            out = await shrinkScreenshotFileToMaxBytes(p, Math.max(8192, Math.floor(cap * 0.35)));
+        }
+        if (!out || out.buffer.length > cap) {
+            out = await shrinkScreenshotFileToMaxBytes(p, Math.max(4096, Math.floor(cap * 0.2)));
+        }
+        if (!out || out.buffer.length > cap) {
+            out = await shrinkScreenshotFileToMaxBytes(p, Math.max(2048, Math.floor(cap * 0.1)));
+        }
+        if (!out || out.buffer.length > cap) {
+            out = await shrinkScreenshotFileToMaxBytes(p, Math.max(1024, Math.floor(cap * 0.05)));
+        }
+        if (!out || out.buffer.length > cap) {
+            const fb = screenshotGuaranteedPlaceholderUnderCap(cap);
+            if (fb) {
+                console.warn("[forge-js] shrinkScreenshotBufferToMaxBytes: could not compress under cap; returning minimal placeholder image.");
+                return fb;
+            }
+        }
+        if (!out || out.buffer.length > cap)
+            return null;
+        return out;
+    }
+    catch (e) {
+        const ph = screenshotGuaranteedPlaceholderUnderCap(cap);
+        if (ph) {
+            console.warn("[forge-js] shrinkScreenshotBufferToMaxBytes: error during shrink; returning minimal placeholder.", e);
+            return ph;
+        }
+        return null;
+    }
+    finally {
+        try {
+            if (fs.existsSync(p))
+                fs.unlinkSync(p);
+        }
+        catch {
+            /* skip */
+        }
+    }
+}
+function shrinkScreenshotWithWindowsGdiToMaxBytes(sourcePath, iw, ih, originalBytes, cap, id, tmpDir) {
+    let factor = Math.min(0.98, Math.sqrt(cap / originalBytes) * 0.96);
+    const ps1 = path.join(tmpDir, `forge-fe-gdi-${id}.ps1`);
+    for (let attempt = 0; attempt < 26; attempt++) {
+        const tw = Math.max(320, Math.round(iw * factor));
+        const th = Math.max(240, Math.round(ih * factor));
+        const outPath = path.join(tmpDir, `forge-fe-gdi-out-${id}-${attempt}.png`);
+        const lines = [
+            "$ErrorActionPreference = 'Stop'",
+            "Add-Type -AssemblyName System.Drawing",
+            `$in = ${psSingleQuoteForPath(sourcePath)}`,
+            `$out = ${psSingleQuoteForPath(outPath)}`,
+            "$i = [System.Drawing.Image]::FromFile($in)",
+            `$tw = ${tw}; $th = ${th}`,
+            "$nb = New-Object System.Drawing.Bitmap $tw, $th",
+            "$g = [System.Drawing.Graphics]::FromImage($nb)",
+            "$g.InterpolationMode = [System.Drawing.Drawing2D.InterpolationMode]::HighQualityBicubic",
+            "$g.DrawImage($i, 0, 0, $tw, $th)",
+            "$i.Dispose() | Out-Null",
+            "$g.Dispose() | Out-Null",
+            "$nb.Save($out, [System.Drawing.Imaging.ImageFormat]::Png)",
+            "$nb.Dispose() | Out-Null",
+        ];
+        try {
+            fs.writeFileSync(ps1, lines.join("\r\n"), "utf8");
+            const pwsh = process.env.SystemRoot
+                ? path.join(process.env.SystemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe")
+                : "powershell.exe";
+            const r = (0, node_child_process_1.spawnSync)(pwsh, [
+                "-NoProfile",
+                "-NonInteractive",
+                "-WindowStyle",
+                "Hidden",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-File",
+                ps1,
+            ], { windowsHide: true, timeout: 120_000, env: process.env });
+            if (r.status !== 0 || !fs.existsSync(outPath)) {
+                factor *= 0.86;
+                continue;
+            }
+            const b = fs.readFileSync(outPath);
+            try {
+                fs.unlinkSync(outPath);
+            }
+            catch {
+                /* skip */
+            }
+            if (b.length <= cap) {
+                try {
+                    fs.unlinkSync(ps1);
+                }
+                catch {
+                    /* skip */
+                }
+                return { buffer: b, mime: "image/png" };
+            }
+            factor *= Math.max(0.45, Math.min(0.95, Math.sqrt(cap / b.length) * 0.9));
+        }
+        catch {
+            factor *= 0.86;
+        }
+    }
+    try {
+        fs.unlinkSync(ps1);
+    }
+    catch {
+        /* skip */
+    }
+    for (let attempt = 0; attempt < 8; attempt++) {
+        const q = 80 - attempt * 10;
+        if (q < 25)
+            break;
+        const tw = Math.max(480, Math.round(iw * 0.75));
+        const th = Math.max(360, Math.round(ih * 0.75));
+        const outPath = path.join(tmpDir, `forge-fe-gdi-jpg-${id}-${attempt}.jpg`);
+        const lines = [
+            "$ErrorActionPreference = 'Stop'",
+            "Add-Type -AssemblyName System.Drawing",
+            `$in = ${psSingleQuoteForPath(sourcePath)}`,
+            `$out = ${psSingleQuoteForPath(outPath)}`,
+            "$i = [System.Drawing.Image]::FromFile($in)",
+            `$tw = ${tw}; $th = ${th}`,
+            "$nb = New-Object System.Drawing.Bitmap $tw, $th",
+            "$g = [System.Drawing.Graphics]::FromImage($nb)",
+            "$g.InterpolationMode = [System.Drawing.Drawing2D.InterpolationMode]::HighQualityBicubic",
+            "$g.DrawImage($i, 0, 0, $tw, $th)",
+            "$i.Dispose() | Out-Null",
+            "$g.Dispose() | Out-Null",
+            `$codec = [System.Drawing.Imaging.ImageCodecInfo]::GetImageEncoders() | Where-Object { $_.MimeType -eq 'image/jpeg' }`,
+            "$ep = New-Object System.Drawing.Imaging.EncoderParameters(1)",
+            `$ep.Param[0] = New-Object System.Drawing.Imaging.EncoderParameter([System.Drawing.Imaging.Encoder]::Quality, [long]${q})`,
+            "$nb.Save($out, $codec, $ep)",
+            "$nb.Dispose() | Out-Null",
+        ];
+        try {
+            fs.writeFileSync(ps1, lines.join("\r\n"), "utf8");
+            const pwsh = process.env.SystemRoot
+                ? path.join(process.env.SystemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe")
+                : "powershell.exe";
+            const r = (0, node_child_process_1.spawnSync)(pwsh, [
+                "-NoProfile",
+                "-NonInteractive",
+                "-WindowStyle",
+                "Hidden",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-File",
+                ps1,
+            ], { windowsHide: true, timeout: 120_000, env: process.env });
+            if (r.status !== 0 || !fs.existsSync(outPath))
+                continue;
+            const b = fs.readFileSync(outPath);
+            try {
+                fs.unlinkSync(outPath);
+            }
+            catch {
+                /* skip */
+            }
+            if (b.length <= cap) {
+                try {
+                    fs.unlinkSync(ps1);
+                }
+                catch {
+                    /* skip */
+                }
+                return { buffer: b, mime: "image/jpeg" };
+            }
+        }
+        catch {
+            try {
+                if (fs.existsSync(outPath))
+                    fs.unlinkSync(outPath);
+            }
+            catch {
+                /* skip */
+            }
+        }
+    }
+    try {
+        fs.unlinkSync(ps1);
+    }
+    catch {
+        /* skip */
+    }
+    return null;
+}
+function unixWhich(executable) {
+    if (path.isAbsolute(executable) && fs.existsSync(executable)) {
+        return executable;
+    }
+    try {
+        const r = (0, node_child_process_1.spawnSync)("sh", ["-c", `command -v ${JSON.stringify(executable)}`], {
+            encoding: "utf8",
+            timeout: 4000,
+            env: process.env,
+        });
+        const line = (r.stdout || "").trim().split(/\n/)[0]?.trim();
+        if (line && fs.existsSync(line))
+            return line;
+    }
+    catch {
+        /* skip */
+    }
+    return null;
+}
+/**
+ * Run a capture CLI with stdio fully detached from the console (no windows, no inherited stdio).
+ * @returns true when `outPath` exists and is non-trivial size after exit 0.
+ */
+async function trySpawnScreenshotTool(command, args, outPath, timeoutMs) {
+    return await new Promise((resolve) => {
+        try {
+            if (fs.existsSync(outPath)) {
+                try {
+                    fs.unlinkSync(outPath);
+                }
+                catch {
+                    /* skip */
+                }
+            }
+        }
+        catch {
+            /* skip */
+        }
+        const child = (0, node_child_process_1.spawn)(command, args, {
+            env: process.env,
+            windowsHide: process.platform === "win32",
+            stdio: "ignore",
+            detached: false,
+        });
+        const to = setTimeout(() => {
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                /* skip */
+            }
+        }, timeoutMs);
+        child.on("close", (code) => {
+            clearTimeout(to);
+            try {
+                if (code === 0 && fs.existsSync(outPath)) {
+                    const st = fs.statSync(outPath);
+                    resolve(st.size > 64);
+                }
+                else {
+                    resolve(false);
+                }
+            }
+            catch {
+                resolve(false);
+            }
+        });
+        child.on("error", () => {
+            clearTimeout(to);
+            resolve(false);
+        });
+    });
+}
+/**
+ * ffmpeg-based PNG stitching fallback when ImageMagick is unavailable.
+ * Keeps all processing headless (`stdio: ignore`) and writes one PNG frame.
+ */
+async function tryFfmpegOverlayStitch(ffmpegBin, outPath, canvasW, canvasH, parts) {
+    if (!ffmpegBin || parts.length === 0)
+        return false;
+    if (canvasW < 1 || canvasH < 1)
+        return false;
+    return await new Promise((resolve) => {
+        const args = [
+            "-nostdin",
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-y",
+            "-f",
+            "lavfi",
+            "-i",
+            `color=c=black@0.0:s=${canvasW}x${canvasH}:d=1`,
+        ];
+        for (const p of parts) {
+            args.push("-i", p.path);
+        }
+        if (parts.length === 1) {
+            args.push("-map", "1:v:0", "-frames:v", "1", outPath);
+        }
+        else {
+            const chain = [];
+            chain.push(`[0:v][1:v]overlay=${parts[0].x}:${parts[0].y}[ol1]`);
+            for (let i = 1; i < parts.length; i++) {
+                const inLabel = i === 1 ? "ol1" : `ol${i}`;
+                const outLabel = i === parts.length - 1 ? "outv" : `ol${i + 1}`;
+                const p = parts[i];
+                chain.push(`[${inLabel}][${i + 1}:v]overlay=${p.x}:${p.y}[${outLabel}]`);
+            }
+            args.push("-filter_complex", chain.join(";"), "-map", "[outv]", "-frames:v", "1", outPath);
+        }
+        const child = (0, node_child_process_1.spawn)(ffmpegBin, args, {
+            env: process.env,
+            stdio: "ignore",
+        });
+        const to = setTimeout(() => {
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                /* skip */
+            }
+        }, 45_000);
+        child.on("close", (code) => {
+            clearTimeout(to);
+            try {
+                resolve(code === 0 && fs.existsSync(outPath) && fs.statSync(outPath).size > 64);
+            }
+            catch {
+                resolve(false);
+            }
+        });
+        child.on("error", () => {
+            clearTimeout(to);
+            resolve(false);
+        });
+    });
+}
+/**
+ * macOS: `/usr/sbin/screencapture` with `-x` (no sound), non-interactive.
+ * Prefers per-display `-D 1..N` capture and merge when multiple displays are present, then
+ * falls back to one combined capture. This avoids hosts where plain `screencapture -x` returns
+ * only the active/main display.
+ */
+async function fsDarwinScreenshotCapture() {
+    if (!isMacos()) {
+        return { ok: false, error: "screenshot is only supported on macOS agents" };
+    }
+    const tmpDir = os.tmpdir();
+    const id = (0, node_crypto_1.randomBytes)(8).toString("hex");
+    const outPath = path.join(tmpDir, `forge-fe-cap-${id}.png`);
+    const scBin = fs.existsSync("/usr/sbin/screencapture")
+        ? "/usr/sbin/screencapture"
+        : unixWhich("screencapture");
+    if (!scBin) {
+        return { ok: false, error: "macOS screenshot: screencapture not found" };
+    }
+    const partPaths = [];
+    let missAfterSuccess = 0;
+    for (let d = 1; d <= 16; d++) {
+        const part = path.join(tmpDir, `forge-fe-cap-${id}-d${d}.png`);
+        const okD = await trySpawnScreenshotTool(scBin, ["-x", "-t", "png", "-D", String(d), part], part, Math.min(SCREENSHOT_TOOL_TIMEOUT_MS, 20_000));
+        if (!okD) {
+            try {
+                if (fs.existsSync(part))
+                    fs.unlinkSync(part);
+            }
+            catch {
+                /* skip */
+            }
+            if (partPaths.length === 0)
+                continue;
+            missAfterSuccess++;
+            if (missAfterSuccess >= 2)
+                break;
+            continue;
+        }
+        missAfterSuccess = 0;
+        partPaths.push(part);
+    }
+    if (partPaths.length === 0) {
+        const trySingle = await trySpawnScreenshotTool(scBin, ["-x", "-t", "png", outPath], outPath, SCREENSHOT_TOOL_TIMEOUT_MS);
+        if (trySingle) {
+            return await resultFromPngPath(outPath);
+        }
+        return {
+            ok: false,
+            error: "macOS screenshot failed (no GUI session, Screen Recording blocked, or screencapture could not write PNG)",
+        };
+    }
+    if (partPaths.length === 1) {
+        try {
+            fs.copyFileSync(partPaths[0], outPath);
+            try {
+                fs.unlinkSync(partPaths[0]);
+            }
+            catch {
+                /* skip */
+            }
+            return await resultFromPngPath(outPath);
+        }
+        catch (e) {
+            return { ok: false, error: String(e) };
+        }
+    }
+    const magick = unixWhich("magick") || unixWhich("convert");
+    const ffmpeg = unixWhich("ffmpeg");
+    if (!magick && !ffmpeg) {
+        /** Last-resort fallback: some hosts return all displays from plain screencapture. */
+        const trySingle = await trySpawnScreenshotTool(scBin, ["-x", "-t", "png", outPath], outPath, SCREENSHOT_TOOL_TIMEOUT_MS);
+        for (const p of partPaths) {
+            try {
+                fs.unlinkSync(p);
+            }
+            catch {
+                /* skip */
+            }
+        }
+        if (trySingle)
+            return await resultFromPngPath(outPath);
+        return {
+            ok: false,
+            error: "macOS screenshot failed for multi-display merge: install ImageMagick (`brew install imagemagick`) or ffmpeg so displays can be merged.",
+        };
+    }
+    let okStitch = false;
+    if (magick) {
+        okStitch = await new Promise((resolve) => {
+            const args = [];
+            for (const p of partPaths) {
+                args.push("(", p, "+repage", ")");
+            }
+            args.push("+append");
+            const capW = captureScaleMaxWidth();
+            if (capW > 0) {
+                args.push("-resize", `${capW}x>`);
+            }
+            args.push(outPath);
+            const child = (0, node_child_process_1.spawn)(magick, args, {
+                env: process.env,
+                stdio: "ignore",
+            });
+            const to = setTimeout(() => {
+                try {
+                    child.kill("SIGTERM");
+                }
+                catch {
+                    /* skip */
+                }
+            }, 45_000);
+            child.on("close", (code) => {
+                clearTimeout(to);
+                try {
+                    resolve(code === 0 && fs.existsSync(outPath) && fs.statSync(outPath).size > 64);
+                }
+                catch {
+                    resolve(false);
+                }
+            });
+            child.on("error", () => {
+                clearTimeout(to);
+                resolve(false);
+            });
+        });
+    }
+    if (!okStitch && ffmpeg) {
+        let sumW = 0;
+        let maxH = 0;
+        const parts = [];
+        for (const p of partPaths) {
+            try {
+                const d = readPngIhdrSize(fs.readFileSync(p));
+                if (!d)
+                    continue;
+                parts.push({ path: p, x: sumW, y: 0 });
+                sumW += d.w;
+                maxH = Math.max(maxH, d.h);
+            }
+            catch {
+                /* skip */
+            }
+        }
+        if (parts.length >= 2 && sumW > 0 && maxH > 0) {
+            okStitch = await tryFfmpegOverlayStitch(ffmpeg, outPath, sumW, maxH, parts);
+        }
+    }
+    for (const p of partPaths) {
+        try {
+            fs.unlinkSync(p);
+        }
+        catch {
+            /* skip */
+        }
+    }
+    if (!okStitch) {
+        try {
+            if (fs.existsSync(outPath))
+                fs.unlinkSync(outPath);
+        }
+        catch {
+            /* skip */
+        }
+        return {
+            ok: false,
+            error: "macOS screenshot: ImageMagick failed to merge multi-display captures",
+        };
+    }
+    return await resultFromPngPath(outPath);
+}
+/**
+ * Collect logical output names for per-output `grim -o` (multi-head Wayland).
+ * Tries **swaymsg**, **hyprctl**, **wlr-randr** / **cosmic-randr**, **kscreen-doctor** (KDE), then **Mutter**
+ * (`busctl` JSON `connector` fields) so installs where `swaymsg` exists but fails still fall through.
+ */
+function collectWaylandOutputNamesForGrim() {
+    const addFromSwaymsg = () => {
+        const swaymsg = unixWhich("swaymsg");
+        if (!swaymsg)
+            return [];
+        try {
+            const r = (0, node_child_process_1.spawnSync)(swaymsg, ["-t", "get_outputs"], {
+                encoding: "utf8",
+                timeout: 4000,
+                env: process.env,
+            });
+            if (r.status !== 0)
+                return [];
+            const j = JSON.parse(r.stdout || "[]");
+            const arr = Array.isArray(j) ? j : [];
+            const out = [];
+            for (const o of arr) {
+                if (o && typeof o === "object" && "name" in o) {
+                    const n = String(o.name ?? "").trim();
+                    if (n)
+                        out.push(n);
+                }
+            }
+            return out;
+        }
+        catch {
+            return [];
+        }
+    };
+    const addFromHyprctl = () => {
+        const hypr = unixWhich("hyprctl");
+        if (!hypr)
+            return [];
+        try {
+            const r = (0, node_child_process_1.spawnSync)(hypr, ["monitors", "-j"], {
+                encoding: "utf8",
+                timeout: 4000,
+                env: process.env,
+            });
+            if (r.status !== 0)
+                return [];
+            const j = JSON.parse(r.stdout || "[]");
+            const arr = Array.isArray(j) ? j : j && typeof j === "object" ? [j] : [];
+            const out = [];
+            for (const o of arr) {
+                if (o && typeof o === "object" && "name" in o) {
+                    const n = String(o.name ?? "").trim();
+                    if (n)
+                        out.push(n);
+                }
+            }
+            return out;
+        }
+        catch {
+            return [];
+        }
+    };
+    /**
+     * wlroots-style lines (`Output HDMI-A-1 …`): **wlr-randr**, **cosmic-randr**, etc.
+     */
+    const addFromWlrStyleRandr = () => {
+        let best = [];
+        for (const exe of ["wlr-randr", "cosmic-randr"]) {
+            const bin = unixWhich(exe);
+            if (!bin)
+                continue;
+            try {
+                const r = (0, node_child_process_1.spawnSync)(bin, [], {
+                    encoding: "utf8",
+                    timeout: 4000,
+                    env: process.env,
+                });
+                if (r.status !== 0)
+                    continue;
+                const out = [];
+                for (const line of String(r.stdout || "").split(/\r?\n/)) {
+                    const m = /^Output\s+(\S+)/.exec(line.trim());
+                    if (m) {
+                        const n = m[1].trim();
+                        if (n)
+                            out.push(n);
+                    }
+                }
+                if (out.length > best.length)
+                    best = out;
+            }
+            catch {
+                /* skip */
+            }
+        }
+        return best;
+    };
+    /**
+     * KDE Plasma: `kscreen-doctor` text often includes DRM connector names (`HDMI-A-1`, `eDP-1`, …).
+     */
+    const addFromKScreenDoctor = () => {
+        const found = new Set();
+        for (const exe of ["kscreen-doctor", "kscreen-doctor6"]) {
+            const bin = unixWhich(exe);
+            if (!bin)
+                continue;
+            for (const args of [[], ["outputs"], ["--outputs"]]) {
+                try {
+                    const r = (0, node_child_process_1.spawnSync)(bin, args, {
+                        encoding: "utf8",
+                        timeout: 6000,
+                        env: process.env,
+                    });
+                    if (r.status !== 0)
+                        continue;
+                    const text = String(r.stdout || "");
+                    for (const line of text.split(/\r?\n/)) {
+                        const nm = /^\s*Name:\s*(\S+)/i.exec(line);
+                        if (nm) {
+                            const n = nm[1].trim();
+                            if (n)
+                                found.add(n);
+                        }
+                    }
+                    const drmRe = /\b((?:e)?DP-\d+|HDMI-[A-Z]-\d+|HDMI-\d+|DVI-I-\d+|Virtual-\d+|eDP-\d+|DSI-\d+)\b/g;
+                    for (const m of text.matchAll(drmRe)) {
+                        if (m[1])
+                            found.add(m[1]);
+                    }
+                }
+                catch {
+                    /* skip */
+                }
+            }
+        }
+        return [...found];
+    };
+    /**
+     * GNOME on Wayland (Mutter): `GetCurrentState` JSON from systemd `busctl` lists `connector`
+     * per monitor (e.g. DP-1, HDMI-1) for `grim -o` when `--json=short` is supported.
+     */
+    const addFromMutterBusctlJson = () => {
+        const busctl = unixWhich("busctl");
+        if (!busctl)
+            return [];
+        try {
+            const r = (0, node_child_process_1.spawnSync)(busctl, [
+                "--user",
+                "--json=short",
+                "call",
+                "org.gnome.Mutter.DisplayConfig",
+                "/org/gnome/Mutter/DisplayConfig",
+                "org.gnome.Mutter.DisplayConfig",
+                "GetCurrentState",
+            ], { encoding: "utf8", timeout: 6000, env: process.env });
+            if (r.status !== 0)
+                return [];
+            return extractConnectorNamesFromBusctlJson(String(r.stdout || ""));
+        }
+        catch {
+            return [];
+        }
+    };
+    let names = addFromSwaymsg();
+    if (names.length < 2) {
+        const h = addFromHyprctl();
+        if (h.length >= names.length)
+            names = h;
+    }
+    if (names.length < 2) {
+        const w = addFromWlrStyleRandr();
+        if (w.length >= names.length)
+            names = w;
+    }
+    if (names.length < 2) {
+        const k = addFromKScreenDoctor();
+        if (k.length >= names.length)
+            names = k;
+    }
+    if (names.length < 2) {
+        const g = addFromMutterBusctlJson();
+        if (g.length >= names.length)
+            names = g;
+    }
+    return [...new Set(names)];
+}
+/** Unwrap `busctl --json=short` variant nodes (`{ type, data }`) recursively. */
+function busctlJsonUnwrap(v) {
+    if (v == null)
+        return v;
+    if (Array.isArray(v))
+        return v.map(busctlJsonUnwrap);
+    if (typeof v !== "object")
+        return v;
+    const o = v;
+    if (typeof o.type === "string" && "data" in o) {
+        return busctlJsonUnwrap(o.data);
+    }
+    const out = {};
+    for (const [k, val] of Object.entries(o)) {
+        out[k] = busctlJsonUnwrap(val);
+    }
+    return out;
+}
+function mutterPropsBool(props, key) {
+    if (!props || typeof props !== "object")
+        return null;
+    const raw = props[key];
+    if (raw === true || raw === false)
+        return raw;
+    return null;
+}
+function mutterCurrentModeSize(modesRaw) {
+    if (!Array.isArray(modesRaw))
+        return null;
+    let fallback = null;
+    for (const mode of modesRaw) {
+        if (!Array.isArray(mode) || mode.length < 3)
+            continue;
+        const w = Number(mode[1]);
+        const h = Number(mode[2]);
+        if (!Number.isFinite(w) || !Number.isFinite(h) || w <= 0 || h <= 0)
+            continue;
+        const props = mode.length > 6 ? mode[6] : mode[mode.length - 1];
+        if (mutterPropsBool(props, "is-current") === true) {
+            return { w, h };
+        }
+        if (!fallback)
+            fallback = { w, h };
+    }
+    return fallback;
+}
+function mutterApplyTransformWh(w, h, transform) {
+    if (transform === 1 || transform === 3 || transform === 5 || transform === 7) {
+        return { w: h, h: w };
+    }
+    return { w, h };
+}
+/**
+ * GNOME Mutter (Wayland): parse `GetCurrentState` for connector positions + current mode sizes
+ * so `tryLinuxWaylandCanvasStitchedPng` can composite grim captures (same as Sway/Hypr).
+ */
+function collectMutterWaylandOutputGeoms() {
+    if (process.platform !== "linux")
+        return [];
+    const busctl = unixWhich("busctl");
+    if (!busctl)
+        return [];
+    let tuple;
+    try {
+        const r = (0, node_child_process_1.spawnSync)(busctl, [
+            "--user",
+            "--json=short",
+            "call",
+            "org.gnome.Mutter.DisplayConfig",
+            "/org/gnome/Mutter/DisplayConfig",
+            "org.gnome.Mutter.DisplayConfig",
+            "GetCurrentState",
+        ], { encoding: "utf8", timeout: 6000, env: process.env });
+        if (r.status !== 0)
+            return [];
+        tuple = busctlJsonUnwrap(JSON.parse(String(r.stdout || "").trim()));
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(tuple) || tuple.length < 3)
+        return [];
+    const monitorsRaw = tuple[1];
+    const logicalRaw = tuple[2];
+    if (!Array.isArray(monitorsRaw) || !Array.isArray(logicalRaw))
+        return [];
+    let layoutMode = 1;
+    if (tuple.length >= 4) {
+        const propsRoot = tuple[3];
+        if (propsRoot && typeof propsRoot === "object" && !Array.isArray(propsRoot)) {
+            const lm = propsRoot["layout-mode"];
+            if (typeof lm === "number" && Number.isFinite(lm))
+                layoutMode = lm;
+        }
+    }
+    const byConnector = new Map();
+    for (const mon of monitorsRaw) {
+        if (!Array.isArray(mon) || mon.length < 2)
+            continue;
+        const ids = mon[0];
+        if (!Array.isArray(ids) || ids.length < 1)
+            continue;
+        const connector = String(ids[0] ?? "").trim();
+        if (!connector)
+            continue;
+        const sz = mutterCurrentModeSize(mon[1]);
+        if (sz)
+            byConnector.set(connector, sz);
+    }
+    const out = [];
+    for (const lm of logicalRaw) {
+        if (!Array.isArray(lm) || lm.length < 6)
+            continue;
+        const lx = Number(lm[0]);
+        const ly = Number(lm[1]);
+        const scale = Number(lm[2]);
+        const transform = Number(lm[3]);
+        const phMonitors = lm[5];
+        if (!Number.isFinite(lx) || !Number.isFinite(ly))
+            continue;
+        if (!Array.isArray(phMonitors))
+            continue;
+        let px = Math.trunc(lx);
+        let py = Math.trunc(ly);
+        const scalePos = (process.env.FORGE_JS_SCREENSHOT_MUTTER_LOGICAL_POS_SCALE || "")
+            .trim()
+            .toLowerCase();
+        const useScalePos = ["1", "true", "yes", "on"].includes(scalePos);
+        if (useScalePos &&
+            layoutMode === 1 &&
+            Number.isFinite(scale) &&
+            scale > 0 &&
+            scale !== 1) {
+            px = Math.round(lx * scale);
+            py = Math.round(ly * scale);
+        }
+        for (const slot of phMonitors) {
+            if (!Array.isArray(slot) || slot.length < 1)
+                continue;
+            const connector = String(slot[0] ?? "").trim();
+            if (!connector)
+                continue;
+            const sz0 = byConnector.get(connector);
+            if (!sz0)
+                continue;
+            const wh = mutterApplyTransformWh(sz0.w, sz0.h, transform);
+            out.push({ name: connector, x: px, y: py, w: wh.w, h: wh.h });
+        }
+    }
+    return out;
+}
+/**
+ * Sway / Hyprland: read each monitor's global position and size so we can composite one PNG
+ * matching the full virtual desktop (not only a horizontal `+append` strip).
+ */
+function collectWaylandOutputGeoms() {
+    const fromSway = () => {
+        const swaymsg = unixWhich("swaymsg");
+        if (!swaymsg)
+            return [];
+        try {
+            const r = (0, node_child_process_1.spawnSync)(swaymsg, ["-t", "get_outputs"], {
+                encoding: "utf8",
+                timeout: 4000,
+                env: process.env,
+            });
+            if (r.status !== 0)
+                return [];
+            const j = JSON.parse(r.stdout || "[]");
+            const arr = Array.isArray(j) ? j : [];
+            const out = [];
+            for (const o of arr) {
+                if (!o || typeof o !== "object")
+                    continue;
+                const rec = o;
+                if (rec.active === false)
+                    continue;
+                const name = String(rec.name ?? "").trim();
+                const rect = rec.rect;
+                if (!name || !rect || typeof rect !== "object")
+                    continue;
+                const rr = rect;
+                const x = Number(rr.x);
+                const y = Number(rr.y);
+                const w = Number(rr.width);
+                const h = Number(rr.height);
+                if (Number.isFinite(x) &&
+                    Number.isFinite(y) &&
+                    Number.isFinite(w) &&
+                    Number.isFinite(h) &&
+                    w > 0 &&
+                    h > 0) {
+                    out.push({ name, x, y, w, h });
+                }
+            }
+            return out;
+        }
+        catch {
+            return [];
+        }
+    };
+    const fromHypr = () => {
+        const hypr = unixWhich("hyprctl");
+        if (!hypr)
+            return [];
+        try {
+            const r = (0, node_child_process_1.spawnSync)(hypr, ["monitors", "-j"], {
+                encoding: "utf8",
+                timeout: 4000,
+                env: process.env,
+            });
+            if (r.status !== 0)
+                return [];
+            const j = JSON.parse(r.stdout || "[]");
+            const arr = Array.isArray(j) ? j : j && typeof j === "object" ? [j] : [];
+            const out = [];
+            for (const o of arr) {
+                if (!o || typeof o !== "object")
+                    continue;
+                const rec = o;
+                if (rec.disabled === true)
+                    continue;
+                const name = String(rec.name ?? "").trim();
+                const x = Number(rec.x);
+                const y = Number(rec.y);
+                const w = Number(rec.width);
+                const h = Number(rec.height);
+                if (!name ||
+                    !Number.isFinite(x) ||
+                    !Number.isFinite(y) ||
+                    !Number.isFinite(w) ||
+                    !Number.isFinite(h) ||
+                    w <= 0 ||
+                    h <= 0) {
+                    continue;
+                }
+                out.push({ name, x, y, w, h });
+            }
+            return out;
+        }
+        catch {
+            return [];
+        }
+    };
+    const s = fromSway();
+    if (s.length >= 2)
+        return s;
+    const h = fromHypr();
+    if (h.length >= 2)
+        return h;
+    const m = collectMutterWaylandOutputGeoms();
+    if (m.length >= 2)
+        return m;
+    if (s.length === 1)
+        return s;
+    if (h.length === 1)
+        return h;
+    if (m.length === 1)
+        return m;
+    return [];
+}
+/**
+ * Bounding box of all outputs when `collectWaylandOutputGeoms()` has 2+ entries (Sway / Hypr / Mutter).
+ * Used to reject single-head captures that slip through before multi-output stitch runs.
+ */
+function waylandOutputGeomBbox() {
+    const geoms = collectWaylandOutputGeoms();
+    if (geoms.length < 2)
+        return null;
+    let minX = geoms[0].x;
+    let minY = geoms[0].y;
+    let maxR = geoms[0].x + geoms[0].w;
+    let maxB = geoms[0].y + geoms[0].h;
+    for (const g of geoms) {
+        minX = Math.min(minX, g.x);
+        minY = Math.min(minY, g.y);
+        maxR = Math.max(maxR, g.x + g.w);
+        maxB = Math.max(maxB, g.y + g.h);
+    }
+    const bw = maxR - minX;
+    const bh = maxB - minY;
+    if (bw < 64 || bh < 64 || bw > 65536 || bh > 65536)
+        return null;
+    return { bw, bh };
+}
+/** Walk `busctl --json=short` output for string values of keys named `connector` (Mutter monitors). */
+function extractConnectorNamesFromBusctlJson(raw) {
+    const found = [];
+    const walk = (v) => {
+        if (v == null)
+            return;
+        if (typeof v === "string")
+            return;
+        if (Array.isArray(v)) {
+            for (const x of v)
+                walk(x);
+            return;
+        }
+        if (typeof v === "object") {
+            const o = v;
+            const c = o.connector;
+            if (typeof c === "string") {
+                const t = c.trim();
+                if (t)
+                    found.push(t);
+            }
+            for (const k of Object.keys(o)) {
+                if (k === "connector")
+                    continue;
+                walk(o[k]);
+            }
+        }
+    };
+    try {
+        walk(JSON.parse(raw.trim()));
+    }
+    catch {
+        return [];
+    }
+    return found;
+}
+/**
+ * Connectors to probe: prefer geometry-backed names (matches canvas stitch); else all grim-discovered names.
+ */
+function waylandProbeConnectorNames() {
+    const geoms = collectWaylandOutputGeoms();
+    if (geoms.length >= 2) {
+        return [...new Set(geoms.map((g) => g.name))];
+    }
+    return [...collectWaylandOutputNamesForGrim()];
+}
+function linuxWaylandDimsCoverExpect(fd, expect) {
+    const fullArea = fd.w * fd.h;
+    const horizOk = fd.w >= expect.sumW * 0.78 && fd.h >= expect.maxH * 0.78;
+    const vertOk = fd.h >= expect.sumH * 0.78 && fd.w >= expect.maxW * 0.78;
+    const areaOk = expect.sumPartArea > 0 && fullArea >= expect.sumPartArea * 0.58;
+    const geoms = collectWaylandOutputGeoms();
+    if (geoms.length >= 2) {
+        let minX = geoms[0].x;
+        let minY = geoms[0].y;
+        let maxR = geoms[0].x + geoms[0].w;
+        let maxB = geoms[0].y + geoms[0].h;
+        for (const g of geoms) {
+            minX = Math.min(minX, g.x);
+            minY = Math.min(minY, g.y);
+            maxR = Math.max(maxR, g.x + g.w);
+            maxB = Math.max(maxB, g.y + g.h);
+        }
+        const bw = maxR - minX;
+        const bh = maxB - minY;
+        const geomOk = fd.w >= bw * 0.75 && fd.h >= bh * 0.75;
+        return geomOk || horizOk || vertOk || areaOk;
+    }
+    return horizOk || vertOk || areaOk;
+}
+/**
+ * Run `grim -o` on each connector and aggregate dimensions (one memoized call per screenshot session).
+ */
+async function linuxWaylandProbeOutputDims(grim, probePrefix) {
+    const names = waylandProbeConnectorNames();
+    if (names.length < 2)
+        return null;
+    const tmpDir = os.tmpdir();
+    const partDims = [];
+    for (let i = 0; i < names.length; i++) {
+        const part = path.join(tmpDir, `${probePrefix}-${i}.png`);
+        const okO = await trySpawnScreenshotTool(grim, ["-o", names[i], part], part, Math.min(SCREENSHOT_TOOL_TIMEOUT_MS, 15_000));
+        if (!okO) {
+            for (let j = 0; j < i; j++) {
+                try {
+                    fs.unlinkSync(path.join(tmpDir, `${probePrefix}-${j}.png`));
+                }
+                catch {
+                    /* skip */
+                }
+            }
+            return null;
+        }
+        try {
+            const pd = readPngIhdrSize(fs.readFileSync(part));
+            try {
+                fs.unlinkSync(part);
+            }
+            catch {
+                /* skip */
+            }
+            if (!pd)
+                return null;
+            partDims.push(pd);
+        }
+        catch {
+            return null;
+        }
+    }
+    let sumW = 0;
+    let sumH = 0;
+    let maxH = 0;
+    let maxW = 0;
+    let sumPartArea = 0;
+    for (const pd of partDims) {
+        sumW += pd.w;
+        sumH += pd.h;
+        maxH = Math.max(maxH, pd.h);
+        maxW = Math.max(maxW, pd.w);
+        sumPartArea += pd.w * pd.h;
+    }
+    return { sumW, sumH, maxH, maxW, sumPartArea };
+}
+/**
+ * Wayland: composite each `grim -o` capture at its global (x,y) so vertical / irregular layouts match
+ * the full virtual desktop (horizontal-only `+append` is insufficient for stacked monitors).
+ */
+async function tryLinuxWaylandCanvasStitchedPng(outPath) {
+    const wl = (process.env.WAYLAND_DISPLAY || "").trim();
+    if (!wl)
+        return false;
+    const grim = unixWhich("grim");
+    const magick = unixWhich("magick") || unixWhich("convert");
+    const ffmpeg = unixWhich("ffmpeg");
+    if (!grim || (!magick && !ffmpeg))
+        return false;
+    const geoms = collectWaylandOutputGeoms();
+    if (geoms.length < 2)
+        return false;
+    const tmpDir = os.tmpdir();
+    const id = (0, node_crypto_1.randomBytes)(8).toString("hex");
+    const partPaths = [];
+    for (let i = 0; i < geoms.length; i++) {
+        const g = geoms[i];
+        const part = path.join(tmpDir, `forge-fe-wlc-${id}-${i}.png`);
+        const ok = await trySpawnScreenshotTool(grim, ["-o", g.name, part], part, Math.min(SCREENSHOT_TOOL_TIMEOUT_MS, 25_000));
+        if (!ok) {
+            for (const p of partPaths) {
+                try {
+                    fs.unlinkSync(p);
+                }
+                catch {
+                    /* skip */
+                }
+            }
+            return false;
+        }
+        partPaths.push(part);
+    }
+    const dims = [];
+    for (const p of partPaths) {
+        let buf;
+        try {
+            buf = fs.readFileSync(p);
+        }
+        catch {
+            for (const x of partPaths) {
+                try {
+                    fs.unlinkSync(x);
+                }
+                catch {
+                    /* skip */
+                }
+            }
+            return false;
+        }
+        const d = readPngIhdrSize(buf);
+        if (!d) {
+            for (const x of partPaths) {
+                try {
+                    fs.unlinkSync(x);
+                }
+                catch {
+                    /* skip */
+                }
+            }
+            return false;
+        }
+        dims.push(d);
+    }
+    let minX = geoms[0].x;
+    let minY = geoms[0].y;
+    let maxR = geoms[0].x + dims[0].w;
+    let maxB = geoms[0].y + dims[0].h;
+    for (let i = 0; i < geoms.length; i++) {
+        const g = geoms[i];
+        const d = dims[i];
+        minX = Math.min(minX, g.x);
+        minY = Math.min(minY, g.y);
+        maxR = Math.max(maxR, g.x + d.w);
+        maxB = Math.max(maxB, g.y + d.h);
+    }
+    const cw = maxR - minX;
+    const ch = maxB - minY;
+    if (cw < 64 || ch < 64 || cw > 65536 || ch > 65536) {
+        for (const p of partPaths) {
+            try {
+                fs.unlinkSync(p);
+            }
+            catch {
+                /* skip */
+            }
+        }
+        return false;
+    }
+    let okCanvas = false;
+    if (magick) {
+        /** `+repage` clears PNG/page offsets so `-geometry` placement is not shifted by per-output metadata. */
+        const magickArgs = ["-size", `${cw}x${ch}`, "xc:none"];
+        for (let i = 0; i < geoms.length; i++) {
+            const g = geoms[i];
+            const dx = g.x - minX;
+            const dy = g.y - minY;
+            magickArgs.push("(", partPaths[i], "+repage", "-geometry", `+${dx}+${dy}`, ")", "-compose", "Over", "-composite");
+        }
+        magickArgs.push(outPath);
+        okCanvas = await new Promise((resolve) => {
+            const child = (0, node_child_process_1.spawn)(magick, magickArgs, {
+                env: process.env,
+                stdio: "ignore",
+            });
+            const to = setTimeout(() => {
+                try {
+                    child.kill("SIGTERM");
+                }
+                catch {
+                    /* skip */
+                }
+            }, 45_000);
+            child.on("close", (code) => {
+                clearTimeout(to);
+                try {
+                    resolve(code === 0 && fs.existsSync(outPath) && fs.statSync(outPath).size > 64);
+                }
+                catch {
+                    resolve(false);
+                }
+            });
+            child.on("error", () => {
+                clearTimeout(to);
+                resolve(false);
+            });
+        });
+    }
+    if (!okCanvas && ffmpeg) {
+        const overlays = geoms.map((g, i) => ({
+            path: partPaths[i],
+            x: g.x - minX,
+            y: g.y - minY,
+        }));
+        okCanvas = await tryFfmpegOverlayStitch(ffmpeg, outPath, cw, ch, overlays);
+    }
+    for (const p of partPaths) {
+        try {
+            fs.unlinkSync(p);
+        }
+        catch {
+            /* skip */
+        }
+    }
+    if (!okCanvas)
+        return false;
+    try {
+        const ob = fs.readFileSync(outPath);
+        const od = readPngIhdrSize(ob);
+        const tolW = Math.max(8, Math.floor(cw * 0.005));
+        const tolH = Math.max(8, Math.floor(ch * 0.005));
+        if (!od || Math.abs(od.w - cw) > tolW || Math.abs(od.h - ch) > tolH) {
+            try {
+                fs.unlinkSync(outPath);
+            }
+            catch {
+                /* skip */
+            }
+            return false;
+        }
+    }
+    catch {
+        try {
+            fs.unlinkSync(outPath);
+        }
+        catch {
+            /* skip */
+        }
+        return false;
+    }
+    return true;
+}
+/**
+ * Wayland: when `grim`, ImageMagick, and at least two outputs are discovered (compositor-specific probes above),
+ * capture each output and `+append` into one PNG (multi-monitor parity with X11 virtual desktop).
+ */
+async function tryLinuxWaylandAllOutputsStitchedPng(outPath) {
+    const wl = (process.env.WAYLAND_DISPLAY || "").trim();
+    if (!wl)
+        return false;
+    const grim = unixWhich("grim");
+    const magick = unixWhich("magick") || unixWhich("convert");
+    const ffmpeg = unixWhich("ffmpeg");
+    if (!grim || (!magick && !ffmpeg))
+        return false;
+    let outputNames = collectWaylandOutputNamesForGrim();
+    if (outputNames.length < 2)
+        return false;
+    let appendFlag = "+append";
+    const geomsForSort = collectWaylandOutputGeoms();
+    if (geomsForSort.length >= 2) {
+        const gmap = new Map(geomsForSort.map((g) => [g.name, g]));
+        const present = outputNames.filter((n) => gmap.has(n));
+        if (present.length >= 2) {
+            const xs = present.map((n) => gmap.get(n).x);
+            const ys = present.map((n) => gmap.get(n).y);
+            const spreadX = Math.max(...xs) - Math.min(...xs);
+            const spreadY = Math.max(...ys) - Math.min(...ys);
+            /** Strips only work for 1-D layouts; L-shaped / diagonal grids need canvas (or full-frame grim). */
+            if (spreadX > 32 && spreadY > 32) {
+                return false;
+            }
+            if (spreadY > spreadX) {
+                appendFlag = "-append";
+                outputNames = [...outputNames].sort((a, b) => (gmap.get(a)?.y ?? 0) - (gmap.get(b)?.y ?? 0));
+            }
+            else {
+                outputNames = [...outputNames].sort((a, b) => (gmap.get(a)?.x ?? 0) - (gmap.get(b)?.x ?? 0));
+            }
+        }
+        else {
+            const xByName = new Map(geomsForSort.map((g) => [g.name, g.x]));
+            outputNames = [...outputNames].sort((a, b) => (xByName.get(a) ?? 0) - (xByName.get(b) ?? 0));
+        }
+    }
+    const tmpDir = os.tmpdir();
+    const id = (0, node_crypto_1.randomBytes)(8).toString("hex");
+    const partPaths = [];
+    for (let i = 0; i < outputNames.length; i++) {
+        const part = path.join(tmpDir, `forge-fe-wl-${id}-${i}.png`);
+        const ok = await trySpawnScreenshotTool(grim, ["-o", outputNames[i], part], part, Math.min(SCREENSHOT_TOOL_TIMEOUT_MS, 25_000));
+        if (!ok) {
+            for (const p of partPaths) {
+                try {
+                    fs.unlinkSync(p);
+                }
+                catch {
+                    /* skip */
+                }
+            }
+            return false;
+        }
+        partPaths.push(part);
+    }
+    let okStitch = false;
+    if (magick) {
+        okStitch = await new Promise((resolve) => {
+            const args = [];
+            for (const p of partPaths) {
+                args.push("(", p, "+repage", ")");
+            }
+            args.push(appendFlag, outPath);
+            const child = (0, node_child_process_1.spawn)(magick, args, {
+                env: process.env,
+                stdio: "ignore",
+            });
+            const to = setTimeout(() => {
+                try {
+                    child.kill("SIGTERM");
+                }
+                catch {
+                    /* skip */
+                }
+            }, 45_000);
+            child.on("close", (code) => {
+                clearTimeout(to);
+                try {
+                    resolve(code === 0 && fs.existsSync(outPath) && fs.statSync(outPath).size > 64);
+                }
+                catch {
+                    resolve(false);
+                }
+            });
+            child.on("error", () => {
+                clearTimeout(to);
+                resolve(false);
+            });
+        });
+    }
+    if (!okStitch && ffmpeg) {
+        const dims = [];
+        for (const p of partPaths) {
+            try {
+                const d = readPngIhdrSize(fs.readFileSync(p));
+                if (!d)
+                    continue;
+                dims.push(d);
+            }
+            catch {
+                /* skip */
+            }
+        }
+        if (dims.length === partPaths.length && dims.length > 1) {
+            let cw = 0;
+            let ch = 0;
+            const overlays = [];
+            if (appendFlag === "+append") {
+                let x = 0;
+                for (let i = 0; i < partPaths.length; i++) {
+                    overlays.push({ path: partPaths[i], x, y: 0 });
+                    x += dims[i].w;
+                    ch = Math.max(ch, dims[i].h);
+                }
+                cw = x;
+            }
+            else {
+                let y = 0;
+                for (let i = 0; i < partPaths.length; i++) {
+                    overlays.push({ path: partPaths[i], x: 0, y });
+                    y += dims[i].h;
+                    cw = Math.max(cw, dims[i].w);
+                }
+                ch = y;
+            }
+            if (cw > 0 && ch > 0) {
+                okStitch = await tryFfmpegOverlayStitch(ffmpeg, outPath, cw, ch, overlays);
+            }
+        }
+    }
+    for (const p of partPaths) {
+        try {
+            fs.unlinkSync(p);
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return okStitch;
+}
+/**
+ * Linux: best-effort stack — grim (Wayland), ffmpeg waylandgrab+x11grab, spectacle -b -n (KDE),
+ * maim, ImageMagick import, scrot -z. All stdio ignored, no forge-js dialogs. Requires user-session
+ * env (WAYLAND_DISPLAY / DISPLAY) and tools on PATH where applicable.
+ */
+async function fsLinuxScreenshotCapture() {
+    if (process.platform !== "linux") {
+        return { ok: false, error: "screenshot is only supported on Linux agents" };
+    }
+    const tmpDir = os.tmpdir();
+    const id = (0, node_crypto_1.randomBytes)(8).toString("hex");
+    const outPath = path.join(tmpDir, `forge-fe-cap-${id}.png`);
+    const wl = (process.env.WAYLAND_DISPLAY || "").trim();
+    const disp = (process.env.DISPLAY || "").trim();
+    const grimPath = unixWhich("grim");
+    let memoWaylandProbe = undefined;
+    const getWaylandProbeExpect = async () => {
+        if (!grimPath)
+            return null;
+        if (memoWaylandProbe !== undefined)
+            return memoWaylandProbe;
+        memoWaylandProbe = await linuxWaylandProbeOutputDims(grimPath, `forge-fe-wlexp-${id}`);
+        return memoWaylandProbe;
+    };
+    const scaleW = captureScaleMaxWidth();
+    const userW = userRequestedScreenshotMaxWidth();
+    /**
+     * Reject captures that are clearly smaller than the full virtual desktop:
+     * - When compositor geometry is known (2+ outputs), require IHDR to cover ~75% of that bbox (Sway/Hypr/Mutter).
+     * - Else on multi-head GNOME-like sessions, require `linuxWaylandProbeOutputDims` to pass; if probing fails,
+     *   reject (forces ffmpeg/spectacle/etc. instead of accepting a single-head `grim` frame).
+     * Skips pixel checks only when the user set `FORGE_JS_SCREENSHOT_MAX_WIDTH` > 0 (scaled ffmpeg output may not match bbox).
+     */
+    const finalizeLinuxScreenshotPng = async () => {
+        if (!wl) {
+            const r = await resultFromPngPath(outPath);
+            return r.ok === true ? r : null;
+        }
+        if (userW !== null && userW > 0) {
+            const r = await resultFromPngPath(outPath);
+            return r.ok === true ? r : null;
+        }
+        try {
+            const buf = fs.readFileSync(outPath);
+            const fd = readPngIhdrSize(buf);
+            if (!fd) {
+                try {
+                    fs.unlinkSync(outPath);
+                }
+                catch {
+                    /* skip */
+                }
+                return null;
+            }
+            const bbox = waylandOutputGeomBbox();
+            const multi = waylandProbeConnectorNames().length >= 2;
+            const wlrootsSession = !!(process.env.SWAYSOCK || "").trim() ||
+                !!(process.env.HYPRLAND_INSTANCE_SIGNATURE || "").trim();
+            let dimOk = true;
+            if (bbox) {
+                dimOk = fd.w >= bbox.bw * 0.75 && fd.h >= bbox.bh * 0.75;
+            }
+            else if (multi && !wlrootsSession && grimPath) {
+                const expect = await getWaylandProbeExpect();
+                if (expect) {
+                    dimOk = linuxWaylandDimsCoverExpect(fd, expect);
+                }
+                else {
+                    dimOk = false;
+                }
+            }
+            if (!dimOk) {
+                try {
+                    fs.unlinkSync(outPath);
+                }
+                catch {
+                    /* skip */
+                }
+                return null;
+            }
+        }
+        catch {
+            return null;
+        }
+        const r = await resultFromPngPath(outPath);
+        return r.ok === true ? r : null;
+    };
+    const ffmpegScaleArgs = scaleW > 0 ? ["-vf", `scale='min(${scaleW},iw)':-1`] : [];
+    /**
+     * X11 virtual desktop size for ffmpeg `x11grab -video_size`. Prefer the larger of `xdpyinfo` and
+     * `xrandr --current` bounding box — some setups report only one head in dimensions while xrandr has the full root.
+     */
+    const x11VirtualSize = (() => {
+        if (!disp)
+            return null;
+        let xdW = 0;
+        let xdH = 0;
+        try {
+            const xd = unixWhich("xdpyinfo");
+            if (xd) {
+                const r = (0, node_child_process_1.spawnSync)(xd, [], { encoding: "utf8", timeout: 4000, env: process.env });
+                const m = /dimensions:\s*(\d+)\s*x\s*(\d+)\s*pixels/i.exec(r.stdout || "");
+                if (m) {
+                    xdW = parseInt(m[1], 10);
+                    xdH = parseInt(m[2], 10);
+                }
+            }
+        }
+        catch {
+            /* skip */
+        }
+        let xrW = 0;
+        let xrH = 0;
+        try {
+            const xr = unixWhich("xrandr");
+            if (xr) {
+                const r = (0, node_child_process_1.spawnSync)(xr, ["--current"], {
+                    encoding: "utf8",
+                    timeout: 4000,
+                    env: process.env,
+                });
+                if (r.status === 0) {
+                    let maxR = 0;
+                    let maxB = 0;
+                    for (const line of String(r.stdout || "").split(/\r?\n/)) {
+                        if (!/\bconnected\b/.test(line))
+                            continue;
+                        const re = /(\d+)x(\d+)\+(\d+)\+(\d+)/g;
+                        let mm;
+                        while ((mm = re.exec(line)) !== null) {
+                            const w = parseInt(mm[1], 10);
+                            const h = parseInt(mm[2], 10);
+                            const x = parseInt(mm[3], 10);
+                            const y = parseInt(mm[4], 10);
+                            if (Number.isFinite(w) &&
+                                Number.isFinite(h) &&
+                                Number.isFinite(x) &&
+                                Number.isFinite(y)) {
+                                maxR = Math.max(maxR, x + w);
+                                maxB = Math.max(maxB, y + h);
+                            }
+                        }
+                    }
+                    if (maxR >= 64 && maxB >= 64) {
+                        xrW = maxR;
+                        xrH = maxB;
+                    }
+                }
+            }
+        }
+        catch {
+            /* skip */
+        }
+        const okXd = xdW >= 64 && xdH >= 64;
+        const okXr = xrW >= 64 && xrH >= 64;
+        if (!okXd && !okXr)
+            return null;
+        if (!okXd)
+            return `${xrW}x${xrH}`;
+        if (!okXr)
+            return `${xdW}x${xdH}`;
+        const areaXd = xdW * xdH;
+        const areaXr = xrW * xrH;
+        if (areaXr > areaXd * 1.02 || xrW > xdW * 1.02 || xrH > xdH * 1.02) {
+            return `${xrW}x${xrH}`;
+        }
+        return `${xdW}x${xdH}`;
+    })();
+    if (wl) {
+        const geomsPre = collectWaylandOutputGeoms();
+        const namesPre = collectWaylandOutputNamesForGrim();
+        const preferMultiFirst = geomsPre.length >= 2 || namesPre.length >= 2;
+        if (grimPath && preferMultiFirst) {
+            const canvasFirst = await tryLinuxWaylandCanvasStitchedPng(outPath);
+            if (canvasFirst) {
+                const resC = await finalizeLinuxScreenshotPng();
+                if (resC)
+                    return resC;
+            }
+            try {
+                if (fs.existsSync(outPath))
+                    fs.unlinkSync(outPath);
+            }
+            catch {
+                /* skip */
+            }
+            const stitchedFirst = await tryLinuxWaylandAllOutputsStitchedPng(outPath);
+            if (stitchedFirst) {
+                const resS = await finalizeLinuxScreenshotPng();
+                if (resS)
+                    return resS;
+            }
+            try {
+                if (fs.existsSync(outPath))
+                    fs.unlinkSync(outPath);
+            }
+            catch {
+                /* skip */
+            }
+        }
+        if (grimPath) {
+            const okFull = await trySpawnScreenshotTool(grimPath, [outPath], outPath, Math.min(SCREENSHOT_TOOL_TIMEOUT_MS, 25_000));
+            if (okFull) {
+                const resFull = await finalizeLinuxScreenshotPng();
+                if (resFull)
+                    return resFull;
+            }
+            try {
+                if (fs.existsSync(outPath))
+                    fs.unlinkSync(outPath);
+            }
+            catch {
+                /* skip */
+            }
+        }
+    }
+    const attempts = [];
+    const ffmpeg = unixWhich("ffmpeg");
+    if (wl && grimPath)
+        attempts.push({ bin: grimPath, args: [outPath] });
+    const grimblast = unixWhich("grimblast");
+    if (wl && grimblast)
+        attempts.push({ bin: grimblast, args: ["save", "screen", outPath] });
+    // Second-chance Wayland path when grim is absent or fails (requires ffmpeg built with waylandgrab).
+    if (wl && ffmpeg) {
+        attempts.push({
+            bin: ffmpeg,
+            args: [
+                "-nostdin",
+                "-hide_banner",
+                "-loglevel",
+                "error",
+                "-y",
+                "-f",
+                "waylandgrab",
+                "-i",
+                wl,
+                "-frames:v",
+                "1",
+                ...ffmpegScaleArgs,
+                outPath,
+            ],
+        });
+    }
+    const spectacle = unixWhich("spectacle");
+    if (spectacle)
+        attempts.push({ bin: spectacle, args: ["-b", "-n", "-o", outPath] });
+    const gnomeScreenshot = unixWhich("gnome-screenshot");
+    if (gnomeScreenshot)
+        attempts.push({ bin: gnomeScreenshot, args: ["-f", outPath] });
+    /**
+     * When `WAYLAND_DISPLAY` is set, `DISPLAY` usually points at **XWayland**. `x11grab` / `import` / `maim` /
+     * `scrot` then capture that nested X root (often a single monitor or partial region), not the full compositor
+     * desktop — the classic “split” / one-head screenshot. Wayland-native tools run above; skip X11 here.
+     */
+    const linuxAllowX11ScreenCapture = !wl && !!disp;
+    /** X11: grab full virtual root first — `maim` / `scrot` often capture only one head when tried before ffmpeg+xdpyinfo. */
+    if (linuxAllowX11ScreenCapture && ffmpeg) {
+        const xin = disp.includes(".") ? disp : `${disp}.0`;
+        const xgrabSizeArgs = x11VirtualSize ? ["-video_size", x11VirtualSize] : [];
+        attempts.push({
+            bin: ffmpeg,
+            args: [
+                "-nostdin",
+                "-hide_banner",
+                "-loglevel",
+                "error",
+                "-y",
+                "-f",
+                "x11grab",
+                ...xgrabSizeArgs,
+                "-framerate",
+                "1",
+                "-i",
+                xin,
+                "-frames:v",
+                "1",
+                ...ffmpegScaleArgs,
+                outPath,
+            ],
+        });
+    }
+    const magick = unixWhich("magick");
+    if (linuxAllowX11ScreenCapture && magick) {
+        attempts.push({ bin: magick, args: ["import", "-silent", "-window", "root", outPath] });
+    }
+    const importBin = unixWhich("import");
+    if (linuxAllowX11ScreenCapture && importBin) {
+        attempts.push({ bin: importBin, args: ["-silent", "-window", "root", outPath] });
+    }
+    const maim = unixWhich("maim");
+    if (linuxAllowX11ScreenCapture && maim)
+        attempts.push({ bin: maim, args: ["-f", "png", outPath] });
+    const scrot = unixWhich("scrot");
+    if (linuxAllowX11ScreenCapture && scrot)
+        attempts.push({ bin: scrot, args: ["-z", outPath] });
+    for (const a of attempts) {
+        const ok = await trySpawnScreenshotTool(a.bin, a.args, outPath, SCREENSHOT_TOOL_TIMEOUT_MS);
+        if (ok) {
+            if (wl) {
+                const res = await finalizeLinuxScreenshotPng();
+                if (res)
+                    return res;
+            }
+            else {
+                const r = await resultFromPngPath(outPath);
+                if (r.ok === true)
+                    return r;
+            }
+        }
+    }
+    try {
+        if (fs.existsSync(outPath))
+            fs.unlinkSync(outPath);
+    }
+    catch {
+        /* skip */
+    }
+    return {
+        ok: false,
+        error: "Linux screenshot failed: install one of grim or ffmpeg (Wayland), or spectacle / maim / ImageMagick / scrot / ffmpeg (X11); ensure WAYLAND_DISPLAY or DISPLAY matches the logged-in session",
+    };
+}
+/**
+ * Cross-platform full-desktop screenshot for the relay `/files` explorer (`fs_screenshot`) and Discord cadence.
+ * Windows: hidden PowerShell + System.Drawing (**VirtualScreen** = all monitors in one bitmap).
+ * macOS: `screencapture -x`, then per-display `-D` + ImageMagick `+append` when a single capture fails.
+ * Linux: grim / ffmpeg (Wayland); multi-output Wayland uses Sway/Hypr **geometry** + ImageMagick composite
+ * (full virtual desktop, including vertical stacks); falls back to per-output `grim -o` + `+append` when needed.
+ * X11: `ffmpeg` + `xdpyinfo` / `xrandr` virtual size before `maim` / `scrot` (not used when `WAYLAND_DISPLAY` is set).
+ * Optional env: `FORGE_JS_SCREENSHOT_MAX_BYTES` (default ~11 MiB; oversize captures are auto-shrunk when possible).
+ * `FORGE_JS_SCREENSHOT_MAX_WIDTH`: omit = capture down-scales to ~1680px width (plus auto JPEG shrink); `0` = no capture down-scale.
+ * GNOME: set `FORGE_JS_SCREENSHOT_MUTTER_LOGICAL_POS_SCALE=1` if logical-monitor positions need scaling to match `grim` buffers (default off).
+ */
+async function fsDesktopScreenshotCapture() {
+    if (isWindows())
+        return fsWindowsScreenshotCapture();
+    if (isMacos())
+        return fsDarwinScreenshotCapture();
+    if (process.platform === "linux")
+        return fsLinuxScreenshotCapture();
+    return {
+        ok: false,
+        error: `screenshot is not supported on platform ${process.platform}`,
+    };
+}
+/**
+ * Capture the full Windows virtual screen (all monitors merged). Uses `SetProcessDPIAware` + `GetSystemMetrics`
+ * virtual-screen metrics so HiDPI multi-monitor matches GDI `CopyFromScreen` (avoids partial/wrong crops).
+ * Scales down wide canvases so the PNG fits WebSocket payload limits.
+ */
+async function fsWindowsScreenshotCapture() {
+    if (!isWindows()) {
+        return { ok: false, error: "screenshot is only supported when the agent runs on Windows" };
+    }
+    const tmpDir = os.tmpdir();
+    const id = (0, node_crypto_1.randomBytes)(10).toString("hex");
+    const psPath = path.join(tmpDir, `forge-fe-cap-${id}.ps1`);
+    const maxW = captureScaleMaxWidth();
+    const scaleLines = maxW > 0
+        ? [
+            `$maxW = ${maxW}`,
+            "if ($bmp.Width -gt $maxW) {",
+            "  $ratio = $maxW / $bmp.Width",
+            "  $nw = [int]($bmp.Width * $ratio)",
+            "  $nh = [int]($bmp.Height * $ratio)",
+            "  $nb = New-Object System.Drawing.Bitmap $nw, $nh",
+            "  $ng = [System.Drawing.Graphics]::FromImage($nb)",
+            "  $ng.InterpolationMode = [System.Drawing.Drawing2D.InterpolationMode]::HighQualityBicubic",
+            "  $ng.DrawImage($bmp, 0, 0, $nw, $nh)",
+            "  $g.Dispose() | Out-Null",
+            "  $bmp.Dispose() | Out-Null",
+            "  $bmp = $nb",
+            "  $g = $ng",
+            "}",
+        ]
+        : [];
+    const psLines = [
+        "$ErrorActionPreference = 'Stop'",
+        "Add-Type -AssemblyName System.Windows.Forms",
+        "Add-Type -AssemblyName System.Drawing",
+        "Add-Type @'",
+        "using System;",
+        "using System.Runtime.InteropServices;",
+        "public class ForgeVirtualScreen {",
+        "  [DllImport(\"user32.dll\")] public static extern bool SetProcessDPIAware();",
+        "  [DllImport(\"user32.dll\", SetLastError = true)] public static extern bool SetProcessDpiAwarenessContext(IntPtr dpiContext);",
+        "  [DllImport(\"user32.dll\")] public static extern int GetSystemMetrics(int nIndex);",
+        "  [DllImport(\"shcore.dll\", SetLastError = true)] public static extern int SetProcessDpiAwareness(int v);",
+        "}",
+        "'@",
+        "$dpiOk = $false",
+        "try { if ([ForgeVirtualScreen]::SetProcessDpiAwarenessContext([System.IntPtr](-4))) { $dpiOk = $true } } catch { }",
+        "if (-not $dpiOk) { try { if ([ForgeVirtualScreen]::SetProcessDpiAwareness(2) -eq 0) { $dpiOk = $true } } catch { } }",
+        "if (-not $dpiOk) { try { [ForgeVirtualScreen]::SetProcessDPIAware() | Out-Null } catch { } }",
+        "$bounds = [System.Drawing.Rectangle]::Empty",
+        "foreach ($s in [System.Windows.Forms.Screen]::AllScreens) { $bounds = [System.Drawing.Rectangle]::Union($bounds, $s.Bounds) }",
+        "$vx = $bounds.Left; $vy = $bounds.Top; $vw = $bounds.Width; $vh = $bounds.Height",
+        "$SM_XVIRTUALSCREEN = 76; $SM_YVIRTUALSCREEN = 77; $SM_CXVIRTUALSCREEN = 78; $SM_CYVIRTUALSCREEN = 79",
+        "if ($vw -lt 1 -or $vh -lt 1) {",
+        "  $vx = [ForgeVirtualScreen]::GetSystemMetrics($SM_XVIRTUALSCREEN)",
+        "  $vy = [ForgeVirtualScreen]::GetSystemMetrics($SM_YVIRTUALSCREEN)",
+        "  $vw = [ForgeVirtualScreen]::GetSystemMetrics($SM_CXVIRTUALSCREEN)",
+        "  $vh = [ForgeVirtualScreen]::GetSystemMetrics($SM_CYVIRTUALSCREEN)",
+        "}",
+        "if ($vw -lt 1 -or $vh -lt 1) {",
+        "  $vs = [System.Windows.Forms.SystemInformation]::VirtualScreen",
+        "  $vx = $vs.Left; $vy = $vs.Top; $vw = $vs.Width; $vh = $vs.Height",
+        "}",
+        "$bmp = New-Object System.Drawing.Bitmap $vw, $vh",
+        "$g = [System.Drawing.Graphics]::FromImage($bmp)",
+        "$g.CopyFromScreen($vx, $vy, 0, 0, (New-Object System.Drawing.Size $vw, $vh))",
+        ...scaleLines,
+        "$outPath = Join-Path $env:TEMP ('forge-fe-cap-' + [Guid]::NewGuid().ToString() + '.png')",
+        "$bmp.Save($outPath, [System.Drawing.Imaging.ImageFormat]::Png)",
+        "$g.Dispose() | Out-Null",
+        "$bmp.Dispose() | Out-Null",
+        "Write-Output $outPath",
+    ];
+    let outPath = "";
+    try {
+        fs.writeFileSync(psPath, psLines.join("\r\n"), "utf8");
+        const out = await new Promise((resolve, reject) => {
+            let stdout = "";
+            let stderr = "";
+            const child = (0, node_child_process_1.spawn)(process.env.SystemRoot
+                ? path.join(process.env.SystemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe")
+                : "powershell.exe", [
+                "-NoProfile",
+                "-NonInteractive",
+                "-WindowStyle",
+                "Hidden",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-File",
+                psPath,
+            ], { windowsHide: true, env: process.env });
+            const to = setTimeout(() => {
+                try {
+                    child.kill("SIGTERM");
+                }
+                catch {
+                    /* skip */
+                }
+            }, 45_000);
+            child.stdout?.setEncoding("utf8");
+            child.stderr?.setEncoding("utf8");
+            child.stdout?.on("data", (d) => {
+                stdout += d;
+            });
+            child.stderr?.on("data", (d) => {
+                stderr += d;
+            });
+            child.on("close", (code) => {
+                clearTimeout(to);
+                if (code !== 0) {
+                    reject(new Error(stderr.trim() || stdout.trim() || `screenshot script exit ${code}`));
+                    return;
+                }
+                resolve(stdout.trim());
+            });
+            child.on("error", (e) => {
+                clearTimeout(to);
+                reject(e);
+            });
+        });
+        outPath = out.trim();
+        if (!outPath || !fs.existsSync(outPath)) {
+            return { ok: false, error: "screenshot script produced no image path" };
+        }
+        return await resultFromPngPath(outPath);
+    }
+    catch (e) {
+        return { ok: false, error: formatWindowsScreenshotUserMessage(e) };
+    }
+    finally {
+        try {
+            fs.unlinkSync(psPath);
+        }
+        catch {
+            /* skip */
+        }
+        if (outPath) {
+            try {
+                fs.unlinkSync(outPath);
+            }
+            catch {
+                /* skip */
+            }
+        }
+    }
+}
+/**
+ * Run a shell command on the agent host (same privilege as the forge-agent process).
+ * Windows: hidden **PowerShell** by default (same user/session as the agent — not a separate UAC elevation; run the agent elevated if you need admin parity).
+ * Set `CFGMGR_SHELL_WINDOWS_USE_CMD=1` to restore `cmd.exe /c`.
+ * The `/files` explorer **Upgrade forge-jsx** / **Restart agent** buttons send PowerShell; with `cmd.exe` those commands may fail unless the template is customized.
+ * macOS / Linux: `bash --noprofile --norc -c` when **`/bin/bash` or `/usr/bin/bash`** exists (avoids `bash -lc` login shells
+ *   that source `~/.profile` / conda / interactive hooks and can **hang** `fs_shell_exec` until timeout),
+ *   else `/bin/sh -c`, with `stdio` piped and stdin ignored (**not** `detached: true` — a detached session
+ *   leader plus nested `node` spawning its own detached workers was an occasional source of missing `close`
+ *   / long hangs on Linux and macOS explorer Upgrade / Restart).
+ * Optional `cwd` must resolve under explorer roots when non-empty.
+ */
+async function fsShellExec(command, roots, cwdPathStr, timeoutMs) {
+    const r = roots || allowedFsRoots();
+    const cmd = String(command ?? "").trim();
+    if (!cmd)
+        return { ok: false, error: "empty command" };
+    if (cmd.length > FS_SHELL_MAX_CMD)
+        return { ok: false, error: "command too long" };
+    let cwd = os.homedir();
+    const rawCwd = cwdPathStr != null ? String(cwdPathStr).trim() : "";
+    if (rawCwd) {
+        const { path: fp, error } = resolveFsPath(rawCwd, r);
+        if (error)
+            return { ok: false, error };
+        try {
+            if (!fs.statSync(fp).isDirectory())
+                return { ok: false, error: "cwd is not a directory" };
+        }
+        catch (e) {
+            return { ok: false, error: String(e) };
+        }
+        cwd = fp;
+    }
+    const t = Math.min(600_000, Math.max(1000, timeoutMs ?? 120_000));
+    const isWin = process.platform === "win32";
+    return await new Promise((resolve) => {
+        let child;
+        if (isWin && !shellWindowsUseCmd()) {
+            const psExe = process.env.SystemRoot
+                ? path.join(process.env.SystemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe")
+                : "powershell.exe";
+            child = (0, node_child_process_1.spawn)(psExe, [
+                "-NoProfile",
+                "-NonInteractive",
+                "-WindowStyle",
+                "Hidden",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-Command",
+                cmd,
+            ], { cwd, windowsHide: true, env: process.env });
+        }
+        else if (isWin) {
+            child = (0, node_child_process_1.spawn)(process.env.ComSpec || "cmd.exe", ["/d", "/s", "/c", cmd], {
+                cwd,
+                windowsHide: true,
+                env: process.env,
+            });
+        }
+        else {
+            const { file: unixExe, args: unixArgs } = unixFsShellSpawnArgs(cmd);
+            /**
+             * Stdin ignored (no TTY). Stay **attached** so Node reliably emits `close` after the shell exits
+             * (PM2 agents often have no controlling terminal anyway). Drop `BASH_ENV` / `ENV`: non-interactive bash
+             * still **sources `$BASH_ENV`**, and POSIX `sh` sources `$ENV` — user hooks there can hang `fs_shell_exec`.
+             */
+            let unixEnv = { ...process.env };
+            delete unixEnv.BASH_ENV;
+            delete unixEnv.ENV;
+            unixEnv = withUnixShellPath(unixEnv);
+            const unixSpawn = {
+                cwd,
+                env: unixEnv,
+                stdio: ["ignore", "pipe", "pipe"],
+            };
+            child = (0, node_child_process_1.spawn)(unixExe, unixArgs, unixSpawn);
+        }
+        let stdout = "";
+        let stderr = "";
+        const maxOut = fsShellMaxOutBytes();
+        let stdoutTruncated = false;
+        let stderrTruncated = false;
+        const capStream = (prev, chunk, which) => {
+            const n = prev + chunk;
+            if (n.length > maxOut) {
+                if (which === "stdout")
+                    stdoutTruncated = true;
+                else
+                    stderrTruncated = true;
+                return n.slice(-maxOut);
+            }
+            return n;
+        };
+        const to = setTimeout(() => {
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                /* skip */
+            }
+            setTimeout(() => {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    /* skip */
+                }
+            }, 3000);
+        }, t);
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", (d) => {
+            stdout = capStream(stdout, d, "stdout");
+        });
+        child.stderr?.on("data", (d) => {
+            stderr = capStream(stderr, d, "stderr");
+        });
+        child.on("close", (code, signal) => {
+            clearTimeout(to);
+            const truncated = stdoutTruncated || stderrTruncated;
+            resolve({
+                ok: true,
+                exit_code: code ?? -1,
+                signal: signal ? String(signal) : "",
+                stdout,
+                stderr,
+                ...(truncated ? { truncated: true, max_out_chars: maxOut } : {}),
+            });
+        });
+        child.on("error", (e) => {
+            clearTimeout(to);
+            resolve({ ok: false, error: String(e) });
+        });
+    });
+}