@mobileaidev/ai-app-bridge 0.4.1 → 0.4.2

package/README.md

@@ -7,9 +7,9 @@ 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 source version is `0.4.1`; registry publication is a separate release step.
+This source version is `0.4.2`; registry publication is a separate release step.
 It fixes iOS observation ownership and preserves extraction results when
-temporary cleanup fails. Device and Web SDKs share version `0.4.1`; their execution contracts are unchanged.
+temporary cleanup fails. Device and Web SDKs share version `0.4.2`; their execution contracts are unchanged.
 The default installation includes the Script/Intent and capture contracts below.
 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.
@@ -67,7 +67,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.4.1
+npm install -g @mobileaidev/ai-app-bridge@0.4.2
 
 ai-app-bridge status --extract null --package-name io.github.mobileaidev.aiappbridge.sample
 ai-app-bridge tree --extract null --package-name io.github.mobileaidev.aiappbridge.sample
@@ -341,6 +341,12 @@ recovery. `uia-runtime --serial DEVICE --operation status|start|stop` controls
 its lifecycle. Fresh observation rotates a full, durably acknowledged session;
 startup retires only confirmed history. Explicit start checks the phone's
 process lock before reopening a dead runtime; unknown actions still block it.
+For a stuck action or agent handoff, run `ai-app-bridge device-ownership
+--operation force-stop --serial DEVICE --extract null`. This independent reset
+stops old Host tasks and phone executors, archives the unknown action, and frees
+occupancy without waiting for its receipt. Tasks sharing those Host processes
+also stop. New operations can then start; dispatched effects are not rolled back.
+Occupancy errors include the same recovery hint.
 Host crashes leave a durable pending-acknowledgement queue. `device-ownership
 --operation reconcile --serial DEVICE` commits completion history, acknowledges
 live or stopped phone records and retires that queue without replay.

package/bin/command-registry.js

