Stop CLI fallback after native pointer region refusal

Author: JE-Chen

CHANGELOG.md

@@ -13,6 +13,10 @@ it shipped into a `## [x.y.z] - date` section of their own; the tag's
 
 ## Unreleased
 
+- Refuse native Wayland pointer coordinates outside all EIS regions with
+  failed state and no automatic CLI fallback. A rejected move cannot emit
+  a subsequent click; valid mapping and explicit CLI selection are preserved.
+
 - Add passive input/capture capability snapshots to both SDK namespaces,
   AC_probe_capabilities, read-only MCP, Builder and Diagnostics Actions.
   Prerequisites remain unverified; local native state is not refreshed or

Progress.md

@@ -15,7 +15,6 @@
 `WIP` — 改版仍缺以下內容；原生平台與正式環境驗收缺口另列於後。
 計畫 D1 仍缺 portal session 關閉／恢復、compositor 重啟的狀態與原生驗收、
 擷取結果與擁有者 context 的接合，以及主動診斷與原生 session 的重試／取消／停止控制。
-原生指標超出 EIS 區域的拒絕仍被誤分類為選用依賴缺失，須停止隱含的 CLI 備援。
 D2 的原生 EI 釋放驗證與 D3 的錄製／全域停止／Windows 原生崩潰證據仍缺，詳見計畫與下方生命週期待辦。
 計畫 E（Android／iOS）、G（MCP 逐步揭露）、H（型別深化與總驗收）尚未開始。F 還缺：
 

README.md

@@ -473,6 +473,13 @@ returning the blank XWayland root. The `screen_capture` check in
 `je_auto_control.api.run_diagnostics()` (and the GUI Diagnostics tab) reports
 which tier is in use.
 
+A native Wayland pointer coordinate outside every granted EIS region, after
+raw-coordinate and layout-origin mapping, raises `LibeiUnavailable` with
+`state="failed"` and disables automatic CLI fallback. A rejected move emits
+no motion/frame or subsequent click. Valid coordinates, devices without
+regions, later valid requests on the same sender and explicit CLI selection
+retain their existing behavior.
+
 Passive **input/capture capabilities** use `BackendContext`, `CapabilityStatus`,
 `CapabilitySnapshot` and `probe_capabilities` from `je_auto_control.api` (also
 exported at the package root). Call

README/README_zh-CN.md

@@ -438,6 +438,11 @@ Wayland 的屏幕截取需要合成器对应的工具，因为没有单一工具
 `je_auto_control.api.run_diagnostics()`（以及 GUI 的 Diagnostics 标签页）的 `screen_capture`
 检查会报告当前使用的是哪一层。
 
+原生 Wayland 指针坐标在原始坐标与布局原点换算后仍不属于任何授权 EIS 区域时，
+会以 `state="failed"` 的 `LibeiUnavailable` 拒绝，停止自动 CLI 备用，
+不发送移动、frame 或后续点击。有效坐标、未提供区域的设备、同一 sender 的后续有效请求，
+以及显式选择 CLI 的现有行为保持不变。
+
 **输入／截取能力**提供 `je_auto_control.api`（也由包根目录导出）的
 `BackendContext`、`CapabilityStatus`、`CapabilitySnapshot` 与 `probe_capabilities`。
 调用 `probe_capabilities(BackendContext.current()).to_dict()`、无参数的

README/README_zh-TW.md

@@ -438,6 +438,11 @@ Wayland 的螢幕擷取需要合成器對應的工具，因為沒有單一工具
 `je_auto_control.api.run_diagnostics()`（以及 GUI 的 Diagnostics 分頁）的 `screen_capture`
 檢查會回報目前使用哪一層。
 
+原生 Wayland 指標座標在原始座標與版面原點換算後仍不屬於任何授權 EIS 區域時，
+會以 `state="failed"` 的 `LibeiUnavailable` 拒絕，停止自動 CLI 備援，
+不送出移動、frame 或後續點擊。有效座標、未提供區域的裝置、同一 sender 的後續有效請求，
+以及明確選擇 CLI 的既有行為維持不變。
+
 **輸入／擷取能力**提供 `je_auto_control.api`（亦由套件根目錄匯出）的
 `BackendContext`、`CapabilityStatus`、`CapabilitySnapshot` 與 `probe_capabilities`。
 呼叫 `probe_capabilities(BackendContext.current()).to_dict()`、無參數的

architecture.md

@@ -13,6 +13,12 @@ macOS, Linux X11, Linux Wayland, Android and iOS.
 
 ## 2. Layers and directories
 
