@youdie006/prodex 0.17.0 → 0.19.0

package/README.md

@@ -35,7 +35,7 @@ prodex ask --file src/auth.ts "Review this for security holes"
 
 `prodex ask` is the short form of `prodex pro browser ask`; the full form and every flag work identically. In an interactive terminal, `login` keeps watching the opened window and tells you exactly which manual step is still missing (log in, clear a check, open a chat) until it reports READY. If you skip `login` and the browser is not running, an interactive `ask` recovers on its own: it launches the dedicated browser, waits for your saved session to be READY, and retries the send once (disable with `--no-auto-login`; scripts opt in with `--auto-login`). While ChatGPT thinks, `prodex` prints progress to stderr (connecting, prompt sent, elapsed seconds while generating), so a multi-minute Pro answer never looks frozen.
 
-The answer prints to your terminal and is saved under `.bridge/` for later (`prodex pro latest` re-prints it). Add `--new-chat` to send into a fresh chat (recommended for repeated consults - long threads eventually confuse send detection). For a structured second-opinion debate between your coding agent and GPT Pro, `prodex pro debate-prompt --topic "..."` prints a ready-to-paste orchestration prompt. `prodex` drives the picker you can see and deliberately will not send into a window you cannot watch — but a dedicated Chrome window left non-minimized (even behind your editor) counts as watchable, so it sends quietly in the background without stealing focus. Just don't minimize it or switch that window to another tab. Pin per-repo defaults once - `prodex setup --model Pro --project "your-project"` - so every ask runs Pro (15-minute timeout) inside that project instead of whatever the ChatGPT UI last had selected; list exact sidebar project names with `prodex pro browser projects`. Pass `--file` more than once to attach several files. When the thread is still generating a previous answer (common right after a timed-out Pro send), the send automatically queues behind it up to the timeout budget; tune that with `--busy-wait-ms` (0 fails fast with a `response_in_progress` blocker). See [First Pro Login](#first-pro-login) for the full flow, and the [FAQ](#faq) if a send stops.
+The answer prints to your terminal and is saved under `.bridge/` for later (`prodex pro latest` re-prints it). Add `--new-chat` to send into a fresh chat (recommended for repeated consults - long threads eventually confuse send detection). For a structured second-opinion debate between your coding agent and GPT Pro, `prodex pro debate-prompt --topic "..."` prints a ready-to-paste orchestration prompt. `prodex` drives the picker you can see and will not send into a tab it cannot read, so leave the dedicated window on a ChatGPT tab; it sends quietly in the background without stealing focus. Prefer no window at all? See [virtual display](#no-window-at-all-virtual-display-recommended). Pin per-repo defaults once - `prodex setup --model Pro --project "your-project"` - so every ask runs Pro (20-minute timeout) inside that project instead of whatever the ChatGPT UI last had selected; list exact sidebar project names with `prodex pro browser projects`. Pass `--file` more than once to attach several files. When the thread is still generating a previous answer (common right after a timed-out Pro send), the send automatically queues behind it up to the timeout budget; tune that with `--busy-wait-ms` (0 fails fast with a `response_in_progress` blocker). See [First Pro Login](#first-pro-login) for the full flow, and the [FAQ](#faq) if a send stops.
 
 ## Core Shape
 
@@ -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;
@@ -310,6 +477,23 @@ async function waitForFreshChatGptPage(page, timeoutMs) {
 export function hasChatGptPromptAcceptance(previous, state) {
     return state.userMessageCount > previous.userMessageCount || state.assistantMessageCount > previous.assistantMessageCount;
 }
+/**
+ * Compare the model that was ASKED for against the model that actually
+ * produced the answer (ChatGPT tags each message with data-message-model-slug).
+ * prodex used to record only the request, so a model click that silently did
+ * not take - or no model pinned at all - was invisible, and the user believed
+ * they were getting Pro reasoning when they were not.
+ */
+export function modelSelectionWarning(requestedModel, modelSlug) {
+    if (!requestedModel || !modelSlug)
+        return undefined;
+    const wantsPro = /\bpro\b/i.test(requestedModel);
+    if (!wantsPro)
+        return undefined;
+    if (/pro/i.test(modelSlug))
+        return undefined;
+    return `model_mismatch: you asked for ${requestedModel}, but the answer came from "${modelSlug}". Check the model picker in the browser; the selection did not take.`;
+}
 export function chatGptBusyBlocker(generating) {
     if (!generating)
         return undefined;
@@ -331,7 +515,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 +849,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) => {
@@ -1397,6 +1587,7 @@ export async function recoverChatGptAnswerFromThread(options) {
         title: state.title,
         answer: state.answer.trim(),
         modelHints: state.modelHints,
+        ...(state.modelSlug ? { modelSlug: state.modelSlug } : {}),
         warnings: []
     };
 }
@@ -1669,7 +1860,8 @@ export async function sendChatGptPrompt(options) {
             title: completed.title,
             answer: completed.answer.trim(),
             modelHints: completed.modelHints,
-            warnings: [...sendWarnings]
+            ...(completed.modelSlug ? { modelSlug: completed.modelSlug } : {}),
+            warnings: [...sendWarnings, modelSelectionWarning(options.model, completed.modelSlug)].filter((warning) => Boolean(warning))
         };
     }
     // Timed out while the answer was still streaming: salvage the partial text
@@ -1682,14 +1874,19 @@ export async function sendChatGptPrompt(options) {
             title: completed.title,
             answer: completed.answer.trim(),
             modelHints: completed.modelHints,
+            ...(completed.modelSlug ? { modelSlug: completed.modelSlug } : {}),
             warnings: [
                 ...sendWarnings,
+                ...(modelSelectionWarning(options.model, completed.modelSlug) ? [modelSelectionWarning(options.model, completed.modelSlug)] : []),
                 `answer_incomplete: ChatGPT was still generating after ${formatDurationMs(timeoutMs)} (${timeoutMs}ms), so the answer below may be truncated. Raise --timeout-ms and retry for the full response.`
             ]
         };
     }
