mobile-debug-mcp 0.33.0 → 0.35.0

package/test/unit/debugger/diagnostics.test.ts

@@ -0,0 +1,80 @@
+import assert from 'node:assert/strict'
+import { mkdtemp, writeFile, rm } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { diagnostic, stages, reasons, classify, parseDiagnostic } from '../../../src/debugger/diagnostics.js'
+import { DebuggerError, JdiWorker, withDebuggerBudget, type WorkerEvent } from '../../../src/debugger/worker.js'
+import { parseWorkerMessage } from '../../../src/debugger/protocol.js'
+import { handleDebugger } from '../../../src/server/handlers/debugger-handlers.js'
+
+const secret = 'PRIVATE_LOCALS_TOKEN_/private/path'
+for (const stage of stages) for (const reason of reasons) {
+  const value = diagnostic(stage, reason)
+  assert.ok(Buffer.byteLength(JSON.stringify(value)) <= 512)
+  assert.ok(value.recovery.length <= 240 && /^[\x00-\x7f]*$/.test(value.recovery))
+  assert.deepEqual(Object.keys(value), ['stage', 'reason', 'recovery'])
+}
+assert.deepEqual(parseDiagnostic({ stage: 'attach', reason: 'connection_refused', recovery: secret, raw: secret }), diagnostic('attach', 'connection_refused'))
+assert.equal(classify(new Error(secret), 'attach', 'DEBUGGER_ATTACH_FAILED').diagnostic?.reason, 'unknown')
+assert.equal(classify(new DebuggerError('DEBUGGER_STALE_REFERENCE'), 'command', 'DEBUGGER_WORKER_FAILED').diagnostic, undefined)
+for (const hostile of [secret, { stage: secret, reason: 'unknown' }, { stage: 'attach', reason: secret }]) {
+  assert.throws(() => parseWorkerMessage({ id: 1, error: { code: 'DEBUGGER_WORKER_FAILED', diagnostic: hostile } }), /INVALID_WORKER_DIAGNOSTIC/)
+}
+assert.throws(() => parseWorkerMessage({ id: 1, error: { code: secret } }), /INVALID_WORKER_ERROR/)
+const cancelled = new AbortController(); cancelled.abort()
+const response = await handleDebugger('get_debugger_state', { debugSessionId: 'absent' }, cancelled.signal)
+assert.equal(response.isError, true)
+const payload = JSON.parse(response.content[0].text)
+assert.equal(payload.error.code, 'DEBUGGER_CANCELLED')
+assert.deepEqual(payload.error.diagnostic, diagnostic('unknown', 'cancelled'))
+assert.equal((await handleDebugger('get_debugger_state', {})).isError, true)
+
+const directory = await mkdtemp(path.join(os.tmpdir(), 'debugger-diagnostics-test-'))
+let index = 0
+async function worker(body: string, onEvent: (event: WorkerEvent) => void = () => {}) {
+  const file = path.join(directory, `worker-${index++}`)
+  await writeFile(file, `#!${process.execPath}\n${body}\n`, { mode: 0o700 })
+  return new JdiWorker(file, directory, onEvent)
+}
+async function fails(body: string, stage: string, reason: string) {
+  const w = await worker(body)
+  try {
+    await assert.rejects(w.call('attach', {}, 3000), (error: unknown) => {
+      assert.ok(error instanceof DebuggerError)
+      assert.equal(error.code, 'DEBUGGER_WORKER_FAILED')
+      assert.deepEqual(error.diagnostic, diagnostic(stage as typeof stages[number], reason as typeof reasons[number]))
+      assert.ok(!JSON.stringify(error).includes(secret))
+      return true
+    })
+  } finally { await w.close() }
+}
+try {
+  const missing = new JdiWorker(path.join(directory, 'missing'), directory, () => {})
+  try { await assert.rejects(missing.call('attach'), (e: unknown) => e instanceof DebuggerError && e.diagnostic?.reason === 'spawn_failed') } finally { await missing.close() }
+  await fails(`process.stderr.write(${JSON.stringify(secret)}); process.exit(7)`, 'worker_start', 'process_exited')
+  await fails(`process.stdout.write(${JSON.stringify(secret + '\n')}); setInterval(()=>{},1000)`, 'ipc', 'invalid_message')
+  await fails(`process.stdout.write('x'.repeat(1048577)+'\\n'); setInterval(()=>{},1000)`, 'ipc', 'message_limit')
+  const attach = await worker(`process.stdin.once('data', data => { const {id}=JSON.parse(data); console.log(JSON.stringify({id,error:{code:'DEBUGGER_WORKER_FAILED',diagnostic:{stage:'attach',reason:'connection_refused',raw:${JSON.stringify(secret)}}}})) })`)
+  try { await assert.rejects(attach.call('attach'), (e: unknown) => e instanceof DebuggerError && e.diagnostic?.reason === 'connection_refused') } finally { await attach.close() }
+  let ready = () => {}
+  const readyPromise = new Promise<void>(resolve => { ready = resolve })
+  const brokenPipe = await worker(`require('node:fs').closeSync(0); console.log(JSON.stringify({event:'ready'})); setInterval(()=>{},1000)`, () => ready())
+  try {
+    await readyPromise
+    await assert.rejects(brokenPipe.call('state'), (e: unknown) => e instanceof DebuggerError && e.diagnostic?.reason === 'write_failed')
+  } finally { await brokenPipe.close() }
+  const afterReply = await worker(`process.stdin.once('data',data=>{const {id}=JSON.parse(data); console.log(JSON.stringify({id,result:{}})); setTimeout(()=>process.exit(7),100)})`)
+  try {
+    await afterReply.call('state')
+    await assert.rejects(afterReply.call('state'), (e: unknown) => e instanceof DebuggerError && e.diagnostic?.stage === 'ipc' && e.diagnostic.reason === 'process_exited')
+  } finally { await afterReply.close() }
+  const idle = await worker('process.stdin.resume()')
+  try {
+    await assert.rejects(idle.call('stack', {}, 50), (e: unknown) => e instanceof DebuggerError && e.diagnostic?.stage === 'command' && e.diagnostic.reason === 'timeout')
+    const controller = new AbortController()
+    const call = withDebuggerBudget(1000, controller.signal, () => idle.call('attach'))
+    controller.abort()
+    await assert.rejects(call, (e: unknown) => e instanceof DebuggerError && e.diagnostic?.stage === 'attach' && e.diagnostic.reason === 'cancelled')
+  } finally { await idle.close() }
+} finally { await rm(directory, { recursive: true, force: true }) }
+console.log('PASS diagnostic bounds/privacy, strict IPC, real worker spawn/exit/malformed/oversize, attach failure, timeout/cancel and MCP wrapping')

