@youdie006/prodex 0.40.12 → 0.40.13

package/README.md

@@ -69,6 +69,10 @@ prodex pro latest                 # re-print the last answer
 
 `prodex ask` is the short form of `prodex pro browser ask`; every flag works on both. The login opens its own Chrome profile (`~/.local/share/prodex/chrome-chatgpt-pro`), never your daily browser, and in a terminal it keeps watching the window and names the manual step still missing (sign in, clear a check, open a chat) until it reports READY.
 
+For a one-time visible login followed by a verified headless handoff, use `prodex pro browser login --background`. Keep the window open until `background: READY`: prodex verifies login, gracefully closes only an idle dedicated browser, then reopens the same profile and conversation headless. Future CLI/MCP relaunches reuse that mode. Other tabs, Chrome account/permission confirmation windows, unfinished input, and active answers block the handoff. A verification challenge remains a blocker; this option does not guarantee that ChatGPT accepts headless Chrome.
+
+Finish any native browser or OS confirmation before requesting the handoff: Chrome does not expose every native dialog through its page-control interface. The guard detects page targets and rendered dialogs, not every OS prompt. Incognito, guest, and explicitly selected Chrome sub-profiles are refused.
+
 While Pro thinks, progress goes to stderr: connecting, prompt sent, elapsed time while generating. A Pro selection raises the send budget to twenty minutes on its own; `--timeout-ms` overrides it. Answers are read from the rendered page, so formatting can differ from the original message. If the dedicated browser is not running, an interactive `ask` starts it, waits for your saved session, and retries once (`--no-auto-login` turns that off; scripts opt in with `--auto-login`).
 
 If the browser stops responding after your question was sent, prodex stops without sending it again. Use the `thread` and `request_id` from the error with `prodex pro browser recover --target-url <thread-url> --request-id <32hex>` (MCP: `pro_recover`). The request ID verifies that the recovered assistant answer follows that exact marked user turn. Legacy recovery without it remains available but returns `request_verified: false` and a warning.
@@ -179,9 +183,9 @@ The last recorded window mode is reused by later `login` commands and by CLI/MCP
 
 `--minimized` keeps a window but minimizes it. Under WSLg a minimized Chrome still reports itself visible and consults keep working; a normal Linux desktop marks it hidden, and prodex refuses to send into a tab it cannot read, restores the window, and tells you.
 
-`--headless` exists and is not usable against ChatGPT today: measured on a signed-in profile, headless Chrome stays on Cloudflare's interstitial past sixty seconds. Only the window is optional; the login is not.
+`--headless` may be blocked even with a saved login: a previous test on a signed-in profile stayed on Cloudflare's interstitial past sixty seconds. `--background` verifies the actual handoff and only reports READY when the signed-in composer works headless. A challenge does not prove that the saved login was lost. Only the window is optional; authentication and protection checks still apply.
 
-If a hidden or virtual browser needs login, captcha, Cloudflare, or account verification, close that browser yourself and run `prodex pro browser login --headed` to complete the interactive step. Merely omitting `--headless` does not switch modes because the saved mode persists. prodex does not bypass the protection or kill a running browser to change its mode.
+If a hidden or virtual browser needs login, captcha, Cloudflare, or account verification, close that browser yourself and run `prodex pro browser login --headed` to complete the interactive step. Merely omitting `--headless` does not switch modes because the saved mode persists. prodex does not bypass protection or force-kill a browser for a mode change; `--background` permits only the guarded graceful handoff described above.
 
 Before a prompt is submitted, a browser confirmed to have stopped answering its control port can be ended and started fresh, and the receipt says so (`PRODEX_NO_AUTO_CLEAR=1` turns that off). A browser that is merely slow is left alone. After submission, prodex never auto-resends a lost prompt.
 
@@ -249,6 +253,8 @@ Reports are deduplicated by blocker code, so something that stays broken adds to
 
 **Can I close the terminal after login?** Yes, once login is READY: the dedicated Chrome is launched separately. Keep that browser running for consults. If a CLI or agent exits during a request, ChatGPT may still finish it; recover the original thread and request ID rather than automatically sending the question again.
 
