mobile-debug-mcp 0.35.0 → 0.37.0

package/test/unit/observe/system-trace-router.test.ts

@@ -0,0 +1,49 @@
+import assert from 'node:assert/strict'
+import { SystemTraceRouter } from '../../../src/observe/system-trace-router.js'
+import type { SystemTraceSessions, TraceResult } from '../../../src/observe/system-trace.js'
+import type { IosTraceSessions, IosTraceResult } from '../../../src/observe/ios-trace/sessions.js'
+import type { IosTraceNative } from '../../../src/observe/ios-trace/native.js'
+function backend(platform:'android'|'ios') {
+  let next=0,starts=0
+  const results=new Map<string,TraceResult|IosTraceResult>()
+  const api={
+    capabilities:async()=>({}),
+    start:async(device:string|{id:string})=>{
+      starts++
+      const result={trace_id:platform+ ++next,device:{platform,id:typeof device==='string'?device:device.id},state:'recording',cleanup:{status:'pending'}} as TraceResult|IosTraceResult
+      results.set(result.trace_id,result);return result
+    },
+    control:async(id:string,op:string)=>{
+      const result=results.get(id);if(!result)throw new Error('TRACE_NOT_FOUND')
+      if(op==='cancel'){result.cleanup.status='complete';result.state='cancelled'}
+      return result
+    },
+    link:async()=>async()=>({trace_id:'linked',coverage:'covered',clock_alignment:'unknown'}),
+    shutdown:async()=>[]
+  }
+  return {api,results,count:()=>starts}
+}
+async function run(){
+  const android=backend('android'),ios=backend('ios')
+  let release!:()=>void,gate=Promise.resolve()
+  const native={shutdown:()=>{},capabilities:async(device:string)=>{await gate;return {supported:true,device:{platform:'ios',id:device,simulator:true}}}} as unknown as IosTraceNative
+  const router=new SystemTraceRouter(android.api as unknown as SystemTraceSessions,ios.api as unknown as IosTraceSessions,native)
+  const a=await router.start('a'),b=await router.start('b',30000,{appId:'fixture'})
+  await assert.rejects(()=>router.link(b.trace_id,{platform:'android',id:'b'},'bad'),/TRACE_NOT_FOUND/)
+  await assert.rejects(()=>router.link(b.trace_id,{platform:'ios',id:'other'},'bad'),/TRACE_NOT_FOUND/)
+  await assert.rejects(()=>router.start('b',30000,{appId:'fixture'}),/TRACE_BUSY/)
+  await router.start('c');await router.start('d',30000,{appId:'fixture'})
+  await assert.rejects(()=>router.start('fifth'),/TRACE_BUSY/)
+  await router.control(a.trace_id,'cancel')
+  await router.start('freed')
+  await router.control(b.trace_id,'cancel')
+  gate=new Promise<void>(r=>{release=r})
+  const first=router.start('pending',30000,{appId:'fixture'})
+  await new Promise(r=>setImmediate(r))
+  await assert.rejects(()=>router.start('pending',30000,{appId:'fixture'}),/TRACE_BUSY/)
+  release();await first
+  assert.equal(ios.count(),3)
+  await router.shutdown();await assert.rejects(()=>router.start('closed'),/TRACE_BUSY/)
+  console.log('PASS cross-platform trace routing, pinned linkage, shared reservations and shutdown')
+}
+run().catch(error=>{console.error(error);process.exitCode=1})

package/test/unit/quality/agent-plugin-export.test.ts

@@ -0,0 +1,38 @@
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = fileURLToPath(new URL('../../../', import.meta.url))
+const temporary = await mkdtemp(path.join(os.tmpdir(), 'agent-plugin-export-'))
+const output = path.join(temporary, 'plugin')
+const exportPlugin = () => spawnSync(process.execPath, ['scripts/agent-plugin.mjs', '--export-antigravity', output], { cwd: root, encoding: 'utf8', timeout: 10000 })
+try {
+  const exported = exportPlugin()
+  assert.equal(exported.status, 0, exported.stderr)
+  assert.deepEqual((await readdir(output)).sort(), ['LICENSE', 'README.md', 'assets', 'mcp_config.json', 'plugin.json', 'skills'])
+  for (const directory of ['skills', 'assets']) {
+    const files = await readdir(path.join(output, directory), { recursive: true })
+    assert.ok(files.every(file => path.basename(file) !== '.DS_Store' && !path.basename(file).startsWith('._')), 'Export must exclude Finder metadata')
+  }
+  const manifest = JSON.parse(await readFile(path.join(output, 'plugin.json'), 'utf8'))
+  assert.equal(manifest.$schema, 'https://antigravity.google/schemas/v1/plugin.json')
+  assert.ok((await readFile(path.join(output, manifest.logo))).length > 0)
+  const config = JSON.parse(await readFile(path.join(output, 'mcp_config.json'), 'utf8'))
+  assert.equal(Object.keys(config.mcpServers).length, 1)
+  const server = config.mcpServers['mobile-debug-mcp']
+  assert.equal(server.command, 'npx')
+  assert.equal(server.cwd, '${PLUGIN_DATA}')
+  assert.equal('type' in server, false, 'Antigravity infers stdio transport; type causes a strict warning')
+  const skill = 'skills/mobile-debug-mcp/SKILL.md'
+  assert.deepEqual(await readFile(path.join(output, skill)), await readFile(path.join(root, 'agent-plugin', skill)))
+  assert.deepEqual(await readFile(path.join(output, 'LICENSE')), await readFile(path.join(root, 'LICENSE')))
+  await writeFile(path.join(output, 'keep.txt'), 'existing user data')
+  assert.notEqual(exportPlugin().status, 0, 'Existing destinations must not be overwritten or merged')
+  assert.equal(await readFile(path.join(output, 'keep.txt'), 'utf8'), 'existing user data')
+  console.log('PASS Antigravity export: native inventory, shared skill/license, no foreign manifests, overwrite refusal')
+} finally {
+  await rm(temporary, { recursive: true, force: true })
+}

