From a9f5d104c08766286397c8c4510c97ba797d8e38 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 00:00:55 +0100 Subject: [PATCH 1/6] Record Android foreground close fence observations --- .../src/__tests__/app-lifecycle-close.test.ts | 27 ++++++++--- .../platform-android/src/app-lifecycle.ts | 47 +++++++++++++++++-- 2 files changed, 62 insertions(+), 12 deletions(-) diff --git a/packages/platform-android/src/__tests__/app-lifecycle-close.test.ts b/packages/platform-android/src/__tests__/app-lifecycle-close.test.ts index 4671aa6c9a..d29db1f4be 100644 --- a/packages/platform-android/src/__tests__/app-lifecycle-close.test.ts +++ b/packages/platform-android/src/__tests__/app-lifecycle-close.test.ts @@ -3,7 +3,7 @@ import assert from 'node:assert/strict'; import { closeAndroidApp, openAndroidApp } from '../app-lifecycle.ts'; import { withAndroidAdbProvider } from '../adb-executor.ts'; import type { DeviceInfo } from '@agent-device/kernel/device'; -import { AppError } from '@agent-device/kernel/errors'; +import { AppError, normalizeError } from '@agent-device/kernel/errors'; import { ANDROID_EMULATOR } from './test-utils/device-fixtures.ts'; import './test-utils/android-host-test-setup.ts'; @@ -217,6 +217,17 @@ test.each([ phase, packageName: 'com.example.app', timeoutMs, + ...(phase === 'foreground' + ? { + initialProcessCount: 1, + foregroundObservations: [1750, 1800, 1850, 1900, 1950].map((ms) => ({ + startMs: ms, + endMs: ms, + remainingMs: 2000 - ms, + result: 'target', + })), + } + : {}), }); return true; }, @@ -278,12 +289,14 @@ test.each([ : assert.rejects(close, (error: unknown) => { assert.ok(error instanceof AppError); assert.equal(error.code, 'COMMAND_FAILED'); - assert.deepEqual(error.details, { - reason: 'android-app-close-timeout', - phase, - packageName: 'com.example.app', - timeoutMs: 2_000, - }); + assert.equal(error.details?.reason, 'android-app-close-timeout'); + assert.equal(error.details?.phase, phase); + assert.equal(error.details?.timeoutMs, 2_000); + if (phase === 'foreground') { + assert.deepEqual(normalizeError(error).details?.foregroundObservations, [ + { startMs: 0, endMs: completionMs, remainingMs: 0, result: 'other' }, + ]); + } return true; }); await Promise.all([result, vi.runAllTimersAsync()]); diff --git a/packages/platform-android/src/app-lifecycle.ts b/packages/platform-android/src/app-lifecycle.ts index fb959c6049..2bebe69774 100644 --- a/packages/platform-android/src/app-lifecycle.ts +++ b/packages/platform-android/src/app-lifecycle.ts @@ -664,8 +664,9 @@ async function stopAndroidPackage(device: DeviceInfo, packageName: string): Prom throw androidPidofUnavailableError(packageName); } await runAndroidShell(device, ['am', 'force-stop', packageName]); - const expired = await waitForAndroidPackageStopped(device, packageName, killed); - if (expired) throw androidCloseTimeoutError(packageName, expired); + const observations: ForegroundObservation[] = []; + const expired = await waitForAndroidPackageStopped(device, packageName, killed, observations); + if (expired) throw androidCloseTimeoutError(packageName, expired, observations, killed.size); } /** @@ -729,8 +730,10 @@ async function waitForAndroidPackageStopped( device: DeviceInfo, packageName: string, killed: ReadonlySet, + observations: ForegroundObservation[], ): Promise { - if (!(await waitForAndroidPackageNotForeground(device, packageName))) return 'foreground'; + if (!(await waitForAndroidPackageNotForeground(device, packageName, observations))) + return 'foreground'; if (!(await waitForAndroidKilledProcessesExit(device, packageName, killed))) return 'exit'; if (!(await waitForAndroidPackageProcessGone(device, packageName))) return 'process'; return undefined; @@ -754,25 +757,43 @@ const ANDROID_CLOSE_TIMEOUTS: Record< }, }; -function androidCloseTimeoutError(packageName: string, phase: AndroidStopFencePhase): AppError { +function androidCloseTimeoutError( + packageName: string, + phase: AndroidStopFencePhase, + observations: ForegroundObservation[], + initialProcessCount: number, +): AppError { const { message, timeoutMs } = ANDROID_CLOSE_TIMEOUTS[phase]; return new AppError('COMMAND_FAILED', `Android app ${packageName} ${message}`, { reason: 'android-app-close-timeout', phase, packageName, timeoutMs, + ...(phase === 'foreground' + ? { foregroundObservations: observations, initialProcessCount } + : {}), }); } +type ForegroundObservation = { + startMs: number; + endMs: number; + remainingMs: number; + result: 'target' | 'other' | 'unknown'; +}; + function waitForAndroidPackageNotForeground( device: DeviceInfo, packageName: string, + observations?: ForegroundObservation[], ): Promise { return waitForAndroidForegroundPackage( device, Deadline.fromTimeoutMs(ANDROID_CLOSE_FOCUS_TIMEOUT_MS), ANDROID_CLOSE_FOCUS_POLL_MS, (foregroundPackage) => foregroundPackage !== packageName, + observations, + packageName, ); } @@ -782,9 +803,25 @@ async function waitForAndroidForegroundPackage( deadline: Deadline, pollMs: number, matches: (foregroundPackage: string | undefined) => boolean, + observations?: ForegroundObservation[], + targetPackage?: string, ): Promise { while (!deadline.isExpired()) { - const foreground = await probeBeforeDeadline(deadline, () => readAndroidForegroundApp(device)); + const foreground = await probeBeforeDeadline(deadline, async () => { + const startMs = deadline.elapsedMs(); + const value = await readAndroidForegroundApp(device); + const endMs = deadline.elapsedMs(); + if (observations) { + observations.push({ + startMs, + endMs, + remainingMs: deadline.remainingMs(), + result: !value ? 'unknown' : value.package === targetPackage ? 'target' : 'other', + }); + if (observations.length > 5) observations.shift(); + } + return value; + }); if (!foreground) break; if (matches(foreground.value?.package)) return true; await sleep(pollMs); From 7d2728f49733cdd20f3805f0f82d2cdb9993530c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 00:09:45 +0100 Subject: [PATCH 2/6] Retain foreground probe failures in request diagnostics --- ...router-android-foreground-evidence.test.ts | 113 ++++++++++++++++++ .../src/__tests__/app-lifecycle-close.test.ts | 67 +++++++++++ .../platform-android/src/app-lifecycle.ts | 44 +++++-- 3 files changed, 211 insertions(+), 13 deletions(-) create mode 100644 packages/daemon/src/server/__tests__/request-router-android-foreground-evidence.test.ts diff --git a/packages/daemon/src/server/__tests__/request-router-android-foreground-evidence.test.ts b/packages/daemon/src/server/__tests__/request-router-android-foreground-evidence.test.ts new file mode 100644 index 0000000000..7afd9aecdc --- /dev/null +++ b/packages/daemon/src/server/__tests__/request-router-android-foreground-evidence.test.ts @@ -0,0 +1,113 @@ +import { test, expect, vi } from 'vitest'; +import fs from 'node:fs'; +import path from 'node:path'; +import { createTestDeviceInventoryGateways } from '@agent-device/device-selection/inventory-gateways-fixtures'; +import { createTestHostEnvironment, mkdtempForTestSync } from '@agent-device/test-kit'; +import { AppError } from '@agent-device/kernel/errors'; +import { getResolveTargetDeviceMock } from '../../__tests__/support/request-router-dispatch-mocks.ts'; +import { fakeCreateCommandSurface } from '../../__tests__/support/command-surface-fake.ts'; +import { dispatchApplicationLifecycleEffect } from '../../__tests__/support/application-lifecycle-runtime-fixture.ts'; +import { + createRequestHandler, + lifecycleDeviceRuntimeGateway, +} from '../../__tests__/support/test-device-runtime-gateway.ts'; +import { makeSessionStore } from '../../__tests__/support/store-factory.ts'; +import { LeaseRegistry } from '../../resources/lease-registry.ts'; +import { makeAndroidDevice, openRequest } from './request-router-open-harness.ts'; +import { openAndroidApp } from '../../../../platform-android/src/app-lifecycle.ts'; +import { withAndroidAdbProvider } from '../../../../platform-android/src/adb-executor.ts'; +import '../../../../platform-android/src/__tests__/test-utils/android-host-test-setup.ts'; + +vi.mock('../../core/device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) })); +const mockResolveTargetDevice = vi.mocked(getResolveTargetDeviceMock()); +function createOpenHandler(sessionStore: ReturnType) { + return createRequestHandler({ + host: createTestHostEnvironment(), + createCommandSurface: fakeCreateCommandSurface, + logPath: path.join(mkdtempForTestSync('daemon'), 'daemon.log'), + token: 'test-token', + sessionStore, + leaseRegistry: new LeaseRegistry(), + deviceRuntimeGateway: lifecycleDeviceRuntimeGateway, + deviceInventoryGateways: createTestDeviceInventoryGateways(), + trackDownloadableArtifact: () => 'artifact-id', + }); +} + +test('open relaunch retains Android foreground probe failure in the serialized response and request artifact', async () => { + const device = makeAndroidDevice('emulator-fence'); + const failure = new AppError( + 'COMMAND_FAILED', + 'probe failed', + { reason: 'probe-failed' }, + new Error('root cause'), + ); + let probes = 0; + try { + const sessionStore = makeSessionStore('android-fence-request-'); + mockResolveTargetDevice.mockResolvedValue(device); + vi.mocked(dispatchApplicationLifecycleEffect).mockImplementationOnce(async () => { + await openAndroidApp(device, 'com.example.app', { terminateRunningApp: true }); + }); + const response = await withAndroidAdbProvider( + { + exec: async (args) => { + if (args[1] === 'dumpsys' && ++probes === 1) throw failure; + return { + stdout: + args[1] === 'dumpsys' + ? 'mCurrentFocus=Window{42 u0 com.example.app/.Main}\n' + : '123\n', + stderr: '', + exitCode: 0, + }; + }, + }, + { serial: device.id }, + async () => { + return await createOpenHandler(sessionStore)( + openRequest( + 'fence-session', + { platform: 'android', relaunch: true }, + 'fence-request', + {}, + ['com.example.app'], + ), + ); + }, + ); + expect(response.ok).toBe(false); + if (response.ok) throw new Error('expected failure'); + const wire = JSON.parse(JSON.stringify(response)); + expect(wire.error).toMatchObject({ + code: 'COMMAND_FAILED', + details: { reason: 'probe-failed' }, + }); + expect(response.error.logPath).toBe( + path.join( + sessionStore.resolveDaemonStateDir(), + 'sessions', + 'fence-session', + 'requests', + 'fence-request.ndjson', + ), + ); + const events = fs + .readFileSync(response.error.logPath!, 'utf8') + .trim() + .split('\n') + .map((line) => JSON.parse(line)); + expect(events).toContainEqual( + expect.objectContaining({ + phase: 'android_close_foreground_fence', + data: { + initialProcessCount: 1, + observations: [expect.objectContaining({ result: 'error' })], + }, + }), + ); + expect(events).toContainEqual(expect.objectContaining({ phase: 'request_failed' })); + } finally { + vi.mocked(dispatchApplicationLifecycleEffect).mockReset(); + } +}); diff --git a/packages/platform-android/src/__tests__/app-lifecycle-close.test.ts b/packages/platform-android/src/__tests__/app-lifecycle-close.test.ts index d29db1f4be..fe82e1ddc9 100644 --- a/packages/platform-android/src/__tests__/app-lifecycle-close.test.ts +++ b/packages/platform-android/src/__tests__/app-lifecycle-close.test.ts @@ -541,3 +541,70 @@ test('closeAndroidApp reports an unanswered pidof after force-stop instead of an ); assert.equal(pidofCalls, 2); }); + +test('foreground probe failure retains bounded history in request diagnostics and rethrows the original error', async () => { + vi.useFakeTimers(); + vi.setSystemTime(0); + const { withDiagnosticsScope, flushDiagnosticsToSessionFile } = + await import('@agent-device/host-kit/diagnostics'); + const fs = await import('node:fs'); + const path = await import('node:path'); + const { mkdtempForTestSync } = await import('@agent-device/test-kit'); + const logPath = path.join(mkdtempForTestSync('foreground-fence'), 'request.ndjson'); + const cause = new Error('underlying failure'); + const failure = new AppError('COMMAND_FAILED', 'probe failed', { reason: 'probe-failed' }, cause); + let probes = 0; + try { + await withDiagnosticsScope({ logPath }, async () => { + await withAndroidAdbProvider( + { + exec: async (args) => { + if (args[1] === 'dumpsys' && ++probes === 7) throw failure; + return { + stdout: + args[1] === 'dumpsys' + ? 'mCurrentFocus=Window{42 u0 com.example.app/.Main}\n' + : '123\n', + stderr: '', + exitCode: 0, + }; + }, + }, + { serial: ANDROID_EMULATOR.id }, + async () => { + const rejected = assert.rejects( + closeAndroidApp(ANDROID_EMULATOR, 'com.example.app'), + (error: unknown) => { + assert.equal(error, failure); + assert.equal(failure.cause, cause); + assert.equal(failure.details?.reason, 'probe-failed'); + return true; + }, + ); + await Promise.all([rejected, vi.runAllTimersAsync()]); + }, + ); + flushDiagnosticsToSessionFile({ force: true }); + }); + const events = fs + .readFileSync(logPath, 'utf8') + .trim() + .split('\n') + .map((line) => JSON.parse(line)); + const event = events.find((item) => item.phase === 'android_close_foreground_fence'); + assert.deepEqual(event.data, { + initialProcessCount: 1, + observations: [ + ...[100, 150, 200, 250].map((ms) => ({ + startMs: ms, + endMs: ms, + remainingMs: 2000 - ms, + result: 'target', + })), + { startMs: 300, endMs: 300, remainingMs: 1700, result: 'error' }, + ], + }); + } finally { + vi.useRealTimers(); + } +}); diff --git a/packages/platform-android/src/app-lifecycle.ts b/packages/platform-android/src/app-lifecycle.ts index 2bebe69774..0d2a7344ce 100644 --- a/packages/platform-android/src/app-lifecycle.ts +++ b/packages/platform-android/src/app-lifecycle.ts @@ -1,6 +1,7 @@ import { AppError } from '@agent-device/kernel/errors'; import type { AppStateRuntimeResult } from '@agent-device/contracts/app-state-runtime'; import { Deadline, sleep } from '@agent-device/host-kit/retry'; +import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; import { isCommandTimeoutError } from '@agent-device/host-kit/command'; import type { AppsFilter } from '@agent-device/contracts/device'; import type { DeviceInfo } from '@agent-device/kernel/device'; @@ -666,6 +667,7 @@ async function stopAndroidPackage(device: DeviceInfo, packageName: string): Prom await runAndroidShell(device, ['am', 'force-stop', packageName]); const observations: ForegroundObservation[] = []; const expired = await waitForAndroidPackageStopped(device, packageName, killed, observations); + if (expired === 'foreground') emitForegroundFenceEvidence(observations, killed.size); if (expired) throw androidCloseTimeoutError(packageName, expired, observations, killed.size); } @@ -732,8 +734,14 @@ async function waitForAndroidPackageStopped( killed: ReadonlySet, observations: ForegroundObservation[], ): Promise { - if (!(await waitForAndroidPackageNotForeground(device, packageName, observations))) - return 'foreground'; + let notForeground: boolean; + try { + notForeground = await waitForAndroidPackageNotForeground(device, packageName, observations); + } catch (error) { + emitForegroundFenceEvidence(observations, killed.size); + throw error; + } + if (!notForeground) return 'foreground'; if (!(await waitForAndroidKilledProcessesExit(device, packageName, killed))) return 'exit'; if (!(await waitForAndroidPackageProcessGone(device, packageName))) return 'process'; return undefined; @@ -779,9 +787,19 @@ type ForegroundObservation = { startMs: number; endMs: number; remainingMs: number; - result: 'target' | 'other' | 'unknown'; + result: 'target' | 'other' | 'unknown' | 'error'; }; +function emitForegroundFenceEvidence( + observations: ForegroundObservation[], + initialProcessCount: number, +): void { + emitDiagnostic({ + phase: 'android_close_foreground_fence', + data: { initialProcessCount, observations }, + }); +} + function waitForAndroidPackageNotForeground( device: DeviceInfo, packageName: string, @@ -808,19 +826,19 @@ async function waitForAndroidForegroundPackage( ): Promise { while (!deadline.isExpired()) { const foreground = await probeBeforeDeadline(deadline, async () => { + if (!observations) return await readAndroidForegroundApp(device); const startMs = deadline.elapsedMs(); - const value = await readAndroidForegroundApp(device); - const endMs = deadline.elapsedMs(); - if (observations) { - observations.push({ - startMs, - endMs, - remainingMs: deadline.remainingMs(), - result: !value ? 'unknown' : value.package === targetPackage ? 'target' : 'other', - }); + let result: ForegroundObservation['result'] = 'error'; + try { + const value = await readAndroidForegroundApp(device); + result = !value ? 'unknown' : value.package === targetPackage ? 'target' : 'other'; + return value; + } finally { + const endedAt = Date.now(); + const endMs = deadline.elapsedMs(endedAt); + observations.push({ startMs, endMs, remainingMs: deadline.remainingMs(endedAt), result }); if (observations.length > 5) observations.shift(); } - return value; }); if (!foreground) break; if (matches(foreground.value?.package)) return true; From a2323b72459ab87ed1bfd2a42a7473110181cf7e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 00:10:50 +0100 Subject: [PATCH 3/6] Place foreground evidence test at composition boundary --- .../android-foreground-evidence.test.ts | 27 +++++++++++-------- 1 file changed, 16 insertions(+), 11 deletions(-) rename packages/daemon/src/server/__tests__/request-router-android-foreground-evidence.test.ts => src/__tests__/daemon-composition/android-foreground-evidence.test.ts (74%) diff --git a/packages/daemon/src/server/__tests__/request-router-android-foreground-evidence.test.ts b/src/__tests__/daemon-composition/android-foreground-evidence.test.ts similarity index 74% rename from packages/daemon/src/server/__tests__/request-router-android-foreground-evidence.test.ts rename to src/__tests__/daemon-composition/android-foreground-evidence.test.ts index 7afd9aecdc..06825001b6 100644 --- a/packages/daemon/src/server/__tests__/request-router-android-foreground-evidence.test.ts +++ b/src/__tests__/daemon-composition/android-foreground-evidence.test.ts @@ -4,21 +4,26 @@ import path from 'node:path'; import { createTestDeviceInventoryGateways } from '@agent-device/device-selection/inventory-gateways-fixtures'; import { createTestHostEnvironment, mkdtempForTestSync } from '@agent-device/test-kit'; import { AppError } from '@agent-device/kernel/errors'; -import { getResolveTargetDeviceMock } from '../../__tests__/support/request-router-dispatch-mocks.ts'; -import { fakeCreateCommandSurface } from '../../__tests__/support/command-surface-fake.ts'; -import { dispatchApplicationLifecycleEffect } from '../../__tests__/support/application-lifecycle-runtime-fixture.ts'; +import { getResolveTargetDeviceMock } from '../../../packages/daemon/src/__tests__/support/request-router-dispatch-mocks.ts'; +import { fakeCreateCommandSurface } from '../../../packages/daemon/src/__tests__/support/command-surface-fake.ts'; +import { dispatchApplicationLifecycleEffect } from '../../../packages/daemon/src/__tests__/support/application-lifecycle-runtime-fixture.ts'; import { createRequestHandler, lifecycleDeviceRuntimeGateway, -} from '../../__tests__/support/test-device-runtime-gateway.ts'; -import { makeSessionStore } from '../../__tests__/support/store-factory.ts'; -import { LeaseRegistry } from '../../resources/lease-registry.ts'; -import { makeAndroidDevice, openRequest } from './request-router-open-harness.ts'; -import { openAndroidApp } from '../../../../platform-android/src/app-lifecycle.ts'; -import { withAndroidAdbProvider } from '../../../../platform-android/src/adb-executor.ts'; -import '../../../../platform-android/src/__tests__/test-utils/android-host-test-setup.ts'; +} from '../../../packages/daemon/src/__tests__/support/test-device-runtime-gateway.ts'; +import { makeSessionStore } from '../../../packages/daemon/src/__tests__/support/store-factory.ts'; +import { LeaseRegistry } from '../../../packages/daemon/src/resources/lease-registry.ts'; +import { + makeAndroidDevice, + openRequest, +} from '../../../packages/daemon/src/server/__tests__/request-router-open-harness.ts'; +import { openAndroidApp } from '../../../packages/platform-android/src/app-lifecycle.ts'; +import { withAndroidAdbProvider } from '../../../packages/platform-android/src/adb-executor.ts'; +import '../../../packages/platform-android/src/__tests__/test-utils/android-host-test-setup.ts'; -vi.mock('../../core/device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) })); +vi.mock('../../../packages/daemon/src/core/device/device-ready.ts', () => ({ + ensureDeviceReady: vi.fn(async () => {}), +})); const mockResolveTargetDevice = vi.mocked(getResolveTargetDeviceMock()); function createOpenHandler(sessionStore: ReturnType) { return createRequestHandler({ From 85518b451eb5f53f0d1afb8667d33db96ae4d27c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 00:12:15 +0100 Subject: [PATCH 4/6] Use Android package seams in routed evidence test --- ...router-android-foreground-evidence.test.ts | 30 ++++++++++--------- 1 file changed, 16 insertions(+), 14 deletions(-) rename src/__tests__/daemon-composition/android-foreground-evidence.test.ts => packages/daemon/src/server/__tests__/request-router-android-foreground-evidence.test.ts (75%) diff --git a/src/__tests__/daemon-composition/android-foreground-evidence.test.ts b/packages/daemon/src/server/__tests__/request-router-android-foreground-evidence.test.ts similarity index 75% rename from src/__tests__/daemon-composition/android-foreground-evidence.test.ts rename to packages/daemon/src/server/__tests__/request-router-android-foreground-evidence.test.ts index 06825001b6..3fb91e8c85 100644 --- a/src/__tests__/daemon-composition/android-foreground-evidence.test.ts +++ b/packages/daemon/src/server/__tests__/request-router-android-foreground-evidence.test.ts @@ -4,24 +4,20 @@ import path from 'node:path'; import { createTestDeviceInventoryGateways } from '@agent-device/device-selection/inventory-gateways-fixtures'; import { createTestHostEnvironment, mkdtempForTestSync } from '@agent-device/test-kit'; import { AppError } from '@agent-device/kernel/errors'; -import { getResolveTargetDeviceMock } from '../../../packages/daemon/src/__tests__/support/request-router-dispatch-mocks.ts'; -import { fakeCreateCommandSurface } from '../../../packages/daemon/src/__tests__/support/command-surface-fake.ts'; -import { dispatchApplicationLifecycleEffect } from '../../../packages/daemon/src/__tests__/support/application-lifecycle-runtime-fixture.ts'; +import { getResolveTargetDeviceMock } from '../../__tests__/support/request-router-dispatch-mocks.ts'; +import { fakeCreateCommandSurface } from '../../__tests__/support/command-surface-fake.ts'; +import { dispatchApplicationLifecycleEffect } from '../../__tests__/support/application-lifecycle-runtime-fixture.ts'; import { createRequestHandler, lifecycleDeviceRuntimeGateway, -} from '../../../packages/daemon/src/__tests__/support/test-device-runtime-gateway.ts'; -import { makeSessionStore } from '../../../packages/daemon/src/__tests__/support/store-factory.ts'; -import { LeaseRegistry } from '../../../packages/daemon/src/resources/lease-registry.ts'; -import { - makeAndroidDevice, - openRequest, -} from '../../../packages/daemon/src/server/__tests__/request-router-open-harness.ts'; -import { openAndroidApp } from '../../../packages/platform-android/src/app-lifecycle.ts'; -import { withAndroidAdbProvider } from '../../../packages/platform-android/src/adb-executor.ts'; -import '../../../packages/platform-android/src/__tests__/test-utils/android-host-test-setup.ts'; +} from '../../__tests__/support/test-device-runtime-gateway.ts'; +import { makeSessionStore } from '../../__tests__/support/store-factory.ts'; +import { LeaseRegistry } from '../../resources/lease-registry.ts'; +import { makeAndroidDevice, openRequest } from './request-router-open-harness.ts'; +import { openAndroidApp, withAndroidAdbProvider } from '@agent-device/platform-android/mechanics'; +import { bindAndroidAdbHost, type AndroidAdbHost } from '@agent-device/platform-android/adb-host'; -vi.mock('../../../packages/daemon/src/core/device/device-ready.ts', () => ({ +vi.mock('../../core/device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}), })); const mockResolveTargetDevice = vi.mocked(getResolveTargetDeviceMock()); @@ -40,6 +36,12 @@ function createOpenHandler(sessionStore: ReturnType) { } test('open relaunch retains Android foreground probe failure in the serialized response and request artifact', async () => { + bindAndroidAdbHost({ + environment: {}, + withAdbCommandExecutorOverride: async (_override, fn) => await fn(), + withoutAdbCommandExecutorOverride: async (fn) => await fn(), + coerceAdbResult: (result) => result, + } as AndroidAdbHost); const device = makeAndroidDevice('emulator-fence'); const failure = new AppError( 'COMMAND_FAILED', From ad488cc1ee99098ba5c656ce918dfb96023e0b41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 00:13:43 +0100 Subject: [PATCH 5/6] Exercise request evidence at daemon boundary --- ...router-android-foreground-evidence.test.ts | 51 +++++-------------- 1 file changed, 14 insertions(+), 37 deletions(-) diff --git a/packages/daemon/src/server/__tests__/request-router-android-foreground-evidence.test.ts b/packages/daemon/src/server/__tests__/request-router-android-foreground-evidence.test.ts index 3fb91e8c85..5702f5ded7 100644 --- a/packages/daemon/src/server/__tests__/request-router-android-foreground-evidence.test.ts +++ b/packages/daemon/src/server/__tests__/request-router-android-foreground-evidence.test.ts @@ -14,8 +14,7 @@ import { import { makeSessionStore } from '../../__tests__/support/store-factory.ts'; import { LeaseRegistry } from '../../resources/lease-registry.ts'; import { makeAndroidDevice, openRequest } from './request-router-open-harness.ts'; -import { openAndroidApp, withAndroidAdbProvider } from '@agent-device/platform-android/mechanics'; -import { bindAndroidAdbHost, type AndroidAdbHost } from '@agent-device/platform-android/adb-host'; +import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; vi.mock('../../core/device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}), @@ -36,12 +35,6 @@ function createOpenHandler(sessionStore: ReturnType) { } test('open relaunch retains Android foreground probe failure in the serialized response and request artifact', async () => { - bindAndroidAdbHost({ - environment: {}, - withAdbCommandExecutorOverride: async (_override, fn) => await fn(), - withoutAdbCommandExecutorOverride: async (fn) => await fn(), - coerceAdbResult: (result) => result, - } as AndroidAdbHost); const device = makeAndroidDevice('emulator-fence'); const failure = new AppError( 'COMMAND_FAILED', @@ -49,39 +42,23 @@ test('open relaunch retains Android foreground probe failure in the serialized r { reason: 'probe-failed' }, new Error('root cause'), ); - let probes = 0; try { const sessionStore = makeSessionStore('android-fence-request-'); mockResolveTargetDevice.mockResolvedValue(device); vi.mocked(dispatchApplicationLifecycleEffect).mockImplementationOnce(async () => { - await openAndroidApp(device, 'com.example.app', { terminateRunningApp: true }); - }); - const response = await withAndroidAdbProvider( - { - exec: async (args) => { - if (args[1] === 'dumpsys' && ++probes === 1) throw failure; - return { - stdout: - args[1] === 'dumpsys' - ? 'mCurrentFocus=Window{42 u0 com.example.app/.Main}\n' - : '123\n', - stderr: '', - exitCode: 0, - }; + emitDiagnostic({ + phase: 'android_close_foreground_fence', + data: { + initialProcessCount: 1, + observations: [{ startMs: 0, endMs: 10, remainingMs: 1990, result: 'error' }], }, - }, - { serial: device.id }, - async () => { - return await createOpenHandler(sessionStore)( - openRequest( - 'fence-session', - { platform: 'android', relaunch: true }, - 'fence-request', - {}, - ['com.example.app'], - ), - ); - }, + }); + throw failure; + }); + const response = await createOpenHandler(sessionStore)( + openRequest('fence-session', { platform: 'android', relaunch: true }, 'fence-request', {}, [ + 'com.example.app', + ]), ); expect(response.ok).toBe(false); if (response.ok) throw new Error('expected failure'); @@ -109,7 +86,7 @@ test('open relaunch retains Android foreground probe failure in the serialized r phase: 'android_close_foreground_fence', data: { initialProcessCount: 1, - observations: [expect.objectContaining({ result: 'error' })], + observations: [{ startMs: 0, endMs: 10, remainingMs: 1990, result: 'error' }], }, }), ); From a13f5f6ee6f3a722ad695a7376216c3357fb22bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 00:31:45 +0100 Subject: [PATCH 6/6] docs(android): explain foreground close failure evidence --- packages/command-surface/src/management/app.ts | 2 +- website/docs/docs/commands.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/command-surface/src/management/app.ts b/packages/command-surface/src/management/app.ts index 77bba7d068..9de7aa211a 100644 --- a/packages/command-surface/src/management/app.ts +++ b/packages/command-surface/src/management/app.ts @@ -95,7 +95,7 @@ const openCommandMetadata = defineFieldCommandMetadata( const closeCommandMetadata = defineFieldCommandMetadata( 'close', - 'Close the named app, or close the active session app when app is omitted. The shutdown option also stops the session simulator or emulator where supported; close alone never stops the device. Android ADB close fails with android-app-close-timeout if the app stays foreground past 2s, a killed process does not exit within 10s, or a new process runs past 2s; a relaunching open accepts that new process. It fails with android-process-probe-unavailable when adb pidof cannot list the app processes; if that happens before the force-stop, the app keeps running. If close cannot confirm its cleanup on a session that holds a device claim, the session and its claim stay. A repeated close retries cleanup with the same options, except that save-script must be omitted after publication.', + 'Close the named app, or close the active session app when app is omitted. The shutdown option also stops the session simulator or emulator where supported; close alone never stops the device. Android ADB close fails with android-app-close-timeout if the app stays foreground past 2s, a killed process does not exit within 10s, or a new process runs past 2s; a relaunching open accepts that new process. For foreground timeouts, JSON details include foregroundObservations and initialProcessCount; the android_close_foreground_fence request diagnostic retains the last five probe results and timings, including when a probe throws. It fails with android-process-probe-unavailable when adb pidof cannot list the app processes; if that happens before the force-stop, the app keeps running. If close cannot confirm its cleanup on a session that holds a device claim, the session and its claim stay. A repeated close retries cleanup with the same options, except that save-script must be omitted after publication.', { app: stringField('Optional app to close.'), shutdown: booleanField('Shutdown the session/device where supported.'), diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md index 90dac45f0a..2a8dd7588a 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -107,6 +107,7 @@ Open apps and links: - Android React Native: `open --relaunch` needs an installed package name. Install or reinstall the APK first; `open --relaunch` is rejected. For Metro-backed JS changes, run `metro reload` before reaching for `open --relaunch`. - Android (adb): an intent target such as `open settings` records the package that opened as `appBundleId`. `open settings --relaunch` stops and restarts that app. If the intent matches more than one activity, `--relaunch` fails. - Android (ADB): `close` force-stops the app, then checks for 2 seconds that it has left the foreground, waits up to 10 seconds for the processes it killed to exit, and checks for 2 more that no new process started. If a check window ends first, `close` fails with `details.reason: android-app-close-timeout` and `details.phase` set to `foreground`, `exit`, or `process`; a process that survives the force-stop fails with `exit`, and apps Android restarts at once, such as the launcher, fail with `process`. `open --relaunch` runs the same checks but accepts a new process once the killed ones exit, because Android can restart an app at once for a background client, such as Settings on Android 17. When `pidof` cannot list the app's processes, `close` fails with `details.reason: android-process-probe-unavailable`; if that happens before the force-stop, the app keeps running. +- To diagnose an Android foreground-close timeout (`details.phase: foreground`), inspect `details.foregroundObservations` and `details.initialProcessCount` in the JSON error. The observations retain at most the last five probes: `startMs` and `endMs` are milliseconds from the start of the foreground check, `remainingMs` is the budget left when the probe ends, and `result` is `target`, `other`, or `unknown`. The process count is read before force-stop. In the [session request log](/docs/sessions#find-a-sessions-logs-and-artifacts), the `android_close_foreground_fence` diagnostic records this history as `data.observations` with `data.initialProcessCount`. If a foreground probe throws, that diagnostic also retains the history with an `error` result for the failed probe; the command reports the probe failure. - When `close` cannot confirm its cleanup on a session that holds a device claim, it fails and keeps the session and its claim, so the device is not handed on unconfirmed. Run `close` again with the same options to retry the cleanup and release the device, leaving out `--save-script` once the first attempt has published the script. Only `close`, or a successful `open`, is supported on the kept session: other commands work, but the session stays marked, so an idle daemon can still shut it down. If nobody retries, the kept session does not keep the daemon alive: when the daemon has been idle for its idle timeout and shuts down, its shutdown retries the cleanup, and a claim it still cannot confirm goes stale instead of being released. Embedded runtimes and `AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS=0` never shut down for idleness, so there a retried `close` is the only release. - If `open --relaunch` leaves an existing session's device effects unconfirmed, the session and claim remain available for `close`, but idle shutdown can retry cleanup and leave an unconfirmed claim stale; embedded runtimes and `AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS=0` do not shut down for idleness, so use `close` to release the claim.