@mobileaidev/ai-app-bridge 0.2.15 → 0.3.0-rc.2

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

@@ -0,0 +1,214 @@
+'use strict';
+
+const { createHash, randomUUID } = require('node:crypto');
+const { isDeepStrictEqual } = require('node:util');
+const { CommandError } = require('../command-errors');
+const { parseXmlAttributes } = require('./xml-attributes');
+
+const schema = 'aab.uia.execution.v1';
+const runtimeSchema = 'aab.uia.runtime.v1';
+const snapshotSchema = 'aab.uia.snapshot.v1';
+const rootDirectory = '/data/local/tmp/ai-app-bridge-uia/v1';
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const hash = /^[0-9a-f]{64}$/;
+const targetRefSchema = { type: 'object', additionalProperties: false,
+  required: ['schemaVersion', 'bootId', 'runtimeEpoch', 'snapshotId', 'nodeRef'],
+  properties: { schemaVersion: { const: 'aab.uia.target/v1' },
+    ...Object.fromEntries(['bootId', 'runtimeEpoch', 'snapshotId', 'nodeRef'].map(key => [key, { type: 'string', pattern: uuid.source }])) } };
+const isUuid = value => typeof value === 'string' && value.length === 36 && uuid.test(value);
+const isHash = value => typeof value === 'string' && value.length === 64 && hash.test(value);
+const isActionId = value => typeof value === 'string' && value.length > 0 && value.length <= 1024 && value.isWellFormed();
+const digest = value => createHash('sha256').update(value).digest('hex');
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const exactKeys = (value, keys) => record(value) && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+const fail = (code, message) => { throw new CommandError(code, message, { dispatched: false, ambiguous: false }); };
+
+function validRoot(root) {
+  const prefix = '/data/local/tmp/ai-app-bridge-uia-test-';
+  return root === rootDirectory || typeof root === 'string' && root.startsWith(prefix) && root.length > prefix.length && !/[^a-z0-9-]/.test(root.slice(prefix.length));
+}
+
+function validRequest(request) {
+  if (!exactKeys(request, ['schemaVersion', 'bootId', 'runtimeEpoch', 'actionId', 'timeoutMs', 'target', 'clickPolicy'])
+    || request.schemaVersion !== schema || ![request.bootId, request.runtimeEpoch].every(isUuid) || !isActionId(request.actionId)
+    || !Number.isSafeInteger(request.timeoutMs) || request.timeoutMs < 1 || request.timeoutMs > 60000
+    || !['exact_node', 'nearest_clickable_ancestor'].includes(request.clickPolicy)
+    || !exactKeys(request.target, ['snapshotId', 'ref', 'selector']) || !isUuid(request.target.snapshotId) || !isUuid(request.target.ref)) return false;
+  const selector = request.target.selector;
+  return exactKeys(selector, ['kind', 'value', 'exact', 'packageName'])
+    && ['text', 'contentDescription', 'resourceName', 'nodeRef'].includes(selector.kind)
+    && typeof selector.value === 'string' && selector.value.length > 0 && selector.value.length <= 4096
+    && typeof selector.exact === 'boolean' && (selector.packageName === null || typeof selector.packageName === 'string' && selector.packageName.length > 0)
+    && (selector.kind !== 'nodeRef' || selector.exact === true && selector.value === request.target.ref && typeof selector.packageName === 'string');
+}
+
+function snapshotIdentity(xml) {
+  const opening = typeof xml === 'string' && xml.match(/<hierarchy\b[^>]*>/);
+  const metadata = opening && parseXmlAttributes(opening[0]);
+  if (!metadata || !metadata['aab-schema']) return null;
+  if (metadata['aab-schema'] !== snapshotSchema
+    || !['aab-boot-id', 'aab-runtime-epoch', 'aab-snapshot-id'].every(key => isUuid(metadata[key])))
+    fail('uia_bound_observation_required', 'Observe UIA again using the node runtime before selecting an action.');
+  return { bootId: metadata['aab-boot-id'], runtimeEpoch: metadata['aab-runtime-epoch'], snapshotId: metadata['aab-snapshot-id'] };
+}
+
+function nodeTargetRef(snapshot, node) {
+  if (!snapshot) return undefined;
+  if (!isUuid(node?.['aab-ref'])) fail('uia_bound_observation_required', 'The observed UIA node has no valid runtime reference.');
+  return { schemaVersion: 'aab.uia.target/v1', ...snapshot, nodeRef: node['aab-ref'] };
+}
+
+function bindingFromTargetRef(ref, packageName) {
+  if (!exactKeys(ref, targetRefSchema.required) || ref.schemaVersion !== 'aab.uia.target/v1'
+    || !['bootId', 'runtimeEpoch', 'snapshotId', 'nodeRef'].every(key => isUuid(ref[key])))
+    fail('uia_bound_observation_required', 'Use the complete targetRef from a fresh UIA observation.');
+  return { bootId: ref.bootId, runtimeEpoch: ref.runtimeEpoch,
+    target: { snapshotId: ref.snapshotId, ref: ref.nodeRef,
+      selector: { kind: 'nodeRef', value: ref.nodeRef, exact: true, packageName } } };
+}
+
+function observedTarget(xml, node, selector, packageName, { exact = true } = {}) {
+  const ref = nodeTargetRef(snapshotIdentity(xml), node);
+  if (!ref) fail('uia_bound_observation_required', 'Observe UIA again using the node runtime before selecting an action.');
+  const keys = Object.keys(selector || {});
+  if (keys.length !== 1) fail('invalid_uia_selector', 'A UIA action requires exactly one selector field.');
+  return { bootId: ref.bootId, runtimeEpoch: ref.runtimeEpoch,
+    target: { snapshotId: ref.snapshotId, ref: ref.nodeRef,
+      selector: { kind: keys[0], value: selector[keys[0]], exact, packageName } } };
+}
+
+function actionRequest(binding, { timeoutMs, actionId = randomUUID(), clickPolicy = 'nearest_clickable_ancestor' } = {}) {
+  if (!record(binding)) fail('invalid_uia_execution_request', 'A bound UIA observation is required.');
+  const request = { schemaVersion: schema, bootId: binding.bootId, runtimeEpoch: binding.runtimeEpoch,
+    actionId, timeoutMs, target: binding.target, clickPolicy };
+  if (!validRequest(request)) fail('invalid_uia_execution_request', 'UIA requires a valid observed node, original action identity, selector and millisecond deadline.');
+  const requestJson = JSON.stringify(request);
+  if (Buffer.byteLength(requestJson) > 32768) fail('uia_request_capacity_exhausted', 'The UIA action request exceeds 32 KiB.');
+  return { request, requestJson, requestSha256: digest(requestJson) };
+}
+
+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
+    && value.socketName === `aab-uia-${value.runtimeEpoch}` && isHash(value.token)
+    && value.sessionPath === `${root}/sessions/${value.runtimeEpoch}` && typeof value.running === 'boolean';
+}
+
+function validIdentity(identity) {
+  if (!record(identity) || identity.kind !== 'uia-node' || identity.schemaVersion !== schema
+    || ![identity.bootId, identity.runtimeEpoch].every(isUuid) || !isActionId(identity.actionId)
+    || typeof identity.requestJson !== 'string' || !isHash(identity.requestSha256)
+    || digest(identity.requestJson) !== identity.requestSha256 || Buffer.byteLength(identity.requestJson) > 32768
+    || !record(identity.target) || typeof identity.target.serial !== 'string' || !identity.target.serial
+    || typeof identity.target.adb !== 'string' || !identity.target.adb || !validRoot(identity.target.root)
+    || identity.target.sessionPath !== `${identity.target.root}/sessions/${identity.runtimeEpoch}` || !isHash(identity.target.dexSha256)) return false;
+  let request;
+  try { request = JSON.parse(identity.requestJson); } catch { return false; }
+  return validRequest(request) && ['bootId', 'runtimeEpoch', 'actionId'].every(key => request[key] === identity[key]);
+}
+
+function originalReceipt(response, identity) {
+  if (!validIdentity(identity) || !record(response) || response.schemaVersion !== schema || response.settled !== true
+    || !['bootId', 'runtimeEpoch', 'actionId', 'requestSha256'].every(key => response[key] === identity[key])
+    || typeof response.receiptJson !== 'string' || !isHash(response.receiptSha256)
+    || Buffer.byteLength(response.receiptJson) > 65536 || digest(response.receiptJson) !== response.receiptSha256) return null;
+  let receipt;
+  try { receipt = JSON.parse(response.receiptJson); } catch { return null; }
+  if (!record(receipt) || receipt.schemaVersion !== schema || receipt.settled !== true || receipt.ambiguous !== false
+    || !['bootId', 'runtimeEpoch', 'actionId', 'requestSha256'].every(key => receipt[key] === identity[key])
+    || typeof receipt.ok !== 'boolean' || typeof receipt.dispatched !== 'boolean'
+    || receipt.ok === false && (typeof receipt.error !== 'string' || !receipt.error)
+    || receipt.ok === true && Object.hasOwn(receipt, 'error')) return null;
+  const request = JSON.parse(identity.requestJson);
+  if (receipt.completion === 'recovered_before_admission') return validRecoveryReceipt(receipt, identity, request) ? receipt : null;
+  if (!Number.isSafeInteger(receipt.completedAtElapsedMs) || receipt.completedAtElapsedMs < 0
+    || !['original_callback', 'admission_rejected', 'before_admission'].includes(receipt.completion)
+    || Object.hasOwn(receipt, 'recovery')) return null;
+  if (Object.hasOwn(receipt, 'binding') && !matchingBinding(receipt.binding, request)) return null;
+  if (receipt.completion === 'original_callback') {
+    if (receipt.dispatched !== true || !Number.isSafeInteger(receipt.callback?.interactionId) || receipt.callback.interactionId < 1
+      || receipt.callback.handled !== receipt.ok || !record(receipt.binding)) return null;
+  } else if (receipt.dispatched !== false || receipt.ok !== false || Object.hasOwn(receipt, 'callback')
+    || receipt.completion === 'admission_rejected' && !record(receipt.binding)) return null;
+  return receipt;
+}
+
+function validRecoveryReceipt(receipt, identity, request) {
+  if (!exactKeys(receipt, ['schemaVersion', 'bootId', 'runtimeEpoch', 'actionId', 'requestSha256',
+    'settled', 'ok', 'dispatched', 'ambiguous', 'completion', 'error', 'recovery'])
+    || receipt.ok !== false || receipt.dispatched !== false || receipt.error !== 'uia_owner_exited_before_admission') return false;
+  const value = receipt.recovery;
+  return exactKeys(value, ['authority', 'bootId', 'observedAtElapsedMs', 'priorPhase', 'priorRecordSha256',
+    'preparedAtElapsedMs', 'originalDexSha256', 'recoveryDexSha256'])
+    && value.authority === 'exclusive_runtime_root_lock' && isUuid(value.bootId)
+    && ['prepared', 'queued'].includes(value.priorPhase) && isHash(value.priorRecordSha256) && isHash(value.recoveryDexSha256)
+    && value.originalDexSha256 === identity.target.dexSha256
+    && Number.isSafeInteger(value.preparedAtElapsedMs) && value.preparedAtElapsedMs >= 0
+    && Number.isSafeInteger(value.preparedAtElapsedMs + request.timeoutMs)
+    && Number.isSafeInteger(value.observedAtElapsedMs) && value.observedAtElapsedMs >= 0
+    && (value.bootId !== identity.bootId || value.observedAtElapsedMs >= value.preparedAtElapsedMs);
+}
+
+function matchingBinding(binding, request) {
+  if (!record(binding) || binding.snapshotId !== request.target.snapshotId || binding.ref !== request.target.ref
+    || !isDeepStrictEqual(binding.selector, request.target.selector) || binding.clickPolicy !== request.clickPolicy
+    || binding.identityStrength !== 'same_connection_node_and_reobserved_attributes'
+    || !record(binding.window) || !Number.isSafeInteger(binding.window.id) || binding.window.id < 0
+    || binding.window.displayId !== 0 || binding.window.focused !== true) return false;
+  const { target, actionTarget } = binding;
+  for (const node of [target, actionTarget]) {
+    if (!record(node) || node.windowId !== binding.window.id || typeof node.sourceId !== 'string'
+      || !/^-?[0-9]{1,20}$/.test(node.sourceId) || node.enabled !== true || node.visible !== true) return false;
+  }
+  const selector = request.target.selector;
+  const value = selector.kind === 'nodeRef' ? binding.ref : target[selector.kind];
+  if (typeof value !== 'string' || !(selector.exact ? value === selector.value : value.includes(selector.value))
+    || selector.packageName !== null && target.packageName !== selector.packageName || actionTarget.clickable !== true) return false;
+  return !(request.clickPolicy === 'exact_node' || target.clickable === true) || isDeepStrictEqual(target, actionTarget);
+}
+
+function recordResponse(value, identity) {
+  if (!record(value) || value.schemaVersion !== 'aab.uia.record.v2' || value.phase !== 'terminal'
+    || value.requestJson !== identity.requestJson || !['bootId', 'runtimeEpoch', 'actionId', 'requestSha256'].every(key => value[key] === identity[key])) return null;
+  const response = { schemaVersion: schema, bootId: value.bootId, runtimeEpoch: value.runtimeEpoch, actionId: value.actionId,
+    requestSha256: value.requestSha256, settled: true, phase: 'terminal', receiptJson: value.receiptJson, receiptSha256: value.receiptSha256 };
+  const receipt = originalReceipt(response, identity);
+  if (!receipt) return null;
+  if (receipt.completion === 'recovered_before_admission'
+    && (value.preparedAtElapsedMs !== receipt.recovery.preparedAtElapsedMs
+      || value.deadlineElapsedMs !== value.preparedAtElapsedMs + JSON.parse(identity.requestJson).timeoutMs
+      || value.interactionId !== 0 || typeof value.acknowledged !== 'boolean')) return null;
+  return response;
+}
+
+function settlementProof(response, identity) {
+  const receipt = originalReceipt(response, identity);
+  return receipt ? { kind: 'uia-node', schemaVersion: schema, settled: true, bootId: identity.bootId,
+    runtimeEpoch: identity.runtimeEpoch, actionId: identity.actionId, requestSha256: identity.requestSha256,
+    dispatched: receipt.dispatched, ambiguous: false, error: receipt.error ?? null,
+    responseSha256: response.receiptSha256, receiptJson: response.receiptJson } : null;
+}
+
+function acknowledgementIdentity(identity, response) {
+  if (!originalReceipt(response, identity)) fail('uia_completion_identity_mismatch', 'Only a validated original UIA receipt may be acknowledged.');
+  return { bootId: identity.bootId, runtimeEpoch: identity.runtimeEpoch, actionSha256: digest(identity.actionId),
+    requestSha256: identity.requestSha256, receiptSha256: response.receiptSha256, originalDexSha256: identity.target.dexSha256 };
+}
+
+function recoveryIdentity(identity) {
+  if (!validIdentity(identity)) fail('invalid_uia_execution_identity', 'Recovery requires the complete original UIA request and target identity.');
+  return { bootId: identity.bootId, runtimeEpoch: identity.runtimeEpoch, actionSha256: digest(identity.actionId),
+    requestSha256: identity.requestSha256, originalDexSha256: identity.target.dexSha256 };
+}
+
+function acknowledgementMatches(response, identity) {
+  return exactKeys(response, ['ok', 'schemaVersion', 'identity', 'disposition']) && response.ok === true
+    && response.schemaVersion === 'aab.uia.ack.v1' && isDeepStrictEqual(response.identity, identity)
+    && ['acknowledged', 'not_retained'].includes(response.disposition);
+}
+
+module.exports = { schema, runtimeSchema, snapshotSchema, rootDirectory, digest, validRoot, validRequest,
+  targetRefSchema, snapshotIdentity, nodeTargetRef, bindingFromTargetRef,
+  actionRequest, observedTarget, validDescriptor, validIdentity, originalReceipt, recordResponse, settlementProof,
+  acknowledgementIdentity, acknowledgementMatches, recoveryIdentity };

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