+Native pointer region validation preserves raw-first then layout-origin
+mapping. A miss raises a failed LibeiUnavailable before motion/frame or
+a following click. The input selector propagates that refusal and cannot
+interpret it as optional dependency absence or switch automatically to CLI.
+The cached sender remains usable for later valid coordinates.
+
 wrapper/capabilities.py owns immutable caller contexts and independent
 input/capture metadata. Live collection reads a bounded set of environment/
 PATH facts and an already-loaded sender via a nonblocking local-state read.

architecture_explore.md

@@ -20,13 +20,13 @@ iOS（WebDriverAgent）。核心能力是滑鼠／鍵盤控制、影像辨識、
 | 指標 | 數值 |
 | --- | ---: |
 | Python 模組總數（含周邊子專案） | 1,215 |
-| 程式碼總行數 | 181,185 |
+| 程式碼總行數 | 181,186 |
 | `je_auto_control/utils/` 子套件數 | 311 |
 | `AC_*` 動作指令數（`known_commands()` 實測） | 810 |
 | 套件門面 `__all__` 公開名稱數 | 1377 |
 | GUI 分頁數（`main_widget` 註冊） | 49 |
 | MCP 工具數（`build_default_tool_registry()` 實測） | 710 |
-| `test_*.py` 測試檔／測試函式 | 836 / 8,743 |
+| `test_*.py` 測試檔／測試函式 | 837 / 8,748 |
 | 範例腳本 | 42 |
 
 **技術基線**：Python ≥ 3.10、MIT 授權、必要相依只有 `je_open_cv`／`opencv-python`／`pillow`／`mss`／
@@ -234,7 +234,7 @@ socket server 有 8 MiB 讀取上限與 30 秒 handler timeout。
 | `uinput/keyboard.py` | 44 | uinput 鍵盤後端，介面與 X11 版一致。 |
 | `uinput/mouse.py` | 130 | uinput 滑鼠後端。 |
 
-#### Linux Wayland（`linux_wayland/`，18 檔／3,138 行）
+#### Linux Wayland（`linux_wayland/`，18 檔／3,139 行）
 
 | 模組 | 行數 | 職責 |
 | --- | ---: | --- |
@@ -246,7 +246,7 @@ socket server 有 8 MiB 讀取上限與 30 秒 handler timeout。
 | `_select_input.py` | 103 | 決定使用原生 libei 或 CLI shim；`active_backend()` 是 keyboard／mouse 的唯一入口，`emitted()` 僅容許未分類的選用後端缺席退回 CLI；明確原生選擇、權限／裝置／協定拒絕保持失敗。 |
 | `_layout.py` | 83 | 版面原點的共用查詢。擷取與輸入不是同一個座標空間,差的就是這個原點:libei 的 region offset 是 `uint32`（描述不了負原點）,`ydotool mousemove --absolute` 的原點是合成器夾取的那個角落——兩條路都要減掉它,所以放在這裡而不是各自複製。讀數快取一秒——擷取那一側刻意不快取,但 ydotool 每次絕對移動都會問,不快取等於每次移動多開一個 `wlr-randr` 行程。 |
 | `oeffis.py` | 214 | liboeffis 綁定：跑完 RemoteDesktop portal 交握，交出 EIS fd；請求後的拒絕／逾時／失敗保留明確狀態。 |
-| `libei.py` | 730 | libei 綁定、撤銷閂鎖與只快取中繼資料的失敗狀態；完整握手（seat 綁定能力 → 由事件取得 device → start_emulating → 每次發送後 frame）。另負責絕對指標的座標空間:讀回裝置的 region,把版面座標映射進去,沒有任何 region 涵蓋就拒絕（libei 對這種移動是靜靜丟掉的）。  快取觀測不讀事件，完整就緒涵蓋全部請求的事件種類。 |
+| `libei.py` | 731 | libei 綁定、撤銷閂鎖與只快取中繼資料的失敗狀態；完整握手（seat 綁定能力 → 由事件取得 device → start_emulating → 每次發送後 frame）。另負責絕對指標的座標空間:讀回裝置的 region,把版面座標映射進去,沒有任何 region 涵蓋就以 failed 拒絕，停止隱含 CLI 備援與後續點擊（不撤銷 sender）。  快取觀測不讀事件，完整就緒涵蓋全部請求的事件種類。 |
 | `mouse.py` | 387 | 滑鼠後端：移動、按鈕與捲動都 libei 優先，僅選用缺席時退回 ydotool；權限／裝置拒絕不重送；送往 libei 時垂直捲動軸取負（kernel `REL_WHEEL` 與 `wl_pointer` 正負號相反）。退到 ydotool 的絕對移動會先減掉版面原點（`--absolute` 是相對於版面左上角,不是版面座標的 `(0, 0)`),並依 `pointer_accel_mode()` 處理指標加速度——倍率讀不回來,只有操作者知道,所以由 `JE_AUTOCONTROL_WAYLAND_POINTER_ACCEL` 宣告:未設定＝每個行程警告一次後照送、`flat`＝已關掉加速度故靜靜送出、`strict`＝拒絕這次移動。 |
 | `keyboard.py` | 206 | 鍵盤後端：按鍵／組合鍵 libei 優先，權限拒絕不改走 CLI；中斷時逐一釋放原後端已按下的鍵。文字仍用 wtype。 |
 | `keymap.py` | 155 | 友善鍵名 → evdev key code。 |
