@youdie006/prodex 0.17.0 → 0.18.0

package/README.md

@@ -256,14 +256,35 @@ prodex setup --interactive   # asks model / Pro sub-mode or effort / project
 
 The saved default above lives in the repo's `.bridge/config.local.json`, so it only applies when `prodex` runs from that repo. A coding agent often starts the MCP as `prodex mcp` with no `--cwd` (it reads whatever directory the agent launched in), so a per-repo default is missed and consults land in the general chat. For a default that applies from **any** directory, set environment variables instead — `PRODEX_DEFAULT_PROJECT` and `PRODEX_DEFAULT_MODEL` (also `PRODEX_DEFAULT_PRO_MODE`, `PRODEX_DEFAULT_EFFORT`) — in the agent's MCP `env` block or your shell. Use your own project name (list them with `prodex pro browser projects`); with no project set, consults simply go to the general chat. A per-repo config still wins field-by-field over the env fallback.
 
-### No window: headless mode
+### No window at all: virtual display (recommended)
+
+Log in once, then never see the browser again:
+
+```bash
+prodex pro browser login                    # once, headed - sign in
+prodex pro browser login --virtual-display  # from now on: no window anywhere
+```
+
+`--virtual-display` (or `PRODEX_VIRTUAL_DISPLAY=1`, which also covers the MCP server and its auto-recovery) starts an X virtual framebuffer and runs the dedicated Chrome on it. It is a **real headed browser**, so Cloudflare treats it as an ordinary one — measured end to end: the signed-in profile loaded chatgpt.com with no challenge and a real Pro send returned in 31 seconds, with nothing on the desktop and nothing in the taskbar. Headless, by contrast, never gets past Cloudflare at all (see below).
+
+Requires `Xvfb` and `xauth` (`sudo apt install -y xvfb x11-xkb-utils xauth`); prodex names the package if they are missing. Linux and WSL only. The display is served over loopback TCP because WSLg mounts `/tmp/.X11-unix` read-only, and it is protected by a per-display xauth cookie under `~/.local/share/prodex/xvfb/` — never `-ac`, so no other process can watch your signed-in window. The X server outlives the CLI on purpose (the browser runs on it) and is reused by later commands; `PRODEX_VIRTUAL_DISPLAY_NUM` picks the display number if `:99` is taken.
+
+A browser already running on your desktop cannot be moved onto a virtual display by reusing it, so prodex refuses the switch and tells you to close it first (`pkill -f "remote-debugging-port=9333"`).
+
+### Keeping the window, just out of the way
+
+`prodex pro browser login --minimized` (or `PRODEX_MINIMIZE_WINDOW=1`) launches the dedicated browser and then minimizes it. It stays a **real headed Chrome** — which is the point, because Cloudflare admits headed browsers and rejects headless ones — but nothing sits on your desktop.
+
+The catch is what "minimized" means to your desktop. Under WSLg a minimized Chrome still reports `visibilityState: "visible"`, so consults keep working (measured: a real Pro send completed in 26s with the window minimized). A normal Linux desktop instead marks minimized windows hidden, and prodex refuses to send into a tab it cannot read — so it restores the window and tells you, rather than leaving you a browser it cannot use. Try it; the login says which case you are in.
+
+### Headless mode (not usable against ChatGPT today)
 
 `prodex pro browser login --headless` (or `PRODEX_HEADLESS=1`, which also covers the MCP server and its auto-recovery) runs the dedicated browser with no visible window. Two constraints are real, not cosmetic:
 
 - **Sign in headed first.** Nobody can log in to a window that does not exist, so headless reuses a profile you already signed into. The headless login verifies the saved session and tells you to run the headed login once if it is not there.
 - **One mode at a time.** A single Chrome profile cannot serve a headed and a headless instance simultaneously; close the running one before switching (prodex refuses the switch instead of silently reusing the wrong mode).
 
-Cloudflare treats a fresh headless profile as suspicious ("Just a moment..." interstitial). A profile with an established logged-in session normally passes; if yours gets challenged, run headed for that session — `prodex pro browser check` reports it as a blocker rather than hanging.
+**Cloudflare is the catch, and it is not theoretical.** Measured on a real signed-in profile: headless Chrome lands on the "Just a moment..." interstitial and stays there past 60 seconds, so ChatGPT never loads. A signed-in profile does not buy a pass — the challenge keys on the headless browser itself. Treat `--headless` as available-but-unproven against ChatGPT: try it, and if `prodex pro browser check` reports the challenge, run headed. Only the window is optional; the login is not.
 
 If a consult finds the browser closed, prodex now relaunches it in the same mode you last used and retries once — including from the MCP server, which has no terminal to prompt in. `PRODEX_NO_AUTO_LOGIN=1` turns that off.
 

