@youdie006/prodex 0.16.33 → 0.18.0

package/README.md

@@ -256,6 +256,38 @@ 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 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 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.
+
 Whatever selection is applied is recorded on the consult receipt (`metadata.selection`); receipt display output redacts the project name, keeping only the model axes visible. `prodex` only clicks the picker you can see; it never selects a model, effort, or project silently outside the visible browser.
 
 For a source checkout, keep the explicit send and inspection commands source-aware too:

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";
@@ -167,13 +169,23 @@ export async function readLastBrowserLoginLaunch() {
         const parsed = JSON.parse(await readFile(lastBrowserLoginPath(), "utf8"));
         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.port === "number" && Number.isInteger(parsed.port) ? { port: parsed.port } : {}),
+            ...(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 {
         return undefined;
     }
 }
+// Headless Chrome defaults to an 800x600 viewport, at which ChatGPT collapses
+// the sidebar - and the sidebar carries the logged-in signals that
+// inferLoggedInLikely reads ("New chat"/"Projects"). Pin a desktop width so a
+// headless session is not misread as logged out.
+const HEADLESS_WINDOW_SIZE = "1440,900";
 export function buildChromeLaunchArgs(options) {
     return [
         "--remote-debugging-address=127.0.0.1",
@@ -181,10 +193,182 @@ export function buildChromeLaunchArgs(options) {
         `--user-data-dir=${options.profileDir}`,
         "--no-first-run",
         "--no-default-browser-check",
-        "--new-window",
+        // 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
     ];
 }
+/**
+ * Headless is opt-in: an explicit option wins, otherwise PRODEX_HEADLESS
+ * (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;
+    const raw = (env.PRODEX_HEADLESS ?? "").trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes";
+}
 export function inferLoggedInLikely(text, visibleButtonLabels = []) {
     // Only sign-up prompts and explicit login/sign-up buttons count as logged-out signals. Bare
     // "Log in"/"로그인" substrings appear in the menus and footers of a logged-in page, so matching
@@ -314,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.",
@@ -638,12 +825,17 @@ export function openChatGptBrowser(options = {}) {
     const command = resolveChromeCommand();
     const port = resolveCdpPort(options.port);
     const profileDir = options.profileDir ?? defaultChatGptProfileDir();
+    const headless = resolveHeadlessPreference(options.headless);
     const args = buildChromeLaunchArgs({
         port,
         profileDir,
-        url: options.url ?? "https://chatgpt.com/"
+        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) => {
@@ -709,7 +901,14 @@ export async function getChatGptBrowserStatus(options = {}) {
             blocker: chatGptPageMissingBlocker()
         };
     }
-    const state = await evaluateOnPage(page.page, statusExpression());
+    // Bound the status read by the CALLER's budget, not the 20s default CDP
+    // command timeout: a very heavy ChatGPT thread answers slowly, and
+    // `pro browser check --timeout-ms 5000` measured 65 seconds because every
+    // evaluate silently used the default. Agents read that silence as a hung
+    // bridge and start "recovering" a browser that is merely busy.
+    const state = await evaluateOnPage(page.page, statusExpression(), {
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {})
+    });
     const loggedInLikely = inferChatGptPageLoggedInLikely(state);
     const blocker = chatGptVisibilityBlocker(state.visibilityState, state.url) ?? detectChatGptPageBlocker(state) ?? chatGptBusyBlocker(state.generating);
     return {
@@ -2076,12 +2275,43 @@ async function insertComposerTextViaCdp(cdp, text) {
         await cdp.send("Input.dispatchKeyEvent", { type: "keyUp", key: "Backspace", code: "Backspace", windowsVirtualKeyCode: 8 });
         await sleep(100);
     }
-    await cdp.send("Input.insertText", { text });
+    // Insert in bounded chunks: a single multi-KB Input.insertText makes
+    // ProseMirror do one huge transaction, which on a heavy thread stalls past
+    // the 20s CDP command timeout and kills the send with "Chrome DevTools
+    // command timed out: Input.insertText" (field failure on long prompts,
+    // twice in one session). Each chunk gets its own command budget.
+    for (const chunk of chunkComposerText(text)) {
+        await cdp.send("Input.insertText", { text: chunk });
+    }
     await sleep(200);
     const state = await cdp.evaluate(composerTextStateExpression(text));
     if (!state.ok)
         throw new Error(state.reason ?? "Composer stayed empty after text insertion");
 }
+export const COMPOSER_INSERT_CHUNK_CHARS = 4_000;
+/**
+ * Split composer text into insertText-sized pieces. Splits on code points (not
+ * UTF-16 units) so a surrogate pair - an emoji, or any astral character - can
+ * never be cut in half and arrive as two replacement characters.
+ */
+export function chunkComposerText(text, size = COMPOSER_INSERT_CHUNK_CHARS) {
+    if (text.length === 0)
+        return [];
+    if (text.length <= size)
+        return [text];
+    const chunks = [];
+    let current = "";
+    for (const character of text) {
+        if (current.length + character.length > size) {
+            chunks.push(current);
+            current = "";
+        }
+        current += character;
+    }
+    if (current.length > 0)
+        chunks.push(current);
+    return chunks;
+}
 export function submitExpression() {
     return `(() => {
     ${composerExpressionHelpers()}

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] [--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] [--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] [--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] [--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, 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"]
+                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"]);
+            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");
             }
@@ -221,24 +221,109 @@ export async function runProCommand(rest, io, runCliFn) {
             // again: Chrome's singleton would just open ANOTHER window (the recurring
             // "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
+                // once, and reusing the running one would silently ignore the
+                // requested mode. Say so instead of pretending the switch took.
+                const previous = await readLastBrowserLoginLaunch();
+                const runningHeadless = previous?.port === port ? previous.headless === true : undefined;
+                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 });
+                : 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.
-            await recordBrowserLoginLaunch({ profile_dir: opened.profileDir, port: opened.port });
+            // Remember this launch so ask auto-recovery reuses the same profile
+            // AND the same window mode.
+            // 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,
+                headless,
                 loginUrl,
                 profileDir: opened.profileDir,
                 port: opened.port,
                 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 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(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.");
+                return 0;
+            }
             // Guided wait: interactive terminals walk the user to a verified READY
             // state instead of returning while login is still unfinished. Scripts
             // and agents (non-TTY) keep the immediate return unless --wait is
@@ -533,6 +618,16 @@ 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";
+}
 // Retired browser subcommands map to the one that replaced them. Every value
 // here must be a subcommand that actually exists, so the error is a single hop
 // to a runnable command.
@@ -1034,6 +1129,12 @@ export async function performBrowserConsultForMcp(cwd, input, onProgress) {
     const stderrLines = [];
     const argv = [
         "--send",
+        // MCP callers have no terminal, so the interactive auto-recovery gate
+        // never fired for them: a closed browser made every pro_consult fail with
+        // a step the agent had to shell out for (the single most common field
+        // failure). Recovery reuses the saved profile and window mode, and
+        // PRODEX_NO_AUTO_LOGIN=1 turns it off.
+        ...(autoLoginDisabledByEnv() ? ["--no-auto-login"] : ["--auto-login"]),
         ...(input.model !== undefined ? ["--model", input.model] : []),
         ...(input.pro_mode !== undefined ? ["--pro-mode", input.pro_mode] : []),
         ...(input.effort !== undefined ? ["--effort", input.effort] : []),
@@ -1078,15 +1179,34 @@ export async function attemptBrowserAutoRecovery(stderr, options) {
         // profile for a custom-profile user would wait on the wrong (logged-out)
         // profile or, worse, silently send to a different account.
         const lastLogin = await readLastBrowserLoginLaunch();
+        // Relaunch in the SAME window mode the user chose: silently reopening a
+        // 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 } : {})
+            ...(lastLogin?.profile_dir ? { profileDir: lastLogin.profile_dir } : {}),
+            ...(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)}`);
@@ -1185,6 +1305,18 @@ export function browserSendBlockerFromError(error) {
             next_step: `Rerun with a bigger budget (${formatDurationMs(suggestedMs)}): \`prodex pro browser ask --timeout-ms ${suggestedMs} "<same prompt>"\`.`
         };
     }
