@youdie006/prodex 0.40.13 → 0.40.15

package/README.md

@@ -73,10 +73,16 @@ For a one-time visible login followed by a verified headless handoff, use `prode
 
 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. For a running headless browser, use `prodex pro browser login --headed --recover-visible` to open that same profile and page visibly. This explicit recovery refuses other tabs, active work, filled inputs, and uncertain browser identity; it never clicks a security check or sends a prompt. 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 |
@@ -185,7 +191,7 @@ The last recorded window mode is reused by later `login` commands and by CLI/MCP
 
 `--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 protection or force-kill a browser for a mode change; `--background` permits only the guarded graceful handoff described above.
+If a running headless browser needs login, captcha, Cloudflare, or account verification, run `prodex pro browser login --headed --recover-visible`. This is an explicit, guarded switch for a known authentication/protection blocker, not an automatic fallback or a general browser reset. It preserves the profile and page, waits for a clean shutdown, and opens a visible browser for any required manual step. That window is temporary: after it closes, the next launch remains headless. Another challenge stops instead of opening a visible window automatically; an ordinary explicit `login --headed` selects headed mode permanently. A virtual-display browser must still be closed manually before `login --headed`; it is not covered by this headless-only recovery. Merely omitting `--headless` does not switch modes because the saved preference persists. prodex never bypasses protection or force-kills a browser for a mode change.
 
 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.
 

package/dist/browser-handoff.js

@@ -3,10 +3,11 @@ 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";
+const VISIBLE_AUTH_BLOCKERS = new Set(["login_required", "cloudflare_check", "captcha_required", "permission_required"]);
 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."
+        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) {
@@ -62,8 +63,32 @@ async function singlePage(port) {
     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.");
+    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 ||
@@ -143,6 +168,37 @@ async function verifyIdle(page) {
         blocked("The page has active work, unfinished input, attachments, or a dialog; no browser was closed.");
     }
 }
+async function verifyVisibleAuthRecovery(page) {
+    const expression = `(() => {
+    const status = ${statusExpression()};
+    const visible = (e) => e.getClientRects().length > 0 && getComputedStyle(e).visibility !== 'hidden' && getComputedStyle(e).display !== 'none';
+    const textControls = [...document.querySelectorAll('textarea,[contenteditable="true"],[role="textbox"],input:not([type=hidden]):not([type=checkbox]):not([type=radio]):not([type=file]):not([type=button]):not([type=submit]):not([type=reset]):not([type=image]):not([type=range]):not([type=color])')];
+    const filledTextControl = textControls.some((e) => {
+      if (!visible(e)) return false;
+      const text = e instanceof HTMLInputElement || e instanceof HTMLTextAreaElement ? e.value : e.innerText || e.textContent || '';
+      return text.trim().length > 0;
+    });
+    const attachmentState = ${attachmentPresenceExpression()};
+    return { status, filledTextControl,
+      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.filledTextControl, value.dialog, value.attachments, value.unpersisted].some((v) => typeof v !== "boolean")) {
+        blocked("Could not verify the blocked page's input and dialog state.");
+    }
+    const state = value.status;
+    const blocker = detectChatGptPageBlocker(state);
+    if (state.url !== page.url || !blocker || !VISIBLE_AUTH_BLOCKERS.has(blocker.code)) {
+        blocked("Visible recovery requires an explicit login, Cloudflare, captcha, or permission blocker; no browser was closed.");
+    }
+    if (state.generating || state.awaitingResponseChoice || state.openDialogText || value.filledTextControl || value.dialog || value.attachments || value.unpersisted) {
+        blocked("The page has active work, filled input, attachments, or a dialog; no browser was closed.");
+    }
+}
 function alive(pid) {
     try {
         process.kill(pid, 0);
@@ -152,6 +208,39 @@ function alive(pid) {
         return error.code !== "ESRCH";
     }
 }
+function matchingBrowserPids(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 that the dedicated browser stayed closed.");
+    return findLaunchedBrowserProcesses(listed.stdout, { port, profileDir });
+}
+async function waitForQuietShutdown(identity, port, profileDir) {
+    const deadline = Date.now() + 12_000;
+    let quietSince;
+    while (Date.now() < deadline) {
+        if (!identity.pids.some(alive)) {
+            const replacement = matchingBrowserPids(port, profileDir).filter((pid) => !identity.pids.includes(pid));
+            if (replacement.length > 0)
+                blocked("A new matching browser process appeared during shutdown; no replacement was launched by prodex.");
+            try {
+                await fetch(`http://127.0.0.1:${port}/json/version`, { signal: AbortSignal.timeout(2_000) });
+                blocked("The old browser exited, but its control port is still active; no replacement was launched.");
+            }
+            catch (error) {
+                if (error instanceof ChatGptBrowserBlockerError)
+                    throw error;
+                const cause = error.cause;
+                if (cause?.code !== "ECONNREFUSED")
+                    blocked("The old browser exited, but its control port could not be verified closed.");
+            }
+            quietSince ??= Date.now();
+            if (Date.now() - quietSince >= 2_000)
+                return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    blocked("The dedicated browser did not remain fully closed. It was not force-killed and no replacement was launched.");
+}
 /** Caller holds the shared browser send lock through this close AND relaunch. */
 export async function closeIdleChatGptBrowserForHandoff(options) {
     const { port, profileDir } = options;
@@ -170,20 +259,29 @@ export async function closeIdleChatGptBrowserForHandoff(options) {
     }
     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));