@@ -0,0 +1,377 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { randomUUID } = require('node:crypto');
+const { CommandError } = require('../command-errors');
+const { execFileBounded, httpRequestBounded } = require('./execution-io');
+const { createOwnershipStore, defaultDirectory } = require('./device-ownership-store');
+const { checkExecution, runExecution, executionSleep } = require('./execution-scope');
+const protocol = require('./uia-protocol');
+
+const mainClass = 'io.github.mobileaidev.aiappbridge.uia.UiaRuntime';
+const quote = value => `'${value.replaceAll("'", "'\\''")}'`;
+
+function createUiaRuntimePort({ adb, serial, timeoutMs = 10000, root = protocol.rootDirectory,
+  bundleDirectory = path.resolve(__dirname, '../../runtime/uia'), run = execFileBounded, http = httpRequestBounded,
+  connectionLocks = createOwnershipStore(path.join(defaultDirectory(), 'uia-connections')) } = {}) {
+  if (typeof serial !== 'string' || !serial || typeof adb !== 'string' || !adb || !protocol.validRoot(root)) {
+    throw new CommandError('invalid_uia_runtime_target', 'UIA runtime requires an explicit Android serial, ADB executable and valid root.', { dispatched: false, ambiguous: false });
+  }
+  const invoke = (args, budgetMs = timeoutMs) => run(adb, ['-s', serial, ...args], {
+    timeoutMs: budgetMs, mutation: false, encoding: 'utf8', maxBuffer: 2 * 1024 * 1024, windowsHide: true,
+  });
+  const shell = script => invoke(['shell', 'sh', '-c', quote(script)]).then(result => result.stdout.trim());
+  const failure = (code, message, details) => new CommandError(code, message, { details });
+
+  async function readJson(file) {
+    const raw = await shell(`if [ -f ${quote(file)} ]; then cat ${quote(file)}; else printf '%s' null; fi`);
+    try { return JSON.parse(raw); }
+    catch { throw failure('uia_runtime_record_invalid', 'The phone did not return a valid UIA JSON record.', { file }); }
+  }
+
+  function bundle() {
+    let manifest, bytes;
+    try {
+      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
+      || 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.');
+    }
+    return { manifest, file: path.join(bundleDirectory, manifest.artifact) };
+  }
+
+  function descriptor(value) {
+    if (!protocol.validDescriptor(value, root)) throw failure('uia_runtime_descriptor_invalid', 'The UIA runtime descriptor has invalid identity or transport fields.');
+    return value;
+  }
+
+  async function withConnectionLock(action) {
+    // Reuse the OS-managed lock implementation, with a separate connection
+    // namespace. Discovery, rotation and forward allocation share this lock.
+    const started = Date.now();
+    let held;
+    while (!(held = connectionLocks.lock(`${serial}:${root}`))) {
+      checkExecution();
+      if (Date.now() - started >= timeoutMs) throw failure('uia_connection_busy', 'Another Host is configuring this UIA connection.');
+      await executionSleep(25);
+    }
+    try { return await action(); } finally { held.close(); }
+  }
+
+  async function forwards() {
+    const result = await invoke(['forward', '--list']);
+    return result.stdout.trim().split(/\r?\n/).filter(Boolean).map(line => {
+      const fields = line.trim().split(/\s+/);
+      if (fields.length !== 3) throw failure('uia_forward_list_invalid', 'ADB returned an invalid forward inventory.');
+      return { serial: fields[0], local: fields[1], remote: fields[2] };
+    });
+  }
+
+  async function connect(peer) {
+    const target = `localabstract:${peer.socketName}`;
+    const existing = (await forwards()).filter(item => item.serial === serial && item.remote === target);
+    if (existing.length > 1) throw failure('uia_forward_ambiguous', 'Multiple ADB forwards target this UIA runtime. Inspect the forward inventory before proceeding.');
+    let local;
+    if (existing.length === 1) local = existing[0].local;
+    else {
+      const assigned = (await invoke(['forward', 'tcp:0', target])).stdout.trim();
+      local = `tcp:${assigned}`;
+      const matches = (await forwards()).filter(item => item.local === local);
+      if (matches.length !== 1 || matches[0].serial !== serial || matches[0].remote !== target) {
+        throw failure('uia_forward_identity_mismatch', 'The allocated ADB forward does not target this exact phone and runtime.');
+      }
+    }
+    if (!/^tcp:[1-9][0-9]{0,4}$/.test(local) || Number(local.slice(4)) > 65535) throw failure('uia_forward_invalid', 'UIA requires an assigned TCP forward port.');
+    return { peer, port: Number(local.slice(4)) };
+  }
+
+  async function post(connection, payload) {
+    let raw;
+    try {
+      raw = await runExecution({ mutation: payload.op === 'start', timeoutMs }, () => http(`http://127.0.0.1:${connection.port}/v1`, {
+        method: 'POST', payload, headers: { Authorization: `Bearer ${connection.peer.token}` }, timeoutMs, maxBytes: 1048576,
+      }));
+    } catch (error) {
+      if (error.statusCode !== undefined) {
+        let response;
+        try { response = JSON.parse(error.responseBody); } catch { throw failure('uia_http_response_invalid', 'The UIA HTTP error did not contain valid JSON.'); }
+        if (response?.ok === false && typeof response.error === 'string' && response.error) {
+          throw failure(response.error, typeof response.message === 'string' ? response.message : 'The UIA runtime rejected this protocol request.');
+        }
+      }
+      throw error;
+    }
+    try { return JSON.parse(raw); }
+    catch { throw failure('uia_http_response_invalid', 'The UIA runtime did not return valid JSON.'); }
+  }
+
+  async function statusOf(connection) {
+    let result;
+    try { result = await post(connection, { op: 'status' }); }
+    catch (error) {
+      if (['ECONNREFUSED', 'ECONNRESET', 'EPIPE'].includes(error.code))
+        throw failure('uia_runtime_unreachable', 'The original UIA runtime is unreachable. Use uia-runtime --operation start with this serial for an explicit phone process-lock check; unresolved actions remain retained.',
+          { bootId: connection.peer.bootId, runtimeEpoch: connection.peer.runtimeEpoch, transportError: error.code });
+      throw error;
+    }
+    const peer = connection.peer;
+    if (result?.ok !== true || result.schemaVersion !== protocol.schema || result.bootId !== peer.bootId
+      || result.runtimeEpoch !== peer.runtimeEpoch || result.dexSha256 !== peer.dexSha256
+      || !Number.isSafeInteger(result.capacity) || result.capacity < 1
+      || !Number.isSafeInteger(result.count) || result.count < 0 || result.count > result.capacity
+      || !Number.isSafeInteger(result.pending) || result.pending < 0 || result.pending > result.count
+      || !Number.isSafeInteger(result.acknowledged) || result.acknowledged < 0 || result.acknowledged > result.count - result.pending
+      || typeof result.closing !== 'boolean') {
+      throw failure('uia_runtime_identity_mismatch', 'The connected runtime did not confirm the expected boot, epoch and artifact.');
+    }
+    return result;
+  }
+
+  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 });
+    const destination = `${root}/runtime-${asset.manifest.sha256}.jar`;
+    await shell(`umask 077\nmkdir -p ${quote(root)} && chmod 700 ${quote(root)}`);
+    const existingHash = await shell(`if [ -f ${quote(destination)} ]; then sha256sum ${quote(destination)}; else printf '%s' null; fi`);
+    if (existingHash !== 'null') {
+      if (existingHash.split(/\s+/)[0] !== asset.manifest.sha256)
+        throw failure('uia_runtime_artifact_mismatch', 'An existing content-addressed UIA runtime artifact has different bytes.');
+      return destination;
+    }
+    const temporary = `${root}/runtime-${asset.manifest.sha256}.${randomUUID()}.tmp`;
+    await invoke(['push', asset.file, temporary]);
+    const installedHash = (await shell(`sha256sum ${quote(temporary)}`)).split(/\s+/)[0];
+    if (installedHash !== asset.manifest.sha256) throw failure('uia_runtime_artifact_mismatch', 'The phone runtime artifact hash differs from the installed CLI bundle.');
+    // Never overwrite an executable that an existing runtime may still map.
+    await shell(`mv -n ${quote(temporary)} ${quote(destination)}`);
+    const publishedHash = (await shell(`sha256sum ${quote(destination)}`)).split(/\s+/)[0];
+    if (publishedHash !== asset.manifest.sha256) throw failure('uia_runtime_artifact_mismatch', 'The published UIA runtime artifact has different bytes.');
+    await shell(`rm -f ${quote(temporary)}`);
+    return destination;
+  }
+
+  async function startRuntime(previous, asset, destination) {
+    destination ??= await installAsset(asset);
+    await shell(`CLASSPATH=${quote(destination)} setsid nohup app_process /system/bin ${mainClass} ${quote(root)} ${asset.manifest.sha256} >${quote(root + '/startup.log')} 2>&1 </dev/null &`);
+    const deadline = Date.now() + Math.min(timeoutMs, 7000);
+    while (Date.now() < deadline) {
+      checkExecution();
+      const current = await readJson(`${root}/runtime.json`);
+      if (current !== null && current.runtimeEpoch !== previous?.runtimeEpoch) {
+        const peer = descriptor(current);
+        if (!peer.running || peer.dexSha256 !== asset.manifest.sha256) throw failure('uia_runtime_identity_mismatch', 'The newly discovered runtime does not match this bundle.');
+        if (previous) await removeForwards(previous);
+        return peer;
+      }
+      await executionSleep(100);
+    }
+    const log = await shell(`tail -c 4096 ${quote(root + '/startup.log')}`);
+    let rejection;
+    try { rejection = JSON.parse(log.trim().split(/\r?\n/).at(-1)); } catch { /* Non-JSON VM startup diagnostics remain below. */ }
+    if (rejection?.ok === false && typeof rejection.error === 'string' && rejection.error.startsWith('uia_'))
+      throw failure(rejection.error, 'The phone runtime refused to start. Original session records were retained.', { startupLog: log });
+    throw failure('uia_runtime_start_failed', 'The phone did not publish a ready UIA runtime.', { startupLog: log });
+  }
+
+  async function removeForwards(peer) {
+    for (const item of await forwards()) if (item.serial === serial && item.remote === `localabstract:${peer.socketName}`)
+      await invoke(['forward', '--remove', item.local]);
+  }
+
+  function publicPeer(peer) {
+    return { serial, bootId: peer.bootId, runtimeEpoch: peer.runtimeEpoch, dexSha256: peer.dexSha256, apiLevel: peer.apiLevel, running: peer.running };
+  }
+
+  async function stopRuntime(connection) {
+    const { peer } = connection;
+    const stopped = await post(connection, { op: 'stop' });
+    if (stopped?.ok !== true || stopped.runtimeEpoch !== peer.runtimeEpoch || stopped.stopping !== true)
+      throw failure('uia_runtime_stop_unconfirmed', 'The original UIA runtime did not accept orderly shutdown.');
+    const deadline = Date.now() + Math.min(timeoutMs, 10000);
+    while (Date.now() < deadline) {
+      const current = descriptor(await readJson(`${root}/runtime.json`));
+      if (current.runtimeEpoch !== peer.runtimeEpoch) throw failure('uia_runtime_identity_mismatch', 'A different UIA runtime appeared during shutdown.');
+      if (!current.running) {
+        await removeForwards(peer);
+        return { ok: true, ...publicPeer(current) };
+      }
+      await executionSleep(50);
+    }
+    throw failure('uia_runtime_stop_unconfirmed', 'The original UIA runtime has not published its stopped state.');
+  }
+
+  async function ensureLocked(rotate) {
+    const asset = bundle();
+    const previous = await readJson(`${root}/runtime.json`);
+    let peer = previous === null ? null : descriptor(previous);
+    if (peer === null || peer.running === false) peer = await startRuntime(peer, asset);
+    if (peer.dexSha256 !== asset.manifest.sha256) throw failure('uia_runtime_version_mismatch', 'Stop the existing UIA runtime before starting this installed bundle.');
+    let connection = await connect(peer), status = await statusOf(connection);
+    if (status.closing) throw failure('uia_runtime_closing', 'The original UIA runtime is closing. Observe again after it exits.');
+    // Rotation belongs to NEW observation, before binding a node. A full epoch
+    // cannot admit another new action; acknowledgements are monotonic.
+    if (rotate && status.count === status.capacity && status.pending === 0 && status.acknowledged === status.count) {
+      await stopRuntime(connection);
+      peer = await startRuntime(peer, asset);
+      connection = await connect(peer); status = await statusOf(connection);
+    }
+    return { ...connection, status };
+  }
+
+  const ensure = () => withConnectionLock(() => ensureLocked(false));
+
+  async function originalConnection(identity) {
+    if (!protocol.validIdentity(identity) || identity.target.serial !== serial || identity.target.root !== root || identity.target.adb !== adb) {
+      throw failure('invalid_uia_execution_identity', 'Recovery requires this exact UIA action and physical device identity.');
+    }
+    return withConnectionLock(async () => {
+      const value = await readJson(`${identity.target.sessionPath}/runtime.json`);
+      if (value === null) return null;
+      const peer = descriptor(value);
+      if (peer.bootId !== identity.bootId || peer.runtimeEpoch !== identity.runtimeEpoch || peer.dexSha256 !== identity.target.dexSha256) {
+        throw failure('uia_runtime_identity_mismatch', 'The original UIA session descriptor does not match the action.');
+      }
+      if (!peer.running) return null;
+      const connection = await connect(peer);
+      await statusOf(connection);
+      return connection;
+    });
+  }
+
+  function actionPayload(op, identity) { return { op, requestJson: identity.requestJson, requestSha256: identity.requestSha256 }; }
+
+  async function maintainRecord(operation, identity) {
+    // One-shot maintenance must acquire the same phone OS lock as the runtime.
+    // It never starts UiAutomation or replays an action.
+    const asset = bundle(), destination = await installAsset(asset);
+    let raw;
+    try {
+      raw = await shell(`CLASSPATH=${quote(destination)} app_process /system/bin ${mainClass} ${quote(root)} ${asset.manifest.sha256} ${operation} ${quote(JSON.stringify(identity))}`);
+    } catch (error) {
+      let rejection;
+      try { rejection = JSON.parse(String(error.stderr).trim().split(/\r?\n/).at(-1)); } catch { /* Retain the transport error. */ }
+      if (rejection?.ok === false && typeof rejection.error === 'string' && rejection.error.startsWith('uia_'))
+        throw failure(rejection.error, 'The phone retained the original action because journal maintenance could not complete safely.');
+      throw error;
+    }
+    try { return JSON.parse(raw); }
+    catch { throw failure('uia_maintenance_response_invalid', 'The phone did not return a valid journal maintenance response.'); }
+  }
+
+  async function recover(identity, { cancel = true } = {}) {
+    if (!protocol.validIdentity(identity) || identity.target.serial !== serial || identity.target.root !== root || identity.target.adb !== adb)
+      throw failure('invalid_uia_execution_identity', 'An exact original UIA identity is required.');
+    let liveError;
+    try {
+      const connection = await originalConnection(identity);
+      if (connection) {
+        const response = await post(connection, actionPayload(cancel ? 'cancel' : 'query', identity));
+        if (protocol.originalReceipt(response, identity)) return { ...response, completionSource: 'original-runtime' };
+        liveError = response?.error || 'uia_action_not_settled';
+      }
+    } catch (error) { liveError = error.code || 'uia_runtime_unreachable'; }
+    // The second completion authority is the SAME action's durable file, not a
+    // restarted runtime, a new action, an installed app state or an idle flag.
+    const saved = await readJson(`${identity.target.sessionPath}/actions/${protocol.digest(identity.actionId)}.json`);
+    const response = protocol.recordResponse(saved, identity);
+    if (response) return { ...response, completionSource: 'original-durable-record', liveQueryError: liveError ?? null };
+    // Missing records and admitted/unknown phases are never non-dispatch proof.
+    // The phone re-reads and fully validates this exact record under owner.lock.
+    if (cancel && ['prepared', 'queued'].includes(saved?.phase)) {
+      try {
+        const record = await withConnectionLock(() => maintainRecord('recover-record', protocol.recoveryIdentity(identity)));
+        const recovered = protocol.recordResponse(record, identity);
+        if (recovered) return { ...recovered, completionSource: 'phone-journal-maintenance', liveQueryError: liveError ?? null };
+        liveError = 'uia_recovery_receipt_invalid';
+      } catch (error) { liveError = error.code || 'uia_recovery_failed'; }
+    }
+    return { ok: false, settled: false, dispatched: null, ambiguous: true, error: liveError || 'uia_original_completion_unavailable' };
+  }
+
+  return {
+    ensure, post,
+    async observe() {
+      const connection = await withConnectionLock(() => ensureLocked(true));
+      const result = await post(connection, { op: 'observe' });
+      if (result?.ok !== true || result.schemaVersion !== protocol.snapshotSchema || result.bootId !== connection.peer.bootId
+        || result.runtimeEpoch !== connection.peer.runtimeEpoch || typeof result.xml !== 'string') {
+        throw failure('uia_snapshot_invalid', 'UIA did not return a snapshot from the verified runtime.');
+      }
+      return result;
+    },
+    action: (connection, op, identity) => post(connection, actionPayload(op, identity)),
+    recover,
+    async acknowledge(identity, response) {
+      const proof = protocol.acknowledgementIdentity(identity, response);
+      if (identity.target.serial !== serial || identity.target.root !== root || identity.target.adb !== adb)
+        throw failure('invalid_uia_execution_identity', 'Acknowledgement requires the original physical device and runtime root.');
+      return withConnectionLock(async () => {
+        const value = await readJson(`${root}/runtime.json`), peer = value === null ? null : descriptor(value);
+        let connection, result;
+        if (peer?.running) {
+          try { connection = await connect(peer); await statusOf(connection); }
+          catch (error) {
+            if (error.code !== 'uia_runtime_unreachable') throw error;
+            connection = null;
+          }
+        }
+        if (connection) {
+          if (peer.runtimeEpoch === identity.runtimeEpoch) {
+            if (peer.bootId !== identity.bootId || peer.dexSha256 !== identity.target.dexSha256)
+              throw failure('uia_runtime_identity_mismatch', 'The active epoch does not match the original action.');
+            result = await post(connection, { ...actionPayload('acknowledge', identity), receiptSha256: response.receiptSha256 });
+            if (!protocol.originalReceipt(result, identity) || result.receiptSha256 !== response.receiptSha256 || result.acknowledged !== true)
+              throw failure('uia_acknowledgement_invalid', 'The runtime did not confirm this exact terminal receipt.');
+            return { ok: true, disposition: 'acknowledged' };
+          }
+          result = await post(connection, { op: 'acknowledge-record', identity: proof });
+        } else {
+          result = await maintainRecord('acknowledge-record', proof);
+        }
+        if (!protocol.acknowledgementMatches(result, proof))
+          throw failure('uia_acknowledgement_invalid', 'Maintenance did not confirm this exact original receipt identity.');
+        return { ok: true, disposition: result.disposition };
+      });
+    },
+    async control(operation) {
+      if (!['status', 'start', 'stop'].includes(operation)) throw failure('invalid_uia_runtime_operation', 'UIA runtime operation must be status, start or stop.');
+      return withConnectionLock(async () => {
+        const value = await readJson(`${root}/runtime.json`);
+        if (operation === 'start') {
+          const asset = bundle(), destination = await installAsset(asset);
+          const ownerRaw = await shell(`CLASSPATH=${quote(destination)} app_process /system/bin ${mainClass} ${quote(root)} ${asset.manifest.sha256} owner-status`);
+          let owner;
+          try { owner = JSON.parse(ownerRaw); }
+          catch { throw failure('uia_runtime_owner_unverified', 'The phone did not return valid JSON for its exclusive UIA process lock.'); }
+          if (owner?.ok !== true || owner.schemaVersion !== 'aab.uia.owner.v1' || owner.root !== root
+            || owner.dexSha256 !== asset.manifest.sha256 || typeof owner.owned !== 'boolean')
+            throw failure('uia_runtime_owner_unverified', 'The phone did not return a valid UIA process-lock observation.');
+          let peer = value === null ? null : descriptor(value);
+          if (owner.owned) {
+            if (peer === null || !peer.running) throw failure('uia_runtime_already_running', 'The original runtime still owns its process lock. Wait for it to finish starting or stopping.');
+            if (peer.dexSha256 !== asset.manifest.sha256) throw failure('uia_runtime_version_mismatch', 'Stop the existing UIA runtime before starting this installed bundle.');
+          } else {
+            // Explicit start may reopen a dead owner. The new process reacquires
+            // the OS lock and audits every original record BEFORE UiAutomation.
+            peer = await startRuntime(peer, asset, destination);
+          }
+          const state = await statusOf(await connect(peer));
+          if (state.closing) throw failure('uia_runtime_closing', 'The original runtime is still stopping.');
+          return { ...state, ...publicPeer(peer) };
+        }
+        if (value === null) return { ok: true, serial, running: false };
+        const peer = descriptor(value);
+        if (!peer.running) return { ok: true, ...publicPeer(peer) };
+        const connection = await connect(peer);
+        const state = await statusOf(connection);
+        if (operation === 'status') return { ...state, ...publicPeer(peer) };
+        return stopRuntime(connection);
+      });
+    },
+  };
+}
+
+module.exports = { createUiaRuntimePort };

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

