@youdie006/prodex 0.40.14 → 0.40.16

package/README.md

@@ -75,7 +75,7 @@ Finish any native browser or OS confirmation before requesting the handoff: Chro
 
 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.
+"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`).
 
@@ -191,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 the dedicated browser fully exits, the next launch remains headless. On macOS, closing a window alone may leave Chrome running; prodex stops rather than reopening that temporary visible window. Another challenge also 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,6 +3,7 @@ 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,
@@ -167,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);
@@ -176,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;
@@ -194,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,
@@ -1001,7 +1005,7 @@ export function detectChatGptPageBlocker(state) {
         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() ?? "")) {
+    if (state.hasComposer === false && /^(?:just a moment|잠시만 기다리십시오)(?:\.{0,3}|…)$/i.test(state.title?.trim() ?? "")) {
         return detectChatGptBlocker("Just a moment", []);
     }
     return undefined;
@@ -4474,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)
@@ -4489,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: {
@@ -4511,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;
@@ -2045,6 +2082,14 @@ async function attemptMissingChatGptTabRecovery(stderr, options) {
                 throw new ChatGptBrowserBlockerError(status.blocker);
             return false;
         }
+        if (saved?.headless !== true && resolveBrowserWindowMode({ lastLogin: saved, forRelaunch: true }).headless) {
+            throw new ChatGptBrowserBlockerError({
+                code: "browser_mode_transition_required",
+                message: "The temporary visible browser is still running after its ChatGPT tab closed; reopening a tab would show another window.",
+                retryable: false,
+                next_step: "Fully quit only the dedicated browser, then retry to launch the saved profile headlessly. On macOS, closing a window alone does not quit Chrome. Do not log in again solely because this transition stopped."
+            });
+        }
         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;
@@ -2066,6 +2111,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 +2130,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 +2247,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 +2262,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 the dedicated browser fully exits, the next launch remains headless. On macOS, closing its window alone may leave Chrome running; prodex will not reopen that temporary 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 +2318,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 +2332,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,10 +2352,11 @@ 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 manualInspection = manualVisibleInspectionStep(headedLoginCommand);
     const startedAt = now();
     stderr(hasInteractiveWindow
         ? "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)...`);
+        : "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;
@@ -2259,18 +2378,19 @@ 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}` : "";
-        const needsVisibleAuth = blocker !== undefined &&
-            ["login_required", "cloudflare_check", "captcha_required", "permission_required"].includes(blocker.code);
-        if (!hasInteractiveWindow && needsVisibleAuth) {
+        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; run \`${headedLoginCommand}\` to handle it visibly.`);
+            stderr(`login: NOT READY - ${blocker.code} requires visible manual handling. No interactive window is available; ${visibleStep}`);
             return false;
         }
         const state = !status.reachable
@@ -2280,11 +2400,11 @@ export async function waitForChatGptLoginReady(stderr, options, deps = {}) {
                 : !status.loggedInLikely
                     ? hasInteractiveWindow
                         ? "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.`
+                        : "login: ChatGPT is reachable, but login readiness is not yet confirmed; waiting for page readiness evidence..."
                     : !status.hasComposer
                         ? hasInteractiveWindow
                             ? "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}\`.`
+                            : "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).`);
@@ -2307,17 +2427,17 @@ export async function waitForChatGptLoginReady(stderr, options, deps = {}) {
     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.`);
+            : `${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. Inspect it visibly with \`${headedLoginCommand}\`, then retry.`);
+            : `${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. Inspect it visibly with \`${headedLoginCommand}\`; complete a manual step only if requested.`);
+            : `${timeoutPrefix}; ChatGPT was reachable, but login readiness was not yet confirmed. ${manualInspection}`);
     }
     return false;
 }
@@ -2922,11 +3042,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 } : {})
@@ -2949,14 +3077,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.");
@@ -2966,9 +3098,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.");
@@ -3074,7 +3210,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);

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 the dedicated browser fully exits, both a new `login` launch and an automatic browser restart use headless mode again. On macOS, closing its last window may leave the process running: automatic missing-tab recovery stops with `browser_mode_transition_required` instead of opening another visible window. Fully quit only the dedicated browser before retrying; the closed tab alone is not a reason to log in again. Reusing a still-open window with `login --wait` keeps the 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.14",
+  "version": "0.40.16",
   "description": "Local receipt bus for coordinating Codex execution with ChatGPT Pro/Projects consultation.",
   "author": "youdie006",
   "license": "MIT",