Skip to content

AI agent skill that researches any topic across Reddit, X, YouTube, HN, Polymarket, and the web - then synthesizes a grounded summary

49.1 KB
Raw Blame
"""U2: backend-chain descriptors with predicted selection (lib/backends.py).

Chained sources declare their routing once — imported from the definitions
lib/env.py already owns — and ``backends.resolve`` produces a truthful
"will use" prediction for alternative chains (X, YouTube, web search) plus
honest conditional wording for Reddit.

Covers the plan's U2 scenarios:
  1. X with cookies present, bird healthy, no XAI key -> predicted ``bird``.
  2. Pin var set to a later backend -> pin honored and marked pinned.
  3. Preferred backend installed-but-unauthenticated does not shadow a
     fully-usable fallback (collect-then-pick).
  4. No backend usable -> tier error; prescription from the highest-priority
     backend.
  5. Paid lanes probe key presence ONLY — no network, no subprocess.
  6. Reddit renders conditional wording (default + backfill), never a
     computed winner; a scrapecreators pin renders as pinned.
  7. Parity: descriptor prediction == pipeline's pre-failover X selection
     (env.x_backend_chain()[0]) across three config permutations.
"""

from pathlib import Path
from unittest import mock

import pytest

from lib import backends, env, grok_x, health, xurl_x


# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------

def _probe_dep(status_map=None, default_status=health.OK):
    """Build a fake health.probe_dependency honoring a per-name status map."""
    status_map = status_map or {}

    def fake(name, timeout=health.PROBE_TIMEOUT):
        status = status_map.get(name, default_status)
        if status == health.OK:
            return health.DependencyProbe(name=name, status=health.OK, detail=f"{name} 1.0.0")
        return health.DependencyProbe(
            name=name,
            status=status,
            detail=f"{name} probe simulated {status}",
            prescription=f"reinstall {name}" if status != health.MISSING else f"install {name}",
            owner_pkg_manager="brew",
        )

    return fake


def _x_env(
    bird_installed=False,
    xurl_installed=False,
    xurl_authed=False,
    node_status=health.OK,
    grok_installed=False,
    grok_authed=False,
    grok_expired=False,
    grok_off_path=None,
):
    """Context managers configuring the X-chain probe environment.

    ``xurl_authed`` drives BOTH auth surfaces consistently: the research-time
    network check (``is_available``) and the doctor-path local evidence
    (``stored_auth_status``/``has_stored_auth``) — a real machine where the
    user logged in has both.

    ``grok_expired`` simulates an expired session: AUTH_EXPIRED status, but
    has_stored_auth/is_available still return True (refresh may work).

    ``grok_off_path`` drives the off-PATH branch of the grok probe. It must be
    patched rather than left to the real filesystem: ``_off_path_binary``
    scans installer dirs like ~/.local/bin, so a developer who has grok
    installed there would otherwise take that branch on every
    ``grok_installed=False`` case and see failures CI never reproduces.
    """
    from datetime import datetime, timezone, timedelta
    stored = (
        (xurl_x.AUTH_OK, "stored OAuth credentials found in ~/.xurl")
        if xurl_authed
        else (xurl_x.AUTH_MISSING, "no token store at ~/.xurl")
    )
    if grok_expired:
        past = datetime.now(timezone.utc) - timedelta(hours=2)
        grok_stored = (
            grok_x.AUTH_EXPIRED,
            f"Grok session expired at {past.isoformat()}",
            past,
        )
        grok_available = grok_installed
    elif grok_authed:
        grok_stored = (
            grok_x.AUTH_OK,
            "stored Grok credentials found in ~/.grok/auth.json",
            None,
        )
        grok_available = grok_installed
    else:
        grok_stored = (
            grok_x.AUTH_MISSING,
            "no Grok credential store at ~/.grok/auth.json",
            None,
        )
        grok_available = False
    return (
        mock.patch("lib.bird_x.is_bird_installed", return_value=bird_installed),
        mock.patch("lib.bird_x.set_credentials", lambda *a, **k: None),
        mock.patch("lib.xurl_x.is_available", return_value=xurl_authed),
        mock.patch(
            "lib.backends.which",
            lambda name: (
                "/usr/local/bin/xurl" if (name == "xurl" and xurl_installed)
                else "/usr/local/bin/grok" if (name == "grok" and grok_installed)
                else None
            ),
        ),
        mock.patch("lib.grok_x.stored_auth_status", return_value=grok_stored),
        mock.patch(
            "lib.grok_x.has_stored_auth",
            return_value=grok_installed and (grok_authed or grok_expired),
        ),
        mock.patch("lib.grok_x.is_available", return_value=grok_available),
        mock.patch(
            "lib.health._off_path_binary",
            lambda name: (
                Path(grok_off_path) if name == "grok" and grok_off_path else None
            ),
        ),
        mock.patch("lib.health.probe_dependency", _probe_dep({"node": node_status})),
        mock.patch("lib.xurl_x.stored_auth_status", return_value=stored),
        mock.patch(
            "lib.xurl_x.has_stored_auth",
            return_value=xurl_installed and xurl_authed,
        ),
    )


def _resolve_x(config, **envkw):
    with _stack(_x_env(**envkw)):
        return backends.resolve("x", config)


class _stack:
    """Enter/exit a tuple of context managers (contextlib.ExitStack, terse)."""

    def __init__(self, ctxs):
        self._ctxs = ctxs

    def __enter__(self):
        for c in self._ctxs:
            c.__enter__()
        return self

    def __exit__(self, *exc):
        for c in reversed(self._ctxs):
            c.__exit__(*exc)
        return False


# ---------------------------------------------------------------------------
# Descriptor registry: routing declared once, imported from env.py (KTD 6)
# ---------------------------------------------------------------------------