@@ -1161,7 +1161,7 @@ GUI 是**選用 extra**（`pip install je_auto_control[gui]`，只需要 PySide6
 | `scripts/dev_release.py` | 只用標準函式庫的發佈輔助腳本 | dev 通道（PyPI 的 `je_auto_control_dev`）的版本與比對：`prepare` 把 `dev.toml` 寫成 `pyproject.toml`，版本取 PyPI 最新一版加一個 patch（`dev.toml` 的版本只是下限，不回寫 repo）；`changed dist` 把建好的 wheel 跟 PyPI 最新一版逐檔比對，內容沒變就不上傳。只給 `dev.yml` 的 `publish-dev` job 與拋棄式的 checkout 用，因為 `prepare` 會蓋掉 `pyproject.toml`。 |
 | `docs/` | Sphinx（`API`／`Eng`／`Zh`／`getting_started`） | Read the Docs 文件。 |
 | `architecture_diagram/` | drawio + png | 既有的架構圖原始檔。 |
-| `test/` | `unit_test/headless`（主要）、`unit_test/flow_control`、`integrated_test`、`gui_test`、`manual_test`、`verify`、`test_source` | 836 個 `test_*.py`／8,743 個測試函式。**注意**：`test/unit_test/` 下的 `*_test.py` 是會真的驅動滑鼠鍵盤的手動示範腳本，因此 `pyproject.toml` 把 `python_files` 釘成 `test_*.py`。`unit_test/headless/conftest.py` 有一個 autouse fixture，每個測試結束都沖掉 Qt 排隊中的 `deleteLater()`——不沖會讓殘留的 widget 在後面某個不相干的測試裡被銷毀，曾經整個直譯器 `__fastfail`。`test_doc_counts.py` 守住文件引用的指令／工具／子套件／範例數,`test_doc_line_counts.py` 守住所有行數（`--fix` 可一次重新產生）。 `verify/macos_verify.py` 是在真的 `macos-14` runner 上量測 TCC 到底允許什麼的探針（macOS 是唯一沒有容器可用的支援平台），不被 pytest 收集。 |
+| `test/` | `unit_test/headless`（主要）、`unit_test/flow_control`、`integrated_test`、`gui_test`、`manual_test`、`verify`、`test_source` | 837 個 `test_*.py`／8,748 個測試函式。**注意**：`test/unit_test/` 下的 `*_test.py` 是會真的驅動滑鼠鍵盤的手動示範腳本，因此 `pyproject.toml` 把 `python_files` 釘成 `test_*.py`。`unit_test/headless/conftest.py` 有一個 autouse fixture，每個測試結束都沖掉 Qt 排隊中的 `deleteLater()`——不沖會讓殘留的 widget 在後面某個不相干的測試裡被銷毀，曾經整個直譯器 `__fastfail`。`test_doc_counts.py` 守住文件引用的指令／工具／子套件／範例數,`test_doc_line_counts.py` 守住所有行數（`--fix` 可一次重新產生）。 `verify/macos_verify.py` 是在真的 `macos-14` runner 上量測 TCC 到底允許什麼的探針（macOS 是唯一沒有容器可用的支援平台），不被 pytest 收集。 |
 
 ---
 
@@ -1255,7 +1255,7 @@ socket 預設綁 `127.0.0.1`；資源一律用 `with`。
 | `utils/rest_api/` | 8 | 2,064 |
 | `utils/agent/` | 9 | 2,142 |
 | `linux_with_x11/` | 19 | 1,281 |
-| `linux_wayland/` | 18 | 3,138 |
+| `linux_wayland/` | 18 | 3,139 |
 | `utils/triggers/` | 4 | 1,401 |
 | `utils/ocr/` | 10 | 1,381 |
 | `utils/usbip/` | 5 | 1,008 |