-    throw new Error(`Timed out after ${formatDurationMs(timeoutMs)} (${timeoutMs}ms) waiting for ChatGPT to respond. ` +
-        "Pro reasoning can run many minutes. Raise --timeout-ms and retry.");
+    // Carry the thread the prompt landed in: ChatGPT usually finishes the answer
+    // after prodex gives up, and `pro browser recover --target-url` exists to
+    // fetch it - but only if the caller knows which thread to point at.
+    throw Object.assign(new Error(`Timed out after ${formatDurationMs(timeoutMs)} (${timeoutMs}ms) waiting for ChatGPT to respond. ` +
+        "Pro reasoning can run many minutes. Raise --timeout-ms and retry."), completed?.url ? { thread: completed.url } : {});
 }
 export function modelMenuOptionsExpression() {
     return `(() => {
@@ -2236,10 +2433,17 @@ export function answerExpression() {
       return parts.join(String.fromCharCode(10));
     };
     const lines = text.split(String.fromCharCode(10)).map((line) => line.trim()).filter(Boolean);
-    const messages = [...document.querySelectorAll('[data-message-author-role]')].map((node) => ({
-      role: node.getAttribute('data-message-author-role'),
-      text: node.innerText || ""
-    }));
+    const messages = [...document.querySelectorAll('[data-message-author-role]')].map((node) => {
+      // ChatGPT tags each message with the model that produced it, on the
+      // message node or an ancestor depending on the build. This is the only
+      // ground truth for "did the Pro selection actually take".
+      let modelSlug = node.getAttribute('data-message-model-slug') || undefined;
+      if (!modelSlug && typeof node.closest === "function") {
+        const tagged = node.closest('[data-message-model-slug]');
+        if (tagged) modelSlug = tagged.getAttribute('data-message-model-slug') || undefined;
+      }
+      return { role: node.getAttribute('data-message-author-role'), text: node.innerText || "", modelSlug };
+    });
     const assistantMessages = messages.filter((message) => message.role === "assistant");
     const userMessages = messages.filter((message) => message.role === "user");
     const assistant = assistantMessages.at(-1);
@@ -2263,6 +2467,9 @@ export function answerExpression() {
       generating: placeholder || Boolean(document.querySelector(${streamingSelector})) || buttons.some((label) => generatingControlPattern.test(label)),
       assistantMessageCount: assistantMessages.length,
       userMessageCount: userMessages.length,
+      // ChatGPT tags each assistant message with the model that produced it -
+      // the only ground truth for "did the Pro selection actually take".
+      modelSlug: assistant ? assistant.modelSlug : undefined,
       modelHints: lines.filter((line) => /GPT|Pro|Thinking|ChatGPT|Extra High|Auto/i.test(line)).slice(0, 30)
     };
   })()`;

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";
@@ -898,7 +962,9 @@ export async function runAskProCommand(rest, io) {
         // after the 2026-07 update reset that to Medium, consults meant for Pro
         // quietly ran on a mid-tier model. Warn loudly and record it.
         if (!selectionModel && !selectionProMode && !selectionEffort) {
-            persistenceWarnings.push("model_selection_warning: no model/effort was selected for this send (no per-ask flag, no saved default), so it used whatever the ChatGPT UI last had selected. Pin one with `prodex setup --model Pro` or pass --model/--effort.");
+            persistenceWarnings.push("model_selection_warning: no model/effort was selected for this send (no per-ask flag, no saved default), so it used whatever the ChatGPT UI last had selected" +
+                (consult.modelSlug ? ` - it answered as "${consult.modelSlug}"` : "") +
+                ". Pin one with `prodex setup --model Pro` or pass --model/--effort.");
         }
         // In-project threads carry the project slug in their URL
         // (/g/g-p-<project>/c/<id>); a bare /c/<id> after requesting a project
@@ -912,6 +978,8 @@ export async function runAskProCommand(rest, io) {
         // would otherwise treat a cut-off answer as complete.
         for (const warning of persistenceWarnings)
             io.stderr(warning);
+        if (consult.modelSlug)
+            io.stderr(`model_used: ${consult.modelSlug}`);
         let answerArtifactPath;
         const answerArtifactBytes = Buffer.byteLength(answerArtifactText, "utf8");
         if (answerArtifactBytes > MAX_FETCHABLE_RESULT_ARTIFACT_BYTES) {
@@ -939,6 +1007,9 @@ export async function runAskProCommand(rest, io) {
                     ...(answerArtifactPath ? { artifact_path: answerArtifactPath } : {}),
                     thread: consult.url,
                     ...(Object.keys(selectionMetadata).length > 0 ? { selection: selectionMetadata } : {}),
+                    // What actually answered, straight from ChatGPT's own tag - the
+                    // receipt used to record only what prodex asked for.
+                    ...(consult.modelSlug ? { model_used: consult.modelSlug } : {}),
                     warnings: persistenceWarnings
                 }
             });
@@ -1119,16 +1190,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)}`);
@@ -1214,6 +1299,9 @@ export function browserSendBlockerFromError(error) {
     }
     // Match the raw ms whether the message uses the old "after 90000ms" form or
     // the newer human-readable "after 20 min (1200000ms)" form.
+    const thread = typeof error === "object" && error !== null && "thread" in error && typeof error.thread === "string"
+        ? (error.thread)
+        : undefined;
     const timedOut = message.match(/Timed out after [\s\S]*?(\d+)\s*ms/);
     if (timedOut) {
         // Suggest a concrete doubled budget so the user can paste a rerun command
@@ -1224,7 +1312,11 @@ export function browserSendBlockerFromError(error) {
             code: "send_timeout",
             message,
             retryable: true,
-            next_step: `Rerun with a bigger budget (${formatDurationMs(suggestedMs)}): \`prodex pro browser ask --timeout-ms ${suggestedMs} "<same prompt>"\`.`
+            ...(thread ? { thread } : {}),
+            next_step: `Rerun with a bigger budget (${formatDurationMs(suggestedMs)}): \`prodex pro browser ask --timeout-ms ${suggestedMs} "<same prompt>"\`.` +
+                (thread
+                    ? ` ChatGPT often finishes after prodex gives up - fetch that answer instead of re-asking: \`prodex pro browser recover --target-url ${thread}\`.`
+                    : "")
         };
     }
     // A CDP command timeout means the page's renderer stalled, which in the