class TestDescriptorRegistry:
    def test_x_chain_comes_from_env_definitions(self):
        d = backends.get_descriptor("x")
        assert d.mode == backends.MODE_ALTERNATIVE
        # Auto chain order: bird first, grok excluded (opt-in only).
        assert env.X_BACKEND_ORDER == ("bird", "xai", "xurl", "xquik")
        # Grok and xapi are opt-in only off Grok Bot, not in the auto chain.
        assert env.X_BACKEND_OPT_IN == ("grok", "xapi")
        # All known backends (auto + opt-in) for pin validation.
        assert env.X_BACKEND_KNOWN == ("bird", "xai", "xurl", "xquik", "grok", "xapi")
        # Descriptor includes all backends (auto + opt-in) for doctor visibility.
        assert tuple(s.name for s in d.backends) == env.X_BACKEND_ORDER + env.X_BACKEND_OPT_IN
        # Grok and xapi are marked opt-in in the descriptor.
        grok_spec = next(s for s in d.backends if s.name == "grok")
        assert grok_spec.opt_in is True
        xapi_spec = next(s for s in d.backends if s.name == "xapi")
        assert xapi_spec.opt_in is True
        assert xapi_spec.paid is True
        assert xapi_spec.requires == "X_BEARER_TOKEN (X API v2)"
        # Auto chain backends are NOT marked opt-in.
        for name in env.X_BACKEND_ORDER:
            spec = next(s for s in d.backends if s.name == name)
            assert spec.opt_in is False
        assert d.pin_var == env.X_BACKEND_PIN_VAR == "LAST30DAYS_X_BACKEND"

    def test_env_exposes_reddit_pin_constants(self):
        assert env.REDDIT_BACKEND_PIN_VAR == "LAST30DAYS_REDDIT_BACKEND"
        assert env.REDDIT_SC_MIN_ITEMS_VAR == "LAST30DAYS_REDDIT_SC_MIN_ITEMS"

    def test_youtube_and_web_chains_declared_in_order(self):
        yt = backends.get_descriptor("youtube")
        assert tuple(s.name for s in yt.backends) == ("yt-dlp", "scrapecreators")
        web = backends.get_descriptor("web")
        assert tuple(s.name for s in web.backends) == (
            "brave", "exa", "serper", "parallel", "keyless",
        )
        assert web.pin_flag == "--web-backend"

    def test_reddit_is_conditional_and_lanes_are_not_chain_entries(self):
        d = backends.get_descriptor("reddit")
        assert d.mode == backends.MODE_CONDITIONAL
        names = [s.name for s in d.backends]
        # Internal keyless lanes are sub-probe detail, never chain entries.
        for lane in ("search", "listing", "arctic", "shreddit", "rss"):
            assert lane not in names
        assert names == ["public", "scrapecreators"]

    def test_unknown_source_raises(self):
        with pytest.raises(KeyError):
            backends.get_descriptor("nope")
        with pytest.raises(KeyError):
            backends.resolve("nope", {})


# ---------------------------------------------------------------------------
# Scenario 1: cookies present, bird healthy, no XAI key -> bird predicted
# ---------------------------------------------------------------------------

