@youdie006/prodex 0.16.32 → 0.17.0

package/README.md

@@ -256,6 +256,17 @@ 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
+
+`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.
+
+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/browser-send-lock.js

@@ -115,7 +115,7 @@ export async function withBrowserSendLock(waitMs, onWait, fn) {
             continue;
         }
         if (Date.now() >= deadline) {
-            throw new Error(`Another prodex browser send is in progress (pid ${holder.pid}). Wait for it to finish, or pass --busy-wait-ms to queue behind it.`);
+            throw new Error(`Another prodex browser send is in progress (pid ${holder.pid}) and did not finish within the wait budget. Retry once it finishes, or raise --timeout-ms (which is also the queue budget).`);
         }
         if (!waited) {
             waited = true;

package/dist/chatgpt-browser.js

@@ -167,13 +167,19 @@ 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 } : {})
         };
     }
     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 +187,21 @@ export function buildChromeLaunchArgs(options) {
         `--user-data-dir=${options.profileDir}`,
         "--no-first-run",
         "--no-default-browser-check",
-        "--new-window",
+        ...(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.
+ */
+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
@@ -638,10 +655,12 @@ 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() });
     let earlyExit;
@@ -709,7 +728,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 {
@@ -1308,7 +1334,7 @@ export async function recoverChatGptAnswerFromThread(options) {
             code: "browser_unreachable",
             message: `No Chrome DevTools endpoint is reachable on 127.0.0.1:${port}.`,
             retryable: true,
-            next_step: "Run `prodex pro browser login`, log in, then retry."
+            next_step: "Run `prodex pro browser login` to reopen the dedicated window - it reuses the saved session (no manual login unless it expired) and returns immediately when run non-interactively - then retry."
         });
     }
     const cdp = await connectCdp(page.page.webSocketDebuggerUrl);
@@ -1790,7 +1816,7 @@ async function findChatGptPage(port, timeoutMs, targetUrl) {
                 code: "browser_unreachable",
                 message: `No Chrome DevTools endpoint is reachable on 127.0.0.1:${port}.`,
                 retryable: true,
-                next_step: "Run `prodex pro browser login`, log in, then retry.",
+                next_step: "Run `prodex pro browser login` to reopen the dedicated window - it reuses the saved session (no manual login unless it expired) and returns immediately when run non-interactively - then retry.",
                 ...(error instanceof Error ? { detail: error.message } : {})
             }
         };
@@ -2076,12 +2102,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,14 +19,14 @@ 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] [--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]
   prodex pro browser models [--source-cli /absolute/path/to/dist/cli.js] [--port 9333] [--timeout-ms 15000]  # read-only list of model menu options
   prodex pro browser projects [--source-cli /absolute/path/to/dist/cli.js] [--port 9333] [--timeout-ms 15000]  # read-only list of sidebar project names (for --project)
   prodex pro browser recover [--source-cli /absolute/path/to/dist/cli.js] [--cwd /absolute/path/to/repo] [--port 9333] --target-url <thread-url> [--timeout-ms 60000]  # recover a finished answer from a thread whose send timed out
-  prodex pro browser ask [--source-cli /absolute/path/to/dist/cli.js] [--cwd /absolute/path/to/repo] [--port 9333] [--timeout-ms 90000] [--busy-wait-ms 600000] [--target-url url --confirm-target] [--new-chat] [--stdin] [--json] [--auto-login|--no-auto-login] [--file path] [--model Pro] [--pro-mode 기본|확장] [--effort 즉시|중간|높음|"매우 높음"] [--project "name" | --project-new "name"] "prompt"  # explicit visible-browser send
+  prodex pro browser ask [--source-cli /absolute/path/to/dist/cli.js] [--cwd /absolute/path/to/repo] [--port 9333] [--timeout-ms 300000] [--busy-wait-ms 600000] [--target-url url --confirm-target] [--new-chat] [--stdin] [--json] [--auto-login|--no-auto-login] [--file path] [--model Pro] [--pro-mode 기본|확장] [--effort 즉시|중간|높음|"매우 높음"] [--project "name" | --project-new "name"] "prompt"  # explicit visible-browser send
   prodex pro latest [--source-cli /absolute/path/to/dist/cli.js] [--cwd /absolute/path/to/repo]
   prodex pro list [--source-cli /absolute/path/to/dist/cli.js] [--cwd /absolute/path/to/repo] [--json]
   prodex pro show <task-id|latest> [--source-cli /absolute/path/to/dist/cli.js] [--cwd /absolute/path/to/repo]
@@ -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] [--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] [--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]";
     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]";
@@ -252,8 +252,8 @@ export function printProBrowserHelp(stdout, sourceCli) {
         : "prodex pro browser smoke [--source-cli /absolute/path/to/dist/cli.js] [--cwd /absolute/path/to/repo] [--port 9333] [--timeout-ms 90000]";
     const selectionUsage = '[--model Pro] [--pro-mode 기본|확장] [--effort 즉시|중간|높음|"매우 높음"] [--project "name" | --project-new "name"]';
     const askUsage = sourceCli
-        ? `${cli} pro browser ask${sourceCliOption} [--cwd /absolute/path/to/repo] [--port 9333] [--timeout-ms 90000] [--busy-wait-ms 600000] [--target-url url --confirm-target] [--new-chat] [--stdin] [--json] [--auto-login|--no-auto-login] [--file path] ${selectionUsage} "prompt"`
-        : `prodex pro browser ask [--source-cli /absolute/path/to/dist/cli.js] [--cwd /absolute/path/to/repo] [--port 9333] [--timeout-ms 90000] [--busy-wait-ms 600000] [--target-url url --confirm-target] [--new-chat] [--stdin] [--json] [--auto-login|--no-auto-login] [--file path] ${selectionUsage} "prompt"`;
+        ? `${cli} pro browser ask${sourceCliOption} [--cwd /absolute/path/to/repo] [--port 9333] [--timeout-ms 300000] [--busy-wait-ms 600000] [--target-url url --confirm-target] [--new-chat] [--stdin] [--json] [--auto-login|--no-auto-login] [--file path] ${selectionUsage} "prompt"`
+        : `prodex pro browser ask [--source-cli /absolute/path/to/dist/cli.js] [--cwd /absolute/path/to/repo] [--port 9333] [--timeout-ms 300000] [--busy-wait-ms 600000] [--target-url url --confirm-target] [--new-chat] [--stdin] [--json] [--auto-login|--no-auto-login] [--file path] ${selectionUsage} "prompt"`;
     const modelsUsage = sourceCli
         ? `${cli} pro browser models${sourceCliOption} [--port 9333] [--timeout-ms 15000]`
         : "prodex pro browser models [--source-cli /absolute/path/to/dist/cli.js] [--port 9333] [--timeout-ms 15000]";

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, readLastBrowserLoginLaunch, 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"]
             })) {
                 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"]);
             if (browserArgs.includes("--wait") && browserArgs.includes("--no-wait")) {
                 throw new Error("pro browser login cannot combine --wait and --no-wait");
             }
@@ -221,24 +221,51 @@ 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);
             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.`);