package/dist/cli.js

@@ -303,9 +303,13 @@ repo: ${cwd}
    ${cli} pro browser login${sourceCliOption}  # opens visible browser
    ${cli} pro browser login --dry-run${sourceCliOption}  # preview, no browser opens
    In an interactive terminal, login waits and narrates until your ChatGPT session is READY.
+   Sign in once, then keep the browser off your screen for good:
+   ${cli} pro browser login --virtual-display${sourceCliOption}  # no window anywhere (needs Xvfb: sudo apt install -y xvfb x11-xkb-utils xauth)
+   ${cli} pro browser login --minimized${sourceCliOption}  # no install; keeps the window minimized
+   Not --headless: Cloudflare rejects headless browsers, so ChatGPT never loads in one.
    Pin per-repo defaults first - otherwise sends silently use whatever the ChatGPT UI last had selected:
    ${cli} pro browser projects${sourceCliOption}  # read-only: exact sidebar project names
-   ${cli} setup --cwd ${quotedCwd} --model Pro --project "your-project"  # every ask: Pro (15-minute timeout) inside that project
+   ${cli} setup --cwd ${quotedCwd} --model Pro --project "your-project"  # every ask: Pro (20-minute timeout) inside that project
    cd ${quotedCwd}
    ${cli} ask --new-chat "Review this repo"${sourceCliOption}  # short form of pro browser ask
    ${proAskCommand}  # dry-run/manual preview
@@ -314,7 +318,7 @@ repo: ${cwd}
    ${cli} pro browser help${sourceCliOption}
    ${cli} pro browser check${sourceCliOption} --cwd ${quotedCwd}
    ${cli} pro browser smoke${sourceCliOption} --cwd ${quotedCwd}
-   Sharing the browser with other agents? Add --busy-wait-ms 600000 to queue behind an in-flight response instead of failing.
+   Sharing the browser with other agents? Sends queue behind an in-flight response automatically; pass --busy-wait-ms 0 to fail fast instead.
 
 2. Let coding agents consult ChatGPT (stdio MCP: Claude, Codex, Cursor, ...):
    ${cli} claude config --cwd ${quotedCwd}${sourceCliOption}

package/dist/schema.js

@@ -35,7 +35,11 @@ export const BlockerSchema = z.object({
     code: z.string(),
     message: z.string(),
     retryable: z.boolean().default(false),
-    next_step: z.string().optional()
+    next_step: z.string().optional(),
+    // The ChatGPT thread the prompt landed in, recorded on send failures so
+    // `pro browser recover --target-url` has something to point at: ChatGPT
+    // usually finishes the answer after prodex has given up waiting.
+    thread: z.string().optional()
 });
 export const TaskSchema = z.object({
     schema_version: z.literal(SCHEMA_VERSION),

package/package.json

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