class TestXPrediction:
    def test_bird_predicted_with_cookies_and_no_xai_key(self):
        config = {"AUTH_TOKEN": "dummy-token", "CT0": "dummy-ct0"}
        res = _resolve_x(config, bird_installed=True)
        assert res.active_backend == "bird"
        assert res.tier == backends.TIER_OK
        assert res.pinned is False
        # Chain includes all backends (auto + opt-in) for doctor visibility.
        expected_chain = list(env.X_BACKEND_ORDER + env.X_BACKEND_OPT_IN)
        assert res.chain == expected_chain
        assert [f.name for f in res.findings] == expected_chain
        assert "will use: bird" in res.summary

    def test_bird_predicted_even_when_xai_key_present(self):
        """Cookies beat XAI_API_KEY when both are present (bird-first chain)."""
        config = {"AUTH_TOKEN": "dummy-token", "CT0": "dummy-ct0", "XAI_API_KEY": "dummy-key"}
        res = _resolve_x(config, bird_installed=True)
        assert res.active_backend == "bird"
        assert res.tier == backends.TIER_OK
        assert "will use: bird" in res.summary

    def test_grok_is_never_auto_selected_unpinned(self):
        """Grok is opt-in only: even if grok is the only configured backend, X is unconfigured unpinned."""
        config = {}
        res = _resolve_x(config, grok_installed=True, grok_authed=True)
        # Grok is available but opt-in - should NOT be auto-selected.
        grok = next(f for f in res.findings if f.name == "grok")
        assert grok.status == health.OK
        # But it should not be the active backend.
        assert res.active_backend is None
        assert res.tier == backends.TIER_ERROR

    def test_grok_selected_when_pinned(self):
        """Pin grok to enable it explicitly."""
        config = {"LAST30DAYS_X_BACKEND": "grok"}
        res = _resolve_x(config, grok_installed=True, grok_authed=True)
        assert res.active_backend == "grok"
        assert res.pinned is True
        assert res.pin == "grok"
        assert res.tier == backends.TIER_OK

    def test_grok_pin_with_no_store_is_error(self):
        """Pin grok without a valid store -> error with grok login prescription."""
        config = {"LAST30DAYS_X_BACKEND": "grok"}
        res = _resolve_x(config, grok_installed=True, grok_authed=False)
        assert res.active_backend is None
        assert res.pinned is True
        assert res.tier == backends.TIER_ERROR
        assert "grok login" in res.prescription.lower()

    # Scenario 2: pin var set to a later backend -> honored + marked pinned.
    def test_pin_to_later_backend_honored_and_marked(self):
        config = {
            "AUTH_TOKEN": "dummy-token",
            "CT0": "dummy-ct0",
            "XQUIK_API_KEY": "dummy-key",
            "LAST30DAYS_X_BACKEND": "xquik",
        }
        res = _resolve_x(config, bird_installed=True)
        assert res.active_backend == "xquik"
        assert res.pinned is True
        assert res.pin == "xquik"
        assert res.tier == backends.TIER_OK
        assert "pinned" in res.summary

    # Scenario 3: installed-but-unauthenticated preferred backend must not
    # shadow a fully usable fallback (collect-then-pick).
    def test_unauthenticated_preferred_does_not_shadow_usable_fallback(self):
        config = {"XQUIK_API_KEY": "dummy-key"}
        res = _resolve_x(config, xurl_installed=True, xurl_authed=False)
        assert res.active_backend == "xquik"
        assert res.tier == backends.TIER_OK
        xurl = next(f for f in res.findings if f.name == "xurl")
        assert not xurl.usable
        assert "auth" in (xurl.detail + xurl.prescription).lower()

    # Scenario 4: nothing usable -> error tier, highest-priority prescription.
    def test_no_backend_usable_is_error_with_top_priority_prescription(self):
        res = _resolve_x({})
        assert res.active_backend is None
        assert res.tier == backends.TIER_ERROR
        # bird (cookies) is first in the chain, so the prescription is about
        # browser cookies, not XAI_API_KEY.
        assert "browser-cookie" in res.prescription or "cookies" in res.prescription.lower()

    def test_pinned_but_unusable_backend_is_error_with_its_prescription(self):
        # Pin bird without cookies: env.x_backend_chain returns [] (pipeline
        # raises); resolution mirrors that as an error carrying bird's fix.
        config = {"LAST30DAYS_X_BACKEND": "bird"}
        res = _resolve_x(config, bird_installed=True)
        assert res.active_backend is None
        assert res.pinned is True
        assert res.tier == backends.TIER_ERROR
        assert res.prescription  # bird's cookie prescription, not xai's
        assert "XAI_API_KEY" not in res.prescription

    def test_broken_node_shim_makes_bird_unusable_and_falls_back(self):
        # U1 integration: a stale node shim (BROKEN, not missing) must not
        # let bird read as usable — the #692 class applied to chains.
        config = {
            "AUTH_TOKEN": "dummy-token",
            "CT0": "dummy-ct0",
            "XQUIK_API_KEY": "dummy-key",
        }
        res = _resolve_x(config, bird_installed=True, node_status=health.BROKEN)
        assert res.active_backend == "xquik"
        bird = next(f for f in res.findings if f.name == "bird")
        assert bird.status == health.BROKEN
        assert not bird.usable

    def test_unconfigured_x_with_broken_node_is_unconfigured_not_node_error(self):
        # F9: cookie presence is checked BEFORE the node runtime. With no X
        # configuration at all, a broken node must not turn bird into a
        # BROKEN finding carrying a node prescription — the honest state is
        # "unconfigured, here is the cookie fix" (which doctor rolls up to
        # tier off, since every finding is MISSING).
        res = _resolve_x({}, node_status=health.BROKEN)
        bird = next(f for f in res.findings if f.name == "bird")
        assert bird.status == health.MISSING
        assert "AUTH_TOKEN/CT0" in bird.detail
        assert "cookie" in bird.prescription.lower()
        assert "node" not in bird.prescription.lower()
        # Doctor's off/unconfigured rollup keys on all-findings-MISSING.
        assert all(f.status == health.MISSING for f in res.findings)

    def test_cookies_present_broken_node_still_reads_broken(self):
        # The inverse guard: once cookies ARE configured, a broken node is a
        # real configured-but-broken state and must keep the node fix.
        config = {"AUTH_TOKEN": "dummy-token", "CT0": "dummy-ct0"}
        res = _resolve_x(config, bird_installed=True, node_status=health.BROKEN)
        bird = next(f for f in res.findings if f.name == "bird")
        assert bird.status == health.BROKEN
        assert "node" in bird.prescription.lower()

    def test_grok_expired_is_degraded_not_ok(self):
        """Expired grok session -> DEGRADED tier (warn), not OK."""
        # Grok is opt-in: needs explicit pin to be selected.
        config = {"LAST30DAYS_X_BACKEND": "grok"}
        res = _resolve_x(config, grok_installed=True, grok_expired=True)
        grok = next(f for f in res.findings if f.name == "grok")
        assert grok.status == health.DEGRADED
        assert grok.usable  # DEGRADED is still usable (refresh may work)
        assert "expired" in grok.detail.lower()
        assert "grok login" in grok.prescription.lower()
        # With pin, grok is selected (degraded is usable).
        assert res.active_backend == "grok"
        assert res.tier == backends.TIER_WARN

    def test_grok_expired_unpinned_not_selected(self):
        """Expired grok without pin: X unconfigured, grok not auto-selected."""
        res = _resolve_x({}, grok_installed=True, grok_expired=True)
        grok = next(f for f in res.findings if f.name == "grok")
        assert grok.status == health.DEGRADED
        # Grok is opt-in, so even though it's usable (degraded), it's not selected.
        assert res.active_backend is None
        assert res.tier == backends.TIER_ERROR

    def test_grok_expired_with_fallback_picks_fallback(self):
        """When grok is expired AND a better auto-chain backend is OK, pick the OK one."""
        config = {"AUTH_TOKEN": "dummy-token", "CT0": "dummy-ct0"}
        res = _resolve_x(config, grok_installed=True, grok_expired=True, bird_installed=True)
        # Bird is OK and in the auto chain. Grok is not considered (opt-in).
        assert res.active_backend == "bird"
        assert res.tier == backends.TIER_OK

    def test_grok_future_expires_at_is_ok(self):
        """Grok with future expires_at reports OK."""
        res = _resolve_x({}, grok_installed=True, grok_authed=True)
        grok = next(f for f in res.findings if f.name == "grok")
        assert grok.status == health.OK
        assert "not live-verified" in grok.detail


# ---------------------------------------------------------------------------
# Grok session expiry: three states (grok is opt-in only)
# ---------------------------------------------------------------------------