@@ -17,7 +17,7 @@ const commandDefinitions = [
   { 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: 'device-ownership', domain: 'execution', summary: 'Read ownership, reconcile completion, or force-stop stuck tasks and reset device occupancy without requiring old receipts. Force-stop terminates the owning and shared Host runtimes, resets phone UIA history, and stops recorded SDK apps; dispatched effects keep an unknown outcome. Also cancel-install or read a retained UIA receipt.', 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'] },
   { 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'] },
@@ -252,7 +252,7 @@ function isMutationCommand(command, args = {}) {
   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')
+    || (command === 'device-ownership' && ['cancel-install', 'force-stop'].includes(args.operation))
     || (command === 'ios-wda-session' && args.operation !== 'status')
     || (command === 'uia-runtime' && args.operation !== 'status')
     || ((command === 'webview-network' || command === 'webview-console') && args.script !== undefined);
@@ -321,7 +321,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 === '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,
+      conditionalMutation: command === 'device-ownership' ? 'operation in reconcile,cancel-install,force-stop' : 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'
@@ -342,11 +342,11 @@ function commandSchema(command) {
     properties: { operation: { enum: ['start', 'status', 'stop'] } } };
   if (definition.domain === 'web') return require('./web/command-schema').webSchema(command);
   if (command === 'device-ownership') return { type: 'object', additionalProperties: false,
-    properties: { operation: { enum: ['status', 'reconcile', 'receipt', 'cancel-install'] }, serial: { type: 'string', minLength: 1 },
+    properties: { operation: { enum: ['status', 'reconcile', 'receipt', 'cancel-install', 'force-stop'] }, serial: { type: 'string', minLength: 1 },
       runtimeEpoch: { type: 'string', pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' },
       actionId: { type: 'string', minLength: 1, maxLength: 1024 }, timeoutMs: { type: 'integer', minimum: 1, maximum: 30000 } },
     required: ['operation', 'serial'], oneOf: [
-      { properties: { operation: { enum: ['status', 'reconcile'] }, runtimeEpoch: false, actionId: false } },
+      { properties: { operation: { enum: ['status', 'reconcile', 'force-stop'] }, runtimeEpoch: false, actionId: false } },
       { properties: { operation: { const: 'receipt' }, timeoutMs: false }, required: ['runtimeEpoch', 'actionId'] },
       { properties: { operation: { const: 'cancel-install' }, runtimeEpoch: false }, required: ['actionId'] },
     ] };

package/bin/executors/automation-owner.js

@@ -8,8 +8,19 @@ 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)); }
+const fileFor = (serial, directory = defaultDirectory()) => path.join(directory, 'automation-sessions', createHash('sha256').update(serial).digest('hex') + '.json');
+function owner(serial, directory) { return readJson(fileFor(serial, directory)); }
+function archive(serial, resetId, directory = defaultDirectory()) {
+  const file = fileFor(serial, directory);
+  if (!fs.existsSync(file)) return null;
+  const destination = path.join(directory, 'force-stopped', `${resetId}.automation.json`);
+  fs.renameSync(file, destination);
+  for (const parent of [path.dirname(file), path.dirname(destination)]) {
+    const fd = fs.openSync(parent, 'r');
+    try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+  }
+  return destination;
+}
 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.');
@@ -35,8 +46,8 @@ async function assertAvailable(serial) {
   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.',
+  throw new CommandError('uia_owned_by_test_executor', 'The test session owns UiAutomation. Close that session, or use device-ownership force-stop to stop stuck tasks and reset this device.',
     { dispatched: false, ambiguous: false, details: { serial, sessionId: current.sessionId, runtimeEpoch: descriptor.runtimeEpoch, packageName: descriptor.packageName } });
 }
 
-module.exports = { owner, claim, release, assertAvailable };
+module.exports = { owner, claim, release, archive, assertAvailable };

package/bin/runtime-client.js

@@ -137,7 +137,8 @@ async function run(request, { signal } = {}) {
   let extract;
   try {
     request = validateRunRequest(request);
-    if (request.command === 'runtime' || (request.command === 'evidence' && request.arguments.operation === 'verify')) {
+    if (request.command === 'runtime' || (request.command === 'evidence' && request.arguments.operation === 'verify')
+      || (request.command === 'device-ownership' && request.arguments.operation === 'force-stop')) {
       extract = require('./extraction/prepare').prepareExtraction(request.extract);
     }
   }
@@ -145,6 +146,9 @@ async function run(request, { signal } = {}) {
   const local = async reply => ({ value: await finishReply({ body: publicReply({ command: request.command, reply, completed: true }),
     extract, output: request.output }) });
   try {
+    if (request.command === 'device-ownership' && request.arguments.operation === 'force-stop') {
+      return local({ value: await require('./shared-kernel/device-force-stop').forceStopDevice(request.arguments) });
+    }
     // Verification is an offline command in both transports; it neither
     // opens FactStore nor depends on a running owner or valid store profile.
     if (request.command === 'evidence' && request.arguments.operation === 'verify') {

package/bin/runtime-directory.js

@@ -80,7 +80,7 @@ function requireCompatible(status, client) {
   let next;
   if (!codeMismatch) next = 'Use matching persistent/provider configuration; the running Runtime was not restarted.';
   else if (outdatedSide === 'client') next = 'The client package is older. Update and reconnect the client; do not stop the newer Runtime to fix this client.';
-  else if (outdatedSide === 'runtime') next = 'The Runtime package is older. Finish its active tasks, then explicitly run runtime --operation stop --extract null and reconnect with the updated installation.';
+  else if (outdatedSide === 'runtime') next = 'The Runtime package is older. Finish its active tasks, then explicitly run runtime --operation stop --extract null and reconnect with the updated installation. If a device task is stuck, device-ownership --operation force-stop --serial <serial> --extract null forcibly stops old tasks and resets occupancy.';
   else next = 'Builds or Node environments differ. Align the installations and reconnect; fingerprints alone cannot identify an older side.';
   throw new CommandError(codeMismatch ? 'runtime_code_mismatch' : 'runtime_configuration_mismatch',
     `Client: ${describe(client)}. Runtime: ${describe(runtime)}. ${next}`,

package/bin/shared-kernel/device-force-stop.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { randomUUID } = require('node:crypto');
+const { CommandError } = require('../command-errors');
+const { createOwnershipStore, schemaVersion } = require('./device-ownership-store');
+const { stopHosts } = require('./host-process-stop');
+
+async function stopDevice(serial, pending, timeoutMs, automation) {
+  const { readJson } = require('../executors/managed-runtime');
+  const descriptor = automation ? readJson(automation.descriptorFile) : null;
+  if (descriptor && (descriptor.serial !== serial || descriptor.sessionId !== automation.sessionId))
+    throw new CommandError('executor_descriptor_mismatch', 'The recorded test session does not match this device.');
+  const { executablePath } = require('./executable-path');
+  const adb = pending.find(item => item.target?.adb)?.target.adb || descriptor?.adb || executablePath(process.env.ADB || 'adb');
+  const { createUiaRuntimePort } = require('./uia-runtime-port');
+  const uia = await createUiaRuntimePort({ adb, serial, timeoutMs }).forceStop();
+  const packages = [...new Set([...pending.map(item => item.target?.packageName || item.packageName),
+    descriptor?.packageName, descriptor?.instrumentation?.split('/')[0]].filter(Boolean))];
+  const { execFileBounded } = require('./execution-io');
+  for (const packageName of packages) {
+    if (!/^[a-zA-Z0-9_.]+$/.test(packageName)) throw new CommandError('invalid_force_stop_package', 'The recorded Android package is invalid.');
+    await execFileBounded(adb, ['-s', serial, 'shell', 'am', 'force-stop', packageName], { timeoutMs, mutation: false, encoding: 'utf8' });
+  }
+  return { ...uia, stoppedPackages: packages };
+}
+
+// This control runs in the CLI/MCP client, before contacting the shared runtime.
+// A hung runtime, its queues, and version mismatch cannot intercept the reset.
+async function forceStopDevice(args, { directory, stopHost = stopHosts, stopDevice: remoteStop = stopDevice,
+  runtimeEndpoint } = {}) {
+  const store = createOwnershipStore(directory);
+  const control = store.controlLock(args.serial);
+  if (!control) throw new CommandError('device_reset_in_progress', 'Another force-stop is resetting this device. Retry after it finishes.');
+  let lock;
+  let journalError = null;
+  const readForReset = () => {
+    try { return store.read(args.serial); }
+    catch (error) {
+      if (error.code !== 'device_ownership_corrupt') throw error;
+      // Forced reset archives corrupt bytes instead of requiring the damaged
+      // task record to prove completion. Normal admission remains strict.
+      journalError = error.code; return null;
+    }
+  };
+  try {
+    let previous = readForReset();
+    if (runtimeEndpoint === undefined) {
+      const { runtimeLocation, readEndpoint } = require('../runtime-directory');
+      runtimeEndpoint = readEndpoint(runtimeLocation());
+    }
+    const stoppedHostPids = await stopHost(previous?.owner, runtimeEndpoint);
+    const deadline = Date.now() + (args.timeoutMs ?? 10000);
+    while (!(lock = store.lock(args.serial))) {
+      if (Date.now() >= deadline) throw new CommandError('force_stop_host_still_owned', 'The terminated Host has not released its OS lock.');
+      await new Promise(resolve => setTimeout(resolve, 25));
+    }
+    const resetId = randomUUID(), resetAtMs = Date.now();
+    previous = readForReset();
+    const pending = previous?.resetPending || [previous?.pending, ...(previous?.reservations || [])].filter(Boolean);
+    const abandoned = pending.map(item => ({ kind: item.kind, actionId: item.actionId ?? null, runtimeEpoch: item.runtimeEpoch ?? null }));
+    const archiveDir = path.join(store.directory, 'force-stopped');
+    fs.mkdirSync(archiveDir, { recursive: true, mode: 0o700 });
+    const archivePath = fs.existsSync(store.paths(args.serial).journal) ? path.join(archiveDir, `${resetId}.json`) : null;
+    if (archivePath) {
+      const file = fs.openSync(archivePath, 'wx', 0o600);
+      try { fs.writeFileSync(file, fs.readFileSync(store.paths(args.serial).journal)); fs.fsyncSync(file); }
+      finally { fs.closeSync(file); }
+      const parent = fs.openSync(archiveDir, 'r');
+      try { fs.fsyncSync(parent); } finally { fs.closeSync(parent); }
+    }
+    const state = { schemaVersion, serial: args.serial, phase: 'idle', owner: null, pending: null, reservations: [],
+      pendingAcknowledgements: [], lastSettlement: previous?.lastSettlement ?? null, resetRequired: true, resetPending: pending,
+      lastReset: { resetId, resetAtMs, disposition: 'force_stopped', outcome: 'unknown', abandoned, archivePath, stoppedHostPids,
+        ...(journalError ? { journalError } : {}) } };
+    store.write(args.serial, state);
+    const automationStore = require('../executors/automation-owner');
+    let phone;
+    try {
+      const automation = automationStore.owner(args.serial, store.directory);
+      phone = await remoteStop(args.serial, pending, args.timeoutMs ?? 10000, automation);
+      if (phone?.ok !== true) throw new CommandError(phone?.error || 'force_stop_device_failed', 'The phone did not confirm the forced reset.');
+      if (automation) state.lastReset.automationArchivePath = automationStore.archive(args.serial, resetId, store.directory);
+    } catch (error) {
+      const code = typeof error.code === 'string' && /^[a-z][a-z0-9_]*$/.test(error.code) ? error.code : 'force_stop_device_failed';
+      return { ok: false, error: code, phase: 'idle', serial: args.serial,
+        ownershipReleased: true, remoteResetPending: true, ...state.lastReset,
+        remoteError: { code, message: error.message },
+        message: 'Local occupancy was reset. Reconnect the device and repeat device-ownership force-stop before new actions.' };
+    }
+    state.resetRequired = false; delete state.resetPending; state.lastReset.phone = phone; store.write(args.serial, state);
+    return { ok: true, serial: args.serial, phase: 'idle', ownershipReleased: true, remoteResetPending: false,
+      ...state.lastReset, phone, message: 'Forced reset completed. Old tasks were stopped; agents can start new operations.' };
+  } finally { lock?.close(); control.close(); }
+}
+
+module.exports = { forceStopDevice };

package/bin/shared-kernel/device-mutation-lease.js

@@ -9,10 +9,15 @@ const acknowledgements = require('./device-acknowledgements');
 const context = new AsyncLocalStorage();
 const effectContext = new AsyncLocalStorage();
 
+const recoveryHint = serial => ({ command: 'device-ownership', arguments: { operation: 'force-stop', serial },
+  message: 'If stuck, force-stop this device to cancel old tasks and reset occupancy. Already dispatched effects are not rolled back.' });
+
 function rejection(error, serial, ownership) {
   return { ok: false, error, serial, active: 1, dispatched: false, ambiguous: false,
     message: error === 'target_busy' ? 'Another Host operation owns this physical device.'
+      : error === 'device_reset_required' ? 'Phone reset is incomplete. Reconnect and repeat device-ownership force-stop before new actions.'
       : 'A previous device action has no confirmed completion. Reconcile device ownership before another mutation.',
+    recoveryHint: recoveryHint(serial),
     ...(ownership ? { ownership: structuredClone(ownership) } : {}) };
 }
 
@@ -39,13 +44,19 @@ function createDeviceMutationLease({ directory } = {}) {
       }, release() {} };
     }
     if (held.has(serial)) return rejection('target_busy', serial, held.get(serial).state);
-    const lock = store.lock(serial);
-    if (!lock) return rejection('target_busy', serial);
+    const control = store.controlLock(serial);
+    if (!control) return rejection('target_busy', serial);
+    let lock;
     try {
+      lock = store.lock(serial);
+      if (!lock) return rejection('target_busy', serial);
       const previous = store.read(serial);
+      if (previous?.resetRequired) { lock.close(); return rejection('device_reset_required', serial, previous); }
       if (previous?.pending || previous?.reservations.length) { lock.close(); return rejection('device_ownership_unresolved', serial, previous); }
-      const state = { schemaVersion, serial, phase: 'owned', owner: { id: randomUUID(), pid: process.pid, acquiredAtMs: Date.now() },
+      const state = { schemaVersion, serial, phase: 'owned', owner: { id: randomUUID(), pid: process.pid,
+        processStart: require('./host-process-stop').processStart(), acquiredAtMs: Date.now() },
         pending: null, reservations: [], lastSettlement: previous?.lastSettlement ?? null,
+        lastReset: previous?.lastReset ?? null,
         pendingAcknowledgements: previous?.pendingAcknowledgements ?? [] };
       store.write(serial, state);
       const owner = { serial, directory: store.directory, state, closed: false,
@@ -94,7 +105,8 @@ function createDeviceMutationLease({ directory } = {}) {
           finally { owner.closed = true; held.delete(serial); lock.close(); }
         },
       };
-    } catch (error) { lock.close(); throw error; }
+    } catch (error) { lock?.close(); throw error; }
+    finally { control.close(); }
   }
   async function run(serial, action) {
     const token = acquire(serial);
@@ -108,11 +120,16 @@ function createDeviceMutationLease({ directory } = {}) {
       const state = store.read(serial);
       const unresolved = state?.pending || state?.reservations.length;
       return { ok: true, serial, active: !lock || unresolved ? 1 : 0, maxActive: 1,
-        phase: !lock ? 'owned' : unresolved ? 'unresolved' : 'idle', ownership: state ? structuredClone(state) : null };
+        phase: !lock ? 'owned' : unresolved ? 'unresolved' : 'idle', ownership: state ? structuredClone(state) : null,
+        ...(unresolved || state?.resetRequired ? { recoveryHint: recoveryHint(serial) } : {}) };
     } finally { lock?.close(); }
   }
   async function reconcile(serial, verify) {
-    const lock = held.has(serial) ? null : store.lock(serial);
+    const control = store.controlLock(serial);
+    if (!control) return rejection('target_busy', serial);
+    let lock;
+    try { lock = held.has(serial) ? null : store.lock(serial); }
+    finally { control.close(); }
     if (!lock) return rejection('target_busy', serial);
     try {
       const state = store.read(serial);
@@ -132,7 +149,11 @@ function createDeviceMutationLease({ directory } = {}) {
     } finally { lock.close(); }
   }
   async function drainAcknowledgements(serial, acknowledge) {
-    const lock = held.has(serial) ? null : store.lock(serial);
+    const control = store.controlLock(serial);
+    if (!control) return rejection('target_busy', serial);
+    let lock;
+    try { lock = held.has(serial) ? null : store.lock(serial); }
+    finally { control.close(); }
     if (!lock) return rejection('target_busy', serial);
     try {
       const state = store.read(serial), errors = [], retired = [];

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

@@ -88,7 +88,8 @@ function createOwnershipStore(directory = defaultDirectory()) {
       throw new CommandError('device_ownership_unavailable', 'Cannot commit device ownership; no new action is allowed.', { details: { serial, cause: error.message } });
     }
   }
-  return { directory, read, lock, write };
+  const controlLock = serial => createOwnershipStore(path.join(directory, 'reset-controls')).lock(serial);
+  return { directory, read, lock, write, paths, controlLock };
 }
 
 module.exports = { createOwnershipStore, defaultDirectory, schemaVersion };

package/bin/shared-kernel/host-process-stop.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+const { CommandError } = require('../command-errors');
+
+function processInfo(pid) {
+  if (!Number.isSafeInteger(pid) || pid < 1) return null;
+  try {
+    if (process.platform === 'win32') {
+      const raw = execFileSync('powershell.exe', ['-NoProfile', '-Command',
+        `$p=Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}'; if($p){@{start=$p.CreationDate.ToUniversalTime().ToString('O');command=$p.CommandLine}|ConvertTo-Json -Compress}`],
+      { encoding: 'utf8', timeout: 3000, windowsHide: true });
+      return raw.trim() ? JSON.parse(raw) : null;
+    }
+    const raw = execFileSync('ps', ['-p', String(pid), '-o', 'lstart=', '-o', 'pgid=', '-o', 'args='],
+      { encoding: 'utf8', timeout: 3000, env: { ...process.env, LC_ALL: 'C' }, stdio: ['ignore', 'pipe', 'pipe'] });
+    const match = raw.trim().match(/^(\w{3}\s+\w{3}\s+\d+\s+\d\d:\d\d:\d\d\s+\d{4})\s+(\d+)\s+([\s\S]+)$/);
+    return match ? { start: match[1], group: Number(match[2]), command: match[3] } : null;
+  } catch (error) {
+    if (error.status === 1) return null;
+    throw error;
+  }
+}
+
+let ownStart;
+function processStart() { return ownStart ||= processInfo(process.pid)?.start; }
+
+async function stopHosts(owner, endpoint) {
+  const stopped = [];
+  for (const item of [owner, endpoint]) {
+    if (!item || stopped.includes(item.pid)) continue;
+    const info = processInfo(item.pid);
+    if (!info) continue;
+    if (item.pid === process.pid) throw new CommandError('force_stop_requires_control_client',
+      'Run device-ownership force-stop through CLI or MCP, outside the execution owner.');
+    const identified = item.processStart ? item.processStart === info.start
+      : /[\\/]bin[\\/](execution-runtime|ai-app-bridge|mcp-server)\.js(?:\s|$)/.test(info.command);
+    // PID reuse means the original Host is gone. It must neither block reset
+    // nor cause an unrelated replacement process to be killed.
+    if (!identified) continue;
+    try {
+      if (process.platform === 'win32') execFileSync('taskkill.exe', ['/PID', String(item.pid), '/F', '/T'], { timeout: 5000, windowsHide: true, stdio: 'pipe' });
+      else if (info.group === item.pid) process.kill(-item.pid, 'SIGKILL');
+      else {
+        const inventory = execFileSync('ps', ['-axo', 'pid=', '-o', 'ppid='],
+          { encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'pipe'] });
+        const pairs = inventory.trim().split('\n').map(line => line.trim().split(/\s+/).map(Number));
+        const descendants = [item.pid];
+        for (let i = 0; i < descendants.length; i++)
+          for (const [pid, parent] of pairs) if (parent === descendants[i]) descendants.push(pid);
+        for (const pid of descendants.reverse()) {
+          try { process.kill(pid, 'SIGKILL'); }
+          catch (error) { if (error.code !== 'ESRCH') throw error; }
+        }
+      }
+      stopped.push(item.pid);
+    } catch (error) { if (error.code !== 'ESRCH') throw error; }
+  }
+  return stopped;
+}
+
+module.exports = { processStart, stopHosts };

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

@@ -294,6 +294,25 @@ function createUiaRuntimePort({ adb, serial, timeoutMs = 10000, root = protocol.
   }
 
   return {
+    async forceStop() {
+      // Host reset owns the separate administrative gate and has already
+      // terminated previous Host writers. This never waits for old callbacks.
+      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} force-reset`); }
+      catch (error) {
+        let remote;
+        try { remote = JSON.parse(error.stderr?.trim()); } catch { /* non-protocol ADB failure */ }
+        if (typeof remote?.error === 'string') throw failure(remote.error, remote.message || 'The phone rejected forced reset.');
+        throw error;
+      }
+      let result;
+      try { result = JSON.parse(raw); }
+      catch { throw failure('uia_force_reset_invalid', 'The phone did not return a forced-reset receipt.'); }
+      if (result?.ok !== true || result.schemaVersion !== 'aab.uia.reset.v1' || result.stopped !== true)
+        throw failure(result?.error || 'uia_force_reset_unconfirmed', 'The UIA executor was not force-reset.');
+      return result;
+    },
     async withInstrumentation(descriptorFile, start) {
       return withConnectionLock(async () => {
         const automation = require('../executors/automation-owner');

package/docs/COMMAND_CONTRACT.md

@@ -710,8 +710,8 @@ the local ADB process does not by itself confirm a cancelled install has settled
 Use `device-ownership {operation:"status",serial:"DEVICE"}` to inspect ownership,
 or `operation:"reconcile"` to query the recorded action through its original
 package and transport configuration. Reconciliation exclusively owns the device
-while checking; there is no force-release, caller-supplied replacement target,
-expiry, or action replay. Android Native, Flutter, H5 and managed shell actions can
+while checking; normal reconciliation does not expire or replay actions, or
+substitute their target. Android Native, Flutter, H5 and managed shell actions can
 recover from an identity-matching `aab.native-execution/v1`,
 `aab.flutter-execution/v1`, `aab.h5-execution/v1` or
 `aab.android-shell-execution/v1` terminal receipt. UIA node actions use
@@ -725,6 +725,30 @@ Other transports without a matching completion protocol remain unresolved.
 Installation uses the original phone job and PackageInstaller session contract
 described below.
 
+**Stuck device / agent handoff:** use `device-ownership
+{operation:"force-stop",serial:"DEVICE"}`. CLI: `ai-app-bridge device-ownership
+--operation force-stop --serial DEVICE --extract null`. This emergency reset runs
+in the CLI/MCP client before connecting to the execution Runtime, including when
+the Runtime hangs, its queue is blocked, or its version differs. It kills the
+recorded owning Host and the shared Host runtime, including Script/Intent child
+processes and queued tasks. Other tasks in those Host processes also stop.
+On the selected phone it kills UIA and managed shell worker groups, archives UIA
+sessions while retaining the process-lock inode, and stops recorded SDK apps.
+A retained instrumentation/Flutter test owner is stopped and its UiAutomation
+claim archived, so a replacement agent can observe the phone again.
+A new observation starts a fresh UIA epoch. No terminal callback is required.
+
+The ownership journal becomes idle. `disposition:force_stopped,outcome:unknown`
+preserves abandoned action identities and the original archived journal; this
+does not roll back dispatched effects or fabricate the original outcome.
+Even a corrupt Host task journal is archived as bytes and reset explicitly.
+Device admission and force-stop share an independent administrative gate.
+If the phone cannot reset, local tasks and occupancy still stop; the reply has
+`ownershipReleased:true,remoteResetPending:true`. Reconnect and repeat force-stop.
+A durable reset-required marker prevents new dispatch until phone reset succeeds,
+including after a reset-client crash. Occupancy failures include a short
+`recoveryHint` with exact force-stop arguments. Resetting an idle device is valid.
+
 The ownership journal is `aab.device-ownership/v2`, under the **same physical
 lock directory** above. Reading v1 preserves every unresolved identity and
 reservation; the next commit upgrades its format. v1 had no pending-ack queue,

package/docs/INSTALLATION.md

@@ -5,7 +5,7 @@ The same npm package contains CLI and MCP; running only MCP is supported.
 FactStore is an embedded library bundled in that package. There is no separate
 database, FactStore service or CLI process to install first.
 
-This source targets the coordinated 0.4.1 release.
+This source targets the coordinated 0.4.2 release.
 Registry publication is a separate step; before
 publication, use the reviewed local tarball instead of expecting this registry
 version to resolve.
@@ -15,7 +15,7 @@ version to resolve.
   "mcpServers": {
     "ai-app-bridge": {
       "command": "npx",
-      "args": ["--yes", "--package", "@mobileaidev/ai-app-bridge@0.4.1", "ai-app-bridge-mcp"]
+      "args": ["--yes", "--package", "@mobileaidev/ai-app-bridge@0.4.2", "ai-app-bridge-mcp"]
     }
   }
 }

package/docs/OPTIONAL_EXECUTORS.md

@@ -1,4 +1,4 @@
-# Optional UI executors (0.4.1)
+# Optional UI executors (0.4.2)
 
 Bridge keeps its existing SDK paths and exposes optional executors through `capabilities`, `run`, and JavaScript/Python Script. Select an executor explicitly. No command silently changes a touch into a setter, switches framework after failure, or repeats an uncertain action.
 
@@ -52,9 +52,9 @@ android {
     }
 }
 dependencies {
-    androidTestImplementation("com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-test-instrumentation:0.4.1")
+    androidTestImplementation("com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-test-instrumentation:0.4.2")
     // Optional H5 adapter:
-    androidTestImplementation("com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-test-espresso-web:0.4.1")
+    androidTestImplementation("com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-test-espresso-web:0.4.2")
 }
 ```
 
@@ -109,7 +109,7 @@ Espresso text actions have different semantics. `replaceText` is the framework's
 
 ## Flutter
 
-Add `ai_app_bridge_test: 0.4.1` to the application's `dev_dependencies`. The helper takes `flutter_test` and `integration_test` from the **same Flutter SDK** as the application. It is a Dart test helper, not an additional Android plugin with its own AGP/Kotlin versions.
+Add `ai_app_bridge_test: 0.4.2` to the application's `dev_dependencies`. The helper takes `flutter_test` and `integration_test` from the **same Flutter SDK** as the application. It is a Dart test helper, not an additional Android plugin with its own AGP/Kotlin versions.
 
 The helper declares Flutter **>=3.41.0** and Dart **>=3.11.0 <4.0.0**. The 0.3.8 automatic preparation was exercised with LocalSend on Flutter **3.41.9 / Android API 36**, preserving all 214 production dependency versions. Earlier executor validation covered Flutter 3.41.9 / API 25 and 3.44.8 / API 36. These are specific verified combinations; other SDK versions still need validation with the application's plugin graph.
 

package/docs/RELEASE.md

@@ -1,71 +1,37 @@
-# 0.4.1 统一补丁发行检查
-
-源码版本、可发布验收、registry 发布和正在运行的客户端是四个不同状态。
-本文件描述发行操作；源码中的版本号不代表 npm/JitPack/pub.dev 已发布。
-0.4.0 改善版的实施与放行证据记录于仓库
-`docs/IMPROVEMENT_RELEASE_V1_2026-09-18.md` 及各 M1–M5 交付记录。
-0.4.1 统一发布全部 Bridge 组件，Host 修复与回归证据见
-`docs/HOST_0.4.0_GROK_REVIEW_2026-09-19.md`；设备及 Web SDK 仅同步版本与依赖。
-
-本次修复 iOS 观察控制误占设备动作 ownership，并为旧误记 marker 提供
-显式 reconcile；提取临时目录清理失败改为 cleanupError，保留原提取结果。
-超预算 reference 交付和 extract 必填合同不变；设备端执行合同不变。
-
-## 兼容与迁移
-
-0.4.0 的外部 run 必填 `extract`，不提取显式 null；CLI `--extract null`。
-返回公共封套含 execution/control/extraction/delivery，删除额外 `_history`、
-`_meta` 副本。旧请求不自动补字段。业务 value 在 null 且预算内保持原值，
-Script 的内部 ctx.call 仍返回 ok/result。Runtime 协议仍是 aab.runtime/v1。
-
-调用方先核对 execution 和控制字段；提取失败后用原 source ref 调 response
-read，不重放动作。详见 [公共提取合同与完整示例](RESPONSE_EXTRACTION.md)。
-发现正文超预算时按 command/operation 收窄，不静默裁剪 schema。
-
-## 发行资源
-
-| 资源 | 源码版本 | 发行渠道 |
-| --- | --- | --- |
-| Desktop CLI/MCP | 0.4.1 | npm @mobileaidev/ai-app-bridge |
-| 嵌入式 native store | 0.2.0 | 随主包 bundleDependencies，包括四个预编译 addon |
-| Android SDK / Gradle plugin / executor modules | 0.4.1 | 同仓库 Git tag / JitPack |
-| iOS Swift 包 | Git tag 0.4.1 | 根 Package.swift |
-| Flutter SDK / test helper | 0.4.1 | pub.dev；Android 固定依赖同版 SDK |
-| Web SDK | 0.4.1 | npm @mobileaidev/ai-app-bridge-web |
-
-UIA bundle、WDA 14.1.1、iOS WDA 模板、Playwright helper 与三类范例随主包。
-未改变代码的设备组件不需要仅为 Host 返回合同重新安装；需要测试新发行
-设备产物时记录实际版本/包/序列号，不能用旧安装冒充新包验收。
-
-## 发布前门禁
-
-本次必须通过新增缺陷回归、Host 完整功能/性能组、真实 iPhone 恢复验证及
-最终 tarball 安装检查。SDK 同步版本后重新验证构建与公开依赖；未变更的
-原生 addon 复用 0.4.0 四平台验收，并核实归档字节相同。
-
-1. 固定审核提交，核对工作包和 A01–A16，保留失败与未验证项。完整 npm
-   功能组与安静环境串行性能组通过，范例由文档读取实际执行。
-2. 对 [Host 支持矩阵](INSTALLATION.md) 的四个 artifact 校验 checksum 和
-   实际加载，运行 native tests 与全新 tarball 安装。正常安装和纯 MCP
-   JS/regex 路径禁止调用本地编译器/Python；Python 回归使用单独环境。
-3. 核对 npm pack 清单真实包含 addon、加载器、source read/worker 和文档，
-   codeFingerprint 哈希实际选中的二进制。固定版本 npx 首次/重复启动、
-   MCP 断连后 Runtime 存续、明确 stop/restart 与持久化恢复均有证据。
-4. 核实实际 CLI 路径、MCP 启动版本/指纹、Runtime code/config/Node 身份，
-   并检查受影响消费脚本的 extract/公共响应迁移。安装成功不替代入口更新。
-5. Android/Swift/Flutter/Web 的发行清单和版本一致。需要时运行相应构建，
-   真实设备证据和离线/受控 ADB 测试分开记录。三类实际任务对照保留来源、
-   时间、目标和原始记录，不能将缺设备写成不适用。
-
-## 对外发布顺序
-
-本次推送已验收提交与统一 `0.4.1` tag，核实 JitPack 公开坐标成功解析，
-再发布依赖它们的 Flutter SDK/helper。Web npm 与主 CLI/MCP npm 分别发布
-已经验证的 tarball，核实 `latest`/`next` 均为 0.4.1、公开下载 checksum
-与候选包一致，并创建对应 GitHub Release。保留旧 `0.4.0` tag 不动。远端流水线
-成功与设备业务验收分别列明。本地构建或 MavenLocal/path 替换不能证明公开
-坐标可安装。
-
-客户端升级时退出旧 MCP 再重新连接。若是旧客户端碰到新 Runtime，先升
-客户端；只有明确 Runtime 是待升级一侧时，在其任务结束后显式 stop。
-同版本不同指纹只能说明构建或 Node 环境不一致，不能凭 hash 判断新旧。
+# 0.4.2 统一补丁发行检查
+
+本次补齐 Android 卡死任务的强制停止与占用重置入口，并统一 CLI/MCP、
+Android SDK/plugin/执行器、iOS Swift、Flutter SDK/helper、Web SDK 为 0.4.2。
+嵌入式 native store 保持 0.2.0。发布结果单独记录，源码版本不代表 registry 已发布。
+
+## 修复
+
+- `device-ownership force-stop` 在 CLI/MCP 客户端独立执行，绕过挂住的
+  Runtime、执行队列和版本检查；终止旧 Host 及共享 Host 的子进程和任务。
+- 手机 UIA 增加强制 reset：停止旧进程，在原 owner.lock 下归档未知/损坏记录，
+  为新 epoch 清出可用空间。普通 cancel/reconcile 的原回执合同保持不变。
+- 原任务结果保留为 `force_stopped/unknown`；占用错误附简短 recoveryHint。
+  手机断开时本地占用仍释放，保留 reset-required 标记，重连后重复重置。
+- SDK/Web 的执行行为不变，仅版本和依赖同步。新 UIA bundle 随 CLI 发布。
+
+## 放行检查
+
+1. 新增未知回执、活进程、并发占用、离线重试及提示合同回归；Host 完整功能组
+   和串行性能组通过。UIA JVM 测试通过，DEX/manifest 同步到 CLI。
+2. OnePlus b46093e6 的旧 admitted 操作真实解除；新会话再次观察和操作成功，
+   占用返回 idle。保存强制停止事实和新操作原始回执。
+3. Android build/lint/test、Swift iPhoneOS 构建、Flutter 分析和测试、Web 测试。
+   版本同步不代替业务 App 验收；测试 helper 无 test 目录不记为测试通过。
+4. 最终 npm tarball 在仓库外安装；CLI/MCP 发现、提取、Script 和强制停止
+   合同通过。未变更的四平台 native addon 校验归档字节。
+5. 两个 Flutter 包发布 dry-run；源码和公开依赖版本一致，历史 changelog 保留。
+
+## 发布与客户端升级
+
+推送验收提交和新 0.4.2 tag；核实 JitPack SDK/plugin/执行器坐标后发布
+Flutter SDK/helper。发布受检 CLI 与 Web npm tarball，并将 latest/next
+统一为 0.4.2；核实公开下载 checksum，再创建 GitHub Release。
+旧 tag 保留。需要凭据或人工登录时明确记录阻塞，不把未发布渠道写成已发布。
+
+全局 CLI 升级后核实路径/版本/运行 Runtime。已有 MCP 连接需重连加载新的
+客户端控制入口。遇到旧占用可使用新 CLI 的 force-stop，不必等待旧任务。

package/package.json

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

package/runtime/uia/manifest.json

@@ -2,7 +2,7 @@
     "schemaVersion": "aab.uia.bundle.v1",
     "mainClass": "io.github.mobileaidev.aiappbridge.uia.UiaRuntime",
     "artifact": "ai-app-bridge-uia.jar",
-    "sha256": "54a78985b47adf05e2db95a1c4deb25a093bbf3f2b158c75d1fb96aaaddd2c80",
+    "sha256": "fa7c38c912a39a14b687ca53b16e849ea6f3c15cd8d0a1e29aa48fb1feb26637",
     "minApi": 25,
     "compileApi": 35,
     "buildTools": "36.0.0",
@@ -17,7 +17,8 @@
         "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": "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/UiaReset.java": "5dfd537ee83a4ae8e6bd87aab5606edf21c132271aea2d46609606e8baa488e5",
+        "android/ai-app-bridge-uia/src/main/java/io/github/mobileaidev/aiappbridge/uia/UiaRuntime.java": "b8d1b298f29a3abcf80d0b5aba8a225607e08612f06b4deda56edcbb547bcac9",
         "android/ai-app-bridge-uia/src/main/java/io/github/mobileaidev/aiappbridge/uia/Wire.java": "d54e79c5e064abf5c7b36d2ab43205b7d47cca001ec37bf9b82ab01e33cf816c"
     }
 }

package/skills/ai-app-bridge-use/SKILL.md

@@ -21,6 +21,8 @@ CLI 与 MCP 共用独立执行 Runtime、命令合同和 operationId。CLI 响
 
 旧 MCP 实例可能与已安装 CLI 不同。缺少 Intent/Script 或参数不匹配时，核对实际入口版本，选用支持当前合同的入口；不要套用旧 batch、工具别名或外层参数。
 
+**卡死 / 换 agent：** Android 遇到 `target_busy`、`device_ownership_unresolved` 或旧动作一直没有终态时，按返回的 `recoveryHint` 调 `device-ownership {operation:"force-stop",serial:"原设备"}`；CLI 为 `ai-app-bridge device-ownership --operation force-stop --serial 原设备 --extract null`。这是独立重置入口：无需旧回执，强制结束旧 Host 及共享 Runtime 的任务，重置手机执行器并解除占用。共享这些 Host 的其他任务也会结束；已派发效果记为未知。读取 `ownershipReleased/remoteResetPending`；手机已重置后重新观察并开始新操作，手机断开时重连后再执行一次。
+
 ## 响应与提取
 
 先看 `execution` 的原执行事实及 `failureStage`，再消费 `value`；Script 内部 `ctx.call` 仍按 `ok/result` 处理，不加 extract。`control` 保留续跑字段和采集覆盖；当前 Script 问题从 `control.pendingQuestion` 读取，即使 events 被游标过滤也可回答。