package/test/unit/server/compact-interaction.test.ts

@@ -0,0 +1,87 @@
+import assert from 'node:assert/strict'
+import { randomUUID } from 'node:crypto'
+import { actionHandler } from '../../../src/server/handlers/action-execution.js'
+import { toolHandlers, handleToolCall } from '../../../src/server/handlers/tool-handlers.js'
+import { wrapResponse } from '../../../src/server/common.js'
+import { withDeviceReadinessProbe } from '../../../src/observe/device-readiness.js'
+import { captureEvidence, evidenceDispatch } from '../../../src/observe/evidence.js'
+import { markDispatchStarted } from '../../../src/utils/operation-budget.js'
+import { observedState } from '../../../src/server/handlers/compact-state.js'
+import { finalizeCompactInteraction } from '../../../src/server/handlers/compact-interaction.js'
+
+const device = { platform: 'android' as const, id: 'fixture-emulator' }
+const original = toolHandlers.tap
+let dispatches = 0
+const decode = (r: Awaited<ReturnType<typeof handleToolCall>>) => JSON.parse(r.content[0].text!)
+const lookup = async (value: ReturnType<typeof decode>) => decode(await handleToolCall('get_interaction_diagnostics', { sessionId: value.diagnostics.session_id, resultId: value.diagnostics.result_id }))
+try {
+  const baselines = [1129, 1639, 1157, 1106]
+  for (const [index, kind] of ['success-none', 'success-observed', 'failed-dispatch', 'blocked-before-dispatch'].entries()) {
+    toolHandlers.tap = actionHandler('tap', async () => {
+      if (kind !== 'blocked-before-dispatch') await evidenceDispatch(device, async () => { markDispatchStarted(); dispatches++ })
+      if (kind === 'success-observed') await captureEvidence('fingerprint', device, async () => ({ device, fingerprint: 'screen-after' }))
+      return wrapResponse({ device, success: kind.startsWith('success'), lifecycle_state: kind === 'success-observed' ? 'verified' : 'pending_verification',
+        ...(kind === 'failed-dispatch' ? { failure_code: 'ACTION_TIMEOUT', retryable: false, details: { error: 'original timeout details' } } : {}),
+        ...(kind === 'blocked-before-dispatch' ? { failure_code: 'ELEMENT_NOT_FOUND', retryable: true } : {}) })
+    })
+    const response = await withDeviceReadinessProbe(async (_cmd, args) => ({ exitCode: 0, stderr: '', stdout: args.includes('power') ? 'mWakefulness=Awake\nmWakefulnessChanging=false' : 'KeyguardServiceDelegate\n showing=false' }), () => handleToolCall('tap', { platform: 'android', deviceId: device.id, responseMode: 'compact', verificationMode: index === 1 ? 'full' : 'none' }))
+    const result = decode(response), size = Buffer.byteLength(response.content[0].text!)
+    assert.ok(size <= 1280 + Buffer.byteLength(device.id), `${kind} exceeds budget: ${size}`)
+    assert.ok(size <= baselines[index] * .8, `${kind} needs 20% reduction: ${size}`)
+    assert.equal(result.observed_state.status, index === 1 ? 'observed' : 'unknown')
+    assert.equal(result.device_readiness.input_ready, null)
+    assert.equal(result.evidence.observations, undefined)
+    const before = dispatches, diagnostic = await lookup(result)
+    assert.equal(diagnostic.success, true)
+    assert.equal(dispatches, before, 'lookup must not replay input')
+    assert.equal(diagnostic.result.evidence.action_id, result.action_id)
+    if (index === 2) { assert.equal(result.delivery_status, 'unknown'); assert.equal(result.retryable, false); assert.equal(diagnostic.result.details.error, 'original timeout details') }
+    if (index === 3) assert.equal(result.dispatch_started, false)
+    console.log(`${kind}: ${size} bytes, ~${Math.ceil(size / 4)} tokens (bytes/4 estimate)`)
+  }
+} finally { toolHandlers.tap = original }
+const stamp = Date.now(), evidence = { session_id: randomUUID(), action_id: randomUUID(), correlation_id: randomUUID(), device, dispatch_completed_at_ms: stamp,
+  observations: [{ kind: 'ui_tree', status: 'captured', freshness: 'fresh', device, capture_started_at_ms: stamp + 1, source_captured_at_ms: stamp + 2, snapshot_session_id: randomUUID(), snapshot_revision: 4 }] }
+assert.equal(observedState(evidence, true).status, 'observed')
+for (const patch of [{ freshness: 'stale' }, { freshness: 'unknown' }, { source_captured_at_ms: null }, { status: 'failed' }, { device: { ...device, id: 'other' } }, { capture_started_at_ms: stamp - 1 }]) {
+  assert.equal(observedState({ ...evidence, observations: [{ ...evidence.observations[0], ...patch }] }, true).status, 'unknown')
+}
+const heavy = { success: false, failure_code: 'PRECONDITION_FAILED', dispatch_started: false, delivery_status: 'not_delivered', verification: { status: 'not_requested' }, evidence,
+  device_readiness: { wakefulness: 'asleep', lock_state: 'locked', input_ready: false, blockers: ['DEVICE_ASLEEP', 'DEVICE_LOCKED'], limitations: [] },
+  condition: { status: 'mismatch', reason: 'STATE_CHANGED', observed: { elements: Array(1000).fill({ text: '私'.repeat(100) }) } },
+  state_delta: { added: Array(1000).fill({ text: 'private' }), changed: [], removed: [], snapshot_revision: 4, truncated: true }, actual_state: '😀'.repeat(100) }
+const response = finalizeCompactInteraction('tap', { responseMode: 'compact' }, wrapResponse(heavy)), compact = decode(response)
+assert.ok(Buffer.byteLength(response.content[0].text!) <= 1280 + device.id.length)
+assert.deepEqual(compact.device_readiness.blockers, ['DEVICE_ASLEEP', 'DEVICE_LOCKED'])
+assert.equal(compact.condition.observed?.elements, undefined)
+assert.equal((await lookup(compact)).result.condition.observed.elements.length, 1000)
+const debug = wrapResponse(heavy), unchanged = debug.content[0].text
+finalizeCompactInteraction('tap', { responseMode: 'debug' }, debug)
+assert.equal(debug.content[0].text, unchanged)
+const steps = Array.from({ length: 50 }, (_, i) => ({ id: `${i}-😀`.repeat(100), type: 'tap', status: 'failed', success: false, result: heavy }))
+const journeyResponse = finalizeCompactInteraction('run_journey', {}, wrapResponse({ success: false, stopped_at_step_id: steps[0].id, steps, evidence })), journey = decode(journeyResponse)
+assert.equal(journey.steps.length, 50)
+assert.deepEqual(journey.steps.map((s: { id: string }) => s.id), steps.map(s => s.id))
+assert.ok(Buffer.byteLength(journeyResponse.content[0].text!) <= 1280 + 1280 * 50 + steps.reduce((n, s) => n + 2 * Buffer.byteLength(s.id), 0))
+assert.equal(journey.diagnostics.available, false, 'oversized original journey reports unavailable explicitly')
+console.log('PASS final compact budgets, freshness, no replay, diagnostic fidelity, huge conditions/deltas, multibyte values, 50-step IDs and debug compatibility')
+const controlId = '\u0001'.repeat(3000)
+const escaped = finalizeCompactInteraction('run_journey', {}, wrapResponse({ success: false, stopped_at_step_id: controlId,
+  steps: [{ id: controlId, type: 'assert', status: 'failed', success: false, result: { success: false, observed_state: { property: 'checked', value: false }, evidence } }], evidence }))
+const escapedJourney = decode(escaped)
+assert.equal(escapedJourney.steps[0].id, controlId)
+assert.deepEqual(escapedJourney.steps[0].result.observed, { property: 'checked', value: false })
+assert.ok(Buffer.byteLength(escaped.content[0].text!) <= 2560 + 2 * (Buffer.byteLength(JSON.stringify(controlId)) - 2) + 2 * device.id.length)
+const maximal = { ...heavy, action_id: randomUUID(), action_type: 'scroll_to_element', lifecycle_state: 'pending_verification', retryable: false,
+  verification: { mode: 'light', status: 'unavailable' }, verification_diagnostic: { code: 'VERIFICATION_UNAVAILABLE', retryable: true },
+  device_readiness: { wakefulness: 'transitioning', lock_state: 'unknown', input_ready: false,
+    blockers: ['DEVICE_ASLEEP', 'DEVICE_LOCKED', 'DEVICE_TRANSITIONING', 'DEBUGGER_PAUSED'],
+    limitations: ['DEVICE_WAKEFULNESS_UNVERIFIED', 'DEVICE_LOCK_OBSERVATION_UNAVAILABLE', 'DEVICE_LOCK_OBSERVATION_FAILED'] },
+  evidence: { ...evidence, trace_context: { trace_id: randomUUID() } }, error: { code: 'UNKNOWN', message: '\u0001'.repeat(1000) } }
+const maximalResponse = finalizeCompactInteraction('tap', { responseMode: 'compact' }, wrapResponse(maximal))
+assert.ok(Buffer.byteLength(maximalResponse.content[0].text!) <= 1280 + device.id.length, maximalResponse.content[0].text!)
+assert.deepEqual(decode(maximalResponse).device_readiness.blockers, maximal.device_readiness.blockers)
+const maximalSteps = Array.from({ length: 50 }, (_, i) => ({ id: `max-${i}`, type: 'tap', status: 'failed', success: false, result: maximal }))
+const maximalJourney = finalizeCompactInteraction('run_journey', {}, wrapResponse({ success: false, stopped_at_step_id: 'max-0', steps: maximalSteps, evidence }))
+assert.ok(Buffer.byteLength(maximalJourney.content[0].text!) <= 1280 + 1280 * 50 + maximalSteps.reduce((n, s) => n + Buffer.byteLength(s.id), 0) + Buffer.byteLength('max-0') + 51 * device.id.length,
+  `maximal 50-step response exceeded budget: ${Buffer.byteLength(maximalJourney.content[0].text!)}`)

