Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

53.9 KB
Raw Blame
"""CU v2 engine state-machine tests — scripted FakeBrain, fake tool layer.

Each test encodes one of the observed live failure classes the rebuild must
kill: duplicate actions on an unchanged screen, blind typing after a missed
focus click, a second stale pointer action in one batch, and unverified
"done" claims.
"""

from __future__ import annotations

from pathlib import Path
from types import SimpleNamespace
from typing import Any

import pytest

pytest.importorskip("PIL", reason="pillow required for frame handling")

import dodaios.cu.engine as engine_mod
from dodaios.cu.capture import VisualProbe, capture_stable_frame
from dodaios.cu.geometry import MonitorInfo
from tests.fakes.fake_permission_service import FakePermissionService

MONITOR = MonitorInfo(left=0, top=0, width=192, height=108)


class FakeBrain:
    """Scripted ``complete_text`` manager: pops one reply per call."""

    def __init__(self, replies: list[str]) -> None:
        self.replies = list(replies)
        self.calls: list[tuple[str, str]] = []

    async def complete_text(self, *, system: str, user: str) -> str:
        self.calls.append((system, user))
        if not self.replies:
            return '{"action": "wait", "ms": 1}'
        return self.replies.pop(0)


class FakeExecutor:
    """Records every dispatched tool call; scriptable per-tool success."""

    def __init__(self, failures: set[str] | None = None) -> None:
        self.calls: list[tuple[str, dict[str, Any]]] = []
        self.failures = failures or set()

    async def execute(self, tool, args, *, user_utterance, trace_id):
        name = tool["name"]
        self.calls.append((name, dict(args)))
        if name in self.failures:
            return SimpleNamespace(success=False, output=None, error=f"{name} broke")
        return SimpleNamespace(success=True, output=f"{name} ok")


def _tools() -> dict[str, Any]:
    return {
        name: {"name": name}
        for name in (
            "click",
            "type_text",
            "hotkey",
            "scroll",
            "drag",
            "open_app",
            "switch_window",
            "click_element",
        )
    }


def _ctx(brain: FakeBrain, executor: FakeExecutor) -> SimpleNamespace:
    return SimpleNamespace(
        brain_manager=brain,
        tool_executor=executor,
        tools=_tools(),
        bus=None,
        step_budget=30,
        monitor="primary",
        main_monitor="primary",
        settle_scale=0.0,  # no real sleeps in tests
        strict_verify=True,
        image_max_dimension=192,
        coordinate_space="auto",
    )


def _solid(shade: int = 30) -> tuple[tuple[int, int], bytes]:
    return ((192, 108), bytes((shade, shade, shade)) * (192 * 108))


@pytest.fixture
def patched(monkeypatch, tmp_path):
    """Patch every OS touchpoint of the engine to deterministic fakes."""
    gate = FakePermissionService()
    monkeypatch.setattr(engine_mod, "_permission_gate", lambda: gate)
    monkeypatch.setattr(engine_mod, "_frontmost_system_consent_owner", lambda: "")
    state = SimpleNamespace(
        screen_shade=30,
        typed_lands=True,  # bool, or a list popped per verify call
        region_changes_after_click=True,
        clicks_seen=0,
        clickables=[],
        focus_hit=None,  # verify_click_focus_point verdict
        capture_calls=0,  # capture_stable_frame invocations
        foreground_handle=11,
        foreground_rect=(0, 0, 192, 108),
        foreground_pid=None,  # set to an int for macOS-style app identity
    )

    def fake_select_capture_target(
        policy,
        *,
        main_monitor="primary",
        scope="window",
    ):
        return MONITOR

    def fake_capture(monitor, *, max_dimension, blob_dir=None, **kw):
        state.capture_calls += 1
        return capture_stable_frame(
            monitor,
            grab=lambda bbox: _solid(state.screen_shade),
            sleep=lambda s: None,
            max_dimension=max_dimension,
            blob_dir=Path(tmp_path),
            capture_guard=kw.get("capture_guard"),
        )

    def fake_grab_region(bbox, *, grab=None):
        # First call is the pre-action baseline. A successful fake click then
        # leaves a persistent changed state for both confirmation captures.
        if state.region_changes_after_click and state.clicks_seen >= 1:
            state.clicks_seen += 1
            return _solid(state.screen_shade + 40)
        state.clicks_seen += 1
        return _solid(state.screen_shade)

    def fake_visual_probe(
        _bbox,
        *,
        point=None,
        radius=110,
        local_only=False,
    ):
        changed = state.region_changes_after_click and state.clicks_seen >= 1
        shade = state.screen_shade + (40 if changed else 0)
        state.clicks_seen += 1
        return VisualProbe(
            global_thumb=(None if local_only else bytes((shade,)) * (96 * 54)),
            local=(((2, 2), bytes((shade, 0, 0, 0)) * 4) if point is not None else None),
        )

    async def fake_snapshot(*a, **kw):
        return [], "", None, state.clickables

    async def fake_verify_typed(text):
        if isinstance(state.typed_lands, list):
            return state.typed_lands.pop(0) if state.typed_lands else None
        return state.typed_lands

    async def fake_verify_click_focus_point(x, y, **kwargs):
        return state.focus_hit

    monkeypatch.setattr(
        engine_mod,
        "select_capture_target",
        fake_select_capture_target,
    )
    monkeypatch.setattr(engine_mod, "list_monitors", lambda: [MONITOR])
    monkeypatch.setattr(engine_mod, "capture_stable_frame", fake_capture)
    monkeypatch.setattr(engine_mod, "grab_region", fake_grab_region)
    monkeypatch.setattr(engine_mod, "grab_visual_probe", fake_visual_probe)
    monkeypatch.setattr(engine_mod, "foreground_ui_snapshot", fake_snapshot)
    monkeypatch.setattr(engine_mod, "verify_typed_text", fake_verify_typed)
    monkeypatch.setattr(
        engine_mod,
        "verify_click_focus_point",
        fake_verify_click_focus_point,
    )
    monkeypatch.setattr(engine_mod, "_foreground_title", lambda: "Test Window")
    # The per-action permission guard reads the LIVE TCC state and the window list: on
    # a macOS dev machine without a grant it would refuse every dispatched action.
    # The guard's own tests drive ``_dispatch_tool`` through a FakeTCC world instead.
    monkeypatch.setattr(engine_mod, "_blocked_before_dispatch", lambda: None)
    # The engine normalizes the target window via dodaios.platform.window_state;
    # tests must never maximize a real window on the dev machine.
    from dodaios.platform import window_state as ws

    monkeypatch.setattr(
        ws,
        "normalize_foreground_window",
        lambda: (False, "test"),
    )
    monkeypatch.setattr(
        ws,
        "foreground_window",
        lambda: ws.WindowInfo(
            "Test Window",
            handle=state.foreground_handle,
            pid=state.foreground_pid,
        ),
    )
    monkeypatch.setattr(
        ws,
        "window_frame_rect",
        lambda _window: state.foreground_rect,
    )
    return state


