@mobileaidev/ai-app-bridge 0.3.5 → 0.3.6

package/README.md

@@ -7,12 +7,16 @@ 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.5`, distributed through the npm `latest` dist-tag.
+This source version is `0.3.6`; registry publication is a separate release step.
 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.
+Local package verification does not change npm dist-tags.
 The supported Node range is `>=26.3.0 <27`; this release was checked on 26.3.0.
 See [the release guide](docs/RELEASE.md) for local packaging and coordinated publication.
 
+Optional Android Instrumentation/UI Automator/Espresso/Compose/H5, Flutter integration_test,
+and Playwright executors use the existing `capabilities + run` and Python/JS Script contracts.
+See [integration, dependency profiles and lifecycle](docs/OPTIONAL_EXECUTORS.md).
+
 AI App Bridge CLI/MCP supports Android native apps, Android WebView/H5/CDP,
 Flutter apps on Android and iOS, iOS native apps via `AiAppBridgeIOS` plus
 WebDriverAgent/XCUITest, WKWebView, and desktop Web Bridge sessions.
@@ -56,7 +60,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.5
+npm install -g @mobileaidev/ai-app-bridge@0.3.6
 
 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

@@ -65,10 +65,12 @@ function parsePermissionState(text, { packageName, permission, userId }, definit
       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]);
+  // Android 7's Settings.permissionFlagsToString omits the entire suffix when flags == 0.
+  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.');
-  const flags = match[2].trim() ? match[2].split('|').map(value => value.trim()) : [];
+  // Nougat separates flags with spaces; newer dumps use pipes.
+  const flags = match[2] !== undefined && match[2].trim() ? match[2].trim().split(/\s*\|\s*|\s+/) : [];
   if (flags.some(value => !/^[A-Z][A-Z0-9_]*$/.test(value)) || new Set(flags).size !== flags.length) {
     throw new CommandError('permission_state_unsupported', 'Android returned unrecognized permission flags.');
   }

package/bin/command-discovery.js

@@ -80,12 +80,18 @@ function commandInputSchema(command, filters = {}) {
   }
   const schema = commandSchema(command);
   if (!Object.keys(filters).length) return schema;
+  if (require('./ui-observation').commands.has(command) && Object.keys(filters).every(key => key === 'operation')) {
+    const branch = schema.oneOf.find(entry => entry.properties.operation.const === filters.operation);
+    if (!branch) throw new CommandError('invalid_argument', 'Unknown UI observation operation.', { field: 'operation' });
+    const { oneOf, ...base } = schema;
+    return { ...base, properties: { ...base.properties, ...branch.properties }, required: [...base.required, ...(branch.required || [])] };
+  }
   const scope = ['platform', 'provider', 'action'].find(key => Object.hasOwn(filters, key));
   if (scope && (command !== 'intent' || filters.operation !== 'decide')) {
     throw new CommandError('invalid_argument', `${scope} is available only with command=intent and operation=decide.`, { field: scope });
   }
-  if (!['intent', 'script', 'evidence'].includes(command)) {
-    throw new CommandError('invalid_argument', 'Operation schema selection supports intent, script and evidence.', { field: 'operation' });
+  if (!['intent', 'script', 'evidence', 'web-executor', 'android-executor', 'flutter-executor'].includes(command)) {
+    throw new CommandError('invalid_argument', 'Operation schema selection supports intent, script, evidence and executor commands.', { field: 'operation' });
   }
   const selected = schema.anyOf.filter(branch => branch.properties.operation.const === filters.operation);
   if (!selected.length) throw new CommandError('invalid_argument', `Unknown ${command} operation: ${filters.operation}.`, { field: 'operation' });

package/bin/command-registry.js

@@ -8,6 +8,12 @@ const { executionCommandSchema, nativeGestureSchema, nativeSelector, flutterSele
 const { flutterActionSchema, webCommandSchema } = require('./shared-kernel/provider-command-contracts');
 
 const commandDefinitions = [
+  { command: 'ui-observation', domain: 'core', summary: 'Start a bounded UI observation window (100–5000 ms), inspect it, or stop its lease. Off by default; provider selects native or Flutter. New windows establish a fresh baseline.', targetApp: true, options: ['operation', 'provider', 'durationMs', 'leaseId', 'packageName', 'serial'] },
+  { command: 'ios-ui-observation', domain: 'ios', summary: 'Control bounded iOS native or Flutter UI observation. Off by default; expires locally even if the Host exits.', targetKind: 'ios-app', options: ['operation', 'provider', 'durationMs', 'leaseId', 'deviceId', 'bundleId'] },
+  { command: 'web-ui-observation', domain: 'web', summary: 'Control bounded Web DOM change observation. Off by default; expires locally even if the Host exits.', targetKind: 'web-target', options: ['operation', 'durationMs', 'leaseId', 'sessionId', 'runtimeEpoch', 'targetId'] },
+  { command: 'android-executor', domain: 'advanced', summary: 'Optional AndroidX UI Automator, Espresso and registered WebView/Compose test adapters. Open an installed androidTest build, observe, act on observed nodes, query original receipts and close. Opening instrumentation restarts the target application. Requires app.test in Script.', targetKind: 'android-app', options: ['operation'] },
+  { command: 'flutter-executor', domain: 'advanced', summary: 'Optional Flutter integration_test executor on Android. Open the installed application test entrypoint, observe widgets, run WidgetTester actions, query receipts and close the test process. Requires app.test in Script.', targetKind: 'android-app', options: ['operation'] },
+  { command: 'web-executor', domain: 'web', summary: 'Optional Playwright executor: inspect readiness, prepare pinned browser dependencies, open a browser, observe bound frames, act, wait, query original receipts, or close. Browser input and test operations retain their actual mechanisms. Script requires app.test.', targetKind: 'web-target', options: ['operation'] },
   { 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 25+ UIA node runtime. Start checks the phone process lock; unacknowledged original receipts are retained.', targetKind: 'android-device', options: ['operation', 'serial', 'adb', 'timeoutMs'] },
@@ -236,6 +242,9 @@ const commandByName = new Map(commandDefinitions.map(d => [d.command, d]));
 const isolatedByName = new Map(isolatedCommandDefinitions.map(d => [d.command, d]));
 
 function isMutationCommand(command, args = {}) {
+  if (require('./ui-observation').commands.has(command)) return args.operation !== 'status';
+  if (['android-executor', 'flutter-executor'].includes(command)) return ['open', 'act', 'close'].includes(args.operation);
+  if (command === 'web-executor') return ['prepare', 'open', 'act', 'navigate', 'close'].includes(args.operation);
   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')
@@ -251,6 +260,8 @@ function isAndroidMutation(command, args = {}) {
 
 function executionTimeoutMs(command, args = {}) {
   if (args.timeoutMs !== undefined) return args.timeoutMs;
+  if (['android-executor', 'flutter-executor'].includes(command)) return args.operation === 'open' ? 60000 : 30000;
+  if (command === 'web-executor') return args.operation === 'prepare' ? 300000 : 30000;
   if (iosSdkCommands.has(command) || command === 'ios-execution' || require('./ios-wda-port').commands.has(command)) return 30000;
   if (command === 'ios-setup') return 300000;
   if (command === 'ios-install-app') return 120000;
@@ -262,9 +273,10 @@ function executionTimeoutMs(command, args = {}) {
 // These are execution capabilities, independent of MCP/CLI transport. Script
 // permissions gate Bridge calls; trusted local code is not a process sandbox.
 const scriptPermissions = Object.freeze({
+  'app.test': ['web-executor', 'android-executor', 'flutter-executor'],
   'app.read': ['status', 'tree', 'uia-tree', 'screenshot', 'flutter-tree', 'flutter-nodes', 'h5-dom', 'flutter-h5-dom', 'keyboard-state', 'permission-state',
     'ios-status', 'ios-tree', 'ios-uia-tree', 'ios-screenshot', 'ios-flutter-tree', 'ios-flutter-nodes', 'ios-h5-dom', 'ios-wda-status', 'web-status', 'web-dom'],
-  'capture.read': ['logs', 'network', 'state', 'events', 'logcat', 'webview-console', 'webview-network', 'ios-logs', 'ios-network', 'ios-state', 'ios-events', 'web-logs', 'web-network', 'web-state', 'web-events'],
+  'capture.read': ['ui-observation', 'ios-ui-observation', 'web-ui-observation', 'logs', 'network', 'state', 'events', 'logcat', 'webview-console', 'webview-network', 'ios-logs', 'ios-network', 'ios-state', 'ios-events', 'web-logs', 'web-network', 'web-state', 'web-events'],
   'app.interact': ['launch-app', 'launch-activity', 'tap', 'tap-text', 'tap-uia-text', 'tap-uia', 'tap-native', 'input-text', 'swipe', 'native-gesture', 'keyevent', 'wait-text', 'hide-keyboard', 'tap-flutter', 'tap-flutter-text', 'input-flutter-text', 'scroll-flutter', 'h5-click', 'h5-input', 'h5-wait', 'h5-scroll', 'flutter-h5-click', 'flutter-h5-input', 'flutter-h5-wait', 'flutter-h5-scroll',
     'ios-h5-click', 'ios-h5-input', 'ios-h5-scroll', 'ios-launch-app', 'ios-wda-session', 'ios-tap', 'ios-input', 'ios-swipe', 'ios-set-orientation', 'ios-tap-native', 'ios-input-native-text', 'ios-tap-flutter', 'ios-input-flutter-text', 'ios-scroll-flutter', 'ios-flutter-back', 'ios-flutter-hide-keyboard', 'web-click', 'web-input', 'web-key', 'web-scroll', 'web-wait'],
   'app.lifecycle': ['clear-app-data'],
@@ -294,7 +306,7 @@ function commandContract(command) {
       providersByPlatform: { android: ['native', 'uia', 'flutter', 'h5'], ios: ['native', 'h5', 'flutter'], web: ['h5'] } } : {}),
     execution: { kind: role === 'execution' ? 'operation' : isMutationCommand(command) ? 'mutation' : 'query',
       mutation: isMutationCommand(command),
-      conditionalMutation: command === 'uia-runtime' ? 'operation != status' : command === 'logcat' ? 'clear=true' : ['webview-network', 'webview-console'].includes(command) ? 'script is supplied' : null,
+      conditionalMutation: command === 'web-executor' ? 'operation in prepare,open,act,navigate,close' : ['android-executor', 'flutter-executor'].includes(command) ? 'operation in open,act,close' : command === 'uia-runtime' ? 'operation != status' : command === 'logcat' ? 'clear=true' : ['webview-network', 'webview-console'].includes(command) ? 'script is supplied' : null,
       arbitration: command === 'script' || command === 'intent' ? 'target-platform-physical-device'
         : isAndroidMutation(command) ? 'cross-process-physical-android-device'
         : platform === 'ios' && isMutationCommand(command) ? 'cross-process-physical-ios-device'
@@ -305,6 +317,10 @@ function commandContract(command) {
 function commandSchema(command) {
   const definition = commandByName.get(command) || isolatedByName.get(command);
   if (!definition) throw new CommandError('unknown_command', `Unknown command: ${command}`, { field: 'command' });
+  if (require('./ui-observation').commands.has(command)) return require('./ui-observation').schema(command, optionTypes);
+  if (command === 'web-executor') return require('./executors/command-schema').webExecutorSchema();
+  if (command === 'android-executor') return require('./executors/command-schema').androidExecutorSchema();
+  if (command === 'flutter-executor') return require('./executors/command-schema').flutterExecutorSchema();
   if (command === 'runtime') return { type: 'object', additionalProperties: false, required: ['operation'],
     properties: { operation: { enum: ['start', 'status', 'stop'] } } };
   if (definition.domain === 'web') return require('./web/command-schema').webSchema(command);

package/bin/device-provider.js

@@ -79,10 +79,18 @@ async function runCommand(command, options, ctx) {
       return removeBridgeForward(ctx, adb);
     case 'status':
       return bridgeStatus(ctx, options);
+    case 'ui-observation':
+      return bridgeRequest(ctx, async () => {
+        const path = require('./ui-observation').path(options);
+        const result = JSON.parse(await httpPost(bridgeUrl(ctx, path), require('./ui-observation').request(options), ctx.httpTimeoutMs));
+        verifyBridgeTargetPackage(ctx, result, path);
+        return result;
+      });
     case 'tree':
       return bridgeTree(ctx, options);
     case 'flutter-tree': {
-      const status = await bridgeGet(ctx, '/v1/status');
+      const status = await bridgeGet(ctx, '/v1/flutter/snapshot');
+      if (status.ok === false) return status;
       return status.flutter?.layout || null;
     }
     case 'flutter-nodes':
@@ -2173,7 +2181,8 @@ async function waitText(ctx, targetText, options = {}, dependencies = {}) {
 }
 
 async function flutterNodes(ctx) {
-  const status = await bridgeGet(ctx, '/v1/status');
+  const status = await bridgeGet(ctx, '/v1/flutter/snapshot');
+  if (status.ok === false) return status;
   return status.flutter?.layout?.operable || { ok: false, error: 'no_flutter_operable_tree' };
 }
 

package/bin/execution-host.js

@@ -20,6 +20,9 @@ const {
 const iosProvider = new IOSBridgeProvider();
 const webProvider = new WebBridgeProvider();
 const targetExecution = new TargetExecution();
+let browserExecutor = null;
+let androidExecutor = null;
+let flutterExecutor = null;
 
 let sharedFactStore = null;
 let sharedFactRecorder = null;
@@ -47,6 +50,9 @@ function close() {
     await require('./script/script-entry').cancelActiveScripts();
     await require('./intent/intent-entry').cancelActiveIntents();
     await webProvider.close();
+    await browserExecutor?.close();
+    await androidExecutor?.close();
+    await flutterExecutor?.close();
     await Promise.allSettled([...activeRuns]);
     try { await sharedObservationCollector?.stop(); }
     finally {
@@ -579,6 +585,18 @@ function getSharedObservationCollector(factRecorder) {
 }
 
 async function runRawCommand(command, args = {}) {
+  if (command === 'android-executor') {
+    androidExecutor ||= new (require('./executors/android-host').AndroidExecutorHost)();
+    return androidExecutor.run(args);
+  }
+  if (command === 'flutter-executor') {
+    flutterExecutor ||= new (require('./executors/flutter-host').FlutterExecutorHost)();
+    return flutterExecutor.run(args);
+  }
+  if (command === 'web-executor') {
+    browserExecutor ||= new (require('./executors/playwright-host').PlaywrightHost)();
+    return browserExecutor.run(args);
+  }
   const definition = commandByName.get(command);
   if (definition?.domain === 'ios') return iosProvider.run(command, args);
   if (definition?.domain === 'web') return webProvider.run(command, args);

package/bin/executors/android-host.js

@@ -0,0 +1,201 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const { randomUUID, randomBytes, createHash } = require('node:crypto');
+const { CommandError } = require('../command-errors');
+const { currentExecution, checkExecution, markExecutionDispatched, withoutExecution, runExecution, executionSleep } = require('../shared-kernel/execution-scope');
+const { runDeviceEffect } = require('../shared-kernel/device-mutation-lease');
+const { executorHome, atomicJson, readJson } = require('./managed-runtime');
+const { AndroidExecutorPort, protocol, quote } = require('./android-port');
+
+const hash = value => createHash('sha256').update(value).digest('hex');
+function settlement(result, pending) {
+  if (result?.executionReceipt?.settled === true && result.executionReceipt.sessionId === pending.sessionId
+    && result.executionReceipt.runtimeEpoch === pending.runtimeEpoch && result.executionReceipt.actionId === pending.actionId) {
+    return { kind: pending.kind, sessionId: pending.sessionId, runtimeEpoch: pending.runtimeEpoch, actionId: pending.actionId,
+      settled: true, dispatched: result.executionReceipt.result?.dispatched === true, receipt: result.executionReceipt };
+  }
+  if (result?.ok === false && result.dispatched === false && result.ambiguous === false)
+    return { kind: pending.kind, sessionId: pending.sessionId, actionId: pending.actionId, settled: true, dispatched: false };
+  if (pending.operation === 'open' && result?.ok && result.protocol === pending.protocol && result.sessionId === pending.sessionId)
+    return { kind: pending.kind, sessionId: pending.sessionId, runtimeEpoch: result.runtimeEpoch, settled: true, dispatched: true, state: 'ready' };
+  if (['open', 'close'].includes(pending.operation) && result?.closed?.settled === true && result.closed.sessionId === pending.sessionId
+    && (pending.runtimeEpoch === null || result.closed.runtimeEpoch === pending.runtimeEpoch))
+    return { kind: pending.kind, sessionId: pending.sessionId, runtimeEpoch: pending.runtimeEpoch, settled: true, dispatched: true, state: 'closed' };
+  return null;
+}
+
+class AndroidExecutorHost {
+  constructor({ home = executorHome() } = {}) { this.home = home; this.sessions = new Map(); this.children = new Map(); }
+  get kind() { return 'android-test-executor'; }
+  createPort(descriptor) { return new AndroidExecutorPort(descriptor); }
+  async finishClose(port) {
+    if (!await port.processEnded()) return false;
+    await require('../shared-kernel/uia-runtime-port').createUiaRuntimePort({ adb: port.descriptor.adb, serial: port.descriptor.serial }).releaseInstrumentation(port.descriptor.sessionId);
+    return true;
+  }
+  directory(sessionId) {
+    if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(sessionId)) throw new CommandError('executor_session_mismatch', 'Invalid executor session ID.');
+    return path.join(this.home, 'sessions', 'android', sessionId);
+  }
+  load(args) {
+    const descriptor = readJson(path.join(this.directory(args.sessionId), 'session.json'));
+    if (!descriptor || descriptor.serial !== args.serial || descriptor.packageName !== args.packageName
+      || args.runtimeEpoch !== descriptor.runtimeEpoch) throw new CommandError('executor_session_mismatch', 'Executor target/session/generation does not match.');
+    let port = this.sessions.get(descriptor.sessionId);
+    if (!port) { port = this.createPort(descriptor); this.sessions.set(descriptor.sessionId, port); }
+    return port;
+  }
+  async run(args) {
+    const adb = args.adb || process.env.ADB || 'adb';
+    if (args.operation === 'status') {
+      const port = new AndroidExecutorPort({ adb, serial: args.serial });
+      const listing = await port.invoke(['shell', 'pm', 'list', 'instrumentation']);
+      const instruments = listing.stdout.trim().split(/\r?\n/).filter(Boolean).map(line => {
+        const match = /^instrumentation:(\S+) \(target=(\S+)\)$/.exec(line);
+        if (!match) throw new CommandError('executor_instrumentation_inventory_invalid', 'Android returned an unexpected instrumentation entry.');
+        return { component: match[1], targetPackage: match[2] };
+      });
+      return { ok: true, serial: args.serial, instruments,
+        prerequisite: 'Use the existing application androidTest source set and install its matching test APK. Opening instrumentation restarts the target application; no separate business app is required.' };
+    }
+    if (args.operation === 'open') return this.open({ ...args, adb });
+    const port = this.load(args), descriptor = port.descriptor;
+    const request = { ...args, requestId: randomUUID() };
+    delete request.adb; delete request.serial; delete request.packageName; delete request.feedback;
+    if (args.operation === 'receipt') {
+      const receipt = await port.readRecord(`receipts/${hash(args.actionId)}.json`);
+      return { ok: Boolean(receipt), sessionId: descriptor.sessionId, runtimeEpoch: descriptor.runtimeEpoch, receipt };
+    }
+    if (args.operation === 'observe') return port.request(request);
+    const actionId = args.actionId || args.runtimeActionId || randomUUID();
+    const pending = { kind: this.kind, protocol: descriptor.protocol, operation: args.operation, sessionId: descriptor.sessionId,
+      runtimeEpoch: descriptor.runtimeEpoch, actionId, target: { serial: descriptor.serial, packageName: descriptor.packageName, adb: descriptor.adb },
+      descriptorFile: path.join(this.directory(descriptor.sessionId), 'session.json') };
+    return runDeviceEffect(pending, async () => {
+      if (args.operation === 'close') {
+        const response = await port.request(request);
+        if (!response.ok) return response;
+        while (true) {
+          const closed = await port.readRecord('closed.json');
+          if (closed?.settled === true && await this.finishClose(port)) {
+            await port.disconnect(); this.sessions.delete(descriptor.sessionId); return { ok: true, closed };
+          }
+          await executionSleep(50);
+        }
+      }
+      try { return await port.request({ ...request, actionId }); }
+      catch (error) {
+        if (error.dispatched === false) throw error;
+        const recovered = await withoutExecution(() => runExecution({ timeoutMs: 5000, mutation: false }, async () => {
+          await port.request({ operation: 'cancel', requestId: request.requestId, timeoutMs: 1000 });
+          while (true) {
+            const response = await port.request({ operation: 'receipt', actionId, timeoutMs: 1000 });
+            if (response.receipt?.settled === true) return { ...response.receipt.result, executionReceipt: response.receipt, recovered: true };
+            await executionSleep(50);
+          }
+        })).catch(recoveryError => ({ ok: false, error: 'executor_completion_unknown', message: error.message,
+          recoveryError: recoveryError.code, dispatched: true, ambiguous: true, sessionId: descriptor.sessionId, runtimeEpoch: descriptor.runtimeEpoch, actionId }));
+        return recovered;
+      }
+    }, result => settlement(result, pending));
+  }
+  async open(args) {
+    const inventory = await this.run({ operation: 'status', adb: args.adb, serial: args.serial });
+    const installed = inventory.instruments.find(item => item.component === args.instrumentation);
+    if (!installed) throw new CommandError('executor_not_installed', 'The selected instrumentation component is not installed.', { dispatched: false, ambiguous: false });
+    if (installed.targetPackage !== args.packageName) throw new CommandError('executor_target_mismatch', 'The test APK must target this exact application package.', { dispatched: false, ambiguous: false });
+    if (!args.activity) throw new CommandError('missing_argument', 'The test executor requires the application Activity to launch.', { field: 'activity', dispatched: false, ambiguous: false });
+    const sessionId = randomUUID(), directory = this.directory(sessionId);
+    const descriptor = { protocol, sessionId, serial: args.serial, packageName: args.packageName, targetPackage: installed.targetPackage,
+      adb: args.adb, token: randomBytes(32).toString('hex'), instrumentation: args.instrumentation, testClass: args.testClass };
+    const file = path.join(directory, 'session.json');
+    const port = new AndroidExecutorPort(descriptor);
+    descriptor.bootId = await port.bootId();
+    atomicJson(file, descriptor);
+    await port.connect();
+    const pending = { kind: this.kind, protocol, operation: 'open', sessionId, runtimeEpoch: null,
+      target: { serial: args.serial, packageName: args.packageName, adb: args.adb }, descriptorFile: file };
+    const uia = require('../shared-kernel/uia-runtime-port').createUiaRuntimePort({ adb: args.adb, serial: args.serial, timeoutMs: args.timeoutMs ?? 60000 });
+    return uia.withInstrumentation(file, () => runDeviceEffect(pending, async () => {
+      checkExecution();
+      const command = ['am', 'instrument', '-w', '-r', '-e', 'class', args.testClass, '-e', 'bridgeSessionId', sessionId,
+        '-e', 'bridgeToken', descriptor.token, '-e', 'bridgeLeaseMs', String(args.leaseMs ?? 600000),
+        ...(args.activity ? ['-e', 'bridgeActivity', args.activity] : []), args.instrumentation];
+      const child = spawn(args.adb, ['-s', args.serial, 'shell', command.map(quote).join(' ')], { stdio: ['ignore', 'pipe', 'pipe'] });
+      let output = '', exited = false, spawnError;
+      child.on('error', error => { spawnError = error; });
+      child.stdout.on('data', chunk => { output = (output + chunk).slice(-65536); });
+      child.stderr.on('data', chunk => { output = (output + chunk).slice(-65536); });
+      child.once('close', code => {
+        exited = true; this.children.delete(sessionId);
+        atomicJson(path.join(directory, 'runner-result.json'), { sessionId, code, output: output.replaceAll(descriptor.token, '[REDACTED_SECRET]'), instrumentFinished: /INSTRUMENTATION_CODE: -?\d+/.test(output) });
+      });
+      this.children.set(sessionId, child);
+      if (child.pid) markExecutionDispatched();
+      this.sessions.set(sessionId, port);
+      try {
+      while (true) {
+        checkExecution();
+        if (spawnError) throw Object.assign(spawnError, { dispatched: false, ambiguous: false });
+        if (exited) throw new CommandError('executor_runner_ended', 'Instrumentation ended before the executor was ready.', { dispatched: true, ambiguous: true, details: { sessionId, output: output.replaceAll(descriptor.token, '[REDACTED_SECRET]') } });
+        let status;
+        try { status = await port.request({ operation: 'status', timeoutMs: 1000 }); }
+        catch (error) { if (!['ECONNRESET', 'ECONNREFUSED', 'executor_disconnected', 'executor_transport_timeout'].includes(error.code)) throw error; }
+        if (status?.ok) {
+          if (status.targetPackage !== installed.targetPackage || status.bootId !== descriptor.bootId || status.capabilities?.engine !== 'android-instrumentation')
+            throw new CommandError('executor_engine_mismatch', 'The running test does not expose the requested executor.', { dispatched: true, ambiguous: true });
+          Object.assign(descriptor, { runtimeEpoch: status.runtimeEpoch, pid: status.pid, processStartTicks: status.processStartTicks, openedAtMs: Date.now() });
+          atomicJson(file, descriptor);
+          return { ...status, serial: args.serial, packageName: args.packageName, targetPackage: installed.targetPackage,
+            lifecycle: 'target-application-instrumented-and-restarted', leaseMs: args.leaseMs ?? 600000 };
+        }
+        await executionSleep(100);
+      }
+      } catch (error) {
+        error.dispatched = Boolean(child.pid); error.ambiguous = error.dispatched;
+        throw error;
+      }
+    }, result => settlement(result, pending)));
+  }
+  async close() {
+    // Runtime teardown only disconnects its ADB clients. Device receipts survive;
+    // the executor lease closes the test, and ownership remains unresolved until proof.
+    for (const child of this.children.values()) child.kill('SIGTERM');
+    this.children.clear();
+  }
+}
+
+async function recoverAndroidExecutor(pending, createPort = descriptor => new AndroidExecutorPort(descriptor)) {
+  const descriptor = readJson(pending.descriptorFile);
+  if (!descriptor || descriptor.serial !== pending.target?.serial || descriptor.sessionId !== pending.sessionId)
+    return { settled: false, error: 'executor_descriptor_mismatch' };
+  const port = createPort(descriptor);
+  if (await port.bootChanged()) return { kind: pending.kind, sessionId: pending.sessionId,
+    runtimeEpoch: pending.runtimeEpoch, actionId: pending.actionId, settled: true, dispatched: null, state: 'device-rebooted-outcome-unknown' };
+  if (pending.operation === 'open') {
+    const session = await port.readRecord('session.json');
+    if (session) {
+      Object.assign(descriptor, { runtimeEpoch: session.runtimeEpoch, pid: session.pid, processStartTicks: session.processStartTicks });
+      if (pending.kind === 'flutter-test-executor') descriptor.port = session.port;
+      atomicJson(pending.descriptorFile, descriptor);
+      return settlement({ ...session, ok: true }, pending);
+    }
+    const runner = readJson(path.join(path.dirname(pending.descriptorFile), 'runner-result.json'));
+    if (runner?.sessionId === pending.sessionId && runner.instrumentFinished) return { kind: pending.kind, sessionId: pending.sessionId, settled: true, dispatched: true, state: 'runner-finished' };
+  }
+  if (pending.operation === 'act') {
+    const receipt = await port.readRecord(`receipts/${hash(pending.actionId)}.json`);
+    if (receipt?.settled) return settlement({ executionReceipt: receipt }, pending);
+  }
+  if (descriptor.pid && await port.processEnded()) return { kind: pending.kind, sessionId: pending.sessionId,
+    runtimeEpoch: pending.runtimeEpoch, actionId: pending.actionId, settled: true, dispatched: null, state: 'executor-process-ended-outcome-unknown' };
+  const closed = await port.readRecord('closed.json');
+  return closed?.settled === true && await port.processEnded() ? { kind: pending.kind, sessionId: pending.sessionId, runtimeEpoch: closed.runtimeEpoch,
+    actionId: pending.actionId, settled: true, dispatched: null, state: 'session-closed-outcome-unknown', closed }
+    : { settled: false, error: 'executor_original_completion_unavailable', actionId: pending.actionId };
+}
+
+module.exports = { AndroidExecutorHost, recoverAndroidExecutor, settlement };

package/bin/executors/android-port.js

@@ -0,0 +1,114 @@
+'use strict';
+
+const net = require('node:net');
+const { randomUUID } = require('node:crypto');
+const { CommandError } = require('../command-errors');
+const { execFileBounded } = require('../shared-kernel/execution-io');
+const { currentExecution, checkExecution, markExecutionDispatched, executionFailure } = require('../shared-kernel/execution-scope');
+const protocol = 'aab.android-test-executor/v1';
+const quote = value => `'${String(value).replaceAll("'", "'\\''")}'`;
+
+class AndroidExecutorPort {
+  constructor(descriptor, { run = execFileBounded, protocolVersion = protocol } = {}) { this.descriptor = descriptor; this.port = null; this.run = run; this.protocolVersion = protocolVersion; }
+  forwardEndpoint() { return `localabstract:aab-test-${this.descriptor.sessionId}`; }
+  recordDirectory() { return `no_backup/ai-app-bridge-executors/${this.descriptor.sessionId}`; }
+  invoke(args, timeoutMs = 10000) {
+    return this.run(this.descriptor.adb, ['-s', this.descriptor.serial, ...args], { timeoutMs, maxBuffer: 4 * 1024 * 1024 });
+  }
+  async connect() {
+    const descriptor = this.descriptor;
+    const remote = this.forwardEndpoint();
+    const inventory = async () => (await this.invoke(['forward', '--list'])).stdout.trim().split(/\r?\n/).filter(Boolean).map(line => {
+      const [serial, local, remote] = line.trim().split(/\s+/); return { serial, local, remote };
+    });
+    const existing = (await inventory()).filter(item => item.serial === descriptor.serial && item.remote === remote);
+    if (existing.length > 1) throw new CommandError('executor_forward_ambiguous', 'Multiple forwards target this exact executor.');
+    const local = existing.length === 1 ? existing[0].local : `tcp:${(await this.invoke(['forward', 'tcp:0', remote])).stdout.trim()}`;
+    if (!/^tcp:[1-9][0-9]{0,4}$/.test(local) || Number(local.slice(4)) > 65535) throw new CommandError('executor_forward_invalid', 'ADB returned an invalid executor forward.');
+    const confirmed = (await inventory()).filter(item => item.local === local);
+    if (confirmed.length !== 1 || confirmed[0].serial !== descriptor.serial || confirmed[0].remote !== remote)
+      throw new CommandError('executor_forward_mismatch', 'Executor forward belongs to another target.');
+    this.port = Number(local.slice(4));
+  }
+  async request(args) {
+    if (this.port === null) await this.connect();
+    checkExecution();
+    const scope = currentExecution();
+    const payload = { protocol: this.protocolVersion, token: this.descriptor.token, sessionId: this.descriptor.sessionId,
+      ...(this.descriptor.runtimeEpoch ? { runtimeEpoch: this.descriptor.runtimeEpoch } : {}), requestId: randomUUID(), ...args };
+    const body = JSON.stringify(payload) + '\n';
+    if (Buffer.byteLength(body) > 1024 * 1024) throw new CommandError('executor_request_limit', 'Executor request exceeds 1 MiB.', { dispatched: false, ambiguous: false });
+    return new Promise((resolve, reject) => {
+      let data = '', bytes = 0, failure, result, timer, dispatched = false;
+      const socket = net.createConnection({ host: '127.0.0.1', port: this.port });
+      const stop = error => { failure ||= error; socket.destroy(); };
+      const abort = () => stop(executionFailure(scope));
+      timer = setTimeout(() => stop(new CommandError('executor_transport_timeout', 'Executor reply did not complete within the request deadline.')), args.timeoutMs ?? 30000);
+      scope?.signal.addEventListener('abort', abort, { once: true });
+      socket.setEncoding('utf8');
+      socket.on('connect', () => {
+        try { checkExecution(); } catch (error) { stop(error); return; }
+        if (['act', 'close'].includes(args.operation)) { dispatched = true; markExecutionDispatched(); }
+        socket.write(body);
+      });
+      socket.on('data', chunk => {
+        bytes += Buffer.byteLength(chunk);
+        if (bytes > 4 * 1024 * 1024) { stop(new CommandError('executor_response_limit', 'Executor reply exceeds 4 MiB.')); return; }
+        data += chunk;
+        if (data.endsWith('\n')) {
+          try {
+            result = JSON.parse(data);
+            if (result.protocol !== this.protocolVersion || result.sessionId !== payload.sessionId || (payload.runtimeEpoch && result.runtimeEpoch !== payload.runtimeEpoch))
+              throw new CommandError('executor_session_mismatch', 'Executor reply identity does not match the original request.');
+            socket.destroy();
+          } catch (error) { stop(error); }
+        }
+      });
+      socket.on('error', error => { failure ||= error; });
+      socket.on('close', () => {
+        clearTimeout(timer); scope?.signal.removeEventListener('abort', abort);
+        if (!result) failure ||= new CommandError('executor_disconnected', 'Executor disconnected without a complete reply.');
+        if (failure) { failure.dispatched = dispatched; failure.ambiguous = dispatched; reject(failure); }
+        else resolve(result);
+      });
+      if (scope?.signal.aborted) abort();
+    });
+  }
+  async readRecord(name) {
+    if (!/^(session|starting|failed|closed)\.json$/.test(name) && !/^receipts\/[a-f0-9]{64}\.json$/.test(name)) throw new Error('Invalid executor record');
+    const file = `${this.recordDirectory()}/${name}`;
+    const script = `if [ -f ${quote(file)} ]; then cat ${quote(file)}; else printf '%s' null; fi`;
+    const result = await this.invoke(['shell', 'run-as', this.descriptor.targetPackage, 'sh', '-c', quote(script)]);
+    const record = JSON.parse(result.stdout.trim());
+    if (record && (record.protocol !== this.protocolVersion || record.sessionId !== this.descriptor.sessionId
+      || record.targetPackage !== this.descriptor.targetPackage || record.bootId !== this.descriptor.bootId
+      || (this.descriptor.runtimeEpoch && record.runtimeEpoch !== this.descriptor.runtimeEpoch))) throw new CommandError('executor_receipt_mismatch', 'Retained device record belongs to a different session.');
+    return record;
+  }
+  async disconnect() {
+    if (this.port !== null) { await this.invoke(['forward', '--remove', `tcp:${this.port}`]); this.port = null; }
+  }
+  async processEnded() {
+    if (await this.bootChanged()) return true;
+    if (!Number.isInteger(this.descriptor.pid) || this.descriptor.pid < 1) throw new CommandError('executor_process_identity_missing', 'The executor did not publish its process identity.');
+    if (!/^[0-9]+$/.test(this.descriptor.processStartTicks)) throw new CommandError('executor_process_identity_missing', 'The executor did not publish its process start identity.');
+    const script = `if [ -d /proc/${this.descriptor.pid} ]; then cat /proc/${this.descriptor.pid}/stat; else printf '%s' gone; fi`;
+    const result = (await this.invoke(['shell', 'run-as', this.descriptor.targetPackage, 'sh', '-c', quote(script)])).stdout.trim();
+    if (result === 'gone') return true;
+    const start = result.slice(result.lastIndexOf(') ') + 2).split(/\s+/)[19];
+    if (!/^[0-9]+$/.test(start)) throw new CommandError('executor_process_probe_invalid', 'The device did not confirm the executor process state.');
+    return start !== this.descriptor.processStartTicks;
+  }
+  async bootId() {
+    const id = (await this.invoke(['shell', 'cat', '/proc/sys/kernel/random/boot_id'])).stdout.trim();
+    if (!/^[a-f0-9-]{36}$/.test(id)) throw new CommandError('executor_boot_identity_invalid', 'The device did not publish a valid boot identity.');
+    return id;
+  }
+  async bootChanged() {
+    if (typeof this.descriptor.bootId !== 'string' || !/^[a-f0-9-]{36}$/.test(this.descriptor.bootId))
+      throw new CommandError('executor_boot_identity_missing', 'The original executor boot identity is unavailable.');
+    return await this.bootId() !== this.descriptor.bootId;
+  }
+}
+
+module.exports = { AndroidExecutorPort, protocol, quote };

package/bin/executors/automation-owner.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const { defaultDirectory } = require('../shared-kernel/device-ownership-store');
+const { CommandError } = require('../command-errors');
+const { atomicJson, readJson } = require('./managed-runtime');
+const { AndroidExecutorPort } = require('./android-port');
+
+const fileFor = serial => path.join(defaultDirectory(), 'automation-sessions', createHash('sha256').update(serial).digest('hex') + '.json');
+function owner(serial) { return readJson(fileFor(serial)); }
+function claim(serial, descriptorFile) {
+  const descriptor = readJson(descriptorFile);
+  if (!descriptor || descriptor.serial !== serial) throw new CommandError('executor_descriptor_mismatch', 'Automation claim requires the exact device descriptor.');
+  const claim = { serial, sessionId: descriptor.sessionId, descriptorFile };
+  atomicJson(fileFor(serial), claim);
+  return claim;
+}
+function release(serial, sessionId) {
+  const current = owner(serial);
+  if (!current) return;
+  if (current.sessionId !== sessionId) throw new CommandError('executor_automation_owner_changed', 'A different test session owns UiAutomation.');
+  fs.unlinkSync(fileFor(serial));
+  const fd = fs.openSync(path.dirname(fileFor(serial)), 'r');
+  try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+}
+async function assertAvailable(serial) {
+  const current = owner(serial);
+  if (!current) return;
+  const descriptor = readJson(current.descriptorFile);
+  if (!descriptor || descriptor.serial !== serial || descriptor.sessionId !== current.sessionId)
+    throw new CommandError('executor_automation_owner_invalid', 'The recorded UiAutomation owner cannot be resolved.');
+  const port = new AndroidExecutorPort(descriptor);
+  const runner = readJson(path.join(path.dirname(current.descriptorFile), 'runner-result.json'));
+  if ((runner?.sessionId === current.sessionId && runner.instrumentFinished)
+    || await port.bootChanged() || (descriptor.pid && await port.processEnded())) { release(serial, current.sessionId); return; }
+  throw new CommandError('uia_owned_by_test_executor', 'The test session owns UiAutomation. Use android-executor with engine uiautomator, or close that session first.',
+    { dispatched: false, ambiguous: false, details: { serial, sessionId: current.sessionId, runtimeEpoch: descriptor.runtimeEpoch, packageName: descriptor.packageName } });
+}
+
+module.exports = { owner, claim, release, assertAvailable };