package/test/unit/server/compact-journey-evidence.test.ts

@@ -0,0 +1,40 @@
+import assert from 'node:assert/strict'
+import { withEvidence, evidenceDispatch, captureEvidence, completeJourneyVerification, withJourneyStepEvidence, refreshJourneyEvidence } from '../../../src/observe/evidence.js'
+import { observedState } from '../../../src/server/handlers/compact-state.js'
+import { finalizeCompactInteraction } from '../../../src/server/handlers/compact-interaction.js'
+import { wrapResponse } from '../../../src/server/common.js'
+import { interactionDiagnostics } from '../../../src/server/handlers/interaction-diagnostics.js'
+
+const device = { platform: 'android' as const, id: 'fixture' }
+await withEvidence({ journey: true }, async () => {
+  const child = await withEvidence({ action: true }, async () => {
+    await evidenceDispatch(device, async () => {})
+    return { success: true, dispatch_started: true, verification: { mode: 'light', status: 'observed' } }
+  })
+  const assertion = await withJourneyStepEvidence(() => captureEvidence('ui_tree', device, async () => ({ success: true, device, snapshot_session_id: 'snapshot', snapshot_revision: 2 })))
+  completeJourneyVerification(child.evidence.action_id!)
+  const steps = [{ id: 'tap', type: 'tap', status: 'passed', success: true, result: { ...child.result, evidence: child.evidence } },
+    { id: 'assert', type: 'assert', status: 'passed', success: true, result: assertion }]
+  refreshJourneyEvidence(steps)
+  assert.equal(observedState(steps[0].result.evidence, true).status, 'observed', 'following assertion supplies actual fresh evidence')
+  const response = finalizeCompactInteraction('run_journey', {}, wrapResponse({ success: true, steps }))
+  const compact = JSON.parse(response.content[0].text!)
+  const ref = compact.steps[0].result.diagnostics
+  const retained = interactionDiagnostics.lookup(ref.session_id, ref.result_id)
+  assert.equal(retained.success, true)
+  assert.equal(compact.steps[0].result.observed_state.status, 'observed')
+  // A later action invalidates the first tap and assertion summaries at finalization.
+  await withEvidence({ action: true }, () => evidenceDispatch(device, async () => {}))
+  refreshJourneyEvidence(steps)
+  assert.equal(observedState(steps[0].result.evidence, true).status, 'unknown')
+  assert.equal(observedState(steps[1].result.evidence).status, 'unknown')
+  const final = finalizeCompactInteraction('run_journey', {}, wrapResponse({ success: true, steps }))
+  const result = JSON.parse(final.content[0].text!)
+  assert.equal(result.steps[0].result.observed_state.freshness, 'stale')
+  assert.equal(result.steps[1].result.observed_state.freshness, 'stale')
+})
+const error = { ...wrapResponse({ error: { code: 'TRACE_NOT_FOUND', message: 'Original failure' } }), isError: true }
+finalizeCompactInteraction('run_journey', {}, error)
+assert.equal(error.isError, true)
+assert.equal(JSON.parse(error.content[0].text!).success, false)
+console.log('PASS shared journey observation, final supersession, child diagnostics and MCP error signalling')

