@mobileaidev/ai-app-bridge 0.3.8 → 0.4.1

package/docs/COMMAND_CONTRACT.md

@@ -13,7 +13,7 @@ a light command directory. Use `capabilities {"command":"tap-text"}`
 for its current `inputSchema`, platform, role and supported entrypoints. Domain
 `execution` contains Intent, Script, runtime lifecycle and device ownership;
 `evidence` contains archive operations.
-`capabilities {"includeOptions":true}` returns every current command schema.
+Discovery has a fixed 96 KiB budget. Broad `includeOptions:true` queries may return `discovery_output_too_large`; use the returned narrower query. Schemas are never silently pruned.
 
 Load only the operation needed for Intent, Script or evidence, for example
 `capabilities {"command":"intent","operation":"start"}`. To inspect an Intent
@@ -24,10 +24,19 @@ runtime contract. Intent terminal decisions remain available in the selected
 decision schema. Unsupported operations or scope combinations return an error
 with the offending field. Omit filters to read the complete command contract.
 
-All parameters are under `run.arguments`:
+Business parameters are under `run.arguments`. The required top-level `extract` chooses delivery; explicit `null` requests the original result within budget:
 
 ```json
-{"command":"tap-text","arguments":{"serial":"DEVICE","packageName":"com.example.app","targetText":"设置","provider":"auto"}}
+{
+  "command": "tap-text",
+  "extract": null,
+  "arguments": {
+    "serial": "DEVICE",
+    "packageName": "com.example.app",
+    "targetText": "设置",
+    "provider": "auto"
+  }
+}
 ```
 
 Names are canonical and case-sensitive. Unknown arguments, aliases, invalid
@@ -55,8 +64,8 @@ provider access and device ownership through their execution-specific contracts.
 ### Shared runtime lifecycle
 
 The first executing command starts a local runtime. `runtime --operation start`
-starts it explicitly; `runtime --operation status` inspects it without starting
-one; `runtime --operation stop` cancels and drains active work before releasing
+starts it explicitly; `runtime --operation status --extract null` inspects it without starting
+one; `runtime --operation stop --extract null` cancels and drains active work before releasing
 its ownership. CLI exit, MCP EOF and client SIGINT/SIGTERM close only that client.
 Use `intent`/`script --operation cancel --operation-id ID` to cancel one task.
 The same operation ID can be queried and controlled from either entrypoint.
@@ -93,12 +102,26 @@ there; Script freezes its `cwd`, source and target before starting. Subsequent
 clients cannot change those paths. `evidence verify` is offline in both adapters
 and requires neither a running runtime nor an available FactStore.
 
-CLI results are one JSON envelope: `{kind: "json"|"text"|"bytes", value, history?}`.
-JSON false, zero and null remain values; text is a string and bytes are base64.
-`history` contains the same recording outcome that MCP exposes as `_history`.
-Command failures have `value.ok:false` and exit code 1. MCP uses its normal
-content and `isError` representation. These are wire-format differences;
-validation, dispatch, task control and evidence semantics are shared.
+CLI results are one compact JSON envelope:
+`{command, execution, control, extraction, delivery, kind, value?, failureStage?}`.
+MCP returns this same body in tool text; no second `_meta`, `_history` or
+`structuredContent` copy is attached. `execution` records the command outcome;
+`control` retains continuation, current pending questions, receipts and capture
+coverage. With `extract:null`, `value` is the command's original value including
+`_feedback`; otherwise it is the extracted JSON value when delivered.
+
+The default final-body budget is 96 KiB UTF-8. `output.maxBytes` can select
+16–256 KiB. Overflow never returns a truncated JSON document or a large original
+fallback. Inspect `control.source`: only `persisted:true` provides a readable
+ref. Retry extraction with `response read` and this ref; repeating the original
+action with the same requestId is not a recovery guarantee. Original response
+snapshots and their exports preserve the original JSON representation.
+
+Exit 0 means requested delivery succeeded; 1 means validation/execution failed
+or remained unknown; 2 means the command succeeded but extraction/delivery
+failed. `failureStage` prioritizes validation, execution, extraction, delivery.
+MCP sets `isError` consistently. See [response extraction](RESPONSE_EXTRACTION.md)
+for exact examples, budgets, ref recovery and the distinction from Script.
 
 `batch`, `smoke`, `launch-native-test` and `launch-flutter` were removed. Use a
 code Script for sequences, `launch-app` for a Flutter app's actual launcher, and
@@ -503,6 +526,30 @@ or call budget prevents another Agent call. Malformed replies remain
 `waiting_for_decision` with a field error and require explicit correction; they
 neither dispatch nor trigger another Agent request automatically.
 