package/test/unit/debugger/guards.test.ts

@@ -0,0 +1,50 @@
+import assert from 'node:assert/strict'
+import { debuggerSessions } from '../../../src/debugger/sessions.js'
+import { withDebuggerGuard, checkDebuggerGuard } from '../../../src/debugger/guard.js'
+import { handleToolCall } from '../../../src/server-core.js'
+import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import { getAppReadiness } from '../../../src/observe/readiness-service.js'
+const originalPause = debuggerSessions.paused
+const originalActive = debuggerSessions.hasActiveSessions
+const originalTree = ToolsObserve.getUITreeHandler
+const originalWait = ToolsInteract.waitForUIHandler
+let paused = true
+const pause: any = { debug_session_id: 'session', target: { app_id: 'test.app', pid: 10 }, state: 'paused', captured_at_ms: 1000 }
+debuggerSessions.paused = device => paused && device === 'fixture' ? pause : null
+debuggerSessions.hasActiveSessions = () => true
+_setDeviceListersForTests({ listAndroidDevices: async () => [{ id: 'fixture', platform: 'android' } as any] })
+const payload = (response: any) => JSON.parse(response.content.find((c: any) => c.type === 'text').text)
+try {
+  ToolsObserve.getUITreeHandler = async () => { throw new Error('Paused readiness must not acquire a UI tree') }
+  const readiness = await getAppReadiness({ platform: 'android', deviceId: 'fixture' })
+  assert.equal(readiness.readiness.state, 'debugger_paused')
+  const wait = await getAppReadiness({ platform: 'android', deviceId: 'fixture' }, true)
+  assert.equal(wait.failure_code, 'DEBUGGER_PAUSED')
+  const blocked = payload(await handleToolCall('tap', { platform: 'android', deviceId: 'fixture', x: 1, y: 1 }))
+  assert.equal(blocked.delivery_status, 'not_delivered')
+  await withDebuggerGuard('android', 'other', async () => checkDebuggerGuard(true))
+  await assert.rejects(withDebuggerGuard('android', 'fixture', async () => checkDebuggerGuard()), /DEBUGGER_PAUSED/)
+  paused = false
+  let calls = 0
+  ToolsInteract.waitForUIHandler = async () => { calls++; if (calls === 2) paused = true; return { status: 'success' } as any }
+  const journey = payload(await handleToolCall('run_journey', { platform: 'android', deviceId: 'fixture', responseMode: 'compact', steps: [
+    { id: 'first', type: 'wait', selector: { text: 'First' } },
+    { id: 'second', type: 'wait', selector: { text: 'Second' } },
+    { id: 'third', type: 'wait', selector: { text: 'Third' } }
+  ] }))
+  assert.equal(journey.steps[0].status, 'passed', 'completed steps survive a later pause')
+  assert.equal(journey.steps[1].success, false)
+  assert.equal(journey.steps[1].result.failure_code, 'DEBUGGER_PAUSED')
+  assert.equal(calls, 2, 'no action queued or retried after pause')
+  _setDeviceListersForTests({ listAndroidDevices: async () => { throw new Error('resolution unavailable') } })
+  const failedResolution = payload(await handleToolCall('tap', { platform: 'android', deviceId: 'fixture', x: 1, y: 1 }))
+  assert.equal(failedResolution.error.tool, 'tap')
+  assert.match(failedResolution.error.message, /resolution unavailable/, 'resolution errors retain the MCP error envelope')
+  console.log('PASS debugger readiness without UI acquisition, device scoping, dispatch guard, mid-journey pause preservation')
+} finally {
+  debuggerSessions.paused = originalPause; debuggerSessions.hasActiveSessions = originalActive
+  ToolsObserve.getUITreeHandler = originalTree; ToolsInteract.waitForUIHandler = originalWait
+  _resetDeviceListersForTests()
+}

package/test/unit/debugger/native.test.ts