package/test/unit/server/compact-review-regressions.test.ts

@@ -0,0 +1,78 @@
+import assert from 'node:assert/strict'
+import { handleToolCall } from '../../../src/server-core.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import { captureEvidence, withJourneyStepEvidence } from '../../../src/observe/evidence.js'
+import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
+import { runWithBudget, remainingBudget } from '../../../src/utils/operation-budget.js'
+import { finalizeCompactInteraction } from '../../../src/server/handlers/compact-interaction.js'
+import { wrapResponse } from '../../../src/server/common.js'
+
+const device = { platform: 'android' as const, id: 'fixture', model: 'Fixture', osVersion: '16', simulator: true }
+const originalWait = ToolsInteract.waitForUIHandler
+const decode = (response: Awaited<ReturnType<typeof handleToolCall>>) => JSON.parse(response.content[0].text!)
+const diagnostics = async (value: ReturnType<typeof decode>) => {
+  const response = decode(await handleToolCall('get_interaction_diagnostics', {
+    sessionId: value.diagnostics.session_id, resultId: value.diagnostics.result_id
+  }))
+  assert.equal(response.success, true)
+  return response.result
+}
+_setDeviceListersForTests({ listAndroidDevices: async () => [device] })
+try {
+  for (const responseMode of ['compact', 'debug']) for (const type of ['assert', 'wait']) for (const thrown of [true, false]) {
+    let reads = 0
+    ToolsInteract.waitForUIHandler = async () => {
+      reads++
+      await captureEvidence('ui_tree', device, async () => ({ device, snapshot_session_id: 'captured-before-timeout', snapshot_revision: 7 }))
+      if (thrown) return runWithBudget(0, async () => { remainingBudget(); throw new Error('unreachable') })
+      return { status: 'timeout', error: { code: 'TIMEOUT', message: 'returned timeout' }, observed: { matched_count: 0 } }
+    }
+    const result = decode(await handleToolCall('run_journey', { platform: 'android', deviceId: device.id, responseMode, steps: [
+      { id: 'fails', type, ...(type === 'assert' ? { assertion: { kind: 'element_visible', selector: { text: 'Ready' } } } : { selector: { text: 'Ready' } }) },
+      { id: 'later', type: 'wait', selector: { text: 'Later' } }
+    ] }))
+    assert.equal(result.success, false)
+    assert.equal(result.stopped_at_step_id, 'fails')
+    assert.equal(result.steps[1].status, 'not_run')
+    assert.equal(reads, 1, 'neither a failure nor diagnostics lookup replays the observation')
+    const step = responseMode === 'compact' ? await diagnostics(result.steps[0].result) : result.steps[0].result
+    if (thrown) {
+      assert.equal(step.failure_code, type === 'assert' ? 'ASSERTION_TIMEOUT' : 'STEP_FAILED')
+      assert.equal(step.error, 'ACTION_TIMEOUT')
+    } else if (type === 'assert') {
+      assert.equal(step.failure_code, 'ASSERTION_TIMEOUT')
+      assert.equal(step.reason, 'returned timeout')
+      assert.equal(step.observed.matched_count, 0)
+    } else {
+      assert.equal(step.status, 'timeout')
+      assert.deepEqual(step.error, { code: 'TIMEOUT', message: 'returned timeout' })
+    }
+    if (responseMode === 'compact') {
+      const observation = step.evidence.observations[0]
+      assert.equal(observation.kind, 'ui_tree')
+      assert.equal(observation.status, 'captured')
+      assert.equal(observation.snapshot_revision, 7)
+      assert.equal(observation.snapshot_session_id, 'captured-before-timeout')
+      assert.deepEqual(observation.device, { platform: device.platform, id: device.id })
+      const journey = await diagnostics(result)
+      assert.deepEqual(journey.steps[0].result.evidence, step.evidence, 'journey and child diagnostics retain the same final evidence')
+    } else assert.equal(step.evidence, undefined, 'debug step shape is unchanged')
+    assert.equal(reads, 1)
+  }
+} finally {
+  ToolsInteract.waitForUIHandler = originalWait
+  _resetDeviceListersForTests()
+}
+const originalError = new Error('outside evidence context')
+await assert.rejects(withJourneyStepEvidence(async () => { throw originalError }), error => error === originalError)
+for (const message of ['short error', 'a'.repeat(128), 'a'.repeat(129), '😀'.repeat(33)]) {
+  const response = finalizeCompactInteraction('run_journey', {}, wrapResponse({ error: { code: 'FIXTURE_ERROR', message } }))
+  const result = decode(response)
+  const shortened = Buffer.byteLength(message) > 128
+  assert.equal(result.truncated, shortened ? true : undefined)
+  assert.equal(result.error.code, 'FIXTURE_ERROR')
+  assert.ok(Buffer.byteLength(result.error.message) <= 128)
+  assert.ok(Buffer.byteLength(response.content[0].text!) < 1280, 'truncation must be marked even without overall budget pressure')
+  assert.equal((await diagnostics(result)).error.message, message)
+}
+console.log('PASS thrown journey evidence, returned-timeout/debug compatibility, and ASCII/multibyte journey error truncation')

