mobile-debug-mcp 0.34.0 → 0.36.0

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

@@ -0,0 +1,67 @@
+import assert from 'node:assert/strict'
+import { DebuggerSessions } from '../../../src/debugger/sessions.js'
+import type { DebugNative, DebugTarget } from '../../../src/debugger/android.js'
+import { DebuggerError, type WorkerEvent } from '../../../src/debugger/worker.js'
+import { diagnostic } from '../../../src/debugger/diagnostics.js'
+const target: DebugTarget = { app_id: 'test.app', process_name: 'test.app', pid: 1, uid: 2, start_identity: '3' }
+let removed = 0
+let closed = 0
+let cleanupFails = false
+let mode = ''
+const callbacks = new Map<string, (event: WorkerEvent) => void>()
+const native: DebugNative = {
+  candidates: async () => [target], identity: async () => target, forward: async () => 12345,
+  removeForward: async () => { if (cleanupFails) throw new Error('private'); removed++ }
+}
+const sessions = new DebuggerSessions(native, async emit => {
+  callbacks.set(mode, emit)
+  return {
+    call: async command => {
+      if (command === 'attach' && mode === 'attach') throw new DebuggerError('DEBUGGER_WORKER_FAILED', diagnostic('attach', 'connection_refused'))
+      if (command === 'step') {
+        emit({ event: 'worker_failed', diagnostic: diagnostic('ipc', 'invalid_message') })
+        throw new DebuggerError('DEBUGGER_WORKER_FAILED', diagnostic('ipc', 'invalid_message'))
+      }
+      return {}
+    },
+    close: async () => { closed++ }
+  }
+}, async () => ({ java: 'unused', directory: 'unused' }))
+try {
+  mode = 'attach'
+  const failed = await sessions.attach('one', 'test.app')
+  assert.equal(failed.error.code, 'DEBUGGER_WORKER_FAILED')
+  assert.deepEqual(failed.error.diagnostic, diagnostic('attach', 'connection_refused'))
+  assert.equal(failed.cleanup.status, 'complete')
+  assert.equal(closed, 1); assert.equal(removed, 1)
+  mode = 'first'
+  const first = await sessions.attach('one', 'test.app')
+  mode = 'second'
+  const second = await sessions.attach('two', 'test.app')
+  callbacks.get('first')!({ event: 'stopped', stop_id: 'stop' })
+  await assert.rejects(sessions.command(first.debug_session_id, 'step', { stopId: 'stop' }), /DEBUGGER_WORKER_FAILED/)
+  const terminal = await sessions.command(first.debug_session_id, 'state')
+  assert.deepEqual(terminal.error.diagnostic, diagnostic('ipc', 'invalid_message'), 'event/rejection race retains primary evidence after cleanup')
+  assert.equal(terminal.cleanup.status, 'complete')
+  await assert.rejects(sessions.command(first.debug_session_id, 'stack', {}), (e: unknown) => e instanceof DebuggerError && e.code === 'DEBUGGER_DISCONNECTED' && e.diagnostic?.reason === 'invalid_message')
+  assert.equal((await sessions.command(second.debug_session_id, 'state')).success, true, 'other device is isolated')
+  const aborted = new AbortController(); aborted.abort()
+  await assert.rejects(sessions.command(second.debug_session_id, 'events', { signal: aborted.signal }), (e: unknown) => e instanceof DebuggerError && e.diagnostic?.stage === 'command' && e.diagnostic.reason === 'cancelled')
+  cleanupFails = true
+  const incomplete = await sessions.command(second.debug_session_id, 'detach')
+  assert.equal(incomplete.error.code, 'DEBUGGER_CLEANUP_FAILED')
+  assert.deepEqual(incomplete.error.diagnostic, diagnostic('cleanup', 'operation_failed'))
+  cleanupFails = false
+  assert.equal((await sessions.command(second.debug_session_id, 'detach')).cleanup.status, 'complete')
+  mode = 'shutdown'
+  const shutdown = await sessions.attach('three', 'test.app')
+  await sessions.shutdown()
+  assert.equal(sessions.summary(shutdown.debug_session_id).cleanup.status, 'complete')
+} finally { await sessions.shutdown() }
+const badProbes = new DebuggerSessions({ ...native, candidates: async () => { throw new Error('private-token') } }, undefined,
+  async () => { throw new DebuggerError('DEBUGGER_UNSUPPORTED', diagnostic('compilation', 'operation_failed')) })
+const probe = await badProbes.capabilities('one', 'test.app')
+assert.equal(probe.success, true); assert.equal(probe.supported, false)
+assert.deepEqual(probe.diagnostics, [diagnostic('compilation', 'operation_failed'), diagnostic('target_resolution', 'unknown')])
+assert.ok(!JSON.stringify(probe).includes('private-token'))
+console.log('PASS diagnostic session retention/races, cleanup retry, isolation, shutdown and ordered capability diagnostics')

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

@@ -38,6 +38,10 @@ try {
   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

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

@@ -0,0 +1,88 @@
+import assert from 'node:assert/strict'
+import { debuggerSessions, iosDebuggerSessions } from '../../../src/debugger/sessions.js'
+import { handleToolCall } from '../../../src/server-core.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import { markDispatchStarted } from '../../../src/utils/operation-budget.js'
+import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
+
+const original = {
+  androidPaused: debuggerSessions.paused, androidActive: debuggerSessions.hasActiveSessions,
+  iosPaused: iosDebuggerSessions.paused, iosActive: iosDebuggerSessions.hasActiveSessions,
+  tree: ToolsObserve.getUITreeHandler, tap: ToolsInteract.tapHandler
+}
+let iosPaused = false, androidPaused = false, racePause = false, reads = 0, androidResolutions = 0
+const inputs: { platform?: string; deviceId?: string }[] = []
+const pause: any = { debug_session_id: 'ios-session', target: { app_id: 'test.app', pid: 1 }, state: 'paused', captured_at_ms: 1 }
+const tree = (platform: string, id: string): any => ({ device: { platform, id }, resolution: { width: 100, height: 100 },
+  elements: [{ text: 'Target', resourceId: 'target', bounds: [0, 0, 40, 40], visible: true, enabled: true, clickable: true }] })
+const payload = (response: any) => JSON.parse(response.content.find((item: any) => item.type === 'text').text)
+const call = async (elementId: string, hints: Record<string, unknown> = {}) => payload(await handleToolCall('tap_element', {
+  elementId, verificationMode: 'none', responseMode: 'compact', ...hints
+}))
+_setDeviceListersForTests({
+  listAndroidDevices: async () => { androidResolutions++; return [{ id: 'android', platform: 'android' } as any] },
+  listIOSDevices: async () => ['ios-a', 'ios-b'].map(id => ({ id, platform: 'ios', booted: true } as any))
+})
+debuggerSessions.hasActiveSessions = () => true
+iosDebuggerSessions.hasActiveSessions = () => true
+debuggerSessions.paused = id => androidPaused && id === 'android' ? { ...pause, debug_session_id: 'android-session' } : null
+iosDebuggerSessions.paused = id => iosPaused && id === 'ios-a' ? pause : null
+ToolsInteract._resetResolvedUiElementsForTests()
+try {
+  ToolsObserve.getUITreeHandler = async ({ platform, deviceId }) => {
+    reads++
+    if (racePause) iosPaused = true
+    return tree(platform!, deviceId!)
+  }
+  ToolsInteract.tapHandler = async ({ platform, deviceId, x, y }) => {
+    markDispatchStarted()
+    inputs.push({ platform, deviceId })
+    return { success: true, device: { platform, id: deviceId }, x, y } as any
+  }
+  const handle = async (platform: 'android' | 'ios', deviceId: string) => {
+    const result = await ToolsInteract.waitForUIHandler({ platform, deviceId, selector: { text: 'Target' }, condition: 'exists', timeout_ms: 1000 })
+    assert.equal(result.status, 'success')
+    return result.element.elementId
+  }
+  const ios = await handle('ios', 'ios-a')
+  const otherIOS = await handle('ios', 'ios-b')
+  const android = await handle('android', 'android')
+  reads = 0; androidResolutions = 0; iosPaused = true
+  for (const hints of [{}, { deviceId: 'ios-a' }, { platform: 'ios' }]) {
+    const blocked = await call(ios, hints)
+    assert.equal(blocked.failure_code, 'DEBUGGER_PAUSED')
+    assert.equal(blocked.debugger.debug_session_id, 'ios-session')
+    assert.equal(blocked.delivery_status, 'not_delivered'); assert.equal(blocked.dispatch_started, false)
+  }
+  assert.equal(reads, 0, 'A known pause must block before hierarchy reads')
+  assert.equal(inputs.length, 0); assert.equal(androidResolutions, 0, 'An iOS handle must not resolve an Android device')
+
+  iosPaused = false
+  assert.equal((await call(ios)).success, true)
+  assert.deepEqual(inputs.pop(), { platform: 'ios', deviceId: 'ios-a' })
+  racePause = true
+  const raced = await call(ios)
+  assert.equal(raced.failure_code, 'DEBUGGER_PAUSED')
+  assert.equal(raced.delivery_status, 'not_delivered'); assert.equal(inputs.length, 0, 'A pause during target refresh must block native dispatch')
+  racePause = false
+
+  assert.equal((await call(android)).success, true, 'An unrelated iOS pause must not block Android')
+  assert.deepEqual(inputs.pop(), { platform: 'android', deviceId: 'android' })
+  androidPaused = true
+  assert.equal((await call(android)).failure_code, 'DEBUGGER_PAUSED')
+  assert.equal((await call(otherIOS)).success, true, 'Other iOS devices must remain usable')
+  assert.deepEqual(inputs.pop(), { platform: 'ios', deviceId: 'ios-b' })
+  androidPaused = false; reads = 0
+  for (const hints of [{ platform: 'android', deviceId: 'android' }, { platform: 'ios', deviceId: 'ios-b' }]) {
+    assert.equal((await call(ios, hints)).failure_code, 'STALE_REFERENCE', 'Explicit mismatches retain handle validation')
+  }
+  assert.equal((await call('unknown', { platform: 'ios', deviceId: 'ios-b' })).failure_code, 'STALE_REFERENCE')
+  assert.equal(reads, 0); assert.equal(inputs.length, 0)
+  console.log('PASS stored-handle debugger guards: omitted target, no observation/input while paused, racing pause, platform/device isolation and mismatches')
+} finally {
+  debuggerSessions.paused = original.androidPaused; debuggerSessions.hasActiveSessions = original.androidActive
+  iosDebuggerSessions.paused = original.iosPaused; iosDebuggerSessions.hasActiveSessions = original.iosActive
+  ToolsObserve.getUITreeHandler = original.tree; ToolsInteract.tapHandler = original.tap
+  ToolsInteract._resetResolvedUiElementsForTests(); _resetDeviceListersForTests()
+}

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

@@ -0,0 +1,57 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { mkdtemp, 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-lldb-'))
+const python = path.join(directory, 'python')
+const xcrun = path.join(directory, 'xcrun')
+const log = path.join(directory, 'calls')
+const failed = path.join(directory, 'failed')
+try {
+  await writeFile(xcrun, `#!${process.execPath}
+const fs=require('node:fs');fs.appendFileSync(${JSON.stringify(log)},'xcrun\\n');
+console.log(process.argv[2]==='lldb'?'/fake/lldb-python':${JSON.stringify(python)});
+`, { mode: 0o700 })
+  await writeFile(python, `#!${process.execPath}
+const fs=require('node:fs');
+if(process.argv.includes('-c')) {
+ fs.appendFileSync(${JSON.stringify(log)},'probe\\n');
+ if(!fs.existsSync(${JSON.stringify(failed)})){fs.writeFileSync(${JSON.stringify(failed)},'');process.exit(1)}
+ console.log('ready');
+} else {
+ fs.appendFileSync(${JSON.stringify(log)},'worker\\n');
+ require('node:readline').createInterface({input:process.stdin}).on('line',line=>{
+  const request=JSON.parse(line);console.log(JSON.stringify({id:request.id,result:{detached:true}}));
+ });
+}
+`, { mode: 0o700 })
+  const code = `
+import assert from 'node:assert/strict';import {readFileSync} from 'node:fs';
+// Load the TypeScript toolchain before emulating macOS so Linux selects its own esbuild.
+const {prepareIOSWorker,createIOSWorker}=await import('./src/debugger/ios-worker.ts');
+// Isolate platform emulation and native binaries from the unit runner process.
+Object.defineProperty(process,'platform',{value:'darwin'});
+const first=prepareIOSWorker();assert.strictEqual(first,prepareIOSWorker());
+const failed=await Promise.allSettled([first,prepareIOSWorker()]);
+assert.ok(failed.every(result=>result.status==='rejected'));
+const retry=prepareIOSWorker();assert.notStrictEqual(first,retry);
+assert.strictEqual(retry,prepareIOSWorker());
+const configuration=await retry;
+assert.equal(configuration.python,${JSON.stringify(python)});
+assert.equal(configuration.env.PYTHONPATH,'/fake/lldb-python');
+assert.equal(configuration.env.PYTHONNOUSERSITE,'1');
+assert.strictEqual(await prepareIOSWorker(),configuration);
+const worker=await createIOSWorker(()=>{});await worker.close();
+const calls=readFileSync(${JSON.stringify(log)},'utf8').trim().split('\\n');
+assert.equal(calls.filter(call=>call==='xcrun').length,4);
+assert.equal(calls.filter(call=>call==='probe').length,2);
+assert.equal(calls.filter(call=>call==='worker').length,1);
+console.log('PASS shared iOS preparation, failed-probe retry, configuration and worker cache reuse');
+`
+  const result = await exec(process.execPath, ['--import', 'tsx', '--input-type=module', '-e', code], {
+    env: { ...process.env, XCRUN_PATH: xcrun }, timeout: 15000
+  })
+  console.log(result.stdout.trim())
+} finally { await rm(directory, { recursive: true, force: true }) }

package/test/unit/debugger/ios.test.ts

@@ -0,0 +1,104 @@
+import assert from 'node:assert/strict'
+import { mkdtemp, writeFile, rm, realpath } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { IOSDebugNative } from '../../../src/debugger/ios.js'
+import { DebuggerSessions, iosDebuggerSessions, debuggerSessions } from '../../../src/debugger/sessions.js'
+import { iosCapabilities, iosLimitations } from '../../../src/debugger/ios-worker.js'
+import { debuggerContracts, debuggerTools } from '../../../src/server/schemas/debugger-schema.js'
+import { withDebuggerGuard, checkDebuggerGuard, pausedReadiness } from '../../../src/debugger/guard.js'
+import { execCommandWithDiagnostics } from '../../../src/utils/ios/utils.js'
+import { handleDebugger } from '../../../src/server/handlers/debugger-handlers.js'
+import { DebuggerError, type WorkerEvent } from '../../../src/debugger/worker.js'
+const directory = await mkdtemp(path.join(os.tmpdir(), 'ios-debugger-unit-'))
+await writeFile(path.join(directory, 'App'), '')
+const executable = await realpath(path.join(directory, 'App'))
+const device = 'F9243BAF-62A8-4990-8A99-17F527F56FDA'
+let processPath = executable, started = 'Mon Nov 4 12:00:00 2026', services = '123\t0\tUIKitApplication:dev.fixture.app[uuid]'
+const calls: string[][] = []
+const native = new IOSDebugNative(async (file, args) => {
+  calls.push([file, ...args])
+  if (args[0] === 'simctl' && args[1] === 'list') return JSON.stringify({ devices: { runtime: [{ udid: device, state: 'Booted' }] } })
+  if (args.includes('get_app_container')) return directory
+  if (file === '/usr/bin/plutil') return 'App'
+  if (args.includes('launchctl')) return services
+  if (args.includes('comm=')) return processPath
+  if (args.includes('lstart=')) return started
+  throw new Error('unexpected native command')
+})
+const base = { debugSessionId: 's', line: 1 }
+for (const selector of [{}, { className: 'dev.App', sourceFile: '/tmp/App.swift' }, { sourceFile: 'App.swift' }]) {
+  assert.equal(debuggerContracts.set_debugger_breakpoint.schema.safeParse({ ...base, ...selector }).success, false)
+}
+for (const selector of [{ className: 'dev.App' }, { sourceFile: '/tmp/App.swift' }]) {
+  assert.equal(debuggerContracts.set_debugger_breakpoint.schema.safeParse({ ...base, ...selector }).success, true)
+}
+assert.ok(debuggerTools.find(t => t.name === 'attach_debugger')!.inputSchema.properties.platform)
+let emit: (event: WorkerEvent) => void = () => {}
+let closed = 0
+const sessions = new DebuggerSessions(native, async onEvent => {
+  emit = onEvent
+  return { call: async (command, args) => {
+    if (command === 'step' && args?.threadId === 'foreign') throw new DebuggerError('DEBUGGER_STALE_REFERENCE')
+    if (command === 'attach') { assert.equal(args?.pid, 123); assert.equal(args?.executablePath, executable); emit({ event: 'stopped', stop_id: 'racing-stop', thread_id: 't' }) }
+    return { breakpoints: [] }
+  }, close: async () => { closed++ } }
+}, async () => {}, { platform: 'ios', capabilities: iosCapabilities, limitations: iosLimitations })
+const androidPause = debuggerSessions.paused, iosPause = iosDebuggerSessions.paused
+try {
+  const candidates = await native.candidates(device, 'dev.fixture.app')
+  assert.equal(candidates[0].pid, 123); assert.equal(candidates[0].executable_path, executable)
+  assert.equal(candidates[0].uid, null)
+  await assert.rejects(native.candidates('booted', 'dev.fixture.app'), /INVALID_ARGUMENT/)
+  await assert.rejects(native.candidates('00000000-0000-0000-0000-000000000000', 'dev.fixture.app'), /DEBUGGER_UNSUPPORTED/)
+  processPath = '/tmp/foreign-process'
+  await assert.rejects(native.identity(device, candidates[0]), /PROCESS_CHANGED/)
+  processPath = executable; started = 'new process'
+  await assert.rejects(native.identity(device, candidates[0]), /PROCESS_CHANGED/)
+  started = candidates[0].start_identity
+  services = '999\t0\tUIKitApplication:dev.fixture.other[uuid]'
+  await assert.rejects(native.identity(device, candidates[0]), /PROCESS_CHANGED/)
+  services = '123\t0\tUIKitApplication:dev.fixture.app[uuid]'
+  const attached = await sessions.attach(device, 'dev.fixture.app')
+  assert.equal(attached.device.platform, 'ios'); assert.equal(attached.state, 'paused', 'racing attach stop is preserved')
+  assert.deepEqual(attached.cleanup.remaining_resources, ['lldb_worker'])
+  await assert.rejects(sessions.command(attached.debug_session_id, 'set', { className: 'Wrong', line: 1 }), /INVALID_ARGUMENT/)
+  emit({ event: 'stopped', stop_id: 'fresh', thread_id: 't' })
+  await assert.rejects(sessions.command(attached.debug_session_id, 'step', { stopId: 'fresh', threadId: 'foreign', kind: 'into' }), /DEBUGGER_STALE_REFERENCE/)
+  assert.equal(sessions.paused(device)?.stop?.stop_id, 'fresh', 'Rejected step preserves known suspension and guard')
+  await assert.rejects(sessions.command(attached.debug_session_id, 'locals', { stopId: 'racing-stop' }), /DEBUGGER_STALE_REFERENCE/)
+  iosDebuggerSessions.paused = id => id === 'same-id' ? { ...attached, debug_session_id: 'ios' } : null
+  debuggerSessions.paused = id => id === 'same-id' ? { ...attached, debug_session_id: 'android' } : null
+  assert.equal(pausedReadiness('same-id', 'ios')?.debug_session_id, 'ios')
+  assert.equal(pausedReadiness('same-id', 'android')?.debug_session_id, 'android')
+  await assert.rejects(withDebuggerGuard('ios', 'same-id', async () => checkDebuggerGuard(true)), /DEBUGGER_PAUSED/)
+  await withDebuggerGuard('ios', 'other', async () => checkDebuggerGuard())
+  await assert.rejects(withDebuggerGuard('ios', 'same-id', async () => execCommandWithDiagnostics(['simctl', 'launch', 'same-id', 'dev.fixture.app'])), /DEBUGGER_PAUSED/, 'Diagnostic fallback cannot resend a paused lifecycle command')
+  assert.equal((await sessions.command(attached.debug_session_id, 'detach')).cleanup.status, 'complete')
+  assert.equal(closed, 1)
+  assert.ok(!calls.some(call => call.includes('forward')), 'iOS must not allocate or remove ADB forwards')
+  const original = iosDebuggerSessions.capabilities
+  try {
+    iosDebuggerSessions.capabilities = async () => { throw new DebuggerError('DEBUGGER_UNSUPPORTED') }
+    const response = await handleDebugger('get_debugger_capabilities', { platform: 'ios', deviceId: device, appId: 'dev.fixture.app' })
+    const payload = JSON.parse(response.content[0].text)
+    assert.equal(payload.device.platform, 'ios'); assert.equal(payload.capabilities.coroutines, false)
+    assert.ok(!/JDK|Java worker|ADB/.test(payload.error.diagnostic.recovery))
+  } finally { iosDebuggerSessions.capabilities = original }
+  console.log('PASS iOS target membership, process identity, contracts, session routing, racing stops and platform guards')
+} finally {
+  debuggerSessions.paused = androidPause; iosDebuggerSessions.paused = iosPause
+  await sessions.shutdown(); await rm(directory, { recursive: true, force: true })
+}
+
+// Confirmed detach and process-exit evidence are required for cleanup success.
+const { IOSWorker } = await import('../../../src/debugger/ios-worker.js')
+let transportClosed = 0
+const disconnected = new IOSWorker({ call: async () => { throw new Error('transport lost') }, close: async () => { transportClosed++ } }, () => false)
+await assert.rejects(disconnected.close(), /DEBUGGER_CLEANUP_FAILED/)
+assert.equal(transportClosed, 1)
+const exited = new IOSWorker({ call: async () => { throw new Error('must not need detach') }, close: async () => {} }, () => true)
+await exited.close()
+const confirmed = new IOSWorker({ call: async () => ({ detached: true }), close: async () => {} }, () => false)
+await confirmed.close()
+console.log('PASS iOS cleanup requires confirmed release; worker exit alone is insufficient')

package/test/unit/debugger/lldb-worker.py

@@ -0,0 +1,166 @@
+"""Platform-independent regression checks for the optional LLDB worker."""
+import pathlib
+import sys
+import types
+
+root = pathlib.Path(__file__).resolve().parents[3] / 'src/debugger/lldb'
+sys.path.insert(0, str(root))
+lldb = types.SimpleNamespace(eStateInvalid=0, eStateStopped=5, eStateExited=10, eStateDetached=9,
+                            eStopReasonNone=1, eStopReasonInvalid=0, eStopReasonBreakpoint=3)
+sys.modules['lldb'] = lldb
+import worker
+from inspection import Inspection
+from breakpoints import Breakpoints
+
+# Independent pause, idle and absolute expiry cannot be extended by heartbeats.
+w = object.__new__(worker.Worker)
+clock = [100.0]
+worker.time.monotonic = lambda: clock[0]
+w.created, w.activity, w.paused_at = 0, 100, 40
+assert w.expired() == 'pause_limit'
+w.paused_at = None
+clock[0] = 400
+assert w.expired() == 'idle_limit'
+w.activity = 1800
+clock[0] = 1800
+assert w.expired() == 'session_limit'
+
+# An internal transition with an empty thread list must not create a pause epoch.
+i = Inspection()
+p = types.SimpleNamespace(GetNumThreads=lambda: 0, GetState=lambda: 5, GetSelectedThread=lambda: types.SimpleNamespace(IsValid=lambda: False))
+assert i.stopped(p) is None
+assert i.stop_id is None
+for method, args in [(i.thread, {'stopId': 'old', 'threadId': 'old'}),
+                     (i.locals, {'stopId': 'old', 'frameId': 'old'})]:
+    try:
+        method(args)
+        raise AssertionError('Stale reference accepted')
+    except ValueError as error:
+        assert str(error) == 'DEBUGGER_STALE_REFERENCE'
+
+# Exact source-line resolver must never request nearest-code relocation.
+class Entry:
+    def IsValid(self): return True
+    def GetFileSpec(self): return '/tmp/App.swift'
+    def GetLine(self): return 13
+class Location:
+    def GetAddress(self): return types.SimpleNamespace(GetLineEntry=lambda: Entry())
+    def SetEnabled(self, enabled): self.enabled = enabled
+class Breakpoint:
+    def __init__(self): self.location = Location()
+    def __iter__(self): return iter([self.location])
+    def GetID(self): return 1
+class Target:
+    def __init__(self): self.deleted = False; self.bp = Breakpoint()
+    def BreakpointCreateByLocation(self, *args):
+        assert args[-1] is False
+        return self.bp
+    def BreakpointDelete(self, identity): self.deleted = True
+    def FindCompileUnits(self, source): return types.SimpleNamespace(GetSize=lambda: 1)
+lldb.SBFileSpec = lambda source: source
+lldb.SBFileSpecList = list
+t = Target()
+b = Breakpoints(t)
+r = b.set({'sourceFile': '/tmp/App.swift', 'line': 12})
+assert r['status'] == 'rejected'
+assert t.bp.location.enabled is False and t.deleted
+
+# Polling must consume events before reading the process snapshot.
+trace = []
+class Listener:
+    def GetNextEvent(self, event): trace.append('consume'); return False
+class Process:
+    def GetState(self): trace.append('state'); return 6
+w.debugger = types.SimpleNamespace(GetListener=lambda: Listener())
+w.process, w.terminal = Process(), False
+lldb.SBEvent = object
+w.poll()
+assert trace == ['consume', 'state']
+
+# EOF cleanup must release an actual target, never call Kill or expression APIs.
+w.attached = True
+w.inspection = Inspection()
+w.breakpoints = types.SimpleNamespace(clear=lambda: None)
+w.process = types.SimpleNamespace(IsValid=lambda: True, GetState=lambda: 5,
+    Detach=lambda: types.SimpleNamespace(Success=lambda: True))
+assert w.detach() == {'detached': True}
+assert w.terminal
+print('PASS LLDB worker expiry, transient stops, stale references, exact lines, events and detach')
+
+# Static Swift bool decoding must preserve boolean meaning without formatters.
+lldb.eNoDynamicValues, lldb.eTypeIsScalar, lldb.eTypeIsInteger, lldb.eTypeIsFloat = 0, 1, 2, 4
+class BoolValue:
+    def GetNonSyntheticValue(self): return self
+    def GetName(self): return 'cancelled'
+    def GetTypeName(self): return 'Swift.Bool'
+    def GetError(self): return types.SimpleNamespace(Success=lambda: True)
+    def GetType(self): return types.SimpleNamespace(GetTypeFlags=lambda: 0)
+    def GetValue(self): return '1'
+    def GetChildMemberWithName(self, name):
+        assert name == '_value'
+        return types.SimpleNamespace(GetNonSyntheticValue=lambda: self)
+    def IsValid(self): return True
+values = types.SimpleNamespace(GetSize=lambda: 1, GetValueAtIndex=lambda index: BoolValue())
+i.stop_id = '00000000-0000-0000-0000-000000000001'
+i.frames['frame'] = types.SimpleNamespace(GetVariables=lambda *args: values)
+assert i.locals({'stopId': i.stop_id, 'frameId': 'frame'})['locals'][0]['value'] == 'true'
+
+# Reference summaries are stable within a stop and never expose the pointer.
+pointer = types.SimpleNamespace(GetValue=lambda: '0x1234')
+first = i.object_identity(pointer, 'Controller')
+assert first == i.object_identity(pointer, 'Controller') and '1234' not in first
+i.stop_id = '00000000-0000-0000-0000-000000000002'
+assert first != i.object_identity(pointer, 'Controller')
+
+# Repeated stack pages reuse references and cannot grow beyond the stop cap.
+import inspection
+original_location = inspection.location
+inspection.location = lambda frame: {'source_file': '/tmp/App.swift', 'line': 1}
+try:
+    i.invalidate()
+    i.stop_id = '00000000-0000-0000-0000-000000000001'
+    i.threads['thread'] = types.SimpleNamespace(GetNumFrames=lambda: 1001, GetFrameAtIndex=lambda index: object())
+    args = {'stopId': i.stop_id, 'threadId': 'thread', 'limit': 100}
+    assert i.stack(args)['frames'][0]['frame_id'] == i.stack(args)['frames'][0]['frame_id']
+    for offset in range(0, 1000, 100): i.stack({**args, 'offset': offset})
+    assert len(i.frames) == 1000
+    i.threads['other'] = i.threads['thread']
+    result = i.stack({**args, 'threadId': 'other'})
+    assert result['frames'] == [] and result['truncated']
+finally:
+    inspection.location = original_location
+print('PASS static bool decoding, opaque identities and bounded stable frame references')
+
+# Error-reporting StepInto requires LLDB's UINT32_MAX sentinel, not line zero.
+lldb.LLDB_INVALID_LINE_NUMBER, lldb.eOnlyDuringStepping = 4294967295, 0
+lldb.SBError = lambda: types.SimpleNamespace(Success=lambda: True)
+class StepThread:
+    def StepInto(self, target, end_line, error, run_mode):
+        assert target is None and end_line == 4294967295
+w.terminal = False
+w.inspection = Inspection()
+w.inspection.stop_id = 'stop'
+w.inspection.threads['thread'] = StepThread()
+w.process = types.SimpleNamespace(GetState=lambda: 5)
+assert w.command({'command': 'step', 'stopId': 'stop', 'threadId': 'thread', 'kind': 'into'}) == {'resumed': True}
+assert w.inspection.stop_id is None
+print('PASS LLDB step error overload uses the documented invalid-line sentinel')
+
+# Signals and exceptions must not be misrepresented as completed source steps.
+lldb.eStopReasonPlanComplete, lldb.eStopReasonSignal, lldb.eStopReasonException = 8, 5, 6
+lldb.eStopReasonWatchpoint, lldb.eStopReasonExec = 4, 7
+assert inspection.stop_reason(types.SimpleNamespace(GetStopReason=lambda: 5)) == 'signal'
+assert inspection.stop_reason(types.SimpleNamespace(GetStopReason=lambda: 6)) == 'exception'
+assert inspection.stop_reason(types.SimpleNamespace(GetStopReason=lambda: 8)) == 'step'
+assert inspection.stop_reason(types.SimpleNamespace(GetStopReason=lambda: 99)) == 'unknown'
+print('PASS LLDB stop reasons preserve signal/exception versus step evidence')
+
+# Losing a previously owned process handle cannot prove detach or resume.
+w.attached = True
+w.process = types.SimpleNamespace(IsValid=lambda: False)
+try:
+    w.detach()
+    raise AssertionError('Lost process handle incorrectly confirmed detach')
+except ValueError as error:
+    assert str(error) == 'DEBUGGER_WORKER_FAILED'
+print('PASS lost process handles preserve cleanup uncertainty')

package/test/unit/debugger/lldb-worker.test.ts

@@ -0,0 +1,10 @@
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+const result = spawnSync('python3', ['-B', fileURLToPath(new URL('./lldb-worker.py', import.meta.url))], { encoding: 'utf8', timeout: 15000 })
+if ((result.error as NodeJS.ErrnoException | undefined)?.code === 'ENOENT') {
+  console.log('UNRUN optional LLDB Python worker checks: python3 is unavailable')
+} else {
+  assert.equal(result.status, 0, result.stderr || result.error?.message)
+  console.log(result.stdout.trim())
+}

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')