+**Does closing the Chrome window switch to headless?** No. Use `login --background` and wait for `background: READY`; ordinary headed login never silently changes mode. A closed window alone is not evidence of logout. Before an unsent request, MCP or an auto-login-enabled CLI can reopen one missing ChatGPT tab in the existing browser and recheck the saved login without restarting Chrome.
+
 **It stopped with `browser_tab_crashed` or `Runtime.enable`.** Chrome can leave an "Aw, Snap!" tab listed on its control port even though that tab's renderer has crashed. Before typing a new prompt, prodex can reload a confirmed crashed tab once at the same conversation address and records `browser_tab_recovered`. A timeout alone never authorizes a reload. A crash after a prompt was submitted stops without resending; inspect the original conversation, then recover with both `--target-url` and `--request-id` from the blocker. Other tabs, the browser profile, and saved login are left alone.
 
 **A send failed with `send_ui_changed`.** ChatGPT redesigned the composer or send control. Update (`npm i -g @youdie006/prodex@latest`); if it persists, `prodex pro report-issue`, and paste the prompt by hand meanwhile.

package/dist/browser-handoff.js

@@ -0,0 +1,189 @@
+import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import WebSocket from "ws";
+import { ChatGptBrowserBlockerError, attachmentPresenceExpression, composerTextStateExpression, detectChatGptPageBlocker, findLaunchedBrowserProcesses, inferChatGptPageLoggedInLikely, statusExpression } from "./chatgpt-browser.js";
+function blocked(message) {
+    throw new ChatGptBrowserBlockerError({
+        code: "browser_handoff_blocked", message, retryable: false,
+        next_step: "Keep only the intended idle ChatGPT tab open, finish any Chrome account or permission confirmation yourself, and retry `prodex pro browser login --background`. Do not close active work or log in again solely because the handoff stopped."
+    });
+}
+function browserIdentity(port, profileDir) {
+    const listed = spawnSync("ps", ["-Ao", "user,pid,command"], { encoding: "utf8", timeout: 5_000 });
+    if (listed.status !== 0 || typeof listed.stdout !== "string")
+        blocked("Could not verify the dedicated browser process.");
+    const pids = findLaunchedBrowserProcesses(listed.stdout, { port, profileDir });
+    const mains = listed.stdout.split(/\r?\n/).filter((line) => {
+        const pid = Number(/^\s*\S+\s+(\d+)\s/.exec(line)?.[1]);
+        return pids.includes(pid) && !/\s--type=/.test(line) && new RegExp(`--remote-debugging-port=${port}(?!\\d)`).test(line);
+    });
+    if (mains.length !== 1)
+        blocked("Could not identify exactly one dedicated browser for this port.");
+    if (/\s--(?:incognito|guest)(?:\s|=|$)/.test(mains[0]))
+        blocked("An incognito or guest browser cannot preserve its login through a restart.");
+    if (/\s--profile-directory(?:\s|=|$)/.test(mains[0]))
+        blocked("An explicitly selected Chrome sub-profile cannot be preserved by this handoff; no browser was closed.");
+    const actualProfile = /--user-data-dir=(.*?)(?=\s--|$)/.exec(mains[0])?.[1];
+    if (!actualProfile || !path.isAbsolute(actualProfile))
+        blocked("The browser profile could not be verified.");
+    try {
+        if (realpathSync(actualProfile) !== realpathSync(profileDir))
+            blocked("The actual browser profile differs from the requested profile.");
+    }
+    catch (error) {
+        if (error instanceof ChatGptBrowserBlockerError)
+            throw error;
+        blocked("The browser profile path could not be verified.");
+    }
+    return { main: Number(/^\s*\S+\s+(\d+)\s/.exec(mains[0])[1]), pids, headless: /\s--headless(?:\s|=|$)/.test(mains[0]) };
+}
+export function getDedicatedBrowserHeadlessMode(options) {
+    return browserIdentity(options.port, options.profileDir).headless;
+}
+async function readJson(port, resource) {
+    const response = await fetch(`http://127.0.0.1:${port}/json/${resource}`, { signal: AbortSignal.timeout(2_000) });
+    if (!response.ok)
+        blocked(`The browser did not answer the ${resource} identity check.`);
+    return response.json();
+}
+function localSocket(value, port, kind) {
+    if (typeof value !== "string")
+        blocked("Missing browser control socket.");
+    const url = new URL(value);
+    if (url.protocol !== "ws:" || !["127.0.0.1", "localhost", "[::1]"].includes(url.hostname) ||
+        Number(url.port) !== port || url.username || url.password || !url.pathname.startsWith(`/devtools/${kind}/`)) {
+        blocked("The control socket is not bound to the expected local browser.");
+    }
+    return value;
+}
+async function singlePage(port) {
+    const response = await readJson(port, "list");
+    if (!Array.isArray(response))
+        blocked("The browser page list is invalid.");
+    const pages = response.filter((page) => page?.type === "page");
+    if (pages.length !== 1)
+        blocked("The dedicated browser has other tabs or a Chrome confirmation surface; nothing was closed.");
+    const page = pages[0];
+    const url = new URL(page.url);
+    if (url.protocol !== "https:" || url.hostname !== "chatgpt.com" || url.username || url.password || url.port ||
+        url.searchParams.has("temporary-chat") || !page.id) {
+        blocked("Handoff requires one normal, non-temporary ChatGPT page.");
+    }
+    localSocket(page.webSocketDebuggerUrl, port, "page");
+    return page;
+}
+// Unlike normal send connections this must not enable Page or answer dialogs.
+async function request(socketUrl, method, params = {}) {
+    return new Promise((resolve, reject) => {
+        const socket = new WebSocket(socketUrl);
+        let sent = false;
+        let finished = false;
+        const finish = (error, value) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            socket.removeAllListeners();
+            socket.on("error", () => { });
+            socket.terminate();
+            if (error)
+                reject(error);
+            else
+                resolve(value);
+        };
+        const timer = setTimeout(() => finish(new Error(`${method} timed out; browser handoff stopped.`)), 5_000);
+        socket.once("open", () => {
+            try {
+                socket.send(JSON.stringify({ id: 1, method, params }));
+                sent = true;
+            }
+            catch (error) {
+                finish(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+        socket.on("message", (data) => {
+            let reply;
+            try {
+                reply = JSON.parse(data.toString());
+            }
+            catch {
+                return;
+            }
+            if (reply.id === 1)
+                finish(reply.error ? new Error(reply.error.message ?? "CDP command failed") : undefined, reply.result);
+        });
+        socket.once("error", (error) => finish(error));
+        socket.once("close", () => finish(method === "Browser.close" && sent ? undefined : new Error("Browser control socket closed before verification.")));
+    });
+}
+async function verifyIdle(page) {
+    const expression = `(() => {
+    const status = ${statusExpression()};
+    const composer = ${composerTextStateExpression()};
+    const visible = (e) => e.getClientRects().length > 0 && getComputedStyle(e).visibility !== 'hidden';
+    const attachmentState = ${attachmentPresenceExpression()};
+    return { status,
+      draft: composer.ok !== false || composer.reason !== 'Composer stayed empty after text insertion',
+      dialog: [...document.querySelectorAll('dialog[open],[role="dialog"],[aria-modal="true"]')].some(visible),
+      attachments: attachmentState.removed > 0 || [...document.querySelectorAll('input[type="file"]')].some(e => e.files?.length > 0) || [...document.querySelectorAll('[role="progressbar"]')].some(visible),
+      unpersisted: !location.pathname.includes('/c/') && !!document.querySelector('[data-message-author-role]')
+    };
+  })()`;
+    const reply = await request(page.webSocketDebuggerUrl, "Runtime.evaluate", { expression, returnByValue: true });
+    const value = reply?.result?.value;
+    if (reply?.exceptionDetails || !value?.status || [value.draft, value.dialog, value.attachments, value.unpersisted].some((v) => typeof v !== "boolean")) {
+        blocked("Could not verify the page's input and dialog state.");
+    }
+    const state = value.status;
+    if (state.url !== page.url || !state.hasComposer || !inferChatGptPageLoggedInLikely(state) || detectChatGptPageBlocker(state)) {
+        blocked("ChatGPT is not ready in the expected conversation; no browser was closed.");
+    }
+    if (state.generating || state.awaitingResponseChoice || state.openDialogText || value.draft || value.dialog || value.attachments || value.unpersisted) {
+        blocked("The page has active work, unfinished input, attachments, or a dialog; no browser was closed.");
+    }
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+/** Caller holds the shared browser send lock through this close AND relaunch. */
+export async function closeIdleChatGptBrowserForHandoff(options) {
+    const { port, profileDir } = options;
+    if (!Number.isInteger(port) || port < 1 || port > 65535 || !path.isAbsolute(profileDir))
+        blocked("Invalid browser handoff identity.");
+    const identity = browserIdentity(port, profileDir);
+    const page = await singlePage(port);
+    const version = await readJson(port, "version");
+    const socket = localSocket(version?.webSocketDebuggerUrl, port, "browser");
+    await verifyIdle(page);
+    const current = await singlePage(port);
+    const currentVersion = await readJson(port, "version");
+    if (current.id !== page.id || current.url !== page.url || current.webSocketDebuggerUrl !== page.webSocketDebuggerUrl ||
+        currentVersion.webSocketDebuggerUrl !== socket || browserIdentity(port, profileDir).main !== identity.main) {
+        blocked("The browser or conversation changed during handoff verification.");
+    }
+    await verifyIdle(current);
+    await request(socket, "Browser.close");
+    const deadline = Date.now() + 10_000;
+    while (Date.now() < deadline) {
+        if (!identity.pids.some(alive)) {
+            try {
+                await readJson(port, "version");
+            }
+            catch (error) {
+                const cause = error.cause;
+                if (cause?.code === "ECONNREFUSED")
+                    return { url: page.url };
+                blocked("The old browser exited, but its control port could not be verified closed.");
+            }
+        }
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    blocked("The dedicated browser did not finish closing. It was not force-killed and no replacement was launched.");
+}

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] [--attach path] [--tool deep-research|web-search|create-image] "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] [--headed|--headless|--minimized|--virtual-display] [--wait-timeout-ms 300000]  # preview/open 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] [--headed|--headless|--minimized|--virtual-display] [--wait-timeout-ms 300000] [--background]  # preview/open 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]
@@ -166,7 +166,7 @@ Commands:
   prodex pro ask [--dry-run] [--cwd /absolute/path/to/repo] [--file path] [--attach path] [--tool deep-research|web-search|create-image] "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] [--headed|--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] [--launch-timeout-ms 5000] [--wait|--no-wait] [--headed|--headless|--minimized|--virtual-display] [--wait-timeout-ms 300000] [--background]
   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]
@@ -251,8 +251,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] [--headed|--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] [--headed|--headless|--minimized|--virtual-display] [--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] [--headed|--headless|--minimized|--virtual-display] [--wait-timeout-ms 300000] [--background]`
+        : "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] [--headed|--headless|--minimized|--virtual-display] [--wait-timeout-ms 300000] [--background]";
     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

@@ -2,7 +2,7 @@ import { existsSync, realpathSync, statSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { buildDryRunBundle } from "./bundle.js";
-import { DEFAULT_CDP_PORT, resolveCdpPort, resolveConversationToDelete, resolveProjectToDelete, chatGptVisibilityBlocker, defaultChatGptProfileDir, formatDurationMs, getChatGptBrowserStatus, formatModelMenuOption, listChatGptModelOptions, deleteChatGptConversation, endWedgedBrowser, browserRecoveryPlan, findWedgedBrowser, wedgedBrowserBlocker, deleteChatGptProject, listChatGptProjectsWithIds, listRecentChatGptConversations, listChatGptSidebarProjects, normalizeChatGptTargetUrl, openChatGptBrowser, openChatGptTab, parseProMode, parseReasoningEffort, defaultTimeoutForTools, ensureVirtualDisplay, minimizeChatGptWindow, readLastBrowserLoginLaunch, resolveBrowserWindowMode, recordBrowserLoginLaunch, recoverChatGptAnswerFromThread, sendChatGptPrompt, statusMeansBrowserDead, namesPro, sendWarningsFromError, destinationVerification, chatGptProjectIdFromUrl } from "./chatgpt-browser.js";
+import { ChatGptBrowserBlockerError, DEFAULT_CDP_PORT, resolveCdpPort, resolveConversationToDelete, resolveProjectToDelete, chatGptVisibilityBlocker, defaultChatGptProfileDir, formatDurationMs, getChatGptBrowserStatus, formatModelMenuOption, listChatGptModelOptions, deleteChatGptConversation, endWedgedBrowser, browserRecoveryPlan, findWedgedBrowser, wedgedBrowserBlocker, deleteChatGptProject, listChatGptProjectsWithIds, listRecentChatGptConversations, listChatGptSidebarProjects, normalizeChatGptTargetUrl, openChatGptBrowser, openChatGptTab, parseProMode, parseReasoningEffort, defaultTimeoutForTools, ensureVirtualDisplay, minimizeChatGptWindow, readLastBrowserLoginLaunch, resolveBrowserWindowMode, recordBrowserLoginLaunch, recoverChatGptAnswerFromThread, sendChatGptPrompt, statusMeansBrowserDead, namesPro, sendWarningsFromError, destinationVerification, chatGptProjectIdFromUrl } 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";
@@ -206,11 +206,15 @@ 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", "--headed", "--headless", "--minimized", "--virtual-display"]
+                booleanFlags: ["--dry-run", "--wait", "--no-wait", "--headed", "--headless", "--minimized", "--virtual-display", "--background"]
             })) {
                 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", "--headed", "--headless", "--minimized", "--virtual-display"]);
+            assertOnlyOptions(browserArgs, "pro browser login", ["--cwd", "--profile-dir", "--port", "--url", "--source-cli", "--launch-timeout-ms", "--wait-timeout-ms"], ["--dry-run", "--wait", "--no-wait", "--headed", "--headless", "--minimized", "--virtual-display", "--background"]);
+            const background = browserArgs.includes("--background");
+            if (background && browserArgs.some((arg) => ["--headed", "--headless", "--minimized", "--virtual-display", "--no-wait"].includes(arg))) {
+                throw new Error("--background cannot combine with another window mode or --no-wait: it waits for login, then verifies the headless handoff.");
+            }
             if (browserArgs.includes("--wait") && browserArgs.includes("--no-wait")) {
                 throw new Error("pro browser login cannot combine --wait and --no-wait");
             }
@@ -231,8 +235,8 @@ export async function runProCommand(rest, io, runCliFn) {
                 ? resolveBrowserProfileDirForLaunch(savedLaunchForPort.profile_dir)
                 : undefined;
             const profileDir = requestedProfileDir ?? savedProfileDir;
-            const windowMode = resolveBrowserWindowMode({
-                flags: {
+            let windowMode = resolveBrowserWindowMode({
+                flags: background ? (savedLaunchForPort?.headless === true ? { headless: true } : { headed: true }) : {
                     ...(browserArgs.includes("--headed") ? { headed: true } : {}),
                     ...(browserArgs.includes("--headless") ? { headless: true } : {}),
                     ...(browserArgs.includes("--virtual-display") ? { virtualDisplay: true } : {}),
@@ -260,15 +264,21 @@ export async function runProCommand(rest, io, runCliFn) {
                     sourceCli,
                     commandOptions
                 });
+                if (background)
+                    io.stdout("background: verify login, then hand the same profile to headless Chrome under the shared send lock. No prompt is sent.");
                 return 0;
             }
             // If the dedicated Chrome is already reachable on this port, do NOT spawn
             // 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 alreadyRunning = (await getChatGptBrowserStatus({ port })).reachable;
+            if (background && alreadyRunning) {
+                const { getDedicatedBrowserHeadlessMode } = await import("./browser-handoff.js");
+                windowMode = { headless: getDedicatedBrowserHeadlessMode({ port, profileDir: profileDir ?? defaultChatGptProfileDir() }), virtualDisplay: false, minimized: false };
+            }
             const headless = windowMode.headless;
             const wantsVirtualDisplay = windowMode.virtualDisplay;
-            const alreadyRunning = (await getChatGptBrowserStatus({ port })).reachable;
             if (alreadyRunning) {
                 if (requestedProfileDir &&
                     savedProfileDir &&
@@ -278,7 +288,7 @@ export async function runProCommand(rest, io, runCliFn) {
                 // 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 runningHeadless = savedLaunchForPort ? savedLaunchForPort.headless === true : undefined;
+                const runningHeadless = background ? headless : savedLaunchForPort ? savedLaunchForPort.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 the existing browser yourself, then rerun; prodex will not end it.`);
                 }