package/test/unit/server/conditional_actions.test.ts

@@ -70,6 +70,9 @@ else process.exit(1)
   ToolsNetwork.notifyActionStart = () => { networkStarts++ }
   _setDeviceListersForTests({ listAndroidDevices: async () => [device()], listIOSDevices: async () => [device()] })
   const payload = (response: any) => JSON.parse(response.content[0].text)
+  const retained = async (result: any) => result.diagnostics
+    ? payload(await handleToolCall('get_interaction_diagnostics', { sessionId: result.diagnostics.session_id, resultId: result.diagnostics.result_id })).result
+    : result
   const nativeInputs = () => readFileSync(eventsPath, 'utf8').split('\n').filter(line => /shell input|ui tap|ui swipe/.test(line))
   const baseline = () => {
     uiState = 'Ready'; propertyChange = {}; observationMode = 'normal'; readDelay = 0
@@ -129,7 +132,8 @@ else process.exit(1)
         assert.equal(result.retryable, false)
         assert.equal(result.delivery_status, 'not_delivered')
         assert.equal(result.verification.status, 'not_requested')
-        assert.deepEqual(result.condition.observed.elements[0], tree().elements[0])
+        assert.deepEqual((await retained(result)).condition.observed.elements[0], tree().elements[0])
+        if (responseMode === 'compact') assert.equal(result.observed_state.status, 'unknown')
         assert.equal(reads, 1, 'no post-dispatch tree read after guard failure')
         assert.equal(nativeInputs().length, inputs)
         assert.equal(networkStarts, starts)
@@ -239,7 +243,7 @@ else process.exit(1)
       assert.equal(journey.stopped_at_step_id, 'guarded')
       assert.equal(journey.steps[0].status, 'passed')
       assert.equal(journey.steps[1].result.failure_code, 'PRECONDITION_FAILED')
-      assert.equal(journey.steps[1].result.condition.observed.elements[0].text, 'Changed')
+      assert.equal((await retained(journey.steps[1].result)).condition.observed.elements[0].text, 'Changed')
       assert.equal(journey.steps[1].result.verification.status, 'not_requested')
       assert.equal(journey.steps[2].status, 'not_run')
       assert.equal(nativeInputs().length, before)
@@ -268,7 +272,7 @@ else process.exit(1)
       const before = nativeInputs().length
       const mismatch = await call('tap', { expectedState })
       assert.equal(mismatch.failure_code, 'PRECONDITION_FAILED', JSON.stringify(mismatch))
-      assert.equal(mismatch.condition.observed.elements[0].text, 'Changed through native hierarchy')
+      assert.equal((await retained(mismatch)).condition.observed.elements[0].text, 'Changed through native hierarchy')
       assert.equal(nativeInputs().length, before)
       const compact: any = await ToolsObserve.getUITreeHandler({ platform, deviceId: 'fixture', responseMode: 'compact' })
       assert.equal(compact.snapshot_session_id, expectedState.snapshotSessionId)

package/test/unit/server/correlated-evidence.test.ts

@@ -59,7 +59,15 @@ else process.exit(1)
     if (platform === 'android') replace('collectGetCurrentScreen', async (id: string) => ({ device: device(platform, id), activity: 'FixtureActivity', package: 'fixture.app' }))
   }
   const payload = (r: any) => JSON.parse(r.content[0].text)
-  const call = async (name: string, args: Record<string, unknown>) => payload(await handleToolCall(name, args))
+  const call = async (name: string, args: Record<string, unknown>) => {
+    const value = payload(await handleToolCall(name, args))
+    if (name !== 'run_journey' && value.diagnostics?.available) {
+      const retained = payload(await handleToolCall('get_interaction_diagnostics', { sessionId: value.diagnostics.session_id, resultId: value.diagnostics.result_id }))
+      assert.equal(retained.success, true)
+      return { ...value, evidence: retained.result.evidence }
+    }
+    return value
+  }
   const refFor = (value: any) => ({ sessionId: value.evidence.session_id, actionId: value.evidence.action_id })
   try {
     for (const platform of ['android', 'ios'] as const) {
@@ -122,9 +130,11 @@ else process.exit(1)
       verificationMode: 'none', responseMode: 'compact', actionTimeoutMs: 500 })
     delete process.env.EVIDENCE_INPUT_SLOW
     assert.equal(timeout.failure_code, 'ACTION_TIMEOUT')
