doordash-cli 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -9,6 +9,12 @@ All notable changes to `doordash-cli` will be documented in this file.
 
 See [docs/releasing.md](docs/releasing.md) for the maintainer release flow.
 
+## [0.4.1](https://github.com/LatencyTDH/doordash-cli/compare/v0.4.0...v0.4.1) (2026-04-10)
+
+### Bug Fixes
+
+* bound auth-check and restore login completion flow ([#39](https://github.com/LatencyTDH/doordash-cli/issues/39)) ([5166944](https://github.com/LatencyTDH/doordash-cli/commit/51669444dc124e39ece719624c997ab9f46acd93))
+
 ## [0.4.0](https://github.com/LatencyTDH/doordash-cli/compare/v0.3.3...v0.4.0) (2026-04-10)
 
 ### Features

package/README.md

@@ -9,7 +9,7 @@ It stops before checkout.
 ## Highlights
 
 - **Cart-safe by design** — browse, inspect existing orders, and manage a cart; no checkout, payment, or order mutation.
-- **Browser-first login** — `dd-cli login` reuses saved local auth or a discoverable signed-in browser session when possible, and otherwise opens a temporary login window.
+- **Browser-first login** — `dd-cli login` reuses saved local auth or an attachable signed-in browser session when possible, and otherwise opens a temporary login window.
 - **Direct API first** — auth, discovery, existing-order, and cart commands use DoorDash consumer-web GraphQL/HTTP rather than DOM clicking.
 - **JSON-friendly** — every command prints structured output.
 - **Fail-closed** — unsupported commands, flags, or unsafe payload shapes are rejected.
@@ -70,13 +70,13 @@ If you are running from a checkout without `npm link`, replace `doordash-cli` wi
 
 ## Login and session reuse
 
-`login` reuses saved local auth when it is still valid. Otherwise it tries to import a discoverable signed-in browser session. If neither is available, it opens a temporary Chromium login window and saves the session there. If authentication still is not established, `login` exits non-zero.
+`login` reuses saved local auth when it is still valid. Otherwise it tries to import a discoverable attachable signed-in browser session. A merely-open Chrome/Brave window is not automatically reusable unless the CLI can actually attach to it. If no attachable session is available, it opens a temporary Chromium login window and saves the session there. If authentication still is not established, `login` exits non-zero.
 
-`auth-check` reports whether the saved state appears logged in and can quietly import a discoverable signed-in browser session unless `logout` disabled that auto-reuse.
+`auth-check` reports whether the saved state appears logged in and can quietly import a discoverable attachable signed-in browser session unless `logout` disabled that auto-reuse.
 
-`logout` clears persisted cookies and stored browser state, then keeps automatic browser-session reuse disabled until you explicitly run `dd-cli login` again.
+`logout` clears persisted cookies and stored browser state, then keeps passive browser-session reuse disabled until your next explicit `dd-cli login` attempt.
 
-If `login` opens a temporary Chromium window, finish signing in there and let the CLI save the session. If you expect reuse from another browser, make sure it exposes a compatible CDP endpoint, then rerun `dd-cli login`.
+If `login` opens a temporary Chromium window, the CLI now keeps checking automatically and also tells you that you can press Enter to force an immediate recheck once the page already shows you are signed in. That restores the old effective manual-completion path without giving up automatic completion when it works. If you expect reuse from another browser instead, make sure it exposes an attachable browser automation session the CLI can actually import; a merely-open browser window is not enough today, even if it is already your main browser.
 
 ## Command surface
 

package/dist/cli.js

@@ -42,10 +42,11 @@ export function usage() {
         "  - Installed command names are lowercase only: dd-cli and doordash-cli.",
         "  - install-browser downloads the bundled Playwright Chromium runtime used when the CLI needs a local browser.",
         "  - Manual pages ship with the project: man dd-cli or man doordash-cli.",
-        "  - login reuses saved local auth when possible, otherwise imports a signed-in browser session or opens a temporary Chromium login window.",
+        "  - login reuses saved local auth when possible, otherwise imports an attachable signed-in browser session or opens a temporary Chromium login window.",
+        "  - login auto-detects completion when it can; in the temporary-browser fallback you can also press Enter to force an immediate recheck once the page shows you are signed in.",
         "  - login exits non-zero if authentication is still not established.",
-        "  - auth-check reports saved-session status and can quietly reuse/import a signed-in browser session unless logout disabled that auto-reuse.",
-        "  - logout clears saved session files and keeps automatic browser-session reuse off until the next login.",
+        "  - auth-check reports saved-session status and can quietly reuse/import an attachable signed-in browser session unless logout disabled that auto-reuse.",
+        "  - logout clears saved session files and keeps passive browser-session reuse off until the next explicit login attempt.",
         "  - configurable items require explicit --options-json selections.",
         "  - unsupported option trees fail closed.",
         "",

package/dist/cli.test.js

@@ -113,10 +113,11 @@ test("help output shows the direct read-only/cart-safe command surface", () => {
     assert.match(result.stdout, /options-json/);
     assert.match(result.stdout, /--version, -v/);
     assert.match(result.stdout, /man dd-cli/);
-    assert.match(result.stdout, /login reuses saved local auth when possible, otherwise imports a signed-in browser session or opens a temporary Chromium login window\./);
+    assert.match(result.stdout, /login reuses saved local auth when possible, otherwise imports an attachable signed-in browser session or opens a temporary Chromium login window\./);
+    assert.match(result.stdout, /login auto-detects completion when it can; in the temporary-browser fallback you can also press Enter to force an immediate recheck once the page shows you are signed in\./);
     assert.match(result.stdout, /login exits non-zero if authentication is still not established\./);
-    assert.match(result.stdout, /auth-check reports saved-session status and can quietly reuse\/import a signed-in browser session unless logout disabled that auto-reuse\./);
-    assert.match(result.stdout, /logout clears saved session files and keeps automatic browser-session reuse off until the next login\./);
+    assert.match(result.stdout, /auth-check reports saved-session status and can quietly reuse\/import an attachable signed-in browser session unless logout disabled that auto-reuse\./);
+    assert.match(result.stdout, /logout clears saved session files and keeps passive browser-session reuse off until the next explicit login attempt\./);
     assert.match(result.stdout, /Out-of-scope commands remain intentionally unsupported/);
     assert.doesNotMatch(result.stdout, /auth-bootstrap/);
     assert.doesNotMatch(result.stdout, /auth-clear/);
@@ -130,7 +131,8 @@ test("repository ships man pages for the supported lowercase command names", ()
     assert.match(readFileSync(ddManPath, "utf8"), /\.B login/);
     assert.doesNotMatch(readFileSync(ddManPath, "utf8"), /auth-bootstrap/);
     assert.doesNotMatch(readFileSync(ddManPath, "utf8"), /auth-clear/);
-    assert.match(readFileSync(ddManPath, "utf8"), /automatic\s+browser-session reuse stays disabled until the next explicit/i);
+    assert.match(readFileSync(ddManPath, "utf8"), /passive\s+browser-session reuse stays disabled until the next explicit/i);
+    assert.match(readFileSync(ddManPath, "utf8"), /merely-open Chrome\/Brave window is not\s+automatically reusable/i);
     assert.match(readFileSync(ddManPath, "utf8"), /temporary Chromium.*window/i);
     assert.doesNotMatch(readFileSync(ddManPath, "utf8"), /Dd-cli/);
     assert.equal(readFileSync(aliasManPath, "utf8").trim(), ".so man1/dd-cli.1");

package/dist/direct-api.d.ts

@@ -24,6 +24,16 @@ export type AuthBootstrapResult = (AuthResult & {
     isLoggedIn: false;
     message: string;
 });
+type ManagedBrowserLoginResult = {
+    status: "completed";
+    completion: "automatic" | "manual";
+    auth: AuthResult;
+} | {
+    status: "timed-out";
+    auth: AuthResult;
+} | {
+    status: "launch-failed";
+};
 export type SearchRestaurantResult = {
     id: string;
     name: string;
@@ -469,6 +479,7 @@ type BootstrapAuthSessionDeps = {
     markBrowserImportAttempted: () => void;
     getAttachedBrowserCdpCandidates: () => Promise<string[]>;
     getReachableCdpCandidates: (candidates: string[]) => Promise<string[]>;
+    describeDesktopBrowserReuseGap: () => Promise<string | null>;
     openUrlInAttachedBrowser: (input: {
         cdpUrl: string;
         targetUrl: string;
@@ -482,7 +493,9 @@ type BootstrapAuthSessionDeps = {
         targetUrl: string;
         timeoutMs: number;
         pollIntervalMs: number;
-    }) => Promise<AuthResult | null>;
+        log: (message: string) => void;
+    }) => Promise<ManagedBrowserLoginResult>;
+    canPromptForManagedBrowserConfirmation: () => boolean;
     checkAuthDirect: () => Promise<AuthResult>;
     log: (message: string) => void;
 };
@@ -562,6 +575,10 @@ export declare function resolveSystemBrowserOpenCommand(targetUrl: string, targe
     command: string;
     args: string[];
 } | null;
+export declare function summarizeDesktopBrowserReuseGap(input: {
+    processCommands: readonly string[];
+    hasAnyDevToolsActivePort: boolean;
+}): string | null;
 export declare function parseSearchRestaurants(body: unknown[]): SearchRestaurantResult[];
 export declare function parseSearchRestaurantRow(entry: unknown): SearchRestaurantResult | null;
 export declare function parseExistingOrderLifecycleStatus(orderRoot: unknown): ExistingOrderLifecycleStatus;

package/dist/direct-api.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
+import { createInterface } from "node:readline";
 import { chromium } from "playwright";
 import { getBrowserImportBlockPath, getCookiesPath, getStorageStatePath } from "./session-storage.js";
 const BASE_URL = "https://www.doordash.com";
@@ -9,6 +10,8 @@ const AUTH_BOOTSTRAP_URL = `${BASE_URL}/home`;
 const AUTH_BOOTSTRAP_TIMEOUT_MS = 180_000;
 const AUTH_BOOTSTRAP_POLL_INTERVAL_MS = 2_000;
 const AUTH_BOOTSTRAP_NO_DISCOVERY_GRACE_MS = 10_000;
+const ATTACHED_BROWSER_CDP_REACHABILITY_TIMEOUT_MS = 2_000;
+const ATTACHED_BROWSER_CDP_CONNECT_TIMEOUT_MS = 5_000;
 const DEFAULT_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36";
 const GRAPHQL_HEADERS = {
     accept: "*/*",
@@ -864,6 +867,42 @@ function buildAuthBootstrapFailure(auth, message) {
         message,
     };
 }
+function canPromptForManagedBrowserConfirmation() {
+    return Boolean(process.stdin.isTTY);
+}
+function createManagedBrowserManualConfirmationHandle() {
+    if (!canPromptForManagedBrowserConfirmation()) {
+        return {
+            isEnabled: false,
+            consumeRequested: () => false,
+            close: () => { },
+        };
+    }
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stderr,
+        terminal: true,
+    });
+    let requested = false;
+    const onLine = () => {
+        requested = true;
+    };
+    rl.on("line", onLine);
+    return {
+        isEnabled: true,
+        consumeRequested: () => {
+            if (!requested) {
+                return false;
+            }
+            requested = false;
+            return true;
+        },
+        close: () => {
+            rl.off("line", onLine);
+            rl.close();
+        },
+    };
+}
 export async function checkAuthDirect() {
     const data = await session.graphql("consumer", CONSUMER_QUERY, {});
     return buildAuthResult(data.consumer ?? null);
@@ -891,11 +930,11 @@ export async function bootstrapAuthSessionWithDeps(deps) {
         });
         const openedDefaultBrowser = openedAttachedBrowser ? false : await deps.openUrlInDefaultBrowser(AUTH_BOOTSTRAP_URL);
         deps.log(openedAttachedBrowser
-            ? `Opened DoorDash in the reusable browser session I'm watching: ${AUTH_BOOTSTRAP_URL}`
+            ? `Opened DoorDash in the attachable browser session I'm watching: ${AUTH_BOOTSTRAP_URL}`
             : openedDefaultBrowser
-                ? `Found a reusable browser connection, but couldn't drive it directly, so I opened DoorDash in your default browser: ${AUTH_BOOTSTRAP_URL}`
-                : `Detected a reusable browser connection, but couldn't open DoorDash automatically. Open this URL in that watched browser to continue: ${AUTH_BOOTSTRAP_URL}`);
-        deps.log(`Detected ${reachableCandidates.length} reusable browser connection(s). Finish the sign-in in that browser window and I'll import it automatically for up to ${Math.round(AUTH_BOOTSTRAP_TIMEOUT_MS / 1000)} seconds.`);
+                ? `Found an attachable browser session, but couldn't drive it directly, so I opened DoorDash in your default browser: ${AUTH_BOOTSTRAP_URL}`
+                : `Detected an attachable browser session, but couldn't open DoorDash automatically. Open this URL in that watched browser to continue: ${AUTH_BOOTSTRAP_URL}`);
+        deps.log(`Detected ${reachableCandidates.length} attachable browser session(s). Finish the sign-in in that browser window and I'll import it automatically for up to ${Math.round(AUTH_BOOTSTRAP_TIMEOUT_MS / 1000)} seconds.`);
         const importedAfterWait = await deps.waitForAttachedBrowserSessionImport({
             timeoutMs: AUTH_BOOTSTRAP_TIMEOUT_MS,
             pollIntervalMs: AUTH_BOOTSTRAP_POLL_INTERVAL_MS,
@@ -903,29 +942,43 @@ export async function bootstrapAuthSessionWithDeps(deps) {
         const auth = await deps.checkAuthDirect();
         if (importedAfterWait) {
             return auth.isLoggedIn
-                ? buildAuthBootstrapSuccess(auth, "Opened DoorDash in a reusable browser session, detected the signed-in consumer state, and saved it for direct API use.")
+                ? buildAuthBootstrapSuccess(auth, "Opened DoorDash in an attachable browser session, detected the signed-in consumer state, and saved it for direct API use.")
                 : buildAuthBootstrapFailure(auth, "Detected browser session state in the watched browser, but the consumer still appears logged out or guest-only.");
         }
         return buildAuthBootstrapFailure(auth, openedAttachedBrowser || openedDefaultBrowser
-            ? `Opened DoorDash and watched reusable browser connections for ${Math.round(AUTH_BOOTSTRAP_TIMEOUT_MS / 1000)} seconds, but no signed-in DoorDash session was imported. Finish the login in that watched browser and rerun dd-cli login.`
-            : `Watched reusable browser connections for ${Math.round(AUTH_BOOTSTRAP_TIMEOUT_MS / 1000)} seconds without importing a signed-in DoorDash session. Open ${AUTH_BOOTSTRAP_URL} manually in the watched browser, finish signing in, then rerun dd-cli login.`);
-    }
-    deps.log("I couldn't find a reusable browser connection, so I'm opening a temporary Chromium login window that the CLI can watch directly.");
+            ? `Opened DoorDash and watched attachable browser sessions for ${Math.round(AUTH_BOOTSTRAP_TIMEOUT_MS / 1000)} seconds, but no signed-in DoorDash session was imported. Finish the login in that watched browser and rerun dd-cli login.`
+            : `Watched attachable browser sessions for ${Math.round(AUTH_BOOTSTRAP_TIMEOUT_MS / 1000)} seconds without importing a signed-in DoorDash session. Open ${AUTH_BOOTSTRAP_URL} manually in the watched browser, finish signing in, then rerun dd-cli login.`);
+    }
+    const desktopBrowserReuseGap = await deps.describeDesktopBrowserReuseGap().catch(() => null);
+    if (desktopBrowserReuseGap) {
+        deps.log(desktopBrowserReuseGap);
+    }
+    const manualManagedConfirmationAvailable = deps.canPromptForManagedBrowserConfirmation();
+    deps.log("I couldn't find an attachable browser session I can reuse, so I'm opening a temporary Chromium login window that the CLI can watch directly.");
+    deps.log(manualManagedConfirmationAvailable
+        ? `Finish signing in in that window. I'll keep checking automatically for up to ${Math.round(AUTH_BOOTSTRAP_TIMEOUT_MS / 1000)} seconds. If the page already shows you're signed in and the CLI still hasn't finished, press Enter here to force an immediate recheck.`
+        : `Finish signing in in that window. I'll keep checking automatically for up to ${Math.round(AUTH_BOOTSTRAP_TIMEOUT_MS / 1000)} seconds.`);
     const managedAuth = await deps.waitForManagedBrowserLogin({
         targetUrl: AUTH_BOOTSTRAP_URL,
         timeoutMs: AUTH_BOOTSTRAP_TIMEOUT_MS,
         pollIntervalMs: AUTH_BOOTSTRAP_POLL_INTERVAL_MS,
+        log: deps.log,
     });
-    if (managedAuth) {
-        return managedAuth.isLoggedIn
-            ? buildAuthBootstrapSuccess(managedAuth, "Opened a temporary Chromium login window, detected the signed-in session there, and saved it for direct API use.")
-            : buildAuthBootstrapFailure(managedAuth, `Opened a temporary Chromium login window and watched for ${Math.round(AUTH_BOOTSTRAP_TIMEOUT_MS / 1000)} seconds, but no authenticated DoorDash session was established.`);
+    if (managedAuth.status === "completed") {
+        return buildAuthBootstrapSuccess(managedAuth.auth, managedAuth.completion === "manual"
+            ? "Opened a temporary Chromium login window. After you pressed Enter to confirm the browser login was complete, the CLI rechecked the signed-in session there and saved it for direct API use."
+            : "Opened a temporary Chromium login window, detected the signed-in session there automatically, and saved it for direct API use.");
+    }
+    if (managedAuth.status === "timed-out") {
+        return buildAuthBootstrapFailure(managedAuth.auth, manualManagedConfirmationAvailable
+            ? `Opened a temporary Chromium login window and watched for ${Math.round(AUTH_BOOTSTRAP_TIMEOUT_MS / 1000)} seconds, but I still couldn't prove an authenticated DoorDash session. If the browser already looks signed in, press Enter sooner next time to force an immediate recheck, or rerun dd-cli login.`
+            : `Opened a temporary Chromium login window and watched for ${Math.round(AUTH_BOOTSTRAP_TIMEOUT_MS / 1000)} seconds, but no authenticated DoorDash session was established.`);
     }
     const openedBrowser = await deps.openUrlInDefaultBrowser(AUTH_BOOTSTRAP_URL);
     deps.log(openedBrowser
         ? `I couldn't launch the temporary Chromium login window, so I opened DoorDash in your default browser instead: ${AUTH_BOOTSTRAP_URL}`
         : `Couldn't open the temporary Chromium login window or your default browser automatically. Open this URL to continue: ${AUTH_BOOTSTRAP_URL}`);
-    deps.log("This environment still isn't exposing a reusable browser session the CLI can import, so I won't keep you waiting for the full login timeout. Once you've exposed a compatible browser session, rerun `dd-cli login`.");
+    deps.log("This environment still isn't exposing an attachable browser session the CLI can import, so I won't keep you waiting for the full login timeout. Once you've exposed an attachable browser session, rerun `dd-cli login`.");
     const importedAfterGrace = await deps.waitForAttachedBrowserSessionImport({
         timeoutMs: AUTH_BOOTSTRAP_NO_DISCOVERY_GRACE_MS,
         pollIntervalMs: AUTH_BOOTSTRAP_POLL_INTERVAL_MS,
@@ -933,12 +986,12 @@ export async function bootstrapAuthSessionWithDeps(deps) {
     const auth = await deps.checkAuthDirect();
     if (importedAfterGrace) {
         return auth.isLoggedIn
-            ? buildAuthBootstrapSuccess(auth, "A reusable browser session appeared a few seconds later and was saved for direct API use.")
+            ? buildAuthBootstrapSuccess(auth, "An attachable browser session appeared a few seconds later and was saved for direct API use.")
             : buildAuthBootstrapFailure(auth, "Detected browser session state after opening the browser, but the consumer still appears logged out or guest-only.");
     }
     return buildAuthBootstrapFailure(auth, openedBrowser
-        ? "Opened DoorDash in your default browser, but this environment still isn't exposing a reusable browser session the CLI can import. Finish signing in there, make a compatible browser session discoverable, then rerun `dd-cli login`."
-        : "Couldn't open a watchable browser automatically, and this environment still isn't exposing a reusable browser session the CLI can import. Open the DoorDash home page manually, make a compatible browser session discoverable, then rerun `dd-cli login`.");
+        ? "Opened DoorDash in your default browser, but this environment still isn't exposing an attachable browser session the CLI can import. Finish signing in there, make an attachable browser session discoverable, then rerun `dd-cli login`."
+        : "Couldn't open a watchable browser automatically, and this environment still isn't exposing an attachable browser session the CLI can import. Open the DoorDash home page manually, make an attachable browser session discoverable, then rerun `dd-cli login`.");
 }
 export async function bootstrapAuthSession() {
     return bootstrapAuthSessionWithDeps({
@@ -948,10 +1001,12 @@ export async function bootstrapAuthSession() {
         markBrowserImportAttempted: () => session.markBrowserImportAttempted(),
         getAttachedBrowserCdpCandidates,
         getReachableCdpCandidates,
+        describeDesktopBrowserReuseGap,
         openUrlInAttachedBrowser,
         openUrlInDefaultBrowser,
         waitForAttachedBrowserSessionImport,
         waitForManagedBrowserLogin,
+        canPromptForManagedBrowserConfirmation,
         checkAuthDirect,
         log: (message) => console.error(message),
     });
@@ -1671,7 +1726,7 @@ async function importBrowserSessionFromCdpCandidates(candidates) {
         let browser = null;
         let tempPage = null;
         try {
-            browser = await chromium.connectOverCDP(cdpUrl);
+            browser = await chromium.connectOverCDP(cdpUrl, { timeout: ATTACHED_BROWSER_CDP_CONNECT_TIMEOUT_MS });
             const context = browser.contexts()[0];
             if (!context) {
                 continue;
@@ -1731,6 +1786,26 @@ async function fetchConsumerViaPage(page) {
     });
     return parseGraphQlResponse("attachedBrowserConsumerImport", raw.status, raw.text);
 }
+async function readLiveManagedBrowserAuth(page) {
+    if (!page || page.isClosed()) {
+        return buildAuthResult(null);
+    }
+    const consumerData = await fetchConsumerViaPage(page).catch(() => null);
+    return buildAuthResult(consumerData?.consumer ?? null);
+}
+async function confirmManagedBrowserAuth(context, page) {
+    const liveAuth = await readLiveManagedBrowserAuth(page);
+    if (liveAuth.isLoggedIn) {
+        if (context) {
+            await saveContextState(context).catch(() => { });
+        }
+        return liveAuth;
+    }
+    if (context) {
+        await saveContextState(context).catch(() => { });
+    }
+    return (await getPersistedAuthDirect().catch(() => null)) ?? liveAuth;
+}
 async function saveContextState(context, cookies = null) {
     const storageStatePath = getStorageStatePath();
     await ensureConfigDir();
@@ -1869,7 +1944,7 @@ async function openUrlInDefaultBrowser(targetUrl) {
 async function openUrlInAttachedBrowser(input) {
     let browser = null;
     try {
-        browser = await chromium.connectOverCDP(input.cdpUrl);
+        browser = await chromium.connectOverCDP(input.cdpUrl, { timeout: ATTACHED_BROWSER_CDP_CONNECT_TIMEOUT_MS });
         const context = browser.contexts()[0];
         if (!context) {
             return false;
@@ -1893,6 +1968,7 @@ async function waitForManagedBrowserLogin(input) {
     let browser = null;
     let context = null;
     let page = null;
+    const manualConfirmation = createManagedBrowserManualConfirmationHandle();
     try {
         browser = await chromium.launch({
             headless: false,
@@ -1917,10 +1993,25 @@ async function waitForManagedBrowserLogin(input) {
         await page.bringToFront().catch(() => { });
         const deadline = Date.now() + input.timeoutMs;
         while (Date.now() <= deadline) {
-            await saveContextState(context).catch(() => { });
-            const auth = await getPersistedAuthDirect();
-            if (auth?.isLoggedIn) {
-                return auth;
+            const liveAuth = await readLiveManagedBrowserAuth(page);
+            if (liveAuth.isLoggedIn) {
+                await saveContextState(context).catch(() => { });
+                return {
+                    status: "completed",
+                    completion: "automatic",
+                    auth: liveAuth,
+                };
+            }
+            if (manualConfirmation.consumeRequested()) {
+                const confirmedAuth = await confirmManagedBrowserAuth(context, page);
+                if (confirmedAuth.isLoggedIn) {
+                    return {
+                        status: "completed",
+                        completion: "manual",
+                        auth: confirmedAuth,
+                    };
+                }
+                input.log("Still not seeing an authenticated DoorDash session yet. Finish signing in in the opened browser window, then press Enter again or keep waiting for automatic detection.");
             }
             if (page.isClosed()) {
                 break;
@@ -1930,16 +2021,27 @@ async function waitForManagedBrowserLogin(input) {
             }
             await wait(input.pollIntervalMs);
         }
-        await saveContextState(context).catch(() => { });
-        return (await getPersistedAuthDirect()) ?? buildAuthResult(null);
+        const finalAuth = await confirmManagedBrowserAuth(context, page);
+        if (finalAuth.isLoggedIn) {
+            return {
+                status: "completed",
+                completion: "automatic",
+                auth: finalAuth,
+            };
+        }
+        return {
+            status: "timed-out",
+            auth: finalAuth,
+        };
     }
     catch (error) {
         if (isPlaywrightBrowserInstallMissingError(error)) {
-            return null;
+            return { status: "launch-failed" };
         }
-        return null;
+        return { status: "launch-failed" };
     }
     finally {
+        manualConfirmation.close();
         await page?.close().catch(() => { });
         await context?.close().catch(() => { });
         await browser?.close().catch(() => { });
@@ -1952,6 +2054,40 @@ function isPlaywrightBrowserInstallMissingError(error) {
     const message = error.message.toLowerCase();
     return message.includes("executable doesn't exist") || message.includes("please run the following command") || message.includes("playwright install");
 }
+const KNOWN_DESKTOP_BROWSERS = [
+    {
+        label: "Brave",
+        processMatchers: [/\bbrave-browser(?:-stable)?\b/i, /\/brave(?:$|\s)/i],
+        devToolsActivePortPaths: [
+            join(homedir(), ".config", "BraveSoftware", "Brave-Browser", "DevToolsActivePort"),
+            join(homedir(), "Library", "Application Support", "BraveSoftware", "Brave-Browser", "DevToolsActivePort"),
+        ],
+    },
+    {
+        label: "Google Chrome",
+        processMatchers: [/\bgoogle-chrome(?:-stable|-beta|-unstable)?\b/i, /\/google-chrome(?:$|\s)/i],
+        devToolsActivePortPaths: [
+            join(homedir(), ".config", "google-chrome", "DevToolsActivePort"),
+            join(homedir(), "Library", "Application Support", "Google", "Chrome", "DevToolsActivePort"),
+        ],
+    },
+    {
+        label: "Microsoft Edge",
+        processMatchers: [/\bmicrosoft-edge(?:-stable|-beta|-dev)?\b/i, /\/microsoft-edge(?:$|\s)/i],
+        devToolsActivePortPaths: [
+            join(homedir(), ".config", "microsoft-edge", "DevToolsActivePort"),
+            join(homedir(), "Library", "Application Support", "Microsoft Edge", "DevToolsActivePort"),
+        ],
+    },
+    {
+        label: "Chromium",
+        processMatchers: [/\bchromium-browser\b/i, /\bchromium\b/i],
+        devToolsActivePortPaths: [
+            join(homedir(), ".config", "chromium", "DevToolsActivePort"),
+            join(homedir(), "Library", "Application Support", "Chromium", "DevToolsActivePort"),
+        ],
+    },
+];
 function normalizeCdpCandidate(value) {
     return value.trim().replace(/\/$/, "");
 }
@@ -2001,6 +2137,82 @@ function wait(ms) {
         setTimeout(resolve, ms);
     });
 }
+function detectRunningDesktopBrowser(processCommands) {
+    const filteredCommands = processCommands
+        .map((command) => command.trim())
+        .filter((command) => command.length > 0)
+        .filter((command) => !/chrome-devtools-mcp/i.test(command));
+    for (const browser of KNOWN_DESKTOP_BROWSERS) {
+        const preferredMatch = filteredCommands.some((command) => !/--type=|crashpad|zygote/i.test(command) && browser.processMatchers.some((matcher) => matcher.test(command)));
+        if (preferredMatch) {
+            return browser;
+        }
+    }
+    for (const browser of KNOWN_DESKTOP_BROWSERS) {
+        if (filteredCommands.some((command) => browser.processMatchers.some((matcher) => matcher.test(command)))) {
+            return browser;
+        }
+    }
+    return null;
+}
+function hasRemoteDebuggingSignal(processCommands) {
+    return processCommands.some((command) => /--remote-debugging-(?:port|pipe)(?:=|\b)/i.test(command));
+}
+export function summarizeDesktopBrowserReuseGap(input) {
+    const browser = detectRunningDesktopBrowser(input.processCommands);
+    if (!browser) {
+        return null;
+    }
+    if (hasRemoteDebuggingSignal(input.processCommands) || input.hasAnyDevToolsActivePort) {
+        return null;
+    }
+    return `I can see ${browser.label} is already running on this desktop, but it is not exposing an attachable browser automation session right now. A normal open browser window is not automatically reusable; dd-cli can only import a browser session it can actually attach to.`;
+}
+async function captureCommandStdout(command, args) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: ["ignore", "pipe", "ignore"] });
+        const stdout = [];
+        child.once("error", reject);
+        child.stdout?.on("data", (chunk) => {
+            stdout.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+        child.once("close", (code) => {
+            if (code === 0) {
+                resolve(Buffer.concat(stdout).toString("utf8"));
+                return;
+            }
+            reject(new Error(`${command} exited with code ${code ?? "null"}`));
+        });
+    });
+}
+async function listProcessCommands(targetPlatform = process.platform) {
+    if (targetPlatform === "win32") {
+        return [];
+    }
+    const args = targetPlatform === "darwin" ? ["-axo", "command="] : ["-eo", "command="];
+    const stdout = await captureCommandStdout("ps", args).catch(() => "");
+    return stdout
+        .split(/\r?\n/)
+        .map((command) => command.trim())
+        .filter((command) => command.length > 0);
+}
+async function hasAnyKnownDevToolsActivePort() {
+    for (const browser of KNOWN_DESKTOP_BROWSERS) {
+        for (const path of browser.devToolsActivePortPaths) {
+            if ((await readFile(path, "utf8").catch(() => null)) !== null) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+async function describeDesktopBrowserReuseGap() {
+    const processCommands = await listProcessCommands();
+    return summarizeDesktopBrowserReuseGap({
+        processCommands,
+        hasAnyDevToolsActivePort: await hasAnyKnownDevToolsActivePort(),
+    });
+}
 async function readOpenClawBrowserConfigCandidates(input) {
     try {
         const raw = await readFile(join(homedir(), ".openclaw", "openclaw.json"), "utf8");
@@ -2021,7 +2233,9 @@ async function readOpenClawBrowserConfigCandidates(input) {
 }
 async function isCdpEndpointReachable(cdpUrl) {
     try {
-        const response = await fetch(`${cdpUrl.replace(/\/$/, "")}/json/version`);
+        const response = await fetch(`${cdpUrl.replace(/\/$/, "")}/json/version`, {
+            signal: AbortSignal.timeout(ATTACHED_BROWSER_CDP_REACHABILITY_TIMEOUT_MS),
+        });
         return response.ok;
     }
     catch {

package/dist/direct-api.test.js

@@ -1,6 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { bootstrapAuthSessionWithDeps, buildAddConsumerAddressPayload, buildAddToCartPayload, buildUpdateCartPayload, extractExistingOrdersFromApolloCache, normalizeItemName, parseExistingOrderLifecycleStatus, parseExistingOrdersResponse, parseOptionSelectionsJson, parseSearchRestaurantRow, resolveAttachedBrowserCdpCandidates, resolveAvailableAddressMatch, resolveSystemBrowserOpenCommand, selectAttachedBrowserImportMode, } from "./direct-api.js";
+import { bootstrapAuthSessionWithDeps, buildAddConsumerAddressPayload, buildAddToCartPayload, buildUpdateCartPayload, extractExistingOrdersFromApolloCache, normalizeItemName, parseExistingOrderLifecycleStatus, parseExistingOrdersResponse, parseOptionSelectionsJson, parseSearchRestaurantRow, resolveAttachedBrowserCdpCandidates, resolveAvailableAddressMatch, resolveSystemBrowserOpenCommand, selectAttachedBrowserImportMode, summarizeDesktopBrowserReuseGap, } from "./direct-api.js";
 function configurableItemDetail() {
     return {
         success: true,
@@ -181,6 +181,29 @@ test("resolveSystemBrowserOpenCommand stays generic across operating systems", (
         args: ["/c", "start", "", "https://www.doordash.com/home"],
     });
 });
+test("summarizeDesktopBrowserReuseGap explains why a merely-open Brave window is not reusable", () => {
+    const message = summarizeDesktopBrowserReuseGap({
+        processCommands: [
+            "/bin/bash /usr/bin/brave-browser-stable",
+            "/opt/brave.com/brave/brave",
+            "/opt/brave.com/brave/brave --type=renderer",
+        ],
+        hasAnyDevToolsActivePort: false,
+    });
+    assert.match(message ?? "", /Brave is already running on this desktop/i);
+    assert.match(message ?? "", /normal open browser window is not automatically reusable/i);
+    assert.match(message ?? "", /attach to/i);
+});
+test("summarizeDesktopBrowserReuseGap stays quiet once the browser exposes attach signals", () => {
+    assert.equal(summarizeDesktopBrowserReuseGap({
+        processCommands: ["/bin/bash /usr/bin/brave-browser-stable --remote-debugging-port=9222"],
+        hasAnyDevToolsActivePort: false,
+    }), null);
+    assert.equal(summarizeDesktopBrowserReuseGap({
+        processCommands: ["/bin/bash /usr/bin/brave-browser-stable"],
+        hasAnyDevToolsActivePort: true,
+    }), null);
+});
 test("selectAttachedBrowserImportMode treats an authenticated browser with DoorDash cookies as an immediate import candidate", () => {
     assert.equal(selectAttachedBrowserImportMode({
         pageUrls: ["https://github.com/LatencyTDH/doordash-cli/pulls"],
@@ -229,6 +252,7 @@ test("bootstrapAuthSessionWithDeps returns immediately when saved local auth is
         getReachableCdpCandidates: async () => {
             throw new Error("should not probe reachability when saved auth is already valid");
         },
+        describeDesktopBrowserReuseGap: async () => null,
         openUrlInAttachedBrowser: async () => {
             throw new Error("should not try to open an attached browser when saved auth is already valid");
         },
@@ -243,6 +267,7 @@ test("bootstrapAuthSessionWithDeps returns immediately when saved local auth is
         waitForManagedBrowserLogin: async () => {
             throw new Error("should not launch a managed browser when saved auth is already valid");
         },
+        canPromptForManagedBrowserConfirmation: () => false,
         checkAuthDirect: async () => {
             throw new Error("should not re-check auth through the live session when saved auth is already valid");
         },
@@ -288,6 +313,7 @@ test("bootstrapAuthSessionWithDeps returns immediately when an attached browser
         getReachableCdpCandidates: async () => {
             throw new Error("should not probe reachability on immediate browser-session import");
         },
+        describeDesktopBrowserReuseGap: async () => null,
         openUrlInAttachedBrowser: async () => {
             throw new Error("should not open a browser when immediate browser-session import succeeded");
         },
@@ -302,6 +328,7 @@ test("bootstrapAuthSessionWithDeps returns immediately when an attached browser
         waitForManagedBrowserLogin: async () => {
             throw new Error("should not launch a managed browser when immediate browser-session import succeeded");
         },
+        canPromptForManagedBrowserConfirmation: () => false,
         checkAuthDirect: async () => auth,
         log: (message) => {
             logs.push(message);
@@ -343,6 +370,7 @@ test("bootstrapAuthSessionWithDeps opens a watchable attached browser session be
             reachableCalls += 1;
             return candidates;
         },
+        describeDesktopBrowserReuseGap: async () => null,
         openUrlInAttachedBrowser: async () => {
             openAttachedCalls += 1;
             return true;
@@ -359,6 +387,7 @@ test("bootstrapAuthSessionWithDeps opens a watchable attached browser session be
         waitForManagedBrowserLogin: async () => {
             throw new Error("should not launch a managed browser when an attached browser is reachable");
         },
+        canPromptForManagedBrowserConfirmation: () => false,
         checkAuthDirect: async () => auth,
         log: (message) => {
             logs.push(message);
@@ -369,11 +398,11 @@ test("bootstrapAuthSessionWithDeps opens a watchable attached browser session be
     assert.equal(openDefaultCalls, 0);
     assert.equal(waitCalls, 1);
     assert.equal(waitTimeoutMs, 180_000);
-    assert.match(logs.join("\n"), /Opened DoorDash in the reusable browser session I'm watching/);
-    assert.match(logs.join("\n"), /Detected 1 reusable browser connection/);
+    assert.match(logs.join("\n"), /Opened DoorDash in the attachable browser session I'm watching/);
+    assert.match(logs.join("\n"), /Detected 1 attachable browser session/);
     assert.match(result.message, /saved it for direct API use/);
 });
-test("bootstrapAuthSessionWithDeps falls back to a managed browser login window when no reusable browser connection is discoverable", async () => {
+test("bootstrapAuthSessionWithDeps falls back to a managed browser login window and auto-completes when it can prove login", async () => {
     const auth = {
         success: true,
         isLoggedIn: true,
@@ -396,6 +425,7 @@ test("bootstrapAuthSessionWithDeps falls back to a managed browser login window
         markBrowserImportAttempted: () => { },
         getAttachedBrowserCdpCandidates: async () => ["http://127.0.0.1:9222"],
         getReachableCdpCandidates: async () => [],
+        describeDesktopBrowserReuseGap: async () => null,
         openUrlInAttachedBrowser: async () => false,
         openUrlInDefaultBrowser: async () => true,
         waitForAttachedBrowserSessionImport: async () => {
@@ -404,8 +434,13 @@ test("bootstrapAuthSessionWithDeps falls back to a managed browser login window
         },
         waitForManagedBrowserLogin: async () => {
             managedCalls += 1;
-            return auth;
+            return {
+                status: "completed",
+                completion: "automatic",
+                auth,
+            };
         },
+        canPromptForManagedBrowserConfirmation: () => true,
         checkAuthDirect: async () => auth,
         log: (message) => {
             logs.push(message);
@@ -414,10 +449,143 @@ test("bootstrapAuthSessionWithDeps falls back to a managed browser login window
     assert.equal(managedCalls, 1);
     assert.equal(attachedWaitCalls, 0);
     assert.match(logs.join("\n"), /temporary Chromium login window/);
-    assert.match(result.message, /temporary Chromium login window/);
+    assert.match(logs.join("\n"), /press Enter here to force an immediate recheck/i);
+    assert.match(result.message, /detected the signed-in session there automatically/i);
+    assert.equal(result.success, true);
+    assert.equal(result.isLoggedIn, true);
+});
+test("bootstrapAuthSessionWithDeps logs why an already-open desktop browser still is not reusable", async () => {
+    const auth = {
+        success: true,
+        isLoggedIn: true,
+        email: "user@example.com",
+        firstName: "Test",
+        lastName: "User",
+        consumerId: "consumer-1",
+        marketId: "market-1",
+        defaultAddress: null,
+        cookiesPath: "/tmp/cookies.json",
+        storageStatePath: "/tmp/storage-state.json",
+    };
+    const logs = [];
+    const result = await bootstrapAuthSessionWithDeps({
+        clearBlockedBrowserImport: async () => { },
+        checkPersistedAuth: async () => null,
+        importBrowserSessionIfAvailable: async () => false,
+        markBrowserImportAttempted: () => { },
+        getAttachedBrowserCdpCandidates: async () => [],
+        getReachableCdpCandidates: async () => [],
+        describeDesktopBrowserReuseGap: async () => "I can see Brave is already running on this desktop, but it is not exposing an attachable browser automation session right now.",
+        openUrlInAttachedBrowser: async () => false,
+        openUrlInDefaultBrowser: async () => true,
+        waitForAttachedBrowserSessionImport: async () => false,
+        waitForManagedBrowserLogin: async () => ({
+            status: "completed",
+            completion: "automatic",
+            auth,
+        }),
+        canPromptForManagedBrowserConfirmation: () => true,
+        checkAuthDirect: async () => auth,
+        log: (message) => {
+            logs.push(message);
+        },
+    });
+    assert.match(logs.join("\n"), /Brave is already running on this desktop/i);
+    assert.match(logs.join("\n"), /couldn't find an attachable browser session I can reuse/i);
     assert.equal(result.success, true);
     assert.equal(result.isLoggedIn, true);
 });
+test("bootstrapAuthSessionWithDeps restores an explicit Enter-style completion path for the managed browser fallback", async () => {
+    const auth = {
+        success: true,
+        isLoggedIn: true,
+        email: "user@example.com",
+        firstName: "Test",
+        lastName: "User",
+        consumerId: "consumer-1",
+        marketId: "market-1",
+        defaultAddress: null,
+        cookiesPath: "/tmp/cookies.json",
+        storageStatePath: "/tmp/storage-state.json",
+    };
+    const logs = [];
+    const result = await bootstrapAuthSessionWithDeps({
+        clearBlockedBrowserImport: async () => { },
+        checkPersistedAuth: async () => null,
+        importBrowserSessionIfAvailable: async () => false,
+        markBrowserImportAttempted: () => { },
+        getAttachedBrowserCdpCandidates: async () => [],
+        getReachableCdpCandidates: async () => [],
+        describeDesktopBrowserReuseGap: async () => null,
+        openUrlInAttachedBrowser: async () => false,
+        openUrlInDefaultBrowser: async () => true,
+        waitForAttachedBrowserSessionImport: async () => false,
+        waitForManagedBrowserLogin: async () => ({
+            status: "completed",
+            completion: "manual",
+            auth,
+        }),
+        canPromptForManagedBrowserConfirmation: () => true,
+        checkAuthDirect: async () => auth,
+        log: (message) => {
+            logs.push(message);
+        },
+    });
+    assert.match(logs.join("\n"), /press Enter here to force an immediate recheck/i);
+    assert.match(result.message, /After you pressed Enter to confirm the browser login was complete/i);
+    assert.equal(result.success, true);
+    assert.equal(result.isLoggedIn, true);
+});
+test("bootstrapAuthSessionWithDeps returns a bounded failure instead of a dead-end when managed browser auto-detection cannot prove login", async () => {
+    const auth = {
+        success: true,
+        isLoggedIn: false,
+        email: null,
+        firstName: null,
+        lastName: null,
+        consumerId: null,
+        marketId: null,
+        defaultAddress: null,
+        cookiesPath: "/tmp/cookies.json",
+        storageStatePath: "/tmp/storage-state.json",
+    };
+    let attachedWaitCalls = 0;
+    let attachedWaitTimeoutMs = 0;
+    const logs = [];
+    const result = await bootstrapAuthSessionWithDeps({
+        clearBlockedBrowserImport: async () => { },
+        checkPersistedAuth: async () => null,
+        importBrowserSessionIfAvailable: async () => false,
+        markBrowserImportAttempted: () => { },
+        getAttachedBrowserCdpCandidates: async () => ["http://127.0.0.1:9222"],
+        getReachableCdpCandidates: async () => [],
+        describeDesktopBrowserReuseGap: async () => null,
+        openUrlInAttachedBrowser: async () => false,
+        openUrlInDefaultBrowser: async () => true,
+        waitForAttachedBrowserSessionImport: async (input) => {
+            attachedWaitCalls += 1;
+            attachedWaitTimeoutMs = input.timeoutMs;
+            return false;
+        },
+        waitForManagedBrowserLogin: async () => ({
+            status: "timed-out",
+            auth,
+        }),
+        canPromptForManagedBrowserConfirmation: () => true,
+        checkAuthDirect: async () => auth,
+        log: (message) => {
+            logs.push(message);
+        },
+    });
+    assert.equal(attachedWaitCalls, 0);
+    assert.equal(attachedWaitTimeoutMs, 0);
+    assert.match(logs.join("\n"), /temporary Chromium login window/i);
+    assert.match(logs.join("\n"), /press Enter here to force an immediate recheck/i);
+    assert.equal(result.success, false);
+    assert.equal(result.isLoggedIn, false);
+    assert.match(result.message, /couldn't prove an authenticated DoorDash session/i);
+    assert.match(result.message, /press Enter sooner next time/i);
+});
 test("bootstrapAuthSessionWithDeps falls back to quick troubleshooting guidance when the managed browser login window cannot launch", async () => {
     const auth = {
         success: true,
@@ -441,6 +609,7 @@ test("bootstrapAuthSessionWithDeps falls back to quick troubleshooting guidance
         markBrowserImportAttempted: () => { },
         getAttachedBrowserCdpCandidates: async () => ["http://127.0.0.1:9222"],
         getReachableCdpCandidates: async () => [],
+        describeDesktopBrowserReuseGap: async () => null,
         openUrlInAttachedBrowser: async () => false,
         openUrlInDefaultBrowser: async () => true,
         waitForAttachedBrowserSessionImport: async (input) => {
@@ -448,7 +617,8 @@ test("bootstrapAuthSessionWithDeps falls back to quick troubleshooting guidance
             attachedWaitTimeoutMs = input.timeoutMs;
             return false;
         },
-        waitForManagedBrowserLogin: async () => null,
+        waitForManagedBrowserLogin: async () => ({ status: "launch-failed" }),
+        canPromptForManagedBrowserConfirmation: () => true,
         checkAuthDirect: async () => auth,
         log: (message) => {
             logs.push(message);
@@ -460,7 +630,53 @@ test("bootstrapAuthSessionWithDeps falls back to quick troubleshooting guidance
     assert.match(logs.join("\n"), /won't keep you waiting for the full login timeout/i);
     assert.equal(result.success, false);
     assert.equal(result.isLoggedIn, false);
-    assert.match(result.message, /still isn't exposing a reusable browser session/);
+    assert.match(result.message, /still isn't exposing an attachable browser session/);
+});
+test("bootstrapAuthSessionWithDeps clears the logout block before an explicit login reuses an attached browser session", async () => {
+    const auth = {
+        success: true,
+        isLoggedIn: true,
+        email: "user@example.com",
+        firstName: "Test",
+        lastName: "User",
+        consumerId: "consumer-1",
+        marketId: "market-1",
+        defaultAddress: null,
+        cookiesPath: "/tmp/cookies.json",
+        storageStatePath: "/tmp/storage-state.json",
+    };
+    let blocked = true;
+    let clearCalls = 0;
+    let importCalls = 0;
+    const result = await bootstrapAuthSessionWithDeps({
+        clearBlockedBrowserImport: async () => {
+            clearCalls += 1;
+            blocked = false;
+        },
+        checkPersistedAuth: async () => null,
+        importBrowserSessionIfAvailable: async () => {
+            importCalls += 1;
+            return blocked === false;
+        },
+        markBrowserImportAttempted: () => { },
+        getAttachedBrowserCdpCandidates: async () => [],
+        getReachableCdpCandidates: async () => [],
+        describeDesktopBrowserReuseGap: async () => null,
+        openUrlInAttachedBrowser: async () => false,
+        openUrlInDefaultBrowser: async () => false,
+        waitForAttachedBrowserSessionImport: async () => false,
+        waitForManagedBrowserLogin: async () => {
+            throw new Error("should not launch a managed browser when explicit login can immediately reuse an attached browser session");
+        },
+        canPromptForManagedBrowserConfirmation: () => false,
+        checkAuthDirect: async () => auth,
+        log: () => { },
+    });
+    assert.equal(clearCalls, 1);
+    assert.equal(importCalls, 1);
+    assert.equal(result.success, true);
+    assert.equal(result.isLoggedIn, true);
+    assert.match(result.message, /Imported an existing signed-in browser session/);
 });
 test("parseOptionSelectionsJson parses structured recursive option selections", () => {
     assert.deepEqual(parseOptionSelectionsJson('[{"groupId":"703393388","optionId":"4716032529"},{"groupId":"recommended_option_546935995","optionId":"546936011","children":[{"groupId":"780057412","optionId":"4702669757","quantity":2}]}]'), [

package/docs/examples.md

@@ -26,13 +26,13 @@ Check whether you already have reusable session state:
 doordash-cli auth-check
 ```
 
-If your saved local state is still valid, this exits immediately. Otherwise it tries to reuse a discoverable signed-in browser session, or opens a temporary Chromium login window and saves the session there:
+If your saved local state is still valid, this exits immediately. Otherwise it tries to reuse a discoverable attachable signed-in browser session. A merely-open Chrome/Brave window is not automatically reusable unless the CLI can actually attach to it, so the fallback is a temporary Chromium login window the CLI can watch directly. In that temporary-browser fallback, the CLI keeps checking automatically and you can also press Enter in the terminal to force an immediate recheck once the page shows you are signed in:
 
 ```bash
 doordash-cli login
 ```
 
-Reset saved session state when you want a clean logged-out start. This also disables automatic browser-session reuse until your next explicit `doordash-cli login`:
+Reset saved session state when you want a clean logged-out start. This also disables passive browser-session reuse until your next explicit `doordash-cli login`:
 
 ```bash
 doordash-cli logout

package/docs/install.md

@@ -60,14 +60,14 @@ doordash-cli search --query sushi
 
 ## Login and session reuse
 
-`doordash-cli login` reuses saved local auth when it is still valid. Otherwise it tries to import a discoverable signed-in browser session. If neither is available, it opens a temporary Chromium login window and saves the session there. If authentication still is not established, `login` exits non-zero.
+`doordash-cli login` reuses saved local auth when it is still valid. Otherwise it tries to import a discoverable attachable signed-in browser session. A merely-open Chrome/Brave window is not automatically reusable unless the CLI can actually attach to it. If no attachable session is available, it opens a temporary Chromium login window and saves the session there. If authentication still is not established, `login` exits non-zero.
 
-`doordash-cli auth-check` can also quietly import a discoverable signed-in browser session unless `doordash-cli logout` disabled that auto-reuse.
+`doordash-cli auth-check` can also quietly import a discoverable attachable signed-in browser session unless `doordash-cli logout` disabled that auto-reuse.
 
-`doordash-cli logout` clears persisted cookies and stored browser state, then keeps automatic browser-session reuse disabled until you explicitly run `doordash-cli login` again.
+`doordash-cli logout` clears persisted cookies and stored browser state, then keeps passive browser-session reuse disabled until your next explicit `doordash-cli login` attempt.
 
 ## Browser-session troubleshooting
 
-Normally you should not need to think about browser plumbing. If `doordash-cli login` opens a temporary Chromium window, finish signing in there and let the CLI save the session.
+Normally you should not need to think about browser plumbing. If `doordash-cli login` opens a temporary Chromium window, finish signing in there and let the CLI save the session. The CLI keeps checking automatically, and if the page already shows you are signed in but the command has not finished yet, press Enter in the terminal to force an immediate recheck.
 
-If you expected reuse from another browser instead, make sure that browser exposes a compatible CDP endpoint, then rerun `doordash-cli login`.
+If you expected reuse from another browser instead, make sure that browser exposes an attachable browser automation session the CLI can actually import. A merely-open browser window is not enough today, even if it is already your main browser.

package/man/dd-cli.1

@@ -35,20 +35,25 @@ local browser, including the temporary login-window fallback.
 .TP
 .B auth-check
 Verify whether the saved session appears authenticated. This command can also
-quietly reuse or import an already-signed-in browser session when one is
-available, unless
+quietly reuse or import an already-signed-in attachable browser session when
+one is available, unless
 .B logout
 explicitly disabled that auto-reuse.
 .TP
 .B login
 Reuse saved local auth when possible. Otherwise try to import a discoverable
-signed-in browser session, or open a temporary Chromium login window and save
-that session there. If authentication is still not established,
+attachable signed-in browser session. A merely-open Chrome/Brave window is not
+automatically reusable unless the CLI can actually attach to it. If no
+attachable session is available, open a temporary Chromium login window and save
+that session there. The temporary-browser fallback auto-detects completion when
+it can, and also accepts an explicit Enter keypress in the terminal to force an
+immediate recheck once the page shows the user is signed in. If authentication
+is still not established,
 .B login
 exits non-zero.
 .TP
 .B logout
-Delete stored session material used by this CLI and disable automatic
+Delete stored session material used by this CLI and disable passive
 browser-session reuse until the next explicit
 .BR login .
 .TP
@@ -205,14 +210,17 @@ time, but the saved state is reused across runs unless cleared with
 .BR logout .
 After
 .BR logout ,
-automatic browser-session reuse stays disabled until the next explicit
+passive browser-session reuse stays disabled until the next explicit
 .BR login .
 .SH ENVIRONMENT
 .PP
 In the common case you should not need to configure browser plumbing manually.
 For attached-browser reuse, the CLI can probe compatible CDP URLs/ports and a
-few localhost defaults. If no reusable browser connection is discoverable,
-login falls back to a temporary Chromium window it can watch directly. See
+few localhost defaults. A merely-open browser window is not automatically
+reusable unless the CLI can actually attach to it. If no attachable browser
+session is discoverable, login falls back to a temporary Chromium window it can
+watch directly, with an explicit Enter-to-recheck fallback in the terminal if
+automatic detection is not yet convincing. See
 .I docs/install.md
 for setup and troubleshooting.
 .SH EXIT STATUS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doordash-cli",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Cart-safe DoorDash CLI with direct API support for browse, read-only existing-order, and cart workflows.",
   "type": "module",
   "main": "dist/lib.js",