+A supervised Intent is driven by the caller: observe, decide against the
+observed revision, observe again, judge independently. One complete lifecycle,
+as sent to `run` (the repository test suite runs this sequence against the
+current contract with an injected device):
+
+```json lifecycle-example
+{"command":"intent","extract":null,"arguments":{"operation":"start","goal":"Open the Labels screen","target":{"platform":"android","serial":"<serial>","packageName":"<package>"}}}
+{"command":"intent","extract":null,"arguments":{"operation":"decide","operationId":"<operationId>","decision":{"decisionId":"d-1","agentDecision":"act","basedOnRevision":1,"action":{"action":"tap","selector":{"text":"Labels"}}}}}
+{"command":"intent","extract":null,"arguments":{"operation":"status","operationId":"<operationId>","limit":20}}
+{"command":"intent","extract":null,"arguments":{"operation":"status","operationId":"<operationId>","limit":20,"afterSequence":"<history.lastSequence of the previous page>"}}
+{"command":"intent","extract":null,"arguments":{"operation":"decide","operationId":"<operationId>","decision":{"decisionId":"d-2","agentDecision":"complete","basedOnRevision":2}}}
+```
+
+`start` and each `decide` return the committed observation with its `revision`
+and `summary`; the next decision must carry that `revision` as
+`basedOnRevision`. `status` returns the current state plus one history page.
+`limit` bounds entries, not bytes: a page of `summary` entries can still be
+large, so read the current state with a small `limit` and page history
+deliberately. The next page's `afterSequence` is the previous page's
+`history.lastSequence`; it is not an `eventSequence`, which belongs to Script.
+Supervised mode never acts on its own: without a decision the Intent stays
+`waiting_for_decision` until `timeoutMs`, and `complete` records the caller's
+judgment rather than evidence of the business outcome.
+
 Every decision requires `decisionId`, positive integer `basedOnRevision`, and
 `agentDecision`. `act` requires a provider-specific `action`; terminal decisions
 `complete/fail/inconclusive` forbid one. Tap uses an exact `selector` object, with
@@ -1186,7 +1233,23 @@ exact and come from one fresh visible provider tree; metadata, hidden windows
 and text from another provider cannot complete a condition. For example:
 
 ```json
-{"command":"wait-text","arguments":{"serial":"DEVICE","packageName":"com.example.app","provider":"native","targetText":"Save, draft","requireText":["Editor"],"absentText":["Loading"],"timeoutMs":5000}}
+{
+  "command": "wait-text",
+  "extract": null,
+  "arguments": {
+    "serial": "DEVICE",
+    "packageName": "com.example.app",
+    "provider": "native",
+    "targetText": "Save, draft",
+    "requireText": [
+      "Editor"
+    ],
+    "absentText": [
+      "Loading"
+    ],
+    "timeoutMs": 5000
+  }
+}
 ```
 
 At least one condition is required. Pure absence or Activity-only waits require
@@ -1491,7 +1554,7 @@ The operation holds the phone's mutation lease through package verification.
 For example, after receiving a fresh observation:
 
 ```json
-{"command":"intent","arguments":{"operation":"decide","operationId":"FROM_START","decision":{"decisionId":"choice-1","basedOnRevision":2,"agentDecision":"act","action":{"action":"tap","selector":{"resourceName":"ID_FROM_ACTUAL_OBSERVATION"}}}}}
+{"command":"intent","extract":null,"arguments":{"operation":"decide","operationId":"FROM_START","decision":{"decisionId":"choice-1","basedOnRevision":2,"agentDecision":"act","action":{"action":"tap","selector":{"resourceName":"ID_FROM_ACTUAL_OBSERVATION"}}}}}
 ```
 
 Completion requires the matching original shell-job receipt, a successful
@@ -1535,11 +1598,11 @@ provider operation. A history failure never retries or rewrites that operation.
 Intent/Script required evidence commits retain their existing strict admission
 and terminal-evidence contracts.
 
-Object results carry `_history` with schema `aab.command-history/v1`, including
-when `feedback:"off"`. Every ordinary CLI/MCP result also carries the same value in
-`_meta["ai-app-bridge/history"]`, so raw text/image-result consumers can inspect
-history without rewriting the original content. This is MCP history metadata;
-CLI and MCP use the same history store; direct internal provider calls do not acquire an auxiliary one.
+Public replies carry command recording status in `control.history` with schema
+`aab.command-history/v1`, where applicable. Full Intent history and original
+business values remain in value; only page/continuation fields are protected.
+CLI and MCP share the same compact body. There is no duplicate `_history` or
+MCP `_meta["ai-app-bridge/history"]` attachment.
 
 - `stored`: this invocation's action and returned Host evidence references were
   committed. It is not a claim of complete mobile history or business correctness.
@@ -1562,7 +1625,16 @@ Background observer health remains separate from this foreground write report.
 Trigger the runtime permission request through the App's existing flow, then call:
 
 ```json
-{"command":"permission-dialog","arguments":{"serial":"DEVICE","packageName":"com.example.app","permission":"android.permission.RECORD_AUDIO","outcome":"allow-once"}}
+{
+  "command": "permission-dialog",
+  "extract": null,
+  "arguments": {
+    "serial": "DEVICE",
+    "packageName": "com.example.app",
+    "permission": "android.permission.RECORD_AUDIO",
+    "outcome": "allow-once"
+  }
+}
 ```
 
 This MCP entry returns an ordinary Intent ID, the actual UI summary, and
@@ -1671,6 +1743,17 @@ tree or publish cached layout as current UI. Query a provider's observation
 command for its live lease state. These endpoints require rebuilt SDKs;
 installing a new CLI cannot patch an installed application's old SDK.
 