+                }
+            }
             const opened = alreadyRunning
                 ? { profileDir: profileDir ?? defaultChatGptProfileDir(), port }
-                : openChatGptBrowser({ port, profileDir, url: loginUrl });
+                : openChatGptBrowser({ port, profileDir, url: loginUrl, ...(headless ? { headless } : {}) });
             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.
+            await recordBrowserLoginLaunch({ profile_dir: opened.profileDir, port: opened.port, headless });
             printBrowserLoginGuide(io.stdout, {
                 opened: !alreadyRunning,
                 reused: alreadyRunning,
+                headless,
                 loginUrl,
                 profileDir: opened.profileDir,
                 port: opened.port,
                 sourceCli,
                 commandOptions
             });
+            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 });
+                if (!headlessReady) {
+                    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.`);
+                    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
@@ -277,8 +304,7 @@ export async function runProCommand(rest, io, runCliFn) {
             }
         }
         if (browserSubcommand === "open" || browserSubcommand === "status" || browserSubcommand === "doctor") {
-            const replacement = browserSubcommand === "open" ? "login" : "check";
-            throw new Error(`Use \`prodex pro browser ${replacement}\` for explicit browser automation.`);
+            throw new Error(`Use \`prodex pro browser ${legacyBrowserSubcommandReplacement(browserSubcommand)}\` for explicit browser automation.`);
         }
         if (browserSubcommand === "smoke") {
             if (printProBrowserHelpIfRequested(browserArgs, "pro browser smoke", io, { valueFlags: ["--cwd", "--port", "--timeout-ms", "--source-cli"] }))
@@ -426,7 +452,10 @@ export async function runProCommand(rest, io, runCliFn) {
         throw unknownSubcommandError("pro browser", browserSubcommand, ["login", "ask", "smoke", "check", "models", "projects", "recover"]);
     }
     if (subcommand === "open" || subcommand === "status" || subcommand === "smoke" || subcommand === "check" || subcommand === "doctor") {
-        throw new Error(`Use \`prodex pro browser ${subcommand === "doctor" ? "check" : subcommand}\` for explicit browser automation.`);
+        // Point at a subcommand that EXISTS: `pro status` used to say "use `pro
+        // browser status`", which itself errors with "use `pro browser check`" -
+        // a two-hop dead end that made an agent abandon the diagnosis.
+        throw new Error(`Use \`prodex pro browser ${legacyBrowserSubcommandReplacement(subcommand)}\` for explicit browser automation.`);
     }
     if (subcommand === "list") {
         if (printHelpIfRequested(proArgs, "pro list", io.stdout, printProHelp, { valueFlags: ["--cwd", "--source-cli"] }))
@@ -531,6 +560,20 @@ 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>`.");
 }
+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.
+function legacyBrowserSubcommandReplacement(subcommand) {
+    if (subcommand === "open")
+        return "login";
+    if (subcommand === "smoke")
+        return "smoke";
+    return "check";
+}
 // File marker + human-pacing gate for visible-browser sends. Reads the previous
 // send's start time from .bridge/last-browser-send, waits out any remaining
 // minimum interval (auto-throttle, not an error), then stamps the new send.
@@ -702,7 +745,11 @@ export async function runAskProCommand(rest, io) {
     const effectiveProSelection = selectionProMode !== undefined || (selectionModel !== undefined && /pro/i.test(selectionModel));
     // Pro reasoning routinely runs 6-20 minutes; 15 min was still cutting long
     // answers off (field report), so a Pro selection defaults to 20 minutes.
-    const defaultBrowserTimeoutMs = effectiveProSelection ? 1_200_000 : 90_000;
+    // With NO model selection at all (no flag, no saved default) the UI's
+    // current model is unknown and may be Pro, so the floor is 5 minutes: the
+    // old 90s guess made repos without saved defaults time out on ordinary
+    // consults (observed in several field sessions).
+    const defaultBrowserTimeoutMs = effectiveProSelection ? 1_200_000 : 300_000;
     const browserTimeoutMs = hasSendMode
         ? (readPositiveIntegerFlag(parsedAskPro.optionArgs, "--timeout-ms") ?? defaultBrowserTimeoutMs)
         : undefined;
@@ -759,7 +806,12 @@ export async function runAskProCommand(rest, io) {
             }
             throw new Error(formatBlockedConsultRecordedMessage(blocker.message, task.id, sourceCli, { cwd: targetCwd }));
         }
-        const sendOnce = () => withBrowserSendLock(busyWaitMs ?? 0, (detail) => io.stderr(`progress: ${detail}`), () => sendChatGptPrompt({
+        // Queue behind another prodex send by default (same budget as the send
+        // itself). MCP consults cannot pass --busy-wait-ms at all, so the old
+        // fail-fast default made pro_consult die instantly with advice the
+        // caller had no way to follow; --busy-wait-ms 0 opts back into failing
+        // fast. A dead holder is still reaped immediately.
+        const sendOnce = () => withBrowserSendLock(busyWaitMs ?? browserTimeoutMs ?? 0, (detail) => io.stderr(`progress: ${detail}`), () => sendChatGptPrompt({
             port: browserPort,
             prompt: bundle.text,
             targetUrl: normalizedTargetUrl,
@@ -1013,6 +1065,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] : []),
@@ -1057,9 +1115,14 @@ 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);
         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 } : {})
         });
         await assertBrowserLaunchStayedAlive(opened);
         const ready = await waitForChatGptLoginReady(stderr, { port: opened.port, timeoutMs: 120_000 });
@@ -1164,6 +1227,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,
@@ -1239,33 +1314,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 {
@@ -1282,7 +1376,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 } : {}),
@@ -1291,11 +1385,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) {
@@ -1366,7 +1469,10 @@ export async function printProductCheck(store, io, args, configCwd = io.cwd) {
     }
     catch (error) {
         if (isMissingFileError(error)) {
-            io.stdout(`config: missing - run \`${formatSetupCommand(sourceCli, { cwd: setupHintCwd })}\``);
+            // Name it optional: browser consults need no config at all, but agents
+            // reading "config: missing" in an otherwise healthy check concluded
+            // prodex was unconfigured and went chasing `setup` (field sessions).
+            io.stdout(`config: missing - run \`${formatSetupCommand(sourceCli, { cwd: setupHintCwd })}\` (optional - only the HTTP MCP surface needs it; browser consults work without it)`);
         }
         else {
             io.stdout(`config: failed ${sourceAwareSetupMessage(errorMessage(error), sourceCli, { cwd: setupHintCwd })}`);
@@ -1412,6 +1518,15 @@ export async function printProductCheck(store, io, args, configCwd = io.cwd) {
             if (nextStep)
                 io.stdout(`next: ${nextStep}`);
         }
+        else if (browserStatus.blocker?.code === "response_in_progress") {
+            // Busy is not broken: the session is healthy and answering, and sends
+            // queue behind it automatically. Reporting it as "blocked" made agents
+            // conclude the browser was down and start relaunching/logging in (field
+            // failure, observed across several repos).
+            io.stdout(`chatgpt: busy ${browserStatus.blocker.code} - ${browserStatus.blocker.message}`);
+            io.stdout("next: No action needed - a send queues behind it automatically (--busy-wait-ms 0 fails fast instead).");
+            chatgptReady = true;
+        }
         else if (browserStatus.blocker) {
             const visibilityText = browserStatus.blocker.code === "tab_not_visible" ? ` visibility=${browserStatus.visibilityState ?? "unknown"}` : "";
             io.stdout(`chatgpt: blocked ${browserStatus.blocker.code}${visibilityText} - ${browserStatus.blocker.message}`);

package/dist/cli.js

@@ -929,7 +929,10 @@ async function runDoctor(store, io, sourceCli, setupHintCwd) {
     }
     catch (error) {
         if (isMissingFileError(error)) {
-            io.stdout(`config: missing - run \`${formatSetupCommand(sourceCli, { cwd: setupHintCwd })}\``);
+            // Name it optional: browser consults need no config at all, but agents
+            // reading "config: missing" in an otherwise healthy check concluded
+            // prodex was unconfigured and went chasing `setup` (field sessions).
+            io.stdout(`config: missing - run \`${formatSetupCommand(sourceCli, { cwd: setupHintCwd })}\` (optional - only the HTTP MCP surface needs it; browser consults work without it)`);
         }
         else {
             ok = false;

package/dist/mcp.js

@@ -142,7 +142,10 @@ export function createServer(cwd = process.cwd(), options = {}) {
             inputSchema: {
                 prompt: McpBridgeTextSchema.min(1),
                 model: McpShortTextSchema.optional(),
-                pro_mode: McpShortTextSchema.optional(),
+                // pro_mode is deliberately NOT advertised: ChatGPT's 2026-07 update
+                // removed Pro sub-modes, and agents that saw the field passed
+                // nonsense ("true") and got a hard validation error instead of an
+                // answer. Unknown keys are stripped, so a stale caller still works.
                 effort: McpShortTextSchema.optional(),
                 project: McpShortTextSchema.optional(),
                 timeout_ms: z.number().int().positive().max(3_600_000).optional(),

package/package.json

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