+    await waitForQuietShutdown(identity, port, profileDir);
+    return { url: page.url };
+}
+/** Caller holds the shared browser send lock through this close AND headed relaunch. */
+export async function closeBlockedHeadlessBrowserForVisibleAuth(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);
+    if (!identity.headless)
+        blocked("Visible recovery requires an actually headless dedicated browser; no browser was closed.");
+    const page = await singlePage(port);
+    const version = await readJson(port, "version");
+    const socket = localSocket(version?.webSocketDebuggerUrl, port, "browser");
+    await verifyVisibleAuthRecovery(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 page changed during visible recovery verification.");
     }
-    blocked("The dedicated browser did not finish closing. It was not force-killed and no replacement was launched.");
+    await verifyVisibleAuthRecovery(current);
+    await request(socket, "Browser.close");
+    await waitForQuietShutdown(identity, port, profileDir);
+    return { url: page.url };
 }

package/dist/chatgpt-browser.js

@@ -6,7 +6,7 @@ import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import WsWebSocket from "ws";
 import { captureBrowserDiagnostics, diagnosticsEnabled, diagnosticsNote } from "./browser-diagnostics.js";
-import { withCrossProcessFileLock } from "./safe-file.js";
+import { withCrossProcessFileLock, writeVerifiedUtf8File } from "./safe-file.js";
 import os from "node:os";
 import { answeredDialogWarning, chatSurfaceState, effortNeedsWorkSurface, javascriptDialogResponse, menuKeyboardStep, readPowerSliderSelection, sliderRestoreStep, surfaceFromProbe, sliderPressOutcome, sliderDidNotRespond } from "./picker-interaction.js";
 import { projectsWithIdsExpression, recentConversationTitlesExpression } from "./tui.js";
