Add cancellable diagnostics with owned tasks and scoped I/O

Author: JE-Chen

CHANGELOG.md

@@ -13,6 +13,13 @@ it shipped into a `## [x.y.z] - date` section of their own; the tag's
 
 ## Unreleased
 
+- Run Diagnostics through the shared owner-bound controller with localized
+  progress/stop/retry states and no late updates after close. Add scoped
+  cancellation primitives to both SDK namespaces and the previously absent
+  active ac_diagnose MCP entry point. Supported Wayland socket/helper/native
+  waits observe scoped cancellation and retain bounded owned cleanup;
+  unscoped calls and existing diagnostic signatures remain compatible.
+
 - Add owner-bound shared GUI task infrastructure with cooperative cancellation,
   typed progress/outcomes, captured context and refreshed identity. Late owner
   results are dropped, failures do not retain traceback objects, and a failed

Progress.md

@@ -14,14 +14,14 @@
 
 `WIP` — 改版仍缺以下內容；原生平台與正式環境驗收缺口另列於後。
 計畫 D1 仍缺 portal session 關閉／恢復、compositor 重啟的狀態與原生驗收、
-擷取結果與擁有者 context 的接合，以及主動診斷與原生 session 的重試／取消／停止控制。
+擷取結果與擁有者 context 的接合，以及原生 session 的重試／取消／停止控制。
 D2 的原生 EI 釋放驗證與 D3 的錄製／全域停止／Windows 原生崩潰證據仍缺，詳見計畫與下方生命週期待辦。
 計畫 E（Android／iOS）、G（MCP 逐步揭露）、H（型別深化與總驗收）尚未開始。F 還缺：
 
 - **Remote Desktop 與 Script Builder 仍在啟動時建立**（預設開啟），啟動時間 2.6–2.7 秒裡大半是它們與門面匯入。
 - **F1 的遺留面板釋放**：擁有者直接建立的核心表單與 Remote Desktop 在關閉時仍保留 widget；需隨 F3 遷移直接控制項引用、執行中工作與連線生命週期，再啟用銷毀。
 - **F2 其餘**：計畫指定的 `WorkspaceShell` 介面、右側可收合詳情，以及各面板的空白／錯誤／permission states 還沒全面交付。
-- **F3** 還缺共用 `TaskController` 接入各面板、backend timeout／cancel 傳遞與關閉生命週期遷移，
+- **F3** 還缺共用 `TaskController` 接入其餘面板、backend timeout／cancel 傳遞與關閉生命週期遷移，
   以及 `webrtc_panel.py` 的 dialog／worker／session 拆分。
 - **F4**（啟動／記憶體基準、mixed-DPI、功能對等測試）尚未開始。
 - **F3 Windows 原生釋放驗收**：`test/unit_test/headless/test_remote_desktop_host_id.py` 的 freed-thread-state abort 尚缺 Windows 原生堆疊與獨立根因確認。

README.md

@@ -338,7 +338,7 @@ under a relative name are written below that directory.
 
 | Surface | Start it with | Notes |
 |---|---|---|
-| **MCP server** | `je_auto_control_mcp` (stdio) or `AC_start_mcp_http_server` | 710 tools for Claude Desktop / Claude Code / custom tool loops: the full `ac_*` surface plus short model-friendly aliases for common GUI actions. Speaks the stateless MCP 2026-07-28 beside the `initialize`-based revisions. Bearer auth, TLS, audit log, rate limit, plugin hot-reload, CI fake backend. |
+| **MCP server** | `je_auto_control_mcp` (stdio) or `AC_start_mcp_http_server` | 711 tools for Claude Desktop / Claude Code / custom tool loops: the full `ac_*` surface plus short model-friendly aliases for common GUI actions. Speaks the stateless MCP 2026-07-28 beside the `initialize`-based revisions. Bearer auth, TLS, audit log, rate limit, plugin hot-reload, CI fake backend. |
 | **REST API** | `je_auto_control start-rest` | Bearer token, per-IP rate limit + lockout, SQLite audit hook, `/metrics`, `/openapi.json`, `/docs` Swagger UI, `/dashboard`. |
 | **TCP socket server** | `je_auto_control start-server` | Newline-framed JSON action lists. Binds `127.0.0.1` by default. |
 | **pytest plugin** | installed automatically | Fixtures plus a Gherkin step library for pytest-bdd / behave. |