async def _run(ctx) -> list:
    task = SimpleNamespace(prompt="open the thing", env={}, timeout_s=60)
    return [chunk async for chunk in engine_mod.run_cu_loop(task, ctx, cancel_token=None)]


def _final(chunks):
    finals = [c for c in chunks if c.is_final]
    assert len(finals) == 1
    return finals[0]


@pytest.mark.asyncio
async def test_effect_wait_requires_persistent_local_change(monkeypatch):
    pre_probe = VisualProbe(bytes((30,)) * (96 * 54), ((2, 2), b"a" * 16))
    post_probe = VisualProbe(None, ((2, 2), b"b" * 16))
    replies = iter((post_probe, post_probe))
    monkeypatch.setattr(
        engine_mod,
        "grab_visual_probe",
        lambda _bbox, **_kwargs: next(replies),
    )

    _latest, local_same, global_changed, confirmed = await engine_mod._wait_for_visual_effect(
        pre_probe,
        MONITOR,
        timeout_s=0.35,
        point=(96, 54),
    )

    assert local_same is False
    assert global_changed is None
    assert confirmed is True


@pytest.mark.asyncio
async def test_transient_visual_delta_is_not_accepted(monkeypatch):
    pre = VisualProbe(bytes((30,)) * (96 * 54), ((2, 2), b"a" * 16))
    changed = VisualProbe(None, ((2, 2), b"b" * 16))
    unchanged = VisualProbe(bytes((30,)) * (96 * 54), ((2, 2), b"a" * 16))
    replies = [changed, unchanged]

    monkeypatch.setattr(
        engine_mod,
        "grab_visual_probe",
        lambda _bbox, **_kwargs: replies.pop(0) if replies else unchanged,
    )
    monkeypatch.setattr(engine_mod, "_EFFECT_POLL_S", 0.0)

    _latest, local_same, global_changed, confirmed = await engine_mod._wait_for_visual_effect(
        pre,
        MONITOR,
        timeout_s=0.001,
        point=(96, 54),
    )

    assert local_same is True
    assert global_changed is False
    assert confirmed is False


@pytest.mark.asyncio
async def test_missing_confirmation_does_not_leak_global_delta(monkeypatch):
    pre = VisualProbe(bytes((30,)) * (96 * 54), ((2, 2), b"a" * 16))
    changed = VisualProbe(bytes((90,)) * (96 * 54), ((2, 2), b"a" * 16))
    replies = iter((changed, None))

    monkeypatch.setattr(
        engine_mod,
        "grab_visual_probe",
        lambda _bbox, **_kwargs: next(replies),
    )

    _latest, local_same, global_changed, confirmed = await engine_mod._wait_for_visual_effect(
        pre,
        MONITOR,
        timeout_s=0.0,
        point=(96, 54),
    )

    assert local_same is None
    assert global_changed is None
    assert confirmed is False


@pytest.mark.asyncio
async def test_open_app_wait_returns_on_foreground_transition(monkeypatch):
    signatures = iter((("window", 1), ("window", 2)))

    async def live_signature():
        return next(signatures)

    monkeypatch.setattr(engine_mod, "_live_window_state_signature", live_signature)
    monkeypatch.setattr(engine_mod, "_EFFECT_POLL_S", 0.0)

    assert await engine_mod._wait_for_foreground_transition(
        ("window", 1),
        timeout_s=1.0,
    )


# ---------------------------------------------------------------------------


async def test_done_is_verified_and_proof_flows_to_stdout(patched):
    brain = FakeBrain(
        [
            '{"action": "done", "reason": "it is visible"}',  # decide
            '{"done": true, "proof": "the calculator shows 8"}',  # judge
        ]
    )
    chunks = await _run(_ctx(brain, FakeExecutor()))
    final = _final(chunks)
    assert final.exit_code == 0
    assert "[cu] done (verified: the calculator shows 8)" in final.stdout


async def test_recent_missions_reach_the_decide_prompt_but_not_the_judge(patched):
    """Follow-up context (BUG-105): a corrective goal ('do it in my Chrome
    browser') starts a mission that is blind to the conversation. The engine
    folds the registry's recently finished runs into the DECIDE prompt so
    the operator can resolve what the elliptical goal refers to — while the
    done-judge keeps verifying strictly against the goal alone, so a prior
    mission's outcome can never count as proof for this one."""
    from dodaios.harness import cu_run_registry

    cu_run_registry.clear_runs()
    cu_run_registry.register_run(
        "prior1",
        "open the newest post of the profile on x.com",
        None,
    )
    cu_run_registry.finish_run(
        "prior1",
        "finished",
        exit_code=0,
        result_text="[cu] done (verified: post visible in Safari)",
    )
    try:
        brain = FakeBrain(
            [
                '{"action": "done", "reason": "it is visible"}',  # decide
                '{"done": true, "proof": "the post is open"}',  # judge
            ]
        )
        chunks = await _run(_ctx(brain, FakeExecutor()))
        final = _final(chunks)
        assert final.exit_code == 0
        decide_user = brain.calls[0][1]
        assert "EARLIER DESKTOP MISSIONS" in decide_user
        assert "open the newest post of the profile" in decide_user
        assert "post visible in Safari" in decide_user
        judge_user = brain.calls[-1][1]
        assert "EARLIER DESKTOP MISSIONS" not in judge_user
    finally:
        cu_run_registry.clear_runs()


def _darwin_world(monkeypatch, **tcc_kwargs):
    """A darwin FakeTCC behind the REAL port; the process-wide service reads it.

    The engine itself never asks macOS: an unanswered dialog makes any unexpected
    prompt visible as a ``request`` in the call log. Nothing here ran on a real
    Mac; FakeTCC models the OS.
    """
    from tests.fakes.fake_tcc import DialogPolicy, FakeTCC, install_port

    tcc_kwargs.setdefault("default_policy", DialogPolicy.NEVER_ANSWERED)
    tcc = FakeTCC(**tcc_kwargs)
    install_port(monkeypatch, tcc.port("darwin"))
    monkeypatch.setattr(engine_mod, "_frontmost_system_consent_owner", lambda: "")
    return tcc


async def test_dispatch_refuses_action_after_screen_permission_revocation(monkeypatch):
    tcc = _darwin_world(monkeypatch, granted=("accessibility",))  # Screen Recording is off
    executor = FakeExecutor()
    ctx = _ctx(FakeBrain([]), executor)

    ok, detail = await engine_mod._dispatch_tool(
        ctx,
        "click",
        {"x": 10, "y": 10},
        trace_id=None,
    )

    assert ok is False
    # The agent-facing refusal: the prefix the loop maps, prohibitive, no paths.
    assert detail.startswith("[permission_needed:screen_recording] ")
    assert "must not retry" in detail
    assert executor.calls == []
    # The gate is silent: it never asks macOS (no dialog, no implicit prompt).
    assert tcc.requests() == []
    assert tcc.implicit_prompts() == []


