@mobileaidev/ai-app-bridge 0.3.4 → 0.3.5

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.4`, distributed through the npm `latest` dist-tag.
+This release is `0.3.5`, 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.4
+npm install -g @mobileaidev/ai-app-bridge@0.3.5
 
 ai-app-bridge status --package-name io.github.mobileaidev.aiappbridge.sample
 ai-app-bridge tree --package-name io.github.mobileaidev.aiappbridge.sample

package/bin/android-permissions.js

@@ -42,7 +42,7 @@ function uniqueBlock(lines, predicate, error) {
   return { header: lines[indexes[0]].trim(), lines: block(lines, indexes[0]) };
 }
 
-function parsePermissionState(text, { packageName, permission, userId }) {
+function parsePermissionState(text, { packageName, permission, userId }, definitions) {
   const pkg = uniqueBlock(text.split(/\r?\n/), line => line.startsWith(`Package [${packageName}] (`), 'permission_package_not_found');
   const appId = pkg.lines.map(line => /^\s+(?:appId|userId)=(\d+)\s*$/.exec(line)).filter(Boolean);
   if (appId.length !== 1 || Number(appId[0][1]) >= 100000) throw new CommandError('permission_state_unsupported', 'Android package appId is unavailable or ambiguous.');
@@ -50,6 +50,21 @@ function parsePermissionState(text, { packageName, permission, userId }) {
   if (!/\binstalled=true\b/.test(user.header)) throw new CommandError('permission_package_not_installed', 'The package is not installed for the requested Android user.');
   const runtime = uniqueBlock(user.lines, line => line === 'runtime permissions:', 'runtime_permission_not_found');
   const matches = runtime.lines.filter(line => line.trim().startsWith(`${permission}:`));
+  if (!matches.length && definitions !== undefined) {
+    // Android 7 omits untouched runtime permissions. Establish that the app
+    // requests a runtime permission and has no install grant before interpreting
+    // the absent PackageManager state as denied with no flags.
+    const requested = uniqueBlock(pkg.lines, line => line === 'requested permissions:', 'runtime_permission_not_found');
+    const targetSdk = pkg.lines.flatMap(line => [...line.matchAll(/\btargetSdk=(\d+)\b/g)]);
+    const definition = uniqueBlock(definitions.split(/\r?\n/), line => line.startsWith(`Permission [${permission}] (`), 'runtime_permission_not_found');
+    const protection = definition.lines.flatMap(line => [...line.matchAll(/\bprot=([^\s]+)/g)]);
+    if (targetSdk.length === 1 && Number(targetSdk[0][1]) >= 23
+        && requested.lines.some(line => line.trim() === permission)
+        && protection.length === 1 && protection[0][1].split('|')[0] === 'dangerous'
+        && !pkg.lines.some(line => line.trim().startsWith(`${permission}:`))) {
+      return { packageName, permission, userId, uid: userId * 100000 + Number(appId[0][1]), granted: false, flags: [] };
+    }
+  }
   const match = matches.length === 1 && /^\s*[^:]+:\s+granted=(true|false),\s*flags=\[([^\]]*)\]\s*$/.exec(matches[0]);
   if (!matches.length) throw new CommandError('runtime_permission_not_found', 'The requested permission has no runtime permission record for this package and user.');
   if (!match) throw new CommandError('permission_state_unsupported', 'Android returned an unrecognized runtime permission record.');
@@ -70,8 +85,15 @@ async function readPermissionState(args, run = execute) {
       userId = Number(current);
     }
     const dump = await androidCommand(args, ['shell', 'dumpsys', 'package', args.packageName], run);
+    let state;
+    try { state = parsePermissionState(dump.stdout, { ...args, userId }); }
+    catch (error) {
+      if (error.code !== 'runtime_permission_not_found') throw error;
+      const definitions = await androidCommand(args, ['shell', 'dumpsys', 'package', 'permissions'], run);
+      state = parsePermissionState(dump.stdout, { ...args, userId }, definitions.stdout);
+    }
     return { ok: true, source: 'android-package-manager', serial: args.serial,
-      ...parsePermissionState(dump.stdout, { ...args, userId }), capturedAtMs: Date.now() };
+      ...state, capturedAtMs: Date.now() };
   } catch (error) {
     if (error instanceof CommandError) throw error;
     throw new CommandError('permission_query_failed', 'Android permission state could not be read.', { details: { cause: error.code || null } });
@@ -125,7 +147,17 @@ function activityIdentity(value) {
 // the actual dialog, and PackageManager independently verifies the named permission.
 function parsePermissionRequest(text) {
   const lines = text.split(/\r?\n/);
-  const tops = lines.filter(line => /^\s*topResumedActivity=/.test(line)).map(activityIdentity);
+  let tops = lines.filter(line => /^\s*topResumedActivity=/.test(line)).map(activityIdentity);
+  if (!tops.length) {
+    // Before multi-resume, ActivityManager records one focused Activity and
+    // each stack's resumed Activity. Both identities must agree.
+    tops = lines.filter(line => /^\s*mFocusedActivity:/.test(line)).map(activityIdentity);
+    const resumed = lines.filter(line => /^\s*mResumedActivity:/.test(line)).map(activityIdentity);
+    if (tops.length !== 1 || !tops[0] || !resumed.some(value => value && value.token === tops[0].token
+        && value.component === tops[0].component && value.userId === tops[0].userId)) {
+      throw new CommandError('permission_request_unsupported', 'The focused and resumed Android Activity identities did not agree.');
+    }
+  }
   if (tops.length !== 1 || !tops[0]) throw new CommandError('permission_request_unsupported', 'One top-resumed Android Activity could not be identified.');
   const records = lines.flatMap((line, i) => /^\s*\* Hist\s+#\d+: ActivityRecord\{/.test(line) ? [{ ...activityIdentity(line), lines: block(lines, i) }] : []);
   const requests = records.filter(record => record.lines.some(line => line.trim().startsWith('Intent {') && line.includes(`act=${REQUEST_PERMISSIONS} `)));

package/bin/command-registry.js

@@ -10,7 +10,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 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: 'uia-runtime', domain: 'advanced', summary: 'Read, start or orderly stop the Android API 25+ 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'] },
   { command: 'uia-tree', domain: 'core', summary: 'Read UIAutomator XML for the current foreground window.', options: ['serial', 'compact', 'textFilter', 'resourceIdFilter', 'classFilter', 'visibleOnly', 'maxNodes', 'maxDepth'] },
@@ -70,7 +70,7 @@ const commandDefinitions = [
   { command: 'ios-devices', domain: 'ios', summary: 'List iOS devices known to xcrun devicectl.', targetKind: 'ios-device', options: ['deviceId'] },
   { command: 'ios-install-app', domain: 'ios', summary: 'Install an iOS .app bundle through devicectl.', targetKind: 'ios-app', options: ['deviceId', 'appPath'] },
   { command: 'ios-launch-app', domain: 'ios', summary: 'Launch an iOS app by bundle identifier through devicectl.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'terminateExisting'] },
-  { command: 'ios-execution', domain: 'ios', summary: 'Read SDK or WDA execution/physical ownership, cancel an original action, read its durable completion, or reconcile unknown ownership without replay.', targetKind: 'ios-app', options: ['operation', 'deviceId', 'bundleId', 'kind', 'actionId', 'runtimeEpoch', 'runtimeUrl', 'iosHost', 'iosPort', 'wdaRunnerBundleId', 'wdaUrl', 'devicectl', 'timeoutMs'] },
+  { command: 'ios-execution', domain: 'ios', summary: 'Read SDK or WDA execution/physical ownership, cancel an original action, read its durable completion, or reconcile unknown ownership without replay.', targetKind: 'ios-app', options: ['operation', 'deviceId', 'bundleId', 'kind', 'actionId', 'runtimeEpoch', 'runtimeUrl', 'iosHost', 'iosPort', 'wdaRunnerBundleId', 'wdaUrl', 'devicectl', 'timeoutMs', 'setupResultPath'] },
   { command: 'ios-status', domain: 'ios', summary: 'Read AiAppBridgeIOS runtime status.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'iosHost', 'iosPort', 'runtimeUrl'] },
   { command: 'ios-tree', domain: 'ios', summary: 'Read UIKit tree from the AiAppBridgeIOS runtime.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'iosHost', 'iosPort', 'runtimeUrl'] },
   { command: 'ios-logs', domain: 'ios', summary: 'Read in-app iOS log records.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'iosHost', 'iosPort', 'runtimeUrl', 'sinceId', 'sinceMs', 'limit'] },
@@ -202,7 +202,7 @@ define('orientation', require('./shared-kernel/ios-native-target').orientationSc
 define('selector', { type: 'string', minLength: 1 });
 define('spec', { type: 'object', additionalProperties: true });
 define('targetRef', require('./shared-kernel/uia-protocol').targetRefSchema);
-define('adb serial packageName artifactDir deviceId bundleId iosHost runtimeUrl wdaUrl wdaSessionId devicectl xcodebuild host path token appPath apkPath activity component action data initialRoute outFile permission op mode targetText requireText absentText requireActivity resourceId textFilter resourceIdFilter classFilter urlFilter method pageUrlFilter socketName targetId sessionId accessibilityId elementId wdaProjectPath wdaBundleId teamId displayUniqueId tag level grep since factCursor cursor runtimeEpoch afterActionId mobileFactId targetKey requestId deviceLogScope logcatFormat format agentModule pythonPath goal intent operationId recordingDir namespace outputDir archiveDir manifestSha256 name reason provider adapter', { type: 'string', minLength: 1 });
+define('adb serial packageName artifactDir deviceId bundleId iosHost runtimeUrl wdaUrl wdaSessionId devicectl xcodebuild host path token setupResultPath appPath apkPath activity component action data initialRoute outFile permission op mode targetText requireText absentText requireActivity resourceId textFilter resourceIdFilter classFilter urlFilter method pageUrlFilter socketName targetId sessionId accessibilityId elementId wdaProjectPath wdaBundleId teamId displayUniqueId tag level grep since factCursor cursor runtimeEpoch afterActionId mobileFactId targetKey requestId deviceLogScope logcatFormat format agentModule pythonPath goal intent operationId recordingDir namespace outputDir archiveDir manifestSha256 name reason provider adapter', { type: 'string', minLength: 1 });
 define('text value script payload', { type: 'string' });
 define('aaptPath apksignerPath', { type: 'string', minLength: 1 });
 define('full compact visibleOnly clear follow appPid force hideKeyboard noAutoHideKeyboard allowDowngrade clearTask exact skipFlutterLaunch includeResponseBody keepForward noBodies startWda terminateExisting clearFirst refresh includeActions history includeRecordedPayloads grepCaseSensitive includeCatalog', { type: 'boolean' });
@@ -355,14 +355,15 @@ function commandSchema(command) {
       actionId: { type: 'string', minLength: 1, maxLength: 256 }, runtimeEpoch: optionTypes.runtimeEpoch,
       wdaRunnerBundleId: optionTypes.wdaRunnerBundleId, wdaUrl: optionTypes.wdaUrl,
       runtimeUrl: optionTypes.runtimeUrl, iosHost: optionTypes.iosHost, iosPort: optionTypes.iosPort,
-      devicectl: optionTypes.devicectl, timeoutMs: optionTypes.timeoutMs },
+      devicectl: optionTypes.devicectl, timeoutMs: optionTypes.timeoutMs, setupResultPath: optionTypes.setupResultPath },
     required: ['operation', 'deviceId'], oneOf: [
       { properties: { kind: { enum: ['h5', 'flutter'] }, wdaRunnerBundleId: false, wdaUrl: false },
         anyOf: [
-          { properties: { operation: { enum: ['status', 'reconcile'] }, kind: false, actionId: false, runtimeEpoch: false } },
-          { properties: { operation: { enum: ['result', 'cancel'] } }, required: ['bundleId', 'kind', 'actionId', 'runtimeEpoch'] },
+          { properties: { operation: { const: 'status' }, kind: false, actionId: false, runtimeEpoch: false, setupResultPath: false } },
+          { properties: { operation: { const: 'reconcile' }, kind: false, actionId: false, runtimeEpoch: false } },
+          { properties: { operation: { enum: ['result', 'cancel'] }, setupResultPath: false }, required: ['bundleId', 'kind', 'actionId', 'runtimeEpoch'] },
         ] },
-      { properties: { kind: { const: 'wda' }, bundleId: false, runtimeUrl: false, iosHost: false, iosPort: false },
+      { properties: { kind: { const: 'wda' }, bundleId: false, runtimeUrl: false, iosHost: false, iosPort: false, setupResultPath: false },
         required: ['kind', 'wdaRunnerBundleId'], anyOf: [
           { properties: { operation: { enum: ['status', 'reconcile'] }, actionId: false, runtimeEpoch: false } },
           { properties: { operation: { enum: ['result', 'cancel'] } }, required: ['actionId', 'runtimeEpoch'] },

package/bin/ios-device-outcome.js

@@ -23,6 +23,23 @@ function deviceCommandRejection(reply, args, error) {
 function originalDeviceRejection(reply, args) {
   const command = args.slice(0, 3).join(' ');
   if (!matchesInvocation(reply, args) || reply.info.outcome !== 'failed') return null;
+  // CoreDevice rejects this launch while acquiring its prerequisites, before
+  // contacting the application service. Match the original structured failure,
+  // not stderr text or a general tunnel/timeout error.
+  const usage = reply.error;
+  const requested = usage?.userInfo?.RequestedDeviceStates?.array;
+  const available = usage?.userInfo?.CurrentlyAssertableStates?.array;
+  const prerequisites = ['com.apple.coredevice.remoteServiceDiscoveryTrustedConnectivityAvailable',
+    'com.apple.coredevice.coreDeviceServicesLoaded', 'com.apple.coredevice.powerAssertionTaken'];
+  if (command === 'device process launch' && !reply.result
+      && usage?.domain === 'com.apple.dt.CoreDeviceError' && usage.code === 4016
+      && Array.isArray(available) && available.length === 0
+      && Array.isArray(requested) && requested.length === prerequisites.length
+      && prerequisites.every(state => requested.some(value => value?.string === state))) {
+    return { ok: false, error: 'ios_device_unavailable',
+      message: 'CoreDevice rejected the launch before dispatch because the device connection and services were unavailable. Restore the device connection before launching again.',
+      settled: true, dispatched: false, ambiguous: false, deviceOutcome: reply };
+  }
   const errors = [];
   function visit(value, depth) {
     if (!value || typeof value !== 'object' || depth > 16 || errors.length > 32) return;

package/bin/ios-execution.js

@@ -4,6 +4,7 @@ const { randomUUID } = require('node:crypto');
 const { CommandError } = require('./command-errors');
 const fs = require('node:fs');
 const { originalDeviceOutcome, deviceCommandProof } = require('./ios-device-outcome');
+const { initializationProof, recoverLegacySetup } = require('./ios-wda-startup');
 const managed = require('./shared-kernel/managed-sdk-execution');
 const { runDeviceEffect } = require('./shared-kernel/device-mutation-lease');
 const { checkExecution, runExecution } = require('./shared-kernel/execution-scope');
@@ -75,12 +76,23 @@ async function executeIOSAction({ port, kind, payload, status, target, timeoutMs
   }, result => result.executionReceipt);
 }
 
-async function reconcileIOS({ lease, device, args, createPort }) {
+async function reconcileIOS({ lease, device, args, createPort, readWdaTestSummary }) {
+  const original = args.setupResultPath ? lease.status(iosDeviceKey(device)).ownership : null;
   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-wda-start' || pending.kind === 'ios-command' && pending.command === 'ios-setup') {
+      try {
+        const proof = pending.kind === 'ios-wda-start'
+          ? initializationProof(await readWdaTestSummary(pending.invocation.resultBundlePath), pending.invocation, device.udid)
+          : original?.pending?.id === pending.id && await recoverLegacySetup({ pending, owner: original.owner,
+            resultPath: args.setupResultPath, device, readSummary: readWdaTestSummary });
+        return proof || { settled: false, error: 'ios_original_wda_startup_outcome_unresolved' };
+      } catch (error) { return { settled: false, error: 'ios_wda_startup_completion_unavailable', cause: error.code || 'invalid_result' }; }
+    }
+    if (args.setupResultPath) 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;

package/bin/ios-provider.js

@@ -17,6 +17,7 @@ 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, deviceCommandProof } = require('./ios-device-outcome');
+const { initializationProof } = require('./ios-wda-startup');
 const { bindFlutterAction } = require('./shared-kernel/flutter-target');
 const nativeTarget = require('./shared-kernel/ios-native-target');
 const h5Target = require('./shared-kernel/ios-h5-target');
@@ -152,6 +153,22 @@ class IOSBridgeProvider {
     const ctx = this.context(args);
     const raw = await this.devicectlJson(ctx, ['list', 'devices']);
     const devices = parseDevicectlDevices(raw).map(shapeDevice);
+    const selected = selectDeviceFromList(devices, args).device;
+    if (selected && (selected.tunnelState !== 'connected' || selected.ddiServicesAvailable !== true)) {
+      // list devices can describe a sleeping tunnel. A targeted, read-only
+      // details request asks CoreDevice to establish its lazy connection.
+      try {
+        const reply = await this.devicectlJson(ctx, ['device', 'info', 'details', '--device', selected.identifier]);
+        const current = shapeDevice(reply?.result);
+        if (current.identifier !== selected.identifier || !current.udid || current.udid !== selected.udid) {
+          throw bindingFailure('ios_device_identity_mismatch', 'Device details did not match the selected device identifier and UDID.');
+        }
+        devices[devices.indexOf(selected)] = { ...current, connectionProbe: { ok: true, source: 'devicectl.device.info.details' } };
+      } catch (error) {
+        selected.connectionProbe = { ok: false, source: 'devicectl.device.info.details',
+          error: error.code || 'ios_device_probe_failed', message: error.message };
+      }
+    }
     return {
       ok: true,
       devices,
@@ -273,7 +290,9 @@ class IOSBridgeProvider {
       if (start.ok === true) {
         wda = start.status || await this.wdaStatus(args);
       } else {
-        return { ok: false, error: start.error, message: start.message, device, steps };
+        return { ok: false, error: start.error, message: start.message, device, steps,
+          ...(start.executionReceipt ? { settled: start.settled, dispatched: start.dispatched,
+            ambiguous: start.ambiguous, executionReceipt: start.executionReceipt } : {}) };
       }
     }
     steps.push({ name: 'wda', ok: wda.ok === true, url: wda.url || null, error: wda.error || null });
@@ -477,7 +496,7 @@ class IOSBridgeProvider {
       return lookupCompletion(completionPort(port), 'wda', identity, cancelled);
     }
     if (args.operation === 'reconcile') return reconcileIOS({ lease, device, args,
-      createPort: target => this.runtimePort(target, { device }) });
+      createPort: target => this.runtimePort(target, { device }), readWdaTestSummary: file => this.readWdaTestSummary(file) });
     if (args.operation === 'status') return {
       ok: true, device, ownership: lease.status(key),
       runtime: args.bundleId ? await this.runtimeGet(args, '/v1/execution/status', { device, allowUnavailable: true }) : null,
@@ -562,7 +581,9 @@ class IOSBridgeProvider {
       throw bindingFailure('ios_device_not_found', 'deviceId must match the selected devicectl identifier or UDID.');
     }
     if (device.developerModeStatus !== 'enabled' || device.ddiServicesAvailable !== true || device.tunnelState !== 'connected') {
-      throw bindingFailure('ios_tunnel_unavailable', 'The selected iPhone must expose a connected developer tunnel. Unlock/trust the device and let Xcode prepare it.');
+      throw bindingFailure('ios_tunnel_unavailable', device.connectionProbe?.ok === false
+        ? `The selected iPhone did not become ready after a targeted device details request: ${device.connectionProbe.message}`
+        : 'The selected iPhone does not expose ready developer services after the device details request. Inspect ios-doctor for the observed device state.');
     }
     const runtimeBinding = await this.readRuntimePortFile(args, device);
     const host = target.iosHost ?? device.tunnelIPAddress;
@@ -768,25 +789,47 @@ class IOSBridgeProvider {
       };
     } finally { await build.stop(); }
     const logFile = path.join(directory, 'xcodebuild.log');
-    const runtime = spawnWdaProcess(ctx.xcodebuild, [...xcodeArgs, 'test-without-building'], logFile, true);
-    const child = runtime.child;
-    let ready = false;
-    try {
-      while (!runtime.terminal) {
-        checkExecution();
-        const status = await this.wdaStatus({ ...args, deviceId: device.udid, wdaRunnerBundleId });
-        if (status.ok) {
-          ready = true; child.unref();
-          return { ok: true, device, wdaTestBundleId, wdaRunnerBundleId, pid: child.pid, logFile, buildLogFile, prepared, status };
+    const resultBundlePath = path.join(directory, 'result.xcresult');
+    const invocation = { arguments: [...xcodeArgs, '-resultBundlePath', resultBundlePath, 'test-without-building'],
+      resultBundlePath, startedAtMs: Date.now() };
+    return runDeviceEffect({ kind: 'ios-wda-start', command: 'ios-setup', invocation,
+      target: { deviceId: device.udid, bundleId: args.bundleId ?? null } }, async () => {
+      const runtime = spawnWdaProcess(ctx.xcodebuild, invocation.arguments, logFile, true);
+      const child = runtime.child;
+      let ready = false;
+      try {
+        while (!runtime.terminal) {
+          checkExecution();
+          const status = await this.wdaStatus({ ...args, deviceId: device.udid, wdaRunnerBundleId });
+          if (status.ok) {
+            ready = true; child.unref();
+            return { ok: true, device, wdaTestBundleId, wdaRunnerBundleId, pid: child.pid, logFile, buildLogFile, prepared, status,
+              executionReceipt: { kind: 'ios-wda-start', settled: true, dispatched: true, ambiguous: false, invocation,
+                runtimeBinding: status.runtimeBinding } };
+          }
+          await executionSleep(1000);
+        }
+        let proof;
+        if (!runtime.spawnError && runtime.exitCode === 65) {
+          try { proof = initializationProof(await this.readWdaTestSummary(resultBundlePath), invocation, device.udid); }
+          catch { /* An absent or unreadable original XCTest result remains unresolved. */ }
         }
-        await executionSleep(1000);
+        return { ok: false, error: runtime.spawnError ? 'ios_wda_xcodebuild_spawn_failed' : 'ios_wda_xcodebuild_exited',
+          message: runtime.spawnError?.message ?? 'xcodebuild closed before the selected Runner published a bound endpoint.',
+          phase: 'device-test', exitCode: runtime.exitCode, logFile, buildLogFile, prepared, resultBundlePath,
+          ...(runtime.spawnError ? { dispatched: false, ambiguous: false,
+            executionReceipt: { kind: 'ios-wda-start', settled: true, dispatched: false, ambiguous: false, invocation } } : {}),
+          ...(proof ? { ...proof.outcome, executionReceipt: proof } : {}) };
+      } finally {
+        if (!ready) await runtime.stop();
       }
-      return { ok: false, error: runtime.spawnError ? 'ios_wda_xcodebuild_spawn_failed' : 'ios_wda_xcodebuild_exited',
-        message: runtime.spawnError?.message ?? 'xcodebuild closed before the selected Runner published a bound endpoint.',
-        phase: 'device-test', exitCode: runtime.exitCode, logFile, buildLogFile, prepared };
-    } finally {
-      if (!ready) await runtime.stop();
-    }
+    }, result => result.executionReceipt);
+  }
+
+  async readWdaTestSummary(resultBundlePath) {
+    const reply = await execFileText(this.execFile, 'xcrun', ['xcresulttool', 'get', 'test-results', 'summary',
+      '--path', resultBundlePath, '--format', 'json'], { timeoutMs: 10000 });
+    return JSON.parse(reply.stdout);
   }
 
   async requireDevice(args = {}) {
@@ -987,7 +1030,9 @@ function withQuery(endpointPath, query) {
 function iosSetupSuggestion(device, runtime, wda) {
   if (!device) return 'Connect one iPhone, trust this Mac on the device, then rerun ios-doctor.';
   if (device.developerModeStatus !== 'enabled') return 'Enable Developer Mode on the iPhone and rerun ios-setup.';
-  if (device.ddiServicesAvailable !== true || device.tunnelState !== 'connected') return 'Unlock/trust the iPhone and let Xcode finish preparing a connected developer tunnel.';
+  if (device.ddiServicesAvailable !== true || device.tunnelState !== 'connected') return device.connectionProbe?.ok === false
+    ? `The device details probe failed: ${device.connectionProbe.message}`
+    : 'The device details probe did not establish ready developer services. Check the selected device connection and Xcode preparation state.';
   if (wda?.ok !== true) return 'Start the prepared Runner with ios-setup --start-wda --team-id, or supply its exact wdaRunnerBundleId. An optional wdaUrl still requires container binding.';
   if (runtime?.ok !== true) return 'Launch a debug App with AiAppBridgeIOS and supply its exact deviceId and bundleId.';
   return 'Rerun ios-setup after resolving the failing check.';

package/bin/ios-wda-startup.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const { getHostFactStore } = require('./shared-kernel/host-fact-store');
+
+const initializationFailure = 'The test runner failed to initialize for UI testing. (Underlying Error: Timed out while enabling automation mode.)';
+const digest = value => createHash('sha256').update(value).digest('hex');
+
+function initializationProof(summary, invocation, deviceId, completedAtMs = Date.now()) {
+  const args = invocation?.arguments;
+  if (!Array.isArray(args) || args[args.indexOf('-destination') + 1] !== `id=${deviceId}`
+      || args[args.indexOf('-scheme') + 1] !== 'WebDriverAgentRunner' || !args.includes('test-without-building')
+      || summary?.result !== 'Failed' || summary.totalTestCount !== 1 || summary.failedTests !== 1
+      || summary.passedTests !== 0 || summary.skippedTests !== 0 || summary.expectedFailures !== 0
+      || summary.devicesAndConfigurations?.length !== 1 || summary.devicesAndConfigurations[0].device?.deviceId !== deviceId
+      || summary.testFailures?.length !== 1 || summary.testFailures[0].targetName !== 'WebDriverAgentRunner'
+      || summary.testFailures[0].failureText !== initializationFailure
+      || !Number.isFinite(summary.startTime) || !Number.isFinite(summary.finishTime)
+      || summary.startTime * 1000 < invocation.startedAtMs || summary.finishTime < summary.startTime
+      || summary.finishTime * 1000 > completedAtMs) return null;
+  return { kind: 'ios-wda-start', settled: true, dispatched: true, ambiguous: false, invocation,
+    outcome: { ok: false, error: 'ios_wda_automation_confirmation_required', settled: true, dispatched: true, ambiguous: false,
+      message: 'XCTest ended before UI test initialization completed. Confirm Enable UI Automation on the iPhone, then explicitly run ios-setup again.' },
+    summary, summarySha256: digest(JSON.stringify(summary)) };
+}
+
+// Old setup markers lack a test invocation. Recovery requires the original
+// public response AND its retained Host action, not a newly supplied exit code.
+async function recoverLegacySetup({ pending, owner, resultPath, device, readSummary, readAction }) {
+  if (pending.command !== 'ios-setup' || pending.invocation || !resultPath) return null;
+  const bytes = await fs.promises.readFile(resultPath);
+  if (bytes.length > 4 * 1024 * 1024) return null;
+  const envelope = JSON.parse(bytes.toString('utf8'));
+  const result = envelope.kind === 'json' ? envelope.value : envelope;
+  const feedback = result?._feedback, times = feedback?.timings;
+  const evidence = feedback?.evidence?.filter(item => item.partition === 'action' && item.stored === true);
+  const steps = result?.steps?.filter(item => item.name === 'start-wda');
+  if (result?.error !== 'ios_wda_xcodebuild_exited' || result.device?.udid !== device.udid
+      || feedback?.dispatch?.command !== 'ios-setup' || feedback.target?.bundleId !== pending.target.bundleId
+      || evidence?.length !== 1 || !evidence[0].actionId?.startsWith(`host-action-${owner?.pid}-`)
+      || !Number.isSafeInteger(times?.startedAtMs) || !Number.isSafeInteger(times?.completedAtMs)
+      || times.startedAtMs > owner.acquiredAtMs || owner.acquiredAtMs > pending.preparedAtMs
+      || pending.preparedAtMs > times.completedAtMs || steps?.length !== 1
+      || steps[0].phase !== 'device-test' || steps[0].exitCode !== 65) return null;
+  const page = (readAction || (actionId => getHostFactStore().read({ partitions: ['action'], actionId, limit: 2 })))(evidence[0].actionId);
+  const fact = page.items?.[0];
+  if (page.ok !== true || page.items?.length !== 1 || fact.globalSeq !== evidence[0].globalSeq
+      || fact.payload?.command !== 'ios-setup' || fact.payload.status !== 'failed' || fact.payload.args?.startWda !== true
+      || fact.payload.args.deviceId !== result.device.identifier || fact.payload.args.bundleId !== pending.target.bundleId
+      || fact.payload.result?.error !== result.error || fact.timestamps?.occurredAtMs !== times.startedAtMs
+      || fact.timestamps.observedAtMs !== times.completedAtMs) return null;
+  const project = steps[0].prepared?.projectPath;
+  if (typeof project !== 'string' || path.basename(project) !== 'WebDriverAgent.xcodeproj') return null;
+  const directory = path.dirname(path.dirname(project));
+  if (steps[0].logFile !== path.join(directory, 'xcodebuild.log')) return null;
+  const resultsDirectory = path.join(directory, 'build', 'Logs', 'Test');
+  const bundles = (await fs.promises.readdir(resultsDirectory)).filter(name => name.endsWith('.xcresult'));
+  if (bundles.length !== 1) return null;
+  const invocation = { arguments: ['-project', project, '-scheme', 'WebDriverAgentRunner', '-destination', `id=${device.udid}`, 'test-without-building'],
+    resultBundlePath: path.join(resultsDirectory, bundles[0]), startedAtMs: pending.preparedAtMs };
+  const proof = initializationProof(await readSummary(invocation.resultBundlePath), invocation, device.udid, times.completedAtMs);
+  return proof && { ...proof, originalSetup: { pendingId: pending.id, actionId: fact.actionId,
+    globalSeq: fact.globalSeq, resultPath: path.resolve(resultPath), responseSha256: digest(bytes) } };
+}
+
+module.exports = { initializationProof, recoverLegacySetup };

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

@@ -100,6 +100,11 @@ async function deviceOwnership(args, { lease = getProcessDeviceMutationLease(),
       if (cleanup.errors.length) (recovered.cleanupErrors ||= []).push(...cleanup.errors);
     }
   }
+  if (args.operation === 'cancel-install' && recovered.ok && recovered.recovered === false) {
+    return { ...recovered, ok: false, error: 'install_action_not_pending', actionId: args.actionId,
+      message: 'No pending installation matches this action. Nothing was cancelled; read the original installation result to determine its outcome.',
+      dispatched: false, ambiguous: false };
+  }
   return recovered;
 }
 

package/bin/shared-kernel/uia-protocol.js

@@ -90,7 +90,7 @@ function actionRequest(binding, { timeoutMs, actionId = randomUUID(), clickPolic
 function validDescriptor(value, root) {
   return record(value) && validRoot(root) && value.schemaVersion === runtimeSchema
     && isUuid(value.bootId) && isUuid(value.runtimeEpoch) && isHash(value.dexSha256)
-    && Number.isSafeInteger(value.pid) && value.pid > 0 && Number.isSafeInteger(value.apiLevel) && value.apiLevel >= 33
+    && Number.isSafeInteger(value.pid) && value.pid > 0 && Number.isSafeInteger(value.apiLevel) && value.apiLevel >= 25
     && value.socketName === `aab-uia-${value.runtimeEpoch}` && isHash(value.token)
     && value.sessionPath === `${root}/sessions/${value.runtimeEpoch}` && typeof value.running === 'boolean';
 }

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

@@ -37,7 +37,7 @@ function createUiaRuntimePort({ adb, serial, timeoutMs = 10000, root = protocol.
       manifest = JSON.parse(fs.readFileSync(path.join(bundleDirectory, 'manifest.json'), 'utf8'));
       bytes = fs.readFileSync(path.join(bundleDirectory, 'ai-app-bridge-uia.jar'));
     } catch (error) { throw failure('uia_runtime_bundle_unavailable', 'The installed CLI has no complete UIA runtime bundle.', { cause: error.code }); }
-    if (manifest?.schemaVersion !== 'aab.uia.bundle.v1' || manifest.mainClass !== mainClass || manifest.minApi !== 33
+    if (manifest?.schemaVersion !== 'aab.uia.bundle.v1' || manifest.mainClass !== mainClass || manifest.minApi !== 25
       || manifest.artifact !== 'ai-app-bridge-uia.jar' || bytes.length > 2 * 1024 * 1024 || protocol.digest(bytes) !== manifest.sha256) {
       throw failure('uia_runtime_bundle_invalid', 'The UIA runtime artifact does not match its bundle manifest.');
     }
@@ -133,7 +133,7 @@ function createUiaRuntimePort({ adb, serial, timeoutMs = 10000, root = protocol.
 
   async function installAsset(asset) {
     const level = await shell('getprop ro.build.version.sdk');
-    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 });
+    if (!/^[0-9]+$/.test(level) || Number(level) < 25) throw failure('uia_android_api_25_required', 'UIA node execution requires Android API 25 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 ${sha256FileScript(destination)}; else printf '%s' null; fi`);

package/docs/COMMAND_CONTRACT.md

@@ -930,7 +930,7 @@ a mutation already running at timeout returns an ambiguous outcome. These checks
 do not make app touch handlers or business outcomes transactional.
 Explicit coordinate commands retain their primitive role.
 
-UIA observation and semantic clicks require Android API 33 or newer and the
+UIA observation and semantic clicks require Android API 25 or newer and the
 bundled, hash-verified `runtime/uia` module. `uia-tree` opens or reuses one
 UiAutomation connection on the explicit device. XML snapshots carry boot,
 runtime and snapshot IDs; each node has an opaque reference. Ordinary UIA text
@@ -938,6 +938,12 @@ commands, Intent (including installer and permission choices), and JavaScript /
 Python Script calls send that reference and their original action ID to the
 same runtime. They do not convert text matches into physical coordinates.
 
+API 25–32 use the process accessibility cache; API 33+ uses its connection
+cache. Before API 30, Android exposes only the default-display window inventory.
+All versions retain durable file and directory synchronization and original
+Binder callbacks. Device validation covers API 25, 30 and 36; this is not a
+claim that every vendor framework implementation has been tested.
+
 The runtime checks the focused default-display window, unique selector match,
 node attributes and clickable ancestor before one node action. Its guarantee
 is `same_connection_node_and_reobserved_attributes`, not a transaction across
@@ -966,6 +972,10 @@ ownership with actions. Stop requires committed terminal actions. Explicit start
 checks the phone's OS-managed process lock. A dead process can be reopened only
 after the new process acquires that lock and audits all original action records;
 any nonterminal or corrupt record blocks reopening, including after a reboot.
+The 0.3.5 audit compares a nodeRef selector with the receipt's `binding.ref`;
+the target attributes do not contain a `nodeRef` field. A successful audit may
+retire acknowledged sessions and publish a new epoch. It does not resurrect
+the old process or authorize replay of old actions.
 An HTTP timeout or a stale `running` descriptor does not authorize replacement.
 Authentication tokens
 stay in private phone descriptors and are absent from public status and Host
@@ -1600,9 +1610,33 @@ explicit state assertions, or request Agent help through `ctx.askAgent`.
 
 ### Android 安装超时后的显式取消
 
+`freeze-app` 使用 SIGSTOP 暂停整个 App 进程，包括 SDK HTTP 服务；冻结期间的
+`tree`、`status` 超时是预期行为。它不是只暂停业务 UI。先完成需要的读取，再冻结；
+后续 SDK 验证前必须 `thaw-app`，并重新确认可读。
+
 `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 进程退出本身仍不是完成证据。
+没有待处理安装时返回 `install_action_not_pending`、`recovered:false` 和
+`dispatched:false`。这同时适用于未知 actionId 和已经结算的安装；是否安装成功应读取
+原操作结果。未抓住安装中途的取消不能当作 PM abandon 验证。
+
+### iOS 设备连接与原始失败对账
+
+`devicectl list devices` 可以返回休眠隧道快照。`ios-devices` 对唯一或显式选择的未就绪
+设备执行只读 `device info details`，核对 identifier/UDID 后使用当前隧道和 DDI 状态；
+`connectionProbe` 保留结果。多设备未选择时不会唤醒任意一台。`ios-doctor` 的
+`deviceConnected` 指开发者隧道可用，USB 配对与传输方式另见 selectedDevice。
+
+`ios-execution reconcile` 可以识别原 launch 的 CoreDevice 4016 回执：要求精确调用、
+失败 outcome、完整请求状态以及空的可用状态，且没有启动 result。它是已结算的启动前
+拒绝；一般超时、丢连接和不匹配的 JSON 仍不能解除所有权。
+
+### WDA startup outcome recovery
+
+`ios-setup --start-wda true` records the exact XCTest invocation and result bundle before starting the device test. A completed XCTest failure that explicitly says UI test initialization timed out while enabling automation is a settled failed startup (`ios_wda_automation_confirmation_required`). The Runner launch was dispatched; this does not undo its installation. Confirm Enable UI Automation on the device, then explicitly run setup again.
+
+`ios-execution --operation reconcile --device-id DEVICE` reads the original result bundle after an interrupted Host. For a legacy generic `ios-setup` marker, supply `--setup-result-path ORIGINAL_RESPONSE.json`: recovery requires the original CLI JSON response (or its unwrapped value), its matching retained Host action in the current FactStore, the same device and startup interval, and the original XCTest bundle identified by that response. Missing, mismatched, or generic test failures remain unresolved. This option is accepted only for SDK/command reconciliation, never action cancellation or WDA session recovery. Lock files and original evidence are retained.

package/docs/INTENT_FOREGROUND.md

@@ -29,7 +29,7 @@ choosing any action. The Host does not retry the read or substitute a provider.
 
 The summary contains `provider` and `foreground` (`packageName`, `activity`, `component`, probe source and timestamps). Observation, decision, dispatch marker and receipt records preserve that route. The original `target` continues to identify the business operation and its app capture streams. System UIA observations do not imply that system-app network/state/event capture is available.
 
-Actions inherit the provider of their committed observation. An explicit conflicting provider is rejected. Before dispatch, the adapter checks the foreground component again; a changed component returns `reobserve_required` without dispatching a tap. Exact UIA taps use the API 33+ phone node runtime. Its `uia-node` execution receipt binds the Intent action ID, original request hash, runtime epoch, node/window attributes and original callback. The selected node is revalidated on the same automation connection before dispatch. A callback still requires a fresh observation and business checks; it does not create system-app SDK events.
+Actions inherit the provider of their committed observation. An explicit conflicting provider is rejected. Before dispatch, the adapter checks the foreground component again; a changed component returns `reobserve_required` without dispatching a tap. Exact UIA taps use the API 25+ phone node runtime. Its `uia-node` execution receipt binds the Intent action ID, original request hash, runtime epoch, node/window attributes and original callback. The selected node is revalidated on the same automation connection before dispatch. A callback still requires a fresh observation and business checks; it does not create system-app SDK events.
 
 Device-scoped physical taps remain managed Android shell input. Cancellation
 and recovery follow the selected executor's admission and completion contract.

package/docs/RELEASE.md

@@ -1,11 +1,15 @@
-# 0.3.4 发行与接入交接
+# 0.3.5 发行与接入交接
 
 本文件记录正式版的依赖关系和出仓库交付入口。封版要求是同一提交的源码、发行包与公开接入合同一致；单个样本的测试进度不改变包版本或发布状态。推送 Git、创建远端标签及发布 npm/pub 包由维护者执行。
 
-## 0.3.4 变更
+## 0.3.5 变更
 
-- CLI 和 MCP 按实际解析后的 ADB 可执行文件判断共享 Runtime 配置；PATH 查找、绝对路径和符号链接指向同一文件时可共享。启动时固定解析路径；不同可执行文件仍拒绝混用，缺少 ADB 不阻塞无设备依赖的能力。
-- 同步全部发行渠道版本；SDK 的设备行为与 0.3.3 相同。
+- 修正 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 修复
 
@@ -20,12 +24,12 @@
 
 | 交付物 | 发行版本 | 独立消费入口 | 发布依赖 |
 | --- | --- | --- | --- |
-| Android SDK | `0.3.4` | JitPack `com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-android:0.3.4` | 同名 Git tag，JitPack 对该提交成功构建 |
-| Android Gradle 插件 | `0.3.4` | JitPack `ai-app-bridge-gradle-plugin` 模块及插件 ID `io.github.mobileaidev.aiappbridge.android` | 与 SDK 相同的 Git tag；不再使用旧默认 `0.2.8` |
-| 原生 iOS SDK | Git tag `0.3.4` | Git URL 的仓库根 `Package.swift`，产品 `AiAppBridgeIOS` | 根清单包含 Swift runtime、C adapter 和 segmented C store，无外部 C 包路径 |
-| Flutter 插件 | `0.3.4` | pub `ai_app_bridge_flutter` | Android 固定依赖上述 SDK；iOS Swift/C 源码随插件分发 |
-| Desktop CLI/MCP | `0.3.4` | npm `@mobileaidev/ai-app-bridge` | 包含 UIA bundle、WDA 模板和 native store 源码；WDA 上游固定 `14.1.1` |
-| Web SDK | `0.3.4` | npm `@mobileaidev/ai-app-bridge-web` | 独立浏览器源码包，无 npm 对 CLI 的安装依赖 |
+| Android SDK | `0.3.5` | JitPack `com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-android:0.3.5` | 同名 Git tag，JitPack 对该提交成功构建 |
+| Android Gradle 插件 | `0.3.5` | JitPack `ai-app-bridge-gradle-plugin` 模块及插件 ID `io.github.mobileaidev.aiappbridge.android` | 与 SDK 相同的 Git tag；不再使用旧默认 `0.2.8` |
+| 原生 iOS SDK | Git tag `0.3.5` | Git URL 的仓库根 `Package.swift`，产品 `AiAppBridgeIOS` | 根清单包含 Swift runtime、C adapter 和 segmented C store，无外部 C 包路径 |
+| Flutter 插件 | `0.3.5` | pub `ai_app_bridge_flutter` | Android 固定依赖上述 SDK；iOS Swift/C 源码随插件分发 |
+| Desktop CLI/MCP | `0.3.5` | npm `@mobileaidev/ai-app-bridge` | 包含 UIA bundle、WDA 模板和 native store 源码；WDA 上游固定 `14.1.1` |
+| Web SDK | `0.3.5` | 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 打包进插件。
@@ -34,11 +38,11 @@ Host 支持范围声明为 Node `>=26.3.0 <27`，本轮实际验证基线是 **2
 
 ## 发布顺序
 
-1. 完成源码审阅并冻结一个提交，核对以下命令的产物确实来自它；包含当前 untracked 的实际源码、测试和文档，排除本机生成目录。所有对外发行版本使用同一个 `0.3.4`，若需要改版本，先同时更新上表涉及的 manifest 与固定依赖。
-2. 维护者推送提交与 `0.3.4` 标签，让 JitPack 构建 Android SDK/插件。确认两条公开坐标可解析后，再发布依赖它们的 Flutter 包。本地 Gradle project/path/AAR 替换不能证明 JitPack 坐标可消费。
+1. 完成源码审阅并冻结一个提交，核对以下命令的产物确实来自它；包含当前 untracked 的实际源码、测试和文档，排除本机生成目录。所有对外发行版本使用同一个 `0.3.5`，若需要改版本，先同时更新上表涉及的 manifest 与固定依赖。
+2. 维护者推送提交与 `0.3.5` 标签，让 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.4`，让已有候选入口也使用本次正式版。将 GitHub `main` 与发行提交同步，并创建非预发布的 GitHub Release。
+5. 同步 npm `next` 指向 `0.3.5`，让已有候选入口也使用本次正式版。将 GitHub `main` 与发行提交同步，并创建非预发布的 GitHub Release。
 6. 从 registry/tag 安装刚发布的确切版本，读取 `capabilities` 和版本，核对来源及支持范围，确认默认安装入口指向本次发行版本。正式发布不自动等于全平台生产验收完成。
 
 正式发布命令需在对应目录由维护者执行，例如 npm 使用 `npm publish --tag latest`；pub 使用 `flutter pub publish`。这些命令属于发布动作，不能混入本地验证脚本。
@@ -79,7 +83,7 @@ npm 升级不会替换已连接的 MCP 进程。用 `ai-app-bridge --version`
 已有工作结束后显式停止旧 Runtime，并在 Cursor 等客户端重连 MCP，核对 initialize
 中的 `serverInfo.version`。工具描述仍有旧 `batch`/`smoke` 时刷新客户端缓存。
 
-实际发布状态与验证边界见仓库 `docs/RELEASE_HANDOFF_2026-09-14.md`。
+实际发布状态与验证边界见仓库 `docs/RELEASE_HANDOFF_0.3.5_2026-09-14.md`。
 Android Gradle 插件的 `webSocketCaptureEnabled`、`logInstrumentationEnabled`、
 `webViewDebuggingEnabled` 没有对应插桩实现，现明确弃用并在显式设置时输出提示；
 旧配置仍可构建。当前有效开关是 `enabled`、`okHttpCaptureEnabled`，以及可选

package/docs/SCRIPT_AUTHORING.md

@@ -298,6 +298,13 @@ as `status` and `keyboard-state` whose `evidenceRefs` can be empty. References
 are preserved unchanged; these metadata fields do not create a capture ref or
 make incomplete or missing evidence valid for a device assertion.
 
+Python uses `ctx.assert_({...})` with one dictionary argument; `assert` is a
+Python keyword. JavaScript uses `ctx.assert({...})`. Both return a verdict that
+the script must check. A `status` response alone supplies no UI tree evidence,
+and `capture_page_limit` means that capture is incomplete. Drain the documented
+capture cursor before making a completeness assertion; do not relabel a partial
+capture as passed.
+
 `ctx.assert` returns `{verdict, name, scope, reason?}`. Verdict is `passed`,
 `failed`, or `inconclusive`; it does not throw or stop the program. Code must
 check the verdict and implement the intended stopping behavior. `throw` alone

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mobileaidev/ai-app-bridge",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Desktop CLI and MCP server for AI App Bridge across Android, iOS, Flutter, WebView, and Web targets.",
   "repository": {
     "type": "git",
@@ -66,6 +66,7 @@
     "bin/ios-wda-port.js",
     "bin/ios-wda-project.js",
     "bin/ios-wda-execution.js",
+    "bin/ios-wda-startup.js",
     "runtime/ios-wda",
     "LICENSE",
     "NOTICE",

package/runtime/uia/manifest.json

@@ -2,21 +2,22 @@
     "schemaVersion": "aab.uia.bundle.v1",
     "mainClass": "io.github.mobileaidev.aiappbridge.uia.UiaRuntime",
     "artifact": "ai-app-bridge-uia.jar",
-    "sha256": "50287a3e533fa54f995a2e14dcf886d8746931232416bba8c9a10e9e16de0d32",
-    "minApi": 33,
+    "sha256": "54a78985b47adf05e2db95a1c4deb25a093bbf3f2b158c75d1fb96aaaddd2c80",
+    "minApi": 25,
     "compileApi": 35,
     "buildTools": "36.0.0",
     "androidJarSha256": "4566663c3876e022b4fa4ced8c8697c4ab1688267f090114fd92d027b32e619b",
     "d8JarSha256": "4097ff9c46c185c6e7214da7fe9b1befb5adeea5cc9ca349270e0249904f9240",
     "sources": {
-        "android/ai-app-bridge-uia/build.gradle.kts": "a16e01b920da2e55823aedbfdf11cec449f5b1e31eb9335182554887cef06e56",
-        "android/ai-app-bridge-uia/src/main/java/io/github/mobileaidev/aiappbridge/uia/DurableFiles.java": "533130ad6d496005af84b99bc175e4ce237ad7c13a1b354f98c2a0e102f5baca",
+        "android/ai-app-bridge-uia/build.gradle.kts": "f43bc522ff813c1aa47619aab10310cdebb3388db40b344855966084bd7cc4b6",
+        "android/ai-app-bridge-uia/src/main/java/io/github/mobileaidev/aiappbridge/uia/AndroidPosix.java": "d1bf8163108ef2948b298831fc7e26a244822d122c07d47160ca182dbed609c6",
+        "android/ai-app-bridge-uia/src/main/java/io/github/mobileaidev/aiappbridge/uia/DurableFiles.java": "481723be04b95a94d3b71b86f155dae4e964f750e479d64541eaf12326d4dea2",
         "android/ai-app-bridge-uia/src/main/java/io/github/mobileaidev/aiappbridge/uia/UiaActionEngine.java": "e7cb3ba5b58d87a1024d6c0dd9eff24f07e74ca90fb716f898441255977c3e6f",
-        "android/ai-app-bridge-uia/src/main/java/io/github/mobileaidev/aiappbridge/uia/UiaConnection.java": "58237fba2d8f078c09e4019eda95c264ca985c320fa44270786adcf94dc659df",
+        "android/ai-app-bridge-uia/src/main/java/io/github/mobileaidev/aiappbridge/uia/UiaConnection.java": "907bc9b3439078766bff03b669cd6d0338d2b309e32403371583b03f60e5eea3",
         "android/ai-app-bridge-uia/src/main/java/io/github/mobileaidev/aiappbridge/uia/UiaHttp.java": "43447130a1829354e50c4df4dac2a66afea3ef7d9f8fa5732d773f526fc6e72a",
-        "android/ai-app-bridge-uia/src/main/java/io/github/mobileaidev/aiappbridge/uia/UiaJournal.java": "3cbbfa6070e9c7ee51c45bb4fa7e5330270cfb9b8c93809176834cadf36936ea",
-        "android/ai-app-bridge-uia/src/main/java/io/github/mobileaidev/aiappbridge/uia/UiaNodes.java": "4d31c535084283c1091c24dcf0ea007f287c1ace78055928920d0b24ac52ac49",
-        "android/ai-app-bridge-uia/src/main/java/io/github/mobileaidev/aiappbridge/uia/UiaRuntime.java": "b3382efdbddc1cf8e94953732846e35d10098aeb64fc6fcfba0d6bbd2f7f5a76",
+        "android/ai-app-bridge-uia/src/main/java/io/github/mobileaidev/aiappbridge/uia/UiaJournal.java": "718a367429c68b16f56418e36d6f73f9147508b85e424c15a8d81c061a82a892",
+        "android/ai-app-bridge-uia/src/main/java/io/github/mobileaidev/aiappbridge/uia/UiaNodes.java": "afd426091f98ff9114ac9947c1c124a1167f566cc875e2063f171c9e42a298cf",
+        "android/ai-app-bridge-uia/src/main/java/io/github/mobileaidev/aiappbridge/uia/UiaRuntime.java": "bfeb921d91977350e1ced62bbac850fcd12ee527e3d837904b4536c5ab9516a4",
         "android/ai-app-bridge-uia/src/main/java/io/github/mobileaidev/aiappbridge/uia/Wire.java": "d54e79c5e064abf5c7b36d2ab43205b7d47cca001ec37bf9b82ab01e33cf816c"
     }
 }