@@ -379,6 +389,8 @@ export async function runProCommand(rest, io, runCliFn) {
             });
             if (minimizeNote)
                 io.stdout(minimizeNote);
+            if (background && !headless)
+                io.stdout("background: keep this window open until login is ready; prodex will close the idle dedicated browser and verify the same profile headless.");
             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.
@@ -392,18 +404,22 @@ export async function runProCommand(rest, io, runCliFn) {
                     headedLoginCommand: formatHeadedBrowserLoginCommand(sourceCli, commandOptions)
                 });
                 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.
+                    // A challenge is not evidence of a lost login. Report the observed
+                    // blocker without promising that another login fixes it.
                     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. Run \`${formatHeadedBrowserLoginCommand(sourceCli, commandOptions)}\` for a visible interactive check; headless browsers are not supported by Cloudflare.`
-                        : `headless: the profile is not signed in. Run \`${formatHeadedBrowserLoginCommand(sourceCli, commandOptions)}\` for a visible interactive login, sign in, close that browser yourself, then rerun with --headless.`);
+                        ? `headless: Cloudflare challenged this headless browser and ChatGPT did not become ready. Run \`${formatHeadedBrowserLoginCommand(sourceCli, commandOptions)}\` for a visible interactive check. This does not prove that the saved login was lost.`
+                        : `headless: readiness was not confirmed (${finalStatus?.blocker?.code ?? "not_ready"}). This does not prove that the saved login was lost. Inspect the dedicated browser with \`${formatHeadedBrowserLoginCommand(sourceCli, commandOptions)}\`; complete an interactive step only if requested.`);
                     return 1;
                 }