@@ -209,7 +209,7 @@ export async function recordBrowserLoginLaunch(record) {
     try {
         const file = lastBrowserLoginPath();
         await mkdir(path.dirname(file), { recursive: true });
-        await writeFile(file, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+        await writeVerifiedUtf8File(file, `${JSON.stringify(record, null, 2)}\n`, async () => { }, { mode: 0o600 });
     }
     catch {
         // Advisory record only.
@@ -223,6 +223,7 @@ export async function readLastBrowserLoginLaunch() {
             ...(typeof parsed.port === "number" && Number.isInteger(parsed.port) ? { port: parsed.port } : {}),
             ...(typeof parsed.headless === "boolean" ? { headless: parsed.headless } : {}),
             ...(typeof parsed.minimized === "boolean" ? { minimized: parsed.minimized } : {}),
+            ...(typeof parsed.resume_headless === "boolean" ? { resume_headless: parsed.resume_headless } : {}),
             ...(typeof parsed.virtual_display === "number" && Number.isInteger(parsed.virtual_display)
                 ? { virtual_display: parsed.virtual_display }
                 : {})
@@ -528,6 +529,9 @@ export function resolveBrowserWindowMode(args) {
         return selected;
     }
     const saved = args.lastLogin;
+    if (args.forRelaunch && saved?.resume_headless === true) {
+        return { headless: true, virtualDisplay: false, minimized: false };
+    }
     const selected = {
         headless: saved?.headless === true,
         virtualDisplay: saved?.virtual_display !== undefined,
@@ -702,6 +706,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 +714,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 +956,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 +964,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 +975,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 +991,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 +1000,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 +1042,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 +3535,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 +3682,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 +3707,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 +3738,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 +3751,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 +3765,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 +3774,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 +3837,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;
@@ -4448,14 +4478,18 @@ export function fetchTimedOut(error) {
  * and ending a busy browser takes the consult it is writing with it.
  */
 export function statusMeansBrowserDead(status) {
-    return !status.reachable && status.blocker?.code !== "browser_slow";
+    return !status.reachable && status.blocker?.code === "browser_unreachable";
 }
 async function findChatGptPage(port, timeoutMs, targetUrl) {
+    let receivedResponse = false;
     try {
         const response = await fetch(`http://127.0.0.1:${port}/json/list`, { signal: AbortSignal.timeout(timeoutMs) });
+        receivedResponse = true;
         if (!response.ok)
             throw new Error(`HTTP ${response.status}`);
         const pages = (await response.json());
+        if (!Array.isArray(pages))
+            throw new Error("Invalid Chrome DevTools page list");
         const visibilityByPage = await getChatGptPageVisibility(pages);
         const blocker = chatGptPageSelectionBlocker(pages, targetUrl, visibilityByPage);
         if (blocker)
@@ -4463,17 +4497,11 @@ async function findChatGptPage(port, timeoutMs, targetUrl) {
         return { ok: true, page: selectChatGptPage(pages, targetUrl, visibilityByPage) };
     }
     catch (error) {
-        // A port that answers too slowly is a browser that is BUSY, not one that is
-        // gone, and the two must not share a verdict: the silence check that
-        // decides whether to end a browser counted three slow answers on a loaded
-        // machine as three dead ones - the exact failure the comment above
-        // confirmBrowserSilence was written to prevent.
-        // A timeout on its own is not proof of life: with a small budget the
-        // timer fires before the connection reports anything, and a port nothing
-        // listens on would be called "busy". A raw TCP connect settles it, and
-        // only an ACCEPT counts - measured on WSL2, a closed loopback port does not
-        // refuse at all, it times out (1.5s), while a listening one accepts in 1ms.
-        if (fetchTimedOut(error) && (await portAccepts(port)) === "accepted") {
+        // An HTTP error or malformed reply proves the endpoint answered. Only a
+        // refused TCP connection permits stopped-browser recovery; an uncertain
+        // timeout must never authorize terminating an existing process.
+        const connection = receivedResponse ? "accepted" : await portAccepts(port);
+        if (fetchTimedOut(error) && connection === "accepted") {
             return {
                 ok: false,
                 blocker: {
@@ -4485,6 +4513,18 @@ async function findChatGptPage(port, timeoutMs, targetUrl) {
                 }
             };
         }
+        if (connection !== "refused") {
+            return {
+                ok: false,
+                blocker: {
+                    code: "browser_control_unavailable",
+                    message: `The Chrome DevTools endpoint on 127.0.0.1:${port} could not be inspected safely; this does not establish that Chrome stopped.`,
+                    retryable: false,
+                    next_step: "Leave the existing browser open and check its control connection. No automatic restart or prompt retry is allowed for this uncertain state.",
+                    ...(error instanceof Error ? { detail: error.message } : {})
+                }
+            };
+        }
         return {
             ok: false,
             blocker: {

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] [--background]  # 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] [--recover-visible]  # 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] [--background]
+  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] [--recover-visible]
   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] [--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]";
+        ? `${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] [--recover-visible]`
+        : "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] [--recover-visible]";
     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

@@ -206,12 +206,19 @@ 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", "--background"]
+                booleanFlags: ["--dry-run", "--wait", "--no-wait", "--headed", "--headless", "--minimized", "--virtual-display", "--background", "--recover-visible"]
             })) {
                 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", "--background"]);
+            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", "--recover-visible"]);
             const background = browserArgs.includes("--background");
+            const recoverVisible = browserArgs.includes("--recover-visible");
+            if (recoverVisible && !browserArgs.includes("--headed")) {
+                throw new Error("--recover-visible requires explicit --headed mode.");
+            }
+            if (recoverVisible && browserArgs.some((arg) => ["--headless", "--minimized", "--virtual-display", "--background"].includes(arg))) {
+                throw new Error("--recover-visible cannot combine with --headless, --minimized, --virtual-display, or --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.");
             }
@@ -235,7 +242,7 @@ export async function runProCommand(rest, io, runCliFn) {
                 ? resolveBrowserProfileDirForLaunch(savedLaunchForPort.profile_dir)
                 : undefined;
             const profileDir = requestedProfileDir ?? savedProfileDir;
-            let windowMode = resolveBrowserWindowMode({
+            const windowModeOptions = {
                 flags: background ? (savedLaunchForPort?.headless === true ? { headless: true } : { headed: true }) : {
                     ...(browserArgs.includes("--headed") ? { headed: true } : {}),
                     ...(browserArgs.includes("--headless") ? { headless: true } : {}),
@@ -245,7 +252,8 @@ export async function runProCommand(rest, io, runCliFn) {
                 // Window mode is a user preference across launches; only the saved
                 // profile and display identity are scoped to this resolved port.
                 ...(savedLaunch ? { lastLogin: savedLaunch } : {})
-            });
+            };
+            let windowMode = resolveBrowserWindowMode({ ...windowModeOptions, forRelaunch: true });
             const commandOptions = {
                 ...(targetCwd ? { cwd: targetCwd } : {}),
                 ...(requestedProfileDir ? { profileDir: requestedProfileDir } : {}),
@@ -262,10 +270,13 @@ export async function runProCommand(rest, io, runCliFn) {
                     profileDir: profileDir ?? defaultChatGptProfileDir(),
                     port,
                     sourceCli,
-                    commandOptions
+                    commandOptions,
+                    reusedProfile: savedProfileDir !== undefined
                 });
                 if (background)
                     io.stdout("background: verify login, then hand the same profile to headless Chrome under the shared send lock. No prompt is sent.");
+                if (recoverVisible)
+                    io.stdout(`recovery: preview only; no browser will be closed or opened. Run \`${formatVisibleAuthRecoveryCommand(sourceCli, { ...commandOptions, profileDir: profileDir ?? defaultChatGptProfileDir(), port })}\` to perform the guarded switch.`);
                 return 0;
             }
             // If the dedicated Chrome is already reachable on this port, do NOT spawn
@@ -273,6 +284,8 @@ export async function runProCommand(rest, io, runCliFn) {
             // "extra windows" problem, which then blocks sends as
             // ambiguous_chatgpt_tabs). Reuse the running instance instead.
             const alreadyRunning = (await getChatGptBrowserStatus({ port })).reachable;
+            if (alreadyRunning)
+                windowMode = resolveBrowserWindowMode(windowModeOptions);
             if (background && alreadyRunning) {
                 const { getDedicatedBrowserHeadlessMode } = await import("./browser-handoff.js");
                 windowMode = { headless: getDedicatedBrowserHeadlessMode({ port, profileDir: profileDir ?? defaultChatGptProfileDir() }), virtualDisplay: false, minimized: false };
@@ -285,6 +298,16 @@ export async function runProCommand(rest, io, runCliFn) {
                     requestedProfileDir !== savedProfileDir) {
                     throw new Error(`A ChatGPT browser is already running on port ${port} with profile ${savedProfileDir}; a different profile was requested. Close the existing browser yourself, then rerun with the intended profile.`);
                 }
+                if (recoverVisible) {
+                    return completeVisibleAuthRecovery(io, {
+                        port,
+                        profileDir: profileDir ?? defaultChatGptProfileDir(),
+                        sourceCli,
+                        commandOptions,
+                        shouldWait: !browserArgs.includes("--no-wait") && (browserArgs.includes("--wait") || io.isInteractive === true),
+                        timeoutMs: readPositiveIntegerFlag(browserArgs, "--wait-timeout-ms") ?? 300_000
+                    });
+                }
                 // 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.
@@ -303,6 +326,9 @@ export async function runProCommand(rest, io, runCliFn) {
                     throw new Error(`A minimized ChatGPT browser is already running on port ${port}, but a visible headed browser was requested. Close the existing browser yourself, then rerun with --headed; prodex will not end it or pretend the minimized window was restored.`);
                 }
             }
+            if (recoverVisible) {
+                throw new Error(`--recover-visible requires a running headless ChatGPT browser on port ${port}; no browser was launched.`);
+            }
             // Allocate/rejoin a display only for a new browser. An already-running
             // virtual browser owns its saved display identity and needs no new X
             // server just because login was invoked again.
@@ -365,6 +391,10 @@ export async function runProCommand(rest, io, runCliFn) {
                     port: opened.port,
                     headless,
                     minimized,
+                    ...(alreadyRunning && savedLaunchForPort?.resume_headless === true &&
+                        !Object.values(windowModeOptions.flags).some((value) => typeof value === "boolean") &&
+                        !["PRODEX_HEADLESS", "PRODEX_VIRTUAL_DISPLAY", "PRODEX_MINIMIZE_WINDOW"].some((key) => (process.env[key] ?? "").trim() !== "")
+                        ? { resume_headless: true } : {}),
                     ...(virtualDisplay
                         ? { virtual_display: virtualDisplay.displayNumber }
                         : wantsVirtualDisplay && savedLaunchForPort?.virtual_display !== undefined
@@ -385,7 +415,8 @@ export async function runProCommand(rest, io, runCliFn) {
                 profileDir: opened.profileDir,
                 port: opened.port,
                 sourceCli,
-                commandOptions
+                commandOptions,
+                reusedProfile: savedProfileDir !== undefined
             });
             if (minimizeNote)
                 io.stdout(minimizeNote);
@@ -397,21 +428,26 @@ export async function runProCommand(rest, io, runCliFn) {
                 // Verify it here (bounded, no human to wait for) instead of letting
                 // the first consult fail with a confusing not-logged-in blocker.
                 const headlessWaitMs = readPositiveIntegerFlag(browserArgs, "--wait-timeout-ms") ?? 30_000;
+                const visibleRecoveryCommand = formatVisibleAuthRecoveryCommand(sourceCli, { ...commandOptions, profileDir: opened.profileDir, port: opened.port });
                 const headlessReady = await waitForChatGptLoginReady(io.stderr, {
                     port: opened.port,
                     timeoutMs: headlessWaitMs,
                     windowMode,
-                    headedLoginCommand: formatHeadedBrowserLoginCommand(sourceCli, commandOptions)
+                    headedLoginCommand: formatHeadedBrowserLoginCommand(sourceCli, commandOptions),
+                    headlessRecoveryCommand: visibleRecoveryCommand
                 });
                 if (!headlessReady) {
                     // 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 ?? "");
+                    const challenged = finalStatus?.blocker?.code === "cloudflare_check";
+                    const visibleStep = needsVisibleAuthRecovery(finalStatus?.blocker?.code)
+                        ? `Run \`${visibleRecoveryCommand}\` for a visible interactive check.`
+                        : `Follow the reported readiness or limit step. ${manualVisibleInspectionStep(formatHeadedBrowserLoginCommand(sourceCli, { ...commandOptions, profileDir: opened.profileDir, port: opened.port }))}`;
                     io.stdout("");
                     io.stdout(challenged
-                        ? `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.`);
+                        ? `headless: Cloudflare challenged this headless browser and ChatGPT did not become ready. Run \`${visibleRecoveryCommand}\` 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. ${visibleStep}`);
                     return 1;
                 }
                 if (background) {
@@ -442,7 +478,8 @@ export async function runProCommand(rest, io, runCliFn) {
                     port: opened.port,
                     profileDir: opened.profileDir,
                     timeoutMs: readPositiveIntegerFlag(browserArgs, "--wait-timeout-ms") ?? 30_000,
-                    headedLoginCommand: formatHeadedBrowserLoginCommand(sourceCli, commandOptions)
+                    headedLoginCommand: formatHeadedBrowserLoginCommand(sourceCli, commandOptions),
+                    headlessRecoveryCommand: formatVisibleAuthRecoveryCommand(sourceCli, { ...commandOptions, profileDir: opened.profileDir, port: opened.port })
                 });
             }
             return ready ? 0 : 1;
@@ -2066,6 +2103,16 @@ async function attemptMissingChatGptTabRecovery(stderr, options) {
     });
 }
 export async function attemptBrowserAutoRecovery(stderr, options) {
+    try {
+        return await withBrowserSendLock(30_000, (detail) => stderr(`recover: ${detail}`), () => recoverBrowserUnderSendLock(stderr, options));
+    }
+    catch (error) {
+        stderr(`recover: failed - ${errorMessage(error)}`);
+        return false;
+    }
+}
+async function recoverBrowserUnderSendLock(stderr, options) {
+    const recoveryPort = resolveCdpPort(options.port);
     // 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
     // replacing it, and the wedged one keeps burning CPU while nobody looks. This
@@ -2075,18 +2122,33 @@ export async function attemptBrowserAutoRecovery(stderr, options) {
     // scanning the DEFAULT profile for a custom-profile user put a second,
     // healthy browser's renderers on the list this function kills.
     const lastLogin = await readLastBrowserLoginLaunch().catch(() => undefined);
-    const recoveryPort = resolveCdpPort(options.port);
     const savedIdentityBelongsToAnotherPort = lastLogin?.port !== undefined &&
-        lastLogin.port !== recoveryPort &&
-        (lastLogin.profile_dir !== undefined || lastLogin.virtual_display !== undefined);
+        lastLogin.port !== recoveryPort;
     if (savedIdentityBelongsToAnotherPort) {
         stderr(`recover: failed - saved browser identity belongs to port ${lastLogin.port}, not requested port ${recoveryPort}. Run \`prodex pro browser login --port ${recoveryPort} --headed\` with the intended profile before retrying; prodex will not launch an unknown account.`);
         return false;
     }
+    const current = await getChatGptBrowserStatus({ port: recoveryPort, timeoutMs: 2_000 });
+    if (current.reachable && current.loggedInLikely && current.hasComposer && !current.blocker) {
+        if (!lastLogin?.profile_dir) {
+            stderr("recover: stopped - a READY browser has no saved profile identity; no automatic retry is allowed.");
+            return false;
+        }
+        const { getDedicatedBrowserHeadlessMode } = await import("./browser-handoff.js");
+        // The process check also verifies canonical profile ownership.
+        getDedicatedBrowserHeadlessMode({ port: recoveryPort, profileDir: lastLogin.profile_dir });
+        stderr("recover: browser is READY - reusing it without relaunching...");
+        return true;
+    }
+    if (current.reachable || !statusMeansBrowserDead(current)) {
+        const state = current.blocker?.code ?? "not_ready";
+        stderr(`recover: stopped - browser is not confirmed stopped or ready (${state}); no browser was ended, launched, or changed.`);
+        return false;
+    }
     const lastLoginForPort = lastLogin?.port === undefined || lastLogin.port === recoveryPort ? lastLogin : undefined;
     let windowMode;
     try {
-        windowMode = resolveBrowserWindowMode({ ...(lastLogin ? { lastLogin } : {}) });
+        windowMode = resolveBrowserWindowMode({ ...(lastLogin ? { lastLogin } : {}), forRelaunch: true });
     }
     catch (error) {
         stderr(`recover: failed - ${errorMessage(error)}`);
@@ -2177,8 +2239,9 @@ export async function attemptBrowserAutoRecovery(stderr, options) {
             windowMode,
             headedLoginCommand: formatHeadedBrowserLoginCommand(undefined, {
                 profileDir: opened.profileDir,
-                ...(opened.port !== DEFAULT_CDP_PORT ? { port: opened.port } : {})
-            })
+                port: opened.port
+            }),
+            headlessRecoveryCommand: formatVisibleAuthRecoveryCommand(undefined, { profileDir: opened.profileDir, port: opened.port })
         });
         if (!ready)
             return false;
@@ -2191,6 +2254,46 @@ export async function attemptBrowserAutoRecovery(stderr, options) {
         return false;
     }
 }
+async function completeVisibleAuthRecovery(io, options) {
+    return withBrowserSendLock(5_000, (detail) => io.stderr(`recovery: ${detail}`), async () => {
+        const { closeBlockedHeadlessBrowserForVisibleAuth, getDedicatedBrowserHeadlessMode } = await import("./browser-handoff.js");
+        io.stderr("recovery: verifying the blocked headless browser before graceful visible handoff...");
+        let url;
+        try {
+            ({ url } = await closeBlockedHeadlessBrowserForVisibleAuth({ port: options.port, profileDir: options.profileDir }));
+        }
+        catch (error) {
+            if (error instanceof ChatGptBrowserBlockerError) {
+                throw new ChatGptBrowserBlockerError({
+                    ...error.blocker,
+                    next_step: `Resolve only the reported visible state, then retry \`${formatVisibleAuthRecoveryCommand(options.sourceCli, { ...options.commandOptions, profileDir: options.profileDir, port: options.port })}\`. No browser was force-killed or replaced.`
+                });
+            }
+            throw error;
+        }
+        const opened = openChatGptBrowser({ port: options.port, profileDir: options.profileDir, headless: false, url });
+        await assertBrowserLaunchStayedAlive(opened, options.commandOptions.launchTimeoutMs);
+        if (getDedicatedBrowserHeadlessMode({ port: opened.port, profileDir: opened.profileDir })) {
+            throw new Error("The replacement browser is still headless; visible recovery was not recorded.");
+        }
+        await recordBrowserLoginLaunch({ port: opened.port, profile_dir: opened.profileDir, headless: false, minimized: false, resume_headless: true });
+        printBrowserLoginGuide(io.stdout, {
+            opened: true, reusedProfile: true, loginUrl: url, profileDir: opened.profileDir, port: opened.port,
+            sourceCli: options.sourceCli, commandOptions: options.commandOptions
+        });
+        io.stdout("recovery: visible browser opened with the same profile and page. Complete a manual step only if ChatGPT requests it; no prompt was sent.");
+        io.stdout("recovery: this visible window is temporary. After it closes, the next launch remains headless; another challenge stops without opening a visible window automatically.");
+        if (!options.shouldWait)
+            return 0;
+        const ready = await waitForChatGptLoginReady(io.stderr, {
+            port: opened.port,
+            timeoutMs: options.timeoutMs,
+            windowMode: { headless: false, virtualDisplay: false, minimized: false },
+            headedLoginCommand: formatHeadedBrowserLoginCommand(options.sourceCli, { ...options.commandOptions, profileDir: opened.profileDir, port: opened.port })
+        });
+        return ready ? 0 : 1;
+    });
+}
 async function completeBackgroundBrowserLogin(io, options) {
     return withBrowserSendLock(5_000, (detail) => io.stderr(`background: ${detail}`), async () => {
         const { closeIdleChatGptBrowserForHandoff, getDedicatedBrowserHeadlessMode } = await import("./browser-handoff.js");
@@ -2207,7 +2310,8 @@ async function completeBackgroundBrowserLogin(io, options) {
             port: opened.port,
             timeoutMs: options.timeoutMs,
             windowMode: { headless: true, virtualDisplay: false, minimized: false },
-            headedLoginCommand: options.headedLoginCommand
+            headedLoginCommand: options.headedLoginCommand,
+            headlessRecoveryCommand: options.headlessRecoveryCommand
         });
         if (!ready) {
             const status = await getChatGptBrowserStatus({ port: opened.port, timeoutMs: 5_000 }).catch(() => undefined);
@@ -2220,6 +2324,12 @@ async function completeBackgroundBrowserLogin(io, options) {
         return 0;
     });
 }
+function needsVisibleAuthRecovery(code) {
+    return code !== undefined && ["login_required", "cloudflare_check", "captcha_required", "permission_required"].includes(code);
+}
+function manualVisibleInspectionStep(headedLoginCommand) {
+    return `For visible inspection, close the dedicated browser yourself only when no work is active, then run \`${headedLoginCommand}\`.`;
+}
 /**
  * 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
@@ -2234,15 +2344,17 @@ 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 manualInspection = manualVisibleInspectionStep(headedLoginCommand);
     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; the observed blocker determines the next step; 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
@@ -2258,23 +2370,33 @@ export async function waitForChatGptLoginReady(stderr, options, deps = {}) {
             if (opened === false) {
                 stderr(hasInteractiveWindow
                     ? "login: could not open a ChatGPT tab through the debug port; open https://chatgpt.com/ in that browser."
-                    : `login: could not open a ChatGPT tab through the debug port; run \`${headedLoginCommand}\` to open it visibly.`);
+                    : `login: could not open a ChatGPT tab through the debug port. ${manualInspection}`);
             }
             await sleepFn(pollMs);
             continue;
         }
+        const blocker = status.blocker;
+        const blockerNextStep = blocker?.next_step ? ` Next: ${blocker.next_step}` : "";
+        if (!hasInteractiveWindow && blocker && needsVisibleAuthRecovery(blocker.code)) {
+            const visibleStep = options.windowMode?.headless === true && options.headlessRecoveryCommand
+                ? `run \`${options.headlessRecoveryCommand}\` to handle it visibly.`
+                : `${manualInspection} Handle the reported step visibly.`;
+            stderr(`login: blocked - ${blocker.message}${blockerNextStep}`);
+            stderr(`login: NOT READY - ${blocker.code} requires visible manual handling. No interactive window is available; ${visibleStep}`);
+            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; waiting for page readiness evidence..."
                     : !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; waiting for a usable chat..."
                         : "";
         if (state === "") {
             stderr(`login: READY - logged-in ChatGPT tab with composer detected (${Math.round((now() - startedAt) / 1000)}s).`);
@@ -2289,9 +2411,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. ${manualInspection}`);
+    }
+    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. ${manualInspection}`);
+    }
+    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. ${manualInspection}`);
+    }
     return false;
 }
 export async function assertBrowserLaunchStayedAlive(opened, timeoutMs) {
@@ -2895,11 +3034,19 @@ export async function listConsultListEntries(store, options = { readOnly: true }
 function formatHeadedBrowserLoginCommand(sourceCli, options = {}) {
     return `${formatBrowserLoginCommand(sourceCli, options)} --headed`;
 }
+function formatVisibleAuthRecoveryCommand(sourceCli, options = {}) {
+    return `${formatBrowserLoginCommand(sourceCli, options)} --headed --recover-visible`;
+}
 export function printBrowserLoginGuide(stdout, input) {
     const noInteractiveWindow = input.headless === true || input.virtualDisplay === true;
     const windowAvailable = (input.opened || input.reused === true) && !noInteractiveWindow;
     const loginCommand = formatBrowserLoginCommand(input.sourceCli, input.commandOptions);
     const headedLoginCommand = formatHeadedBrowserLoginCommand(input.sourceCli, input.commandOptions);
+    const visibleRecoveryCommand = formatVisibleAuthRecoveryCommand(input.sourceCli, {
+        ...input.commandOptions,
+        profileDir: input.profileDir,
+        port: input.port
+    });
     const runtimeCommandOptions = {
         ...(input.commandOptions?.cwd ? { cwd: input.commandOptions.cwd } : {}),
         ...(input.commandOptions?.port ? { port: input.commandOptions.port } : {})
@@ -2922,14 +3069,18 @@ export function printBrowserLoginGuide(stdout, input) {
                     : "Dry run: no browser was opened.");
     if (noInteractiveWindow && (input.opened || input.reused)) {
         stdout("");
-        stdout(`If ChatGPT needs login, captcha, or human verification, run \`${headedLoginCommand}\` to handle it in a visible window.`);
+        stdout(input.headless
+            ? `If ChatGPT needs login, captcha, or human verification, run \`${visibleRecoveryCommand}\` to perform the explicit guarded switch to a visible window.`
+            : `If ChatGPT needs login, captcha, or human verification, close the virtual-display browser yourself, then run \`${headedLoginCommand}\` to handle it in a visible window.`);
         stdout(`Next: run \`${checkCommand}\` to confirm the session, then consult as usual.`);
         return;
     }
     stdout("");
     stdout("Steps:");
     if (windowAvailable) {
-        stdout(`1. Log in manually at ${input.loginUrl} in the dedicated Chrome window.`);
+        stdout(input.reusedProfile || input.reused === true
+            ? `1. The existing profile is open at ${input.loginUrl}; log in manually only if ChatGPT requests it.`
+            : `1. Log in manually at ${input.loginUrl} in the dedicated Chrome window.`);
         stdout("2. If ChatGPT asks for captcha, Cloudflare/human verification, permission, or account verification, complete it in the browser.");
         stdout("3. For usage limit, message limit, model limit, or rate limit, wait for the reset or choose an available model in the browser.");
         stdout("4. Open a normal ChatGPT chat or the intended Project/thread so the prompt composer is visible.");
@@ -2939,9 +3090,13 @@ export function printBrowserLoginGuide(stdout, input) {
     }
     else {
         stdout(noInteractiveWindow
-            ? `1. Run \`${headedLoginCommand}\` to open a visible dedicated Chrome window for login or verification.`
+            ? input.headless
+                ? `1. Run \`${visibleRecoveryCommand}\` to perform the guarded switch to a visible dedicated Chrome window.`
+                : `1. Close the virtual-display browser yourself, then run \`${headedLoginCommand}\` to open a visible dedicated Chrome window.`
             : `1. Run \`${loginCommand}\` without \`--dry-run\` to open the dedicated Chrome window.`);
-        stdout(`2. Log in manually at ${input.loginUrl} in that Chrome window.`);
+        stdout(input.reusedProfile
+            ? `2. Log in manually only if ChatGPT requests it at ${input.loginUrl}.`
+            : `2. Log in manually at ${input.loginUrl} in that Chrome window.`);
         stdout("3. If ChatGPT asks for captcha, Cloudflare/human verification, permission, or account verification, complete it in the browser.");
         stdout("4. For usage limit, message limit, model limit, or rate limit, wait for the reset or choose an available model in the browser.");
         stdout("5. Open a normal ChatGPT chat or the intended Project/thread so the prompt composer is visible.");
@@ -3047,7 +3202,9 @@ export async function printProductCheck(store, io, args, configCwd = io.cwd) {
             // report both as "not running": the browser really is gone, or it is still
             // there and has stopped answering. The second keeps burning CPU until
             // somebody notices, and nobody notices a message that says it is absent.
-            const wedged = findWedgedBrowser({ ...(browserCommandOptions.port !== undefined ? { port: browserCommandOptions.port } : {}) });
+            const wedged = statusMeansBrowserDead(browserStatus)
+                ? findWedgedBrowser({ ...(browserCommandOptions.port !== undefined ? { port: browserCommandOptions.port } : {}) })
+                : [];
             const blocker = wedged.length > 0 ? wedgedBrowserBlocker(wedged, browserCommandOptions.port ?? DEFAULT_CDP_PORT) : browserStatus.blocker;
             io.stdout(`chatgpt: ${blocker?.code ?? "unreachable"} - ${blocker?.message ?? "browser is not reachable"}`);
             const nextStep = productCheckBrowserNextStep(blocker?.next_step, sourceCli, browserCommandOptions);
@@ -3150,7 +3307,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

@@ -82,7 +82,8 @@ Use this only when you explicitly want to use your logged-in ChatGPT Pro web ses
 ```bash
 prodex pro browser login --dry-run
 prodex pro browser login
-prodex pro browser login --headed  # force a visible window for interactive reauthentication
+prodex pro browser login --headed  # visible mode when no incompatible browser is running
+prodex pro browser login --headed --recover-visible  # guarded recovery of a blocked headless browser
 prodex pro browser help
 prodex pro browser check
 prodex pro browser smoke --cwd /absolute/path/to/your/repo
@@ -107,7 +108,7 @@ What happens:
 - `login --dry-run` prints the dedicated Chrome profile, debug URL, and next commands without opening a browser.
 - `login` opens that dedicated Chrome profile at ChatGPT. In an interactive terminal it then waits (default 5 minutes; `--no-wait` skips, `--wait-timeout-ms` tunes) and narrates which manual step is still missing until it reports READY; scripts and agents get the immediate return unless they pass `--wait`.
 - `login` reuses the last profile recorded for the resolved debug port when `--profile-dir` is omitted. It does not reuse a saved custom port implicitly: `--port` / `PRODEX_CDP_PORT` / the normal `9333` default still resolve the port exactly as before.
-- You log in manually in the visible browser.
+- You log in manually only if the visible browser asks; an already signed-in profile is reused.
 - If ChatGPT asks for captcha, Cloudflare/human verification, permission, or account verification, handle it in that browser.
 - If ChatGPT shows a usage limit, message limit, model limit, or rate limit, wait for the reset or choose an available model in the browser.
 - Open a normal ChatGPT chat or the intended Project/thread so the prompt composer is visible.
@@ -122,6 +123,10 @@ Closing that Chrome window does not switch to headless mode or prove that the sa
 
 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.
 
+To inspect an authentication/protection blocker in a running headless browser, explicitly use `prodex pro browser login --headed --recover-visible`. The command requires one verified dedicated headless browser and one ChatGPT page reporting `login_required`, `cloudflare_check`, `captcha_required`, or `permission_required`. It preserves the exact profile and page under the shared send lock, refuses unfinished inputs, active work, dialogs, attachments, extra tabs, and ambiguous identity, and waits for a verified shutdown before launching headed. It does not click, solve, or suppress a security check. Use `--wait` to wait for manual handling or `--no-wait` to return after launch; `--dry-run` performs no browser change. This is headless-only, not a generic reset or a virtual-display switch.
+
+The visible recovery window does not change the headless relaunch preference. Once it closes, both a new `login` launch and an automatic browser restart use headless mode again. Reusing the still-open window with `login --wait` keeps that preference. An ordinary explicit window-mode option or environment override replaces it. There is no automatic headed fallback when the next headless launch encounters another challenge.
+
 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.
@@ -214,8 +219,8 @@ The catch is what "minimized" means to your desktop. Under WSLg a minimized Chro
 
 `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. Use the guarded `--background` handoff for headed-to-headless operation, or close the browser yourself before an explicit mode switch.
+- **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 the running headless browser reports login, captcha, Cloudflare, permission, or account verification, use `prodex pro browser login --headed --recover-visible` for a guarded switch to 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. Use the guarded `--background` handoff for headed-to-headless operation or the explicit `--headed --recover-visible` recovery for a blocked headless browser. Other mode changes require closing the browser yourself.
 
 **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.
 

package/package.json

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