mobile-debug-mcp 0.35.0 → 0.37.0

package/docs/tools/system-traces.md

@@ -1,9 +1,10 @@
-# Android system traces
+# System traces for Android and iOS
 
 [Documentation](../README.md) · [Tool reference](TOOLS.md)
 
 Use system traces to collect scheduling and system annotations around a slow
-interaction. Capture is optional, device-wide and Android-only; it does not
+interaction. Capture is optional; Android uses device-wide Perfetto and iOS simulators use
+app-attached Instruments Time Profiler. It does not
 automatically diagnose performance problems. No root or Android CLI installation
 is required. The device must provide Perfetto (Android API 29+), authorised ADB,
 tracing services, required sched/input categories, readable process identity,
@@ -11,14 +12,14 @@ base64 decoding and writable `/data/misc/perfetto-traces` storage.
 
 ## Tools
 
-All inputs reject unknown fields. `platform` is `android` or `ios`; iOS is
-unsupported and never starts capture. Optional `deviceId` uses existing device
-resolution; supplying one is recommended when multiple devices are connected.
+All inputs reject unknown fields. `platform` is `android` or `ios`. Android's
+optional `deviceId` uses existing device resolution. iOS requires an explicit
+booted simulator UDID, plus `appId` for start; it never records the Mac host.
 
 | Tool | Arguments | Result |
 | --- | --- | --- |
-| `get_system_trace_capabilities` | `platform`, `deviceId?` | `supported`, `backend`, resolved `device`, prerequisite booleans, reasons, enabled sources, unavailable categories, limitations. No recording. |
-| `start_system_trace` | `platform`, `deviceId?`, `durationMs?` | Owned recording session after data-source acknowledgement. Duration is an integer 1,000–120,000 ms, default 30,000. |
+| `get_system_trace_capabilities` | `platform`, `deviceId?`, `appId?`, `template?` | Common: `supported`, `backend`, resolved `device`, reasons and limitations. Android: prerequisite booleans, `enabled_sources`, `unavailable_categories`. iOS: prerequisites as `available`/`missing`/`unknown`, `discovered_templates`, `templates`, `app`, `xcode_version`, `recovery`. No recording. |
+| `start_system_trace` | `platform`, `deviceId?`, `durationMs?`, `appId?`, `template?` | Owned recording session after native readiness acknowledgement. Duration is an integer 1,000–120,000 ms, default 30,000. |
 | `get_system_trace_status` | `traceId` | Reconcile process/deadline and finalise ended recording. |
 | `stop_system_trace` | `traceId` | Gracefully stop and retrieve local artifact; retry transfer/cleanup after failure. |
 | `cancel_system_trace` | `traceId` | Stop and discard partial files. Already retrieved artifacts remain local. |
@@ -26,7 +27,7 @@ resolution; supplying one is recommended when multiple devices are connected.
 Trace control IDs are UUIDs and cannot redirect to another device. One capture
 per device and four pending sessions per server are allowed. Pending failed
 cleanup reserves its slot until resolved. Terminal records with complete cleanup
-expire after 10 minutes or eviction beyond 100 records. Server restart invalidates
+expire after 10 minutes or eviction beyond 100 records per backend (the router retains at most 100 completed IDs). Server restart invalidates
 IDs. Repeated terminal operations return the stored outcome.
 
 ## Capture workflow
@@ -89,12 +90,13 @@ proof of causality; host intervals are not aligned with device trace clocks.
 ## Session response and failures
 
 JSON responses contain `trace_id`, process-scoped `session_id`, `device`,
-`backend:"perfetto"`, `state` (starting/recording/stopping/completed/cancelled/failed),
+`backend:"perfetto"` (Android) or `"xctrace"` (iOS), `state` (starting/recording/stopping/completed/cancelled/failed),
 nullable `reason` and `completion_reason`, host UTC capture bounds, nullable
-`artifact`, `cleanup`, `correlation_ids`, `enabled_sources`, and
-`unavailable_categories`. Capture bounds include command/acknowledgement latency.
+`artifact`, `cleanup`, and `correlation_ids`. Android additionally returns
+`enabled_sources` and `unavailable_categories`. Capture bounds include command/acknowledgement latency.
 
-`artifact` contains absolute `path`, `format:"perfetto"` and `size_bytes`.
+Android `artifact` contains absolute `path`, `format:"perfetto"` and `size_bytes`;
+see the iOS section below for Instruments artifact and session fields.
 `cleanup` contains `status` (pending/complete/failed) and `remaining_resources`.
 Errors preserve known session metadata and set MCP `isError`. Argument/unknown-ID
 errors return `{error:{tool,code,message}}` without a session. Codes include