class TestGrokExpiryStates:
    """Test the three grok auth states from the plan:
    1. No grok CLI -> silent fallback (opt-in only)
    2. CLI installed, never logged in -> silent fallback (opt-in only)
    3. CLI installed, WAS logged in, session dead -> DEGRADED with expiry info (opt-in only)

    Note: Grok is opt-in only. These tests verify the finding status, but grok
    is never auto-selected unpinned.
    """

    def test_no_grok_cli_is_missing(self):
        """No grok CLI -> MISSING status, no extra failure noise."""
        res = _resolve_x({}, grok_installed=False)
        grok = next(f for f in res.findings if f.name == "grok")
        assert grok.status == health.MISSING
        assert "not found on PATH" in grok.detail
        # Grok is opt-in, so even MISSING doesn't affect the resolution.
        # X is unconfigured (no auto-chain backends available).
        assert res.active_backend is None

    def test_grok_off_path_prescribes_a_path_edit_not_an_install(self):
        """grok present in an installer dir but absent from PATH -> still
        MISSING, but the prescription must be a PATH edit: installing again
        would fix nothing. This branch had no coverage, so it only ever ran
        on developer machines that happened to have grok in ~/.local/bin."""
        res = _resolve_x({}, grok_installed=False,
                         grok_off_path="/home/dev/.local/bin/grok")
        grok = next(f for f in res.findings if f.name == "grok")
        assert grok.status == health.MISSING
        assert "not on this process's PATH" in grok.detail
        assert "/home/dev/.local/bin/grok" in grok.detail
        assert "/home/dev/.local/bin" in grok.prescription
        assert "install" not in grok.prescription.lower()
        assert res.active_backend is None

    def test_grok_installed_never_logged_in_is_missing(self):
        """CLI installed but never logged in -> MISSING with login hint."""
        res = _resolve_x({}, grok_installed=True, grok_authed=False)
        grok = next(f for f in res.findings if f.name == "grok")
        assert grok.status == health.MISSING
        assert "not signed in" in grok.detail
        assert "grok login" in grok.prescription
        # Grok is opt-in, so X is unconfigured.
        assert res.active_backend is None

    def test_grok_session_expired_is_degraded_with_expiry(self):
        """Session expired -> DEGRADED with timestamp and refresh hint."""
        res = _resolve_x({}, grok_installed=True, grok_expired=True)
        grok = next(f for f in res.findings if f.name == "grok")
        assert grok.status == health.DEGRADED
        assert "expired" in grok.detail.lower()
        # The detail should include the expiry timestamp and hint
        assert "refresh" in grok.detail.lower() or "login" in grok.prescription.lower()
        # Grok is opt-in, so X is unconfigured even with degraded grok.
        assert res.active_backend is None

    def test_grok_healthy_session_is_ok(self):
        """Non-expired credentials -> OK, but still opt-in only."""
        res = _resolve_x({}, grok_installed=True, grok_authed=True)
        grok = next(f for f in res.findings if f.name == "grok")
        assert grok.status == health.OK
        # Grok is opt-in, so X is unconfigured unpinned.
        assert res.active_backend is None


# ---------------------------------------------------------------------------
# Scenario 5: paid lanes probe key presence only — never network/subprocess
# ---------------------------------------------------------------------------

def _forbid_io():
    def boom(*a, **k):
        raise AssertionError("paid-lane probe attempted I/O")

    return (
        mock.patch("socket.socket", boom),
        mock.patch("socket.create_connection", boom),
        mock.patch("urllib.request.urlopen", boom),
        mock.patch("subprocess.run", boom),
        mock.patch("subprocess.Popen", boom),
    )


class TestPaidLaneProbes:
    PAID = [
        ("x", "xai", "XAI_API_KEY"),
        ("x", "xquik", "XQUIK_API_KEY"),
        ("web", "serper", "SERPER_API_KEY"),
        ("youtube", "scrapecreators", "SCRAPECREATORS_API_KEY"),
        ("reddit", "scrapecreators", "SCRAPECREATORS_API_KEY"),
    ]

    def test_paid_lanes_are_flagged_paid(self):
        for source, name, _key in self.PAID:
            spec = next(
                s for s in backends.get_descriptor(source).backends if s.name == name
            )
            assert spec.paid is True, f"{source}/{name} must be a paid (key-only) lane"

    def test_key_presence_probe_makes_no_network_or_subprocess_calls(self):
        ctxs = _forbid_io()
        with ctxs[0], ctxs[1], ctxs[2], ctxs[3], ctxs[4]:
            for source, name, key in self.PAID:
                spec = next(
                    s for s in backends.get_descriptor(source).backends if s.name == name
                )
                present = spec.probe({key: "dummy-key"})
                assert present.status == health.OK
                absent = spec.probe({})
                assert absent.status == health.MISSING
                assert key in absent.prescription


# ---------------------------------------------------------------------------
# F1 + F10: the doctor-path xurl probe is LOCAL-ONLY (stored-token evidence,
# never a live `xurl whoami` — doctor's no-network guarantee) and typed.
# ---------------------------------------------------------------------------