@@ -0,0 +1,33 @@
+import assert from 'node:assert/strict'
+import { AndroidDebugNative } from '../../../src/debugger/android.js'
+import { DebuggerError, debuggerRemaining, withDebuggerBudget } from '../../../src/debugger/worker.js'
+class Native extends AndroidDebugNative {
+  calls: string[][] = []
+  forwards = 'device tcp:1234 jdwp:10\nother tcp:3456 jdwp:20'
+  async adb(_device: string, args: string[]) {
+    this.calls.push(args)
+    if (args[0] === 'forward' && args[1] === '--list') return this.forwards
+    if (args.at(-1)?.endsWith('/stat')) return '10 (complex process name) S ' + Array(18).fill('0').join(' ') + ' 999 0'
+    if (args.at(-1)?.endsWith('/status')) return 'Name:\ttest\nUid:\t42\t42\t42\t42'
+    if (args.at(-1)?.endsWith('/cmdline')) return 'test.app\0'
+    return ''
+  }
+}
+const native = new Native()
+await native.removeForward('device', 1234, 10)
+assert.deepEqual(native.calls.at(-1), ['forward', '--remove', 'tcp:1234'])
+await assert.rejects(native.removeForward('device', 3456, 10), /DEBUGGER_CLEANUP_FAILED/)
+const before = native.calls.length
+await native.removeForward('device', 9999, 10)
+assert.equal(native.calls.length, before + 1, 'absent owned forward requires no removal')
+const target = { app_id: 'test.app', pid: 10, process_name: 'test.app', start_identity: '', uid: 42 }
+assert.equal((await native.identity('device', target)).start_identity, '999')
+await assert.rejects(native.identity('device', { ...target, start_identity: 'old' }), /PROCESS_CHANGED/)
+await assert.rejects(native.identity('device', { ...target, uid: 44 }), /PROCESS_CHANGED/)
+await assert.rejects(native.candidates('device', 'test.app;evil'), /INVALID_ARGUMENT/)
+const aborted = new AbortController(); aborted.abort()
+await assert.rejects(withDebuggerBudget(100, aborted.signal, async () => debuggerRemaining(10)), /DEBUGGER_CANCELLED/)
+await assert.rejects(withDebuggerBudget(-1, undefined, async () => debuggerRemaining(10)), /DEBUGGER_TIMEOUT/)
+assert.equal(await withDebuggerBudget(100, undefined, async () => debuggerRemaining(10)), 10)
+assert.equal(new DebuggerError('DEBUGGER_TIMEOUT').code, 'DEBUGGER_TIMEOUT')
+console.log('PASS debugger native identity, PID reuse, forward ownership, deadlines and cancellation')

package/test/unit/debugger/preparation.test.ts

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+const exec = promisify(execFile)
+const directory = await mkdtemp(path.join(os.tmpdir(), 'debugger-fake-jdk-'))
+const secret = 'SECRET_COMPILER_OUTPUT'
+const run = async () => {
+  const code = `import {prepareWorker} from './src/debugger/worker.ts'; try {await prepareWorker(); process.exitCode=1} catch(e) {console.log(JSON.stringify({code:e.code,diagnostic:e.diagnostic}))}`
+  const { stdout, stderr } = await exec(process.execPath, ['--import', 'tsx', '--input-type=module', '-e', code], {
+    env: { ...process.env, ANDROID_STUDIO_JDK: directory }, timeout: 10000
+  })
+  assert.ok(!stdout.includes(secret)); assert.ok(!stderr.includes(secret))
+  return JSON.parse(stdout)
+}
+try {
+  await mkdir(path.join(directory, 'bin'))
+  const java = path.join(directory, 'bin', 'java')
+  await writeFile(java, `#!${process.execPath}\nconsole.error('openjdk version "17.0.1"');`, { mode: 0o700 })
+  await writeFile(path.join(directory, 'bin', 'javac'), `#!${process.execPath}\nconsole.error('${secret}');process.exit(1)`, { mode: 0o700 })
+  const compile = await run()
+  assert.equal(compile.code, 'DEBUGGER_UNSUPPORTED')
+  assert.equal(compile.diagnostic.stage, 'compilation'); assert.equal(compile.diagnostic.reason, 'operation_failed')
+  // Discovery succeeds; the actual bounded version subprocess then fails.
+  await writeFile(java, `#!${process.execPath}\nconst fs=require('node:fs');const marker=${JSON.stringify(path.join(directory, 'seen'))};if(fs.existsSync(marker)){console.error('${secret}');process.exit(1)}fs.writeFileSync(marker,'');console.error('openjdk version "17.0.1"');`, { mode: 0o700 })
+  const prerequisite = await run()
+  assert.equal(prerequisite.code, 'DEBUGGER_ATTACH_FAILED')
+  assert.equal(prerequisite.diagnostic.stage, 'prerequisite'); assert.equal(prerequisite.diagnostic.reason, 'unavailable')
+} finally { await rm(directory, { recursive: true, force: true }) }
+console.log('PASS isolated fake-JDK compilation/prerequisite classification without compiler output leakage')

package/test/unit/debugger/protocol.test.ts

@@ -0,0 +1,15 @@
+import assert from 'node:assert/strict'
+import { parseWorkerMessage } from '../../../src/debugger/protocol.js'
+
+const event = { event: 'stopped', stop_id: 'stop-1', thread_id: 'thread-1', stops: [] }
+assert.deepEqual(parseWorkerMessage(event), { kind: 'event', value: event })
+assert.deepEqual(parseWorkerMessage({ id: 1, result: { locals: [] } }), { kind: 'reply', id: 1, result: { locals: [] } })
+assert.deepEqual(parseWorkerMessage({ id: 2, error: { code: 'DEBUGGER_STALE_REFERENCE' } }), {
+  kind: 'reply', id: 2, result: {}, error: { code: 'DEBUGGER_STALE_REFERENCE' }
+})
+for (const invalid of [null, [], { event: 42 }, { event: 'stopped', stop_id: 42 },
+  { id: '1', result: {} }, { id: -1, result: {} }, { id: 1.2, result: {} },
+  { id: 1, result: 'private-debuggee-value' }, { id: 1, error: { code: 42 } }]) {
+  assert.throws(() => parseWorkerMessage(invalid), /^Error: INVALID_WORKER_/, 'malformed worker input is rejected without exposing its contents')
+}
+console.log('PASS validated worker events/replies and content-free protocol errors')