+                if (background) {
+                    const { getDedicatedBrowserHeadlessMode } = await import("./browser-handoff.js");
+                    if (!getDedicatedBrowserHeadlessMode({ port: opened.port, profileDir: opened.profileDir }))
+                        throw new Error("The browser is not actually headless; background readiness was not confirmed.");
+                    io.stdout("background: READY - the saved login works headless. Later consults reuse this mode.");
+                }
                 io.stdout("headless: signed-in session confirmed - consults will run with no visible window.");
                 return 0;
             }
@@ -411,7 +427,7 @@ export async function runProCommand(rest, io, runCliFn) {
             // state instead of returning while login is still unfinished. Scripts
             // and agents (non-TTY) keep the immediate return unless --wait is
             // passed; --no-wait always skips.
-            const shouldWaitForReady = !browserArgs.includes("--no-wait") && (browserArgs.includes("--wait") || io.isInteractive === true);
+            const shouldWaitForReady = background || (!browserArgs.includes("--no-wait") && (browserArgs.includes("--wait") || io.isInteractive === true));
             if (!shouldWaitForReady)
                 return 0;
             const waitTimeoutMs = readPositiveIntegerFlag(browserArgs, "--wait-timeout-ms") ?? 300_000;
@@ -421,6 +437,14 @@ export async function runProCommand(rest, io, runCliFn) {
                 windowMode,
                 headedLoginCommand: formatHeadedBrowserLoginCommand(sourceCli, commandOptions)
             });