class TestXurlLocalProbe:
    def _spec(self):
        return next(
            s for s in backends.get_descriptor("x").backends if s.name == "xurl"
        )

    def _finding(self, stored, installed=True):
        """Run the xurl probe under the forbid-all-I/O harness."""
        ctxs = _forbid_io()
        with ctxs[0], ctxs[1], ctxs[2], ctxs[3], ctxs[4], \
             mock.patch(
                 "lib.backends.which",
                 lambda n: "/usr/local/bin/xurl" if installed else None,
             ), \
             mock.patch("lib.xurl_x.stored_auth_status", return_value=stored):
            return self._spec().probe({})

    def test_token_store_present_is_ok_without_network(self):
        finding = self._finding(
            (xurl_x.AUTH_OK, "stored OAuth credentials found in ~/.xurl")
        )
        assert finding.status == health.OK
        assert "not live-verified" in finding.detail

    def test_no_token_store_is_missing_with_auth_prescription(self):
        finding = self._finding((xurl_x.AUTH_MISSING, "no token store at ~/.xurl"))
        assert finding.status == health.MISSING
        assert "not authenticated" in finding.detail
        assert "xurl auth oauth2 login" in finding.prescription

    def test_unreadable_token_store_is_error_tier(self):
        # F10: binary resolvable but the token-store read fails -> typed
        # ERROR (doctor's error tier), never "unconfigured".
        finding = self._finding(
            (
                xurl_x.AUTH_ERROR,
                "token store ~/.xurl unreadable: PermissionError: denied",
            )
        )
        assert finding.status == health.ERROR
        assert not finding.usable
        assert "unreadable" in finding.detail

    def test_binary_absent_stays_not_installed(self):
        finding = self._finding((xurl_x.AUTH_OK, "irrelevant"), installed=False)
        assert finding.status == health.MISSING
        assert "not found on PATH" in finding.detail

    def test_whole_doctor_path_x_probe_makes_no_network_or_subprocess(self, tmp_path):
        """The full X chain resolution plus the safe get_x_source_status —
        the exact X probes doctor runs — under the forbid-everything
        harness. The token store is a REAL file so the genuine
        stored_auth_status code path (filesystem only) is exercised."""
        store = tmp_path / ".xurl"
        store.write_text(
            "apps:\n  app:\n    oauth2_tokens:\n      me:\n        oauth2:\n"
            "          access_token: dummy-not-real\n",
            encoding="utf-8",
        )
        config = {"AUTH_TOKEN": "dummy-token", "CT0": "dummy-ct0"}
        bird_status = {
            "installed": True,
            "authenticated": True,
            "username": "env AUTH_TOKEN",
            "can_install": True,
        }
        ctxs = _forbid_io()
        with ctxs[0], ctxs[1], ctxs[2], ctxs[3], ctxs[4], \
             mock.patch(
                 "lib.xurl_x.is_available",
                 side_effect=AssertionError(
                     "doctor path ran the live `xurl whoami` network check"
                 ),
             ), \
             mock.patch("lib.xurl_x.token_store_path", return_value=store), \
             mock.patch("lib.backends.which", lambda n: f"/usr/local/bin/{n}"), \
             mock.patch(
                 "lib.xurl_x.shutil.which", lambda n: f"/usr/local/bin/{n}"
             ), \
             mock.patch("lib.health.probe_dependency", _probe_dep()), \
             mock.patch("lib.bird_x.is_bird_installed", return_value=True), \
             mock.patch("lib.bird_x.set_credentials", lambda *a, **k: None), \
             mock.patch("lib.bird_x.get_bird_status", return_value=bird_status):
            res = backends.resolve("x", config)
            status = env.get_x_source_status(config, probe=False)
        xurl_finding = next(f for f in res.findings if f.name == "xurl")
        assert xurl_finding.status == health.OK
        assert "not live-verified" in xurl_finding.detail
        assert status["xurl_available"] is True


# ---------------------------------------------------------------------------
# Scenario 6: Reddit conditional wording, never a computed winner
# ---------------------------------------------------------------------------

class TestRedditConditional:
    def test_sc_key_present_renders_default_plus_backfill_no_winner(self):
        res = backends.resolve("reddit", {"SCRAPECREATORS_API_KEY": "dummy-key"})
        assert res.mode == backends.MODE_CONDITIONAL
        assert res.active_backend is None  # never a single computed winner
        assert "will use" not in res.summary
        low = res.conditional.lower()
        assert "public keyless" in low
        assert "default" in low
        assert "scrapecreators backfill" in low
        assert res.tier == backends.TIER_OK

    def test_thinness_floor_appears_in_wording(self):
        res = backends.resolve(
            "reddit",
            {"SCRAPECREATORS_API_KEY": "dummy-key", "LAST30DAYS_REDDIT_SC_MIN_ITEMS": "5"},
        )
        assert "5" in res.conditional
        assert "floor" in res.conditional.lower()

    def test_default_floor_names_five_item_floor(self):
        res = backends.resolve("reddit", {"SCRAPECREATORS_API_KEY": "dummy-key"})
        low = res.conditional.lower()
        assert "5-item floor" in low
        assert "nothing" not in low

    def test_empty_floor_treated_as_default(self):
        res = backends.resolve(
            "reddit",
            {"SCRAPECREATORS_API_KEY": "dummy-key", "LAST30DAYS_REDDIT_SC_MIN_ITEMS": ""},
        )
        assert "5-item floor" in res.conditional.lower()

    def test_explicit_zero_floor_means_empty_only_wording(self):
        res = backends.resolve(
            "reddit",
            {"SCRAPECREATORS_API_KEY": "dummy-key", "LAST30DAYS_REDDIT_SC_MIN_ITEMS": "0"},
        )
        low = res.conditional.lower()
        assert "nothing" in low
        assert "floor" not in low

    def test_malformed_floor_spends_nothing_extra(self):
        # Malformed parses to 0 (empty-only), matching the pipeline.
        res = backends.resolve(
            "reddit",
            {"SCRAPECREATORS_API_KEY": "dummy-key", "LAST30DAYS_REDDIT_SC_MIN_ITEMS": "lots"},
        )
        low = res.conditional.lower()
        assert "nothing" in low
        assert "floor" not in low

    def test_pinned_scrapecreators_renders_pin(self):
        res = backends.resolve(
            "reddit",
            {
                "SCRAPECREATORS_API_KEY": "dummy-key",
                "LAST30DAYS_REDDIT_BACKEND": "scrapecreators",
            },
        )
        assert res.pinned is True
        assert res.pin == "scrapecreators"
        low = res.conditional.lower()
        assert "pinned" in low
        assert "primary" in low
        assert res.active_backend is None  # still conditional, not a winner

    def test_no_key_means_no_backfill_wording(self):
        res = backends.resolve("reddit", {})
        low = res.conditional.lower()
        assert "public keyless" in low
        assert "backfill" not in low or "no scrapecreators" in low
        assert res.tier == backends.TIER_OK  # public composite always reachable

    def test_pin_without_key_is_ignored_like_the_pipeline(self):
        # pipeline gates sc_first on has_sc_key; the pin alone changes nothing.
        res = backends.resolve(
            "reddit", {"LAST30DAYS_REDDIT_BACKEND": "scrapecreators"},
        )
        assert res.pinned is False
        assert "primary" not in res.conditional.lower().split("pin ignored")[0]

    def test_keyless_lanes_are_sub_probe_detail(self):
        res = backends.resolve("reddit", {})
        public = next(f for f in res.findings if f.name == "public")
        assert public.detail.endswith("(lanes: search, listing, arctic, shreddit)")
        assert "rss" not in public.detail