@@ -511,8 +511,8 @@ distinct from automatic fallback after observed optional native absence;
 permission/pause/revocation/failure metadata cannot imply CLI fallback.
 Capture helper and portal selection are diagnosed independently. Rendering and
 language changes reuse the snapshot without probing. Native portal restore,
-compositor restart, capture-result/context integration and cancelable active
-diagnostics remain in `Progress.md`.
+compositor restart, capture-result/context integration and native session
+controls remain in `Progress.md`.
 
 The GUI task infrastructure provides `gui.task_controller.TaskController`:
 `submit(work, owner=widget)` returns a caller-owned `TaskHandle` with
@@ -530,16 +530,43 @@ thread. Cancellation does not forcibly interrupt an uncooperative call
 or relabel a successful committed return. Errors/progress use the captured
 secret scope; terminal errors retain no exception traceback. Failed thread
 starts roll back both registries and preserve the original failure.
-This is shared infrastructure: Diagnostics and other panels still await
-controller/timeout/stop integration, tracked in `Progress.md`.
-
-Active diagnostics stop immediately when a check raises explicit cancellation
-or a hard control signal, including an explicit exception cause chain.
-The original object propagates through the core, SDK, CLI and Diagnostics
-action; it is not logged or converted into a failed report row, and later
-checks do not run. Ordinary probe errors still produce failed rows and
-allow remaining checks. A canceled GUI run can be retried explicitly.
-Background workers and cooperative stop controls remain pending.
+Diagnostics now adopts this controller. Remaining panel/backend migrations
+and native session operations stay in `Progress.md`.
+
+Active **Diagnostics → Actions → Run diagnostics** uses the shared task
+controller off the GUI thread. **Stop diagnostics** requests cooperative stop;
+the view distinguishes running, stopping, canceled and failed states in four
+languages. Progress counts completed checks. Duplicate runs are ignored, close
+abandons late progress/results, and a deliberate retry starts a new owned run.
+GUI cancellation is a typed outcome without retained exception tracebacks;
+headless core/SDK/CLI and the MCP handler preserve original direct/wrapped controls.
+Ordinary probe failures still become report rows and allow remaining checks.
+
+`CancellationToken`, `TaskProgress` and `cancellation_scope` are exported by both
+SDK namespaces. Bind `with cancellation_scope(token): report = run_diagnostics()`;
+the owning caller can call `token.cancel()` from another thread. The existing
+no-argument diagnostics signature remains. Scope binding grants no authority;
+`cancellation_scope(None)` only suspends cancellation for bounded owned cleanup.
+`AC_diagnose` and the new read-only `ac_diagnose` share the report. The MCP tool
+accepts no arguments, uses request cancellation/progress and requires
+`read_screen`, as does the explicit GUI action. Caller-supplied tokens or
+authority metadata are rejected. These are active checks: capture may request
+consent. `ac_probe_capabilities` remains the separate passive alternative.
+
+Scoped Wayland D-Bus connect/read/partial-write waits poll at intervals capped
+at 0.1s within the original total deadline. Cancellation attempts Request.Close
+on the originating bus with its separate 0.25s budget, then releases that
+connection; a canceled returned image is discarded. Scoped CLI captures stop
+and reap their newly owned helper/process group with bounded cleanup, preserving
+the original control even if pipe close fails; reaped numeric PIDs are never
+signaled. liboeffis acquisition observes scoped stop and releases its own context.
+Uncooperative/native calls are not forcibly preempted; the GUI remains responsive
+while cleanup completes. Restore/restart, native session controls, capture-owner
+metadata and remaining panel/backend migrations stay in `Progress.md`.
+
+`python -m examples.cancellable_diagnostics` runs a controlled cancellation demo
+without providers. `--active --cancel-after 2` explicitly runs diagnostics and
+requests stop after two seconds; native/device/API acceptance remains separate.
 
 Opening Diagnostics displays a localized not-run state and performs no checks.
 Choose **Actions → Run diagnostics** to start the existing active checks, which
@@ -590,7 +617,7 @@ ignore synthetic input, and fall back silently when the driver is absent.
 
 | Resource | What's in it |
 |---|---|