-    assert.ok(timeout.evidence.dispatch_started_at_ms)
-    assert.ok(timeout.evidence.dispatch_completed_at_ms)
-    assert.equal(timeout.evidence.verification_completed_at_ms, null)
+    const retainedTimeout = await call('get_interaction_diagnostics', { sessionId: timeout.diagnostics.session_id, resultId: timeout.diagnostics.result_id })
+    assert.equal(retainedTimeout.success, true)
+    assert.ok(retainedTimeout.result.evidence.dispatch_started_at_ms)
+    assert.ok(retainedTimeout.result.evidence.dispatch_completed_at_ms)
+    assert.equal(retainedTimeout.result.evidence.verification_completed_at_ms, null)
     const before = captureCount
     const malformed = await call('capture_screenshot', { platform: 'android', actionRef: { actionId: '' } })
     assert.match(malformed.error.message, /INVALID_ARGUMENT/)
@@ -149,9 +159,11 @@ else process.exit(1)
       ] })
     assert.equal(light.success, true)
     const lightStep = light.steps[0].result
-    assert.ok(lightStep.evidence.verification_completed_at_ms)
+    assert.equal(lightStep.observed_state.status, 'observed', JSON.stringify(lightStep))
+    const retainedLight = await call('get_interaction_diagnostics', { sessionId: lightStep.diagnostics.session_id, resultId: lightStep.diagnostics.result_id })
+    assert.ok(retainedLight.result.evidence.verification_completed_at_ms)
     const afterLight = await call('capture_screenshot', { platform: 'android', deviceId: 'fixture-android', actionRef: refFor(lightStep) })
-    assert.equal(afterLight.evidence.verification_completed_at_ms, lightStep.evidence.verification_completed_at_ms)
+    assert.equal(afterLight.evidence.verification_completed_at_ms, retainedLight.result.evidence.verification_completed_at_ms)
 
     const started = await call('start_log_stream', { platform: 'android', deviceId: 'other', sessionId: 'evidence-owned', packageName: 'fixture.app' })
     assert.equal(started.success, true)

package/test/unit/server/end-to-end-report.test.ts

@@ -0,0 +1,46 @@
+import assert from 'node:assert/strict'
+import { parseMetric, summarizeAttempts, unionDuration, observationOverhead, type Attempt } from '../../device/automated/latency/end-to-end-report.js'
+import { validObservation } from '../../device/automated/latency/end-to-end-session.js'
+
+assert.equal(unionDuration([{ stage: 'parent', start_ms: 1, end_ms: 10 }, { stage: 'nested', start_ms: 2, end_ms: 5 },
+  { stage: 'overlap', start_ms: 8, end_ms: 12 }], 11), 10)
+const attempts: Attempt[] = [
+  { case: 'full', iteration: 0, warmup: true, success: false, setup_ms: 1, requests: [] },
+  { case: 'full', iteration: 1, warmup: false, success: false, setup_ms: 1, requests: [] },
+  { case: 'full', iteration: 2, warmup: false, success: true, setup_ms: 500, requests: [
+    { tool: 'run_journey', elapsed_ms: 100, response_bytes: 50, success: true, tree: [], metrics: [
+      { event: 'latency_metric', request_id: 'opaque', tool: 'run_journey', handler_completed: true, elapsed_ms: 90,
+        spans: [{ stage: 'parent', start_ms: 0, end_ms: 80 }, { stage: 'child', start_ms: 10, end_ms: 70 }] }
+    ] }
+  ] },
+  { case: 'empty', iteration: 1, warmup: false, success: false, setup_ms: 0, requests: [] }
+]
+const report = summarizeAttempts(attempts)
+assert.equal(report.full.total_ms?.p50, 100)
+assert.equal(report.full.failures, 1)
+assert.equal(report.full.warmup_failures, 1)
+assert.equal(report.full.handler_unattributed_ms?.p50, 10)
+assert.equal(report.full.client_minus_handler_ms?.p50, 10)
+assert.equal(report.empty.total_ms, null)
+assert.equal(observationOverhead(attempts).tree.paired_on_minus_off_ms, null)
+const observation = (name: string, elapsed: number, success = true): Attempt => ({ case: name, iteration: 3, warmup: false,
+  success, setup_ms: 0, requests: [{ tool: 'get_ui_tree', elapsed_ms: elapsed, success, metrics: [], tree: [] }] })
+assert.equal(observationOverhead([observation('tree-on', 15), observation('tree-off', 20)]).tree.paired_on_minus_off_ms?.p50, -5)
+assert.equal(observationOverhead([observation('tree-on', 15), observation('tree-off', 20, false)]).tree.paired_on_minus_off_ms, null)
+assert.equal(parseMetric('secret stderr'), null)
+assert.equal(parseMetric('{"event":"latency_metric","tool":"tap","spans":[]}'), null)
+assert.equal(parseMetric('{"event":"unrecognized","secret":"credential"}'), null)
+const filtered = parseMetric(JSON.stringify({ event: 'latency_metric', tool: 'tap', request_id: 'opaque', handler_completed: true,
+  elapsed_ms: 10, arguments: { deviceId: 'private-device', text: 'secret' }, stdout: 'secret',
+  spans: [{ stage: 'dispatch_ms', start_ms: 0, end_ms: 8, secret: 'credential' }] }))
+assert.ok(filtered)
+assert.ok(!JSON.stringify(filtered).includes('secret'))
+assert.ok(!JSON.stringify(filtered).includes('private-device'))
+const tree = { device: { id: 'emulator-fixture' }, elements: [{}] }
+assert.equal(validObservation('get_ui_tree', tree, [], 'emulator-fixture'), true)
+assert.equal(validObservation('get_ui_tree', tree, [], 'other-device'), false)
+assert.equal(validObservation('get_ui_tree', {}, [], 'emulator-fixture'), false)
+assert.equal(validObservation('capture_screenshot', { device: { id: 'emulator-fixture' } }, [], 'emulator-fixture'), false)
+assert.equal(validObservation('capture_debug_snapshot', { raw: { ui_tree: tree, fingerprint_error: 'failed' } }, [], 'emulator-fixture'), false)
+assert.equal(validObservation('capture_debug_snapshot', { raw: { ui_tree: tree } }, [], 'emulator-fixture'), true)
+console.log('End-to-end benchmark accounting/privacy: PASS')