# ---------------------------------------------------------------------------
# Scenario 7: parity with the pipeline's pre-failover X selection
# ---------------------------------------------------------------------------

class TestXParityWithPipeline:
    """Descriptor prediction must equal env.x_backend_chain(config)[0] — the
    exact expression pipeline._retrieve_stream uses as its pre-failover
    primary (lib/pipeline.py, `chain = env.x_backend_chain(config)`)."""

    def _assert_parity(self, config, **envkw):
        with _stack(_x_env(**envkw)):
            chain = env.x_backend_chain(config)
            predicted = backends.resolve("x", config).active_backend
        expected = chain[0] if chain else None
        assert predicted == expected, (
            f"prediction {predicted!r} != pipeline pre-failover {expected!r} "
            f"for config keys {sorted(config)}"
        )

    def test_parity_xai_key_only(self):
        self._assert_parity({"XAI_API_KEY": "dummy-key"})

    def test_parity_cookies_and_bird_installed(self):
        self._assert_parity(
            {"AUTH_TOKEN": "dummy-token", "CT0": "dummy-ct0"},
            bird_installed=True,
        )

    def test_parity_pin_forces_xquik(self):
        self._assert_parity(
            {"XQUIK_API_KEY": "dummy-key", "LAST30DAYS_X_BACKEND": "xquik"},
        )

    def test_parity_nothing_configured(self):
        self._assert_parity({})

    def test_parity_grok_only_unpinned_is_unconfigured(self):
        """Grok-only with no pin: X unconfigured (parity with env.x_backend_chain)."""
        self._assert_parity({}, grok_installed=True, grok_authed=True)

    def test_parity_grok_pinned(self):
        """Grok pinned: grok is selected (parity with env.x_backend_chain)."""
        self._assert_parity(
            {"LAST30DAYS_X_BACKEND": "grok"},
            grok_installed=True,
            grok_authed=True,
        )

    def test_parity_cookies_beat_xai_key(self):
        """Cookies beat XAI_API_KEY when both present (bird-first chain)."""
        self._assert_parity(
            {"AUTH_TOKEN": "dummy-token", "CT0": "dummy-ct0", "XAI_API_KEY": "dummy-key"},
            bird_installed=True,
        )

    # Host rows (U1): the policy shapes both sides identically.

    def test_parity_grok_bot_bearer(self):
        self._assert_parity(
            {"LAST30DAYS_HOST": "grok-bot", "X_BEARER_TOKEN": "dummy-bearer",
             "AUTH_TOKEN": "dummy-token", "CT0": "dummy-ct0"},
            bird_installed=True,
        )

    def test_parity_grok_bot_xai_key(self):
        self._assert_parity(
            {"LAST30DAYS_HOST": "grok-bot", "XAI_API_KEY": "dummy-key",
             "AUTH_TOKEN": "dummy-token", "CT0": "dummy-ct0"},
            bird_installed=True,
        )

    def test_parity_grok_bot_cookies_only_unpinned(self):
        self._assert_parity(
            {"LAST30DAYS_HOST": "grok-bot", "AUTH_TOKEN": "dummy-token", "CT0": "dummy-ct0",
             "XQUIK_API_KEY": "dummy-key"},
            bird_installed=True,
        )

    def test_parity_grok_bot_bird_pin(self):
        self._assert_parity(
            {"LAST30DAYS_HOST": "grok-bot", "LAST30DAYS_X_BACKEND": "bird",
             "AUTH_TOKEN": "dummy-token", "CT0": "dummy-ct0"},
            bird_installed=True,
        )

    def test_parity_grok_bot_grok_pin(self):
        self._assert_parity(
            {"LAST30DAYS_HOST": "grok-bot", "LAST30DAYS_X_BACKEND": "grok"},
            grok_installed=True,
            grok_authed=True,
        )

    def test_parity_non_grok_linux_cookies_and_bearer(self):
        with mock.patch("platform.system", return_value="Linux"):
            self._assert_parity(
                {"AUTH_TOKEN": "dummy-token", "CT0": "dummy-ct0",
                 "X_BEARER_TOKEN": "dummy-bearer"},
                bird_installed=True,
            )

    def test_parity_macbook_xai_key(self):
        with (
            mock.patch("platform.system", return_value="Darwin"),
            mock.patch.object(env, "_mac_model", return_value="MacBookPro18,2"),
        ):
            self._assert_parity({"XAI_API_KEY": "dummy-key"})


# ---------------------------------------------------------------------------
# get_x_source_status pin semantics (R4): grok pin forces grok source
# ---------------------------------------------------------------------------