+            if (ready && background) {
+                return completeBackgroundBrowserLogin(io, {
+                    port: opened.port,
+                    profileDir: opened.profileDir,
+                    timeoutMs: readPositiveIntegerFlag(browserArgs, "--wait-timeout-ms") ?? 30_000,
+                    headedLoginCommand: formatHeadedBrowserLoginCommand(sourceCli, commandOptions)
+                });
+            }
             return ready ? 0 : 1;
         }
         if (browserSubcommand === "ask") {
@@ -1466,10 +1490,11 @@ export async function runAskProCommand(rest, io, beforeSend) {
             catch (error) {
                 const firstBlocker = browserSendBlockerFromError(error);
                 // Loss while reading an already-submitted prompt must not send it again.
-                if (firstBlocker.code !== "browser_unreachable" ||
+                if (!["browser_unreachable", "chatgpt_page_missing"].includes(firstBlocker.code) ||
                     !firstBlocker.retryable || firstBlocker.thread || !autoLoginAllowed)
                     throw error;
-                const recovered = await attemptBrowserAutoRecovery(io.stderr, {
+                const recover = firstBlocker.code === "chatgpt_page_missing" ? attemptMissingChatGptTabRecovery : attemptBrowserAutoRecovery;
+                const recovered = await recover(io.stderr, {
                     ...(browserPort !== undefined ? { port: browserPort } : {}),
                     notes: recoveryNotes
                 });
@@ -2005,6 +2030,41 @@ export function browserRecoveredNote(ended) {
         ? `browser_recovered: the dedicated browser stopped answering its control port and prodex ended it (pid ${ended.join(", ")}) and started a fresh one before sending. Anything it was doing at the time is gone; the profile and login were kept.`
         : "browser_recovered: the dedicated browser was not running, so prodex started it with the saved profile before sending. The login was kept; anything the old browser had open is gone.";
 }
+async function attemptMissingChatGptTabRecovery(stderr, options) {
+    const port = resolveCdpPort(options.port);
+    return withBrowserSendLock(30_000, (detail) => stderr(`recover: ${detail}`), async () => {
+        const saved = await readLastBrowserLoginLaunch();
+        if (saved?.port !== undefined && saved.port !== port) {
+            throw new Error("Saved browser identity belongs to a different port; no tab was opened.");
+        }
+        let status = await getChatGptBrowserStatus({ port, timeoutMs: 2_000 });
+        if (status.loggedInLikely && status.hasComposer && !status.blocker)
+            return true;
+        if (!status.reachable || status.blocker?.code !== "chatgpt_page_missing") {
+            if (status.blocker)
+                throw new ChatGptBrowserBlockerError(status.blocker);
+            return false;
+        }
+        stderr("recover: the browser is running but its ChatGPT tab was closed; opening one tab and checking the saved login...");
+        if (!await openChatGptTab(port))
+            return false;
+        const deadline = Date.now() + 30_000;
+        while (Date.now() < deadline) {
+            status = await getChatGptBrowserStatus({ port, timeoutMs: 2_000 });
+            if (status.loggedInLikely && status.hasComposer && !status.blocker) {
+                options.notes?.push("browser_tab_reopened: reopened the closed ChatGPT tab in the running browser and verified the saved login before sending. No previous prompt was resent.");
+                return true;
+            }
+            if (status.blocker && !["login_required", "chatgpt_page_missing", "composer_not_ready", "browser_slow"].includes(status.blocker.code)) {
+                throw new ChatGptBrowserBlockerError(status.blocker);
+            }
+            await sleep(Math.min(500, Math.max(1, deadline - Date.now())));
+        }
+        if (status.blocker)
+            throw new ChatGptBrowserBlockerError(status.blocker);
+        return false;
+    });
+}
 export async function attemptBrowserAutoRecovery(stderr, options) {
     // Launching is right when the browser is gone and wrong when it is only deaf:
     // a second Chrome on the same profile joins the wedged one rather than
@@ -2131,6 +2191,35 @@ export async function attemptBrowserAutoRecovery(stderr, options) {
         return false;
     }
 }
+async function completeBackgroundBrowserLogin(io, options) {
+    return withBrowserSendLock(5_000, (detail) => io.stderr(`background: ${detail}`), async () => {
+        const { closeIdleChatGptBrowserForHandoff, getDedicatedBrowserHeadlessMode } = await import("./browser-handoff.js");
+        io.stderr("background: checking the dedicated browser before graceful handoff...");
+        const { url } = await closeIdleChatGptBrowserForHandoff({ port: options.port, profileDir: options.profileDir });
+        const opened = openChatGptBrowser({ port: options.port, profileDir: options.profileDir, headless: true, url });
+        await assertBrowserLaunchStayedAlive(opened);
+        // This records the actual process, not a claim that authentication succeeded.
+        const actualHeadless = getDedicatedBrowserHeadlessMode({ port: opened.port, profileDir: opened.profileDir });
+        await recordBrowserLoginLaunch({ port: opened.port, profile_dir: opened.profileDir, headless: actualHeadless, minimized: false });
+        if (!actualHeadless)
+            throw new Error("The replacement browser is not actually headless; background readiness was not confirmed.");
+        const ready = await waitForChatGptLoginReady(io.stderr, {
+            port: opened.port,
+            timeoutMs: options.timeoutMs,
+            windowMode: { headless: true, virtualDisplay: false, minimized: false },
+            headedLoginCommand: options.headedLoginCommand
+        });
+        if (!ready) {
+            const status = await getChatGptBrowserStatus({ port: opened.port, timeoutMs: 5_000 }).catch(() => undefined);
+            io.stderr(`background: NOT READY (${status?.blocker?.code ?? "not_ready"}). The same profile was kept; this is not proof that your saved login was lost. No prompt was sent.`);
+            return 1;
+        }
+        if (!getDedicatedBrowserHeadlessMode({ port: opened.port, profileDir: opened.profileDir }))
+            throw new Error("The replacement browser is not actually headless; background readiness was not confirmed.");
+        io.stdout("background: READY - the saved login works headless, with no visible window. You may close this terminal; later consults reuse this mode.");
+        return 0;
+    });
+}
 /**
  * Guided login: poll the visible browser until a logged-in ChatGPT tab with a
  * usable composer appears, narrating each state change so the user knows what
@@ -2864,7 +2953,8 @@ export function printBrowserLoginGuide(stdout, input) {
     stdout(`Profile: ${input.profileDir}`);
     stdout(`Debug: http://127.0.0.1:${input.port}`);
     if (windowAvailable) {
-        stdout("You can close this Chrome window after check/smoke or when you are done. The dedicated profile is reused next time.");
+        stdout("Closing this Chrome window does not switch it to headless mode. Keep it open for headed consults; closing the terminal is different from closing the browser.");
+        stdout(`For a one-time login followed by a verified no-window handoff, run \`${loginCommand} --background\`. The same profile is reused; a closed tab alone does not mean you logged out.`);
     }
     else {
         stdout("The dedicated profile path above will be reused by the real login command.");

package/docs/cli-reference.md

@@ -118,7 +118,13 @@ What happens:
 ~/.local/share/prodex/chrome-chatgpt-pro
 ```
 
-You can close that Chrome window after check/smoke or when you are done. The next time you need it, run `pro browser login` or `pro browser check` again. `check` will tell you what to do if the browser is closed.
+Closing that Chrome window does not switch to headless mode or prove that the saved login was erased. Keep it open for headed consults. Closing the terminal after READY is safe because Chrome is detached; closing the CLI or agent during a consult may interrupt answer collection.
+
+For a one-time interactive login followed by a no-window handoff, run `prodex pro browser login --background`. It waits even without a terminal, verifies readiness, then under the shared send lock gracefully closes the idle dedicated browser and launches the same profile and conversation headless. Wait for `background: READY`. The resulting mode is recorded for future CLI/MCP relaunches. This option cannot be combined with other window modes or `--no-wait`; `--dry-run` previews without opening or closing anything. Other page targets (including Chrome account prompts), dialogs, drafts, attachments, active responses, and uncertain browser identity/shutdown stop the handoff. Headless authentication and protection checks are never bypassed.
+
+If only the ChatGPT tab was closed, MCP and auto-login-enabled CLI requests can reopen one tab in the existing browser before an unsent request. They verify the saved login before sending and never use this path to resend an accepted or uncertain request.
+
+Before requesting `--background`, finish native browser and OS confirmations yourself. Page targets and rendered dialogs are checked, but Chrome does not expose every native prompt through CDP. Incognito/guest mode and an explicit `--profile-directory` are refused because their login identity cannot be safely handed off by this launcher.
 
 Actual explicit visible-browser consult (`prodex ask` is the short form of `prodex pro browser ask`):
 
@@ -200,18 +206,18 @@ A browser already running on your desktop cannot be moved onto a virtual display
 
 ### 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.
+`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 worked in the previous test where headless Chrome encountered a challenge. This is not a guarantee that future verification checks will pass.
 
 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)
+### Headless mode (requires live readiness verification)
 
 `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. If login, captcha, Cloudflare, permission, or account verification is needed, close the hidden browser yourself and run `prodex pro browser login --headed` for a visible interactive window. Do not merely omit `--headless`: saved modes persist.
-- **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).
+- **One mode at a time.** A single Chrome profile cannot serve a headed and a headless instance simultaneously. Use the guarded `--background` handoff for headed-to-headless operation, or close the browser yourself before an explicit mode switch.
 
-**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: if `prodex pro browser check` reports the challenge, run `prodex pro browser login --headed` and complete it visibly. prodex does not invoke a hidden API or bypass login/protection. Only the window is optional; the login is not.
+**A saved login does not guarantee headless readiness.** A previous test on a signed-in profile remained on the "Just a moment..." interstitial past 60 seconds. That observation does not establish why the challenge appeared or prove that the saved login was lost. Require an actual READY result; if a protection check blocks the browser, stop and inspect it visibly. prodex does not invoke a hidden API or bypass login/protection. 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/docs/releasing.md

@@ -2,6 +2,20 @@
 
 How a version of `@youdie006/prodex` gets from `main` to npm, and the checks that guard it. Moved here from the README so the README can stay about using the tool.
 
+## 0.40.13 Verification Record
+
+Release target: `v0.40.13` on `main`. The GitHub Release records the resolved commit, publication workflow and final installation checks; an installed candidate is not proof of public publication or a restarted MCP process.
+
+- PASS: `npm run release:verify` after updating the obsolete window-closing assertions. This ran the full tests, typecheck, build, installed-package CLI/HTTP-MCP/stdio-MCP smoke and doctor.
+- PASS: `npx vitest run tests/browser-handoff.test.ts tests/background-login.test.ts --maxWorkers=2`, 30 tests. Targeted regressions first failed for stale mode, incognito/guest, explicit Chrome sub-profile and incorrect launch-mode recording, then passed with the fixes.
+- PASS: Node 20 imports the built handoff module; background dry-run works without opening a browser. This is not a Node 20 live Pro test.
+- PASS: M3 candidate CLI without tmux refused the existing Chrome account confirmation, returned exit 1, did not report READY, and preserved the same browser PIDs and page targets. Runtime modules matched the tested local build by SHA-256.
+- BLOCKED: M3's native account confirmation requires manual action before the actual close/relaunch can be tested. Not every OS dialog is exposed through CDP; native confirmations must be finished before requesting a handoff.
+- BLOCKED: local WSL headless startup with the saved profile reached `cloudflare_check`, not READY. No Pro request was sent and no protective check was bypassed.
+- Earlier full checks failed on two outdated CLI guidance assertions and then one installed-document assertion. Those expectations were corrected; the subsequent complete verification passed. WSL packaging used normalized staging because mount file modes are not publishable directly; the user's unrelated untracked file was left untouched.
+
+The release adds a guarded, opt-in transition and more accurate blocker reporting. It does not claim that headless Pro consultation is verified on either deployment target or that authentication can be retained indefinitely.
+
 ## Publishing
 
 Publishing to npm runs entirely in CI with **no long-lived token** — auth is npm [trusted publishing](https://docs.npmjs.com/trusted-publishers) (OIDC), so nothing needs to store or paste an `NPM_TOKEN`, and every release carries a verifiable `--provenance` attestation.

package/package.json

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