package/test/unit/debugger/sessions.test.ts

@@ -0,0 +1,83 @@
+import assert from 'node:assert/strict'
+import { DebuggerSessions, debuggerExpiry } from '../../../src/debugger/sessions.js'
+import { DebuggerError, type WorkerEvent } from '../../../src/debugger/worker.js'
+import type { DebugNative, DebugTarget } from '../../../src/debugger/android.js'
+import { debuggerContracts, debuggerTools } from '../../../src/server/schemas/debugger-schema.js'
+assert.equal(debuggerExpiry(0, 0, 0, 59999), null)
+assert.equal(debuggerExpiry(0, 60000, 0, 60000), 'pause_limit', 'polling cannot extend pause expiry')
+assert.equal(debuggerExpiry(0, 0, undefined, 300000), 'idle_limit')
+assert.equal(debuggerExpiry(0, 1800000, undefined, 1800000), 'session_limit', 'activity cannot extend lifetime')
+const target: DebugTarget = { app_id: 'test.app', pid: 123, uid: 456, process_name: 'test.app', start_identity: '100' }
+let candidates = [target]
+let removed = 0
+let emit: (event: WorkerEvent) => void = () => {}
+let close = 0
+let failCleanup = false
+let failCommand = ''
+const native: DebugNative = {
+  candidates: async () => candidates, identity: async () => target, forward: async () => 12345,
+  removeForward: async () => { if (failCleanup) throw new Error('offline'); removed++ }
+}
+const sessions = new DebuggerSessions(native, async event => {
+  emit = event
+  return { call: async (command: string) => { if (command === failCommand) throw new DebuggerError('DEBUGGER_TIMEOUT'); return { state: 'running', breakpoints: [] } }, close: async () => { close++ } }
+}, async () => ({ java: 'java', directory: '/unused' }))
+try {
+  candidates = [target, { ...target, pid: 124 }]
+  const ambiguous = await sessions.attach('emulator', 'test.app')
+  assert.equal(ambiguous.error.code, 'PROCESS_AMBIGUOUS')
+  assert.equal(removed, 0)
+  candidates = [target]
+  const first = await sessions.attach('emulator', 'test.app')
+  const id = first.debug_session_id
+  assert.equal(first.state, 'running')
+  await assert.rejects(sessions.attach('emulator', 'test.app'), /DEBUGGER_BUSY/)
+  emit({ event: 'stopped', stop_id: 'stop-1', thread_id: 't1', stops: [] })
+  assert.equal(sessions.paused('emulator')?.stop.stop_id, 'stop-1')
+  assert.equal(sessions.paused('other'), null)
+  assert.throws(() => sessions.assertRunning('emulator'), /DEBUGGER_PAUSED/)
+  const pendingWait = sessions.command(id, 'events', { afterSequence: 1 }, 500)
+  await sessions.command(id, 'resume', { stopId: 'stop-1' })
+  assert.equal(sessions.paused('emulator'), null)
+  await assert.rejects(sessions.command(id, 'locals', { stopId: 'stop-1', frameId: 'old' }), /DEBUGGER_STALE_REFERENCE/)
+  emit({ event: 'stopped', stop_id: 'stop-2', thread_id: 't2' })
+  assert.equal((await pendingWait).events[0].stop_id, 'stop-2', 'event wait cannot block resume')
+  for (let i = 0; i < 260; i++) emit({ event: 'breakpoint', i })
+  const events = await sessions.command(id, 'events', { afterSequence: 0 }, 100)
+  assert.equal(events.overflow, true); assert.equal(events.events.length, 100)
+  await assert.rejects(sessions.command(id, 'events', { afterSequence: 9999 }, 100), /INVALID_ARGUMENT/)
+  const controller = new AbortController(); controller.abort()
+  await assert.rejects(sessions.command(id, 'events', { afterSequence: 262, signal: controller.signal }, 100), /DEBUGGER_CANCELLED/)
+  failCommand = 'locals'
+  await assert.rejects(sessions.command(id, 'locals', { stopId: 'stop-2' }, 100), /DEBUGGER_TIMEOUT/)
+  assert.equal(sessions.paused('emulator')?.state, 'paused', 'inspection timeout preserves known suspension')
+  failCommand = 'step'
+  await assert.rejects(sessions.command(id, 'step', { stopId: 'stop-2', threadId: 't2' }, 100), /DEBUGGER_TIMEOUT/)
+  assert.equal((await sessions.command(id, 'state')).cleanup.status, 'complete')
+  assert.equal(close, 1); assert.equal(removed, 1)
+  failCommand = ''
+  const second = await sessions.attach('emulator', 'test.app')
+  failCleanup = true
+  const partial = await sessions.command(second.debug_session_id, 'detach')
+  assert.equal(partial.success, false); assert.equal(partial.cleanup.status, 'failed')
+  await assert.rejects(sessions.attach('emulator', 'test.app'), /DEBUGGER_BUSY/)
+  failCleanup = false
+  const retry = await sessions.command(second.debug_session_id, 'detach')
+  assert.equal(retry.cleanup.status, 'complete'); assert.equal(close, 2)
+  assert.equal((await sessions.command(second.debug_session_id, 'detach')).cleanup.status, 'complete')
+  const third = await sessions.attach('emulator', 'test.app')
+  emit({ event: 'worker_failed' })
+  const crashed = await sessions.command(third.debug_session_id, 'state')
+  assert.equal(crashed.state, 'failed')
+  assert.equal(crashed.cleanup.status, 'complete')
+  assert.equal(crashed.error.code, 'DEBUGGER_WORKER_FAILED')
+  assert.equal(sessions.paused('emulator'), null)
+  for (const tool of debuggerTools) {
+    const contract = debuggerContracts[tool.name]
+    assert.equal(tool.inputSchema.additionalProperties, false)
+    assert.equal(contract.schema.safeParse({ ...Object.fromEntries(tool.inputSchema.required.map(k => [k, 'x'])), unexpected: true }).success, false)
+  }
+  assert.equal(debuggerContracts.attach_debugger.schema.safeParse({ platform: 'android', appId: 'test.app' }).success, false)
+  assert.equal(debuggerContracts.set_debugger_breakpoint.schema.safeParse({ debugSessionId: 's', className: '$(bad)', line: 2 }).success, false)
+  console.log('PASS debugger session ownership, stop epochs, event concurrency/overflow, timeout recovery, cleanup retries, strict contracts')
+} finally { await sessions.shutdown() }