class TestGetXSourceStatusGrokPin:
    """get_x_source_status must respect LAST30DAYS_X_BACKEND=grok pin."""

    def test_pin_grok_with_store_returns_grok_source(self):
        """Pin grok + valid store -> get_x_source_status source is 'grok'."""
        config = {"LAST30DAYS_X_BACKEND": "grok"}
        bird_status = {
            "installed": False,
            "authenticated": False,
            "username": "",
            "can_install": False,
        }
        with (
            mock.patch("lib.grok_x.has_stored_auth", return_value=True),
            mock.patch("lib.bird_x.get_bird_status", return_value=bird_status),
        ):
            status = env.get_x_source_status(config, probe=False)
        assert status["source"] == "grok"
        assert status["grok_available"] is True

    def test_unpinned_with_store_does_not_return_grok_source(self):
        """Unpinned + valid grok store -> source is NOT 'grok' (opt-in only)."""
        config = {}  # No pin
        bird_status = {
            "installed": False,
            "authenticated": False,
            "username": "",
            "can_install": False,
        }
        with (
            mock.patch("lib.grok_x.has_stored_auth", return_value=True),
            mock.patch("lib.bird_x.get_bird_status", return_value=bird_status),
        ):
            status = env.get_x_source_status(config, probe=False)
        # Grok is available but NOT the source (opt-in only)
        assert status["source"] != "grok"
        assert status["source"] is None  # No other backend configured
        assert status["grok_available"] is True

    def test_pin_grok_with_cookies_still_returns_grok(self):
        """Pin grok with cookies present -> grok (pin forces single backend)."""
        config = {
            "LAST30DAYS_X_BACKEND": "grok",
            "AUTH_TOKEN": "dummy-token",
            "CT0": "dummy-ct0",
        }
        bird_status = {
            "installed": True,
            "authenticated": True,
            "username": "test",
            "can_install": True,
        }
        with (
            mock.patch("lib.grok_x.has_stored_auth", return_value=True),
            mock.patch("lib.bird_x.get_bird_status", return_value=bird_status),
        ):
            status = env.get_x_source_status(config, probe=False)
        # Pin forces grok even when bird is available
        assert status["source"] == "grok"

    def test_pin_grok_no_store_with_other_creds_returns_none(self):
        """Pin grok + no store + other creds present -> source is None (exclusive pin)."""
        config = {
            "LAST30DAYS_X_BACKEND": "grok",
            "AUTH_TOKEN": "dummy-token",
            "CT0": "dummy-ct0",
            "XAI_API_KEY": "dummy-key",
        }
        bird_status = {
            "installed": True,
            "authenticated": True,
            "username": "test",
            "can_install": True,
        }
        with (
            mock.patch("lib.grok_x.has_stored_auth", return_value=False),
            mock.patch("lib.bird_x.get_bird_status", return_value=bird_status),
        ):
            status = env.get_x_source_status(config, probe=False)
        # Pin is exclusive: grok unavailable -> None, NOT fallback to bird/xai
        assert status["source"] is None
        assert status["grok_available"] is False
        # Other backends ARE available, but pin blocks fallback
        assert status["bird_authenticated"] is True
        assert status["xai_available"] is True

    def test_pin_xai_with_cookies_returns_xai(self):
        """Pin xai + cookies + XAI_API_KEY -> source is xai, not bird."""
        config = {
            "LAST30DAYS_X_BACKEND": "xai",
            "AUTH_TOKEN": "dummy-token",
            "CT0": "dummy-ct0",
            "XAI_API_KEY": "dummy-key",
        }
        bird_status = {
            "installed": True,
            "authenticated": True,
            "username": "test",
            "can_install": True,
        }
        with (
            mock.patch("lib.grok_x.has_stored_auth", return_value=False),
            mock.patch("lib.bird_x.get_bird_status", return_value=bird_status),
        ):
            status = env.get_x_source_status(config, probe=False)
        # Pin is exclusive: xai pinned + available -> xai (not bird)
        assert status["source"] == "xai"
        # Bird is also available, but pin forces xai
        assert status["bird_authenticated"] is True

    def test_pin_xai_no_key_with_cookies_returns_none(self):
        """Pin xai + no XAI_API_KEY + cookies -> source is None (exclusive pin)."""
        config = {
            "LAST30DAYS_X_BACKEND": "xai",
            "AUTH_TOKEN": "dummy-token",
            "CT0": "dummy-ct0",
            # No XAI_API_KEY
        }
        bird_status = {
            "installed": True,
            "authenticated": True,
            "username": "test",
            "can_install": True,
        }
        with (
            mock.patch("lib.grok_x.has_stored_auth", return_value=False),
            mock.patch("lib.bird_x.get_bird_status", return_value=bird_status),
        ):
            status = env.get_x_source_status(config, probe=False)
        # Pin is exclusive: xai pinned but unavailable -> None (no fallback)
        assert status["source"] is None
        assert status["xai_available"] is False
        # Bird is available but pin blocks fallback
        assert status["bird_authenticated"] is True


# ---------------------------------------------------------------------------
# Runtime X backend pin (x_backend_chain / _resolve_x_backend)
# ---------------------------------------------------------------------------

class TestRuntimeXBackendPin:
    """Runtime fetch path must honor any known pin exclusively, including grok."""

    def test_pin_grok_with_store_and_cookies_returns_grok(self):
        """Pin grok + grok store + cookies -> runtime returns grok, not bird."""
        from lib import grok_x, providers

        config = {
            "LAST30DAYS_X_BACKEND": "grok",
            "AUTH_TOKEN": "dummy-token",
            "CT0": "dummy-ct0",
            "XAI_API_KEY": "dummy-key",
        }
        with (
            mock.patch.object(grok_x, "has_stored_auth", return_value=True),
            mock.patch("lib.bird_x.is_bird_installed", return_value=True),
        ):
            # x_backend_chain is the authoritative runtime path
            chain = env.x_backend_chain(config)
            # _resolve_x_backend delegates to get_x_source (wraps x_backend_chain)
            resolved = providers._resolve_x_backend(config)
        # Pin grok + available -> grok (not bird/xai)
        assert chain == ["grok"]
        assert resolved == "grok"

    def test_pin_grok_no_store_with_cookies_returns_none(self):
        """Pin grok + no store + cookies -> runtime returns None (exclusive pin)."""
        from lib import grok_x, providers

        config = {
            "LAST30DAYS_X_BACKEND": "grok",
            "AUTH_TOKEN": "dummy-token",
            "CT0": "dummy-ct0",
        }
        with (
            mock.patch.object(grok_x, "has_stored_auth", return_value=False),
            mock.patch("lib.bird_x.is_bird_installed", return_value=True),
        ):
            chain = env.x_backend_chain(config)
            resolved = providers._resolve_x_backend(config)
        # Pin grok + unavailable -> [] / None (no fallthrough to bird)
        assert chain == []
        assert resolved is None

    def test_unpinned_with_grok_store_and_cookies_returns_bird(self):
        """Unpinned + grok store + cookies -> runtime returns bird, never grok."""
        from lib import grok_x, providers

        config = {
            "AUTH_TOKEN": "dummy-token",
            "CT0": "dummy-ct0",
        }
        with (
            mock.patch.object(grok_x, "has_stored_auth", return_value=True),
            mock.patch("lib.bird_x.is_bird_installed", return_value=True),
        ):
            chain = env.x_backend_chain(config)
            resolved = providers._resolve_x_backend(config)
        # Unpinned -> auto-chain (bird first), grok never auto-selected
        assert chain[0] == "bird"
        assert "grok" not in chain
        assert resolved == "bird"