+    // A CDP command timeout means the page's renderer stalled, which in the
+    // field means a very long thread (or a long prompt landing on one). Generic
+    // "resolve the browser issue manually" advice gave the caller nothing to do.
+    const cdpTimeout = message.match(/Chrome DevTools command timed out: (\S+)/);
+    if (cdpTimeout) {
+        return {
+            code: "browser_cdp_timeout",
+            message,
+            retryable: true,
+            next_step: "The ChatGPT tab stopped responding (usually a very long thread). Retry with `--new-chat` for a fresh, light thread, or reload the tab in the browser first."
+        };
+    }
     return {
         code: "browser_send_failed",
         message,
@@ -1260,33 +1392,52 @@ export async function getConsult(store, taskId, options = {}) {
     return isConsultRecord(record) ? record : undefined;
 }
 export async function latestTrustedConsult(store, options = { readOnly: true }) {
-    const entries = await listConsultListEntries(store, options);
-    const trusted = entries.find((entry) => entry.kind === "trusted");
-    if (trusted)
-        return trusted.consult;
-    const untrusted = entries.find((entry) => entry.kind === "untrusted");
-    if (untrusted)
-        throw untrusted.error;
+    // Verify lazily, newest first, and stop at the first trusted consult.
+    // Verifying the whole history to report ONE record made `pro browser check`
+    // spend 42 of its 46 seconds in latest_pro on a repo with real history
+    // (measured live) - each record is a full receipt scan - and agents read
+    // that silence as a hung bridge.
+    const records = await listConsultRecordsNewestFirst(store, options);
+    let firstUntrusted;
+    for (const record of records) {
+        try {
+            return { ...record, result: await store.getFinalizedResultReadOnly(record.result.task_id) };
+        }
+        catch (error) {
+            if (isUntrustedResultError(error)) {
+                firstUntrusted ??= error;
+                continue;
+            }
+            throw error;
+        }
+    }
+    if (firstUntrusted)
+        throw firstUntrusted;
     return undefined;
 }
 export function legacyChatGptNamespaceError(subcommand) {
     const prefix = subcommand ? `Unknown legacy chatgpt subcommand: ${subcommand}.` : "The legacy `chatgpt` namespace is hidden.";
     return new Error(`${prefix} Use \`prodex pro browser help\` for visible-browser commands.`);
 }
-export async function listConsultListEntries(store, options = { readOnly: true }) {
+// Consult records (unverified) newest first, with the ledger-integrity checks
+// that must run regardless of how many records the caller ends up verifying.
+async function listConsultRecordsNewestFirst(store, options = { readOnly: true }) {
     const [tasks, results] = options.readOnly === false
         ? await Promise.all([store.listTasks(), store.listResults()])
         : await Promise.all([listTasksForInspection(store), listRawResultsForInspection(store)]);
     const tasksById = new Map(tasks.map((task) => [task.id, task]));
     assertNoMissingTerminalConsultResults(tasks, results);
     assertNoOrphanConsultResults(tasksById, results);
-    const records = results
+    return results
         .map((result) => {
         const task = tasksById.get(result.task_id);
         return task ? { task, result } : undefined;
     })
         .filter((record) => Boolean(record && isConsultRecord(record)))
         .sort((a, b) => b.result.created_at.localeCompare(a.result.created_at));
+}
+export async function listConsultListEntries(store, options = { readOnly: true }) {
+    const records = await listConsultRecordsNewestFirst(store, options);
     const entries = [];
     for (const record of records) {
         try {
@@ -1303,7 +1454,7 @@ export async function listConsultListEntries(store, options = { readOnly: true }
     return entries;
 }
 export function printBrowserLoginGuide(stdout, input) {
-    const windowAvailable = input.opened || input.reused === true;
+    const windowAvailable = (input.opened || input.reused === true) && input.headless !== true;
     const loginCommand = formatBrowserLoginCommand(input.sourceCli, input.commandOptions);
     const runtimeCommandOptions = {
         ...(input.commandOptions?.cwd ? { cwd: input.commandOptions.cwd } : {}),
@@ -1312,11 +1463,20 @@ export function printBrowserLoginGuide(stdout, input) {
     const checkCommand = formatBrowserCheckCommand(input.sourceCli, runtimeCommandOptions);
     const smokeCommand = formatBrowserSmokeCommand(input.sourceCli, runtimeCommandOptions);
     stdout("ChatGPT Pro browser login");
-    stdout(input.reused
-        ? "Chrome is already running for ChatGPT - reusing it (no new window opened)."
-        : input.opened
-            ? "Opened the dedicated Chrome window for ChatGPT."
-            : "Dry run: no browser was opened.");
+    stdout(input.headless && (input.opened || input.reused)
+        ? input.reused
+            ? "Headless ChatGPT browser is already running - reusing it (no window)."
+            : "Started the dedicated ChatGPT browser headless (no window). It reuses the profile you signed in with."
+        : input.reused
+            ? "Chrome is already running for ChatGPT - reusing it (no new window opened)."
+            : input.opened
+                ? "Opened the dedicated Chrome window for ChatGPT."
+                : "Dry run: no browser was opened.");
+    if (input.headless && (input.opened || input.reused)) {
+        stdout("");
+        stdout(`Next: run \`${checkCommand}\` to confirm the session, then consult as usual.`);
+        return;
+    }
     stdout("");
     stdout("Steps:");
     if (windowAvailable) {

package/package.json

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