package/test/unit/interact/adjustment_service.test.ts

@@ -0,0 +1,42 @@
+import assert from 'node:assert/strict'
+import { adjustControl } from '../../../src/interact/adjustment/adjustment.js'
+import type { AdjustmentDependencies } from '../../../src/interact/adjustment/adjustment-context.js'
+import type { ActionTargetResolved, DeviceInfo } from '../../../src/types.js'
+import type { UiElement } from '../../../src/interact/model.js'
+
+const device: DeviceInfo = { platform: 'android', id: 'fixture', model: 'fixture', osVersion: 'fixture', simulator: true }
+let value = 10
+const calls: string[] = []
+const element = (): UiElement => ({ visible: true, enabled: true, role: 'slider', stable_id: 'duration', bounds: [0, 0, 300, 40],
+  state: { value, value_range: { min: 0, max: 100 } }, actions: ['set_value'] })
+const handle = { elementId: 'handle', platform: 'android' as const, deviceId: device.id, bounds: [0, 0, 300, 40] as [number, number, number, number], index: 0, stable_id: 'duration' }
+const target = (): ActionTargetResolved => ({ elementId: 'handle', text: null, resource_id: null, accessibility_id: null, class: 'Slider', bounds: handle.bounds, index: 0 })
+const deps: AdjustmentDependencies = {
+  observe: async () => ({ device, elements: [element()] }), fingerprint: async () => 'fingerprint',
+  getHandle: () => handle, currentHandle: () => ({ el: element(), index: 0 }), target,
+  wait: async () => { throw new Error('handle targeting must not use selector waits') },
+  find: async () => { throw new Error('handle targeting must not use semantic search') },
+  expectState: async input => {
+    calls.push('verify')
+    return { success: true, element_id: 'handle', expected_state: { property: input.property, expected: input.expected },
+      observed_state: { property: input.property, value }, trace: { action_id: 'assertion', steps: [], final_outcome: 'success', attempts: 1 } }
+  },
+  service: async () => ({ resolved: { id: device.id }, interact: { setAdjustableValue: async () => { calls.push('semantic'); return { success: false } } } }),
+  tap: async () => { calls.push('coordinate'); value = 20; return { success: true, device } },
+  swipe: async () => { throw new Error('a converged coordinate adjustment must not dispatch a gesture') }
+}
+const already = await adjustControl({ element_id: 'handle', targetValue: 10 }, deps)
+assert.equal(already.success, true)
+assert.equal(already.attempts, 0)
+assert.deepEqual(calls, [])
+const adjusted = await adjustControl({ element_id: 'handle', targetValue: 20 }, deps)
+assert.equal(adjusted.success, true)
+assert.equal(adjusted.attempts, 2)
+assert.equal(adjusted.adjustment_mode, 'coordinate')
+assert.deepEqual(calls, ['semantic', 'coordinate', 'verify'], 'failed direct capability falls back in the established order')
+calls.length = 0
+const stale = await adjustControl({ element_id: 'missing', targetValue: 20 }, { ...deps, getHandle: () => undefined })
+assert.equal(stale.success, false)
+assert.equal(stale.failure_code, 'STALE_REFERENCE')
+assert.deepEqual(calls, [], 'missing handles cannot dispatch native input')
+console.log('PASS injected adjustment service: read-only convergence, strategy order, attempt accounting and stale-handle rejection')

package/test/unit/interact/adjustment_verification.test.ts

