mobile-debug-mcp 0.35.0 → 0.36.0

package/docs/specs/032-ios-runtime-debugger/spec.md

@@ -0,0 +1,153 @@
+# iOS runtime debugger — specification
+
+Source: [issue #70](https://github.com/clivejefferies/mobile-debug-tools/issues/70).
+Scope: [accepted intent](intent.md), approved by the user's “ok” on 2026-11-04.
+Status: **approved** by the user's “ok” on 2026-11-04 in response to the complete
+specification and approval request in this chat. Implementation authorised.
+
+## Behaviour and supported environment
+
+Add optional LLDB-backed debugging for an already-running development app on an
+explicit iOS simulator UDID, on macOS with full Xcode and its Swift-enabled LLDB.
+Initial verification targets the installed Xcode 27.2, LLDB 2103.0.34.407 and Swift
+6.4.2 toolchain; other versions remain unverified until separately exercised.
+Physical devices, remote hosts and production/optimised apps are unsupported in
+this initial matrix. Normal mobile tools must not acquire an LLDB dependency.
+
+Provide source breakpoints, stop events, bounded stacks and shallow locals,
+into/over/out stepping, resume and detach through the existing eleven tools.
+Attach may briefly stop the process for setup, but returns running unless an
+actual stop event has been retained; never discard a racing breakpoint stop.
+LLDB stops suspend the target process, not the whole simulator.
+
+## Tool contract and compatibility
+
+Extend `get_debugger_capabilities` and `attach_debugger` to accept
+`platform: "android" | "ios"`, existing explicit `deviceId`, `appId` and optional
+positive `processId`. For iOS, require a simulator UDID and valid bundle identifier.
+Probe without attaching or launching the app. Report missing prerequisites,
+unsupported target types, absent apps/processes and ambiguous candidates
+explicitly. A probe cannot guarantee that later attach permission will succeed.
+
+Preserve all existing Android requests. Extend `set_debugger_breakpoint` with
+optional `sourceFile` (nonempty absolute local source path, maximum 512 characters).
+Require exactly one of `className` or `sourceFile`, with the existing positive
+1-based `line`. Android sessions require `className`; iOS sessions require
+`sourceFile`. Invalid combinations fail `INVALID_ARGUMENT`. Resolve the full
+path against loaded debug information, never a basename fallback or shell search.
+Return owned breakpoint ID, pending/resolved/rejected status and actual locations.
+Unloaded images can remain pending. Only exact executable line matches may be
+enabled; locations silently moved by LLDB are rejected and removed.
+
+Keep session, stop, thread and frame arguments, tool names, response modes,
+pagination, defaults and timeout bounds unchanged. Existing common response and
+error shapes remain: `success`, session/target/device metadata, state, timestamp,
+capabilities, limitations, cleanup, reason, stop, operation `result`, and sanitized
+`error: {code, message, retryable, diagnostic?}`. Device platform is correct on
+success and failure. iOS target metadata carries bundle ID, PID, executable name,
+process-start identity and nullable UID; Android retains its existing fields.
+
+Capability values are backend-specific. iOS advertises supported core operations;
+`evaluation`, `mutation`, `coroutines` and `native` remain false (`native` denotes
+an exposed native-specific inspection capability, not LLDB's implementation).
+Add iOS-only boolean `async_execution_inspection` and `async_stepping`; the former
+requires the async acceptance journey below, the latter a separate demonstrated
+step across suspension. False values carry explanatory limitations. No suspended
+task enumeration, task identity API or logical-task reconstruction is promised.
+Preserve compact mode's existing omissions and full attach/capabilities/state
+responses. Unknown fields remain rejected.
+
+## Async semantics
+
+Source breakpoints must work before and after a controlled Swift `await`, with
+useful known primitive locals at each actual stop. Include nested child work,
+actor/executor transitions and a separately triggered task cancellation path.
+Use deterministic fixture gates and completion/cancellation UI state.
+
+Stepping acknowledges delivery and resumes; only a subsequent event establishes
+where execution stopped. Exercise ordinary helper into/over/out and an `await`
+boundary. Delegate stepping to Swift-enabled LLDB; do not equate a physical
+thread ID with stable task identity. If the tested LLDB route follows the async
+continuation, report the observed source stop and advertise `async_stepping`.
+Otherwise report it false with the limitation and demonstrate recovery through
+independent after-await breakpoints. Unexpected missing async locals or source
+stops fail core async acceptance rather than being labelled support.
+
+Stacks describe LLDB's observed frames; label unavailable source/variable data
+and generated frames honestly. Do not claim a complete logical async ancestry.
+No expression evaluation, object descriptions, custom formatters that execute
+code, property getters, dynamic method calls or continuation-field traversal.
+
+## Ownership, failure and safety
+
+Resolve simulator, bundle executable and running PID together; validate executable
+path, start identity and simulator membership before and after attach. Never attach
+to an arbitrary host PID, launch a missing app or replace another debugger.
+Reject identity changes and duplicate owned sessions. Serialize session mutations;
+isolate sessions and guards by platform plus device, including identical IDs.
+
+Reuse stop-scoped opaque references, the 256-event ring/100-event response limit,
+1000-frame cap, default 20/max 100 stack page, max 100 locals and 256-character
+string bound. Object locals expose type/opaque identity only. Missing or
+inaccessible variables are explicit; an empty list cannot prove availability.
+
+Generalise pause guards/readiness to iOS lifecycle actions, input, waits and
+assertions. Preserve device-wide conservative guarding, racing-dispatch
+uncertainty and observation access within existing deadlines. Do not claim
+foreground identity from debugger state.
+
+Use a dedicated owned LLDB worker with bounded structured IPC, argument-array
+subprocess calls, disabled user init files and no arbitrary command interface.
+Sanitize errors using the existing bounded diagnostic catalog; iOS recovery
+guidance names Xcode/LLDB rather than JDK/ADB. Never log worker messages, locals,
+raw stderr, exception text or source contents. Debug inspection stays local and
+request-scoped; public evidence uses only the disposable fixture.
+
+Retain 100–30000 ms request bounds, 60-second pause, five-minute idle and
+30-minute session expiry, including independent worker watchdogs. Event-wait
+cancellation preserves a usable session. Inspection timeouts preserve a known
+session; uncertain attach or mutation outcomes trigger owned teardown and report
+execution uncertainty. No automatic retries of attach/step/resume.
+
+Detach releases owned suspension, breakpoints, step plans and worker resources;
+never kill the app, another debugger or simulator. EOF/shutdown/expiry attempt
+detach. Cleanup is idempotent and retryable with explicit remaining resources;
+transport loss or forced host termination cannot imply confirmed recovery.
+
+## Acceptance and verification
+
+1. Real MCP simulator journey: attach, exact and pending source breakpoint,
+   stop, source stack, known locals, helper stepping, resume, removal and detach.
+2. Async journey: before/after-await locals, nested work and executor transition,
+   completion, cancellation recovery, and recorded boundary-step outcome.
+3. Safety: stale references, cross-session/device isolation, paused input and
+   readiness, cancelled event wait, process exit, attach failure, timeout,
+   automatic expiry and repeatable cleanup. Verify app usability after detach.
+4. Contract checks cover registration, runtime validation, dispatch, both response
+   modes, diagnostics and Android compatibility. Run `npm run verify`, applicable
+   `npm run test:device`, focused iOS MCP journeys and Android debugger regressions.
+5. Record fixture/server hashes, Xcode/LLDB/Swift/runtime versions, target UDID,
+   exact actions, observed values and independent UI-tree assertions. Report
+   physical-device and unavailable coverage as unrun, never inferred.
+
+Likely affected areas: `src/debugger/`, debugger schemas/handlers/serialization,
+iOS interaction/readiness boundaries, fixture/device/unit trees, packaging and
+debugger tool documentation/README/changelog. Reuse worker/session abstractions
+without routing Android through LLDB. Main risks are simulator process attribution,
+LLDB/Python distribution, async metadata, source relocation and teardown races.
+
+## Investigation evidence and remaining prerequisites
+
+On 2026-11-04, local version probes found the toolchain above. Sandboxed simctl
+could not contact CoreSimulator; an authorised outside-sandbox read succeeded and
+found no booted simulators. No existing iOS debugger implementation or live iOS
+debug journey is claimed. Implementation verification requires booting an
+available simulator and installing only the disposable development fixture.
+
+Apple documents async-aware stepping since Swift 6.2 in
+[What's new in Swift](https://developer.apple.com/videos/play/wwdc2025/245/).
+The [LLDB SBFrame API](https://lldb.llvm.org/python_reference/lldb.SBFrame-class.html)
+provides frame-variable access. These support the proposed route, not proof of
+this server's behaviour; exact worker loading, attach and safe variable extraction
+must be validated before claiming support. If unavailable, record the concrete
+blocker and return for a scope decision rather than weakening acceptance.

package/docs/tools/TOOLS.md

@@ -11,8 +11,8 @@ Use the guides below when you need a tool contract or a specific workflow.
 - [Interaction](interact.md) — UI resolution, actions, waits, and deterministic verification.
 - [Environment diagnostics](system.md) — toolchain discovery and health checks.
 - [Evidence correlation](correlated-evidence.md) — action references, capture timing, and freshness.
-- [Android system traces](system-traces.md) — performance capture and local Perfetto artifacts.
-- [Android runtime debugger](debugger.md) — process attachment, breakpoints, and bounded runtime inspection.
+- [System traces](system-traces.md) — Android Perfetto and iOS simulator Time Profiler capture with local artifacts.
+- [Android and iOS simulator runtime debugger](debugger.md) — process attachment, breakpoints, and bounded runtime inspection.
 
 ## Interaction principles
 

package/docs/tools/debugger.md

@@ -1,4 +1,4 @@
-# Android runtime debugger
+# Runtime debugger
 
 [Documentation](../README.md) · [Tool reference](TOOLS.md)
 
@@ -98,7 +98,7 @@ state-changing command. Timeout or cancellation does not prove nondelivery.
 Retry incomplete cleanup with `detach_debugger`; never automatically retry
 attach, step or resume, or kill the app/ADB server. Diagnostics improve failure
 classification and do not establish the cause of a previously intermittent error.
-This contract applies to the Android backend; iOS debugging remains unsupported.
+These details describe Android; see the iOS simulator backend below for its prerequisites and recovery guidance.
 
 ## Suspension, limits and cleanup
 
@@ -108,8 +108,8 @@ racing input submission preserves delivery uncertainty and blocks verification.
 Journeys preserve completed steps. Other devices are unaffected.
 
 `get_app_readiness` returns evidence-backed `debugger_paused` without reading the
-UI; readiness waits fail with `DEBUGGER_PAUSED`. This signal covers managed Android
-sessions only and does not establish foreground app identity. Raw trees, screenshots
+UI; readiness waits fail with `DEBUGGER_PAUSED`. This signal covers managed Android and iOS simulator
+sessions and does not establish foreground app identity. Raw trees, screenshots
 and logs remain available within their own timeouts; snapshot/log acquisition may
 still fail while the app is suspended. Known pauses are annotated on observations.
 
@@ -134,7 +134,7 @@ step, resume or attach.
 ## Limits, privacy and evidence
 
 There is no expression evaluation, object traversal, method invocation, mutation,
-coroutine reconstruction, native debugger, iOS debugger or heap capture. Kotlin
+coroutine reconstruction, native-specific inspection or heap capture. The optional iOS simulator backend is described below. Kotlin
 results follow emitted bytecode/debug metadata; optimized/obfuscated apps may lack
 useful source lines or locals. Locals may contain private data: values are returned
 only on request, without protocol/value logging, persistent dumps or upload.
@@ -178,3 +178,43 @@ is selected. Fixture compilation requires SDK platform/build-tools 36 and `javac
 - [App management](manage.md): build, install, and launch the app before attaching.
 - [App readiness](observe.md#app-readiness): understand known debugger-pause evidence.
 - [Android system traces](system-traces.md): investigate performance without paused-state inspection.
+
+## iOS simulator backend
+
+The same eleven tools accept `platform: "ios"` for target capability probes and
+attach. Supply an explicit booted simulator UDID and bundle `appId`; an optional
+`processId` must belong to that simulator's installed app. Requires macOS and full
+Xcode with its Swift-enabled LLDB and Python bindings. Physical iOS devices remain
+unsupported. Attach never launches an app, chooses a host process by name alone,
+replaces another debugger, or changes security settings.
+
+For `set_debugger_breakpoint`, supply `sourceFile` (absolute local source path)
+and 1-based `line` for iOS; continue using binary `className` for Android. Exactly
+one selector is required. iOS reports `resolved`, `pending` or `rejected` with
+actual locations; LLDB line relocation is disabled. Pending breakpoints may bind
+when their image loads. Other tool arguments, stop-scoped references, stack/locals
+limits, event cursors, response modes and expiry durations follow the flow above.
+
+iOS returns backend-specific capabilities and limitations; `target.uid` may be
+null and `target.executable_path` identifies the verified simulator executable.
+`async_execution_inspection` and `async_stepping` are independent capability flags.
+False means the capability is not established for the backend's supported matrix;
+inspect the limitations. A source breakpoint after await and a shallow local do
+not enumerate suspended tasks or establish logical task identity. Step requests
+acknowledge delivery; inspect the subsequent actual stop. Object locals expose
+only bounded type/opaque identity; Swift standard numeric/bool wrappers are read
+from static storage; Swift strings and other aggregates retain type summaries. No expressions, descriptions, dynamic getters or arbitrary
+LLDB commands execute through this API.
+
+Known iOS pauses guard lifecycle actions, input, waits and assertions on that
+platform/device and supply `debugger_paused` readiness. Raw observations remain
+available within their own deadlines. Detach removes owned breakpoints and worker
+resources and releases owned suspension; it never kills the app or simulator.
+A worker exit without confirmed detach/process exit cannot prove cleanup; retry
+`detach_debugger` and inspect `cleanup.remaining_resources`. Failure diagnostics
+provide static Xcode/LLDB-specific recovery guidance without raw worker text.
+
+Use the [isolated simulator fixture](../../test/fixtures/ios-debugger-app/README.md)
+for real MCP runtime and async checks. The [implementation plan](../specs/032-ios-runtime-debugger/plan.md)
+records exact verification and unavailable coverage. An installed/published package,
+physical device, or other Xcode version requires separate evidence.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.35.0",
+  "version": "0.36.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/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')
+  }
+}