@@ -0,0 +1,39 @@
+'use strict';
+
+const { parseXmlAttributes } = require('./xml-attributes');
+const { visitAndroidUiHierarchyTags, looksLikeAndroidUiHierarchyXml } = require('../android-uia-xml');
+
+const selectorSchema = { type: 'object', additionalProperties: false, minProperties: 1, maxProperties: 1,
+  properties: Object.fromEntries(['text', 'contentDescription', 'resourceName']
+    .map(key => [key, { type: 'string', minLength: 1 }])) };
+const intentSelectorSchema = { ...selectorSchema, properties: { ...selectorSchema.properties,
+  nodeRef: require('./uia-protocol').targetRefSchema.properties.nodeRef } };
+
+function selectUiaNode(rawTree, spec, packageName) {
+  const reject = error => ({ ok: false, error, dispatched: false });
+  if (typeof rawTree !== 'string' || !looksLikeAndroidUiHierarchyXml(rawTree)) return reject('observed_uia_xml_required');
+  const selector = spec.selector || (typeof spec.text === 'string' ? { text: spec.text } : null);
+  const keys = Object.keys(selector || {});
+  const attribute = { text: 'text', contentDescription: 'content-desc', resourceName: 'resource-id', nodeRef: 'aab-ref' }[keys[0]];
+  if (keys.length !== 1 || !attribute || typeof selector[keys[0]] !== 'string' || !selector[keys[0]]
+    || spec.exact === false || (spec.selector && spec.text != null)) return reject('explicit_exact_uia_selector_required');
+  const nodes = [];
+  visitAndroidUiHierarchyTags(rawTree, ({ tag, tagName, closing }) => {
+    if (!closing) {
+      const node = parseXmlAttributes(tag);
+      if (!node.class && tagName !== 'node') node.class = tagName;
+      nodes.push(node);
+    }
+  });
+  const selected = nodes.filter(node => node.package === packageName && node[attribute] === selector[keys[0]]
+    && node['visible-to-user'] !== 'false' && node.displayed !== 'false');
+  if (selected.length !== 1) return reject(selected.length ? 'uia_selector_not_unique' : 'uia_selector_not_found');
+  const node = selected[0];
+  const bounds = /^\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]$/.exec(node.bounds || '');
+  if (!bounds || node.enabled !== 'true' || (spec.requireClickable === true && node.clickable !== 'true')) return reject('uia_node_not_operable');
+  const [left, top, right, bottom] = bounds.slice(1).map(Number);
+  if (left < 0 || top < 0 || right <= left || bottom <= top) return reject('uia_node_not_operable');
+  return { ok: true, node, x: Math.round((left + right) / 2), y: Math.round((top + bottom) / 2) };
+}
+
+module.exports = { selectUiaNode, selectorSchema, intentSelectorSchema };