+iOS observation control uses the SDK's bounded capture lease, not physical-device
+action ownership. A rejected control or lost response cannot block later UI
+actions, and its HTTP request does not mark an enclosing UI action dispatched.
+An older Host may have left an `ios-command` / `ios-ui-observation` ownership
+marker. Explicit `ios-execution --operation reconcile` retires only that marker
+after checking the recorded device and any supplied bundle identity. Its receipt
+reports `reason: observation_control_not_device_mutation` and
+`observationOutcome: unknown`; it does not claim that observation started or
+stopped successfully. Other unresolved actions still require their original
+completion proof. Runtime restart alone does not erase the durable journal.
+
 Ordinary CLI/MCP `feedback=full` opens a window before the action and releases
 it in finally. If observation is unavailable, the action is rejected before
 dispatch; acquiring evidence does not mark the enclosing UI action dispatched.

package/docs/EVIDENCE_ARCHIVE.md

@@ -1,7 +1,7 @@
 # Record, export and verify execution evidence
 
 Discover the public MCP command with `capabilities {"command":"evidence"}`.
-It works for both Intent operation IDs and Script execution IDs, including
+It works for Intent operation IDs, Script execution IDs and saved response IDs, including
 records retained after the execution runtime has restarted. CLI and MCP use the
 same operation IDs and export command. Export does not require a
 connected phone or a live worker.