@@ -0,0 +1,35 @@
+import assert from 'node:assert/strict'
+import type { ExpectStateResponse } from '../../../src/types.js'
+import { verifyAdjustment, type AdjustmentVerificationInput } from '../../../src/interact/adjustment/adjustment-verification.js'
+
+const input: AdjustmentVerificationInput = {
+  labeled: false, currentEl: { state: { value: 10 } },
+  actualState: { property: 'value', value: 10 }, property: 'value', target: 20, tolerance: 0.5,
+  expectation: { element_id: 'control', property: 'value', expected: 20, platform: 'android', deviceId: 'fixture' }
+}
+let observations = 0
+let assertions = 0
+const verified = await verifyAdjustment(input, {
+  observe: async () => { throw new Error('ordinary verification must use the assertion boundary') },
+  expectState: async args => {
+    assertions++
+    assert.equal(args.element_id, 'control')
+    return { success: false, observed_state: { value: 20.25 }, reason: 'exact comparison failed' } as ExpectStateResponse
+  }
+})
+assert.equal(assertions, 1)
+assert.equal(verified.withinTolerance, true, 'numeric tolerance is independent of exact assertion success')
+assert.equal(verified.observedState?.value, 20.25)
+const stale = await verifyAdjustment({ ...input, labeled: true, actualState: { property: 'value', value: 20 } }, {
+  observe: async () => { observations++; return { elements: [] } },
+  expectState: async () => { throw new Error('label verification must acquire a new tree') }
+})
+assert.equal(observations, 1)
+assert.equal(stale.withinTolerance, false, 'fallback state must not establish fresh convergence')
+assert.equal(stale.verification.success, false)
+assert.equal(stale.observedState?.value, 20, 'last readable state remains available for diagnostics')
+await assert.rejects(verifyAdjustment(input, {
+  observe: async () => null,
+  expectState: async () => { throw new Error('ACTION_TIMEOUT') }
+}), /ACTION_TIMEOUT/, 'timeouts propagate without manufacturing an observation')
+console.log('PASS adjustment verification dependencies, tolerance, freshness and timeout preservation')

package/test/unit/interact/clock_dependencies.test.ts

@@ -0,0 +1,63 @@
+import assert from 'node:assert/strict'
+import type { Clock } from '../../../src/runtime/clock.js'
+import type { UiTree } from '../../../src/interact/observation.js'
+import { waitForUI } from '../../../src/interact/waits/ui-wait.js'
+import { waitForScreenChange } from '../../../src/interact/waits/screen-wait.js'
+import { findElement } from '../../../src/interact/targeting/find-element.js'
+import { expectState } from '../../../src/interact/assertions/state-assertion.js'
+import { _resolvedTargetFromElement } from '../../../src/interact/targeting/element-helpers.js'
+
+function fakeClock() {
+  let now = 1000
+  const delays: number[] = []
+  const clock: Clock = { now: () => now, sleep: async ms => { delays.push(ms); now += ms } }
+  return { clock, delays }
+}
+const resolve = (_platform: string, _device: string | undefined, element: NonNullable<UiTree['elements']>[number], index: number) => _resolvedTargetFromElement('test-id', element, index)
+const present = (clock: Clock): UiTree => ({ captured_at_ms: clock.now(), elements: [{ text: 'Button', state: { enabled: true } }] })
+
+{
+  const { clock, delays } = fakeClock()
+  const result = await waitForUI({ selector: { text: 'Button' }, timeout_ms: 500, poll_interval_ms: 50 }, {
+    clock, observe: async () => present(clock), resolve
+  })
+  assert.equal(result?.status, 'success')
+  assert.deepEqual(result?.metrics, { latency_ms: 50, poll_count: 2, attempts: 1 })
+  assert.deepEqual(delays, [50])
+}
+{
+  const { clock, delays } = fakeClock()
+  const result = await waitForUI({ selector: { text: 'missing' }, timeout_ms: 100, poll_interval_ms: 50,
+    retry: { max_attempts: 2, backoff_ms: 20 } }, { clock, observe: async () => ({ elements: [] }), resolve })
+  assert.equal(result?.status, 'timeout')
+  assert.deepEqual(result?.metrics, { latency_ms: 320, poll_count: 6, attempts: 2 })
+  assert.deepEqual(delays, [50, 50, 50, 20, 50, 50, 50])
+}
+{
+  const { clock, delays } = fakeClock()
+  let samples = 0
+  const result = await waitForScreenChange({ previousFingerprint: 'old', timeoutMs: 500, pollIntervalMs: 50 }, {
+    clock, fingerprint: async () => ({ fingerprint: samples++ === 0 ? 'old' : 'new' })
+  })
+  assert.equal(result.success, true)
+  assert.equal(result.elapsedMs, 100)
+  assert.deepEqual(delays, [50, 50])
+}
+{
+  const { clock, delays } = fakeClock()
+  const result = await findElement({ query: 'missing', timeoutMs: 200 }, async () => ({ elements: [] }), clock)
+  assert.equal(result.found, false)
+  assert.deepEqual(delays, [100, 100, 100])
+}
+{
+  const { clock, delays } = fakeClock()
+  const result = await expectState({ selector: { text: 'Button' }, property: 'enabled', expected: true }, {
+    clock, observe: async () => present(clock), getHandle: () => undefined,
+    currentHandle: () => null, target: (platform, device, match) => resolve(platform, device, match.el, match.idx)
+  })
+  assert.equal(result.success, true)
+  assert.equal(result.stabilization_window_ms, 150)
+  assert.deepEqual(delays, [150])
+  assert(result.trace.steps.every(step => step.timestamp >= 1000 && step.timestamp <= 1150))
+}
+console.log('PASS injected clocks: wait stability, retry/backoff deadlines, screen confirmation, search expiry and state trace timestamps without global timer replacement')

package/test/unit/interact/element_helpers.test.ts

@@ -0,0 +1,19 @@
+import assert from 'node:assert/strict'
+import { _matchesSelector, _resolveActionableAncestor, _normalizeBounds } from '../../../src/interact/targeting/element-helpers.js'
+import { _readNumericControlRange, _quantizeTargetValue } from '../../../src/interact/adjustment/control-values.js'
+
+assert(_matchesSelector({ text: 'Save', resourceId: 'app:id/save' }, { text: 'save', resource_id: 'app:id/save' }))
+assert(!_matchesSelector({ text: 'Save', resourceId: 'app:id/other' }, { text: 'save', resource_id: 'app:id/save' }), 'all supplied selector fields constrain selection')
+assert(_matchesSelector({ contentDesc: 'Save changes' }, { accessibility_id: 'changes', contains: true }))
+assert(!_matchesSelector({ text: 'Save' }, undefined))
+assert.deepEqual(_normalizeBounds(['1', 2, 3, 4]), [1, 2, 3, 4])
+assert.equal(_normalizeBounds([1, 'invalid', 3, 4]), null)
+const elements = [
+  { id: 'parent', clickable: true, bounds: [0, 0, 100, 100] },
+  { parentId: 'parent', text: 'Save', bounds: [20, 20, 40, 40] }
+]
+assert.deepEqual(_resolveActionableAncestor(elements, { el: elements[1], idx: 1 }), { el: elements[0], idx: 0 })
+assert.deepEqual(_readNumericControlRange({ state: { value: '3 of 10' } }), { min: 0, max: 10 })
+assert.equal(_readNumericControlRange({ state: { value_range: { min: 10, max: 0 } } }), null)
+assert.equal(_quantizeTargetValue(0.26, 0, 1, 0.1), 0.3)
+console.log('PASS injected-free selector, actionable ancestor, numeric range and snapping helpers')

package/test/unit/interact/legacy_wait_service.test.ts

@@ -0,0 +1,17 @@
+import assert from 'node:assert/strict'
+import { waitForUICore } from '../../../src/interact/waits/legacy-wait.js'
+import type { LegacyWaitDependencies } from '../../../src/interact/waits/legacy-wait-state.js'
+
+const calls: string[] = []
+const deps: LegacyWaitDependencies = {
+  fingerprint: async () => { calls.push('fingerprint'); return { fingerprint: 'initial' } },
+  logs: async () => { calls.push('logs'); return { logs: ['before'] } },
+  stream: async () => { calls.push('stream'); return { entries: [{ message: 'operation done' }] } },
+  find: async () => { throw new Error('log waits must not search UI elements') },
+  snapshot: async () => { throw new Error('successful waits must not collect failure snapshots') }
+}
+const result = await waitForUICore({ type: 'log', query: 'done', timeoutMs: 1000 }, deps)
+assert.equal(result.success, true)
+assert.equal(result.observed_state, true)
+assert.deepEqual(calls, ['fingerprint', 'logs', 'stream'])
+console.log('PASS injected legacy wait: baseline collection, stream-first matching and no failure snapshot')

package/test/unit/interact/state_comparison.test.ts

@@ -0,0 +1,20 @@
+import assert from 'node:assert/strict'
+import { compareReadableState } from '../../../src/interact/assertions/state-comparison.js'
+
+assert.equal(compareReadableState('checked', true, { checked: true }).success, true)
+const invalidBoolean = compareReadableState('checked', 'true', { checked: true })
+assert.equal(invalidBoolean.success, false)
+assert.equal(invalidBoolean.reason, 'expected checked must be boolean')
+assert.equal(invalidBoolean.observedValue, true)
+assert.equal(invalidBoolean.rawValue, null)
+assert.equal(compareReadableState('value', 20, { value: '20' }).success, false, 'numeric assertions do not coerce readable strings')
+assert.equal(compareReadableState('value', '20', { value: '20' }).success, true)
+assert.equal(compareReadableState('selected', { id: 'dark' }, { selected: { id: 'dark', label: 'Dark' } }).success, true)
+assert.equal(compareReadableState('selected', false, { selected: false }).success, true)
+assert.equal(compareReadableState('selected', true, { selected: 'true' }).reason, 'selected state is not boolean')
+assert.equal(compareReadableState('text_value', '', { text_value: '' }).reason, 'expected text_value must be string')
+assert.equal(compareReadableState('value', 20, null).reason, 'value state unavailable')
+const range = { min: 0, max: 20 }
+assert.equal(compareReadableState('value_range', range, { value_range: range }).success, true, 'fallback comparison preserves reference equality')
+assert.equal(compareReadableState('value_range', { min: 0, max: 20 }, { value_range: range }).success, false)
+console.log('PASS readable-state comparison compatibility without UI or global mocks')

package/test/unit/interact/target_scope.test.ts

@@ -0,0 +1,35 @@
+import assert from 'node:assert/strict'
+import { ResolvedElements } from '../../../src/interact/targeting/resolved-elements.js'
+import { findScopedElement, resolveUiChangeScope } from '../../../src/interact/targeting/target-scope.js'
+import type { ResolvedUiElementContext } from '../../../src/interact/model.js'
+
+const store = new ResolvedElements(2)
+const context = (id: string): ResolvedUiElementContext => ({
+  elementId: id, platform: 'android', deviceId: 'fixture', bounds: null, index: 0, stable_id: id
+})
+store.remember('one', context('one'))
+store.remember('two', context('two'))
+store.remember('one', context('one'))
+store.remember('three', context('three'))
+assert.equal(store.get('two'), undefined, 'oldest handle is evicted; refresh updates insertion order')
+assert(store.get('one'))
+const tree = { elements: [{ text: 'Root', stable_id: 'one', children: [1] }, { text: 'Child', parentId: 0 }] }
+const match = findScopedElement(tree, 'one', store)
+assert.equal(match?.index, 0)
+assert.equal(match?.reason, 'stable_id_match')
+let calls = 0
+const subtree = resolveUiChangeScope(tree, 'subtree', 'custom-handle', (_tree, id) => {
+  calls++
+  assert.equal(id, 'custom-handle')
+  return { index: 0, stableId: 'one', reason: 'injected_lookup' }
+})
+assert.equal(calls, 1)
+assert.equal(subtree.elements.length, 2)
+assert.equal(subtree.resolution.reason, 'injected_lookup')
+assert.equal(resolveUiChangeScope(tree, 'subtree', '', () => { throw new Error('must not resolve empty targets') }).error?.code, 'INVALID_SCOPE')
+assert.equal(resolveUiChangeScope(tree, 'subtree', 'missing', () => null).error?.code, 'ELEMENT_NOT_FOUND')
+const other = new ResolvedElements(2)
+assert.equal(other.get('one'), undefined, 'resolution stores do not share process-global state')
+store.clear()
+assert.equal(store.get('one'), undefined)
+console.log('PASS bounded handle retention and injected subtree resolution without static replacements')