async def test_dispatch_sees_a_screen_recording_grant_given_mid_session(monkeypatch):
    # The per-process preflight is frozen (BUG-161); the deep read's window-title
    # oracle must still see the grant the user flipped on while Jarvis runs.
    tcc = _darwin_world(monkeypatch)
    executor = FakeExecutor()
    ctx = _ctx(FakeBrain([]), executor)
    first, _detail = await engine_mod._dispatch_tool(ctx, "click", {"x": 1, "y": 1}, None)
    assert first is False

    tcc.grant("screen_recording")
    second, _detail = await engine_mod._dispatch_tool(ctx, "click", {"x": 1, "y": 1}, None)

    assert second is True
    assert [name for name, _args in executor.calls] == ["click"]
    assert tcc.requests() == []


async def test_dispatch_refuses_after_a_proven_screen_recording_grant_is_revoked(monkeypatch):
    # The remembered proof of a grant must not defeat the blind-input guard: the gate
    # reads deep, so a revoke that lands between two actions is seen on the next one.
    tcc = _darwin_world(monkeypatch)
    executor = FakeExecutor()
    ctx = _ctx(FakeBrain([]), executor)
    tcc.grant("screen_recording")  # the preflight stays frozen negative; the oracle proves it
    ok, _detail = await engine_mod._dispatch_tool(ctx, "click", {"x": 1, "y": 1}, None)
    assert ok is True

    tcc.deny("screen_recording")
    ok, detail = await engine_mod._dispatch_tool(ctx, "click", {"x": 1, "y": 1}, None)

    assert ok is False
    assert detail.startswith("[permission_needed:screen_recording] ")
    assert [name for name, _args in executor.calls] == ["click"]  # only the first one ran
    assert tcc.requests() == []


async def test_dispatch_pauses_while_a_system_consent_dialog_is_frontmost(monkeypatch):
    tcc = _darwin_world(monkeypatch, granted=("screen_recording", "accessibility"))
    monkeypatch.setattr(engine_mod, "_frontmost_system_consent_owner", lambda: "SecurityAgent")
    executor = FakeExecutor()
    ctx = _ctx(FakeBrain([]), executor)

    ok, detail = await engine_mod._dispatch_tool(ctx, "key", {}, None)
    ok_click, _detail_click = await engine_mod._dispatch_tool(ctx, "click", {"x": 5, "y": 5}, None)

    assert ok is False and ok_click is False
    assert detail.startswith("[permission_needed:system_dialog] ")
    assert "must not try to answer" in detail
    assert "SecurityAgent" not in detail  # no window or owner names in agent text
    assert executor.calls == []  # an AI agent never answers a system dialog
    assert tcc.requests() == []


async def test_dispatch_gate_is_read_only_through_an_injected_gate(monkeypatch):
    # The engine gate only READS (``check_deep`` or ``check``) and records a
    # background episode: it never makes an interactive request.
    from tests.fakes.fake_permission_service import FakePermissionService

    gate = FakePermissionService({"screen_recording": "needs_settings"})
    monkeypatch.setattr(engine_mod, "_permission_gate", lambda: gate)
    executor = FakeExecutor()

    ok, detail = await engine_mod._dispatch_tool(
        _ctx(FakeBrain([]), executor), "click", {"x": 5, "y": 5}, None
    )

    assert ok is False and detail.startswith("[permission_needed:screen_recording] ")
    assert executor.calls == []
    assert gate.native_free()  # nothing interactive: no call could have made macOS ask
    assert all(not call.interactive for call in gate.ensure_calls())


async def test_dispatch_proceeds_when_no_system_dialog_is_frontmost(monkeypatch):
    _darwin_world(monkeypatch, granted=("screen_recording", "accessibility"))
    monkeypatch.setattr(engine_mod, "_frontmost_system_consent_owner", lambda: "")
    executor = FakeExecutor()

    ok, _detail = await engine_mod._dispatch_tool(
        _ctx(FakeBrain([]), executor), "click", {"x": 5, "y": 5}, None
    )

    assert ok is True
    assert [name for name, _args in executor.calls] == ["click"]


async def test_dispatch_refuses_on_macos_when_the_guard_itself_fails(monkeypatch):
    _darwin_world(monkeypatch, granted=("screen_recording",))
    monkeypatch.setattr(engine_mod.sys, "platform", "darwin")

    def _boom() -> str:
        raise RuntimeError("window list exploded")

    monkeypatch.setattr(engine_mod, "_frontmost_system_consent_owner", _boom)
    executor = FakeExecutor()

    ok, detail = await engine_mod._dispatch_tool(
        _ctx(FakeBrain([]), executor), "click", {"x": 5, "y": 5}, None
    )

    assert ok is False and detail.startswith("[permission_needed:")
    assert "exploded" not in detail  # no exception text in agent-facing text
    assert executor.calls == []


@pytest.mark.parametrize("platform", ["linux", "win32"])
async def test_dispatch_off_macos_asks_nothing_and_changes_nothing(monkeypatch, platform):
    from tests.fakes.fake_tcc import FakeTCC, install_port

    tcc = FakeTCC()
    install_port(monkeypatch, tcc.port(platform))
    monkeypatch.setattr(engine_mod, "sys", SimpleNamespace(platform=platform))
    executor = FakeExecutor()

    ok, _detail = await engine_mod._dispatch_tool(
        _ctx(FakeBrain([]), executor), "click", {"x": 5, "y": 5}, None
    )

    assert ok is True and [name for name, _args in executor.calls] == ["click"]
    tcc.assert_silent()


async def test_rejected_done_feeds_history_and_eventually_fails(patched):
    brain = FakeBrain(
        [
            '{"action": "done", "reason": "sure"}',
            '{"done": false, "proof": "the window is not open"}',
        ]
        * 3,
    )
    chunks = await _run(_ctx(brain, FakeExecutor()))
    final = _final(chunks)
    assert final.exit_code == 5
    assert "could not be verified" in final.stderr
    # The judge's rejection reached the model as history.
    assert any("done REJECTED" in user for (_, user) in brain.calls)


async def test_duplicate_click_on_unchanged_screen_is_refused(patched):
    patched.region_changes_after_click = True
    brain = FakeBrain(
        [
            '{"action": "click", "x": 500, "y": 500, "target": "play"}',
            '{"action": "click", "x": 502, "y": 498, "target": "play"}',  # same spot
            '{"action": "done", "reason": "toggled"}',
            '{"done": true, "proof": "playback is running"}',
        ]
    )
    executor = FakeExecutor()
    chunks = await _run(_ctx(brain, executor))
    final = _final(chunks)
    assert final.exit_code == 0
    clicks = [c for c in executor.calls if c[0] == "click"]
    assert len(clicks) == 1, "the near-identical re-click must be refused"
    assert any("REFUSED" in user for (_, user) in brain.calls)