package/test/unit/server/input-device-readiness.test.ts

@@ -0,0 +1,55 @@
+import assert from 'node:assert/strict'
+import { handleToolCall } from '../../../src/server-core.js'
+import { AndroidInteract } from '../../../src/interact/android.js'
+import { _setDeviceListersForTests, _resetDeviceListersForTests, withResolvedDevice } from '../../../src/utils/resolve-device.js'
+import { withDeviceReadinessProbe } from '../../../src/observe/device-readiness.js'
+
+async function run() {
+  const physical = { platform: 'android', id: 'physical', model: 'Fixture', osVersion: '16', simulator: false }
+  const emulator = { ...physical, id: 'emulator', simulator: true }
+  const originalTap = AndroidInteract.prototype.tap, originalSwipe = AndroidInteract.prototype.swipe
+  let dispatched = '', dispatches = 0, resolutions = 0
+  _setDeviceListersForTests({ listAndroidDevices: async () => { resolutions++; return [emulator, physical] } })
+  AndroidInteract.prototype.tap = async (x, y, id) => {
+    dispatched = id!; dispatches++
+    return { success: true, device: id === physical.id ? physical : emulator, x, y }
+  }
+  AndroidInteract.prototype.swipe = async (x1, y1, x2, y2, duration, id) => {
+    dispatched = id!; dispatches++
+    return { success: true, device: id === physical.id ? physical : emulator, start: [x1, y1], end: [x2, y2], duration }
+  }
+  try {
+    for (const tool of ['tap', 'swipe']) {
+      for (const responseMode of ['compact', 'debug']) {
+        for (const explicit of [false, true]) {
+          const expected = explicit ? emulator.id : physical.id
+          const probes: string[] = []
+          const response = await withDeviceReadinessProbe(async (_cmd, args) => {
+            probes.push(args[1])
+            return { exitCode: 0, stderr: '', stdout: args.includes('power') ? 'mWakefulness=Asleep\nmWakefulnessChanging=false' : 'KeyguardServiceDelegate\n showing=false\n mIsShowing=false' }
+          }, () => handleToolCall(tool, { platform: 'android', ...(explicit ? { deviceId: emulator.id } : {}), x: 1, y: 2, x1: 1, y1: 2, x2: 3, y2: 4, duration: 100, verificationMode: 'none', responseMode }))
+          const result = JSON.parse(response.content[0].text!)
+          assert.equal(result.success, true)
+          assert.equal(dispatched, expected)
+          assert.deepEqual(probes, [expected, expected], 'readiness probes use the device actually selected for dispatch')
+          assert.deepEqual(result.device_readiness.blockers, ['DEVICE_ASLEEP'])
+        }
+      }
+    }
+    assert.equal(dispatches, 8)
+    assert.equal(resolutions, 8, 'readiness does not select another device')
+    const before = resolutions
+    await withResolvedDevice(emulator, () => withDeviceReadinessProbe(async (_cmd, args) => {
+      assert.equal(args[1], emulator.id)
+      return { exitCode: 0, stderr: '', stdout: '' }
+    }, () => handleToolCall('tap', { x: 1, y: 2, verificationMode: 'none', responseMode: 'compact' })))
+    assert.equal(dispatched, emulator.id, 'an existing resolved/guarded target is preserved')
+    assert.equal(resolutions, before)
+    console.log('PASS ordinary tap/swipe device readiness follows implicit, explicit and already-resolved targets')
+  } finally {
+    AndroidInteract.prototype.tap = originalTap
+    AndroidInteract.prototype.swipe = originalSwipe
+    _resetDeviceListersForTests()
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/server/interaction-diagnostics.test.ts

@@ -0,0 +1,45 @@
+import assert from 'node:assert/strict'
+import { randomUUID } from 'node:crypto'
+import { InteractionDiagnostics } from '../../../src/server/handlers/interaction-diagnostics.js'
+import { handleToolCall, toolDefinitions } from '../../../src/server-core.js'
+
+let now = 0
+const store = new InteractionDiagnostics(() => now)
+const value = { error: 'original private diagnostic', evidence: { observations: [1, 2] } }
+const ref = store.retain(value)
+assert.equal(ref.available, true)
+assert.deepEqual(store.lookup(ref.session_id, ref.result_id), { success: true, result: value })
+value.error = 'mutated'
+assert.notDeepEqual(store.lookup(ref.session_id, ref.result_id), { success: true, result: value })
+now = 599999
+assert.equal(store.lookup(ref.session_id, ref.result_id).success, true)
+now++
+assert.equal(store.lookup(ref.session_id, ref.result_id).error?.code, 'RESULT_UNAVAILABLE', 'reads do not extend expiry')
+assert.equal(store.lookup(randomUUID(), ref.result_id).error?.code, 'SESSION_MISMATCH')
+const oldest = store.retain({ n: 0 })
+for (let n = 1; n <= 100; n++) store.retain({ n })
+assert.equal(store.lookup(oldest.session_id, oldest.result_id).success, false)
+const large = store.retain('a'.repeat(1024 * 1024))
+assert.equal(large.available, false)
+assert.equal(large.reason, 'RESULT_TOO_LARGE')
+const byteStore = new InteractionDiagnostics()
+const first = byteStore.retain('a'.repeat(1024 * 1024 - 100))
+for (let n = 0; n < 16; n++) byteStore.retain('a'.repeat(1024 * 1024 - 100))
+assert.equal(byteStore.lookup(first.session_id, first.result_id).success, false, 'total byte limit evicts before count limit')
+const refs = await Promise.all(Array.from({ length: 30 }, async (_, n) => store.retain({ n })))
+assert.equal(new Set(refs.map(r => r.result_id)).size, 30)
+assert.ok(toolDefinitions.find(t => t.name === 'get_interaction_diagnostics')?.inputSchema.additionalProperties === false)
+for (const args of [{}, { sessionId: randomUUID(), resultId: randomUUID(), extra: true }, { sessionId: 'bad', resultId: randomUUID() }]) {
+  const response = await handleToolCall('get_interaction_diagnostics', args)
+  assert.equal(JSON.parse(response.content[0].text!).error.code, 'INVALID_ARGUMENT')
+}
+console.log('PASS diagnostics fidelity, expiry, count/byte bounds, size rejection, session isolation and strict dispatch schema')
+
+let expire: (() => void) | undefined
+let cancelled = 0
+const automatic = new InteractionDiagnostics(() => 0, randomUUID(), callback => { expire = callback; return () => { cancelled++ } })
+const automaticRef = automatic.retain({ original: true })
+assert(expire)
+expire()
+assert.equal(automatic.lookup(automaticRef.session_id, automaticRef.result_id).success, false, 'timer purges the payload without later cache access')
+assert.equal(cancelled, 1)

package/test/unit/server/owned-benchmark-transport.test.ts

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict'
+import { setTimeout as delay } from 'node:timers/promises'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { OwnedTransport } from '../../device/automated/latency/owned-transport.js'
+
+if (process.platform !== 'win32') {
+  // A stalled initialization with a stubborn child must time out, then both
+  // processes must be gone. This uses real processes, not mocked kill calls.
+  let childStarted = false
+  const transport = new OwnedTransport(process.env, chunk => { childStarted ||= chunk.includes('ready') }, ['-e', `
+    const {spawn}=require('node:child_process');
+    process.on('SIGTERM',()=>{});
+    const child=spawn(process.execPath,['-e', 'process.on("SIGTERM",()=>{}); setInterval(()=>{},1000)'],{stdio:'ignore'});
+    child.on('spawn',()=>process.stderr.write('ready\\n'));
+    setInterval(()=>{},1000);
+  `])
+  const client = new Client({ name: 'timeout-cleanup-test', version: '1' })
+  try { await assert.rejects(client.connect(transport, { timeout: 500 }), /timed out/i) }
+  finally { await transport.close() }
+  assert.equal(childStarted, true)
+  assert.equal(transport.cleanupVerified, true)
+  // Interrupting a pending call takes the same owned-group cleanup path.
+  const controller = new AbortController()
+  const interrupted = new OwnedTransport(process.env, () => {}, ['-e', 'process.stdin.resume(); setInterval(()=>{},1000)'])
+  const other = new Client({ name: 'interrupt-cleanup-test', version: '1' })
+  const pending = other.connect(interrupted, { timeout: 5000, signal: controller.signal })
+  await delay(50); controller.abort()
+  await assert.rejects(pending)
+  await interrupted.close()
+  assert.equal(interrupted.cleanupVerified, true)
+}
+console.log('Owned benchmark timeout/interrupt cleanup: PASS')

package/test/unit/server/readiness-retained-deadline.test.ts

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict'
+import { getAppReadiness } from '../../../src/observe/readiness-service.js'
+import { withDeviceReadinessProbe } from '../../../src/observe/device-readiness.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
+import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
+
+async function run() {
+  const original = ToolsObserve.getUITreeHandler
+  let samples = 0
+  _setDeviceListersForTests({ listAndroidDevices: async () => [{ id: 'fixture', platform: 'android', osVersion: '16', model: 'Fixture', simulator: true }] })
+  ToolsObserve.getUITreeHandler = async () => { assert.fail('inconclusive probes must not clear a known device blocker') }
+  try {
+    const result = await withDeviceReadinessProbe(async (_cmd, args) => {
+      if (args.includes('power')) samples++
+      if (samples > 1) throw new Error('probe unavailable')
+      return { exitCode: 0, stderr: '', stdout: args.includes('power') ? 'mWakefulness=Asleep\nmWakefulnessChanging=false' : 'KeyguardServiceDelegate\n showing=false\n mIsShowing=false' }
+    }, () => getAppReadiness({ platform: 'android', deviceId: 'fixture', timeoutMs: 300, pollIntervalMs: 100 }, true))
+    assert.ok(samples > 1, 'exercise a later inconclusive probe in the same wait')
+    assert.equal(result.success, false)
+    assert.equal(result.failure_code, 'READINESS_TIMEOUT')
+    assert.deepEqual(result.device_readiness.blockers, ['DEVICE_ASLEEP'])
+    assert.equal(result.device_readiness.input_ready, false)
+    assert.ok(result.device_readiness.evidence.some(item => item.code === 'DEVICE_ASLEEP'))
+    assert.ok(result.device_readiness.limitations.includes('DEVICE_POWER_OBSERVATION_FAILED'))
+    assert.ok(result.readiness.limitations.includes('DEADLINE_EXCEEDED'))
+    console.log('PASS readiness deadline retains the earlier blocker and later probe failure')
+  } finally {
+    ToolsObserve.getUITreeHandler = original
+    _resetDeviceListersForTests()
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })