luckiest-co 1.0.47 → 1.0.49

package/skills/trends/scripts/lib/setup_wizard.py

@@ -8,6 +8,7 @@ presents it), but this module provides the detection and setup actions.
 import json
 import logging
 import os
+import re
 import shutil
 import subprocess
 import time
@@ -16,6 +17,9 @@ from typing import Any, Dict, Optional, Tuple
 from urllib.error import HTTPError, URLError
 from urllib.request import Request, urlopen
 
+from . import brightdata
+from .private_files import write_private_text
+
 logger = logging.getLogger(__name__)
 
 
@@ -28,6 +32,42 @@ def is_first_run(config: Dict[str, Any]) -> bool:
     return not config.get("SETUP_COMPLETE")
 
 
+_WELCOME_TEXT = """Welcome to /last30days! I research any topic across Reddit, X, YouTube, TikTok, Digg, arXiv, Techmeme, HN, Polymarket & more - what people actually said in the last 30 days. Let's get you set up (~30s).
+
+I synthesize what people are actually saying right now across social, news, and market sources.
+
+Auto setup gives you the core sources free in about 30 seconds:
+- Reddit with comments - free keyless discovery (Reddit search + shreddit), no API key needed.
+- YouTube search + transcripts - installs yt-dlp (open source, 190K+ GitHub stars).
+- Digg - trending news, GitHub stars, and pipeline feeds - installs the free, keyless Digg CLI.
+- arXiv (papers) + Techmeme (tech-news) - install free, keyless Printing Press CLIs and run on any topic (arXiv is relevance + recency gated to research topics).
+- StockTwits - retail trader sentiment - auto-on when your topic is a ticker or crypto (e.g. "$NVDA earnings", "bitcoin"), off for everything else.
+- Trustpilot - brand/company review sentiment - opt-in (add trustpilot to INCLUDE_SOURCES), off by default.
+- Hacker News + Polymarket + GitHub (auto-on if the gh CLI is installed) - always on, zero config.
+- X/Twitter - optional. It stays available when you already configured it, or after you explicitly approve a browser-cookie read; skipping it never blocks research.
+
+Want TikTok and Instagram too? ScrapeCreators adds those (10,000 free calls, scrapecreators.com). No kickbacks, no affiliation.
+
+Power users can turn on more sources in the Manual Setup guide (LinkedIn, Bluesky, Perplexity, and others) - each needs its own credential, so they are off by default."""
+
+
+def render_welcome() -> str:
+    """Return the first-run welcome text.
+
+    Owned by the engine (single source of truth) so the model relays it rather
+    than re-authoring it -- authored prose gets skipped, relayed command output
+    does not. Mirrors the SKILL.md welcome; keep in sync if the source set
+    changes.
+    """
+    return _WELCOME_TEXT
+
+
+# Neutral note recorded on an official-only host instead of a cookie scan.
+# Deliberately names no cookie mechanism beyond the fact that none is used
+# (the vocabulary rule for Grok Bot onboarding output).
+OFFICIAL_HOST_COOKIE_NOTE = "browser sessions are not read on this host"
+
+
 def run_auto_setup(config: Dict[str, Any], *, allow_browser_cookies: bool = False) -> Dict[str, Any]:
     """Perform the auto-setup actions.
 
@@ -40,6 +80,12 @@ def run_auto_setup(config: Dict[str, Any], *, allow_browser_cookies: bool = Fals
     Returns:
         Dict with keys:
           cookies_found: {source_name: browser_name} for each source where cookies were found
+          browser_cookie_scan_attempted: bool (True only after explicit consent
+              and at least one browser is eligible for extraction)
+          x_cookie_access_denied: browser names denied during an attempted X
+              cookie read when no other browser supplied a complete X pair
+          cookie_note: present only on an official-only host, where the scan
+              is skipped for every domain (neutral, relayable text)
           ytdlp_installed: bool
           ytdlp_action: already_installed | installed | install_failed | no_homebrew
           digg_installed: bool (True when the engine can resolve digg-pp-cli on PATH)
@@ -49,16 +95,35 @@ def run_auto_setup(config: Dict[str, Any], *, allow_browser_cookies: bool = Fals
           digg_stderr: present when digg_action is install_failed
           digg_path: present when digg_action is installed_off_path (binary on disk, not on PATH)
     """
-    from .env import COOKIE_DOMAINS, cookie_extraction_browsers
+    from .env import COOKIE_DOMAINS, cookie_extraction_browsers, x_policy
 
     cookies_found: Dict[str, str] = {}
+    access_denied: dict[str, set[str]] = {}
+    cookie_note: Optional[str] = None
+    browsers: list[str] = []
+
+    # Official-only host (LAST30DAYS_HOST=grok-bot): the consented
+    # cookie scan is skipped for EVERY domain (X and Truth Social alike) and
+    # recorded as not attempted, with a neutral note the caller can relay.
+    # The free CLI installs below still run. A LAST30DAYS_X_BACKEND=bird pin
+    # is the one path that re-enables discovery, via x_policy.
+    if allow_browser_cookies and not x_policy(config).cookie_discovery:
+        allow_browser_cookies = False
+        cookie_note = OFFICIAL_HOST_COOKIE_NOTE
 
     if allow_browser_cookies:
         from . import cookie_extract
 
         cookie_config = dict(config)
+        cookie_config["BROWSER_CONSENT"] = "true"
         if not (cookie_config.get("FROM_BROWSER") or "").strip():
-            cookie_config["FROM_BROWSER"] = "firefox,safari"
+            # Chromium-first avoids Safari's usual Full Disk Access prompt.
+            # Browser-data permissions can still deny Chromium DB reads before
+            # the Keychain step, so a failed scan must report that separately.
+            # firefox/safari stay as the silent fallbacks. Note: an explicit
+            # comma list preserves this order (cookie_extraction_browsers);
+            # "auto" would put the silent browsers first, so do not use it here.
+            cookie_config["FROM_BROWSER"] = "chrome,brave,edge,vivaldi,opera,arc,chromium,firefox,safari"
         browsers = cookie_extraction_browsers(cookie_config)
 
         for source_name, spec in COOKIE_DOMAINS.items():