async def test_type_that_does_not_land_blocks_the_rest_of_the_batch(patched):
    patched.typed_lands = False
    brain = FakeBrain(
        [
            # Blind batch: type + enter. The type read-back fails -> enter must NOT run.
            '[{"action":"type","text":"https://example.com"},{"action":"key","keys":["enter"]}]',
            '{"action": "fail", "reason": "cannot focus the address bar"}',
        ]
    )
    executor = FakeExecutor()
    chunks = await _run(_ctx(brain, executor))
    final = _final(chunks)
    assert final.exit_code == 5
    tool_names = [name for (name, _) in executor.calls]
    assert "type_text" in tool_names
    assert "hotkey" not in tool_names, "enter after a failed type is the blind-action bug"
    assert any("did NOT land" in user for (_, user) in brain.calls)


async def test_second_pointer_action_in_one_batch_is_skipped(patched):
    brain = FakeBrain(
        [
            '[{"action":"click","x":100,"y":100},{"action":"click","x":900,"y":900}]',
            '{"action": "done", "reason": "clicked"}',
            '{"done": true, "proof": "both dialogs handled"}',
        ]
    )
    executor = FakeExecutor()
    chunks = await _run(_ctx(brain, executor))
    assert _final(chunks).exit_code == 0
    clicks = [c for c in executor.calls if c[0] == "click"]
    assert len(clicks) == 1, "a second stale-frame pointer action must not execute"
    assert any("only one pointer action" in user for (_, user) in brain.calls)


async def test_click_then_click_element_in_one_batch_is_skipped(patched):
    brain = FakeBrain(
        [
            '[{"action":"click","x":100,"y":100},{"action":"click_element","name":"Continue"}]',
            '{"action": "done", "reason": "clicked"}',
            '{"done": true, "proof": "the dialog advanced"}',
        ]
    )
    executor = FakeExecutor()

    chunks = await _run(_ctx(brain, executor))

    assert _final(chunks).exit_code == 0
    assert [name for name, _args in executor.calls].count("click") == 1
    assert not any(name == "click_element" for name, _args in executor.calls)
    assert any("only one pointer action" in user for _system, user in brain.calls)


async def test_foreground_change_after_model_decision_refuses_action(patched):
    class _FocusChangingBrain(FakeBrain):
        async def complete_text(self, *, system: str, user: str) -> str:
            reply = await super().complete_text(system=system, user=user)
            if len(self.calls) == 1:
                patched.foreground_handle = 22
            return reply

    brain = _FocusChangingBrain(
        [
            '{"action":"click","x":500,"y":500}',
            '{"action":"fail","reason":"the target window changed"}',
        ]
    )
    executor = FakeExecutor()

    chunks = await _run(_ctx(brain, executor))

    assert _final(chunks).exit_code == 5
    assert executor.calls == []
    assert any("foreground window changed" in user for _system, user in brain.calls)


async def test_same_app_window_swap_before_first_action_refuses(patched):
    # macOS app-identity signatures stay WINDOW-precise: a second top-level
    # window of the SAME app stealing focus between screenshot and the FIRST
    # action must refuse exactly like a cross-app steal (reviewer regression
    # for the 2026-07-20 signature redesign).
    patched.foreground_pid = 812

    class _FocusChangingBrain(FakeBrain):
        async def complete_text(self, *, system: str, user: str) -> str:
            reply = await super().complete_text(system=system, user=user)
            if len(self.calls) == 1:
                patched.foreground_handle = 22  # same app, different window
            return reply

    brain = _FocusChangingBrain(
        [
            '{"action":"click","x":500,"y":500}',
            '{"action":"fail","reason":"the target window changed"}',
        ]
    )
    executor = FakeExecutor()

    chunks = await _run(_ctx(brain, executor))

    assert _final(chunks).exit_code == 5
    assert executor.calls == []
    assert any("foreground window changed" in user for _system, user in brain.calls)


async def test_same_app_churn_after_own_click_rebaselines_and_type_proceeds(patched):
    # The live 2026-07-20 failure loop: the click makes a same-app dropdown
    # the frontmost layer-0 window; the batched type must STILL land instead
    # of "REFUSED — the foreground window changed after the screenshot".
    patched.foreground_pid = 812
    state = patched

    class _ChurningExecutor(FakeExecutor):
        async def execute(self, tool, args, *, user_utterance, trace_id):
            result = await super().execute(
                tool,
                args,
                user_utterance=user_utterance,
                trace_id=trace_id,
            )
            if tool["name"] == "click":
                state.foreground_handle = 5177  # dropdown became frontmost
            return result

    brain = FakeBrain(
        [
            '[{"action":"click","x":500,"y":500},{"action":"type","text":"https://example.com"}]',
            '{"action":"fail","reason":"stop here"}',
        ]
    )
    executor = _ChurningExecutor()

    chunks = await _run(_ctx(brain, executor))

    _final(chunks)
    tool_names = [name for (name, _) in executor.calls]
    assert "click" in tool_names
    assert "type_text" in tool_names, (
        "same-app churn caused by our own click must not behead the batch"
    )


async def test_cross_app_steal_after_own_click_still_refuses_type(patched):
    # The relaxation is app-scoped only: a DIFFERENT app taking over after
    # our click still breaks the batch before the type.
    patched.foreground_pid = 812
    state = patched

    class _StealingExecutor(FakeExecutor):
        async def execute(self, tool, args, *, user_utterance, trace_id):
            result = await super().execute(
                tool,
                args,
                user_utterance=user_utterance,
                trace_id=trace_id,
            )
            if tool["name"] == "click":
                state.foreground_handle = 9001
                state.foreground_pid = 990  # another app stole focus
            return result

    brain = FakeBrain(
        [
            '[{"action":"click","x":500,"y":500},{"action":"type","text":"https://example.com"}]',
            '{"action":"fail","reason":"stop here"}',
        ]
    )
    executor = _StealingExecutor()

    chunks = await _run(_ctx(brain, executor))

    _final(chunks)
    tool_names = [name for (name, _) in executor.calls]
    assert "click" in tool_names
    assert "type_text" not in tool_names, (
        "typing after a cross-app focus steal is the blind-input bug"
    )