@@ -1264,5 +1264,5 @@ socket 預設綁 `127.0.0.1`；資源一律用 `with`。
 | `autocontrol-lsp/` | 8 | 744 |
 | `utils/hotkey/` | 7 | 861 |
 | 其餘模組（約 286 個 `utils/` 子套件 + `android/`／`ios/`／周邊小工具） | 794 | 71,242 |
-| **總計** | **1,208** | **181,098** |
+| **總計** | **1,208** | **181,099** |
 

docker/eis_verify.py

@@ -501,18 +501,19 @@ def _check_libei_drops_out_of_region_motion(backend, server, libei) -> str:
 
 
 def _check_out_of_region_move_is_refused(backend, server, libei) -> str:
-    """AutoControl turns that silence into something the CLI path can act on."""
+    """AutoControl refuses an invalid native coordinate without selecting another provider."""
     before = len(server.recording.absolute_motions)
     try:
         backend.set_position(9000, 9000)
     except libei.LibeiUnavailable as error:
         _require("outside every region" in str(error),
                  f"refused, but with an unhelpful message: {error}")
+        _require(error.state == 'failed' and not error.status.fallback_allowed,
+                 "a region refusal was misclassified as optional backend absence")
         time.sleep(0.3)
         _require(len(server.recording.absolute_motions) == before,
                  "the refusal still put a motion on the wire")
-        return f"refused with {str(error)[:60]}... — _select_input.emitted "\
-               "hands it to ydotool"
+        return f"refused with {str(error)[:60]}... — native request stopped without CLI fallback"
     raise AssertionError(
         "set_position(9000, 9000) returned as though the pointer had moved; "
         "libei dropped it and nobody was told")

docs/API_LIFECYCLE.md

@@ -1,5 +1,15 @@
 # Public API lifecycle
 
+A native Wayland pointer coordinate outside every granted EIS region, after
+raw-coordinate and layout-origin mapping, raises `LibeiUnavailable` with
+`state="failed"` and disables automatic CLI fallback. A rejected move emits
+no motion/frame or subsequent click. Valid coordinates, devices without
+regions, later valid requests on the same sender and explicit CLI selection
+retain their existing behavior.
+
+This correction adds no public names or signatures and retains the existing
+exception family. It does not revoke an otherwise valid sender or its grant.
+
 The additive public capability API is BackendContext, CapabilityStatus,
 CapabilitySnapshot and probe_capabilities(context), exported from the root
 and versioned je_auto_control.api/core namespaces. Contexts are detached and

docs/CAPABILITY_MATRIX.md

@@ -79,6 +79,14 @@ all-thread native backtraces through batch GDB; other platforms retain Python
 faulthandler output. This is diagnostic infrastructure, not native lifecycle
 acceptance or a root-cause correction; outstanding crashes remain in Progress.md.
 
+Controlled region-authority checks cover automatic and native input selection,
+exclusive region edges, gaps, raw-first/origin mapping, no-region devices,
+same-sender retry, explicit CLI and original direct/wrapped control signals.
+A refused native coordinate is failed and emits neither CLI input nor native
+motion/frame/click. These are fake-backend checks. The real-EIS verifier now
+requires the same failure contract, but was not executed for this change;
+physical and multi-monitor acceptance remain deferred.
+
 Passive capabilities are available through both SDK namespaces, one AC
 command, one read-only MCP tool, Builder and explicit Diagnostics Actions.
 Controlled checks cover independent input/capture prerequisites, denied/
@@ -329,10 +337,12 @@ where the negative-origin layout above reaches the input half: a region's
 offset is part of the coordinate rather than something to subtract, and a
 motion landing outside every region is dropped by libei without a return code,
 an event or an error — so the sender maps the point into region space and
-refuses what no region covers, which is what lets the `ydotool` path take it.
+refuses what no region covers. That refusal now carries failed state and stops
+implicit CLI fallback; the updated real-EIS assertion still needs a native run.
 
-The `ydotool-verification` job covers the CLI fallback, which the `libei` path
-drops to at every failure point. A seat is what makes an injected event arrive
+The `ydotool-verification` job covers the separate CLI provider. Automatic
+selection permits it only for optional native absence; native authority,
+device and region refusals stop the request. A seat makes an injected event arrive
 somewhere; it is not what makes one observable, so no compositor is needed:
 `ydotoold` creates an ordinary uinput device, the kernel publishes it as
 `/dev/input/eventN`, and the job reads the `input_event` structs back off it.