mobile-debug-mcp 0.35.0 → 0.36.0

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/observe/ios-trace-native.test.ts

@@ -0,0 +1,90 @@
+import assert from 'node:assert/strict'
+import { promises as fs } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { iosCapabilities, resolveIosApp } from '../../../src/observe/ios-trace/capabilities.js'
+import { validateArtifact, validateToc, traceSize, IOS_TRACE_MAX_BYTES } from '../../../src/observe/ios-trace/artifact.js'
+import { IosTraceNative } from '../../../src/observe/ios-trace/native.js'
+import { spawnTrace, stopTraceChild, classifyTraceFailure, type TraceSpawn, type TraceCommandResult } from '../../../src/observe/ios-trace/process.js'
+const app={app_id:'fixture',pid:123,executable:'/Fixture.app/Fixture',started_at:'Wed Nov 4 10:00:00 2026'}
+const toc=(id='sim',pid=123,template='Time Profiler')=>`<trace-toc><run><info><target><device uuid="${id}"/><process pid="${pid}"/></target><summary><template-name>${template}</template-name></summary></info><processes><process pid="${pid}" path="/Fixture.app/Fixture"/></processes><data><table schema="time-sample"/></data></run></trace-toc>`
+function fake(){
+  const calls:{command:string;args:string[];signals:NodeJS.Signals[]}[]=[],lines:string[]=[]
+  let mismatch=false,failExport=false,failReady=false
+  const spawn:TraceSpawn=(command,args)=>{
+    const call={command,args,signals:[] as NodeJS.Signals[]};calls.push(call)
+    const recording=args.includes('record'),listener=command.endsWith('/notification'),pending=recording||listener
+    let alive=pending,resolve!:(r:TraceCommandResult)=>void
+    const done=new Promise<TraceCommandResult>(r=>{resolve=r})
+    const execute=async()=>{
+      let output=''
+      if(args.includes('get_app_container'))output='/Fixture.app'
+      else if(args.includes('launchctl'))output='123 0 UIKitApplication:fixture[abc]'
+      else if(command==='/bin/ps')output=args.includes('lstart=')?app.started_at:mismatch?'/Other.app/Other':app.executable
+      else if(args.includes('clang'))await fs.writeFile(args[args.indexOf('-o')+1],'binary')
+      else if(args.includes('xcodebuild'))output='Xcode 27.2'
+      else if(args.includes('templates'))output='== Standard Templates ==\nTime Profiler\nSystem Trace\nAnimation Hitches'
+      else if(args.includes('xctrace')&&args.includes('devices'))output='fixture (sim)'
+      else if(args.includes('devices'))output=JSON.stringify({devices:{'iOS-26-4':[{udid:'sim',state:'Booted',name:'fixture',isAvailable:true}]}})
+      else if(args.includes('export')){
+        if(failExport){resolve({code:2,output:'private stderr',timedOut:false});return}
+        const file=args[args.indexOf('--output')+1]
+        await fs.writeFile(file,args.includes('--toc')?toc():'<trace-query-result><node><schema name="time-sample"/><row><sample-time>1</sample-time></row></node></trace-query-result>')
+      }
+      if(!pending)resolve({code:0,output,timedOut:false})
+    }
+    void execute()
+    return {done,alive:()=>alive,signal:s=>{call.signals.push(s);alive=false;resolve({code:0,output:'Stopped',timedOut:false})},line:async(line)=>{lines.push(line);if(failReady&&line==='READY')throw new Error('READINESS_TIMEOUT')}}
+  }
+  return {spawn,calls,lines,flags:(v:{mismatch?:boolean;export?:boolean;ready?:boolean})=>{mismatch=v.mismatch??false;failExport=v.export??false;failReady=v.ready??false}}
+}
+async function run(){
+  const f=fake(),directory=await fs.mkdtemp(path.join(os.tmpdir(),'ios-trace-unit-'))
+  try{
+    assert.deepEqual(await resolveIosApp('sim','fixture',f.spawn),app)
+    f.flags({mismatch:true});await assert.rejects(()=>resolveIosApp('sim','fixture',f.spawn),/APP_IDENTITY_UNAVAILABLE/);f.flags({})
+    const cap=await iosCapabilities('sim','fixture','Time Profiler',f.spawn,'darwin')
+    assert.equal(cap.supported,true);assert.equal(cap.prerequisites.permissions,'unknown');assert.equal(cap.templates.filter(t=>t.supported).length,1)
+    assert.equal((await iosCapabilities('sim',undefined,'System Trace',f.spawn,'darwin')).supported,false)
+    assert.equal((await iosCapabilities('physical',undefined,'Time Profiler',f.spawn,'darwin')).supported,false)
+    assert.equal((await iosCapabilities('sim',undefined,'Time Profiler',f.spawn,'linux')).reasons[0],'MACOS_REQUIRED')
+    assert.ok(!f.calls.some(c=>c.args.includes('record')),'Discovery must not record')
+    validateToc(toc(),'sim',app)
+    assert.throws(()=>validateToc(toc(),'sim',{...app,executable:'/Other.app/Other'}),/ARTIFACT_APP_MISMATCH/)
+    assert.equal(classifyTraceFailure({code:1,output:'secret path: permission denied',timedOut:false}),'PROFILING_PERMISSION_REQUIRED')
+    assert.equal(classifyTraceFailure({code:1,output:'Cannot find process for provided pid: 123',timedOut:false}),'APP_NOT_RUNNING')
+    for(const xml of [toc('other'),toc('sim',456),toc('sim',123,'System Trace'),'<invalid>'])assert.throws(()=>validateToc(xml,'sim',app))
+    const file=path.join(directory,'capture.trace');await fs.mkdir(file);await fs.writeFile(path.join(file,'data'),'samples')
+    const artifact=await validateArtifact(file,'sim',app,f.spawn)
+    assert.equal(artifact.validation.sample_rows,1);assert.equal(artifact.kind,'directory');assert.equal((await fs.stat(path.join(file,'data'))).mode&0o777,0o600)
+    await assert.rejects(()=>fs.stat(path.join(directory,'samples.xml')),{code:'ENOENT'})
+    f.flags({export:true});await assert.rejects(()=>validateArtifact(file,'sim',app,f.spawn));f.flags({})
+    const outside=path.join(directory,'link');await fs.symlink(file,outside);await assert.rejects(()=>traceSize(outside),/UNSAFE_ARTIFACT/)
+    const huge=path.join(directory,'huge');await fs.writeFile(huge,'');await fs.truncate(huge,IOS_TRACE_MAX_BYTES+1)
+    assert.ok(await traceSize(huge)>IOS_TRACE_MAX_BYTES)
+    const native=new IosTraceNative(f.spawn)
+    const recording=await native.start('sim',app,directory,30000,()=>{})
+    assert.deepEqual(f.lines,['ARMED','READY'])
+    const recorder=f.calls.find(c=>c.args.includes('record'))!,listener=f.calls.find(c=>c.command.endsWith('/notification'))!
+    assert.equal(recorder.args[recorder.args.indexOf('--device')+1],'sim')
+    assert.equal(recorder.args[recorder.args.indexOf('--attach')+1],'123')
+    assert.equal(recorder.args[recorder.args.indexOf('--notify-tracing-started')+1],listener.args[0])
+    assert.ok(!recorder.args.includes('--no-prompt'));await native.stop(recording);assert.deepEqual(recorder.signals,['SIGINT'])
+    const failed=fake();failed.flags({ready:true});const other=new IosTraceNative(failed.spawn)
+    await assert.rejects(()=>other.start('sim',app,directory,30000,()=>{}),/READINESS_TIMEOUT/)
+    assert.ok(failed.calls.find(c=>c.args.includes('record'))?.signals.includes('SIGINT'))
+    native.shutdown();other.shutdown()
+    const child=spawnTrace(process.execPath,['-e','process.stdout.write("READY\\n");setInterval(()=>{},1000)'],2000)
+    await child.line('READY',1000);await stopTraceChild(child,1000);assert.equal(child.alive(),false)
+    const signals:NodeJS.Signals[]=[]
+    const stuck={done:new Promise<TraceCommandResult>(()=>{}),alive:()=>true,line:async()=>{},signal:(s:NodeJS.Signals)=>{signals.push(s)}}
+    await assert.rejects(()=>stopTraceChild(stuck,1),/ACTION_TIMEOUT/)
+    assert.deepEqual(signals,['SIGINT','SIGKILL'])
+    const noisy=await spawnTrace(process.execPath,['-e','process.stdout.write("x".repeat(100000))'],2000).done
+    assert.equal(noisy.output.length,65536)
+    const timeout=await spawnTrace(process.execPath,['-e','setInterval(()=>{},1000)'],30).done
+    assert.equal(timeout.timedOut,true)
+    console.log('PASS iOS native discovery, notification, ownership, artifact schemas and bounded children')
+  }finally{await fs.rm(directory,{recursive:true,force:true})}
+}
+run().catch(error=>{console.error(error);process.exitCode=1})