async def test_foreground_change_during_capture_discards_stale_frame(
    patched,
    monkeypatch,
):
    from dodaios.platform import window_state as ws

    handles = iter((11, 22, 22, 22))
    monkeypatch.setattr(
        ws,
        "foreground_window",
        lambda: ws.WindowInfo("Test Window", handle=next(handles, 22)),
    )
    brain = FakeBrain(
        [
            '{"action":"fail","reason":"fresh frame reached the model"}',
        ]
    )
    executor = FakeExecutor()

    chunks = await _run(_ctx(brain, executor))

    assert _final(chunks).exit_code == 5
    assert patched.capture_calls == 2
    assert len(brain.calls) == 1
    assert executor.calls == []


async def test_coordinate_less_scroll_targets_capture_center_and_stales_batch(patched):
    brain = FakeBrain(
        [
            '[{"action":"scroll","direction":"down","amount":2},'
            '{"action":"click","x":900,"y":900}]',
            '{"action": "done", "reason": "scrolled"}',
            '{"done": true, "proof": "the target is visible"}',
        ]
    )
    executor = FakeExecutor()

    chunks = await _run(_ctx(brain, executor))

    assert _final(chunks).exit_code == 0
    scrolls = [args for name, args in executor.calls if name == "scroll"]
    assert scrolls == [
        {
            "direction": "down",
            "amount": 2,
            "x": 96,
            "y": 54,
            "_expected_window_signature": ("handle", 11, (0, 0, 192, 108)),
        }
    ]
    assert not any(name == "click" for name, _args in executor.calls)
    assert any("only one pointer action" in user for _system, user in brain.calls)


async def test_ineffective_scroll_fails_with_keyboard_hint(patched):
    # Live run 2026-07-18 07:47 (Gmail unsubscribe hunt): the wheel event was
    # dispatched but the reading pane never moved. The old engine recorded a
    # phantom "scroll ok"; every retry was then silently refused as a ledger
    # duplicate and the mission died as an opaque "no progress". An
    # ineffective scroll must FAIL with actionable feedback so the model can
    # switch to keyboard scrolling — and that keyboard fallback must run.
    patched.region_changes_after_click = False  # pre == post → no effect
    brain = FakeBrain(
        [
            '{"action":"scroll","direction":"down","amount":5}',
            '{"action":"key","keys":["pagedown"]}',
            '{"action": "done", "reason": "scrolled"}',
            '{"done": true, "proof": "the unsubscribe link is visible"}',
        ]
    )
    executor = FakeExecutor()

    chunks = await _run(_ctx(brain, executor))

    assert _final(chunks).exit_code == 0
    assert any("NO visible effect" in user for _system, user in brain.calls), (
        "the model must be told the scroll did not move anything"
    )
    assert any(name == "hotkey" for name, _args in executor.calls), (
        "the keyboard fallback the hint suggests must not be blocked"
    )


async def test_repeated_ineffective_scroll_aborts_with_honest_reason(patched):
    # Worst case: the model stubbornly re-issues the same dead scroll. The
    # abort must carry the real cause (scroll had no effect) instead of the
    # bare "no progress" the voice layer previously embroidered into a
    # fabricated story ("the unsubscribe link did not work").
    patched.region_changes_after_click = False
    brain = FakeBrain(['{"action":"scroll","direction":"down","amount":5}'] * 6)
    executor = FakeExecutor()

    chunks = await _run(_ctx(brain, executor))

    final = _final(chunks)
    assert final.exit_code == 5
    assert "NO visible effect" in final.stderr, (
        "the no-progress abort must name the last real attempts"
    )
    scrolls = [name for name, _args in executor.calls if name == "scroll"]
    assert len(scrolls) >= 2, (
        "retrying an ineffective scroll must stay allowed (no silent ledger "
        "refusal) so the failure surfaces as FAILED feedback instead"
    )


async def test_done_judge_reuses_the_step_frame_when_no_action_ran(patched):
    # "Say you are done FAST": when `done` arrives before any action of the
    # batch executed, the screen is exactly the frame the model saw — the
    # judge must verify against THAT frame instead of paying a second
    # stability capture (live complaint 2026-07-02: the completion
    # confirmation took too long).
    brain = FakeBrain(
        [
            '{"action": "done", "reason": "goal visible"}',
            '{"done": true, "proof": "the channel is open"}',
        ]
    )
    executor = FakeExecutor()
    chunks = await _run(_ctx(brain, executor))
    assert _final(chunks).exit_code == 0
    assert patched.capture_calls == 1, (
        "the done-judge must reuse the perception frame, not recapture"
    )


async def test_done_judge_recaptures_after_batch_actions(patched):
    # After any executed action the screen may differ from the perception
    # frame — the judge must then verify against a FRESH capture.
    brain = FakeBrain(
        [
            '[{"action":"key","keys":["enter"]},{"action":"done","reason":"submitted"}]',
            '{"done": true, "proof": "the form is submitted"}',
        ]
    )
    executor = FakeExecutor()
    chunks = await _run(_ctx(brain, executor))
    assert _final(chunks).exit_code == 0
    assert patched.capture_calls == 2, "a done after executed actions needs a fresh judge frame"


async def test_click_on_already_focused_target_passes_and_type_proceeds(patched):
    # Live incident 2026-07-02 19:06 (Chrome guest new-tab): the address bar
    # is focused BY DEFAULT, so clicking it changes zero pixels. The pixel
    # effect-check alone judged that a miss, truncated the batched type, and
    # the mission stalled AT its goal. Focus evidence must rescue the click.
    patched.region_changes_after_click = False
    patched.focus_hit = True  # the click point sits in the focused control
    brain = FakeBrain(
        [
            '[{"action":"click","x":300,"y":88,"target":"address bar"},'
            '{"action":"type","text":"weather berlin"}]',
            '{"action": "done", "reason": "typed the search"}',
            '{"done": true, "proof": "the address bar shows weather berlin"}',
        ]
    )
    executor = FakeExecutor()
    chunks = await _run(_ctx(brain, executor))
    assert _final(chunks).exit_code == 0
    tool_names = [name for (name, _) in executor.calls]
    assert "click" in tool_names
    assert "type_text" in tool_names, (
        "a click on an already-focused target must not behead the batch"
    )
    assert not any("NO visible change" in user for (_, user) in brain.calls)


async def test_type_false_verdict_is_rechecked_once_before_failing(patched):
    # Async UI surfaces (UWP flyouts, start menu) commit the typed value
    # LATER than the injection returns — the first read-back sees stale
    # state (live incident 2026-07-02 18:00). One re-check absorbs that.
    patched.typed_lands = [False, True]
    brain = FakeBrain(
        [
            '{"action":"type","text":"spotify"}',
            '{"action": "done", "reason": "typed"}',
            '{"done": true, "proof": "the search shows spotify"}',
        ]
    )
    executor = FakeExecutor()
    chunks = await _run(_ctx(brain, executor))
    assert _final(chunks).exit_code == 0
    assert not any("did NOT land" in user for (_, user) in brain.calls)


async def test_missed_click_no_visible_change_is_reported_as_failure(patched):
    patched.region_changes_after_click = False  # click voids: nothing changes
    brain = FakeBrain(
        [
            '{"action": "click", "x": 500, "y": 500, "target": "button"}',
            '{"found": false}',  # the zoom-refine probe finds nothing either
            '{"action": "fail", "reason": "the button does not react"}',
        ]
    )
    executor = FakeExecutor()
    chunks = await _run(_ctx(brain, executor))
    final = _final(chunks)
    assert final.exit_code == 5
    assert any("NO visible change" in user for (_, user) in brain.calls)


async def test_clear_first_sends_platform_select_all(patched):
    brain = FakeBrain(
        [
            '{"action":"type","text":"example.com","clear_first":true}',
            '{"action": "done", "reason": "typed"}',
            '{"done": true, "proof": "the address bar shows example.com"}',
        ]
    )
    executor = FakeExecutor()
    chunks = await _run(_ctx(brain, executor))
    assert _final(chunks).exit_code == 0
    hotkeys = [args for (name, args) in executor.calls if name == "hotkey"]
    assert hotkeys and hotkeys[0]["keys"][-1] == "a"
    assert hotkeys[0]["_expected_window_signature"] == (
        "handle",
        11,
        (0, 0, 192, 108),
    )


async def test_clear_first_aborts_typing_when_select_all_fails(patched):
    brain = FakeBrain(
        [
            '{"action":"type","text":"replacement","clear_first":true}',
            '{"action":"fail","reason":"keyboard shortcut unavailable"}',
        ]
    )
    executor = FakeExecutor(failures={"hotkey"})

    chunks = await _run(_ctx(brain, executor))

    assert _final(chunks).exit_code == 5
    assert not any(name == "type_text" for name, _args in executor.calls)
    assert any("refusing to append" in user for _system, user in brain.calls)


async def test_cancelled_token_stops_immediately(patched):
    token = SimpleNamespace(is_cancelled=lambda: True, reason="hangup")
    brain = FakeBrain([])
    task = SimpleNamespace(prompt="anything", env={}, timeout_s=60)
    chunks = [
        c
        async for c in engine_mod.run_cu_loop(
            task,
            _ctx(brain, FakeExecutor()),
            cancel_token=token,
        )
    ]
    final = _final(chunks)
    assert final.exit_code == 130
    assert "[cu] cancelled" in final.stderr
    assert not brain.calls


async def test_unparseable_replies_exhaust_llm_budget(patched):
    brain = FakeBrain(["gibberish", "more gibberish", "still gibberish"])
    chunks = await _run(_ctx(brain, FakeExecutor()))
    final = _final(chunks)
    assert final.exit_code == 2


async def test_tool_failures_exhaust_consecutive_budget(patched):
    brain = FakeBrain(
        ['{"action":"open_app","name":"spotify"}'] * 8,
    )
    executor = FakeExecutor(failures={"open_app"})
    chunks = await _run(_ctx(brain, executor))
    final = _final(chunks)
    # Either the consecutive-failure cap (8) or the duplicate guard (5) ends
    # it — both are honest failures, never silent grinding.
    assert final.exit_code in (5, 8)


async def test_click_is_anchored_to_containing_element_center(patched):
    # Model points a few px off inside a small button whose center is
    # (145, 87): the dispatched click must hit the CENTER, not the estimate.
    patched.clickables = [("Send", "Button", (130, 80, 30, 14))]
    brain = FakeBrain(
        [
            # norm (740, 787) on the 192x108 monitor -> raw point (142, 85).
            '{"action": "click", "x": 740, "y": 787, "target": "Send"}',
            '{"action": "done", "reason": "sent"}',
            '{"done": true, "proof": "the message shows as sent"}',
        ]
    )
    executor = FakeExecutor()
    chunks = await _run(_ctx(brain, executor))
    assert _final(chunks).exit_code == 0
    clicks = [args for (name, args) in executor.calls if name == "click"]
    assert clicks and (clicks[0]["x"], clicks[0]["y"]) == (145, 87)


async def test_container_sized_elements_never_snap(patched):
    # A rect covering most of the capture is a container — the raw point
    # must be kept.
    patched.clickables = [("Body", "Text", (0, 0, 190, 100))]
    brain = FakeBrain(
        [
            '{"action": "click", "x": 500, "y": 500, "target": "middle"}',
            '{"action": "done", "reason": "ok"}',
            '{"done": true, "proof": "clicked"}',
        ]
    )
    executor = FakeExecutor()
    chunks = await _run(_ctx(brain, executor))
    assert _final(chunks).exit_code == 0
    clicks = [args for (name, args) in executor.calls if name == "click"]
    assert clicks and (clicks[0]["x"], clicks[0]["y"]) == (96, 54)


async def test_verified_miss_triggers_one_zoom_refined_retry(patched):
    patched.region_changes_after_click = False  # every click: no visible change
    brain = FakeBrain(
        [
            '{"action": "click", "x": 500, "y": 500, "target": "tiny icon"}',
            # The zoom-refine call answers with a corrected in-crop position.
            '{"found": true, "x": 900, "y": 900}',
            '{"action": "fail", "reason": "the icon does not react"}',
        ]
    )
    executor = FakeExecutor()
    chunks = await _run(_ctx(brain, executor))
    final = _final(chunks)
    assert final.exit_code == 5
    clicks = [args for (name, args) in executor.calls if name == "click"]
    assert len(clicks) == 2, "exactly one refined retry after the verified miss"
    assert (clicks[1]["x"], clicks[1]["y"]) != (clicks[0]["x"], clicks[0]["y"])
    assert all(args["_expected_window_signature"][0:2] == ("handle", 11) for args in clicks)


async def test_zoom_refine_refuses_click_after_foreground_switch(patched):
    patched.region_changes_after_click = False

    class _SwitchDuringRefineBrain(FakeBrain):
        async def complete_text(self, *, system: str, user: str) -> str:
            reply = await super().complete_text(system=system, user=user)
            if len(self.calls) == 2:
                patched.foreground_handle = 22
            return reply

    brain = _SwitchDuringRefineBrain(
        [
            '{"action": "click", "x": 500, "y": 500, "target": "tiny icon"}',
            '{"found": true, "x": 900, "y": 900}',
            '{"action": "fail", "reason": "the original window lost focus"}',
        ]
    )
    executor = FakeExecutor()

    chunks = await _run(_ctx(brain, executor))

    assert _final(chunks).exit_code == 5
    clicks = [args for name, args in executor.calls if name == "click"]
    assert len(clicks) == 1, "the stale zoom-refined click must not execute"