# ---------------------------------------------------------------------------
# YouTube chain: yt-dlp -> ScrapeCreators
# ---------------------------------------------------------------------------

class TestYouTubeChain:
    def test_ytdlp_healthy_wins(self):
        with mock.patch("lib.health.probe_dependency", _probe_dep()):
            res = backends.resolve("youtube", {"SCRAPECREATORS_API_KEY": "dummy-key"})
        assert res.active_backend == "yt-dlp"
        assert res.tier == backends.TIER_OK

    def test_missing_ytdlp_falls_back_to_sc_key(self):
        with mock.patch(
            "lib.health.probe_dependency", _probe_dep({"yt-dlp": health.MISSING}),
        ):
            res = backends.resolve("youtube", {"SCRAPECREATORS_API_KEY": "dummy-key"})
        assert res.active_backend == "scrapecreators"
        assert res.tier == backends.TIER_OK

    def test_ytdlp_pin_never_fails_over_to_sc(self):
        """#1316: a pinned yt-dlp lane reports its own failure, not SC."""
        config = {"SCRAPECREATORS_API_KEY": "dummy-key", "LAST30DAYS_YOUTUBE_BACKEND": "yt-dlp"}
        with mock.patch(
            "lib.health.probe_dependency", _probe_dep({"yt-dlp": health.MISSING}),
        ):
            res = backends.resolve("youtube", config)
        assert res.pinned is True
        assert res.pin == "yt-dlp"
        assert res.active_backend is None
        assert res.tier == backends.TIER_ERROR

    def test_ytdlp_pin_spelling_matches_runtime_gate(self):
        """Doctor reads " YTDLP " as the same pin the runtime honors."""
        config = {"SCRAPECREATORS_API_KEY": "dummy-key", "LAST30DAYS_YOUTUBE_BACKEND": " YTDLP "}
        with mock.patch("lib.health.probe_dependency", _probe_dep()):
            res = backends.resolve("youtube", config)
        assert res.pinned is True
        assert res.pin == "yt-dlp"

    def test_scrapecreators_is_not_a_youtube_pin_value(self):
        config = {"SCRAPECREATORS_API_KEY": "dummy-key", "LAST30DAYS_YOUTUBE_BACKEND": "scrapecreators"}
        with mock.patch("lib.health.probe_dependency", _probe_dep()):
            res = backends.resolve("youtube", config)
        assert res.pinned is False
        assert res.active_backend == "yt-dlp"

    def test_neither_available_error_carries_ytdlp_prescription(self):
        with mock.patch(
            "lib.health.probe_dependency", _probe_dep({"yt-dlp": health.MISSING}),
        ):
            res = backends.resolve("youtube", {})
        assert res.active_backend is None
        assert res.tier == backends.TIER_ERROR
        assert "yt-dlp" in res.prescription


# ---------------------------------------------------------------------------
# Web search chain: brave -> exa -> serper -> parallel -> keyless floor
# ---------------------------------------------------------------------------

class TestWebChain:
    def test_brave_key_predicted_first(self):
        res = backends.resolve(
            "web", {"BRAVE_API_KEY": "dummy-key", "EXA_API_KEY": "dummy-key"},
        )
        assert res.active_backend == "brave"
        assert res.tier == backends.TIER_OK

    def test_keyless_floor_is_degraded_warn(self):
        res = backends.resolve("web", {})
        assert res.active_backend == "keyless"
        assert res.tier == backends.TIER_WARN

    def test_native_search_suppresses_keyless_floor(self):
        res = backends.resolve("web", {"LAST30DAYS_NATIVE_SEARCH": "1"})
        keyless = next(f for f in res.findings if f.name == "keyless")
        assert not keyless.usable
        assert res.active_backend is None

    def test_pin_via_web_backend_flag(self):
        res = backends.resolve(
            "web", {"BRAVE_API_KEY": "dummy-key", "EXA_API_KEY": "dummy-key"}, pin="exa",
        )
        assert res.active_backend == "exa"
        assert res.pinned is True
        assert "pinned" in res.summary

    def test_parity_with_grounding_auto_dispatch(self):
        """resolve('web').active_backend must match the backend grounding's
        auto branch actually dispatches to, per config permutation."""
        from lib import grounding

        def _auto_pick(config):
            picked = {}

            def rec(label):
                def f(query, date_range, key, count=5):
                    picked["backend"] = label
                    return [], {"label": label}
                return f

            with mock.patch.object(grounding, "brave_search", rec("brave")), \
                 mock.patch.object(grounding, "exa_search", rec("exa")), \
                 mock.patch.object(grounding, "serper_search", rec("serper")), \
                 mock.patch.object(grounding, "parallel_search", rec("parallel")), \
                 mock.patch(
                     "lib.web_search_keyless.keyless_search",
                     lambda q, dr, cfg: (picked.__setitem__("backend", "keyless") or ([], {})),
                 ):
                grounding.web_search("q", ("2026-06-04", "2026-07-04"), config, backend="auto")
            return picked.get("backend")

        for config in (
            {"BRAVE_API_KEY": "dummy-key"},
            {"SERPER_API_KEY": "dummy-key"},
            {},
        ):
            assert backends.resolve("web", config).active_backend == _auto_pick(config)


# ---------------------------------------------------------------------------
# Rendering: prediction reads as will-use, never as past observation
# ---------------------------------------------------------------------------

class TestSummaryWording:
    def test_alternative_summary_is_will_use(self):
        res = backends.resolve("web", {"BRAVE_API_KEY": "dummy-key"})
        assert res.summary.startswith("will use: brave")
        assert "used" not in res.summary.split("will use")[1]

    def test_error_summary_names_no_backend(self):
        with mock.patch(
            "lib.health.probe_dependency", _probe_dep({"yt-dlp": health.MISSING}),
        ):
            res = backends.resolve("youtube", {})
        assert "will use" not in res.summary
        assert "no usable backend" in res.summary.lower()

    def test_conditional_summary_is_the_conditional_wording(self):
        res = backends.resolve("reddit", {"SCRAPECREATORS_API_KEY": "dummy-key"})
        assert res.summary == res.conditional