@@ -105,7 +107,7 @@ Capability failures return ordinary `supported:false` responses with reasons.
 Read state/cleanup independently: a successful artifact transfer can still have
 failed device-file cleanup. Retry stop/status, or cancel to discard failed output.
 
-## Limits and privacy
+## Android limits and privacy
 
 The fixed preset requests sched, freq, idle, am, wm, gfx, view and input categories,
 a 16 MiB ring buffer and a 32 MiB maximum output. Missing optional categories are
@@ -127,8 +129,73 @@ a uniquely named bounded device file for manual removal; restart performs no
 broad cleanup sweep. Device suspend can extend Perfetto's own monotonic duration
 limit; the server timer bounds wall-clock lifetime while the server is running.
 
+## iOS simulator Instruments capture
+
+Requires macOS, full Xcode with Instruments and clang, a booted simulator visible
+in both `simctl` and `xctrace list devices`, and an already running development
+app. Journey input also needs a compatible idb companion; capability discovery
+for capture does not establish HID input support. The initial verified target is iPhone 17 Pro simulator / iOS 26.4.1 with
+Xcode 27.2. Physical-device capture is unsupported and unrun. Tool installation,
+OS profiling permissions and pairing/security changes are user actions.
+
+```json
+{"platform":"ios","deviceId":"<simulator-UDID>","appId":"<bundle-id>","template":"Time Profiler","durationMs":60000}
+```
+
+Use this target with capabilities and start, then bracket a `run_journey` on the
+same simulator using the returned `systemTraceId`, and stop/cancel as above.
+Omitting `template` defaults to Time Profiler. `appId` and `template` are rejected
+on Android. Capabilities do not start capture; permissions and symbols remain
+`unknown` until separately established. Installed templates are listed separately
+from support: System Trace scheduling coverage is unverified, Animation Hitches
+reported unsupported on the tested simulator, and Hangs is bundled within Time
+Profiler rather than a selectable standalone template. No silent substitution.
+
+The server resolves the bundle to an exact current executable/PID, pins the UDID,
+and waits for a uniquely named Darwin recording-start notification before
+returning `recording`. It compiles a small private listener with Xcode clang in
+the owned temporary directory. A failed/uncertain start cleans up and returns a
+failure, not an automatic retry. Errors such as `APP_NOT_RUNNING`,
+`PROFILING_PERMISSION_REQUIRED`, `READINESS_TIMEOUT` and `TARGET_DISCONNECTED`
+include bounded recovery guidance; raw recorder output is not returned.
+
+Only the session-owned recorder is signalled; cleanup never terminates the app.
+iOS readiness has a 35-second budget, stop/finalisation 30 seconds and artifact
+validation 30 seconds. Recording is bounded by native duration and server
+monitoring. Monitoring retains the pinned app identity and tolerates two consecutive
+non-definitive command failures, resetting after a successful poll. The third
+fails capture with its bounded reason (`COMMAND_FAILED`, `ACTION_TIMEOUT`, or
+`TRACE_MONITOR_FAILED` for an unclassified failure). Storage limits, changed app
+identity and a missing running app fail immediately. Expiry and recorder exit
+are still checked after a tolerated poll failure. Shutdown attempts cancellation under an overall ten-second budget.
+Failed export can be retried using stop/status without starting another recording;
+cancel removes owned partial files. Completed artifacts remain for user deletion.
+
+The `.trace` result may be a bundle/directory. `artifact` adds
+`format:"instruments"`, `kind`, recursive `size_bytes`, and
+`validation:{readable,schema,sample_rows}`. Validation checks a readable TOC,
+matching target UUID/PID/template, `time-sample` schema and exported sample data.
+Zero rows mean no CPU sample evidence. Warnings are preserved as bounded
+classifications. This establishes readable capture, not successful symbolication,
+working hang detection or root-cause diagnosis. Do not treat a saved failed trace
+as a successful recording.
+
+Results also include `app_id`, `pid`, `executable`, `template`,
+`recording_ready_at_ms`, `warnings` and `clock_alignment:"unknown"`. The profiled
+app stays pinned even if the journey navigates elsewhere; linked IDs do not prove
+that other apps are captured. Start/stop during a linked journey reports partial
+coverage. Host capture bounds include startup/finalisation uncertainty.
+
+At least 1 GiB free output space is required before recording. The server checks
+a 256 MiB recursive size threshold each second; this is a soft limit and can be
+overshot during polling/finalisation. Oversized output fails and is discarded.
+Final bundles reject symlinks and use restricted file/directory permissions.
+Even app-attached capture may include sensitive system metadata, paths, symbols,
+logs and signposts. Keep artifacts local and delete them when finished; no upload,
+base64 response, permission bypass or restart-wide cleanup sweep occurs.
+
 ## Related guides
 
 - [Interaction](interact.md#interaction-execution-controls-rfc-018): run the journey being measured.
 - [Evidence correlation](correlated-evidence.md): interpret action and observation timing.
-- [Android runtime debugger](debugger.md): inspect paused application state.
+- [Runtime debugger](debugger.md): inspect paused application state.

package/docs/tools/system.md

@@ -10,6 +10,12 @@ required platform is available, continue with [device selection](manage.md#list_
 ## get_system_status
 A fast, non-throwing healthcheck that inspects key dependencies and connections required for mobile debugging.
 
+Android installation checks use `MCP_TARGET_PACKAGE` then `MCP_TARGET_APP_ID`.
+`appInstallations` contains device-specific installed/absent/unknown observations
+with app ID, device ID, scope and timestamp. Legacy `appInstalled` is omitted
+unless exactly one device has a conclusive result. Missing context and failed
+queries never establish absence; these fields do not report iOS installation.
+
 Input:
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {
@@ -19,6 +19,7 @@
     "test": "npm run test:unit",
     "lint": "eslint src test --quiet && npm run check:quality && npm run check:architecture",
     "lint:fix": "eslint src test --fix && npm run check:quality && npm run check:architecture",
+    "package:antigravity": "node scripts/agent-plugin.mjs --export-antigravity",
     "sync:agent-plugin": "node scripts/agent-plugin.mjs --sync",
     "check:quality": "node scripts/code-quality.mjs",
     "check:architecture": "node scripts/check-architecture.mjs",

package/scripts/agent-plugin.mjs

@@ -1,5 +1,5 @@
 import assert from 'node:assert/strict'
-import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { copyFileSync, cpSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import path from 'node:path'
 
@@ -43,22 +43,53 @@ const cursorManifest = {
     },
   },
 }
+const antigravityManifest = {
+  $schema: 'https://antigravity.google/schemas/v1/plugin.json',
+  ...sharedMetadata,
+  displayName: extensions['com.openai'].interface.displayName,
+  logo: 'assets/mobile-debug-tools.svg',
+  suggestedPrompts: extensions['com.openai'].interface.defaultPrompt,
+}
+const antigravityMcp = {
+  mcpServers: Object.fromEntries(Object.entries(codexMcp.mcpServers).map(([name, server]) => {
+    const { type: _transport, ...settings } = server
+    return [name, settings]
+  })),
+}
+const mcpConfigs = [
+  ['.mcp.json', codexMcp],
+  ['mcp_config.json', antigravityMcp],
+]
 const manifests = [
   ['.codex-plugin/plugin.json', codexManifest],
   ['.claude-plugin/plugin.json', claudeManifest],
   ['.cursor-plugin/plugin.json', cursorManifest],
+  ['.antigravity-plugin/plugin.json', antigravityManifest],
 ]
 
+const cursorFiles = [
+  ['.cursor-plugin/plugin.json', `${JSON.stringify(cursorManifest, null, 2)}\n`],
+  ['skills/mobile-debug-mcp/SKILL.md', readFileSync(packagedSkill)],
+  ['LICENSE', readFileSync(sourceLicense)],
+  ['README.md', '# Mobile Debug Tools for Cursor\n\nGenerated by `npm run sync:agent-plugin`; edit the canonical plugin source.\n\nCopy the contents of this directory into `~/.cursor/plugins/local/mobile-debug-tools`,\nthen run Developer: Reload Window and check Customize for the skill and MCP server.\nDo not copy the portable parent plugin: its `${PLUGIN_DATA}` variable is not expanded by Cursor.\n\nSetup and support: https://github.com/clivejefferies/mobile-debug-tools\n'],
+]
 if (process.argv[2] === '--sync') {
   copyFileSync(sourceLicense, packagedLicense)
-  writeFileSync(path.join(pluginRoot, '.mcp.json'), `${JSON.stringify(codexMcp, null, 2)}\n`)
+  for (const [relativePath, contents] of cursorFiles) {
+    const target = path.join(pluginRoot, 'cursor', relativePath)
+    mkdirSync(path.dirname(target), { recursive: true })
+    writeFileSync(target, contents)
+  }
+  for (const [relativePath, config] of mcpConfigs) {
+    writeFileSync(path.join(pluginRoot, relativePath), `${JSON.stringify(config, null, 2)}\n`)
+  }
   for (const [relativePath, manifest] of manifests) {
     const manifestPath = path.join(pluginRoot, relativePath)
     mkdirSync(path.dirname(manifestPath), { recursive: true })
     writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
   }
 }
-else if (process.argv[2] !== '--check') throw new Error('Use --sync or --check')
+else if (!['--check', '--export-antigravity'].includes(process.argv[2])) throw new Error('Use --sync, --check or --export-antigravity <new-directory>')
 
 assert.equal(plugin.$schema, 'https://agent-plugins.org/schemas/1.0.0/plugin.schema.json')
 assert.equal(plugin.name, 'mobile-debug-tools')
@@ -73,7 +104,10 @@ assert.equal(server.command, 'npx')
 assert.deepEqual(server.args, ['--yes', `${packageInfo.name}@${packageInfo.version}`, 'server'])
 assert.equal(server.cwd, '${PLUGIN_DATA}', 'npx must run outside the same-named source checkout')
 assert.deepEqual(readFileSync(packagedLicense), readFileSync(sourceLicense), 'packaged license must match its source')
-assert.deepEqual(JSON.parse(readFileSync(path.join(pluginRoot, '.mcp.json'), 'utf8')), codexMcp, 'Codex MCP configuration must match the portable plugin')
+for (const [relativePath, config] of mcpConfigs) {
+  assert.deepEqual(JSON.parse(readFileSync(path.join(pluginRoot, relativePath), 'utf8')), config, `${relativePath} must match the portable MCP configuration`)
+}
+assert.ok(readFileSync(path.join(pluginRoot, antigravityManifest.logo)).length > 0, 'Antigravity logo must be bundled')
 for (const [relativePath, expectedManifest] of manifests) {
   assert.deepEqual(
     JSON.parse(readFileSync(path.join(pluginRoot, relativePath), 'utf8')),
@@ -81,6 +115,9 @@ for (const [relativePath, expectedManifest] of manifests) {
     `${relativePath} must match the portable plugin`,
   )
 }
+for (const [relativePath, contents] of cursorFiles) {
+  assert.deepEqual(readFileSync(path.join(pluginRoot, 'cursor', relativePath)), Buffer.from(contents), `Cursor native ${relativePath} must match its source`)
+}
 for (const marketplacePath of [
   '.agents/plugins/marketplace.json',
   '.claude-plugin/marketplace.json',
@@ -90,9 +127,22 @@ for (const marketplacePath of [
   assert.equal(marketplace.name, plugin.name, `${marketplacePath} name must match the plugin`)
   assert.equal(marketplace.plugins.length, 1, `${marketplacePath} must expose one plugin`)
   assert.equal(marketplace.plugins[0].name, plugin.name, `${marketplacePath} plugin name must match`)
-  assert.equal(marketplace.plugins[0].source?.path ?? marketplace.plugins[0].source, './agent-plugin', `${marketplacePath} source must point to the plugin`)
+  assert.equal(marketplace.plugins[0].source?.path ?? marketplace.plugins[0].source, marketplacePath.startsWith('.cursor-plugin') ? './agent-plugin/cursor' : './agent-plugin', `${marketplacePath} source must point to the plugin`)
 }
 const skillName = readFileSync(packagedSkill, 'utf8').match(/^---\r?\nname: ([a-z0-9-]+)\r?\n/)?.[1]
 assert.equal(skillName, path.basename(path.dirname(packagedSkill)), 'packaged skill directory must match its frontmatter name')
 
 console.log('Agent plugin package is in sync')
+
+if (process.argv[2] === '--export-antigravity') {
+  assert.ok(process.argv[3], 'Supply a new output directory for the Antigravity export')
+  const target = path.resolve(process.argv[3])
+  // Refuse existing directories rather than overwrite source or stale package files.
+  mkdirSync(target)
+  writeFileSync(path.join(target, 'plugin.json'), `${JSON.stringify(antigravityManifest, null, 2)}\n`)
+  writeFileSync(path.join(target, 'mcp_config.json'), `${JSON.stringify(antigravityMcp, null, 2)}\n`)
+  copyFileSync(path.join(pluginRoot, '.antigravity-plugin/README.md'), path.join(target, 'README.md'))
+  copyFileSync(packagedLicense, path.join(target, 'LICENSE'))
+  for (const directory of ['skills', 'assets']) cpSync(path.join(pluginRoot, directory), path.join(target, directory), { recursive: true, filter: file => path.basename(file) !== '.DS_Store' && !path.basename(file).startsWith('._') })
+  console.log(`Antigravity package exported to ${target}`)
+}

package/src/contracts/device-readiness.ts

@@ -0,0 +1,8 @@
+export interface DeviceReadiness {
+  wakefulness: 'awake' | 'asleep' | 'transitioning' | 'unknown' | 'unsupported'
+  lock_state: 'locked' | 'unlocked' | 'unknown' | 'unsupported'
+  input_ready: false | null
+  blockers: Array<'DEVICE_ASLEEP' | 'DEVICE_LOCKED' | 'DEVICE_TRANSITIONING' | 'DEBUGGER_PAUSED'>
+  evidence: Array<{ code: string; source: string; captured_at_ms: number }>
+  limitations: string[]
+}

package/src/debugger/android.ts

@@ -3,7 +3,7 @@ import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
 import { DebuggerError, debuggerRemaining, debuggerSignal, nativeError } from './worker.js'
 const exec = promisify(execFile)
-export interface DebugTarget { app_id: string; pid: number; process_name: string; start_identity: string; uid: number }
+export interface DebugTarget { app_id: string; pid: number; process_name: string; start_identity: string; uid: number | null; executable_path?: string }
 export interface DebugNative {
   candidates(device: string, app: string): Promise<DebugTarget[]>
   identity(device: string, target: DebugTarget): Promise<DebugTarget>

package/src/debugger/guard.ts

@@ -5,7 +5,7 @@ interface PauseEvidence {
   captured_at_ms: number
   target: unknown
 }
-let pauseProvider: (device: string) => PauseEvidence | null = () => null
+let pauseProvider: (device: string, platform?: string) => PauseEvidence | null = () => null
 export function registerDebuggerPauseProvider(provider: typeof pauseProvider) { pauseProvider = provider }
 const context = new AsyncLocalStorage<{ platform: string; device: string; dispatched: boolean }>()
 export function withDebuggerGuard<T>(platform: string, device: string, operation: () => Promise<T>) {
@@ -14,13 +14,13 @@ export function withDebuggerGuard<T>(platform: string, device: string, operation
 // Synchronous checks and native submission share a JS turn with pause updates.
 export function checkDebuggerGuard(dispatch = false) {
   const current = context.getStore()
-  if (!current || current.platform !== 'android') return
-  if (pauseProvider(current.device)) throw new DebuggerError('DEBUGGER_PAUSED')
+  if (!current) return
+  if (pauseProvider(current.device, current.platform)) throw new DebuggerError('DEBUGGER_PAUSED')
   if (dispatch) current.dispatched = true
 }
 export function guardDispatched() { return context.getStore()?.dispatched ?? false }
-export function pausedReadiness(device: string) {
-  const paused = pauseProvider(device)
+export function pausedReadiness(device: string, platform = 'android') {
+  const paused = pauseProvider(device, platform)
   if (!paused) return null
   return { state: 'debugger_paused' as const, scope: 'device_ui' as const, basis: 'observed' as const,
     captured_at_ms: paused.captured_at_ms, sample_count: 0, stable_for_ms: 0, snapshot_session_id: null, snapshot_revision: null,

package/src/debugger/ios-worker.ts

@@ -0,0 +1,49 @@
+import { fileURLToPath } from 'node:url'
+import { getXcrunCmd } from '../utils/ios/utils.js'
+import { iosExec } from './ios.js'
+import { DebuggerProcess, type WorkerEvent, type DebugWorker } from './worker.js'
+import { DebuggerError } from './diagnostics.js'
+export const iosCapabilities = { attach: true, breakpoints: true, stacks: true, locals: true, step: true, resume: true,
+  evaluation: false, mutation: false, coroutines: false, native: false, async_execution_inspection: true, async_stepping: true }
+export const iosLimitations = ['IOS_SIMULATOR_ONLY', 'DEBUG_METADATA_REQUIRED', 'SHALLOW_LOCALS', 'ALL_THREADS_SUSPEND', 'DEVICE_WIDE_UI_GUARD', 'ASYNC_STEPPING_TOOLCHAIN_DEPENDENT', 'AGGREGATE_VALUES_TYPE_ONLY', 'NO_TASK_ENUMERATION']
+export const iosWorkerSource = fileURLToPath(new URL('../../src/debugger/lldb/worker.py', import.meta.url))
+let prepared: Promise<{ python: string; env: NodeJS.ProcessEnv }> | undefined
+export function prepareIOSWorker() {
+  prepared ??= (async () => {
+    if (process.platform !== 'darwin') throw new DebuggerError('DEBUGGER_UNSUPPORTED')
+    const pythonPath = await iosExec(getXcrunCmd(), ['lldb', '-P'])
+    const python = await iosExec(getXcrunCmd(), ['--find', 'python3'])
+    // Ignore user Python startup/customisation and LLDB init files.
+    const env = { PATH: process.env.PATH, HOME: process.env.HOME, PYTHONPATH: pythonPath, PYTHONNOUSERSITE: '1' }
+    const ready = await iosExec(python, ['-s', '-B', '-c', 'import lldb; d=lldb.SBDebugger.Create(False); print("ready" if d.IsValid() else "unavailable"); lldb.SBDebugger.Destroy(d)'], env)
+    if (ready !== 'ready') throw new DebuggerError('DEBUGGER_UNSUPPORTED')
+    return { python, env }
+  })().catch(error => { prepared = undefined; throw error })
+  return prepared
+}
+export async function createIOSWorker(onEvent: (event: WorkerEvent) => void) {
+  const { python, env } = await prepareIOSWorker()
+  let released = false
+  const worker = new DebuggerProcess(python, '', event => {
+    if (event.event === 'terminated' && ['process_exit', 'detached', 'pause_limit', 'idle_limit', 'session_limit'].includes(String(event.reason))) released = true
+    onEvent(event)
+  }, { args: ['-u', '-s', '-B', iosWorkerSource], env })
+  return new IOSWorker(worker, () => released)
+}
+/** A dead worker is not proof that its owned suspension was released. */
+export class IOSWorker implements DebugWorker {
+  private detached = false
+  constructor(private worker: DebugWorker, private released: () => boolean) {}
+  async call(command: string, args: Record<string, unknown> = {}, timeout = 10000) {
+    const result = await this.worker.call(command, args, timeout)
+    if (command === 'detach' && result.detached === true) this.detached = true
+    return result
+  }
+  async close() {
+    if (!this.detached && !this.released()) {
+      try { await this.call('detach', {}, 1000) } catch { /* Report uncertainty after bounded transport shutdown. */ }
+    }
+    await this.worker.close()
+    if (!this.detached && !this.released()) throw new DebuggerError('DEBUGGER_CLEANUP_FAILED')
+  }
+}

package/src/debugger/ios.ts

@@ -0,0 +1,45 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import path from 'node:path'
+import { realpath } from 'node:fs/promises'
+import { getXcrunCmd } from '../utils/ios/utils.js'
+import type { DebugNative, DebugTarget } from './android.js'
+import { DebuggerError, debuggerRemaining, debuggerSignal, nativeError } from './worker.js'
+const exec = promisify(execFile)
+export async function iosExec(file: string, args: string[], env?: NodeJS.ProcessEnv) {
+  try { return (await exec(file, args, { timeout: debuggerRemaining(5000), signal: debuggerSignal(), maxBuffer: 1024 * 1024, ...(env ? { env } : {}) })).stdout.trim() }
+  catch (e) { throw nativeError(e, 'DEVICE_UNAVAILABLE') }
+}
+export class IOSDebugNative implements DebugNative {
+  constructor(private run = iosExec) {}
+  private sim(args: string[]) { return this.run(getXcrunCmd(), ['simctl', ...args]) }
+  async candidates(device: string, app: string): Promise<DebugTarget[]> {
+    if (!/^[A-Fa-f0-9]{8}(?:-[A-Fa-f0-9]{4}){3}-[A-Fa-f0-9]{12}$/.test(device) || !/^[A-Za-z0-9][A-Za-z0-9.-]+$/.test(app)) throw new DebuggerError('INVALID_ARGUMENT')
+    const inventory = JSON.parse(await this.sim(['list', 'devices', 'booted', '--json'])) as { devices: Record<string, { udid: string; state: string }[]> }
+    if (!Object.values(inventory.devices).flat().some(d => d.udid === device && d.state === 'Booted')) throw new DebuggerError('DEBUGGER_UNSUPPORTED')
+    const services = await this.sim(['spawn', device, 'launchctl', 'list'])
+    const pids = this.processes(services, app)
+    if (!pids.length) return []
+    const container = await this.sim(['get_app_container', device, app, 'app'])
+    const executable = await this.run('/usr/bin/plutil', ['-extract', 'CFBundleExecutable', 'raw', '-o', '-', path.join(container, 'Info.plist')])
+    if (path.basename(executable) !== executable || !executable) throw new DebuggerError('PROCESS_NOT_FOUND')
+    const executablePath = await realpath(path.join(container, executable))
+    return Promise.all(pids.map(pid => this.identity(device, { app_id: app, pid, process_name: executable, executable_path: executablePath, start_identity: '', uid: null })))
+  }
+  private processes(services: string, app: string) {
+    return services.split('\n').flatMap(line => {
+      const [pid, , label] = line.trim().split(/\s+/)
+      return /^\d+$/.test(pid) && label?.startsWith(`UIKitApplication:${app}[`) ? [Number(pid)] : []
+    })
+  }
+  async identity(device: string, target: DebugTarget): Promise<DebugTarget> {
+    const services = await this.sim(['spawn', device, 'launchctl', 'list'])
+    if (!this.processes(services, target.app_id).includes(target.pid)) throw new DebuggerError('PROCESS_CHANGED')
+    const command = await this.run('/bin/ps', ['-ww', '-p', String(target.pid), '-o', 'comm='])
+    const started = await this.run('/bin/ps', ['-p', String(target.pid), '-o', 'lstart='])
+    if (command !== target.executable_path || !started || (target.start_identity && started !== target.start_identity)) throw new DebuggerError('PROCESS_CHANGED')
+    return { ...target, start_identity: started }
+  }
+  async forward(): Promise<number> { throw new DebuggerError('DEBUGGER_UNSUPPORTED') }
+  async removeForward() { throw new DebuggerError('DEBUGGER_UNSUPPORTED') }
+}

package/src/debugger/lldb/breakpoints.py

@@ -0,0 +1,51 @@
+"""Owned source breakpoints with exact-line checking, including late image loads."""
+import os
+import uuid
+import lldb
+
+
+class Breakpoints:
+    def __init__(self, target):
+        self.target = target
+        self.owned = {}
+
+    def describe(self, key):
+        bp, source, line = self.owned[key]
+        locations = []
+        rejected = False
+        for loc in bp:
+            entry = loc.GetAddress().GetLineEntry()
+            actual = str(entry.GetFileSpec())
+            exact = entry.IsValid() and os.path.normpath(actual) == source and entry.GetLine() == line
+            loc.SetEnabled(exact)
+            if exact:
+                locations.append({"source_file": actual, "line": line})
+            else:
+                rejected = True
+        known_source = self.target.FindCompileUnits(lldb.SBFileSpec(source)).GetSize() > 0
+        status = "resolved" if locations else "rejected" if rejected or known_source else "pending"
+        return {"breakpoint_id": key, "status": status, "locations": locations}
+
+    def set(self, args):
+        source = os.path.normpath(args["sourceFile"])
+        bp = self.target.BreakpointCreateByLocation(lldb.SBFileSpec(source), args["line"], 0, 0, lldb.SBFileSpecList(), False)
+        key = str(uuid.uuid4())
+        self.owned[key] = (bp, source, args["line"])
+        result = self.describe(key)
+        if result["status"] == "rejected":
+            self.target.BreakpointDelete(bp.GetID())
+            del self.owned[key]
+        return result
+
+    def refresh(self):
+        return [self.describe(key) for key in list(self.owned)]
+
+    def remove(self, key):
+        if key in self.owned:
+            bp, _, _ = self.owned.pop(key)
+            self.target.BreakpointDelete(bp.GetID())
+        return {"removed": True}
+
+    def clear(self):
+        for key in list(self.owned):
+            self.remove(key)

package/src/debugger/lldb/inspection.py

@@ -0,0 +1,109 @@
+"""Bounded, static inspection. Never evaluate expressions or object descriptions."""
+import uuid
+import re
+import lldb
+
+
+def location(frame):
+    entry = frame.GetLineEntry()
+    file = entry.GetFileSpec()
+    source = str(file)[:512] if file.IsValid() else None
+    return {"source_file": source, "line": entry.GetLine() if entry.IsValid() else None,
+            "method_name": (frame.GetFunctionName() or "")[:512], "class_name": None}
+
+
+class Inspection:
+    def __init__(self):
+        self.invalidate()
+
+    def invalidate(self):
+        self.stop_id = None
+        self.threads = {}
+        self.frames = {}
+
+    def stopped(self, process):
+        self.invalidate()
+        self.stop_id = str(uuid.uuid4())
+        selected = None
+        chosen = process.GetSelectedThread()
+        threads = [chosen] if chosen.IsValid() else []
+        for index in range(min(process.GetNumThreads(), 100)):
+            thread = process.GetThreadAtIndex(index)
+            if not chosen.IsValid() or thread.GetThreadID() != chosen.GetThreadID():
+                threads.append(thread)
+        for thread in threads[:100]:
+            key = str(uuid.uuid4())
+            self.threads[key] = thread
+            if selected is None and thread.GetStopReason() not in (lldb.eStopReasonNone, lldb.eStopReasonInvalid):
+                selected = key
+        if selected is None or process.GetState() != lldb.eStateStopped:
+            self.invalidate()
+            return None
+        thread = self.threads.get(selected)
+        return {"event": "stopped", "stop_id": self.stop_id, "thread_id": selected,
+                "reason": stop_reason(thread),
+                "location": location(thread.GetFrameAtIndex(0)) if thread else None,
+                "threads": [{"thread_id": key, "name": (t.GetName() or "")[:256]} for key, t in self.threads.items()],
+                "threads_truncated": process.GetNumThreads() > 100}
+
+    def thread(self, args):
+        if args.get("stopId") != self.stop_id or args.get("threadId") not in self.threads:
+            raise ValueError("DEBUGGER_STALE_REFERENCE")
+        return self.threads[args["threadId"]]
+
+    def stack(self, args):
+        thread = self.thread(args)
+        offset, limit = args.get("offset", 0), args.get("limit", 20)
+        count = min(thread.GetNumFrames(), 1000)
+        frames = []
+        for index in range(offset, min(count, offset + limit)):
+            frame = thread.GetFrameAtIndex(index)
+            key = self.stop_id + ":" + args["threadId"] + ":" + str(index)
+            if key not in self.frames and len(self.frames) >= 1000:
+                break
+            self.frames[key] = frame
+            frames.append({"frame_id": key, "index": index, **location(frame)})
+        return {"frames": frames, "truncated": count > offset + len(frames) or thread.GetNumFrames() > 1000}
+
+    def locals(self, args):
+        if args.get("stopId") != self.stop_id or args.get("frameId") not in self.frames:
+            raise ValueError("DEBUGGER_STALE_REFERENCE")
+        frame = self.frames[args["frameId"]]
+        values = frame.GetVariables(True, True, False, True, lldb.eNoDynamicValues)
+        result = []
+        for index in range(min(values.GetSize(), 100)):
+            value = values.GetValueAtIndex(index).GetNonSyntheticValue()
+            name, kind = (value.GetName() or "")[:256], (value.GetTypeName() or "")[:256]
+            if not value.GetError().Success():
+                result.append({"name": name, "type": kind, "availability": "unavailable"})
+                continue
+            primitive = value.GetType().GetTypeFlags() & (lldb.eTypeIsScalar | lldb.eTypeIsInteger | lldb.eTypeIsFloat)
+            text = value.GetValue() if primitive else None
+            # Swift value wrappers are not C scalars. Decode only standard primitive storage.
+            if kind in ("Swift.Int", "Swift.Int32", "Swift.Int64", "Swift.UInt", "Swift.Bool", "Swift.Double", "Swift.Float"):
+                storage = value.GetChildMemberWithName("_value").GetNonSyntheticValue()
+                if storage.IsValid() and storage.GetError().Success():
+                    text = storage.GetValue()
+            if kind == "Swift.Bool" and text in ("0", "1"):
+                text = "true" if text == "1" else "false"
+            result.append({"name": name, "type": kind, "value": text[:256] if text else None,
+                           "kind": "primitive" if text is not None else "object",
+                           "truncated": bool(text and len(text) > 256),
+                           "object_id": self.object_identity(value, kind) if text is None else None})
+        return {"availability": "available" if result else "unknown", "locals": result,
+                "reason": None if result else "EMPTY_OR_UNAVAILABLE_VARIABLE_METADATA",
+                "truncated": values.GetSize() > 100}
+
+    def object_identity(self, value, kind):
+        pointer = value.GetValue()
+        if pointer and re.fullmatch(r"0x[0-9a-fA-F]+", pointer):
+            return str(uuid.uuid5(uuid.UUID(self.stop_id), kind + ":" + pointer))
+        return None
+
+
+def stop_reason(thread):
+    if thread is None:
+        return "unknown"
+    return {lldb.eStopReasonBreakpoint: "breakpoint", lldb.eStopReasonPlanComplete: "step",
+            lldb.eStopReasonSignal: "signal", lldb.eStopReasonException: "exception",
+            lldb.eStopReasonWatchpoint: "watchpoint", lldb.eStopReasonExec: "exec"}.get(thread.GetStopReason(), "unknown")