async def test_handoff_screen_fails_fast_with_speakable_reason(patched, monkeypatch):
    async def snapshot_with_captcha(*a, **kw):
        return [], "", "captcha challenge", []

    monkeypatch.setattr(engine_mod, "foreground_ui_snapshot", snapshot_with_captcha)
    brain = FakeBrain([])
    chunks = await _run(_ctx(brain, FakeExecutor()))
    final = _final(chunks)
    assert final.exit_code == 5
    assert "captcha challenge" in final.stderr
    assert not brain.calls, "no model call may happen on a handoff screen"


# ---------------------------------------------------------------------------
# Patience vs. dead end (AU-16). Waiting for a page to load, a download to
# finish or an installer to run looks EXACTLY like being stuck. A deliberate
# wait is progress and must survive the no-progress guard; unbounded waiting
# on a frozen screen must still die.
# ---------------------------------------------------------------------------


async def test_deliberate_wait_is_not_a_fruitless_step(patched):
    # Five waits in a row on a screen that never changes — more than
    # _STUCK_FRAMES. Before AU-16 the third one killed the mission as "no
    # progress"; a mission that patiently waits out a load must reach its goal.
    assert engine_mod._STUCK_FRAMES < 5, "the scenario must exceed the guard"
    brain = FakeBrain(
        ['{"action": "wait", "ms": 1}'] * 5
        + [
            '{"action": "done", "reason": "the page finished loading"}',
            '{"done": true, "proof": "the page is loaded"}',
        ]
    )

    chunks = await _run(_ctx(brain, FakeExecutor()))

    final = _final(chunks)
    assert final.exit_code == 0, f"patience was killed: {final.stderr!r}"
    assert "no progress" not in final.stderr


async def test_waiting_forever_on_a_frozen_screen_still_aborts(patched):
    # The bound on patience: waits that change nothing accumulate, and once
    # _MAX_STALLED_WAITS of them pass in a row the mission ends honestly
    # instead of stalling until the mission timeout.
    brain = FakeBrain(['{"action": "wait", "ms": 1}'] * 20)

    chunks = await _run(_ctx(brain, FakeExecutor()))

    final = _final(chunks)
    assert final.exit_code == 5
    assert "no progress" in final.stderr
    assert "waited" in final.stderr, (
        f"the abort must name waiting as the cause, got: {final.stderr!r}"
    )
    waits = [c for c in chunks if "wait(" in (c.stdout or "")]
    assert len(waits) >= engine_mod._MAX_STALLED_WAITS, (
        "the mission must actually be allowed to wait before giving up"
    )


async def test_repeated_no_op_actions_still_abort_as_a_dead_end(patched):
    # The dead-end protection stays intact for genuinely fruitless steps: an
    # action that keeps failing on an unchanged screen ends the mission.
    brain = FakeBrain(['{"action": "click_element", "name": "Next"}'] * 8)
    executor = FakeExecutor(failures={"click_element"})

    chunks = await _run(_ctx(brain, executor))

    final = _final(chunks)
    assert final.exit_code in (5, 8), f"a dead end must abort: {final.stderr!r}"
    assert len(executor.calls) <= engine_mod._STUCK_FRAMES + 2, (
        "a dead end must be cut short, not retried indefinitely"
    )


async def test_spent_patience_budget_is_told_to_the_model(patched, monkeypatch):
    # Patience is also bounded in TIME, so waiting can never eat the whole
    # mission budget. Once spent, waits shrink to a beat and the model is told
    # in plain words that it has to act instead.
    monkeypatch.setattr(engine_mod, "_MAX_TOTAL_WAIT_S", 0.005)
    brain = FakeBrain(['{"action": "wait", "ms": 10}'] * 5)

    await _run(_ctx(brain, FakeExecutor()))

    assert any("patience budget" in user for _system, user in brain.calls), (
        "the model must learn that its waiting budget is spent"
    )


async def test_the_model_is_told_that_waiting_is_a_legitimate_move(patched):
    # A capability nobody is told about is useless: both the discipline block
    # and the action grammar must surface the wait action and when to use it.
    brain = FakeBrain(['{"action": "fail", "reason": "stop"}'])

    await _run(_ctx(brain, FakeExecutor()))

    system = brain.calls[0][0]
    assert '"action": "wait"' in system
    assert "still loading" in system
    assert "installer" in system


async def test_a_busy_screen_survives_more_than_two_observe_failures(patched, monkeypatch):
    # A page finishing its load or an installer opening its next window flips
    # the foreground mid-capture, which trips the capture identity guard. At
    # two tolerated failures a mission died after ~2 s of ordinary desktop
    # churn (AU-16); transient blindness must be ridden out, not fatal.
    real_capture = engine_mod.capture_stable_frame
    state = {"n": 0}

    def flaky_capture(monitor, **kw):
        state["n"] += 1
        if state["n"] <= 3:
            raise RuntimeError("foreground window changed during capture")
        return real_capture(monitor, **kw)

    monkeypatch.setattr(engine_mod, "capture_stable_frame", flaky_capture)
    brain = FakeBrain(
        [
            '{"action": "done", "reason": "the page finished loading"}',
            '{"done": true, "proof": "the page is loaded"}',
        ]
    )

    chunks = await _run(_ctx(brain, FakeExecutor()))

    final = _final(chunks)
    assert final.exit_code == 0, f"transient blindness was fatal: {final.stderr!r}"
    assert state["n"] > 3, "the retries must actually have happened"


async def test_a_screen_that_stays_unreadable_still_fails(patched, monkeypatch):
    # The honest counterpart: a screen that never becomes readable ends the
    # mission with the observe exit code instead of grinding to the budget.
    def dead_capture(monitor, **kw):
        raise RuntimeError("no display available")

    monkeypatch.setattr(engine_mod, "capture_stable_frame", dead_capture)

    chunks = await _run(_ctx(FakeBrain([]), FakeExecutor()))

    final = _final(chunks)
    assert final.exit_code == 1
    assert "cannot see the screen" in final.stderr


@pytest.mark.parametrize("refusal", ["pending", "denied"])
async def test_a_screen_recording_refusal_during_perception_is_terminal(
    patched, monkeypatch, refusal
):
    # The first perception frame of a mission is where Screen Recording is asked
    # for. The refusal is not flaky capture: no retries, a blocked_permission
    # ending with the people sentence and a single capture attempt.
    from dodaios.platform import screen_access
    from dodaios.platform.permissions import PermissionState

    attempts: list[int] = []

    def refused_capture(monitor, **kw):
        attempts.append(1)
        if refusal == "pending":
            raise screen_access.refusal_pending()
        raise screen_access.refusal_for_state(PermissionState.DENIED)

    monkeypatch.setattr(engine_mod, "capture_stable_frame", refused_capture)

    chunks = await _run(_ctx(FakeBrain([]), FakeExecutor()))

    final = _final(chunks)
    assert final.exit_code == 8
    assert "blocked_permission" in final.stderr
    assert "Screen Recording" in final.stderr
    assert "You must not" not in final.stderr
    assert "[permission_needed:" not in final.stderr
    assert "cannot see the screen" not in final.stderr
    assert len(attempts) == 1