@@ -68,18 +133,27 @@ def run_auto_setup(config: Dict[str, Any], *, allow_browser_cookies: bool = Fals
             for browser in browsers:
                 try:
                     result = cookie_extract.extract_cookies_with_source(browser, domain, cookie_names)
+                except PermissionError:
+                    access_denied.setdefault(source_name, set()).add(browser)
+                    continue
                 except Exception as exc:
                     logger.debug("Cookie extraction failed for %s via %s: %s", source_name, browser, exc)
                     continue
-                if result is not None and result[0]:
+                if result is not None and cookie_extract.has_complete_pair(result[0], cookie_names):
                     cookies_found[source_name] = result[1]
-                    break  # Found cookies for this service, stop trying browsers
+                    break  # Complete pair found for this service, stop trying browsers
 
-    # Check yt-dlp availability and install via Homebrew if missing
+    # Check yt-dlp availability and install via Homebrew if missing. Windows
+    # has no Homebrew, and its working install path is `pip install yt-dlp`
+    # (see #904), so it gets its own no-op-install guidance branch instead of
+    # falling into the Homebrew-oriented no_homebrew outcome.
     ytdlp_action: str
     if shutil.which("yt-dlp") is not None:
         ytdlp_installed = True
         ytdlp_action = "already_installed"
+    elif os.name == "nt":
+        ytdlp_installed = False
+        ytdlp_action = "no_pip_windows"
     elif shutil.which("brew") is not None:
         brew_stderr = ""
         try:
@@ -107,8 +181,14 @@ def run_auto_setup(config: Dict[str, Any], *, allow_browser_cookies: bool = Fals
     digg_installed, digg_action, digg_stderr, digg_path = _install_digg_cli()
     pp_sources = install_default_pp_sources()
 
+    scan_attempted = allow_browser_cookies and bool(browsers)
     results: Dict[str, Any] = {
         "cookies_found": cookies_found,
+        "x_cookie_access_denied": (
+            [browser for browser in browsers if browser in access_denied.get("x", set())]
+            if scan_attempted and "x" not in cookies_found else []
+        ),
+        "browser_cookie_scan_attempted": scan_attempted,
         "ytdlp_installed": ytdlp_installed,
         "ytdlp_action": ytdlp_action,
         "digg_installed": digg_installed,
@@ -116,8 +196,16 @@ def run_auto_setup(config: Dict[str, Any], *, allow_browser_cookies: bool = Fals
         # Per-CLI status for the additional default-on Printing Press sources
         # (arxiv, techmeme, trustpilot): {source: {installed, action, ...}}.
         "pp_sources": pp_sources,
+        # Reported, never installed: this CLI spends the user's own metered
+        # credits, so acquiring it stays their decision. Passing
+        # config matters: a user whose key lives in a .env file or the
+        # keychain (rather than a `brightdata login` credentials file) is
+        # active in the engine, and setup must not tell them otherwise.
+        "brightdata": brightdata_status(config),
         "env_written": False,
     }
+    if cookie_note:
+        results["cookie_note"] = cookie_note
     if ytdlp_action == "install_failed":
         results["ytdlp_stderr"] = brew_stderr
     if digg_action == "install_failed":
@@ -141,22 +229,22 @@ def _digg_bin_candidate_paths() -> list[Path]:
     """Known install locations for digg-pp-cli (Printing Press library defaults).
 
     Order: current installer default (~/.local/bin), legacy Go bins, Windows
-    managed dir. ``pipeline.available_sources()`` only activates Digg when
+    managed dir. The directory list is ``health.installer_bin_dirs()`` — the
+    shared single source — with the Digg filename variants appended (plain
+    name for Unix-style dirs, ``.exe`` in the Windows managed dir).
+    ``pipeline.available_sources()`` only activates Digg when
     ``shutil.which`` resolves on PATH — probing these dirs is for setup
     verification and honest off-PATH messaging, not engine activation.
     """
-    home = Path.home()
-    candidates: list[Path] = [home / ".local" / "bin" / DIGG_CLI_BIN]
-    gopath = os.environ.get("GOPATH")
-    if gopath:
-        candidates.append(Path(gopath) / "bin" / DIGG_CLI_BIN)
-    candidates.append(home / "go" / "bin" / DIGG_CLI_BIN)
-    if os.name == "nt":
-        local_app = os.environ.get("LOCALAPPDATA") or os.environ.get("LocalAppData")
-        if local_app:
-            candidates.append(
-                Path(local_app) / "Programs" / "PrintingPress" / "bin" / f"{DIGG_CLI_BIN}.exe"
-            )
+    from . import health
+
+    win_dir = health.windows_printing_press_bin_dir()
+    candidates: list[Path] = []
+    for directory in health.installer_bin_dirs():
+        if win_dir is not None and directory == win_dir:
+            candidates.append(directory / f"{DIGG_CLI_BIN}.exe")
+        else:
+            candidates.append(directory / DIGG_CLI_BIN)
     return candidates
 
 
@@ -189,6 +277,46 @@ def _digg_bin_dir_hint(digg_path: str) -> str:
     return parent
 
 
+def _run_npx_install(slug: str) -> Tuple[str, str]:
+    """Resolve ``npx`` and run the Printing Press catalog install for ``slug``.
+
+    Shared by ``_install_digg_cli`` and ``_install_pp_cli`` -- this is only the
+    "resolve npx, run the install, interpret no_npx/exception/nonzero-rc"
+    slice; each caller keeps its own on-path/off-path re-verification
+    (``_digg_bin_candidate_paths`` vs ``_pp_bin_candidate_paths`` already use
+    different candidate-directory sources, so merging them here would change
+    off-path detection behavior beyond this fix's scope).
+
+    Fixes the Windows PATHEXT mismatch: ``shutil.which("npx")`` resolves
+    ``npx.CMD`` via PATHEXT, but ``subprocess.run`` given the bare string
+    ``"npx"`` as argv[0] does not do that resolution and fails with
+    ``WinError 2``. Passing the resolved path is a no-op on macOS/Linux, where
+    ``shutil.which`` already returns the exact path ``CreateProcess``/``execve``
+    would resolve.
+
+    Returns ``(action, stderr)``: ``action`` is ``"no_npx"``,
+    ``"install_failed"``, or ``""`` when the subprocess ran and returned
+    ``rc=0`` (in which case ``stderr`` carries any non-fatal stderr output for
+    the caller's own off-path logging).
+    """
+    npx = shutil.which("npx")
+    if npx is None:
+        return "no_npx", ""
+    try:
+        proc = subprocess.run(
+            [npx, "-y", PRINTING_PRESS_NPM, "install", slug, "--cli-only"],
+            capture_output=True, text=True, timeout=DIGG_INSTALL_TIMEOUT,
+        )
+    except Exception as exc:
+        logger.warning("npx install %s exception: %s", slug, exc)
+        return "install_failed", str(exc)
+    if proc.returncode != 0:
+        stderr = proc.stderr or f"npx install {slug} exited {proc.returncode}"
+        logger.warning("npx install %s failed (rc=%s): %s", slug, proc.returncode, stderr)
+        return "install_failed", stderr
+    return "", (proc.stderr or "")
+
+
 def _install_digg_cli() -> Tuple[bool, str, str, str]:
     """Best-effort install of the digg-pp-cli binary.
 
@@ -210,32 +338,21 @@ def _install_digg_cli() -> Tuple[bool, str, str, str]:
     off_path = _digg_off_path_binary()
     if off_path:
         return False, "installed_off_path", "", off_path
-    if shutil.which("npx") is None:
-        return False, "no_npx", "", ""
-    try:
-        proc = subprocess.run(
-            ["npx", "-y", PRINTING_PRESS_NPM, "install", "digg", "--cli-only"],
-            capture_output=True, text=True, timeout=DIGG_INSTALL_TIMEOUT,
-        )
-    except Exception as exc:
-        logger.warning("npx install digg exception: %s", exc)
-        return False, "install_failed", str(exc), ""
-    if proc.returncode != 0:
-        stderr = proc.stderr or f"npx install digg exited {proc.returncode}"
-        logger.warning("npx install digg failed (rc=%s): %s", proc.returncode, stderr)
-        return False, "install_failed", stderr, ""
+    action, stderr = _run_npx_install("digg")
+    if action:
+        return False, action, stderr, ""
     on_path = _digg_on_path()
     if on_path:
         return True, "installed", "", ""
     off_path = _digg_off_path_binary()
     if off_path:
-        combined = (proc.stderr or "").strip()
+        combined = stderr.strip()
         if combined:
             logger.warning("digg-pp-cli installed off PATH: %s", combined)
         return False, "installed_off_path", combined, off_path
-    stderr = proc.stderr or "install completed but digg-pp-cli was not found"
-    logger.warning("npx install digg failed verification: %s", stderr)
-    return False, "install_failed", stderr, ""
+    stderr_msg = stderr or "install completed but digg-pp-cli was not found"
+    logger.warning("npx install digg failed verification: %s", stderr_msg)
+    return False, "install_failed", stderr_msg, ""
 
 
 # Additional default-on Printing Press sources installed the same way as Digg:
@@ -250,6 +367,85 @@ PP_DEFAULT_SOURCES: list[tuple[str, str, str]] = [
     ("techmeme", "techmeme", "techmeme-pp-cli"),
 ]
 
+# Bright Data is deliberately absent from PP_DEFAULT_SOURCES: it is not a
+# Printing Press CLI, it is opt-in like Trustpilot, and it spends the user's
+# own metered credits. Setup reports its state and never installs it.
+BRIGHTDATA_BIN = "brightdata"
+
+
+def _brightdata_off_path_binary() -> Optional[str]:
+    """Locate a brightdata binary that exists on disk but not on PATH.
+
+    Covers the common npm global prefixes. The distinction matters because
+    Hermes and OpenClaw gateways routinely run the engine with a PATH that
+    excludes the user's npm bin directory, so "installed" and "the engine
+    can see it" are different questions.
+    """
+    home = Path.home()
+    candidates = [
+        home / ".local" / "bin" / BRIGHTDATA_BIN,
+        home / ".npm-global" / "bin" / BRIGHTDATA_BIN,
+        Path("/opt/homebrew/bin") / BRIGHTDATA_BIN,
+        Path("/usr/local/bin") / BRIGHTDATA_BIN,
+    ]
+    npm_prefix = os.environ.get("NPM_CONFIG_PREFIX")
+    if npm_prefix:
+        candidates.insert(0, Path(npm_prefix) / "bin" / BRIGHTDATA_BIN)
+    for candidate in candidates:
+        try:
+            if candidate.is_file() and os.access(candidate, os.X_OK):
+                return str(candidate)
+        except OSError:
+            continue
+    return None
+
+
+def brightdata_status(config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """Report the Bright Data install and auth state honestly.
+
+    Deliberately never claims the source is active unless the engine's own
+    gate would pass -- ``brightdata.is_available`` is the single predicate,
+    so setup and the engine cannot drift apart. Three states matter:
+
+    * ``already_installed``  -- on PATH; ``authenticated`` says whether the
+      amazon lane will actually run.
+    * ``installed_off_path`` -- on disk but invisible to the engine, which
+      is the Hermes/OpenClaw failure mode. Carries the path so the user can
+      fix their PATH.
+    * ``not_installed``      -- nothing found. No auto-install: this CLI
+      spends the user's metered credits, so acquiring it is their call.
+    """
+    installed = brightdata.is_installed()
+    authenticated = brightdata.has_credentials(config)
+    if installed:
+        action = "already_installed"
+        off_path = ""
+    else:
+        off_path = _brightdata_off_path_binary() or ""
+        action = "installed_off_path" if off_path else "not_installed"
+
+    status: Dict[str, Any] = {
+        "installed": installed,
+        "action": action,
+        "authenticated": installed and authenticated,
+        # The engine gate, verbatim. Never report active on anything else.
+        "engine_active": brightdata.is_available(config),
+    }
+    if off_path:
+        status["path"] = off_path
+        status["hint"] = (
+            f"brightdata found at {off_path} but not on PATH; add its directory "
+            "to PATH so the engine subprocess can see it"
+        )
+    elif installed and not authenticated:
+        status["hint"] = "run `brightdata login` to activate the amazon source"
+    elif not installed:
+        status["hint"] = (
+            "install with `npm i -g @brightdata/cli` then `brightdata login` "
+            "to enable the amazon source"
+        )
+    return status
+
 
 def _pp_bin_candidate_paths(bin_name: str) -> list[Path]:
     """Known install locations for a Printing Press CLI binary (slug-parameterized
@@ -291,32 +487,21 @@ def _install_pp_cli(slug: str, bin_name: str) -> Tuple[bool, str, str, str]:
     off_path = _pp_off_path_binary(bin_name)
     if off_path:
         return False, "installed_off_path", "", off_path
-    if shutil.which("npx") is None:
-        return False, "no_npx", "", ""
-    try:
-        proc = subprocess.run(
-            ["npx", "-y", PRINTING_PRESS_NPM, "install", slug, "--cli-only"],
-            capture_output=True, text=True, timeout=DIGG_INSTALL_TIMEOUT,
-        )
-    except Exception as exc:
-        logger.warning("npx install %s exception: %s", slug, exc)
-        return False, "install_failed", str(exc), ""
-    if proc.returncode != 0:
-        stderr = proc.stderr or f"npx install {slug} exited {proc.returncode}"
-        logger.warning("npx install %s failed (rc=%s): %s", slug, proc.returncode, stderr)
-        return False, "install_failed", stderr, ""
+    action, stderr = _run_npx_install(slug)
+    if action:
+        return False, action, stderr, ""
     on_path = shutil.which(bin_name)
     if on_path:
         return True, "installed", "", ""
     off_path = _pp_off_path_binary(bin_name)
     if off_path:
-        combined = (proc.stderr or "").strip()
+        combined = stderr.strip()
         if combined:
             logger.warning("%s installed off PATH: %s", bin_name, combined)
         return False, "installed_off_path", combined, off_path
-    stderr = proc.stderr or f"install completed but {bin_name} was not found"
-    logger.warning("npx install %s failed verification: %s", slug, stderr)
-    return False, "install_failed", stderr, ""
+    stderr_msg = stderr or f"install completed but {bin_name} was not found"
+    logger.warning("npx install %s failed verification: %s", slug, stderr_msg)
+    return False, "install_failed", stderr_msg, ""
 
 
 def install_default_pp_sources() -> Dict[str, Dict[str, Any]]:
@@ -355,6 +540,58 @@ def _open_secret_append(path: Path):
     return os.fdopen(fd, "a", encoding="utf-8")
 
 
+def _env_line_key(stripped: str) -> str:
+    """Return the key a stripped ``KEY=value`` line sets, as the loader reads it."""
+    from . import env as _env
+
+    return _env.env_line_key(stripped.split("=", 1)[0])
+
+
+def _replace_env_line(env_path: Path, content: str, key_name: str, value: str) -> bool:
+    """Rewrite every ``key_name=`` line of ``content`` with ``value`` as a 0o600 secret.
+
+    The new file is written to a sibling temp path opened at 0o600 and moved
+    over the original, so the secret never has a readable window and a
+    crash mid-write leaves the old file intact.
+    """
+    def _is_key(stripped: str) -> bool:
+        return bool(
+            stripped and not stripped.startswith("#") and "=" in stripped
+            and _env_line_key(stripped) == key_name
+        )
+
+    stripped_lines = [line.strip() for line in content.splitlines()]
+    # Keep a hand-written ``export`` -- on any of the duplicates being
+    # collapsed -- so a shell that sources the file still exports the key.
+    exported = any(
+        _is_key(s) and s.split("=", 1)[0].strip() != key_name for s in stripped_lines
+    )
+    new_line = f"{key_name}={_format_env_value(value)}"
+    if exported:
+        new_line = f"export {new_line}"
+    lines = []
+    replaced = False
+    for line, stripped in zip(content.splitlines(), stripped_lines):
+        if _is_key(stripped):
+            if not replaced:
+                lines.append(new_line)
+                replaced = True
+            continue
+        lines.append(line)
+    if not replaced:
+        lines.append(new_line)
+    tmp_path = env_path.with_name(env_path.name + ".tmp")
+    fd = os.open(tmp_path, os.O_CREAT | os.O_WRONLY | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        f.write("\n".join(lines) + "\n")
+    os.replace(tmp_path, env_path)
+    try:
+        os.chmod(env_path, 0o600)
+    except OSError:
+        pass
+    return True
+
+
 def _format_env_value(value: str) -> str:
     """Quote a value so it round-trips through env.load_env_file.
 
@@ -378,20 +615,30 @@ def _format_env_value(value: str) -> str:
     return value
 
 
-def write_setup_config(env_path: Path, from_browser: str | None = None) -> bool:
-    """Write SETUP_COMPLETE and FROM_BROWSER to the .env file.
+def write_setup_config(
+    env_path: Path,
+    from_browser: str | None = None,
+    *,
+    browser_consent: bool | None = None,
+    x_cookie_access_denied: str | None = None,
+) -> bool:
+    """Write setup completion, browser selection, and consent to the .env file.
 
     Creates the file and parent directories if needed.
-    Appends to existing file without overwriting existing keys.
+    Appends without overwriting existing keys, except for an explicit consent
+    decision.
 
     Args:
         env_path: Path to the .env file (e.g. ~/.config/last30days/.env)
-        from_browser: Browser extraction mode to persist. Pass the browser that
-            actually yielded cookies (e.g. "firefox") to fast-path future runs.
-            Pass None (default) to NOT pin FROM_BROWSER — the steady-state
-            default (Firefox/Safari, no Keychain prompt) then applies. We avoid
-            persisting "auto" because it makes every later run probe Chrome and
-            re-trigger the Keychain prompt.
+        from_browser: Browser or comma-separated browser list that actually
+            yielded cookies after consent (e.g. "chrome,firefox"). Pass None
+            (default) to leave FROM_BROWSER unchanged; when unset, future runs
+            do not read native browser stores. Avoid "auto", which would also probe
+            browsers that did not supply cookies during setup.
+        browser_consent: Record the user's current cookie-access decision.
+            None preserves any previous decision.
+        x_cookie_access_denied: Setup's non-secret last X denial observation.
+            Pass "none" to clear a prior denial after a new setup run.
 
     Returns:
         True if config was written successfully, False on error.
@@ -399,6 +646,18 @@ def write_setup_config(env_path: Path, from_browser: str | None = None) -> bool:
     try:
         env_path = Path(env_path)
         env_path.parent.mkdir(parents=True, exist_ok=True)
+        if browser_consent is not None:
+            if not write_api_key(
+                env_path, "true" if browser_consent else "false",
+                key_name="BROWSER_CONSENT", replace=True,
+            ):
+                return False
+        if x_cookie_access_denied is not None:
+            if not write_api_key(
+                env_path, x_cookie_access_denied,
+                key_name="LAST30DAYS_X_COOKIE_ACCESS_DENIED", replace=True,
+            ):
+                return False
 
         # Read existing content to avoid overwriting keys
         existing_keys: set = set()
@@ -408,7 +667,7 @@ def write_setup_config(env_path: Path, from_browser: str | None = None) -> bool:
             for line in existing_content.splitlines():
                 stripped = line.strip()
                 if stripped and not stripped.startswith("#") and "=" in stripped:
-                    key = stripped.split("=", 1)[0].strip()
+                    key = _env_line_key(stripped)
                     existing_keys.add(key)
 
         lines_to_add = []
@@ -434,19 +693,28 @@ def write_setup_config(env_path: Path, from_browser: str | None = None) -> bool:
         return False
 
 
-def write_api_key(env_path: Path, api_key: str, key_name: str = "SCRAPECREATORS_API_KEY") -> bool:
+def write_api_key(
+    env_path: Path,
+    api_key: str,
+    key_name: str = "SCRAPECREATORS_API_KEY",
+    *,
+    replace: bool = False,
+) -> bool:
     """Append an API key to the .env file as a 0o600 secret.
 
     Reuses the same secret-safe write path as ``write_setup_config`` so the
     value lands with restrictive permissions and round-trips through
-    ``env.load_env_file``. Idempotent: if ``key_name`` is already present in
-    the file, nothing is written and the existing value is preserved (we never
-    clobber a key the user may have set by hand).
+    ``env.load_env_file``. Idempotent by default: if ``key_name`` is already
+    present in the file, nothing is written and the existing value is
+    preserved (we never clobber a key the user may have set by hand). With
+    ``replace=True`` an existing line is rewritten in place instead, so an
+    explicit ``setup --store-key`` can rotate a rejected credential.
 
     Args:
         env_path: Path to the .env file (e.g. ~/.config/last30days/.env).
         api_key: The raw key value to persist.
         key_name: The env var name to write (default SCRAPECREATORS_API_KEY).
+        replace: Rewrite an existing ``key_name`` line instead of keeping it.
 
     Returns:
         True if the key was written or already present, False on error or when
@@ -464,7 +732,9 @@ def write_api_key(env_path: Path, api_key: str, key_name: str = "SCRAPECREATORS_
             for line in existing_content.splitlines():
                 stripped = line.strip()
                 if stripped and not stripped.startswith("#") and "=" in stripped:
-                    if stripped.split("=", 1)[0].strip() == key_name:
+                    if _env_line_key(stripped) == key_name:
+                        if replace:
+                            return _replace_env_line(env_path, existing_content, key_name, api_key)
                         return True  # Already configured; do not duplicate
 
         line = f"{key_name}={_format_env_value(api_key)}\n"
@@ -500,16 +770,25 @@ def get_setup_status_text(results: Dict[str, Any]) -> str:
     Returns:
         Multi-line status text.
     """
+    from .env import X_COOKIE_ACCESS_FIX
+
     lines = []
     lines.append("Setup complete! Here's what I found:")
     lines.append("")
 
     cookies_found = results.get("cookies_found", {})
-    if cookies_found:
+    if results.get("browser_cookie_scan_attempted") and cookies_found:
         for source, browser in cookies_found.items():
             lines.append(f"  - {source.upper()} cookies found in {browser}")
-    else:
-        lines.append("  - No browser cookies found for X/Twitter")
+    denied_browsers = (
+        results.get("x_cookie_access_denied") or []
+        if results.get("browser_cookie_scan_attempted") else []
+    )
+    if denied_browsers:
+        lines.append(
+            "  - X cookie access was permission denied in "
+            f"{', '.join(denied_browsers)}. {X_COOKIE_ACCESS_FIX}"
+        )
 
     ytdlp_action = results.get("ytdlp_action", "")
     if ytdlp_action == "installed":
@@ -518,6 +797,11 @@ def get_setup_status_text(results: Dict[str, Any]) -> str:
         lines.append("  - yt-dlp install failed \u2014 run `brew install yt-dlp` manually")
     elif ytdlp_action == "no_homebrew":
         lines.append("  - yt-dlp not found. Install Homebrew first, then: brew install yt-dlp")
+    elif ytdlp_action == "no_pip_windows":
+        lines.append(
+            "  - yt-dlp not found. Install with: pip install yt-dlp "
+            "(it may install to a Scripts directory not on PATH -- add it to PATH if YouTube search stays inactive)"
+        )
     elif ytdlp_action == "already_installed":
         lines.append("  - yt-dlp already installed")
     elif results.get("ytdlp_installed", False):
@@ -553,10 +837,82 @@ def get_setup_status_text(results: Dict[str, Any]) -> str:
             f"{DIGG_INSTALL_CMD}"
         )
 
+    pp_sources = results.get("pp_sources", {})
+    pp_name: dict[str, str] = {"arxiv": "arXiv", "techmeme": "Techmeme"}
+    for source_key, entry in sorted(pp_sources.items()):
+        name = pp_name.get(source_key, source_key.title())
+        action = entry.get("action", "")
+        if action == "installed":
+            lines.append(f"  - Installed {name} CLI ({name} source now active)")
+        elif action == "already_installed":
+            lines.append(f"  - {name} CLI already installed ({name} active)")
+        elif action == "installed_off_path":
+            path = entry.get("path", "")
+            if path:
+                lines.append(
+                    f"  - {name} CLI at {path} but not on PATH — add "
+                    f"{os.path.dirname(os.path.expanduser(path))} to PATH and "
+                    f"restart your agent session/gateway for {name} to activate"
+                )
+            else:
+                lines.append(
+                    f"  - {name} CLI installed but not on PATH — add its install "
+                    "directory to PATH and restart your agent session/gateway for "
+                    f"{name} to activate"
+                )
+        elif action == "install_failed":
+            lines.append(
+                f"  - {name} CLI install failed — run "
+                f"`npx -y {PRINTING_PRESS_NPM} install {source_key} --cli-only` manually"
+            )
+        elif action == "no_npx":
+            lines.append(
+                f"  - {name} CLI not installed (free, optional). Install Node/npx, "
+                f"then: `npx -y {PRINTING_PRESS_NPM} install {source_key} --cli-only`"
+            )
+
+    # Bright Data / Amazon. Reported but never installed (it spends the user's
+    # own metered credits), so the only useful thing setup can do is say
+    # precisely why the lane is or is not active -- the three states below are
+    # otherwise invisible, since SKILL.md tells the model not to raise the
+    # subject mid-run.
+    brightdata_status_entry = results.get("brightdata") or {}
+    bd_action = brightdata_status_entry.get("action", "")
+    if brightdata_status_entry.get("engine_active"):
+        lines.append("  - Bright Data CLI ready (Amazon buyer signals available)")
+    elif bd_action == "already_installed":
+        lines.append(
+            "  - Bright Data CLI installed but not logged in — run "
+            "`brightdata login` to enable Amazon buyer signals (optional)"
+        )
+    elif bd_action == "installed_off_path":
+        bd_path = brightdata_status_entry.get("path", "")
+        lines.append(
+            f"  - Bright Data CLI found at {bd_path} but not on PATH — add "
+            f"{os.path.dirname(os.path.expanduser(bd_path))} to PATH and restart "
+            "your agent session/gateway for Amazon buyer signals to activate"
+        )
+    elif bd_action == "not_installed":
+        lines.append(
+            "  - Amazon buyer signals not installed (optional; 5,000 free "
+            "requests/month). Install with: npm i -g @brightdata/cli && brightdata login"
+        )
+
+    cookie_note = results.get("cookie_note")
+    if cookie_note:
+        # Official-only host: relay the neutral note; say nothing about
+        # browsers. The scan was not attempted, so nothing is "found".
+        lines.append(f"  - {cookie_note}")
+
     env_written = results.get("env_written", False)
     if env_written:
         lines.append("")
-        lines.append("Configuration saved. Future runs will auto-detect your browsers.")
+        if cookie_note:
+            lines.append("Configuration saved.")
+        elif denied_browsers:
+            lines.append("Configuration saved. X browser cookie access remains unverified.")
+        else:
+            lines.append("Configuration saved. Future runs will auto-detect your browsers.")
 
     return "\n".join(lines)
 
@@ -625,6 +981,39 @@ def run_openclaw_setup(config: Dict[str, Any]) -> Dict[str, Any]:
 
 _DEVICE_BASE = "https://api.scrapecreators.com/v1/github/device"
 
+# A GitHub device code is always XXXX-XXXX (uppercase alphanumerics). We validate
+# user_code against this before copying, labeling, or emitting it so a malformed
+# or key-shaped value (e.g. a returning-account server response) is never
+# mislabeled as a device code or leaked to stdout/clipboard.
+_DEVICE_CODE_RE = re.compile(r"^[0-9A-Z]{4}-[0-9A-Z]{4}$")
+
+
+def _existing_scrapecreators_key() -> Optional[str]:
+    """Return the SCRAPECREATORS_API_KEY already saved in the .env, if any."""
+    try:
+        from . import env as _env
+
+        if _env.CONFIG_FILE and _env.CONFIG_FILE.exists():
+            return _env.load_env_file(_env.CONFIG_FILE).get("SCRAPECREATORS_API_KEY") or None
+    except Exception as exc:  # never let a config-read failure block auth
+        logger.debug("Could not read existing ScrapeCreators key: %s", exc)
+    return None
+
+
+def _clamp_device_interval(interval: Any) -> int:
+    """Clamp a server-provided device-flow poll interval to [1, 30] seconds.
+
+    The ``interval`` comes from the server (device/code response or the
+    persisted poll handle), so 0 would hot-loop ``time.sleep``, a negative
+    would crash it, a huge value would sail past the poll timeout, and a
+    non-numeric value would raise. Defaults to 5 on missing/garbled input.
+    """
+    try:
+        value = int(interval or 5)
+    except (TypeError, ValueError):
+        return 5
+    return min(max(value, 1), 30)
+
 
 def run_device_auth() -> Optional[Tuple[str, str, str, int]]:
     """Start the device authorization flow.
@@ -648,10 +1037,14 @@ def run_device_auth() -> Optional[Tuple[str, str, str, int]]:
     device_code = data.get("device_code")
     user_code = data.get("user_code")
     verification_uri = data.get("verification_uri")
-    interval = data.get("interval", 5)
+    interval = _clamp_device_interval(data.get("interval", 5))
 
     if not device_code or not user_code:
-        logger.warning("Device auth returned incomplete response: %s", data)
+        # Log only the response's key names, never its values — a returning
+        # account's response could carry a raw API key we must not write to logs.
+        logger.warning(
+            "Device auth returned incomplete response (keys: %s)", sorted(data.keys())
+        )
         return None
 
     return (device_code, user_code, verification_uri or "", interval)
@@ -678,6 +1071,7 @@ def poll_device_auth(
     """
     import sys
 
+    interval = _clamp_device_interval(interval)
     started_at = time.time()
     deadline = started_at + timeout
     last_reminder = started_at
@@ -733,62 +1127,211 @@ def poll_device_auth(
     return None
 
 
-def fetch_api_key(access_token: str) -> Optional[str]:
+# Bounded retries for transient ScrapeCreators /profile 5xx (see #882).
+_PROFILE_FETCH_ATTEMPTS = 3
+_PROFILE_FETCH_RETRY_SLEEP_S = 1.0
+_PROFILE_ERROR_BODY_LIMIT = 200
+
+
+def _http_error_detail(exc: HTTPError, *, body_limit: int = _PROFILE_ERROR_BODY_LIMIT) -> str:
+    """Build a diagnosable HTTPError string including a truncated body.
+
+    The body is capped and never treated as a secret source of truth; callers
+    still must not log bearer tokens. Used so a 5xx is not a black box.
+    """
+    base = f"HTTP Error {exc.code}: {getattr(exc, 'reason', '') or ''}".rstrip(": ")
+    try:
+        raw = exc.read() or b""
+    except Exception:
+        return base
+    if not raw:
+        return base
+    text = raw.decode("utf-8", errors="replace").strip()
+    if not text:
+        return base
+    if len(text) > body_limit:
+        text = text[:body_limit] + "…"
+    return f"{base} body={text!r}"
+
+
+def fetch_api_key(access_token: str) -> Dict[str, Any]:
     """Fetch the ScrapeCreators API key using the GitHub access token.
 
-    GETs the device/profile endpoint with Bearer auth.
+    GETs the device/profile endpoint with Bearer auth. Distinguishes outcomes
+    so callers (and SKILL.md) do not collapse a server 5xx into the
+    already-linked guidance (#882).
+
+    Returns a result dict:
+      - ``{"ok": True, "api_key": str}`` on success
+      - ``{"ok": False, "reason": "no_api_key"}`` when /profile is 2xx but has
+        no ``api_key`` field (typical already-linked account)
+      - ``{"ok": False, "reason": "upstream_error", "http_status": int,
+        "detail": str}`` on 5xx after bounded retries
+      - ``{"ok": False, "reason": "http_error", "http_status": int,
+        "detail": str}`` on other HTTP errors (e.g. 401)
+      - ``{"ok": False, "reason": "request_failed", "detail": str}`` on
+        network/OS failures
+    """
+    data: Optional[Dict[str, Any]] = None
+    last_upstream: Optional[Dict[str, Any]] = None
 
-    Returns:
-        api_key string on success, None on failure.
+    for attempt in range(_PROFILE_FETCH_ATTEMPTS):
+        try:
+            req = Request(f"{_DEVICE_BASE}/profile")
+            req.add_header("Authorization", f"Bearer {access_token}")
+            with urlopen(req, timeout=15) as resp:
+                data = json.loads(resp.read())
+            break
+        except HTTPError as exc:
+            detail = _http_error_detail(exc)
+            if 500 <= int(exc.code) <= 599:
+                logger.warning(
+                    "Device auth /profile upstream error (attempt %s/%s): %s",
+                    attempt + 1,
+                    _PROFILE_FETCH_ATTEMPTS,
+                    detail,
+                )
+                last_upstream = {
+                    "ok": False,
+                    "reason": "upstream_error",
+                    "http_status": int(exc.code),
+                    "detail": detail,
+                }
+                if attempt + 1 < _PROFILE_FETCH_ATTEMPTS:
+                    time.sleep(_PROFILE_FETCH_RETRY_SLEEP_S)
+                    continue
+                return last_upstream
+            logger.warning("Failed to fetch API key: %s", detail)
+            return {
+                "ok": False,
+                "reason": "http_error",
+                "http_status": int(exc.code),
+                "detail": detail,
+            }
+        except (URLError, OSError) as exc:
+            logger.warning("Failed to fetch API key: %s", exc)
+            return {"ok": False, "reason": "request_failed", "detail": str(exc)}
+
+    if data is None:
+        # Defensive: loop exited without success or an explicit return.
+        return last_upstream or {
+            "ok": False,
+            "reason": "request_failed",
+            "detail": "No profile response",
+        }
+
+    api_key = data.get("api_key")
+    if not api_key:
+        # The /profile response parsed but carried no api_key — the common case
+        # for a GitHub account already linked to a ScrapeCreators account. Log
+        # the response's FIELD NAMES only (never values — the body may contain a
+        # key under a different field) so the already-registered response shape
+        # can be handled in a follow-up (see plan OQ1).
+        logger.warning(
+            "Device auth /profile returned no api_key (fields: %s)", sorted(data.keys())
+        )
+        return {"ok": False, "reason": "no_api_key"}
+    return {"ok": True, "api_key": api_key}
+
+
+def _device_handle_path() -> Path:
+    """Where run_github_start persists the device_code/interval for run_github_poll.
+
+    Kept next to the .env in the config dir; falls back to the OS temp dir when
+    no config dir is resolvable (clean/no-config mode).
     """
     try:
-        req = Request(f"{_DEVICE_BASE}/profile")
-        req.add_header("Authorization", f"Bearer {access_token}")
-        with urlopen(req, timeout=15) as resp:
-            data = json.loads(resp.read())
-    except (HTTPError, URLError, OSError) as exc:
-        logger.warning("Failed to fetch API key: %s", exc)
-        return None
+        from . import env as _env
 
-    return data.get("api_key")
+        if _env.CONFIG_FILE:
+            return _env.CONFIG_FILE.parent / ".github-device-handle.json"
+    except Exception:
+        pass
+    import tempfile
 
+    return Path(tempfile.gettempdir()) / "last30days-github-device-handle.json"
 
-def run_full_device_auth(timeout: int = 300) -> Dict[str, Any]:
-    """Run the complete GitHub device auth flow and return JSON-serializable result.
 
-    Chains: start device flow -> open browser -> poll -> fetch API key.
-    Designed to be called from the CLI and have its stdout parsed by the LLM.
+def _start_device_flow() -> "Tuple[Dict[str, Any], Optional[Dict[str, Any]]]":
+    """Submit the GitHub device flow and surface the code, without polling.
 
-    Returns:
-        Dict with status and relevant fields:
-        - {"status": "success", "api_key": "sc_...", "user_code": "ABCD-1234"}
-        - {"status": "error", "message": "..."}
-        - {"status": "timeout", "user_code": "ABCD-1234"}
-        - {"status": "denied"}
+    Returns ``(public_result, handle)``. ``handle`` is None for the
+    already-registered and error cases (nothing to poll); otherwise it carries
+    the private poll state (``device_code``/``interval``/``user_code``/
+    ``clipboard_ok``) that never belongs in the public, stdout-printed result.
+    Callers either persist the handle to a file (``run_github_start``, for a
+    separate poll process) or hand it straight to ``run_github_poll`` in-memory
+    (``run_full_device_auth``, so a failed file write can't strand the one-shot).
     """
+    import sys
     import webbrowser
 
-    # Step 1: Start device flow
+    # Already-registered short-circuit: a saved key means no device dance. The
+    # key is returned raw here and masked at the CLI boundary before print.
+    existing = _existing_scrapecreators_key()
+    if existing:
+        return (
+            {
+                "status": "already_registered",
+                "method": "existing",
+                "api_key": existing,
+                "persisted": True,
+            },
+            None,
+        )
+
     result = run_device_auth()
     if result is None:
-        return {"status": "error", "message": "Failed to start device auth flow"}
+        return ({"status": "error", "message": "Failed to start device auth flow"}, None)
 
     device_code, user_code, verification_uri, interval = result
 
-    import sys
+    # Validate the code shape BEFORE copying, labeling, or emitting it. A
+    # non-conforming user_code (e.g. a key-shaped value) is never surfaced as a
+    # GitHub device code; we stop rather than instruct the user to paste garbage.
+    if not _DEVICE_CODE_RE.match(user_code):
+        logger.warning("Device auth returned a non-device-shaped user_code; aborting.")
+        return (
+            {
+                "status": "error",
+                "message": "ScrapeCreators returned an unexpected device-code format.",
+            },
+            None,
+        )
+
+    # Structured stdout line for machine consumers.
+    print(
+        json.dumps(
+            {
+                "event": "device_code_ready",
+                "user_code": user_code,
+                "verification_uri": verification_uri,
+            }
+        ),
+        flush=True,
+    )
 
-    # Step 2: Copy code to clipboard BEFORE opening browser
+    # Copy the code to the clipboard BEFORE opening the browser.
     clipboard_ok = False
     if sys.platform == "darwin":
         try:
-            subprocess.run(
-                ["pbcopy"], input=user_code.encode(), check=True, timeout=5,
-            )
+            subprocess.run(["pbcopy"], input=user_code.encode(), check=True, timeout=5)
             clipboard_ok = True
         except Exception:
             pass  # pbcopy unavailable or failed, fall through
 
-    # Step 3: Show code prominently, then open browser
+    # Print the code as a plain HUMAN line on stdout too, so a foreground caller
+    # sees it in the returned output even without reading the JSON. The clipboard
+    # claim is only made when pbcopy actually succeeded (else: type it).
+    if clipboard_ok:
+        print(
+            f"Your GitHub code: {user_code}  (already on your clipboard - just paste it, Cmd+V)",
+            flush=True,
+        )
+    else:
+        print(f"Your GitHub code: {user_code}  (type it on the GitHub page)", flush=True)
+
+    # Human box on stderr for direct-terminal users.
     clipboard_hint = "  (copied to clipboard)" if clipboard_ok else ""
     code_line = f"  Your code: {user_code}{clipboard_hint}"
     action_line = "  Paste it on the GitHub page that just opened"
@@ -805,26 +1348,143 @@ def run_full_device_auth(timeout: int = 300) -> Dict[str, Any]:
         except Exception:
             print(f"Open: {verification_uri}", file=sys.stderr)
 
-    print("Waiting for authorization...", file=sys.stderr, flush=True)
+    public = {
+        "status": "awaiting_authorization",
+        "user_code": user_code,
+        "verification_uri": verification_uri,
+        "clipboard_ok": clipboard_ok,
+    }
+    handle = {
+        "device_code": device_code,
+        "interval": interval,
+        "user_code": user_code,
+        "clipboard_ok": clipboard_ok,
+    }
+    return (public, handle)
+
+
+def run_github_start() -> Dict[str, Any]:
+    """Start the device flow and persist the poll handle for a later
+    ``run_github_poll`` process. Returns the public result (never the private
+    device_code). See ``_start_device_flow`` for the returned statuses."""
+    public, handle = _start_device_flow()
+    if handle is not None:
+        # Persist the poll handle (0o600) so a separate --github-poll process can
+        # resume it. Best-effort: the in-memory one-shot path does not depend on
+        # this write succeeding.
+        path = _device_handle_path()
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            write_private_text(path, json.dumps(handle), encoding="utf-8")
+            if os.name != "posix":
+                os.chmod(path, 0o600)
+        except Exception as exc:
+            logger.warning("Could not persist device handle: %s", exc)
+    return public
+
+
+def run_github_poll(timeout: int = 300, *, _handle: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """Poll for authorization using the handle from start.
+
+    ``_handle`` (in-memory, from the one-shot) takes precedence over the
+    persisted handle file. Returns success (with the fetched key), timeout, or
+    the honest "Authorized but failed to fetch API key" branch. Deletes the
+    persisted handle when the flow terminates.
+    """
+    import sys
 
-    # Step 4: Poll for token (with periodic code reminders)
+    if _handle is not None:
+        data = _handle
+    else:
+        try:
+            data = json.loads(_device_handle_path().read_text(encoding="utf-8"))
+        except Exception:
+            return {
+                "status": "error",
+                "message": "No pending GitHub device flow; run setup --github-start first.",
+            }
+
+    device_code = data["device_code"]
+    interval = _clamp_device_interval(data.get("interval", 5))
+    user_code = data.get("user_code", "")
+    # Read the real clipboard state so the polling reminder never falsely claims
+    # the code is on the clipboard (non-macOS, or a failed pbcopy). Missing key
+    # (older handle) defaults to False -- don't overstate.
+    clipboard_ok = bool(data.get("clipboard_ok", False))
+
+    print("Waiting for authorization...", file=sys.stderr, flush=True)
     access_token = poll_device_auth(
-        device_code, interval, timeout=timeout,
-        user_code=user_code, clipboard_ok=clipboard_ok,
+        device_code, interval, timeout=timeout, user_code=user_code, clipboard_ok=clipboard_ok
     )
+
+    def _cleanup() -> None:
+        try:
+            _device_handle_path().unlink()
+        except Exception:
+            pass
+
     if access_token is None:
-        return {"status": "timeout", "user_code": user_code, "clipboard_ok": clipboard_ok}
+        _cleanup()
+        return {"status": "timeout", "user_code": user_code}
+
+    fetched = fetch_api_key(access_token)
+    _cleanup()
+    if fetched.get("ok") and fetched.get("api_key"):
+        return {
+            "status": "success",
+            "method": "device",
+            "api_key": fetched["api_key"],
+            "user_code": user_code,
+        }
 
-    # Step 4: Fetch API key
-    api_key = fetch_api_key(access_token)
-    if api_key is None:
+    # Discriminate failure modes so SKILL.md does not misdiagnose a 5xx as
+    # "GitHub already linked" (#882). Keep the historical message only for the
+    # 2xx-without-api_key / already-linked case.
+    reason = fetched.get("reason") or "request_failed"
+    if reason == "no_api_key":
         return {
             "status": "error",
             "message": "Authorized but failed to fetch API key",
-            "clipboard_ok": clipboard_ok,
+            "reason": "no_api_key",
         }
+    if reason == "upstream_error":
+        http_status = fetched.get("http_status")
+        return {
+            "status": "error",
+            "message": f"Authorized but ScrapeCreators profile failed (HTTP {http_status})",
+            "reason": "upstream_error",
+            "http_status": http_status,
+            "detail": fetched.get("detail"),
+        }
+    if reason == "http_error":
+        http_status = fetched.get("http_status")
+        return {
+            "status": "error",
+            "message": f"Authorized but failed to fetch API key (HTTP {http_status})",
+            "reason": "http_error",
+            "http_status": http_status,
+            "detail": fetched.get("detail"),
+        }
+    return {
+        "status": "error",
+        "message": "Authorized but failed to fetch API key",
+        "reason": reason,
+        "detail": fetched.get("detail"),
+    }
+
+
+def run_full_device_auth(timeout: int = 300) -> Dict[str, Any]:
+    """Back-compat one-shot: start the device flow, then poll to completion.
 
-    return {"status": "success", "method": "device", "api_key": api_key, "user_code": user_code, "clipboard_ok": clipboard_ok}
+    Passes the poll handle to ``run_github_poll`` IN MEMORY, so a failed handle-
+    file write can't strand the one-shot. Kept so callers of ``setup --github`` /
+    ``--device-auth`` still work; the model-driven wizard uses the two-command
+    split (start then poll) instead.
+    """
+    public, handle = _start_device_flow()
+    if handle is None:
+        return public  # already_registered or error
+    return run_github_poll(timeout=timeout, _handle=handle)
 
 
 # ---------------------------------------------------------------------------
@@ -833,11 +1493,10 @@ def run_full_device_auth(timeout: int = 300) -> Dict[str, Any]:
 
 
 def run_github_auth(timeout: int = 300) -> Dict[str, Any]:
-    """Run the --github setup path via device auth only.
-
-    Kept as the semantic entry point for GitHub-backed setup; this path must
-    not read or forward local GitHub CLI tokens.
+    """Run the --github setup path via device auth (one-shot, back-compat).
 
-    Returns JSON-serializable dict with status, method, and api_key.
+    The existing-key short-circuit now lives in run_github_start; this delegates
+    to the start+poll chain. This path must not read or forward local GitHub CLI
+    tokens.
     """
     return run_full_device_auth(timeout=timeout)