-| [`examples/`](examples/) | 42 self-contained scripts: screenshot + click, OCR, scheduler, remote desktop, agent loop, observability, recording, variables, hotkeys, triggers, reports, MCP, REST, secrets, plugins, computer use, Wayland, cross-host DAGs, chat-ops, pytest/BDD, anchor locators, action journals. |
+| [`examples/`](examples/) | 43 self-contained scripts: screenshot + click, OCR, scheduler, remote desktop, agent loop, observability, recording, variables, hotkeys, triggers, reports, MCP, REST, secrets, plugins, computer use, Wayland, cross-host DAGs, chat-ops, pytest/BDD, anchor locators, action journals. |
 | [Read the Docs](https://autocontrol.readthedocs.io/en/latest/) | Full API reference, English and 中文. |
 | [architecture_explore.md](architecture_explore.md) | Every module's responsibility, layer by layer. |
 | [docs/CAPABILITY_MATRIX.md](docs/CAPABILITY_MATRIX.md) | Capability × platform matrix. |

README/README_zh-CN.md

@@ -319,7 +319,7 @@ je_auto_control version
 
 | 接口 | 启动方式 | 说明 |
 |---|---|---|
-| **MCP 服务器** | `je_auto_control_mcp`（stdio）或 `AC_start_mcp_http_server` | 710 个工具，供 Claude Desktop／Claude Code／自定义 tool loop 使用：完整的 `ac_*` 工具接口，以及常用 GUI 操作的短名称 alias。除了以 `initialize` 握手的各版协议，也支持无状态的 MCP 2026-07-28。Bearer 认证、TLS、审计日志、限流、插件热重载、CI 假后端。 |
+| **MCP 服务器** | `je_auto_control_mcp`（stdio）或 `AC_start_mcp_http_server` | 711 个工具，供 Claude Desktop／Claude Code／自定义 tool loop 使用：完整的 `ac_*` 工具接口，以及常用 GUI 操作的短名称 alias。除了以 `initialize` 握手的各版协议，也支持无状态的 MCP 2026-07-28。Bearer 认证、TLS、审计日志、限流、插件热重载、CI 假后端。 |
 | **REST API** | `je_auto_control start-rest` | Bearer token、按 IP 限流与锁定、SQLite 审计 hook、`/metrics`、`/openapi.json`、`/docs` Swagger UI、`/dashboard`。 |
 | **TCP socket 服务器** | `je_auto_control start-server` | 以换行分隔的 JSON 动作列表。默认绑定 `127.0.0.1`。 |
 | **pytest 插件** | 安装后自动生效 | 提供 fixture 与供 pytest-bdd／behave 使用的 Gherkin step library。 |
@@ -462,7 +462,7 @@ Context 会复制环境／工具数据，可由拥有者提供无原生对象的
 默认本机结果不含环境值、命令参数、可执行文件路径或原生错误文字；AC／MCP 不接受外部提供观察。
 显式选择 CLI 与观察到可选原生依赖缺失后的自动备用分开；拒绝、暂停、撤销与失败不表示改走 CLI。
 截取工具／portal 选择独立诊断，重绘与切换语言只使用现有快照。原生 portal 恢复、compositor 重启、
-截取结果与 context 的接合，以及可取消的主动诊断仍列于 `Progress.md`。
+截取结果与 context 的接合，以及原生 session 的重试／取消／停止控制仍列于 `Progress.md`。
 
 GUI 工作基础提供 `gui.task_controller.TaskController`：
 `submit(work, owner=widget)` 返回调用者持有的 `TaskHandle`，通过
@@ -474,12 +474,30 @@ GUI 工作基础提供 `gui.task_controller.TaskController`：
 拥有者、handle 或 controller 销毁时会请求协作式停止并丢弃延迟结果；每项工作有独立 ID／token，
 回调在 GUI 线程执行。不强制中断不配合的调用，也不把已成功提交的结果改标为取消。
 错误与进度使用捕获的秘密遮罩 scope，终态不保留异常 traceback；线程启动失败会恢复两层登记并保留原失败。
-这是共用基础；Diagnostics 与其余面板的 controller／timeout／停止控制整合仍列于 `Progress.md`。
-
-主动诊断的检查若抛出显式取消或中断控制（含显式的异常原因链），立即停止，
-并由核心、SDK、CLI 与 Diagnostics 操作传递原始对象，不记录为普通错误或失败报告行，
-也不执行后续检查。普通检查错误仍产生失败行并继续其余项目；GUI 取消后可显式重试。
-后台 worker 与协作式停止控制仍待完成。
+Diagnostics 已接入此共用控制器；其余面板／backend 迁移与原生 session 操作仍列于 `Progress.md`。
+
+主动 **Diagnostics → Actions → 运行诊断** 以共用控制器在 GUI 线程外运行。
+**停止诊断** 请求协作式停止；四种语言的状态区分运行中、清理中、已取消和失败，并显示已完成检查数。
+重复运行不另开工作，关闭后丢弃延迟进度／结果，显式重试会建立新的拥有者工作。
+GUI 以不保留异常 traceback 的 typed outcome 呈现取消；核心／SDK／CLI 与 MCP handler
+保持原始直接／包装取消对象。普通检查错误仍计入报告并继续其余项目。
+
+两个 SDK namespace 导出 `CancellationToken`、`TaskProgress`、`cancellation_scope`。
+使用 `with cancellation_scope(token): report = run_diagnostics()`，拥有者可由另一线程调用
+`token.cancel()`；现有无参数诊断签名不变。Scope 不授予权限，`cancellation_scope(None)`
+只在有时限的自有资源清理期间暂停取消。`AC_diagnose` 与新增的只读 `ac_diagnose` 共用报告；
+MCP 不接受参数，使用请求取消／进度，与显式 GUI 操作同样需要 `read_screen`，拒绝外部 token／授权数据。
+这些是主动检查，截取可能请求同意；`ac_probe_capabilities` 保持独立的被动选项。
+
+Scoped Wayland D-Bus 的连接／读取／部分写入，以最多 0.1 秒的间隔轮询，保持原本总时限。
+取消时在原 bus 以独立 0.25 秒预算尝试 Request.Close，再释放连接；取消的已返回图片会删除。
+Scoped CLI 截取会停止并回收自己建立的 helper／process group，清理有时限，pipe close 失败也不覆盖原取消，
+已回收的数字 PID 不再作为信号目标。liboeffis 获取 session 时会观察停止并释放自身 context。
+不强制中断不配合或原生调用，清理期间 GUI 仍可操作；restore／重启、原生 session 控制、
+截取拥有者 metadata 与其余面板／backend 迁移保留于 `Progress.md`。
+
+`python -m examples.cancellable_diagnostics` 默认只做受控取消示例，不调用 provider。
+`--active --cancel-after 2` 才显式运行诊断并在两秒后请求停止；真机／设备／API 验收另外列管。
 
 打开 Diagnostics 只显示已翻译的「尚未运行」状态，不执行检查。
 选择 **Actions → 运行诊断** 才会启动现有主动检查，可能截取屏幕或需要 portal 同意；
@@ -521,7 +539,7 @@ Windows、macOS（pyobjc）与 X11（含 XWayland）；纯 Wayland 会话的协
 
 | 资源 | 内容 |
 |---|---|
-| [`examples/`](../examples/) | 42 个自包含脚本：截图点击、OCR、调度器、远程桌面、agent loop、可观测性、录制、变量、热键、触发器、报表、MCP、REST、密钥、插件、computer use、Wayland、跨主机 DAG、chat-ops、pytest/BDD、锚点定位、动作日志。 |
+| [`examples/`](../examples/) | 43 个自包含脚本：截图点击、OCR、调度器、远程桌面、agent loop、可观测性、录制、变量、热键、触发器、报表、MCP、REST、密钥、插件、computer use、Wayland、跨主机 DAG、chat-ops、pytest/BDD、锚点定位、动作日志。 |
 | [Read the Docs](https://autocontrol.readthedocs.io/en/latest/) | 完整 API 参考，含英文与中文。 |
 | [architecture_explore.md](../architecture_explore.md) | 逐层记录每个模块的职责。 |
 | [docs/CAPABILITY_MATRIX.md](../docs/CAPABILITY_MATRIX.md) | 能力 × 平台对照矩阵。 |