# ---- a permission refusal is TERMINAL (blocked_permission), never a model retry loop ----


class _RefusingExecutor(FakeExecutor):
    """A tool layer whose input tools answer with the permission layer's agent text."""

    def __init__(self, error: str, tool_names: set[str] | None = None) -> None:
        super().__init__()
        self.error = error
        self.tool_names = tool_names

    async def execute(self, tool, args, *, user_utterance, trace_id):
        name = tool["name"]
        self.calls.append((name, dict(args)))
        if self.tool_names is None or name in self.tool_names:
            return SimpleNamespace(success=False, output=None, error=self.error)
        return SimpleNamespace(success=True, output=f"{name} ok")


def _agent_refusal(permission: str = "accessibility") -> str:
    from dodaios.platform.permission_service import agent_detail_for
    from dodaios.platform.permissions import PermissionId

    return agent_detail_for(PermissionId(permission), "needs_settings")


async def test_a_permission_refusal_ends_the_mission_as_blocked_permission(patched):
    brain = FakeBrain(['{"action": "click", "x": 500, "y": 500, "target": "ok"}'] * 8)
    executor = _RefusingExecutor(_agent_refusal())

    chunks = await _run(_ctx(brain, executor))

    final = _final(chunks)
    # An existing terminal status carries a stable reason code (no new status value).
    assert final.exit_code == 8
    assert "blocked_permission" in final.stderr
    assert engine_mod.CU_REASON_BLOCKED_PERMISSION == "blocked_permission"
    # No model retry loop: one dispatch, one decide call, then the mission is over.
    assert [name for name, _args in executor.calls] == ["click"]
    assert len(brain.calls) == 1
    # People get a sentence from a fixed template, not the prohibitive agent text.
    assert "Accessibility" in final.stderr
    assert "You must not" not in final.stderr
    assert "[permission_needed:" not in final.stderr


async def test_a_wrapped_permission_refusal_is_still_terminal(patched):
    # clear_first wraps the hotkey error: "could not select ... : <detail>; refusing ...".
    brain = FakeBrain(
        ['{"action": "type", "text": "hello", "clear_first": true}'] * 8,
    )
    executor = _RefusingExecutor(_agent_refusal(), tool_names={"hotkey"})

    chunks = await _run(_ctx(brain, executor))

    final = _final(chunks)
    assert final.exit_code == 8 and "blocked_permission" in final.stderr
    assert [name for name, _args in executor.calls] == ["hotkey"]  # nothing was typed


async def test_a_system_dialog_refusal_is_terminal_and_names_no_permission(patched):
    from dodaios.cu import system_dialogs

    brain = FakeBrain(['{"action": "key", "keys": ["enter"]}'] * 8)
    executor = _RefusingExecutor(system_dialogs.agent_detail())

    chunks = await _run(_ctx(brain, executor))

    final = _final(chunks)
    assert final.exit_code == 8 and "blocked_permission" in final.stderr
    assert "system dialog" in final.stderr
    assert "You must not" not in final.stderr


class _ClickThenRefuseExecutor(FakeExecutor):
    """The first click lands (and misses); every later click is refused with ``error``."""

    def __init__(self, error: str) -> None:
        super().__init__()
        self.error = error

    async def execute(self, tool, args, *, user_utterance, trace_id):
        name = tool["name"]
        self.calls.append((name, dict(args)))
        clicks = [n for n, _a in self.calls if n == "click"]
        if name == "click" and len(clicks) > 1:
            return SimpleNamespace(success=False, output=None, error=self.error)
        return SimpleNamespace(success=True, output=f"{name} ok")


async def test_a_refused_zoom_refined_retry_ends_the_mission_without_another_model_call(patched):
    from dodaios.cu import system_dialogs

    patched.region_changes_after_click = False  # the first click misses
    brain = FakeBrain(
        [
            '{"action": "click", "x": 500, "y": 500, "target": "tiny icon"}',
            '{"found": true, "x": 900, "y": 900}',
            '{"action": "fail", "reason": "must never be asked"}',
        ]
    )
    executor = _ClickThenRefuseExecutor(system_dialogs.agent_detail())

    final = _final(await _run(_ctx(brain, executor)))

    # A dialog opened after the first click: the refine click is refused by the guard
    # and the mission is over, not a failure the model is asked about again.
    assert final.exit_code == 8 and "blocked_permission" in final.stderr
    assert "system dialog" in final.stderr
    assert [n for n, _a in executor.calls].count("click") == 2
    assert len(brain.calls) == 2  # decide + zoom-refine; no third (re-perceive) call


@pytest.mark.parametrize(
    ("reason", "asking"),
    [
        ("needs_settings", False),
        ("denied", False),
        ("not_determined", True),
        ("restart_hint", False),
        ("restricted", False),
        ("unavailable", False),
    ],
)
def test_the_user_sentence_follows_the_reason_the_refusal_carries(reason, asking):
    from dodaios.platform.permission_service import agent_detail_for, user_detail_for
    from dodaios.platform.permissions import PermissionId

    family = PermissionId.SCREEN_RECORDING
    sentence = engine_mod._permission_block(agent_detail_for(family, reason, asking=asking))

    assert sentence is not None
    assert "[permission_needed:" not in sentence and "You must not" not in sentence
    if reason in ("restricted", "unavailable"):
        # Nothing the user can switch on: an explanation, not "turn it on in Settings".
        assert sentence == user_detail_for(family, reason)
        assert "Then try the task again" not in sentence
    else:
        # not_determined shares its agent sentence with needs_settings: that wording wins.
        expected = "needs_settings" if reason == "not_determined" else reason
        assert sentence.startswith(user_detail_for(family, expected, asking=asking))
    if reason == "denied":
        assert "turned off" in sentence and sentence.endswith("Then try the task again.")


def test_the_guard_failure_refusal_is_explained_not_blamed_on_a_switch(monkeypatch):
    monkeypatch.setattr(engine_mod.sys, "platform", "darwin")

    sentence = engine_mod._permission_block(engine_mod._guard_failure_refusal() or "")

    assert sentence is not None
    assert "cannot ask for Screen Recording" in sentence
    assert "turn" not in sentence.lower() and "try the task again" not in sentence.lower()


def test_an_unknown_permission_token_gets_a_neutral_sentence():
    sentence = engine_mod._permission_block("[permission_needed:something_new] stop")

    assert sentence is not None and "System Settings" not in sentence


async def test_an_ordinary_tool_failure_is_not_a_permission_block(patched):
    brain = FakeBrain(['{"action":"open_app","name":"spotify"}'] * 8)
    executor = FakeExecutor(failures={"open_app"})

    final = _final(await _run(_ctx(brain, executor)))

    assert "blocked_permission" not in final.stderr