mobile-debug-mcp 0.34.0 → 0.36.0

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

@@ -0,0 +1,205 @@
+# iOS runtime debugger verification — issue #70
+
+Date: 2026-11-04. Scope: [approved specification](spec.md).
+Implementation: existing eleven MCP debugger tools gain the optional simulator
+LLDB backend; Android remains on JDI. This is local source/build verification,
+not hosted CI, an installed package, a publication or physical-device evidence.
+
+## Environment and method
+
+macOS, Node 23.11.0 (repository requires >=22; hosted CI selects Node 22),
+Xcode 27.2/27B52, LLDB 2103.0.34.407 and Swift 6.4.2. Simulator:
+F9243BAF-62A8-4990-8A99-17F527F56FDA, iPhone 17 Pro, iOS 26.4.
+The disposable Swift fixture uses `-g -Onone`, targeting iOS 18 simulator.
+
+The runner communicates with a freshly built stdio MCP server. It checks actual
+source stops, stack frames and synthetic known-value locals; independent fresh
+MCP UI-tree assertions establish completion/cancellation and recovery. It does
+not infer logical task identity from opaque thread IDs or task/thread names.
+
+Installed idb can read UI trees but cannot inject HID with this Xcode: its
+SimulatorKit framework path is absent. Therefore fixture actions use a private
+command file, delivered by atomic rename and handled by the fixture main-loop
+timer. This is independent fixture control, not proof of successful MCP tap
+injection. Paused MCP taps are checked for rejection before dispatch. No
+production app instrumentation, source evaluation or security changes are used.
+
+## Evidence and results
+
+The final stable-build simulator journey **PASS**ed with real pause expiry enabled.
+[Compact evidence](evidence.json) records the exact server/fixture/test hashes,
+source stops and bounded synthetic values. Recomputing the final source/build hash
+matched the runtime fingerprint. Log: `/tmp/ios-debugger-final.log`.
+
+| Check | Result |
+| --- | --- |
+| Exact source binding; pending source; non-executable line rejection | PASS |
+| Core stack/locals and into/over/out | PASS: known=41, fresh result=42 UI |
+| Pause guard/readiness and stale references | PASS |
+| Cancelled event wait and usable running session | PASS |
+| Before/after await with nested async child and actor/main-actor transitions | PASS: known=42, after=43, fresh Async result 44 UI |
+| Step over await | PASS: source line 20 to line 21 in the resumed partial function |
+| Task cancellation | PASS: cancelled=true and fresh Task cancelled UI |
+| Real 60-second pause expiry | PASS: pause_limit, complete cleanup and fresh result UI |
+| Target process exit | PASS: disconnected state, complete cleanup and fixture relaunch |
+| Idempotent detach and server shutdown while paused | PASS: no remaining resources; independent fresh result UI |
+
+`npm run verify` **PASS**: lint/structural/architecture checks, TypeScript build,
+all 96 unit files and generated plugin consistency. Log:
+`/tmp/ios-debugger-final-verify.log`. The portable usage skill and generated Cursor
+copy now describe the advertised iOS backend; this does not install/update a
+connected or pinned published server.
+
+The broader device suite passed the final Android debugger regression, then
+**FAIL**ed on an Android interaction SDK request timeout (120000 ms); its original
+log does not identify the call. A focused assertion-identical retry with tool-name
+and elapsed-time logging **PASS**ed every call (approximately 47 seconds total).
+The timeout was not reproduced and its cause is unknown; no assertion, timeout,
+retry policy or interaction implementation was changed. Original and retry logs:
+`/tmp/ios-debugger-device-suite.log` and
+`/tmp/ios-debugger-interaction-retest.log`. The unchanged full-suite retry passed the Android debugger/interaction checks and
+both-platform screenshot/log/tree/correlated-evidence checks, then **FAIL**ed the
+last Android Perfetto active-shutdown cleanup assertion (one owned capture file
+still existed). Log: `/tmp/ios-debugger-device-suite-retry.log`.
+
+The same isolated Perfetto test then **PASS**ed on both unmodified HEAD
+`8bafc318a6342cf4585621d2108353836d40f72d` (archived and compiled in a temporary
+copy using the same dependencies) and the current build. Logs:
+`/tmp/ios-debugger-trace-baseline.log`, `/tmp/ios-debugger-trace-current.log`.
+This does not establish the original timeout/cleanup cause or prove it fixed.
+No tracing source, assertion or deadline was changed; no full device-suite pass
+is claimed. The failed check's exact owned artifact was removed through the
+existing identity-checking trace adapter. Final checks found no MCP capture files
+or ADB forwards. Debugger/coroutine test packages and Swift build directories were
+removed; unrelated installed fixtures were preserved. The iOS simulator was
+returned to its initial shutdown state; the Android emulator remains running.
+
+Independent unchanged iOS screenshot, log and UI-tree smoke checks **PASS**ed.
+Log: `/tmp/ios-debugger-ios-observations.log`. These establish observation delivery
+and structure, not a layout claim or successful HID input.
+
+The initial Android runtime, Kotlin locals and coroutine MCP regressions passed
+on emulator-5554, Android 16/API 36. Kotlin/stdlib 2.0.21, coroutines 1.9.0 and
+fixture JDK 17.0.11 used existing cached dependencies and `/tmp/pr96-kotlinc`.
+The debugger uses its ordinary Android Studio JBR discovery. Raw local logs:
+`/tmp/ios-debugger-android-regression.log`,
+`/tmp/ios-debugger-kotlin-regression.log`,
+`/tmp/ios-debugger-coroutine-regression.log`.
+
+`npm pack --dry-run --json` and explicit contents assertions passed for all three
+LLDB Python modules and compiled iOS backend modules. CI packaging assertions now
+cover these resources. This does not establish installed-package loading.
+
+## Findings resolved during development
+
+- Ignore internal LLDB transitions without stopped-thread evidence; consume LLDB
+  process events before reading public process/thread snapshots.
+- Keep fixture variables live across await. The original constant's scope had no
+  location in a resume partial function; requiring its later use preserved actual
+  `known=42` inspection. Assertions were retained, not replaced by availability.
+- Use LLDB's invalid-line sentinel for the error-reporting StepInto overload;
+  line zero is not that sentinel. Check native step errors before acknowledging.
+- Normalize Swift Bool static storage to textual true/false; never evaluate a
+  getter, formatter, expression or object description.
+- Preserve known suspension when a stale/invalid step is rejected. Diagnostic
+  lifecycle fallbacks cannot bypass pause guards.
+- Bound and reuse frame references; preserve cleanup uncertainty after lost worker
+  or process handles instead of treating process closure as confirmed release.
+- Classify signals/exceptions separately from completed steps. A synchronous
+  `simctl terminate` probe timed out while attached; the fixture now exits itself
+  to test actual process-exit cleanup without blocking the runner on a signal stop.
+- URL-based fixture control encountered a system confirmation. The simulator was
+  rebooted to clear this fixture-created prompt; URL control was removed. Atomic
+  file delivery avoids the timer observing a partially written command.
+
+These failed development observations remain distinct from successful reruns;
+none is represented as evidence that all environments or timings are covered.
+
+## Limits and review
+
+Physical iOS devices, other Xcode/Swift/runtime versions, optimized builds,
+installed/published-package operation, real device disconnect, forced host kill,
+long idle/absolute expiry and a late-loaded-image binding journey remain unrun.
+Pause expiry is checked live; idle/absolute expiry logic also has deterministic
+worker/host unit coverage. Pending source creation is checked independently.
+
+Swift strings and other aggregate locals expose type/opaque reference summaries;
+standard supported numeric/bool wrappers use static storage. Missing debug values
+remain explicitly unavailable. No suspended-task enumeration or complete logical
+async-stack reconstruction is exposed. Async stepping evidence is the tested
+step-over-await route, not every Swift concurrency construct.
+
+Focused review covers target membership/start identity, source resolution, strict
+schema/dispatch parity, bounded IPC/inspection, stop epochs, diagnostic privacy,
+platform guards, expiry and owned teardown. Android contract compatibility remains
+covered by its existing fixture and unit tests; iOS scope is simulator-only.
+
+
+## PR #103 preparation-cache follow-up — 2026-11-04
+
+[Review comment](https://github.com/clivejefferies/mobile-debug-tools/pull/103#discussion_r4470121366)
+identified duplicated prerequisite subprocesses during attach. Preparation now
+shares its in-flight/successful promise per server process and clears a rejected
+promise, preserving platform checks, readiness validation and worker configuration.
+No tool schema, timeout or inspection behaviour changes.
+
+- **PASS** isolated fake-toolchain regression: concurrent calls share preparation,
+  failure permits retry, successful configuration is reused, and worker creation
+  adds no extra prerequisite probes.
+- **PASS** real Xcode preparation followed by cached reuse within a 100 ms budget;
+  no app was attached by that probe.
+- **PASS** focused real iOS MCP runtime/async/cancellation/process-exit/shutdown
+  journey on the same simulator/toolchain. Build fingerprint:
+  `0200deeb0cff9f04b54ed929258ebd19185c8be86e2badb6cdcbfa21f798fdb1`.
+  Source fingerprint remains `295ff0f30f5670530f9cdd7073b958917c1c574ccca9c7b921e295d0d902b699`.
+  Log: `/tmp/pr103-cache-ios.log`. Extended pause expiry was not repeated for
+  this preparation-only fix; the earlier extended evidence remains above.
+- **PASS** quiet `npm run verify`: lint/quality/architecture, build, all 97 unit
+  files and plugin consistency. Log: `/tmp/pr103-cache-verify-final.log`.
+  A prior run alongside native testing failed the unchanged conditional-action
+  timing assertion. Its isolated retry passed, as did the quiet full verification;
+  no assertion or timeout was modified. Original/retry logs:
+  `/tmp/pr103-cache-verify.log`, `/tmp/pr103-cache-conditional-retest.log`.
+
+The regression child loads its TypeScript toolchain before platform emulation,
+so the host retains its native compiler selection on Linux. This test-only ordering
+adjustment also passed all 97 files in `npm run verify` (log:
+`/tmp/pr103-cache-portable-verify.log`). The preparation fix was published in
+`f00e9fd`, and its review thread was resolved; both hosted unit-test runs passed
+that commit. Later PR-head checks must be assessed separately.
+
+The broader device-suite failures above remain separate; this fix does not claim
+that their causes were established or corrected. Simulator shutdown was restored.
+
+
+## PR #103 stored-handle guard follow-up — 2026-11-04
+
+[Outside-diff review finding](https://github.com/clivejefferies/mobile-debug-tools/pull/103#pullrequestreview-5772655824):
+`tap_element` could execute on its stored iOS handle's device while the central
+guard selected Android when platform hints were omitted. The guard now obtains
+its target through the same handle/platform/device validation used by execution.
+Other tool defaults remain unchanged; explicit conflicting hints still reject
+handle use rather than retargeting input.
+
+- **PASS** regression using real handle creation with mocked device/UI/input
+  boundaries: omitted/partial hints select the stored iOS device, known pauses
+  prevent UI reads/input, a racing pause prevents native dispatch, and unrelated
+  platforms/devices remain usable. Mismatched and missing handles retain rejection.
+- **PASS** mutation check: restoring the original Android-default guard route
+  makes that regression fail; fixed source was restored before verification.
+- **PASS** `npm run verify`: lint/quality/architecture, build, all 98 unit files,
+  and plugin consistency. Log: `/tmp/pr103-handle-verify.log`.
+- **PASS** updated real simulator MCP journey: obtain an iOS handle while running,
+  stop at a source breakpoint, then call `tap_element` with only that handle and
+  controls, omitting both platform and device ID. Observed `DEBUGGER_PAUSED`,
+  `delivery_status: not_delivered`, `dispatch_started: false`, and the correct
+  iOS debugger/device metadata. This proves pause rejection, not successful HID
+  injection. The existing core/async/cancellation/process-exit/shutdown journey
+  also passed on the same Xcode/LLDB/Swift/runtime matrix.
+
+Native build fingerprint:
+`28e56d77b9ba4caad778c223306609c3bb284b210b1ea996b927aca47134cf55`.
+Log: `/tmp/pr103-handle-ios.log`. No fixture source change or timeout/assertion
+weakening was needed. Device tests were run after repository verification to keep
+the checks separate. The fixture was removed and simulator shutdown restored.
+The earlier broader-suite limitations remain recorded above.

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

@@ -1,27 +1,40 @@
-# Tools index
+# Tool reference
 
-This repository groups the MCP tools into four areas aligned with the codebase:
+[Documentation](../README.md)
 
-- [manage](manage.md) — build, install, launch, restart, and device-management tools
-- [observe](observe.md) — screenshots, logs, UI trees, fingerprints, and debug snapshots
-- [interact](interact.md) — UI resolution, actions, waits, and deterministic verification
-- [system](system.md) — environment and health checks
+Use the guides below when you need a tool contract or a specific workflow.
 
-Correlation metadata and explicit action references are documented in
-[correlated evidence](evidence.md). Android performance capture is documented in
-[system traces](system-traces.md). Android bytecode debugging is documented in
-[runtime debugger](debugger.md).
+## Reference guides
 
-## Agent guidance
+- [App management](manage.md) — build, install, launch, restart, and device management.
+- [Observation](observe.md) — screenshots, logs, UI trees, fingerprints, debug snapshots, and app readiness.
+- [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.
+- [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.
 
-For interactive flows, the intended deterministic pattern is:
+## Interaction principles
 
-**RESOLVE -> ACT -> WAIT (if needed) -> EXPECT**
+Interactive flows follow a common sequence:
 
-- **wait_for_\*** tools are for resolution and synchronization
-- **expect_\*** tools are for final outcome verification
-- observation tools are supporting context, not primary success signals
+**RESOLVE → ACT → WAIT (if needed) → EXPECT**
 
-For environment-sensitive work, call `get_system_status` first so the client can rely on automatic discovery when it is available and fall back to explicit tool paths only when needed.
+- Resolution identifies the target before an action.
+- Actions report execution; successful dispatch alone does not establish the intended outcome.
+- `wait_for_*` tools resolve targets and synchronize with UI changes.
+- `expect_*` tools verify the final outcome using explicit assertions.
+- Observation tools provide evidence for targeting, assertions, and diagnosis; collecting evidence alone does not establish success.
+- `get_system_status` identifies available toolchains and missing prerequisites before environment-sensitive operations. Explicit tool paths override automatic discovery when needed.
 
-Use the linked documents below for per-tool inputs, outputs, and usage guidance.
+## Reading examples
+
+Inputs are MCP tool arguments, not shell commands. Replace example device IDs,
+app identifiers, and UI labels with values from your environment. Response
+examples show relevant fields and may omit optional metadata, execution traces,
+and [evidence correlation](correlated-evidence.md). Clients receive JSON in MCP
+text content blocks, with additional image blocks for screenshot tools.
+
+Parameter spelling varies by tool: for example, standalone UI waits use
+`timeout_ms`, while journeys and readiness tools use `timeoutMs`. Follow the
+individual tool's input contract rather than translating names between tools.

package/docs/tools/{evidence.md → correlated-evidence.md}

@@ -1,4 +1,12 @@
-# Correlated evidence
+# Evidence correlation
+
+[Documentation](../README.md) · [Tool reference](TOOLS.md)
+
+Use evidence correlation to connect an action with later screenshots, UI trees,
+and logs, and to understand when those observations were captured. Association
+does not prove that the action caused an observed change.
+
+## Associate an observation with an action
 
 Covered actions (`start_app`, `restart_app`, `tap`, `tap_element`, `swipe`,
 `scroll_to_element`, `type_text`, `press_back`, `adjust_control`) return an

package/docs/tools/debugger.md

@@ -1,4 +1,6 @@
-# Android runtime debugger
+# Runtime debugger
+
+[Documentation](../README.md) · [Tool reference](TOOLS.md)
 
 Optional managed Java/Kotlin bytecode debugging through an independently developed
 JDI worker. Requires JDK 17+ (`java`, `javac`, `jdk.jdi`), Android platform-tools,
@@ -50,6 +52,54 @@ Failures carry `error: {code, message, retryable}`. Event polls use top-level
 `events`, `next_cursor`, `overflow`, `timed_out`; empty waits are successful.
 The 256-event ring returns at most 100 entries; overflow must not be ignored.
 
+## Response modes
+
+All eleven debugger tools accept `responseMode: "compact" | "debug"` (default
+`"debug"`, the existing full response). Selection applies only to the current call.
+For routine session commands, compact mode omits only top-level `device`, `target`
+and `capabilities` when `debug_session_id` is non-null. Attach, capabilities and
+state calls retain their full payload in either mode. Use `get_debugger_state`
+or request `debug` to recover target/capability context.
+
+Errors and sanitized diagnostics, identifiers, stop and execution state, event
+cursors/overflow, limitations, truncation and cleanup remain intact. Unknown
+session IDs still fail explicitly. Compact mode does not redact locals or prove
+execution resumed: detach retains `execution_state: "unknown"`. Retry incomplete
+cleanup according to its remaining resources. Invalid modes are rejected.
+
+## Failure diagnostics
+
+Debugger operation failures add `error.diagnostic: {stage, reason, recovery}` while
+preserving existing error codes, messages and retryability. `stage` identifies
+prerequisite checks, compilation, worker startup, IPC, target resolution,
+forwarding, JDI attach, command execution, transport or cleanup; `unknown` is
+explicit when evidence is insufficient. `reason` is a fixed classification,
+such as `spawn_failed`, `process_exited`, `invalid_message`, `message_limit`,
+`write_failed`, `connection_refused`, `transport_lost`, `timeout` or `cancelled`.
+Remaining catalog values and the exact schema are defined in the
+[accepted specification](../specs/027-debugger-failure-diagnostics/spec.md).
+
+`recovery` is static guidance, not raw stderr or exception text. Each diagnostic
+is at most 512 UTF-8 bytes with guidance at most 240 ASCII characters. Untrusted
+worker fields are validated and reconstructed. No new logging or app-value
+collection is introduced. Startup classification means no valid worker reply had
+yet arrived; it does not establish the underlying cause of an unexpected exit.
+Argument, stale-reference and pause/state validation errors may omit diagnostics.
+
+Capability probes retain `success: true` and `supported: false` for unavailable
+prerequisites; optional top-level `diagnostics` contains at most two entries,
+ordered JDK then target. Successful probes omit it. Terminal session failures
+retain sanitized diagnostics until normal summary expiry, even after inspection
+data is cleared. A cleanup failure has its own diagnostic; inspect the existing
+session reason and `cleanup.remaining_resources` as well.
+
+Follow recovery guidance and inspect session/cleanup state before another
+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.
+These details describe Android; see the iOS simulator backend below for its prerequisites and recovery guidance.
+
 ## Suspension, limits and cleanup
 
 Stops suspend all app threads. UI actions, app lifecycle/data changes, waits and
@@ -58,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.
 
@@ -84,21 +134,87 @@ 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.
 Worker heap is capped at 128 MiB; IPC and messages are bounded; forwarding remains loopback-only.
 
+For Kotlin, stop after a local's assignment before expecting its value. A stop
+on the assignment line may precede initialization and the compiler's variable
+scope. Compare source location and emitted debug tables before classifying a
+missing local as a debugger failure. The isolated
+[Kotlin validation](../specs/029-kotlin-locals-validation/report.md) covers a plain
+calculation; it does not establish coroutine, inline/suspend, optimized or
+obfuscated-code support.
+
+An opt-in [coroutine fixture](../../test/fixtures/coroutine-app/README.md) assesses
+source breakpoints across suspension, dispatcher changes, nested work and
+cancellation with explicit Kotlin/coroutine dependencies. Use source breakpoints
+at both sides of a suspension point and inspect each actual stop. A thread-based
+step may stop in generated coroutine code; its acknowledgement does not establish
+that it followed a coroutine. Stop/thread/frame references expire when execution
+resumes. Shallow locals do not expose spilled continuation fields or reconstruct
+parent/child coroutine identity. The [assessment record](../specs/030-android-coroutine-validation/report.md)
+distinguishes device evidence from follow-up proposals.
+
 Verified environments and remaining checks are recorded in
 [the implementation plan](../specs/025-android-runtime-debugger/plan.md).
 To run the isolated fixture journey (installs then removes its own test package):
 
 ```sh
 MCP_DEBUGGER_DEVICE=emulator-5554 npx tsx test/device/automated/debugger/runtime.android.test.ts
+# Exercise opt-in compact responses across the same assertions:
+MCP_DEBUGGER_DEVICE=emulator-5554 MCP_DEBUGGER_RESPONSE_MODE=compact npx tsx test/device/automated/debugger/runtime.android.test.ts
 # Also exercise the real 60-second pause expiry:
 MCP_DEBUGGER_DEVICE=emulator-5554 MCP_DEBUGGER_EXTENDED=1 npx tsx test/device/automated/debugger/runtime.android.test.ts
 ```
 
 The ordinary device suite explicitly reports this journey unrun unless the device
 is selected. Fixture compilation requires SDK platform/build-tools 36 and `javac -g`.
+
+## Related guides
+
+- [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.