package/test/unit/network/get_network_activity.test.ts

@@ -5,7 +5,7 @@ import {
   classifyStatus,
   _setTimestampsForTests,
   ToolsNetwork
-} from '../../../src/network/index.js'
+} from '../../../src/observe/network/index.js'
 
 function run() {
 

package/test/unit/observe/readiness.test.ts

@@ -32,8 +32,10 @@ for (const extra of [{ error: 'offline' }, { elements: [] }, { captured_at_ms: 9
 for (let index = 0; index < 20; index++) tracker.observe(sample(), 10000, 8000 + index)
 assert.equal(tracker.summary.evidence.length, 8)
 assert.equal(tracker.summary.capabilities.unresponsive, false)
-assert.equal(tracker.summary.capabilities.debugger_paused, false)
+assert.equal(tracker.summary.capabilities.debugger_paused, true)
 assert.ok(tracker.deadline().limitations.includes('DEADLINE_EXCEEDED'))
 assert.equal(new ReadinessTracker('android', 'fixture').observe(sample(), 10000, 9000).state, 'unknown', 'no cross-request history')
 assert.ok(!JSON.stringify(tracker.summary).includes('Ready'), 'evidence contains codes rather than private labels')
+assert.equal(new ReadinessTracker('ios', 'fixture').summary.capabilities.debugger_paused, false)
+assert.ok(tracker.summary.limitations.includes('MANAGED_DEBUGGER_ONLY'))
 console.log('Readiness classifier: PASS')

package/test/unit/observe/screenshot-encoding.test.ts

@@ -0,0 +1,30 @@
+import assert from 'node:assert/strict'
+import sharp from 'sharp'
+import { encodeScreenshot } from '../../../src/observe/screenshot-encoding.js'
+
+async function run() {
+  const alpha = await sharp({ create: { width: 2, height: 2, channels: 4, background: { r: 255, g: 0, b: 0, alpha: 0.5 } } }).png().toBuffer()
+  const opaque = await sharp({ create: { width: 2, height: 2, channels: 3, background: 'red' } }).png().toBuffer()
+  for (const platform of ['android', 'ios'] as const) {
+    const transparent = await encodeScreenshot(alpha, platform)
+    assert.equal(transparent.screenshot_mime, 'image/webp')
+    assert.equal((await sharp(Buffer.from(transparent.screenshot, 'base64')).metadata()).hasAlpha, true)
+    assert.equal(transparent.screenshot_fallback_mime, platform === 'ios' ? 'image/png' : 'image/jpeg')
+    if (platform === 'ios') assert.equal(transparent.screenshot_fallback, alpha.toString('base64'))
+    const solid = await encodeScreenshot(opaque, platform)
+    assert.equal(solid.screenshot_mime, 'image/webp')
+    assert.equal(solid.screenshot_fallback_mime, 'image/jpeg')
+    assert.equal((await sharp(Buffer.from(solid.screenshot_fallback!, 'base64')).metadata()).format, 'jpeg')
+  }
+  // An unreadable capture must survive conversion failures unchanged.
+  const invalid = Buffer.from('unreadable screenshot')
+  const originalError = console.error
+  try {
+    console.error = () => {}
+    for (const platform of ['android', 'ios'] as const) {
+      assert.deepEqual(await encodeScreenshot(invalid, platform), { screenshot: invalid.toString('base64'), screenshot_mime: 'image/png' })
+    }
+  } finally { console.error = originalError }
+  console.log('Screenshot alpha, fallback format and failed conversion tests passed')
+}
+run().catch(error => { console.error(error); process.exit(1) })

package/test/unit/observe/snapshot-logs.test.ts

@@ -0,0 +1,14 @@
+import assert from 'node:assert/strict'
+import { snapshotLog, streamLog } from '../../../src/observe/snapshot-logs.js'
+
+const iso = '2026-10-30T12:00:00Z'
+assert.deepEqual(snapshotLog({ timestamp: 123, message: 'warning', levelName: 'warn' }), { timestamp: 123, message: 'warning', level: 'WARN' })
+assert.equal(streamLog({ timestamp: 123, message: 'warning' }).timestamp, null)
+assert.equal(snapshotLog({ timestamp: 123, _iso: iso, msg: 'hello' }).timestamp, 123)
+assert.equal(streamLog({ timestamp: 123, _iso: iso, msg: 'hello' }).timestamp, Date.parse(iso))
+assert.equal(snapshotLog('FATAL EXCEPTION: crash').level, 'ERROR')
+assert.equal(streamLog('WARN: slow').level, 'WARN')
+assert.equal(snapshotLog({ timestamp: 'invalid', msg: 'hello' }).timestamp, null)
+assert.deepEqual(snapshotLog(null), { timestamp: null, level: 'INFO', message: '' })
+assert.equal(snapshotLog({ context: 'value' }).message, '{"context":"value"}')
+console.log('Snapshot and stream timestamp precedence and log normalization tests passed')