@@ -9,6 +9,7 @@ connected phone or a live worker.
 ```json
 {
   "command": "evidence",
+  "extract": null,
   "arguments": {
     "operation": "export",
     "namespace": "intent",
@@ -24,6 +25,16 @@ queued writes, and freezes the retained records for exactly that namespace
 and operation. The parent directory must exist; the output directory must
 not exist. No existing directory is replaced.
 
+For a saved public response, use `namespace: "response"` and the unchanged
+`control.source.ref.operationId`. A response record stores the final command
+result and execution/control facts in `snapshotBase64`, using canonical UTF-8
+JSON bytes after feedback has been added. The decoded bytes are exactly the
+input used for extraction. They can differ from a UI history record captured
+earlier. Export and verification preserve these bytes and use the existing
+evidence checksum; no second snapshot checksum or archive format is added.
+Only `control.source.persisted: true` supplies a readable ref. Missing, expired
+or evicted responses fail reads; they never cause a device query or action.
+
 The response includes `archiveDir`, `manifestPath`, `manifestSha256`,
 `recordCount`, `targets`, and `coverage`. Save the returned manifest SHA256
 separately when handing the archive to an author or reviewer.
@@ -52,6 +63,7 @@ Move or copy the directory as a unit, then call:
 ```json
 {
   "command": "evidence",
+  "extract": null,
   "arguments": {
     "operation": "verify",
     "archiveDir": "/absolute/moved-archive",
@@ -181,6 +193,7 @@ Use the same public export call with `includeRecordedPayloads: true`:
 ```json
 {
   "command": "evidence",
+  "extract": null,
   "arguments": {
     "operation": "export",
     "namespace": "script",

package/docs/INSTALLATION.md

@@ -0,0 +1,74 @@
+# Installation and supported Host platforms
+
+The simplest path is a supported Node installation and one MCP configuration.
+The same npm package contains CLI and MCP; running only MCP is supported.
+FactStore is an embedded library bundled in that package. There is no separate
+database, FactStore service or CLI process to install first.
+
+This source targets the coordinated 0.4.1 release.
+Registry publication is a separate step; before
+publication, use the reviewed local tarball instead of expecting this registry
+version to resolve.
+
+```json
+{
+  "mcpServers": {
+    "ai-app-bridge": {
+      "command": "npx",
+      "args": ["--yes", "--package", "@mobileaidev/ai-app-bridge@0.4.1", "ai-app-bridge-mcp"]
+    }
+  }
+}
+```
+
+For a local tarball, replace the package/version argument with its absolute
+`.tgz` path. Pin a version; do not let an unrelated global CLI installation
+silently determine the MCP server version. After upgrading, reconnect the MCP
+client so it loads the new code. Read mismatch diagnostics before stopping any
+shared Runtime: an older client should be upgraded without stopping a newer owner.
+
+## Requirements
+
+| Layer | Requirement |
+| --- | --- |
+| Host runtime | Node >=26.3.0 <27; validation baseline 26.3.0 |
+| macOS Host | arm64 or x64, macOS 13.5+ |
+| Linux Host | arm64 or x64, glibc 2.28+, kernel 4.18+; Node's libstdc++ and libatomic runtime requirements |
+| Native store | Bundled Node-API 8 addon selected by OS/architecture/libc, checksum checked; no compiler/Python during normal install |
+| JS/regex extraction and ordinary commands | No Python interpreter needed |
+| Python Script/extraction | Python 3.9+; optionally set AI_APP_BRIDGE_PYTHON |
+| Android provider | ADB and a connected device; SDK commands need the App's debuggable Bridge integration |
+| iOS/WDA provider | macOS, Xcode and the device/provider setup in COMMAND_CONTRACT |
+| Web providers | Browser/App connection required by the selected provider |
+
+The Node OS/library baseline follows [Node 26.3.0 build/platform requirements](https://github.com/nodejs/node/blob/v26.3.0/BUILDING.md#platform-list).
+It does not imply validation on every later OS or Node minor release. Native
+Windows, musl/Alpine and other architectures are outside this native Host matrix;
+the POSIX store does not acquire Windows support from a sample cmd.exe config.
+WDA 14.1.1 is installed as an npm dependency on all platforms, but preparation
+and execution use macOS. No split WDA package is required for basic MCP use.
+
+Missing/corrupt/unsupported prebuilds fail with the actual OS, architecture and
+Node-API information. Normal install never silently compiles, downloads a
+substitute addon or chooses another storage backend. Release checks must verify
+each matrix artifact; a Mac build alone is not Linux acceptance.
+
+## Development and release verification
+
+Native maintainers may explicitly run `npm run build` in
+`native/segmented-fact-store` to build from source with node-gyp and stage their
+local artifact. This requires the developer's compiler/Python. Release artifacts
+must also record their actual ABI minimum; never label a newer glibc build 2.28.
+The loader and startup fingerprint use the same selected `.node` file.
+
+`npm run verify:package -- /absolute/new/output` creates a real tarball and a
+fresh installation outside the repository. It denies compiler/Python commands
+for install and the pure MCP npx checks, verifies the loaded artifact/checksum,
+then uses a separate normal environment for the existing two-language regression.
+It checks first/repeated npx start, schema discovery, JS/regex, source ref recovery,
+MCP disconnection versus Runtime lifetime, durable store restart and controlled
+ADB scenarios. This is package/transport evidence, not physical-device acceptance.
+
+`npm test` runs functional checks and then a serial performance group. Use
+`npm run test:performance` on an otherwise quiet host for the timing gate;
+existing p95 thresholds are unchanged.

package/docs/INTENT_FOREGROUND.md

@@ -5,6 +5,7 @@ An Intent can keep its original business target while navigating through explici
 ```json
 {
   "command": "intent",
+  "extract": null,
   "arguments": {
     "operation": "start",
     "goal": "Export a backup, choose its file in the system picker, and return to the notes app",
@@ -12,7 +13,9 @@ An Intent can keep its original business target while navigating through explici
     "target": {
       "serial": "DEVICE_SERIAL",
       "packageName": "io.github.mobileaidev.notallyx.sample",
-      "foregroundPackages": ["com.coloros.filemanager"]
+      "foregroundPackages": [
+        "com.coloros.filemanager"
+      ]
     }
   }
 }

package/docs/OPTIONAL_EXECUTORS.md

@@ -1,4 +1,4 @@
-# Optional UI executors (0.3.8)
+# Optional UI executors (0.4.1)
 
 Bridge keeps its existing SDK paths and exposes optional executors through `capabilities`, `run`, and JavaScript/Python Script. Select an executor explicitly. No command silently changes a touch into a setter, switches framework after failure, or repeats an uncertain action.
 
@@ -20,12 +20,12 @@ These dependencies are isolated from ordinary production source sets. They are v
 Use `executor-prepare` from CLI, MCP `run`, or JavaScript/Python `ctx.call` with `app.test`. This is a Host operation: it does not require a device target, install an App, start UI observation, or open an executor session. Preparation uses the selected project's existing toolchain and keeps its application ID. The result separates preparation from installation and session readiness.
 
 ```sh
-ai-app-bridge executor-prepare --platform android --project-dir /project \
+ai-app-bridge executor-prepare --extract null --platform android --project-dir /project \
   --module :app --variant debug --adapters '["espresso-web"]'
-ai-app-bridge executor-prepare --platform flutter --project-dir /flutter-app \
+ai-app-bridge executor-prepare --extract null --platform flutter --project-dir /flutter-app \
   --flutter-path /flutter-sdk/bin/flutter
-ai-app-bridge executor-prepare --platform ios
-ai-app-bridge executor-prepare --platform web --browser chromium
+ai-app-bridge executor-prepare --extract null --platform ios
+ai-app-bridge executor-prepare --extract null --platform web --browser chromium
 ```
 
 - Android: a temporary Gradle init script adds the test dependencies and a generated session class only for this invocation. The dependency-check plugin is applied automatically. The result contains the actual application ID, instrumentation component, test class, APK paths and SHA-256 values. Existing matching test dependencies/runners are reused; conflicting Bridge test dependencies are rejected. Business Gradle, manifest and source files are not edited. Select the actual module and debuggable variant; flavors and APK splits retain their original identities. The current build integration uses the AGP 7.4–8.x variant API on macOS/Linux; AGP 9 and Windows preparation are not part of this profile. A local `file:` Maven `repositoryUrl` can explicitly select development artifacts; ordinary preparation resolves the same release version from JitPack.
@@ -52,9 +52,9 @@ android {
     }
 }
 dependencies {
-    androidTestImplementation("com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-test-instrumentation:0.3.8")
+    androidTestImplementation("com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-test-instrumentation:0.4.1")
     // Optional H5 adapter:
-    androidTestImplementation("com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-test-espresso-web:0.3.8")
+    androidTestImplementation("com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-test-espresso-web:0.4.1")
 }
 ```
 
@@ -74,8 +74,8 @@ Opening a session **restarts and instruments the target application**. Install t
 ./gradlew :app:assembleDebug :app:assembleDebugAndroidTest
 adb -s DEVICE install -r -t app/build/outputs/apk/debug/app-debug.apk
 adb -s DEVICE install -r -t app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk
-ai-app-bridge android-executor --operation status --serial DEVICE
-ai-app-bridge android-executor --operation open --serial DEVICE \
+ai-app-bridge android-executor --extract null --operation status --serial DEVICE
+ai-app-bridge android-executor --extract null --operation open --serial DEVICE \
   --package-name example.app \
   --instrumentation example.app.test/androidx.test.runner.AndroidJUnitRunner \
   --test-class example.app.BridgeSessionTest --activity example.app.MainActivity
@@ -109,7 +109,7 @@ Espresso text actions have different semantics. `replaceText` is the framework's
 
 ## Flutter
 
-Add `ai_app_bridge_test: 0.3.8` to the application's `dev_dependencies`. The helper takes `flutter_test` and `integration_test` from the **same Flutter SDK** as the application. It is a Dart test helper, not an additional Android plugin with its own AGP/Kotlin versions.
+Add `ai_app_bridge_test: 0.4.1` to the application's `dev_dependencies`. The helper takes `flutter_test` and `integration_test` from the **same Flutter SDK** as the application. It is a Dart test helper, not an additional Android plugin with its own AGP/Kotlin versions.
 
 The helper declares Flutter **>=3.41.0** and Dart **>=3.11.0 <4.0.0**. The 0.3.8 automatic preparation was exercised with LocalSend on Flutter **3.41.9 / Android API 36**, preserving all 214 production dependency versions. Earlier executor validation covered Flutter 3.41.9 / API 25 and 3.44.8 / API 36. These are specific verified combinations; other SDK versions still need validation with the application's plugin graph.
 
@@ -124,7 +124,7 @@ void main() => aiAppBridgeTest(app.main);
 flutter build apk --debug --target integration_test/bridge_test.dart \
   --dart-define=INTEGRATION_TEST_SHOULD_REPORT_RESULTS_TO_NATIVE=false
 adb -s DEVICE install -r -t build/app/outputs/flutter-apk/app-debug.apk
-ai-app-bridge flutter-executor --operation open --serial DEVICE \
+ai-app-bridge flutter-executor --extract null --operation open --serial DEVICE \
   --package-name example.app --activity example.app.MainActivity
 ```
 
@@ -133,9 +133,9 @@ This version supports the standard **Android Flutter embedder**, with its normal
 ## Web
 
 ```sh
-ai-app-bridge web-executor --operation status --browser chromium
-ai-app-bridge web-executor --operation prepare --browser chromium --timeout-ms 300000
-ai-app-bridge web-executor --operation open --url http://localhost:3000 --browser chromium
+ai-app-bridge web-executor --extract null --operation status --browser chromium
+ai-app-bridge web-executor --extract null --operation prepare --browser chromium --timeout-ms 300000
+ai-app-bridge web-executor --extract null --operation open --url http://localhost:3000 --browser chromium
 ```
 
 The CLI manages exact Playwright **1.63.0**, an included npm lock file and matching browser downloads. `prepare` is explicit; normal SDK usage does not download browsers. Cache keys include the dependency lock digest, OS and CPU architecture. Node **26.3.x** is the verified Host baseline (`>=26.3.0 <27` contract). Browser preparation is serialized and reports failures. `status` separates the static version from actual executable availability.

package/docs/RELEASE.md

@@ -1,122 +1,71 @@
-# 0.3.8 发行与接入交接
-
-本文件记录正式版的依赖关系和出仓库交付入口。封版要求是同一提交的源码、发行包与公开接入合同一致；单个样本的测试进度不改变包版本或发布状态。推送 Git、创建远端标签及发布 npm/pub 包由维护者执行。
-
-## 0.3.8 自动准备
-
-- 新增 `executor-prepare`，为原工程准备可选测试执行器，公开命令数为 122。
-- Android 自动生成 androidTest 入口、注入测试依赖并构建原包名的主包与测试包；Flutter 自动添加 dev_dependency、生成入口并检查业务依赖版本。
-- iOS 管理并校验可复用的 WDA 工程；Web 复用精确版本 Playwright 和浏览器准备流程。
-- 准备不启动持续 UI 观察，不自动升级业务工具链；实际设备/浏览器验证与发布证据另行记录。
-- Espresso 增加显式 `replaceTextViaInputConnection` 输入选项，并返回可勾选控件的实际状态；原有 setter 和按键输入分别保留其语义。NotallyX 真机回归验证了自定义 `setText` 抑制业务监听的情况，不能只以屏幕文字变化认定保存成功。
-- 允许安装标准 AGP 生成的无版本号 androidTest APK，包名、签名和安装后文件哈希校验继续执行。
-
-## 随本版包含的 0.3.7 修复
-
-- Android Host 读取全部焦点记录，跳过 `null`，不再依赖记录排列顺序。只有一个有效窗口时直接使用；多个窗口通过系统 `mTopFocusedDisplayId` 选择，仍不能唯一定位时返回 `foreground_ambiguous`。
-- 包名匹配、SDK 窗口与控件身份校验沿用既有路径。App SDK 只同步发行版本。
-
-## 随本版包含的 0.3.6 能力
-
-- Android、iOS、Flutter、Web 与内嵌 H5 的持续 UI 观察默认关闭；仅按需开启 100–5000 ms 的观察窗口，期限到达、主动停止或相应生命周期退出时清理观察任务。新增三个平台观察控制命令，公开命令共 121 个。
-- Flutter 当前树改为显式读取 `/v1/flutter/snapshot`，状态请求不再触发树遍历；CLI/MCP 与 App 内 SDK 需要配套升级。Android 指纹编码减少 JNI 调用与临时分配。实测证据及边界见仓库中的 UI 观察性能评估记录。
-
-- 可选 Android Instrumentation 会话，复用业务 androidTest；UI Automator、Espresso、Espresso-Web 和 Compose 可在同一会话内选择。
-- 可选 Flutter integration_test/WidgetTester 测试入口，以及 Host 管理的 Playwright 1.63.0 浏览器执行器。
-- 公开 capabilities + run、Python/JS Script 的 app.test 权限、观测身份、原始回执、取消和设备占用接线。
-- Compose 主包/测试包版本检查；按测试配置隔离依赖，不自动升级业务 AGP/Kotlin/Compose。
-- Android 7 权限输出的零 flags 省略及空格分隔格式支持，来源为实际 API-25 环境和 AOSP Settings 输出实现。
-- 本地交付和外部发布分开记录；这份源码不表示 npm/JitPack/pub.dev 已发布 0.3.8。
-
-接入合同、具体依赖和实测性能见 [OPTIONAL_EXECUTORS.md](OPTIONAL_EXECUTORS.md)。
-
-## 随本版包含的 0.3.5 修复
-
-- 修正 UIA nodeRef 原回执对账，正常重启和死进程后的显式启动可完成原 session 审计；未知回执和失效引用仍受保护。
-- UIA node runtime 支持 Android API 25+，保留 POSIX 原子重命名、fsync、进程锁与原始 Binder 回调；不使用 dump 或坐标回退。Android 7 权限观察支持未初始化的权限状态以及旧 ActivityManager 的身份字段。
-- iOS 对未就绪的 list 快照先执行所选设备的 details 探测；原始 4016 使用断言拒绝可按精确调用公开对账，不删除占用记录。
-- WDA 启动前持久保存 XCTest 调用身份。原始启用自动化超时能结算；旧 ios-setup 记录用原公开响应、Host action 与 XCTest 结果公开对账，未知结果继续保留。
-- 没有待处理安装时，cancel-install 明确返回 install_action_not_pending，不把空操作报告成安装取消成功。
-- 各 SDK 同步版本；原生 SDK 设备执行逻辑沿用 0.3.4。真实业务验收与渠道发布状态单独记录。
-
-## 随本版包含的 0.3.3 修复
-
-- Native 观察按当前 Activity 的窗口组选择节点，保留 Dialog/Popup；修复返回和前进时 Activity 与节点不一致。
-- Android 安装与执行校验实际探测 standalone、toybox、busybox 的 SHA-256；保留完整性校验，不要求固定 PATH 命令。
-- iOS 未安装 App 的明确启动拒绝及时释放设备；未知回执保留原始结果文件并支持公开核对，不因 JSON 版本号差异拒绝有效结果。
-- `device-ownership cancel-install` 可凭原 actionId 取消遗留 PM 会话；恢复只读同一份回执，不重发安装，也不声称回滚。
-- CLI `--version`、录制目录、错误字段、Script 起步权限及 Reader UIA 只读重试修正；明确 freeze 与 MCP 重连语义。
-- Android Gradle 无实现的历史开关发出弃用提示，旧 DSL 仍可构建；各端统一版本。
-
-## 新增可选分发物
-
-Android `ai-app-bridge-test-core`、`ai-app-bridge-test-uia`、`ai-app-bridge-test-espresso`、`ai-app-bridge-test-instrumentation`、`ai-app-bridge-test-espresso-web`、`ai-app-bridge-test-compose` 均使用 0.3.8，通过 androidTestImplementation 消费。Gradle 插件增加 `io.github.mobileaidev.aiappbridge.test` 依赖校验入口。新 Flutter 包 `ai_app_bridge_test` 使用 0.3.8，只作为 dev_dependency；它的发布不依赖 Android SDK 的 JitPack 坐标。
-
-## 版本与消费方式
-
-| 交付物 | 发行版本 | 独立消费入口 | 发布依赖 |
-| --- | --- | --- | --- |
-| Android SDK | `0.3.8` | JitPack `com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-android:0.3.8` | 同名 Git tag，JitPack 对该提交成功构建 |
-| Android Gradle 插件 | `0.3.8` | JitPack `ai-app-bridge-gradle-plugin` 模块及插件 ID `io.github.mobileaidev.aiappbridge.android` | 与 SDK 相同的 Git tag；不再使用旧默认 `0.2.8` |
-| 原生 iOS SDK | Git tag `0.3.8` | Git URL 的仓库根 `Package.swift`，产品 `AiAppBridgeIOS` | 根清单包含 Swift runtime、C adapter 和 segmented C store，无外部 C 包路径 |
-| Flutter 插件 | `0.3.8` | pub `ai_app_bridge_flutter` | Android 固定依赖上述 SDK；iOS Swift/C 源码随插件分发 |
-| Desktop CLI/MCP | `0.3.8` | npm `@mobileaidev/ai-app-bridge` | 包含 UIA bundle、WDA 模板和 native store 源码；WDA 上游固定 `14.1.1` |
-| Web SDK | `0.3.8` | npm `@mobileaidev/ai-app-bridge-web` | 独立浏览器源码包，无 npm 对 CLI 的安装依赖 |
-| Native store | `0.1.0` | 随 CLI 的 bundled dependency 安装 | 不要求另行发布到 npm；`file:../../native/segmented-fact-store` 是工作区构建入口，最终 tarball 必须包含该依赖源码 |
-
-Flutter 的 podspec 是随 pub 插件消费的本地 podspec，不是独立 CocoaPods trunk 发布包；原生 iOS 使用根 Swift package。Flutter SwiftPM 的 `../FlutterFramework` 由 Flutter 的集成生成，不能当作本仓库的外部私有依赖，也不应将本机 Flutter framework 打包进插件。
-
-Host 支持范围声明为 Node `>=26.3.0 <27`，本轮实际验证基线是 **26.3.0**。共享 runtime 与查询索引依赖 `node:sqlite`，native store 安装需要 node-gyp 所需的 Python 和 C/C++ 编译工具。未对其他 Node 版本或跨主版本兼容作实测声明。Python Script 另需可用的 `python3`，从实际 `script runtime-status` 读取环境能力。
-
-## 发布顺序
-
-1. 完成源码审阅并冻结一个提交，核对以下命令的产物确实来自它；包含当前 untracked 的实际源码、测试和文档，排除本机生成目录。所有对外发行版本使用同一个 `0.3.8`，若需要改版本，先同时更新上表涉及的 manifest 与固定依赖。
-2. 维护者推送提交与 `0.3.8` 标签，让 JitPack 构建 Android SDK/插件。确认两条公开坐标可解析后，再发布依赖它们的 Flutter 包。本地 Gradle project/path/AAR 替换不能证明 JitPack 坐标可消费。
-3. 原生 iOS 消费相同 Git tag 的根 package；完成根 package 的 iOS 构建，不仅构建 `ios/ai-app-bridge-ios/Package.swift`。Flutter iOS 则检查实际 pub 包内 Swift/C 源码与声明相符。
-4. CLI 与 Web SDK 可分别发布到 npm 的 `latest` dist-tag。CLI 的 native store 已打包随行，不等待一个不存在的单独 registry 依赖。Flutter 包发布以第 2 步完成为前提。
-5. 同步 npm `next` 指向 `0.3.8`，让已有候选入口也使用本次正式版。将 GitHub `main` 与发行提交同步，并创建非预发布的 GitHub Release。
-6. 从 registry/tag 安装刚发布的确切版本，读取 `capabilities` 和版本，核对来源及支持范围，确认默认安装入口指向本次发行版本。正式发布不自动等于全平台生产验收完成。
-
-正式发布命令需在对应目录由维护者执行，例如 npm 使用 `npm publish --tag latest`；pub 使用 `flutter pub publish`。这些命令属于发布动作，不能混入本地验证脚本。
-
-## 本地检查与最终包验证
-
-以下检查不发布版本。路径相对仓库根；输出使用新的、Git 忽略的目录。
-
-```sh
-swift package --package-path . dump-package
-swift package --package-path ios/ai-app-bridge-ios dump-package
-
-cd desktop/ai-app-bridge-cli
-npm pack --dry-run --json --ignore-scripts
-
-cd ../../web/ai-app-bridge-web
-npm pack --dry-run --json --ignore-scripts
-
-cd ../../flutter/ai_app_bridge_flutter
-flutter pub publish --dry-run
-```
-
-`dump-package` 只证明 manifest 可解析及目标声明，不能替代 iOS 编译；`npm pack --dry-run` 只证明拟打包文件清单，不能替代安装；pub dry-run 中的分析/网络检查结果应原样记录。干净安装与 Host 协议验证必须在核心源码冻结、没有运行中修改时执行：
-
-```sh
-cd desktop/ai-app-bridge-cli
-npm ci
-npm run verify:package -- ../../build/ai_app_bridge_artifacts/release-package-NEW
-```
-
-`verify:package` 在仓库外安装实际 tarball，检查 native 安装编译、CLI/MCP 共享运行时、控制接口与随包运行时身份。它使用受控 ADB，不声称完成新真机业务验收。报告、tgz 哈希、安装日志和源码提交身份一起交接；已运行的旧包验证不能代替后来修改过的包。
-
-CLI 的 `files` 已排除旧 `fact-cache.js` 发布载荷及 fake/P9/旧设备 adapter；旧 fact-cache 实现仅保留为 `test-support` 测试夹具，无生产引用。各 npm 包和 Flutter 目录的 `LICENSE`/`NOTICE` 均来自仓库根原文，发行时核对内容一致，不生成替代版权说明。
-
-## 升级进程与后续修复
-
-npm 升级不会替换已连接的 MCP 进程。用 `ai-app-bridge --version` 核对本机入口；
-已有工作结束后显式停止旧 Runtime，并在 Cursor 等客户端重连 MCP，核对 initialize
-中的 `serverInfo.version`。工具描述仍有旧 `batch`/`smoke` 时刷新客户端缓存。
-
-实际发布状态与验证边界见仓库 `docs/RELEASE_HANDOFF_0.3.8_2026-09-15.md`。
-Android Gradle 插件的 `webSocketCaptureEnabled`、`logInstrumentationEnabled`、
-`webViewDebuggingEnabled` 没有对应插桩实现，现明确弃用并在显式设置时输出提示；
-旧配置仍可构建。当前有效开关是 `enabled`、`okHttpCaptureEnabled`，以及可选
-`runtimeDependencyNotation`。不要把弃用选项的配置值当作采集功能已经启用。
+# 0.4.1 统一补丁发行检查
+
+源码版本、可发布验收、registry 发布和正在运行的客户端是四个不同状态。
+本文件描述发行操作；源码中的版本号不代表 npm/JitPack/pub.dev 已发布。
+0.4.0 改善版的实施与放行证据记录于仓库
+`docs/IMPROVEMENT_RELEASE_V1_2026-09-18.md` 及各 M1–M5 交付记录。
+0.4.1 统一发布全部 Bridge 组件，Host 修复与回归证据见
+`docs/HOST_0.4.0_GROK_REVIEW_2026-09-19.md`；设备及 Web SDK 仅同步版本与依赖。
+
+本次修复 iOS 观察控制误占设备动作 ownership，并为旧误记 marker 提供
+显式 reconcile；提取临时目录清理失败改为 cleanupError，保留原提取结果。
+超预算 reference 交付和 extract 必填合同不变；设备端执行合同不变。
+
+## 兼容与迁移
+
+0.4.0 的外部 run 必填 `extract`，不提取显式 null；CLI `--extract null`。
+返回公共封套含 execution/control/extraction/delivery，删除额外 `_history`、
+`_meta` 副本。旧请求不自动补字段。业务 value 在 null 且预算内保持原值，
+Script 的内部 ctx.call 仍返回 ok/result。Runtime 协议仍是 aab.runtime/v1。
+
+调用方先核对 execution 和控制字段；提取失败后用原 source ref 调 response
+read，不重放动作。详见 [公共提取合同与完整示例](RESPONSE_EXTRACTION.md)。
+发现正文超预算时按 command/operation 收窄，不静默裁剪 schema。
+
+## 发行资源
+
+| 资源 | 源码版本 | 发行渠道 |
+| --- | --- | --- |
+| Desktop CLI/MCP | 0.4.1 | npm @mobileaidev/ai-app-bridge |
+| 嵌入式 native store | 0.2.0 | 随主包 bundleDependencies，包括四个预编译 addon |
+| Android SDK / Gradle plugin / executor modules | 0.4.1 | 同仓库 Git tag / JitPack |
+| iOS Swift 包 | Git tag 0.4.1 | 根 Package.swift |
+| Flutter SDK / test helper | 0.4.1 | pub.dev；Android 固定依赖同版 SDK |
+| Web SDK | 0.4.1 | npm @mobileaidev/ai-app-bridge-web |
+
+UIA bundle、WDA 14.1.1、iOS WDA 模板、Playwright helper 与三类范例随主包。
+未改变代码的设备组件不需要仅为 Host 返回合同重新安装；需要测试新发行
+设备产物时记录实际版本/包/序列号，不能用旧安装冒充新包验收。
+
+## 发布前门禁
+
+本次必须通过新增缺陷回归、Host 完整功能/性能组、真实 iPhone 恢复验证及
+最终 tarball 安装检查。SDK 同步版本后重新验证构建与公开依赖；未变更的
+原生 addon 复用 0.4.0 四平台验收，并核实归档字节相同。
+
+1. 固定审核提交，核对工作包和 A01–A16，保留失败与未验证项。完整 npm
+   功能组与安静环境串行性能组通过，范例由文档读取实际执行。
+2. 对 [Host 支持矩阵](INSTALLATION.md) 的四个 artifact 校验 checksum 和
+   实际加载，运行 native tests 与全新 tarball 安装。正常安装和纯 MCP
+   JS/regex 路径禁止调用本地编译器/Python；Python 回归使用单独环境。
+3. 核对 npm pack 清单真实包含 addon、加载器、source read/worker 和文档，
+   codeFingerprint 哈希实际选中的二进制。固定版本 npx 首次/重复启动、
+   MCP 断连后 Runtime 存续、明确 stop/restart 与持久化恢复均有证据。
+4. 核实实际 CLI 路径、MCP 启动版本/指纹、Runtime code/config/Node 身份，
+   并检查受影响消费脚本的 extract/公共响应迁移。安装成功不替代入口更新。
+5. Android/Swift/Flutter/Web 的发行清单和版本一致。需要时运行相应构建，
+   真实设备证据和离线/受控 ADB 测试分开记录。三类实际任务对照保留来源、
+   时间、目标和原始记录，不能将缺设备写成不适用。
+
+## 对外发布顺序
+
+本次推送已验收提交与统一 `0.4.1` tag，核实 JitPack 公开坐标成功解析，
+再发布依赖它们的 Flutter SDK/helper。Web npm 与主 CLI/MCP npm 分别发布
+已经验证的 tarball，核实 `latest`/`next` 均为 0.4.1、公开下载 checksum
+与候选包一致，并创建对应 GitHub Release。保留旧 `0.4.0` tag 不动。远端流水线
+成功与设备业务验收分别列明。本地构建或 MavenLocal/path 替换不能证明公开
+坐标可安装。
+
+客户端升级时退出旧 MCP 再重新连接。若是旧客户端碰到新 Runtime，先升
+客户端；只有明确 Runtime 是待升级一侧时，在其任务结束后显式 stop。
+同版本不同指纹只能说明构建或 Node 环境不一致，不能凭 hash 判断新旧。