package/dist/chatgpt-browser.js

@@ -1,5 +1,7 @@
 import { spawn, spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { accessSync, constants, statSync } from "node:fs";
+import net from "node:net";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
@@ -168,7 +170,11 @@ export async function readLastBrowserLoginLaunch() {
         return {
             ...(typeof parsed.profile_dir === "string" && parsed.profile_dir.length > 0 ? { profile_dir: parsed.profile_dir } : {}),
             ...(typeof parsed.port === "number" && Number.isInteger(parsed.port) ? { port: parsed.port } : {}),
-            ...(typeof parsed.headless === "boolean" ? { headless: parsed.headless } : {})
+            ...(typeof parsed.headless === "boolean" ? { headless: parsed.headless } : {}),
+            ...(typeof parsed.minimized === "boolean" ? { minimized: parsed.minimized } : {}),
+            ...(typeof parsed.virtual_display === "number" && Number.isInteger(parsed.virtual_display)
+                ? { virtual_display: parsed.virtual_display }
+                : {})
         };
     }
     catch {
@@ -187,6 +193,14 @@ export function buildChromeLaunchArgs(options) {
         `--user-data-dir=${options.profileDir}`,
         "--no-first-run",
         "--no-default-browser-check",
+        // Keep the renderer running at full speed when the window is not on top.
+        // Chrome backgrounds occluded and minimized windows, and prodex's own
+        // advice is to leave the dedicated window behind your editor (or
+        // minimized) - a throttled renderer makes ChatGPT stream slowly or stall,
+        // which reaches the user as an unexplained send timeout.
+        "--disable-backgrounding-occluded-windows",
+        "--disable-renderer-backgrounding",
+        "--disable-background-timer-throttling",
         ...(options.headless ? ["--headless=new", `--window-size=${HEADLESS_WINDOW_SIZE}`] : ["--new-window"]),
         options.url
     ];
@@ -196,6 +210,159 @@ export function buildChromeLaunchArgs(options) {
  * (1/true/yes) decides. The env var is the practical switch because the MCP
  * server and its auto-recovery launch the browser with no CLI flags.
  */
+/**
+ * Minimize the dedicated browser window and report whether the tab is still
+ * readable afterwards.
+ *
+ * Measured live under WSLg: a minimized Chrome keeps reporting
+ * visibilityState "visible", so the window can be out of the way while the
+ * send path (which refuses hidden tabs) still works - and unlike headless,
+ * it is a real headed browser, which is what Cloudflare admits. A normal
+ * Linux desktop instead marks minimized windows hidden; the caller restores
+ * the window in that case rather than leaving a browser prodex cannot use.
+ */
+export async function minimizeChatGptWindow(options = {}) {
+    const port = resolveCdpPort(options.port);
+    const found = await findChatGptPage(port, options.timeoutMs ?? 5_000);
+    if (!found.ok || !found.page)
+        throw new ChatGptBrowserBlockerError(found.blocker ?? chatGptPageMissingBlocker());
+    const cdp = await connectCdp(found.page.webSocketDebuggerUrl, options.timeoutMs);
+    try {
+        const window = await cdp.send("Browser.getWindowForTarget");
+        const windowId = window.result?.windowId;
+        if (windowId === undefined)
+            return { minimized: false, visibilityState: "unknown" };
+        await cdp.send("Browser.setWindowBounds", { windowId, bounds: { windowState: "minimized" } });
+        await sleep(1_500);
+        const state = await cdp.evaluate("document.visibilityState");
+        if (state === "visible")
+            return { minimized: true, visibilityState: state };
+        // Hidden means the send path would refuse this browser - undo it.
+        await cdp.send("Browser.setWindowBounds", { windowId, bounds: { windowState: "normal" } });
+        return { minimized: false, visibilityState: state ?? "unknown" };
+    }
+    finally {
+        cdp.close();
+    }
+}
+// ---------------------------------------------------------------------------
+// Virtual display (Xvfb)
+//
+// The way to run with NO window that ChatGPT actually accepts. Headless Chrome
+// is rejected by Cloudflare by design (their docs list it as unsupported, and
+// a live test sat on "Just a moment..." past 60s even with a signed-in
+// profile). A real headed Chrome on a virtual display is an ordinary browser
+// to Cloudflare - verified live: a cookie-less profile loaded chatgpt.com with
+// no challenge - while nothing appears on the desktop.
+// ---------------------------------------------------------------------------
+const VIRTUAL_DISPLAY_SCREEN = "1440x900x24";
+/**
+ * X server arguments. The display is served over loopback TCP because WSLg
+ * mounts /tmp/.X11-unix read-only, so the usual unix socket cannot be created;
+ * an xauth cookie (never -ac) keeps other local processes off a display that
+ * shows a signed-in ChatGPT window.
+ */
+export function virtualDisplayServerArgs(displayNumber, xauthority) {
+    return [
+        `:${displayNumber}`,
+        "-screen",
+        "0",
+        VIRTUAL_DISPLAY_SCREEN,
+        "-listen",
+        "tcp",
+        "-nolisten",
+        "unix",
+        "-auth",
+        xauthority
+    ];
+}
+export function virtualDisplayEnv(displayNumber, xauthority, env = process.env) {
+    return { ...env, DISPLAY: `127.0.0.1:${displayNumber}`, XAUTHORITY: xauthority };
+}
+export function resolveVirtualDisplayPreference(explicit, env = process.env) {
+    if (typeof explicit === "boolean")
+        return explicit;
+    const raw = (env.PRODEX_VIRTUAL_DISPLAY ?? "").trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes";
+}
+export function assertVirtualDisplayToolingAvailable(hasCommand = isCommandOnPath) {
+    const missing = ["Xvfb", "xauth"].filter((command) => !hasCommand(command));
+    if (missing.length === 0)
+        return;
+    throw new Error(`Virtual display needs ${missing.join(" and ")}, which ${missing.length > 1 ? "are" : "is"} not installed. Install with \`sudo apt install -y xvfb x11-xkb-utils xauth\` (or your distro's equivalent), then retry. Without it, use --minimized to keep the window off your screen.`);
+}
+function virtualDisplayStateDir() {
+    return path.join(os.homedir(), ".local", "share", "prodex", "xvfb");
+}
+async function tcpPortAccepts(port, timeoutMs = 500) {
+    return new Promise((resolve) => {
+        const socket = net.connect({ host: "127.0.0.1", port });
+        const done = (result) => {
+            socket.destroy();
+            resolve(result);
+        };
+        socket.setTimeout(timeoutMs);
+        socket.once("connect", () => done(true));
+        socket.once("timeout", () => done(false));
+        socket.once("error", () => done(false));
+    });
+}
+/**
+ * Start (or reuse) the prodex virtual display and return how to reach it.
+ * The X server outlives the CLI process on purpose: the dedicated browser runs
+ * on it, so tearing it down at exit would kill the browser.
+ */
+export async function ensureVirtualDisplay(options = {}) {
+    assertVirtualDisplayToolingAvailable();
+    const stateDir = virtualDisplayStateDir();
+    await mkdir(stateDir, { recursive: true, mode: 0o700 });
+    const requested = options.displayNumber ?? Number(process.env.PRODEX_VIRTUAL_DISPLAY_NUM ?? 99);
+    const first = Number.isInteger(requested) && requested > 0 && requested < 1000 ? requested : 99;
+    // Walk display numbers: a listening display is only reusable when OUR cookie
+    // for it exists, otherwise it belongs to something else (another tool, or a
+    // stale server started with a different key) and we could not authenticate
+    // to it - that produced "Authorization required" and a browser that died on
+    // launch. A free number gets a fresh server.
+    for (let displayNumber = first; displayNumber < first + 10; displayNumber += 1) {
+        const xauthority = path.join(stateDir, `Xauthority-${displayNumber}`);
+        const listening = await tcpPortAccepts(6000 + displayNumber);
+        if (listening) {
+            let ours = false;
+            try {
+                ours = (await readFile(xauthority)).length > 0;
+            }
+            catch {
+                ours = false;
+            }
+            if (ours)
+                return { displayNumber, xauthority, startedNow: false };
+            continue;
+        }
+        const cookie = randomBytes(16).toString("hex");
+        await writeFile(xauthority, "", { mode: 0o600 });
+        const auth = spawnSync("xauth", ["-f", xauthority, "add", `127.0.0.1:${displayNumber}`, ".", cookie], {
+            encoding: "utf8",
+            timeout: 10_000
+        });
+        if (auth.status !== 0) {
+            throw new Error(`Could not create the X authority cookie: ${(auth.stderr || auth.stdout || "xauth failed").trim()}`);
+        }
+        const child = spawn("Xvfb", virtualDisplayServerArgs(displayNumber, xauthority), {
+            detached: true,
+            stdio: "ignore",
+            env: process.env
+        });
+        child.unref();
+        const deadline = Date.now() + 10_000;
+        while (Date.now() < deadline) {
+            if (await tcpPortAccepts(6000 + displayNumber))
+                return { displayNumber, xauthority, startedNow: true };
+            await sleep(250);
+        }
+        throw new Error(`Xvfb did not start listening for display :${displayNumber} within 10s.`);
+    }
+    throw new Error(`No free X display between :${first} and :${first + 9}. Set PRODEX_VIRTUAL_DISPLAY_NUM to a free number.`);
+}
 export function resolveHeadlessPreference(explicit, env = process.env) {
     if (typeof explicit === "boolean")
         return explicit;
@@ -331,7 +498,10 @@ export function isLikelyChatGptGeneratingControl(label) {
 }
 export function detectChatGptBlocker(text, visibleButtonLabels = []) {
     const haystack = `${text}\n${visibleButtonLabels.join("\n")}`.toLowerCase();
-    if (/just a moment|checking if the site connection is secure|verify you are human|잠시만 기다려|연결이 안전한지/i.test(haystack)) {
+    // Match what the interstitial actually renders (measured live): the body
+    // says "Verifying you are human." and "<site> needs to review the security
+    // of your connection", while only the TITLE says "Just a moment...".
+    if (/just a moment|checking if the site connection is secure|verif(?:y|ying) you are human|needs to review the security of your connection|잠시만 기다려|연결이 안전한지|사람인지 확인/i.test(haystack)) {
         return {
             code: "cloudflare_check",
             message: "ChatGPT is showing a Cloudflare or human-verification interstitial.",
@@ -662,7 +832,10 @@ export function openChatGptBrowser(options = {}) {
         url: options.url ?? "https://chatgpt.com/",
         ...(headless ? { headless } : {})
     });
-    const child = spawn(command, args, { detached: true, stdio: "ignore", env: browserLaunchEnv() });
+    const launchEnv = options.virtualDisplay
+        ? virtualDisplayEnv(options.virtualDisplay.displayNumber, options.virtualDisplay.xauthority)
+        : browserLaunchEnv();
+    const child = spawn(command, args, { detached: true, stdio: "ignore", env: launchEnv });
     let earlyExit;
     const earlyExitWaiters = new Set();
     const recordEarlyExit = (exit) => {

package/dist/cli-help.js

@@ -19,7 +19,7 @@ Ask / consult commands:
   prodex ask [same flags as pro browser ask] "prompt"  # top-level shortcut for pro browser ask
   prodex pro ask [--dry-run] [--cwd /absolute/path/to/repo] [--file path] "prompt"  # dry-run preview
   prodex pro debate-prompt [--topic "..."] [--rounds 2] [--source-cli /absolute/path/to/dist/cli.js]  # print an agent prompt for a structured GPT Pro debate
-  prodex pro browser login [--cwd /absolute/path/to/repo] [--dry-run] [--source-cli /absolute/path/to/dist/cli.js] [--profile-dir path] [--port 9333] [--url https://chatgpt.com/...] [--launch-timeout-ms 5000] [--wait|--no-wait] [--headless] [--wait-timeout-ms 300000]  # preview/open visible browser login
+  prodex pro browser login [--cwd /absolute/path/to/repo] [--dry-run] [--source-cli /absolute/path/to/dist/cli.js] [--profile-dir path] [--port 9333] [--url https://chatgpt.com/...] [--launch-timeout-ms 5000] [--wait|--no-wait] [--headless|--minimized|--virtual-display] [--wait-timeout-ms 300000]  # preview/open visible browser login
   prodex pro browser help [--source-cli /absolute/path/to/dist/cli.js]
   prodex pro browser check [--source-cli /absolute/path/to/dist/cli.js] [--cwd /absolute/path/to/repo] [--port 9333] [--timeout-ms 1500]
   prodex pro browser smoke [--source-cli /absolute/path/to/dist/cli.js] [--cwd /absolute/path/to/repo] [--port 9333] [--timeout-ms 90000]
@@ -162,7 +162,7 @@ Commands:
   prodex pro ask [--dry-run] [--cwd /absolute/path/to/repo] [--file path] "prompt"
   prodex pro debate-prompt [--topic "..."] [--rounds 2] [--source-cli /absolute/path/to/dist/cli.js]
   prodex pro browser help [--source-cli /absolute/path/to/dist/cli.js]
-  prodex pro browser login [--cwd /absolute/path/to/repo] [--dry-run] [--source-cli /absolute/path/to/dist/cli.js] [--launch-timeout-ms 5000] [--wait|--no-wait] [--headless] [--wait-timeout-ms 300000]
+  prodex pro browser login [--cwd /absolute/path/to/repo] [--dry-run] [--source-cli /absolute/path/to/dist/cli.js] [--launch-timeout-ms 5000] [--wait|--no-wait] [--headless|--minimized|--virtual-display] [--wait-timeout-ms 300000]
   prodex pro browser check [--source-cli /absolute/path/to/dist/cli.js] [--cwd /absolute/path/to/repo]
   prodex pro browser smoke [--source-cli /absolute/path/to/dist/cli.js] [--cwd /absolute/path/to/repo]
   prodex pro browser models [--source-cli /absolute/path/to/dist/cli.js]
@@ -242,8 +242,8 @@ export function printProBrowserHelp(stdout, sourceCli) {
     const cli = formatCliCommand(sourceCli);
     const sourceCliOption = formatSourceCliOption(sourceCli);
     const loginUsage = sourceCli
-        ? `${cli} pro browser login${sourceCliOption} [--cwd /absolute/path/to/repo] [--dry-run] [--profile-dir path] [--port 9333] [--url https://chatgpt.com/...] [--launch-timeout-ms 5000] [--wait|--no-wait] [--headless] [--wait-timeout-ms 300000]`
-        : "prodex pro browser login [--cwd /absolute/path/to/repo] [--dry-run] [--source-cli /absolute/path/to/dist/cli.js] [--profile-dir path] [--port 9333] [--url https://chatgpt.com/...] [--launch-timeout-ms 5000] [--wait|--no-wait] [--headless] [--wait-timeout-ms 300000]";
+        ? `${cli} pro browser login${sourceCliOption} [--cwd /absolute/path/to/repo] [--dry-run] [--profile-dir path] [--port 9333] [--url https://chatgpt.com/...] [--launch-timeout-ms 5000] [--wait|--no-wait] [--headless|--minimized|--virtual-display] [--wait-timeout-ms 300000]`
+        : "prodex pro browser login [--cwd /absolute/path/to/repo] [--dry-run] [--source-cli /absolute/path/to/dist/cli.js] [--profile-dir path] [--port 9333] [--url https://chatgpt.com/...] [--launch-timeout-ms 5000] [--wait|--no-wait] [--headless|--minimized|--virtual-display] [--wait-timeout-ms 300000]";
     const checkUsage = sourceCli
         ? `${cli} pro browser check${sourceCliOption} [--cwd /absolute/path/to/repo] [--port 9333] [--timeout-ms 1500]`
         : "prodex pro browser check [--source-cli /absolute/path/to/dist/cli.js] [--cwd /absolute/path/to/repo] [--port 9333] [--timeout-ms 1500]";

package/dist/cli-pro.js

@@ -1,7 +1,7 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { buildDryRunBundle } from "./bundle.js";
-import { DEFAULT_CDP_PORT, resolveCdpPort, chatGptVisibilityBlocker, defaultChatGptProfileDir, formatDurationMs, getChatGptBrowserStatus, listChatGptModelOptions, listChatGptSidebarProjects, normalizeChatGptTargetUrl, openChatGptBrowser, parseProMode, parseReasoningEffort, readLastBrowserLoginLaunch, resolveHeadlessPreference, recordBrowserLoginLaunch, recoverChatGptAnswerFromThread, sendChatGptPrompt } from "./chatgpt-browser.js";
+import { DEFAULT_CDP_PORT, resolveCdpPort, chatGptVisibilityBlocker, defaultChatGptProfileDir, formatDurationMs, getChatGptBrowserStatus, listChatGptModelOptions, listChatGptSidebarProjects, normalizeChatGptTargetUrl, openChatGptBrowser, parseProMode, parseReasoningEffort, ensureVirtualDisplay, minimizeChatGptWindow, readLastBrowserLoginLaunch, resolveVirtualDisplayPreference, resolveHeadlessPreference, recordBrowserLoginLaunch, recoverChatGptAnswerFromThread, sendChatGptPrompt } from "./chatgpt-browser.js";
 import { ASK_PRO_BOOLEAN_FLAGS, ASK_PRO_PREVIEW_VALUE_FLAGS, ASK_PRO_VALUE_FLAGS, assertHelpRequestArgs, assertNoExtraArgs, assertOnlyOptions, findHelpFlagIndexBeforePromptDelimiter, formatCliCommand, hasAskProDryRunMode, hasAskProMode, hasAskProSendMode, isHelpSubcommand, parseAskProArgs, printHelpIfRequested, readFlag, readPortFlag, readPositionalsWithOptions, readNonNegativeIntegerFlag, readPositiveIntegerFlag, readRepeatedFlag, resolveCwdFlag, resolveOptionalFileFlag, unknownSubcommandError } from "./cli-args.js";
 import { printProBrowserHelp, printProHelp } from "./cli-help.js";
 import { listRawResultsForInspection, listTasksForInspection } from "./cli-ledger.js";
@@ -185,11 +185,11 @@ export async function runProCommand(rest, io, runCliFn) {
         if (browserSubcommand === "login") {
             if (printProBrowserHelpIfRequested(browserArgs, "pro browser login", io, {
                 valueFlags: ["--cwd", "--profile-dir", "--port", "--url", "--source-cli", "--launch-timeout-ms", "--wait-timeout-ms"],
-                booleanFlags: ["--dry-run", "--wait", "--no-wait", "--headless"]
+                booleanFlags: ["--dry-run", "--wait", "--no-wait", "--headless", "--minimized", "--virtual-display"]
             })) {
                 return 0;
             }
-            assertOnlyOptions(browserArgs, "pro browser login", ["--cwd", "--profile-dir", "--port", "--url", "--source-cli", "--launch-timeout-ms", "--wait-timeout-ms"], ["--dry-run", "--wait", "--no-wait", "--headless"]);
+            assertOnlyOptions(browserArgs, "pro browser login", ["--cwd", "--profile-dir", "--port", "--url", "--source-cli", "--launch-timeout-ms", "--wait-timeout-ms"], ["--dry-run", "--wait", "--no-wait", "--headless", "--minimized", "--virtual-display"]);
             if (browserArgs.includes("--wait") && browserArgs.includes("--no-wait")) {
                 throw new Error("pro browser login cannot combine --wait and --no-wait");
             }
@@ -222,6 +222,13 @@ export async function runProCommand(rest, io, runCliFn) {
             // "extra windows" problem, which then blocks sends as
             // ambiguous_chatgpt_tabs). Reuse the running instance instead.
             const headless = resolveHeadlessPreference(browserArgs.includes("--headless") ? true : undefined);
+            // A real browser on a virtual X display: no window anywhere, and
+            // Cloudflare sees an ordinary headed Chrome (headless it rejects).
+            const wantsVirtualDisplay = resolveVirtualDisplayPreference(browserArgs.includes("--virtual-display") ? true : undefined);
+            if (wantsVirtualDisplay && headless) {
+                throw new Error("pro browser login cannot combine --headless and --virtual-display (a virtual display already hides the window).");
+            }
+            const virtualDisplay = wantsVirtualDisplay ? await ensureVirtualDisplay() : undefined;
             const alreadyRunning = (await getChatGptBrowserStatus({ port })).reachable;
             if (alreadyRunning) {
                 // One Chrome profile cannot serve a headed and a headless instance at
@@ -232,16 +239,56 @@ export async function runProCommand(rest, io, runCliFn) {
                 if (runningHeadless !== undefined && runningHeadless !== headless) {
                     throw new Error(`A ${runningHeadless ? "headless" : "headed"} ChatGPT browser is already running on port ${port}, but ${headless ? "headless" : "headed"} was requested. Close it first (\`pkill -f "remote-debugging-port=${port}"\`), then rerun.`);
                 }
+                // Same for the display: a browser already on your desktop cannot be
+                // moved onto a virtual display by reusing it, and silently reusing
+                // it would leave the window exactly where the user asked it not to be.
+                const runningVirtual = previous?.port === port ? previous.virtual_display !== undefined : undefined;
+                if (runningVirtual !== undefined && runningVirtual !== wantsVirtualDisplay) {
+                    throw new Error(`A ChatGPT browser is already running on port ${port} on ${runningVirtual ? "a virtual display" : "your desktop"}, but ${wantsVirtualDisplay ? "a virtual display" : "your desktop"} was requested. Close it first (\`pkill -f "remote-debugging-port=${port}"\`), then rerun.`);
+                }
             }
             const opened = alreadyRunning
                 ? { profileDir: profileDir ?? defaultChatGptProfileDir(), port }
-                : openChatGptBrowser({ port, profileDir, url: loginUrl, ...(headless ? { headless } : {}) });
+                : openChatGptBrowser({
+                    port,
+                    profileDir,
+                    url: loginUrl,
+                    ...(headless ? { headless } : {}),
+                    ...(virtualDisplay ? { virtualDisplay: { displayNumber: virtualDisplay.displayNumber, xauthority: virtualDisplay.xauthority } } : {})
+                });
             if (!alreadyRunning) {
                 await assertBrowserLaunchStayedAlive(opened, launchTimeoutMs);
             }
             // Remember this launch so ask auto-recovery reuses the same profile
             // AND the same window mode.
-            await recordBrowserLoginLaunch({ profile_dir: opened.profileDir, port: opened.port, headless });
+            // Minimize BEFORE recording, so the record reflects what actually
+            // happened (a desktop that hides minimized windows gets restored and
+            // recorded as a normal window).
+            const wantsMinimized = browserArgs.includes("--minimized") || resolveMinimizeWindowPreference();
+            let minimized = false;
+            let minimizeNote;
+            if (wantsMinimized && !headless) {
+                try {
+                    const outcome = await minimizeChatGptWindow({ port: opened.port });
+                    minimized = outcome.minimized;
+                    minimizeNote = outcome.minimized
+                        ? "window: minimized out of the way - the tab still reads visible, so consults keep working."
+                        : `window: this desktop reports a minimized window as ${outcome.visibilityState}, and prodex will not send into a tab it cannot read - the window was restored. Keep it open behind your editor instead.`;
+                }
+                catch (error) {
+                    minimizeNote = `window: could not minimize (${errorMessage(error)}); leaving it as it is.`;
+                }
+            }
+            await recordBrowserLoginLaunch({
+                profile_dir: opened.profileDir,
+                port: opened.port,
+                headless,
+                minimized,
+                ...(virtualDisplay ? { virtual_display: virtualDisplay.displayNumber } : {})
+            });
+            if (virtualDisplay) {
+                io.stdout(`window: none - running on virtual display :${virtualDisplay.displayNumber}${virtualDisplay.startedNow ? " (started now)" : " (reused)"}.`);
+            }
             printBrowserLoginGuide(io.stdout, {
                 opened: !alreadyRunning,
                 reused: alreadyRunning,
@@ -252,15 +299,26 @@ export async function runProCommand(rest, io, runCliFn) {
                 sourceCli,
                 commandOptions
             });
+            if (minimizeNote)
+                io.stdout(minimizeNote);
             if (headless) {
                 // Nobody can sign in to a window that does not exist, so a headless
                 // launch is only useful when the profile is already logged in.
                 // Verify it here (bounded, no human to wait for) instead of letting
                 // the first consult fail with a confusing not-logged-in blocker.
-                const headlessReady = await waitForChatGptLoginReady(io.stderr, { port: opened.port, timeoutMs: 30_000 });
+                const headlessWaitMs = readPositiveIntegerFlag(browserArgs, "--wait-timeout-ms") ?? 30_000;
+                const headlessReady = await waitForChatGptLoginReady(io.stderr, { port: opened.port, timeoutMs: headlessWaitMs });
                 if (!headlessReady) {
+                    // Name the real cause. Cloudflare rejects headless Chrome by
+                    // design (its docs list headless browsers as unsupported), and
+                    // reporting that as "not signed in" sent users to re-login over
+                    // and over instead of back to a headed window.
+                    const finalStatus = await getChatGptBrowserStatus({ port: opened.port, timeoutMs: 5_000 }).catch(() => undefined);
+                    const challenged = finalStatus?.blocker?.code === "cloudflare_check" || /just a moment/i.test(finalStatus?.title ?? "");
                     io.stdout("");
-                    io.stdout(`headless: the profile is not signed in. Run \`${formatBrowserLoginCommand(sourceCli, commandOptions)}\` WITHOUT --headless once, sign in, close that window, then rerun with --headless.`);
+                    io.stdout(challenged
+                        ? "headless: Cloudflare challenged the headless browser and never let ChatGPT load. This is expected - Cloudflare lists headless browsers as unsupported. Run without --headless, or run a real headed Chrome on a virtual display (Xvfb) and point prodex at it with DISPLAY."
+                        : `headless: the profile is not signed in. Run \`${formatBrowserLoginCommand(sourceCli, commandOptions)}\` WITHOUT --headless once, sign in, close that window, then rerun with --headless.`);
                     return 1;
                 }
                 io.stdout("headless: signed-in session confirmed - consults will run with no visible window.");
@@ -560,6 +618,12 @@ export async function runProCommand(rest, io, runCliFn) {
 export async function runConsultsCommand(rest, io) {
     throw new Error("The legacy `consults` alias is retired. Use `prodex pro list`, `prodex pro latest`, or `prodex pro show <task-id|latest>`.");
 }
+// PRODEX_MINIMIZE_WINDOW=1 gives the no-window setup to every entry point,
+// including the MCP server's auto-recovery, without a CLI flag.
+export function resolveMinimizeWindowPreference(env = process.env) {
+    const raw = (env.PRODEX_MINIMIZE_WINDOW ?? "").trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes";
+}
 function autoLoginDisabledByEnv(env = process.env) {
     const raw = (env.PRODEX_NO_AUTO_LOGIN ?? "").trim().toLowerCase();
     return raw === "1" || raw === "true" || raw === "yes";
@@ -1119,16 +1183,30 @@ export async function attemptBrowserAutoRecovery(stderr, options) {
         // visible window for someone running headless would be exactly the
         // surprise window they turned headless to avoid.
         const headless = resolveHeadlessPreference(lastLogin?.headless);
+        // Rejoin the same virtual display the user set up, so recovery does not
+        // put a window back on a desktop they deliberately keep empty.
+        const virtualDisplay = lastLogin?.virtual_display !== undefined || resolveVirtualDisplayPreference()
+            ? await ensureVirtualDisplay(lastLogin?.virtual_display !== undefined ? { displayNumber: lastLogin.virtual_display } : {}).catch(() => undefined)
+            : undefined;
         const opened = openChatGptBrowser({
             ...(options.port !== undefined ? { port: options.port } : {}),
             ...(lastLogin?.profile_dir ? { profileDir: lastLogin.profile_dir } : {}),
-            ...(headless ? { headless } : {})
+            ...(headless ? { headless } : {}),
+            ...(virtualDisplay ? { virtualDisplay: { displayNumber: virtualDisplay.displayNumber, xauthority: virtualDisplay.xauthority } } : {})
         });
         await assertBrowserLaunchStayedAlive(opened);
         const ready = await waitForChatGptLoginReady(stderr, { port: opened.port, timeoutMs: 120_000 });
-        if (ready)
-            stderr("recover: browser READY - retrying the send...");
-        return ready;
+        if (!ready)
+            return false;
+        // Restore the no-window setup too: someone who runs minimized does not
+        // want recovery to leave a window sitting on their desktop.
+        if (!headless && (lastLogin?.minimized === true || resolveMinimizeWindowPreference())) {
+            const outcome = await minimizeChatGptWindow({ port: opened.port }).catch(() => undefined);
+            if (outcome?.minimized)
+                stderr("recover: window minimized again");
+        }
+        stderr("recover: browser READY - retrying the send...");
+        return true;
     }
     catch (error) {
         stderr(`recover: failed - ${errorMessage(error)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youdie006/prodex",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Local receipt bus for coordinating Codex execution with ChatGPT Pro/Projects consultation.",
   "author": "youdie006",
   "license": "MIT",