@youdie006/prodex 0.40.12 → 0.40.14

package/README.md

@@ -69,10 +69,20 @@ 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.
+
+A Chrome account-connection chooser is separate from ChatGPT sign-in. If prodex confirms that chooser is displayed, choose for yourself whether to connect Chrome to the account; "Use Chrome without an account" declines that separate connection. A hidden or unreadable internal target still blocks the handoff but is not proof that a prompt is visible or that ChatGPT is logged out.
+
+"Login readiness is not yet confirmed" does not mean the saved login was lost. Inspect the dedicated browser before signing in again. An explicit `login_required`, `cloudflare_check`, `captcha_required`, or `permission_required` during a headless/virtual-display wait stops promptly: use `prodex pro browser login --headed` to handle the reported step visibly. A usage limit or missing composer has its own next step instead of a blanket login instruction.
+
 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.
 
+If submission itself is unconfirmed, do not resend or simply increase the timeout: first inspect the original conversation for the `[prodex-request:...]` marker in the error. Missing login signals or text still in the composer do not prove that the question was never submitted.
+
 Useful flags on every send:
 
 | Flag | What it does |
@@ -179,9 +189,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 +259,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,213 @@
+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: "Inspect the dedicated browser and keep only the intended idle ChatGPT tab open, then retry `prodex pro browser login --background`. Complete a login or permission step only if it is actually shown. 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) {
+        const chooser = pages.find((page) => page.url === "chrome://signin-dice-web-intercept.top-chrome/chrome-signin");
+        if (chooser) {
+            let state;
+            try {
+                const socket = localSocket(chooser.webSocketDebuggerUrl, port, "page");
+                const reply = await request(socket, "Runtime.evaluate", {
+                    expression: `(() => { const r = document.body?.getBoundingClientRect(); return { visibilityState: document.visibilityState, width: r?.width, height: r?.height, isChooser: !!document.querySelector('chrome-signin-app') }; })()`,
+                    returnByValue: true
+                });
+                if (!reply.exceptionDetails)
+                    state = reply.result?.value;
+            }
+            catch { /* An unreadable internal target is not proof of a visible prompt. */ }
+            if (state?.visibilityState === "visible" && state.isChooser === true &&
+                typeof state.width === "number" && state.width > 0 && typeof state.height === "number" && state.height > 0) {
+                throw new ChatGptBrowserBlockerError({
+                    code: "browser_account_confirmation", retryable: false,
+                    message: "Chrome is showing its browser-account connection chooser. This is separate from ChatGPT login; no browser was closed.",
+                    next_step: "Choose in the dedicated Chrome window yourself. 'Use Chrome without an account' declines Chrome account connection if you do not want it. Keep the ChatGPT tab open, then retry `prodex pro browser login --background`."
+                });
+            }
+            blocked("Chrome has an internal account target, but its chooser visibility was not confirmed. This does not establish a ChatGPT login problem; nothing was closed.");
+        }
+        blocked("The dedicated browser has additional page targets; 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/chatgpt-browser.js

@@ -702,6 +702,7 @@ export function formatDurationMs(ms) {
 export function acceptanceTimeoutError(ctx) {
     const uiLikelyChanged = ctx.composerStillHasText || !ctx.submitButtonFound;
     const took = `${formatDurationMs(ctx.timeoutMs)} (${ctx.timeoutMs}ms)`;
+    const inspect = `Do not resend automatically: submission was attempted but acceptance is unconfirmed. Inspect the original conversation${ctx.requestId ? ` for [prodex-request:${ctx.requestId}]` : ""} before another request.`;
     if (uiLikelyChanged) {
         const detail = [
             ctx.composerStillHasText ? "the composer still holds the prompt" : undefined,
@@ -709,13 +710,16 @@ export function acceptanceTimeoutError(ctx) {
         ]
             .filter(Boolean)
             .join(" and ");
-        return new Error(`Timed out after ${took} and ChatGPT never registered the prompt (${detail}). ` +
-            "The ChatGPT web UI may have changed, so prodex could not submit. Update prodex " +
-            "(npm i -g @youdie006/prodex@latest); if it persists, report it at " +
-            "https://github.com/youdie006/prodex/issues. You can also paste the prompt manually in the visible browser.");
+        return new ChatGptBrowserBlockerError({
+            code: "send_ui_changed", retryable: false,
+            message: `Timed out after ${took} without confirming prompt acceptance (${detail}). The ChatGPT web UI may have changed.`,
+            next_step: `${inspect} Update prodex (npm i -g @youdie006/prodex@latest); if it persists, report it at https://github.com/youdie006/prodex/issues.`
+        });
     }
-    return new Error(`Timed out after ${took} waiting for ChatGPT to accept the prompt. ` +
-        "Pro reasoning can run many minutes. Raise --timeout-ms and retry.");
+    return new ChatGptBrowserBlockerError({
+        code: "prompt_acceptance_unconfirmed", retryable: false,
+        message: `Timed out after ${took} waiting for ChatGPT to accept the prompt.`, next_step: inspect
+    });
 }
 export function hasPartialChatGptAnswer(previousAssistantMessageCount, state) {
     return state.assistantMessageCount > previousAssistantMessageCount && isUsableChatGptAnswer(state.answer);
@@ -948,7 +952,7 @@ export function detectChatGptBlocker(text, visibleButtonLabels = []) {
             code: "cloudflare_check",
             message: "ChatGPT is showing a Cloudflare or human-verification interstitial.",
             retryable: true,
-            next_step: "Complete the visible browser check manually, then retry."
+            next_step: "Complete the visible browser check manually."
         };
     }
     if (hasLikelyChatGptLoginPrompt(haystack)) {
@@ -956,7 +960,7 @@ export function detectChatGptBlocker(text, visibleButtonLabels = []) {
             code: "login_required",
             message: "ChatGPT is asking you to log in.",
             retryable: true,
-            next_step: "Log in manually in the visible browser, then retry."
+            next_step: "Log in manually in the visible browser."
         };
     }
     // Match real captcha / human-verification phrasing only. Bare words like "robot"/"로봇"/"자동화"
@@ -967,7 +971,7 @@ export function detectChatGptBlocker(text, visibleButtonLabels = []) {
             code: "captcha_required",
             message: "ChatGPT is asking for captcha or human verification.",
             retryable: true,
-            next_step: "Solve it manually in the visible browser, then retry."
+            next_step: "Solve it manually in the visible browser."
         };
     }
     if (/message limit|usage limit|model limit|rate limit|you.?ve reached|try again later|limit resets|사용 한도|메시지 한도|모델 한도|요금 제한|나중에 다시/i.test(haystack)) {
@@ -983,7 +987,7 @@ export function detectChatGptBlocker(text, visibleButtonLabels = []) {
             code: "permission_required",
             message: "ChatGPT requires account verification or permission handling.",
             retryable: true,
-            next_step: "Complete the visible account or permission prompt manually, then retry."
+            next_step: "Complete the visible account or permission prompt manually."
         };
     }
     return undefined;
@@ -992,7 +996,15 @@ export function detectChatGptPageBlocker(state) {
     // Blocker scan uses the nav-excluded sample so a sidebar chat title cannot
     // fake a blocker; fall back to the nav-included sample / full text when the
     // scan sample is absent (older callers).
-    return detectChatGptBlocker(state.blockerScanTextSample ?? state.blockerTextSample ?? state.textSample, state.visibleButtonLabels);
+    const rendered = detectChatGptBlocker(state.blockerScanTextSample ?? state.blockerTextSample ?? state.textSample, state.visibleButtonLabels);
+    if (rendered)
+        return rendered;
+    // The interstitial can have an empty body. Never use a conversation title
+    // alone when the composer exists or its state was not actually checked.
+    if (state.hasComposer === false && /^just a moment\.{0,3}$/i.test(state.title?.trim() ?? "")) {
+        return detectChatGptBlocker("Just a moment", []);
+    }
+    return undefined;
 }
 export function inferChatGptPageLoggedInLikely(state) {
     // The logged-in signals live in the sidebar - "New chat", "Projects", the
@@ -1026,6 +1038,17 @@ export function chatGptBlockerErrorFromAnswerState(state) {
 export function chatGptBlockerFromAnswerState(state) {
     return detectChatGptPageBlocker(state);
 }
+function submittedRequestBlocker(blocker, requestId, thread) {
+    return {
+        ...blocker,
+        retryable: false,
+        ...(thread ? { thread } : {}),
+        next_step: `${blocker.next_step ?? "Inspect the visible browser."} Do not automatically resend. ` +
+            (thread
+                ? `Collect the original answer with \`prodex pro browser recover --target-url ${thread} --request-id ${requestId}\` after resolving the blocker.`
+                : `Submission is unconfirmed; inspect the original conversation for [prodex-request:${requestId}] before another request.`)
+    };
+}
 export function computePromptAcceptanceDeadline(timeoutMs, startedAt) {
     return startedAt + Math.max(1, timeoutMs);
 }
@@ -3508,6 +3531,7 @@ export async function sendChatGptPrompt(options) {
     let beforeSubmit;
     let boundProjectId;
     let submitButtonFound = false;
+    let submissionAttempted = false;
     const sendWarnings = [...preflightWarnings];
     // Anything the page put in front of prodex was answered on the caller's
     // behalf. The note is read at return time - there are several return paths -
@@ -3654,6 +3678,8 @@ export async function sendChatGptPrompt(options) {
       const last = [...document.querySelectorAll('[data-message-author-role="user"]')].at(-1);
       return Boolean(last && (last.innerText || "").includes(${JSON.stringify(`[prodex-request:${requestId}]`)}));
     })()`;
+        // A dispatch can reach Chrome even if its acknowledgement is lost.
+        submissionAttempted = true;
         await cdp.send("Input.dispatchKeyEvent", enterKeyEvent("keyDown"));
         await cdp.send("Input.dispatchKeyEvent", enterKeyEvent("keyUp"));
         let promptPosted = await waitForExpressionTrue(cdp, promptPostedExpression, 1_500);
@@ -3677,6 +3703,13 @@ export async function sendChatGptPrompt(options) {
         await captureOnFailure(`send-${new Date().toISOString().replace(/[:.]/g, "-")}`);
         if (isCrashedTabError(error))
             throw attachSendWarnings(new ChatGptBrowserBlockerError(crashedTabBlocker(undefined, requestId)), sendWarnings);
+        if (submissionAttempted) {
+            const blocker = error instanceof ChatGptBrowserBlockerError ? error.blocker : {
+                code: "prompt_acceptance_unconfirmed", retryable: false,
+                message: `Browser control failed after submission was attempted: ${error instanceof Error ? error.message : String(error)}`
+            };
+            throw attachSendWarnings(new ChatGptBrowserBlockerError(submittedRequestBlocker(blocker, requestId)), sendWarnings);
+        }
         throw attachSendWarnings(error, sendWarnings);
     }
     finally {
@@ -3701,7 +3734,7 @@ export async function sendChatGptPrompt(options) {
         }
         const runtimeBlocker = chatGptBlockerFromAnswerState(finalState);
         if (runtimeBlocker)
-            throw new ChatGptBrowserBlockerError(runtimeBlocker);
+            throw new ChatGptBrowserBlockerError(submittedRequestBlocker(runtimeBlocker, requestId));
         dbgSend(`accept-poll url=${finalState.url} user=${finalState.userMessageCount} assistant=${finalState.assistantMessageCount} generating=${finalState.generating}`);
         if (requestMatches(finalState)) {
             if (normalizedTargetUrl)
@@ -3714,19 +3747,13 @@ export async function sendChatGptPrompt(options) {
         emitProgress("waiting", "prompt posting");
     }
     if (!accepted) {
-        // The session can expire mid-send (logged out during a long Pro wait), which
-        // otherwise surfaces as a cryptic "raise --timeout-ms" failure. Re-check the
-        // login state first and, if the session is gone, say so clearly so the user
-        // re-logs in instead of chasing a timeout.
+        // Missing logged-in signals do not prove session expiry. Only rendered
+        // blockers justify an authentication diagnosis after uncertain submission.
         try {
             const status = await evaluateOnPage(page, statusExpression());
-            if (!inferChatGptPageLoggedInLikely(status)) {
-                throw new ChatGptBrowserBlockerError({
-                    code: "session_expired",
-                    message: "The ChatGPT session is no longer logged in - it likely expired during the send.",
-                    retryable: true,
-                    next_step: "Run `prodex pro browser login`, log in, then retry."
-                });
+            const blocker = detectChatGptPageBlocker(status);
+            if (blocker) {
+                throw new ChatGptBrowserBlockerError(submittedRequestBlocker(blocker, requestId));
             }
         }
         catch (error) {
@@ -3734,8 +3761,7 @@ export async function sendChatGptPrompt(options) {
                 throw error;
             // best effort: a CDP eval failure here falls through to the generic timeout
         }
-        // A successful submit clears the composer, so text still sitting there means
-        // the send control did not register the prompt — the UI-changed signature.
+        // Composer text is only a UI hint, not proof that submission failed.
         let composerStillHasText = false;
         try {
             const composerState = await evaluateOnPage(page, composerTextStateExpression());
@@ -3744,7 +3770,7 @@ export async function sendChatGptPrompt(options) {
         catch {
             // best effort: fall back to submit-button signal only
         }
-        throw acceptanceTimeoutError({ timeoutMs, composerStillHasText, submitButtonFound });
+        throw acceptanceTimeoutError({ timeoutMs, composerStillHasText, submitButtonFound, requestId });
     }
     // Pin the conversation the prompt actually landed in. The browser is shared
     // (other agents, the user, tooling), and a tab that moves mid-wait made
@@ -3807,7 +3833,7 @@ export async function sendChatGptPrompt(options) {
         }
         const runtimeBlocker = chatGptBlockerFromAnswerState(finalState);
         if (runtimeBlocker)
-            throw new ChatGptBrowserBlockerError(runtimeBlocker);
+            throw new ChatGptBrowserBlockerError(submittedRequestBlocker(runtimeBlocker, requestId, pinnedThreadUrl));
         emitProgress("waiting", finalState.generating ? "generating" : "stabilizing");
         if (!hasFreshChatGptAnswer(beforeSubmit.assistantMessageCount, finalState))
             continue;

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
@@ -2145,15 +2234,16 @@ export async function waitForChatGptLoginReady(stderr, options, deps = {}) {
     const pollMs = options.pollMs ?? 2_000;
     const hasInteractiveWindow = options.windowMode?.headless !== true && options.windowMode?.virtualDisplay !== true;
     const headedLoginCommand = options.headedLoginCommand ?? "prodex pro browser login --headed";
-    const headedLoginHint = ` No interactive window is available; run \`${headedLoginCommand}\` to complete login, captcha, or human verification visibly.`;
     const startedAt = now();
     stderr(hasInteractiveWindow
-        ? "login: waiting for a logged-in ChatGPT tab (finish login in the dedicated Chrome browser; Ctrl+C stops waiting)..."
-        : `login: waiting for a logged-in ChatGPT tab (no interactive window; use \`${headedLoginCommand}\` if login or verification is required; Ctrl+C stops waiting)...`);
+        ? "login: waiting for ChatGPT readiness in the dedicated Chrome browser (complete any visible step it requests; Ctrl+C stops waiting)..."
+        : `login: waiting for ChatGPT readiness (no interactive window; use \`${headedLoginCommand}\` to inspect any requested browser step visibly; Ctrl+C stops waiting)...`);
     let lastState = "";
+    let lastStatus;
     let openMissingTabAttempts = 0;
     while (now() - startedAt < timeoutMs) {
         const status = await statusFn({ port: options.port, timeoutMs: 1_500 });
+        lastStatus = status;
         // A running Chrome with no chatgpt.com tab leaves the user nothing to log
         // into, so prodex opens one. Keep trying while the tab is still missing:
         // one silent attempt that fails looks exactly like no attempt, which is how
@@ -2174,18 +2264,27 @@ export async function waitForChatGptLoginReady(stderr, options, deps = {}) {
             await sleepFn(pollMs);
             continue;
         }
+        const blocker = status.blocker;
+        const blockerNextStep = blocker?.next_step ? ` Next: ${blocker.next_step}` : "";
+        const needsVisibleAuth = blocker !== undefined &&
+            ["login_required", "cloudflare_check", "captcha_required", "permission_required"].includes(blocker.code);
+        if (!hasInteractiveWindow && needsVisibleAuth) {
+            stderr(`login: blocked - ${blocker.message}${blockerNextStep}`);
+            stderr(`login: NOT READY - ${blocker.code} requires visible manual handling. No interactive window is available; run \`${headedLoginCommand}\` to handle it visibly.`);
+            return false;
+        }
         const state = !status.reachable
             ? "login: browser starting..."
             : status.blocker
-                ? `login: blocked - ${status.blocker.message}${hasInteractiveWindow ? "" : headedLoginHint}`
+                ? `login: blocked - ${status.blocker.message}${blockerNextStep}`
                 : !status.loggedInLikely
                     ? hasInteractiveWindow
-                        ? "login: waiting for ChatGPT login in the dedicated Chrome browser..."
-                        : `login: waiting for a saved ChatGPT login.${headedLoginHint}`
+                        ? "login: ChatGPT is reachable, but login readiness is not yet confirmed; review any visible browser prompt..."
+                        : `login: ChatGPT is reachable, but login readiness is not yet confirmed; inspect it visibly with \`${headedLoginCommand}\` if needed.`
                     : !status.hasComposer
                         ? hasInteractiveWindow
-                            ? "login: logged in; open a chat so the prompt composer is visible..."
-                            : `login: logged in, but no prompt composer is ready.${headedLoginHint}`
+                            ? "login: login looks active; open a chat so the prompt composer is visible..."
+                            : `login: login looks active, but no prompt composer is ready; inspect it visibly with \`${headedLoginCommand}\`.`
                         : "";
         if (state === "") {
             stderr(`login: READY - logged-in ChatGPT tab with composer detected (${Math.round((now() - startedAt) / 1000)}s).`);
@@ -2200,9 +2299,26 @@ export async function waitForChatGptLoginReady(stderr, options, deps = {}) {
             break;
         await sleepFn(Math.min(pollMs, Math.max(1, remainingMs)));
     }
-    stderr(hasInteractiveWindow
-        ? `login: not ready after ${Math.round(timeoutMs / 1000)}s. Finish login in the browser, then verify with \`prodex pro browser check\`.`
-        : `login: not ready after ${Math.round(timeoutMs / 1000)}s. Run \`${headedLoginCommand}\` to complete login, captcha, or human verification visibly, then retry.`);
+    const timeoutPrefix = `login: not ready after ${Math.round(timeoutMs / 1000)}s`;
+    if (lastStatus?.blocker) {
+        const nextStep = lastStatus.blocker.next_step ? ` Next: ${lastStatus.blocker.next_step}` : "";
+        stderr(`${timeoutPrefix}; last blocker ${lastStatus.blocker.code}: ${lastStatus.blocker.message}${nextStep}`);
+    }
+    else if (!lastStatus?.reachable) {
+        stderr(hasInteractiveWindow
+            ? `${timeoutPrefix}; browser startup was not confirmed. Check the dedicated Chrome browser, then verify with \`prodex pro browser check\`.`
+            : `${timeoutPrefix}; browser startup was not confirmed. Inspect it visibly with \`${headedLoginCommand}\`, then retry.`);
+    }
+    else if (lastStatus.loggedInLikely && !lastStatus.hasComposer) {
+        stderr(hasInteractiveWindow
+            ? `${timeoutPrefix}; login looked active, but the prompt composer was not detected. Open a normal ChatGPT chat or Project thread, then verify with \`prodex pro browser check\`.`
+            : `${timeoutPrefix}; login looked active, but the prompt composer was not detected. Inspect it visibly with \`${headedLoginCommand}\`, then retry.`);
+    }
+    else {
+        stderr(hasInteractiveWindow
+            ? `${timeoutPrefix}; ChatGPT was reachable, but login readiness was not yet confirmed. Review the dedicated Chrome browser, then verify with \`prodex pro browser check\`.`
+            : `${timeoutPrefix}; ChatGPT was reachable, but login readiness was not yet confirmed. Inspect it visibly with \`${headedLoginCommand}\`; complete a manual step only if requested.`);
+    }
     return false;
 }
 export async function assertBrowserLaunchStayedAlive(opened, timeoutMs) {
@@ -2864,7 +2980,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.");
@@ -3060,7 +3177,7 @@ export function assertNoOrphanConsultResults(tasksById, results) {
 }
 export function browserReadinessNextStep(input) {
     if (!input.loggedInLikely) {
-        return "Log in manually in the visible ChatGPT browser, then retry.";
+        return "ChatGPT login readiness is not yet confirmed. Review the visible ChatGPT browser state, then retry.";
     }
     if (!input.hasComposer) {
         return "Open a normal ChatGPT chat or Project thread, select the Pro/Thinking model, and retry.";

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.14",
   "description": "Local receipt bus for coordinating Codex execution with ChatGPT Pro/Projects consultation.",
   "author": "youdie006",
   "license": "MIT",