@mobileaidev/ai-app-bridge 0.3.1 → 0.3.3

package/README.md

@@ -7,7 +7,7 @@ discovery. Every request checks the mapping before dispatch. Mutating requests
 are never replayed after a missing route or uncertain result. For manual cleanup,
 pass the exact serial and returned Host port to `remove-forward`.
 
-This release is `0.3.1`, distributed through the npm `latest` dist-tag.
+This release is `0.3.3`, distributed through the npm `latest` dist-tag.
 The default installation includes the Script/Intent and capture contracts below.
 The `next` dist-tag also points to this release until a newer candidate is published.
 The supported Node range is `>=26.3.0 <27`; this release was checked on 26.3.0.
@@ -56,7 +56,7 @@ domains, commands, and options, then call `run` with the selected command.
 
 ```bash
 # Install the current stable release; see docs/RELEASE.md for packaging.
-npm install -g @mobileaidev/ai-app-bridge@0.3.1
+npm install -g @mobileaidev/ai-app-bridge@0.3.3
 
 ai-app-bridge status --package-name io.github.mobileaidev.aiappbridge.sample
 ai-app-bridge tree --package-name io.github.mobileaidev.aiappbridge.sample
@@ -338,12 +338,11 @@ explicit original/redacted hashes. A busy FactStore preserves pending cleanup.
 API 36 on OPPO PGFM10 and OnePlus PKR110 is the current real-device scope. See
 the [command contract](docs/COMMAND_CONTRACT.md#semantic-targets-and-text-waits).
 
-For dynamic or transient screens, MCP agents can use `freeze-app`/`thaw-app` as
-an optional stabilization control: thaw before reads, actions, waits, or
-captures; freeze after evidence capture only when a changing UI would make
-reasoning unreliable; and thaw before the next app operation or before
-finishing so the app is not left frozen. Static screens and ordinary form
-flows usually do not need freezing.
+`freeze-app` sends SIGSTOP to the target App processes, including the Bridge
+SDK and its socket. It is a process control command, not a way to obtain live
+SDK observations of a frozen page. Capture evidence first; use `thaw-app` before
+further reads, actions, waits or captures and before finishing. Ordinary Intent
+and Script flows do not need freezing.
 For visible state changes such as panels, dialogs, page transitions, tabs, or
 button-triggered content, verify with both `screenshot` and `tree`/`uia-tree`;
 do not conclude success from UI tree alone.
@@ -388,3 +387,15 @@ debug dependency exposes multiple launcher entries, it returns
 `launcher_ambiguous` with the candidates instead of guessing. Use
 `launch-activity` or `launch-app --activity/--component` to choose the intended
 entry point explicitly.
+
+### Upgrading the running CLI and MCP
+
+`ai-app-bridge --version` (also `-V`) reads the installed entrypoint's package
+version without requiring a device. Upgrading npm replaces files; it does not
+replace an MCP process already connected to Cursor or another client. Stop the
+shared Runtime with `ai-app-bridge runtime --operation stop` when existing work
+has finished, then reconnect the client's MCP server. The MCP initialize
+response reports `serverInfo.version`; refresh cached tool descriptions in the
+client when they still show removed commands such as `batch` or `smoke`.
+A running Runtime from different source code reports `runtime_code_mismatch`
+until explicitly stopped, so in-flight work is not silently moved to new code.

package/bin/ai-app-bridge.js

@@ -17,6 +17,7 @@ for an orderly runtime shutdown, or intent/script --operation cancel for a task.
 Commands:
 ${[...isolatedCommandDefinitions, ...commandDefinitions].map(d => `  ${d.command.padEnd(22)} ${d.summary}`).join('\n')}
   help                   Show this help.
+  --version, -V          Show the installed CLI/MCP package version.
 
 Use --help <command> to inspect its JSON input schema.
 For intent/script/evidence, add --operation to read only that operation.
@@ -37,7 +38,13 @@ async function main() {
   process.once('SIGINT', disconnect);
   process.once('SIGTERM', disconnect);
   try {
-    const parsed = parseArgs(process.argv.slice(2));
+    const argv = process.argv.slice(2);
+    if (argv.length === 1 && ['--version', '-V', 'version'].includes(argv[0])) {
+      process.stdout.write(`${require('../package.json').version}\n`);
+      return;
+    }
+    if (!argv.length) { process.stdout.write(`${helpText}\n`); return; }
+    const parsed = parseArgs(argv);
     command = parsed.command;
     if (parsed.options.help || command === 'help') {
       const name = command === 'help' ? '' : command;

package/bin/command-registry.js

@@ -9,7 +9,7 @@ const { flutterActionSchema, webCommandSchema } = require('./shared-kernel/provi
 
 const commandDefinitions = [
   { command: 'runtime', domain: 'execution', summary: 'Inspect, start or orderly stop the shared local execution runtime. CLI exit and MCP disconnect leave operations running; stop cancels and drains them.', targetKind: 'host-runtime', options: ['operation'] },
-  { command: 'device-ownership', domain: 'execution', summary: 'Read device ownership, reconcile original completion and pending acknowledgements, or query a retained UIA receipt from Host FactStore by serial/runtimeEpoch/actionId. Never force-release or replay.', targetKind: 'android-device', options: ['operation', 'serial', 'timeoutMs', 'runtimeEpoch', 'actionId'] },
+  { command: 'device-ownership', domain: 'execution', summary: 'Read ownership, reconcile original completion, explicitly cancel a retained install by actionId, or read a retained UIA receipt by serial/runtimeEpoch/actionId. Installation cancellation abandons its original PM session; it does not roll back an installed APK.', targetKind: 'android-device', options: ['operation', 'serial', 'timeoutMs', 'runtimeEpoch', 'actionId'] },
   { command: 'uia-runtime', domain: 'advanced', summary: 'Read, start or orderly stop the Android API 33+ UIA node runtime. Start checks the phone process lock; unacknowledged original receipts are retained.', targetKind: 'android-device', options: ['operation', 'serial', 'adb', 'timeoutMs'] },
   { command: 'status', domain: 'core', summary: 'Read bridge status, app/device metadata, capture counts, and Flutter summary.', targetApp: true, options: ['packageName', 'port', 'serial', 'full'] },
   { command: 'tree', domain: 'core', summary: 'Read Android View tree from the in-app bridge.', targetApp: true, options: ['packageName', 'port', 'serial', 'compact', 'textFilter', 'resourceIdFilter', 'classFilter', 'visibleOnly', 'maxNodes', 'maxDepth'] },
@@ -22,7 +22,7 @@ const commandDefinitions = [
   { command: 'logcat', domain: 'diagnostics', summary: 'Read Android logcat with optional app pid, tag, level, and grep filters.', options: ['serial', 'packageName', 'pid', 'appPid', 'tag', 'level', 'grep', 'lines', 'since', 'follow', 'durationSec', 'clear'] },
   { command: 'install-apk', domain: 'app', summary: 'Start a supervised Intent installation. Use intent observe/decide for actual system UI; completion binds the original phone job/session and independently verifies installed APK bytes. Requires Android SDK aapt/apksigner.', options: ['serial', 'packageName', 'apkPath', 'allowDowngrade', 'timeoutMs', 'adb', 'adbTimeoutMs', 'aaptPath', 'apksignerPath', 'recordingDir'] },
   { command: 'clear-app-data', domain: 'app', summary: 'Clear app data once through explicit method: pm-clear (default) or runtime. No fallback on failure.', targetApp: true, options: ['serial', 'packageName', 'method'] },
-  { command: 'freeze-app', domain: 'app', summary: 'Optionally stop target app processes with SIGSTOP when dynamic UI needs stable evidence.', targetApp: true, options: ['serial', 'packageName', 'pid'] },
+  { command: 'freeze-app', domain: 'app', summary: 'Stop target App processes with SIGSTOP, including the SDK socket. Capture first; thaw before SDK reads or actions.', targetApp: true, options: ['serial', 'packageName', 'pid'] },
   { command: 'thaw-app', domain: 'app', summary: 'Resume target app processes with SIGCONT before reads, waits, captures, actions, or final handoff.', targetApp: true, options: ['serial', 'packageName', 'pid'] },
   { command: 'launch-app', domain: 'app', summary: 'Launch the target package LAUNCHER Activity and report launcher candidates.', targetApp: true, options: ['serial', 'packageName', 'activity', 'component', 'action', 'category', 'data', 'extra', 'clearTask'] },
   { command: 'launch-activity', domain: 'app', summary: 'Launch an explicit Android Activity component with optional string extras.', targetApp: true, options: ['serial', 'packageName', 'activity', 'component', 'action', 'category', 'data', 'extra'] },
@@ -126,7 +126,7 @@ const isolatedCommandDefinitions = [
   {
     command: 'script',
     domain: 'execution',
-    summary: 'Run a trusted-local-code JavaScript or Python Script. Operations: start, status, wait, pause, resume, decide, cancel, runtime-status. Commands and assertions return results for Script code to handle; uncaught errors fail execution. Script source is not an OS sandbox.',
+    summary: 'Run a trusted-local-code JavaScript or Python Script. Operations: start, status, wait, result, pause, resume, decide, cancel, runtime-status. Commands and assertions return results for Script code to handle; uncaught errors fail execution. Script source is not an OS sandbox.',
     options: ['operation', 'waitMs', 'afterSequence', 'recordingDir'],
     runtime: 'trusted-local-code',
   },
@@ -238,13 +238,15 @@ const isolatedByName = new Map(isolatedCommandDefinitions.map(d => [d.command, d
 function isMutationCommand(command, args = {}) {
   if (command === 'web-command' && args.name === 'domSnapshot') return false;
   return mutationCommands.has(command) || (command === 'logcat' && args.clear === true)
+    || (command === 'device-ownership' && args.operation === 'cancel-install')
     || (command === 'ios-wda-session' && args.operation !== 'status')
     || (command === 'uia-runtime' && args.operation !== 'status')
     || ((command === 'webview-network' || command === 'webview-console') && args.script !== undefined);
 }
 
 function isAndroidMutation(command, args = {}) {
-  return isMutationCommand(command, args) && command !== 'runtime' && !command.startsWith('ios-') && !command.startsWith('web-');
+  return isMutationCommand(command, args) && !['runtime', 'device-ownership'].includes(command)
+    && !command.startsWith('ios-') && !command.startsWith('web-');
 }
 
 function executionTimeoutMs(command, args = {}) {
@@ -307,12 +309,13 @@ function commandSchema(command) {
     properties: { operation: { enum: ['start', 'status', 'stop'] } } };
   if (definition.domain === 'web') return require('./web/command-schema').webSchema(command);
   if (command === 'device-ownership') return { type: 'object', additionalProperties: false,
-    properties: { operation: { enum: ['status', 'reconcile', 'receipt'] }, serial: { type: 'string', minLength: 1 },
+    properties: { operation: { enum: ['status', 'reconcile', 'receipt', 'cancel-install'] }, serial: { type: 'string', minLength: 1 },
       runtimeEpoch: { type: 'string', pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' },
       actionId: { type: 'string', minLength: 1, maxLength: 1024 }, timeoutMs: { type: 'integer', minimum: 1, maximum: 30000 } },
     required: ['operation', 'serial'], oneOf: [
       { properties: { operation: { enum: ['status', 'reconcile'] }, runtimeEpoch: false, actionId: false } },
       { properties: { operation: { const: 'receipt' }, timeoutMs: false }, required: ['runtimeEpoch', 'actionId'] },
+      { properties: { operation: { const: 'cancel-install' }, runtimeEpoch: false }, required: ['actionId'] },
     ] };
   if (require('./ios-wda-port').commands.has(command)) {
     const names = ['deviceId', 'wdaRunnerBundleId', 'wdaUrl', 'devicectl', 'timeoutMs', ...executionOptions];
@@ -355,9 +358,9 @@ function commandSchema(command) {
       devicectl: optionTypes.devicectl, timeoutMs: optionTypes.timeoutMs },
     required: ['operation', 'deviceId'], oneOf: [
       { properties: { kind: { enum: ['h5', 'flutter'] }, wdaRunnerBundleId: false, wdaUrl: false },
-        required: ['bundleId'], anyOf: [
+        anyOf: [
           { properties: { operation: { enum: ['status', 'reconcile'] }, kind: false, actionId: false, runtimeEpoch: false } },
-          { properties: { operation: { enum: ['result', 'cancel'] } }, required: ['kind', 'actionId', 'runtimeEpoch'] },
+          { properties: { operation: { enum: ['result', 'cancel'] } }, required: ['bundleId', 'kind', 'actionId', 'runtimeEpoch'] },
         ] },
       { properties: { kind: { const: 'wda' }, bundleId: false, runtimeUrl: false, iosHost: false, iosPort: false },
         required: ['kind', 'wdaRunnerBundleId'], anyOf: [

package/bin/device-provider.js

@@ -2716,6 +2716,8 @@ async function launchApp(ctx, options = {}) {
     return {
       ok: false,
       error: 'launcher_not_found',
+      dispatched: false,
+      ambiguous: false,
       packageName: ctx.packageName,
       launcherCandidates: candidates,
     };
@@ -2724,6 +2726,8 @@ async function launchApp(ctx, options = {}) {
     return {
       ok: false,
       error: 'launcher_ambiguous',
+      dispatched: false,
+      ambiguous: false,
       packageName: ctx.packageName,
       launcherCandidates: candidates,
       suggestion: 'Pass --component or --activity to choose the intended launcher Activity.',

package/bin/intent/install-intent.js

@@ -15,6 +15,7 @@ const { checksumOf } = require('../shared-kernel/evidence-schema');
 const { createProductionIntentDeviceAdapter } = require('./intent-production-adapter');
 const { createIntentWorker } = require('./intent-worker');
 const { prepareInstallJob, settlementProof } = require('../shared-kernel/android-install-execution');
+const { sha256FileScript } = require('../shared-kernel/android-sha256');
 
 async function sha256(file) {
   const hash = crypto.createHash('sha256');
@@ -86,7 +87,9 @@ async function installedIdentity(args, artifact, run = execute) {
   }
   const devicePath = paths[0].slice('package:'.length);
   try {
-    const digest = (await command(['shell', 'sha256sum', devicePath])).stdout.trim().split(/\s+/)[0];
+    const script = sha256FileScript(devicePath);
+    const quoted = `'${script.replaceAll("'", "'\\''")}'`;
+    const digest = (await command(['shell', 'sh', '-c', quoted])).stdout.trim().split(/\s+/)[0];
     if (!/^[a-f0-9]{64}$/.test(digest)) return { known: false, installed: true, identityMatches: false, error: 'installed_hash_unavailable' };
     return { known: true, installed: true, path: devicePath, sha256: digest, identityMatches: digest === artifact.sha256,
       identitySource: 'exact installed APK bytes compared with the locally verified manifest and signer' };

package/bin/intent/intent-entry.js

@@ -80,7 +80,9 @@ async function start(args) {
     try {
       recording = createEvidenceRecording({ directory: args.recordingDir, namespace: 'intent', operationId, store,
         now: args.now || Date.now });
-    } catch (error) { return intentError(error.code || 'recording_failed', { operationId }); }
+    } catch (error) { return intentError(error.code || 'recording_failed', {
+      field: 'recordingDir', message: error.detail || error.message, dispatched: false, ambiguous: false,
+    }); }
   }
   reservedIds.add(operationId);
   let worker;

package/bin/ios-device-outcome.js

@@ -1,5 +1,14 @@
 'use strict';
 const { isDeepStrictEqual } = require('node:util');
+const { checksumOf } = require('./shared-kernel/evidence-schema');
+
+function matchesInvocation(reply, args) {
+  if (!Array.isArray(args)) return false;
+  const type = { 'device process launch': 'devicectl.device.process.launch',
+    'device install app': 'devicectl.device.install.app' }[args.slice(0, 3).join(' ')];
+  return Boolean(type && reply?.info?.commandType === type
+    && isDeepStrictEqual(reply.info.arguments, ['devicectl', ...args]));
+}
 
 // A normal process exit alone cannot settle a remote action. Only the original
 // devicectl JSON response, with its exact arguments and explicit OS rejection,
@@ -13,12 +22,7 @@ function deviceCommandRejection(reply, args, error) {
 // response and exact invocation with the pending operation before using it.
 function originalDeviceRejection(reply, args) {
   const command = args.slice(0, 3).join(' ');
-  const type = command === 'device process launch' ? 'devicectl.device.process.launch'
-    : command === 'device install app' ? 'devicectl.device.install.app' : null;
-  if (!type
-      || reply?.info?.jsonVersion !== 4 || reply.info.outcome !== 'failed'
-      || reply.info.commandType !== type
-      || !isDeepStrictEqual(reply.info.arguments, ['devicectl', ...args])) return null;
+  if (!matchesInvocation(reply, args) || reply.info.outcome !== 'failed') return null;
   const errors = [];
   function visit(value, depth) {
     if (!value || typeof value !== 'object' || depth > 16 || errors.length > 32) return;
@@ -36,6 +40,12 @@ function originalDeviceRejection(reply, args) {
       message: 'The selected iPhone has reached the free developer profile App limit. Remove an explicitly selected test App before installing another.',
       settled: true, dispatched: true, ambiguous: false, deviceOutcome: reply };
   }
+  if (errors.some(value => value.domain === 'com.apple.dt.CoreDeviceError' && value.code === 10002)
+      && errors.some(value => value.domain === 'NSOSStatusErrorDomain' && value.code === -10814)) {
+    return { ok: false, error: 'ios_app_not_installed',
+      message: 'The requested App is not installed on the selected iPhone.',
+      settled: true, dispatched: true, ambiguous: false, deviceOutcome: reply };
+  }
   const reason = errors.find(value => value.domain === 'FBSOpenApplicationErrorDomain' && [3, 7].includes(value.code));
   if (!errors.some(value => value.domain === 'FBSOpenApplicationServiceErrorDomain' && value.code === 1) || !reason) return null;
   return { ok: false, error: reason.code === 7 ? 'ios_device_locked' : 'ios_app_launch_rejected',
@@ -44,4 +54,16 @@ function originalDeviceRejection(reply, args) {
     settled: true, dispatched: true, ambiguous: false, deviceOutcome: reply };
 }
 
-module.exports = { deviceCommandRejection, originalDeviceRejection };
+function originalDeviceOutcome(reply, args) {
+  if (!matchesInvocation(reply, args)) return null;
+  if (reply.info.outcome === 'failed') return originalDeviceRejection(reply, args);
+  if (reply.info.outcome !== 'success' || !reply.result) return null;
+  return { ok: true, settled: true, dispatched: true, ambiguous: false, deviceOutcome: reply };
+}
+
+function deviceCommandProof(outcome, invocation) {
+  return { kind: 'ios-command', settled: true, dispatched: outcome.dispatched, ambiguous: false,
+    invocation, outcome, responseSha256: checksumOf(outcome.deviceOutcome) };
+}
+
+module.exports = { deviceCommandRejection, originalDeviceRejection, originalDeviceOutcome, deviceCommandProof };

package/bin/ios-execution.js

@@ -2,6 +2,8 @@
 
 const { randomUUID } = require('node:crypto');
 const { CommandError } = require('./command-errors');
+const fs = require('node:fs');
+const { originalDeviceOutcome, deviceCommandProof } = require('./ios-device-outcome');
 const managed = require('./shared-kernel/managed-sdk-execution');
 const { runDeviceEffect } = require('./shared-kernel/device-mutation-lease');
 const { checkExecution, runExecution } = require('./shared-kernel/execution-scope');
@@ -74,9 +76,26 @@ async function executeIOSAction({ port, kind, payload, status, target, timeoutMs
 }
 
 async function reconcileIOS({ lease, device, args, createPort }) {
-  return lease.reconcile(iosDeviceKey(device), async pending => {
+  const result = await lease.reconcile(iosDeviceKey(device), async pending => {
+    if (pending.target?.deviceId !== device.udid
+        || args.bundleId && pending.target?.bundleId && pending.target.bundleId !== args.bundleId) {
+      return { settled: false, error: 'ios_original_completion_identity_required' };
+    }
+    if (pending.kind === 'ios-command') {
+      const invocation = pending.invocation;
+      const index = Array.isArray(invocation?.arguments) ? invocation.arguments.indexOf('--json-output') : -1;
+      if (!invocation?.resultPath || index < 0 || invocation?.arguments?.[index + 1] !== invocation.resultPath) {
+        return { settled: false, error: 'ios_original_command_identity_unavailable' };
+      }
+      try {
+        const reply = JSON.parse(await fs.promises.readFile(invocation.resultPath, 'utf8'));
+        const outcome = originalDeviceOutcome(reply, invocation.arguments);
+        return outcome ? deviceCommandProof(outcome, invocation)
+          : { settled: false, error: 'ios_original_command_outcome_unresolved' };
+      } catch (error) { return { settled: false, error: 'ios_command_completion_unavailable', cause: error.code || 'invalid_json' }; }
+    }
     const kind = pending.kind === 'ios-h5' ? 'h5' : pending.kind === 'ios-flutter' ? 'flutter' : null;
-    if (!kind || pending.target?.deviceId !== device.udid || pending.target?.bundleId !== args.bundleId
+    if (!kind
       || typeof pending.actionId !== 'string' || typeof pending.runtimeEpoch !== 'string') {
       return { settled: false, error: 'ios_original_completion_identity_required' };
     }
@@ -103,6 +122,11 @@ async function reconcileIOS({ lease, device, args, createPort }) {
         || { settled: false, error: 'invalid_ios_completion_receipt' };
     } catch (error) { return { settled: false, error: error.code || 'ios_completion_query_failed', message: error.message }; }
   });
+  if (result.recovered && result.executionReceipt?.kind === 'ios-command') {
+    try { await fs.promises.rm(result.executionReceipt.invocation.resultPath, { force: true }); }
+    catch (error) { result.cleanupError = error.code || 'ios_command_receipt_cleanup_failed'; }
+  }
+  return result;
 }
 
 module.exports = { iosDeviceKey, executeIOSAction, lookupCompletion, reconcileIOS };

package/bin/ios-provider.js

@@ -3,7 +3,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { URL } = require('url');
-const { createHash } = require('node:crypto');
+const { createHash, randomUUID } = require('node:crypto');
 const { isDeepStrictEqual } = require('node:util');
 const { defaultArtifactPath, pruneGeneratedArtifacts } = require('./artifact-paths');
 const { execFileBounded, httpRequestBounded } = require('./shared-kernel/execution-io');
@@ -16,7 +16,7 @@ const { descriptorBinding, bindingHeaders, assertRuntimeResponse, bindingFailure
 const { openWdaPort, target: wdaTarget } = require('./ios-wda-port');
 const { prepareWdaProject, wdaBuildEnvironment } = require('./ios-wda-project');
 const { executeWDAAction, reconcileWDA, completionPort } = require('./ios-wda-execution');
-const { deviceCommandRejection } = require('./ios-device-outcome');
+const { deviceCommandRejection, deviceCommandProof } = require('./ios-device-outcome');
 const { bindFlutterAction } = require('./shared-kernel/flutter-target');
 const nativeTarget = require('./shared-kernel/ios-native-target');
 const h5Target = require('./shared-kernel/ios-h5-target');
@@ -60,7 +60,7 @@ class IOSBridgeProvider {
               result = { ...error.deviceOutcome, command };
             }
             return currentExecution()?.dispatched ? result : { ...result, dispatched: false, ambiguous: false };
-          });
+          }, undefined, { allowNested: true });
         });
       });
     } catch (error) {
@@ -89,9 +89,9 @@ class IOSBridgeProvider {
         case 'ios-setup':
           return await this.setup(args);
         case 'ios-install-app':
-          return await this.installApp(args);
+          return await this.installApp(args, context);
         case 'ios-launch-app':
-          return await this.launchApp(args);
+          return await this.launchApp(args, context);
         case 'ios-status':
           return await this.runtimeGet(args, '/v1/status');
         case 'ios-tree':
@@ -320,9 +320,9 @@ class IOSBridgeProvider {
     };
   }
 
-  async installApp(args = {}) {
+  async installApp(args = {}, { device: boundDevice } = {}) {
     const ctx = this.context(args);
-    const device = await this.requireDevice(args);
+    const device = boundDevice || await this.requireDevice(args);
     const appPath = requiredString(args.appPath, 'appPath');
     const resolvedPath = path.resolve(appPath);
     const raw = await this.devicectlJson(ctx, [
@@ -332,7 +332,7 @@ class IOSBridgeProvider {
       '--device',
       device.identifier || device.udid,
       resolvedPath,
-    ], { mutation: true });
+    ], { mutation: true, target: { deviceId: device.udid, bundleId: null } });
     return {
       ok: true,
       device,
@@ -341,9 +341,9 @@ class IOSBridgeProvider {
     };
   }
 
-  async launchApp(args = {}) {
+  async launchApp(args = {}, { device: boundDevice } = {}) {
     const ctx = this.context(args);
-    const device = await this.requireDevice(args);
+    const device = boundDevice || await this.requireDevice(args);
     const bundleId = requiredString(args.bundleId, 'bundleId');
     const launchArgs = [
       'device',
@@ -354,7 +354,7 @@ class IOSBridgeProvider {
     ];
     if (args.terminateExisting !== false) launchArgs.push('--terminate-existing');
     launchArgs.push(bundleId);
-    const raw = await this.devicectlJson(ctx, launchArgs, { mutation: true });
+    const raw = await this.devicectlJson(ctx, launchArgs, { mutation: true, target: { deviceId: device.udid, bundleId } });
     return {
       ok: true,
       device,
@@ -480,7 +480,7 @@ class IOSBridgeProvider {
       createPort: target => this.runtimePort(target, { device }) });
     if (args.operation === 'status') return {
       ok: true, device, ownership: lease.status(key),
-      runtime: await this.runtimeGet(args, '/v1/execution/status', { device, allowUnavailable: true }),
+      runtime: args.bundleId ? await this.runtimeGet(args, '/v1/execution/status', { device, allowUnavailable: true }) : null,
     };
     const port = await this.runtimePort(args, { device });
     const identity = { actionId: args.actionId, runtimeEpoch: args.runtimeEpoch };
@@ -809,8 +809,10 @@ class IOSBridgeProvider {
     }
   }
 
-  async devicectlJson(ctx, args, { mutation = false } = {}) {
-    const jsonPath = path.join(os.tmpdir(), `ai-app-bridge-devicectl-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`);
+  async devicectlJson(ctx, args, { mutation = false, target } = {}) {
+    const directory = mutation ? path.join((this.lease || getProcessDeviceMutationLease()).directory, 'ios-command-results') : os.tmpdir();
+    if (mutation) await fs.promises.mkdir(directory, { recursive: true, mode: 0o700 });
+    const jsonPath = path.join(directory, `ai-app-bridge-devicectl-${randomUUID()}.json`);
     const allArgs = [
       ...devicectlPrefix(ctx.devicectl),
       ...args,
@@ -819,7 +821,9 @@ class IOSBridgeProvider {
       '--json-output',
       jsonPath,
     ];
-    try {
+    let completed = false;
+    const invocation = { arguments: allArgs.slice(devicectlPrefix(ctx.devicectl).length), resultPath: jsonPath };
+    const invoke = async () => {
       const command = devicectlBinary(ctx.devicectl);
       try { await execFileText(this.execFile, command, allArgs, { timeoutMs: (ctx.deviceTimeoutSec * 1000) + 5000, mutation }); }
       catch (error) {
@@ -833,8 +837,27 @@ class IOSBridgeProvider {
         throw error;
       }
       return JSON.parse(await fs.promises.readFile(jsonPath, 'utf8'));
+    };
+    try {
+      if (!mutation) return await invoke();
+      let raw, rejected;
+      await runDeviceEffect({ kind: 'ios-command', target, invocation }, async () => {
+        try {
+          raw = await invoke();
+          return { ok: true, settled: true, dispatched: true, ambiguous: false, deviceOutcome: raw };
+        } catch (error) {
+          if (!error.deviceOutcome) throw error;
+          rejected = error;
+          return error.deviceOutcome;
+        }
+      }, outcome => deviceCommandProof(outcome, invocation));
+      completed = true;
+      if (rejected) throw rejected;
+      return raw;
     } finally {
-      await fs.promises.rm(jsonPath, { force: true });
+      // An unknown call may finish after the Host stops waiting. Its unique
+      // original output path is retained in ownership for public reconciliation.
+      if (!mutation || completed) await fs.promises.rm(jsonPath, { force: true });
     }
   }
 }

package/bin/script/script-supervisor.js

@@ -79,12 +79,14 @@ function createScriptSupervisor({
     let recording = null;
     if (args.recordingDir !== undefined) {
       if (compiled.spec.policy.restartPolicy !== 'none') {
-        return scriptError('recording_restart_unsupported', { operationId });
+        return scriptError('recording_restart_unsupported', { field: 'recordingDir', dispatched: false, ambiguous: false });
       }
       try {
         recording = createEvidenceRecording({ directory: args.recordingDir, namespace: 'script',
           operationId, store: args.store, now });
-      } catch (error) { return scriptError(error.code || 'recording_failed', { operationId }); }
+      } catch (error) { return scriptError(error.code || 'recording_failed', {
+        field: 'recordingDir', message: error.detail || error.message, dispatched: false, ambiguous: false,
+      }); }
     }
     const events = createBoundedEventLog({
       maxEvents: registry.maxEvents,

package/bin/shared-kernel/android-install-cancellation.js

@@ -0,0 +1,117 @@
+'use strict';
+const { createHash } = require('node:crypto');
+const shell = require('./android-shell-execution');
+const { execFileBounded } = require('./execution-io');
+const { executionSleep } = require('./execution-scope');
+const { checksumOf } = require('./evidence-schema');
+const { CommandError } = require('../command-errors');
+const root = '/data/local/tmp/ai-app-bridge-install/v1';
+const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const quote = value => `'${String(value).replaceAll("'", "'\\''")}'`;
+const original = identity => Object.fromEntries(['actionId', 'runtimeEpoch', 'jobId', 'installId', 'commandSha256']
+  .map(key => [key, identity[key]]));
+const argvFor = sessionId => ['pm', 'install-abandon', String(sessionId)];
+
+function validMapping(mapping, identity) {
+  return mapping?.schemaVersion === 'aab.android-install-cancellation/v1'
+    && mapping.original && typeof mapping.original === 'object'
+    && checksumOf(mapping.original) === checksumOf(original(identity))
+    && Number.isSafeInteger(mapping.sessionId) && mapping.sessionId > 0
+    && mapping.command?.schemaVersion === shell.schema && uuid.test(mapping.command?.jobId)
+    && Number.isSafeInteger(mapping.command?.deadlineUptimeMs) && mapping.command.deadlineUptimeMs > 0
+    && mapping.command?.runtimeEpoch === identity.runtimeEpoch
+    && mapping.command?.actionId === `install-abandon:${identity.installId}`
+    && mapping.command?.commandSha256 === createHash('sha256')
+      .update(`exec ${argvFor(mapping.sessionId).map(quote).join(' ')}\n`).digest('hex');
+}
+
+function cancellationProof(result, identity) {
+  const mapping = result?.mapping;
+  if (!require('./android-install-execution').validIdentity(identity) || !validMapping(mapping, identity)
+    || !shell.terminalReceipt(result.receipt, mapping.command) || !result.receipt.dispatched
+    || result.receipt.exitCode !== 0 || result.output?.stdout?.trim() !== 'Success') return null;
+  return { kind: 'android-install', ...original(identity), packageName: identity.packageName,
+    apkSha256: identity.apkSha256, sessionId: mapping.sessionId, phase: 'session-abandoned',
+    // Abandon prevents further work by this session. It neither uninstalls an
+    // already applied APK nor supplies the missing original commit outcome.
+    requestSucceeded: null, settled: true, dispatched: null, ambiguous: false,
+    cancellation: structuredClone(result), responseSha256: checksumOf(result) };
+}
+
+function createInstallCancellationPort({ adb = process.env.ADB || 'adb', serial, timeoutMs = 5000,
+  run = execFileBounded, shellPort = shell.createAndroidShellPort({ adb, serial, timeoutMs }) } = {}) {
+  async function staging(identity, script) {
+    if (!require('./android-install-execution').validIdentity(identity))
+      throw new CommandError('invalid_install_execution_identity', 'Cancellation requires the original installation identity.');
+    const guard = `if [ "$(cat /proc/sys/kernel/random/boot_id)" != ${quote(identity.runtimeEpoch)} ]; then printf '%s' '{"error":"shell_runtime_changed"}'; exit 0; fi\n`;
+    const reply = await run(adb, ['-s', serial, 'shell', 'sh', '-c', quote(guard + `job=${quote(`${root}/${identity.installId}`)}\n` + script)],
+      { timeoutMs, mutation: false, encoding: 'utf8', maxBuffer: 65536, windowsHide: true });
+    let value;
+    try { value = JSON.parse(reply.stdout); }
+    catch { throw new CommandError('invalid_install_cancellation_response', 'The original installation cancellation record is unreadable.'); }
+    if (value?.error) throw new CommandError(value.error, 'The original installation session could not be recovered.');
+    return value;
+  }
+  async function saved(identity) {
+    const value = await staging(identity, `if [ -f "$job/abandon.json" ]; then cat "$job/abandon.json"; else printf null; fi`);
+    if (value && !validMapping(value, identity))
+      throw new CommandError('invalid_install_cancellation_identity', 'The saved cancellation does not match this original installation and PM session.');
+    return value;
+  }
+  async function receipt(mapping) {
+    if (!mapping) return null;
+    const value = await shellPort.query(mapping.command);
+    return { mapping, receipt: value,
+      output: shell.terminalReceipt(value, mapping.command) ? await shellPort.output(mapping.command) : null };
+  }
+  return {
+    read: async identity => receipt(await saved(identity)),
+    async cancel(identity) {
+      let mapping = await saved(identity), previous;
+      if (mapping) {
+        const result = await receipt(mapping);
+        if (shell.terminalReceipt(result.receipt, mapping.command)) {
+          if (result.receipt.dispatched) return result;
+          // A confirmed admission rejection did not call PM. A new explicit
+          // request may replace it, retaining that proof with the new identity.
+          previous = { command: mapping.command, receipt: result.receipt };
+          mapping = null;
+        }
+      }
+      if (!mapping) {
+        const sessionId = await staging(identity, `session=$(cat "$job/session" 2>/dev/null)\n` +
+          `case "$session" in ''|*[!0-9]*) printf '%s' '{"error":"install_session_unavailable"}';; *) printf '%s' "$session";; esac`);
+        if (!Number.isSafeInteger(sessionId) || sessionId < 1)
+          throw new CommandError('install_session_unavailable', 'The original worker has not retained a PM installation session yet.');
+        mapping = { schemaVersion: 'aab.android-install-cancellation/v1', original: original(identity), sessionId,
+          ...(previous ? { previous } : {}),
+          command: await shellPort.prepare(argvFor(sessionId), `install-abandon:${identity.installId}`) };
+        if (!validMapping(mapping, identity)) throw new CommandError('invalid_install_cancellation_identity', 'Cancellation preparation changed the original device boot.');
+        // The physical ownership lock serializes writers. Persist the child job
+        // before admission so a lost Host can query that same job, never a new PM request.
+        await staging(identity, `printf '%s' ${quote(JSON.stringify(mapping))} >"$job/abandon.tmp" && mv "$job/abandon.tmp" "$job/abandon.json" || exit 1\nprintf true`);
+      }
+      let result = await receipt(mapping);
+      if (shell.terminalReceipt(result.receipt, mapping.command)) return result;
+      const submitted = await shellPort.start(mapping.command);
+      if (!submitted.ok && submitted.error !== 'shell_action_id_reused')
+        throw new CommandError(submitted.error || 'install_cancellation_submission_failed', 'The saved cancellation job could not be submitted.');
+      const deadline = Date.now() + timeoutMs;
+      do {
+        result = await receipt(mapping);
+        if (shell.terminalReceipt(result.receipt, mapping.command)) return result;
+        await executionSleep(60);
+      } while (Date.now() < deadline);
+      return result;
+    },
+    async acknowledge(identity, result) {
+      if (!cancellationProof(result, identity)) throw new CommandError('invalid_install_cancellation_receipt', 'Cleanup requires the saved session cancellation receipt.');
+      // The durable abandonment proof replaces the missing OEM callback for
+      // retirement. This exact PM session cannot consume the staged APK again.
+      await staging(identity, `rm -rf "$job" ${quote(`/data/local/tmp/ai-app-bridge-shell/v1/${identity.jobId}`)} || exit 1\nprintf true`);
+      return shellPort.acknowledge(result.mapping.command, result.receipt);
+    },
+  };
+}
+
+module.exports = { createInstallCancellationPort, cancellationProof };

package/bin/shared-kernel/android-install-execution.js

@@ -6,6 +6,7 @@ const { execFileBounded } = require('./execution-io');
 const { runExecution, withoutExecution, checkExecution, executionSleep } = require('./execution-scope');
 const { CommandError } = require('../command-errors');
 const { checksumOf } = require('./evidence-schema');
+const { sha256Shell } = require('./android-sha256');
 
 const schema = 'aab.android-install-execution/v1';
 const root = '/data/local/tmp/ai-app-bridge-install/v1';
@@ -26,7 +27,10 @@ function installScript(identity) {
     `  base64 "$job/result.out" | tr -d '\\n'\n` +
     `  printf '","stderr":"'; base64 "$job/result.err" | tr -d '\\n'; printf '"}'\n}\n` +
     `: >"$job/result.out"; : >"$job/result.err"\n` +
-    `actual=$(sha256sum "$job/base.apk"); actual=\${actual%% *}\n` +
+    // Preserve the exact v1 script hash so retained jobs remain reconcilable.
+    (identity.scriptVersion === 2 ? sha256Shell + `aab_select_sha256 || { emit hash-unavailable 1; exit 0; }\n` +
+      `actual=$(aab_sha256sum "$job/base.apk") || { emit hash-unavailable 1; exit 0; }; actual=\${actual%% *}\n`
+      : `actual=$(sha256sum "$job/base.apk"); actual=\${actual%% *}\n`) +
     `if [ "$actual" != ${quote(identity.apkSha256)} ]; then emit artifact-mismatch 1; exit 0; fi\n` +
     `pm install-create -r ${identity.allowDowngrade ? '-d ' : ''}-S ${identity.apkBytes} >"$job/result.out" 2>"$job/result.err"\ncode=$?\n` +
     `if [ "$code" -ne 0 ]; then emit create-failed "$code"; exit 0; fi\n` +
@@ -41,6 +45,7 @@ function installScript(identity) {
 
 function validIdentity(identity) {
   return identity?.kind === 'android-install' && uuid.test(identity.installId)
+    && (identity.scriptVersion === undefined || identity.scriptVersion === 2)
     && identity.schemaVersion === shell.schema && uuid.test(identity.jobId) && uuid.test(identity.runtimeEpoch)
     && typeof identity.actionId === 'string' && identity.actionId.length > 0 && identity.actionId.length <= 1024
     && Number.isSafeInteger(identity.deadlineUptimeMs) && identity.deadlineUptimeMs > 0
@@ -69,7 +74,7 @@ function settlementProof(result, identity) {
       // output stay unresolved. These names are final legacy PM failure codes.
       const failed = commit.code === 1 && /^Failure \[(?:INSTALL_FAILED_|INSTALL_PARSE_FAILED_)[A-Z_]+(?:: [\s\S]*)?\]$/.test(output);
       if (!requestSucceeded && !failed) return null;
-    } else if (!['artifact-mismatch', 'create-failed', 'create-invalid', 'write-failed'].includes(phase)
+    } else if (!['artifact-mismatch', 'hash-unavailable', 'create-failed', 'create-invalid', 'write-failed'].includes(phase)
       || commit.code === 0 || (phase === 'write-failed' ? !Number.isSafeInteger(sessionId) || sessionId < 1 : sessionId !== null)) return null;
   }
   return { kind: 'android-install', actionId: identity.actionId, runtimeEpoch: identity.runtimeEpoch,
@@ -86,10 +91,14 @@ function createAndroidInstallPort({ adb = process.env.ADB || 'adb', serial, time
   const command = args => run(adb, ['-s', serial, ...args], { timeoutMs: Math.min(timeoutMs, 30000), mutation: false,
     encoding: 'utf8', maxBuffer: 1024 * 1024, windowsHide: true });
   const staging = script => command(['shell', 'sh', '-c', quote(script)]);
+  const cancellation = require('./android-install-cancellation').createInstallCancellationPort({ adb, serial, timeoutMs, run, shellPort });
   return {
+    cancelInstall: identity => cancellation.cancel(identity),
+    readCancellation: identity => cancellation.read(identity),
+    acknowledgeCancellation: (identity, result) => cancellation.acknowledge(identity, result),
     async prepare(artifact, actionId, allowDowngrade = false) {
       const installId = randomUUID(), directory = `${root}/${installId}`;
-      const identity = { kind: 'android-install', installId, packageName: artifact.packageName,
+      const identity = { kind: 'android-install', scriptVersion: 2, installId, packageName: artifact.packageName,
         apkSha256: artifact.sha256, apkBytes: artifact.bytes, allowDowngrade };
       const staged = await staging(`umask 077\nmkdir -p ${quote(root)} || exit 1\nexec 0>${quote(root + '/prepare.lock')} || exit 1\nflock -x 0 || exit 1\n` +
         `count=0; for p in ${quote(root)}/*; do [ ! -d "$p" ] || count=$((count + 1)); done\n` +

package/bin/shared-kernel/android-sha256.js

@@ -0,0 +1,27 @@
+'use strict';
+
+// Android images expose the same SHA-256 operation as either a standalone tool
+// or a toybox/busybox applet. Select by an actual digest, not ROM or API level.
+const sha256Shell = `aab_sha256sum() {
+  case "$aab_sha256_provider" in
+    native) command sha256sum "$@";;
+    toybox) command toybox sha256sum "$@";;
+    busybox) command busybox sha256sum "$@";;
+  esac
+}
+aab_select_sha256() {
+  for aab_sha256_provider in native toybox busybox; do
+    aab_sha256_probe=$(aab_sha256sum /dev/null 2>/dev/null) || continue
+    [ "\${aab_sha256_probe%% *}" = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 ] && return 0
+  done
+  printf '%s\\n' 'SHA-256 unavailable: sha256sum, toybox sha256sum and busybox sha256sum were tried.' >&2
+  return 127
+}
+`;
+
+const quote = value => `'${String(value).replaceAll("'", "'\\''")}'`;
+function sha256FileScript(file) {
+  return `${sha256Shell}aab_select_sha256 || exit 127\naab_sha256sum ${quote(file)}`;
+}
+
+module.exports = { sha256Shell, sha256FileScript };

package/bin/shared-kernel/android-shell-execution.js

@@ -5,6 +5,7 @@ const { execFileBounded } = require('./execution-io');
 const { runExecution, checkExecution, currentExecution, withoutExecution, executionSleep, markExecutionDispatched } = require('./execution-scope');
 const { runDeviceEffect, isDeviceSettlementDurable } = require('./device-mutation-lease');
 const { CommandError } = require('../command-errors');
+const { sha256Shell } = require('./android-sha256');
 
 const schema = 'aab.android-shell-execution/v1';
 const rootDirectory = '/data/local/tmp/ai-app-bridge-shell/v1';
@@ -53,8 +54,10 @@ function createAndroidShellPort({ adb, serial, timeoutMs = 15000, run = execFile
         throw new CommandError('invalid_shell_arguments', 'Shell arguments must be nonempty string argv without NUL.');
       }
       const deadlineMs=Math.min(currentExecution()?.deadlineMs??Infinity,Date.now()+timeoutMs);
-      const probe=await request(`command -v setsid >/dev/null && command -v nohup >/dev/null || exit 1\n${uptimeScript}`+
+      const probe=await request(sha256Shell + `aab_select_sha256 || { printf '%s' '{"ok":false,"error":"android_sha256_unavailable"}'; exit 0; }\n` +
+        `command -v setsid >/dev/null && command -v nohup >/dev/null || exit 1\n${uptimeScript}`+
         `printf '{"runtimeEpoch":"%s","uptimeMs":%s}' "$(cat /proc/sys/kernel/random/boot_id)" "$uptime_ms"`);
+      if (probe.ok === false) throw new CommandError(probe.error, 'The device needs a working SHA-256 implementation: sha256sum, toybox sha256sum or busybox sha256sum.');
       if (!uuid.test(probe.runtimeEpoch)||!Number.isSafeInteger(probe.uptimeMs)||probe.uptimeMs<0) throw new CommandError('shell_runtime_unavailable', 'Android boot identity and monotonic uptime are unavailable.');
       const remaining=Math.floor(deadlineMs-Date.now());
       if(remaining<1)throw new CommandError('deadline_exceeded','The execution budget expired before shell preparation.');
@@ -65,11 +68,14 @@ function createAndroidShellPort({ adb, serial, timeoutMs = 15000, run = execFile
       const prefix = JSON.stringify(fields).slice(0,-1);
       const completedPrefix = `${prefix},"ok":true,"settled":true,"dispatched":true,"ambiguous":false,"exitCode":`;
       const expired = JSON.stringify({ ...fields, ok:false, error:'shell_action_timeout', settled:true, dispatched:false, ambiguous:false, exitCode:null });
+      const rejected = error => `printf '%s' ${quote(JSON.stringify({ ...fields, ok: false, error, settled: true,
+        dispatched: false, ambiguous: false, exitCode: null }))} >"$job/receipt.tmp" && mv "$job/receipt.tmp" "$job/receipt.json"; exit 0;`;
       const worker = `job=${quote(directory)}\n` +
         `if ! mkdir "$job/admission" 2>/dev/null; then exit 0; fi\n` +
         `if [ "$(cat /proc/sys/kernel/random/boot_id)" != ${quote(fields.runtimeEpoch)} ]; then exit 1; fi\n` +
-        `actual=$(sha256sum "$job/command.sh"); actual=\${actual%% *}\n` +
-        `if [ "$actual" != ${quote(fields.commandSha256)} ]; then exit 1; fi\n` +
+        sha256Shell + `aab_select_sha256 || { ${rejected('shell_sha256_unavailable')} }\n` +
+        `actual=$(aab_sha256sum "$job/command.sh") || { ${rejected('shell_command_hash_unavailable')} }; actual=\${actual%% *}\n` +
+        `if [ "$actual" != ${quote(fields.commandSha256)} ]; then ${rejected('shell_command_mismatch')} fi\n` +
         uptimeScript +
         `if [ "$uptime_ms" -ge ${fields.deadlineUptimeMs} ]; then printf '%s' ${quote(expired)} >"$job/receipt.tmp" && mv "$job/receipt.tmp" "$job/receipt.json"; exit 0; fi\n` +
         `ulimit -f 128 || exit 1\n` +
@@ -134,7 +140,8 @@ function terminalReceipt(result, identity) {
     && result.deadlineUptimeMs===identity.deadlineUptimeMs
     && result.settled===true && typeof result.dispatched==='boolean' && result.ambiguous===false
     && (result.dispatched ? result.ok===true && Number.isInteger(result.exitCode) && result.exitCode>=0 && result.exitCode<=255
-      : result.ok===false && ['shell_action_cancelled','shell_action_timeout'].includes(result.error) && result.exitCode===null);
+      : result.ok===false && ['shell_action_cancelled','shell_action_timeout','shell_sha256_unavailable',
+        'shell_command_hash_unavailable','shell_command_mismatch'].includes(result.error) && result.exitCode===null);
 }
 function settlementProof(result, identity) {
   if (!terminalReceipt(result, identity)) return null;

package/bin/shared-kernel/device-ownership-recovery.js

@@ -4,6 +4,7 @@ const { getProcessDeviceMutationLease } = require('./device-mutation-lease');
 const protocols = { flutter: require('./flutter-execution'), native: require('./native-execution'), h5: require('./h5-execution') };
 const shellProtocol = require('./android-shell-execution');
 const installProtocol = require('./android-install-execution');
+const { cancellationProof } = require('./android-install-cancellation');
 const uiaProtocol = require('./uia-protocol');
 const { createUiaRuntimePort } = require('./uia-runtime-port');
 const acknowledgements = require('./device-acknowledgements');
@@ -16,6 +17,8 @@ async function deviceOwnership(args, { lease = getProcessDeviceMutationLease(),
   const bridge = ports || require('../device-provider');
   const installCleanup = [];
   const recovered = await lease.reconcile(args.serial, async pending => {
+    if (args.operation === 'cancel-install' && (pending.kind !== 'android-install' || pending.actionId !== args.actionId))
+      return { settled: false, error: 'install_action_mismatch', actionId: pending.actionId };
     if (pending.kind === 'uia-node') {
       if (!uiaProtocol.validIdentity(pending) || pending.target.serial !== args.serial) return { settled: false, error: 'invalid_uia_execution_identity' };
       try {
@@ -32,11 +35,19 @@ async function deviceOwnership(args, { lease = getProcessDeviceMutationLease(),
       }
       try {
         const port = installPortFactory({ ...pending.target, timeoutMs: args.timeoutMs ?? 5000 });
-        const result = await port.read(pending, true);
+        let result, readError;
+        try { result = await port.read(pending, true); }
+        catch (error) { readError = error; }
         const proof = installProtocol.settlementProof(result, pending);
-        if (!proof) return { settled: false, error: 'install_completion_unavailable', actionId: pending.actionId };
-        installCleanup.push({ port, pending, result });
-        return proof;
+        if (proof) {
+          installCleanup.push({ port, pending, result });
+          return proof;
+        }
+        const cancellation = args.operation === 'cancel-install' ? await port.cancelInstall(pending) : await port.readCancellation?.(pending);
+        const cancelled = cancellationProof(cancellation, pending);
+        if (!cancelled) return { settled: false, error: readError?.code || 'install_completion_unavailable', actionId: pending.actionId };
+        installCleanup.push({ port, pending, result: cancellation, cancelled: true });
+        return cancelled;
       } catch (error) { return { settled: false, error: error.code || 'install_completion_query_failed' }; }
     }
     if (pending.kind === 'android-shell') {
@@ -71,8 +82,8 @@ async function deviceOwnership(args, { lease = getProcessDeviceMutationLease(),
   });
   // Reconciliation fsyncs each exact proof before its phone copy may be retired.
   // Even a later unresolved reservation cannot invalidate an earlier settlement.
-  for (const { port, pending, result } of installCleanup) {
-    try { await port.acknowledge(pending, result); }
+  for (const { port, pending, result, cancelled } of installCleanup) {
+    try { await (cancelled ? port.acknowledgeCancellation(pending, result) : port.acknowledge(pending, result)); }
     catch (error) { (recovered.cleanupErrors ||= []).push({ actionId: pending.actionId, error: error.code || 'install_cleanup_failed' }); }
   }
   if (recovered.error !== 'target_busy') {

package/bin/shared-kernel/evidence-recording.js

@@ -46,8 +46,10 @@ function createEvidenceRecording({ directory, namespace, operationId, store, now
   requireValue(typeof directory === 'string' && directory.trim().length > 0, 'invalid_recording_directory');
   requireValue(store && typeof store.persist === 'function', 'recording_store_required');
   const root = path.resolve(directory);
-  try { fs.mkdirSync(root); }
-  catch (error) { if (error.code === 'EEXIST') error.code = 'output_exists'; throw error; }
+  fs.mkdirSync(root, { recursive: true });
+  const stat = fs.lstatSync(root);
+  requireValue(stat.isDirectory() && !stat.isSymbolicLink(), 'invalid_recording_directory');
+  requireValue(fs.readdirSync(root).length === 0, 'output_exists', 'recordingDir must be empty; existing evidence is never overwritten.');
   const recordingId = crypto.randomUUID();
   let sequence = 0;
   let bytesWritten = 0;
@@ -64,6 +66,11 @@ function createEvidenceRecording({ directory, namespace, operationId, store, now
     return { name, bytes: bytes.length, sha256: sha256(bytes) };
   }
 
+  // Claim even an existing empty directory atomically before admitting work.
+  try {
+    write('recording.json', Buffer.from(JSON.stringify({ namespace, operationId, recordingId }) + '\n'));
+  } catch (error) { if (error.code === 'EEXIST') error.code = 'output_exists'; throw error; }
+
   function record({ kind, revision, target, data, parentFactId }) {
     if (failure) return Promise.resolve({ ok: false, error: failure });
     let metadata;

package/bin/shared-kernel/native-target.js

@@ -2,8 +2,9 @@
 
 const { checkExecution } = require('./execution-scope');
 
-// The top non-hidden Android window owns all semantic selection. Unknown or
-// disabled foreground roots block controls in earlier windows.
+// WindowInspector retains other Activities during transitions, and focus can
+// lag the current Activity. Select its window group, including dialogs/popups
+// sharing its focus owner. Older trees keep their window-order semantics.
 
 function visible(node) {
   return node && (node.effectiveVisible === true || node.visible === true)
@@ -20,7 +21,10 @@ function foregroundNativeWindow(rawTree) {
   if (!rawTree || typeof rawTree !== 'object') return null;
   const windows = Array.isArray(rawTree.windows) ? rawTree.windows : [];
   if (windows.length) {
-    const index = windows.findLastIndex(item => !explicitlyHidden(item?.root));
+    const activity = windows.findLast(item => item?.activityDecor === true && Object.hasOwn(item, 'focusOwnerWindowId'));
+    const index = windows.findLastIndex(item => !explicitlyHidden(item?.root)
+      && (!activity || item === activity || !Object.hasOwn(item || {}, 'focusOwnerWindowId')
+        || item.focusOwnerWindowId !== null && item.focusOwnerWindowId === activity.focusOwnerWindowId));
     if (index < 0) return null;
     const window = windows[index];
     return { index, root: window?.root, type: window?.type, windowId: window?.windowId,

package/bin/shared-kernel/summary-transformer.js

@@ -103,7 +103,7 @@ function walkNative(tree, visit) {
   }
   const index = { i: 0 };
   if (Array.isArray(tree?.windows) && tree.windows.length) {
-    // Match native action selection: the last non-hidden root owns the foreground.
+    // Match native action selection within the current Activity's window group.
     // An unknown/disabled root still blocks background controls. Do not spend the
     // summary budget on a long background page before exposing its modal dialog.
     const selected = foregroundNativeWindow(tree);

package/bin/shared-kernel/text-wait.js

@@ -7,15 +7,17 @@ const { looksLikeAndroidUiHierarchyXml, visitAndroidUiHierarchyTags } = require(
 const { runExecution, checkExecution, executionSleep } = require('./execution-scope');
 
 function validateTextConditions({ targetText, requireText = [], absentText = [], requireActivity, provider = 'auto' }) {
-  const invalid = message => { throw new CommandError('invalid_argument', message, { field: 'conditions' }); };
-  if (!['auto', 'native', 'flutter', 'uia'].includes(provider)) invalid('provider must be auto, native, flutter, or uia.');
-  if (targetText !== undefined && (typeof targetText !== 'string' || !targetText)) invalid('targetText must be a non-empty exact label.');
-  if (requireActivity !== undefined && (typeof requireActivity !== 'string' || !requireActivity)) invalid('requireActivity must be a full Activity class name.');
-  for (const values of [requireText, absentText]) if (!Array.isArray(values) || values.some(value => typeof value !== 'string' || !value)) invalid('requireText and absentText must be arrays of non-empty exact labels.');
+  const invalid = (field, message) => { throw new CommandError('invalid_argument', message, { field }); };
+  if (!['auto', 'native', 'flutter', 'uia'].includes(provider)) invalid('provider', 'provider must be auto, native, flutter, or uia.');
+  if (targetText !== undefined && (typeof targetText !== 'string' || !targetText)) invalid('targetText', 'targetText must be a non-empty exact label.');
+  if (requireActivity !== undefined && (typeof requireActivity !== 'string' || !requireActivity)) invalid('requireActivity', 'requireActivity must be a full Activity class name.');
+  for (const [field, values] of Object.entries({ requireText, absentText })) {
+    if (!Array.isArray(values) || values.some(value => typeof value !== 'string' || !value)) invalid(field, `${field} must be an array of non-empty exact labels.`);
+  }
   const present = [...new Set([...(targetText === undefined ? [] : [targetText]), ...requireText])];
-  if (!present.length && !absentText.length && !requireActivity) invalid('Supply targetText, requireText, absentText, or requireActivity.');
-  if (!present.length && provider === 'auto') invalid('Waiting for absence or Activity alone requires an explicit provider.');
-  if (present.some(value => absentText.includes(value))) invalid('The same label cannot be both required and absent.');
+  if (!present.length && !absentText.length && !requireActivity) invalid('targetText', 'Supply targetText, requireText, absentText, or requireActivity.');
+  if (!present.length && provider === 'auto') invalid('provider', 'Waiting for absence or Activity alone requires an explicit provider.');
+  if (present.some(value => absentText.includes(value))) invalid('absentText', 'The same label cannot be both required and absent.');
   return { present, absent: [...new Set(absentText)], requireActivity, provider };
 }
 

package/bin/shared-kernel/uia-runtime-port.js

@@ -1,4 +1,5 @@
 'use strict';
+const { sha256FileScript } = require('./android-sha256');
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -135,7 +136,7 @@ function createUiaRuntimePort({ adb, serial, timeoutMs = 10000, root = protocol.
     if (!/^[0-9]+$/.test(level) || Number(level) < 33) throw failure('uia_android_api_33_required', 'UIA node execution requires Android API 33 or newer.', { apiLevel: level });
     const destination = `${root}/runtime-${asset.manifest.sha256}.jar`;
     await shell(`umask 077\nmkdir -p ${quote(root)} && chmod 700 ${quote(root)}`);
-    const existingHash = await shell(`if [ -f ${quote(destination)} ]; then sha256sum ${quote(destination)}; else printf '%s' null; fi`);
+    const existingHash = await shell(`if [ -f ${quote(destination)} ]; then ${sha256FileScript(destination)}; else printf '%s' null; fi`);
     if (existingHash !== 'null') {
       if (existingHash.split(/\s+/)[0] !== asset.manifest.sha256)
         throw failure('uia_runtime_artifact_mismatch', 'An existing content-addressed UIA runtime artifact has different bytes.');
@@ -143,11 +144,11 @@ function createUiaRuntimePort({ adb, serial, timeoutMs = 10000, root = protocol.
     }
     const temporary = `${root}/runtime-${asset.manifest.sha256}.${randomUUID()}.tmp`;
     await invoke(['push', asset.file, temporary]);
-    const installedHash = (await shell(`sha256sum ${quote(temporary)}`)).split(/\s+/)[0];
+    const installedHash = (await shell(sha256FileScript(temporary))).split(/\s+/)[0];
     if (installedHash !== asset.manifest.sha256) throw failure('uia_runtime_artifact_mismatch', 'The phone runtime artifact hash differs from the installed CLI bundle.');
     // Never overwrite an executable that an existing runtime may still map.
     await shell(`mv -n ${quote(temporary)} ${quote(destination)}`);
-    const publishedHash = (await shell(`sha256sum ${quote(destination)}`)).split(/\s+/)[0];
+    const publishedHash = (await shell(sha256FileScript(destination))).split(/\s+/)[0];
     if (publishedHash !== asset.manifest.sha256) throw failure('uia_runtime_artifact_mismatch', 'The published UIA runtime artifact has different bytes.');
     await shell(`rm -f ${quote(temporary)}`);
     return destination;

package/docs/COMMAND_CONTRACT.md

@@ -299,13 +299,17 @@ This coordination covers one OS user sharing the same ownership directory.
 
 Use `ios-execution` through CLI or MCP:
 
-- `status`: requires `deviceId` and `bundleId`; returns Host ownership and SDK status.
-- `result`: additionally requires `kind:"h5"|"flutter"`, `actionId` and
+- `status`: requires `deviceId`; returns physical-device Host ownership. Supplying
+  `bundleId` also requests SDK status. An absent/offline App need not be queried.
+- `result`: additionally requires `bundleId`, `kind:"h5"|"flutter"`, `actionId` and
   `runtimeEpoch`; queries that original completion through bounded disk pages.
 - `cancel`: has the same identity fields as `result`; requests cancellation and
   reports the original completion or an unresolved result.
-- `reconcile`: requires `deviceId` and the original `bundleId`; reads the saved
-  pending identity and releases Host ownership only with its durable SDK receipt.
+- `reconcile`: requires `deviceId`; reads the saved pending identity and original
+  completion. For SDK actions it reconnects to the saved App and reads its durable
+  receipt. Generic install/launch uses the retained original devicectl JSON response
+  bound to its exact invocation, without requiring the App SDK. An optional
+  `bundleId` constrains recovery to that App.
 
 An explicit `runtimeUrl` or `iosHost`/`iosPort` can select the new connection used
 for recovery. Container verification still binds the same physical device and
@@ -315,7 +319,12 @@ run `reconcile` to resolve a retained Host reservation.
 
 These receipts prove the execution callback ended, not business success or all
 asynchronous work triggered by arbitrary App code. WDA has its separate Runner
-execution namespace below. Generic lost install/launch replies, simultaneous multi-WebView
+execution namespace below. An OS-confirmed missing App, locked device or known
+launch rejection is a settled failure and releases ownership. JSON format version
+numbers alone do not invalidate an otherwise matching structured reply. A lost
+reply remains unresolved until the original matching response is available; no
+command is rerun by reconciliation. Older pending jobs without saved invocation
+identity cannot be released using a guessed response. Simultaneous multi-WebView
 acceptance and complete complex iOS business coverage remain open. Native, H5 and
 Flutter Intent/Script are available within their implemented command contracts;
 availability does not establish production acceptance.
@@ -1430,6 +1439,16 @@ PackageInstaller session, writes the base APK, and commits that session. The
 session ID and original PackageManager CLI response are retained on the phone.
 `allowDowngrade` is opt-in. `streaming` has been removed and is rejected.
 
+Device-side SHA-256 is selected by computing a known digest using `sha256sum`,
+`toybox sha256sum`, or `busybox sha256sum`. Neither a standalone command nor a
+particular Android version is required for hashing. Shell execution, APK checks,
+installed-package verification and UIA asset checks share this capability probe.
+No weaker checksum is substituted. If no implementation works, staging fails
+with `android_sha256_unavailable` before a worker is admitted. If the tool or
+command file changes afterwards, the worker records a settled pre-dispatch failure
+instead of exiting without a receipt. New install scripts record `scriptVersion:2`;
+previous journal entries retain their original script identity for reconciliation.
+
 `timeoutMs` bounds device staging, admission and Host waiting (default 180000).
 APK inspection, initial/final installed-identity reads and UI observation still
 have separate bounded calls; this is not yet one end-to-end deadline. Inspectors
@@ -1450,7 +1469,7 @@ For example, after receiving a fresh observation:
 ```
 
 Completion requires the matching original shell-job receipt, a successful
-PackageInstaller commit response, and an independent `pm path`/`sha256sum` check
+PackageInstaller commit response, and an independent `pm path`/SHA-256 check
 of the installed bytes. The proof binds actionId, jobId, Android boot, command
 hash, admission deadline, installId, package and APK hash, and identifies the
 PackageInstaller session. The install receipt response hashes use canonical JSON
@@ -1573,3 +1592,12 @@ result. OEM restrictions may reject the shell identity with `permission_change_d
 `app.read` for queries. `permission-dialog` is a supervised operation and is not
 a synchronous Script primitive; fixed regression can replay known selectors with
 explicit state assertions, or request Agent help through `ctx.askAgent`.
+
+### Android 安装超时后的显式取消
+
+`device-ownership status` 返回原安装的 `actionId`。若原 commit 回执因 OEM 确认页丢失，
+可用 `device-ownership --operation cancel-install --serial SERIAL --action-id ORIGINAL_ACTION_ID`。
+该命令只对保留的原 PM session 执行 abandon，先持久保存取消任务身份，再派发；
+重连后 `reconcile` 可读取同一任务的原回执。明确成功才解除该安装的设备占用。
+`phase: session-abandoned` 的 `requestSucceeded: null` 表示原安装结果未被推断，
+已经安装的 APK 不会回滚。取消按钮、等待超时或 Host 进程退出本身仍不是完成证据。

package/docs/EVIDENCE_ARCHIVE.md

@@ -133,9 +133,11 @@ Archive integrity alone does not establish a passed business assertion.
 
 ## Explicit recording for one execution
 
-Add `recordingDir: "/absolute/existing-parent/new-recording"` to the
+Add `recordingDir: "/absolute/output/recording"` to the
 **arguments of `script start` or `intent start`**, alongside `script` or
-`goal`/`target`. The parent must exist and the directory must be new.
+`goal`/`target`. Missing parents are created; the directory may be new or empty.
+The Host claims it before admitting work. Nonempty directories are rejected to
+preserve existing evidence, with `field:"recordingDir"` and no admitted operation ID.
 This is opt-in file output for this execution; ordinary live calls do not
 copy mobile payloads to a Host history database.
 

package/docs/RELEASE.md

@@ -1,24 +1,26 @@
-# 0.3.1 发行与接入交接
+# 0.3.3 发行与接入交接
 
 本文件记录正式版的依赖关系和出仓库交付入口。封版要求是同一提交的源码、发行包与公开接入合同一致；单个样本的测试进度不改变包版本或发布状态。推送 Git、创建远端标签及发布 npm/pub 包由维护者执行。
 
-## 0.3.1 变更
+## 0.3.3 变更
 
-- CLI/MCP 默认发现返回精简目录；按 operation，以及 Intent decide 的 platform/provider/action 查询合同。完整合同仍可显式获取。
-- 合同中的重复 union 规则去重并展平；保留实际执行校验。
-- 随包 skill 保留目标、观察、回执和结果合同，详细文档按需读取。
-- Android、iOS、Flutter、Web 同步版本与固定依赖；设备执行行为没有新增改动。
+- 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 SDK | `0.3.1` | JitPack `com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-android:0.3.1` | 同名 Git tag，JitPack 对该提交成功构建 |
-| Android Gradle 插件 | `0.3.1` | JitPack `ai-app-bridge-gradle-plugin` 模块及插件 ID `io.github.mobileaidev.aiappbridge.android` | 与 SDK 相同的 Git tag；不再使用旧默认 `0.2.8` |
-| 原生 iOS SDK | Git tag `0.3.1` | Git URL 的仓库根 `Package.swift`，产品 `AiAppBridgeIOS` | 根清单包含 Swift runtime、C adapter 和 segmented C store，无外部 C 包路径 |
-| Flutter 插件 | `0.3.1` | pub `ai_app_bridge_flutter` | Android 固定依赖上述 SDK；iOS Swift/C 源码随插件分发 |
-| Desktop CLI/MCP | `0.3.1` | npm `@mobileaidev/ai-app-bridge` | 包含 UIA bundle、WDA 模板和 native store 源码；WDA 上游固定 `14.1.1` |
-| Web SDK | `0.3.1` | npm `@mobileaidev/ai-app-bridge-web` | 独立浏览器源码包，无 npm 对 CLI 的安装依赖 |
+| Android SDK | `0.3.3` | JitPack `com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-android:0.3.3` | 同名 Git tag，JitPack 对该提交成功构建 |
+| Android Gradle 插件 | `0.3.3` | JitPack `ai-app-bridge-gradle-plugin` 模块及插件 ID `io.github.mobileaidev.aiappbridge.android` | 与 SDK 相同的 Git tag；不再使用旧默认 `0.2.8` |
+| 原生 iOS SDK | Git tag `0.3.3` | Git URL 的仓库根 `Package.swift`，产品 `AiAppBridgeIOS` | 根清单包含 Swift runtime、C adapter 和 segmented C store，无外部 C 包路径 |
+| Flutter 插件 | `0.3.3` | pub `ai_app_bridge_flutter` | Android 固定依赖上述 SDK；iOS Swift/C 源码随插件分发 |
+| Desktop CLI/MCP | `0.3.3` | npm `@mobileaidev/ai-app-bridge` | 包含 UIA bundle、WDA 模板和 native store 源码；WDA 上游固定 `14.1.1` |
+| Web SDK | `0.3.3` | 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 打包进插件。
@@ -27,11 +29,11 @@ Host 支持范围声明为 Node `>=26.3.0 <27`，本轮实际验证基线是 **2
 
 ## 发布顺序
 
-1. 完成源码审阅并冻结一个提交，核对以下命令的产物确实来自它；包含当前 untracked 的实际源码、测试和文档，排除本机生成目录。所有对外发行版本使用同一个 `0.3.1`，若需要改版本，先同时更新上表涉及的 manifest 与固定依赖。
-2. 维护者推送提交与 `0.3.1` 标签，让 JitPack 构建 Android SDK/插件。确认两条公开坐标可解析后，再发布依赖它们的 Flutter 包。本地 Gradle project/path/AAR 替换不能证明 JitPack 坐标可消费。
+1. 完成源码审阅并冻结一个提交，核对以下命令的产物确实来自它；包含当前 untracked 的实际源码、测试和文档，排除本机生成目录。所有对外发行版本使用同一个 `0.3.3`，若需要改版本，先同时更新上表涉及的 manifest 与固定依赖。
+2. 维护者推送提交与 `0.3.3` 标签，让 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.1`，让已有候选入口也使用本次正式版。将 GitHub `main` 与发行提交同步，并创建非预发布的 GitHub Release。
+5. 同步 npm `next` 指向 `0.3.3`，让已有候选入口也使用本次正式版。将 GitHub `main` 与发行提交同步，并创建非预发布的 GitHub Release。
 6. 从 registry/tag 安装刚发布的确切版本，读取 `capabilities` 和版本，核对来源及支持范围，确认默认安装入口指向本次发行版本。正式发布不自动等于全平台生产验收完成。
 
 正式发布命令需在对应目录由维护者执行，例如 npm 使用 `npm publish --tag latest`；pub 使用 `flutter pub publish`。这些命令属于发布动作，不能混入本地验证脚本。
@@ -65,3 +67,15 @@ npm run verify:package -- ../../build/ai_app_bridge_artifacts/release-package-NE
 `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_2026-09-14.md`。
+Android Gradle 插件的 `webSocketCaptureEnabled`、`logInstrumentationEnabled`、
+`webViewDebuggingEnabled` 没有对应插桩实现，现明确弃用并在显式设置时输出提示；
+旧配置仍可构建。当前有效开关是 `enabled`、`okHttpCaptureEnabled`，以及可选
+`runtimeDependencyNotation`。不要把弃用选项的配置值当作采集功能已经启用。

package/docs/SCRIPT_AUTHORING.md

@@ -22,7 +22,7 @@ Call MCP `run` with this shape, replacing the target and source path:
       "entrypoint": "main",
       "target": {"platform":"android", "serial": "explicit-device", "packageName": "explicit.package"},
       "inputs": {},
-      "permissions": ["app.read", "app.interact"],
+      "permissions": ["app.read", "app.interact", "capture.read"],
       "policy": {"timeoutMs": 180000, "restartPolicy": "none"}
     }
   }
@@ -32,7 +32,7 @@ Call MCP `run` with this shape, replacing the target and source path:
 The same request is available through CLI:
 
 ```sh
-ai-app-bridge script --operation start --script '{"schemaVersion":"aab.code-script/v1","language":"javascript","sourcePath":"./flow.js","permissions":["app.read","app.interact"]}'
+ai-app-bridge script --operation start --script '{"schemaVersion":"aab.code-script/v1","language":"javascript","sourcePath":"./flow.js","permissions":["app.read","app.interact","capture.read"]}'
 ai-app-bridge script --operation status --operation-id RETURNED_ID
 ai-app-bridge script --operation result --operation-id RETURNED_ID
 ```
@@ -52,6 +52,16 @@ in a real Node child. Export `main`; use `ctx.inputs` for run-specific values.
 The source is trusted local code, not an OS sandbox. Use `ctx.call` for device
 operations so the Host can apply permissions and record receipts.
 
+An explicit `permissions` list replaces the defaults: `events`, `logs`, `network`
+and `state` need `capture.read`, included in both starting examples above.
+A transient `uia-tree` read rejected with `uia_tree_changed` and
+`dispatched:false` may be retried within a bounded wait for a stable snapshot.
+Do not use that read retry to replay a mutation with an unknown result.
+The repository fixture `scripts/validation/reader-regression.js` demonstrates
+this handling with Reader navigation, chapter restoration and captured events.
+It expects its documented book, chapters and font-size fixture; it records the
+installed SDK version without requiring an exact release number.
+
 `start` returns an operation ID without waiting for completion. Query `status`
 or `wait` with that `operationId`; `waitMs` bounds one wait and `afterSequence`
 pages execution events. Preserve every returned event page and inspect gaps.
@@ -93,7 +103,7 @@ source, throw to fail, and use explicit pause/resume/cancel control as needed.
 Use `status` or `wait` for progress; there is no separate `progress` operation.
 
 For a portable evidence run, add `recordingDir` to the start arguments with
-a new output directory. The Host records returned calls, assertions and
+a new or empty output directory. The Host records returned calls, assertions and
 referenced screenshots before bounded events are evicted. With
 `restartPolicy: "none"`, use public `evidence export` with
 `includeRecordedPayloads: true`, then offline `evidence verify` with the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mobileaidev/ai-app-bridge",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Desktop CLI and MCP server for AI App Bridge across Android, iOS, Flutter, WebView, and Web targets.",
   "repository": {
     "type": "git",