mobile-debug-mcp 0.33.0 → 0.34.0

package/docs/specs/025-android-runtime-debugger/spec.md

@@ -0,0 +1,182 @@
+# Specification: Android runtime debugger
+
+Date: 2026-10-30. Status: approved.
+Intent: [approved intent](intent.md), approved by the user's “yes” in this conversation.
+Source: [issue #68](https://github.com/clivejefferies/mobile-debug-tools/issues/68).
+
+## Behaviour and supported environment
+
+Provide managed Java/Kotlin bytecode debugging of running, debuggable Android
+apps using an independently developed Java JDI worker over ADB-forwarded JDWP.
+No Debroid implementation or artifacts are reused. Require host JDK 17+ with
+`jdk.jdi` and `javac`, Android platform-tools, an authorized Android device, and
+a JDWP-visible app process. Package worker sources with the npm distribution;
+compile into a private, version-keyed host cache on first use. Missing tooling
+must not prevent ordinary MCP tools or server startup.
+
+Initial verification target: API 36 arm64 emulator; other Android versions and
+physical devices require separate evidence. iOS, native frames, expression
+evaluation, method invocation, mutation, coroutine reconstruction, heap capture,
+launch-under-debugger, and changing app debuggability are excluded. Kotlin
+inspection follows emitted JVM/DEX debug metadata; do not promise source-level
+coroutine or inline-function reconstruction.
+
+## MCP contracts
+
+All new inputs reject unknown fields. Strings are nonempty and bounded to 512
+characters unless otherwise stated; IDs are opaque server-issued strings.
+Every tool accepts `timeoutMs` (integer 100–30000, default 10000); event waits
+default to 1000. Tables list other inputs; `?` means optional.
+
+| Tool | Inputs | Result payload |
+| --- | --- | --- |
+| `get_debugger_capabilities` | `platform: android`, `deviceId`, `appId`, `processId?` | Prerequisites, candidate processes, supported operations and limitations; no attach |
+| `attach_debugger` | `platform: android`, `deviceId`, `appId`, `processId?` | Session and resolved target |
+| `get_debugger_state` | `debugSessionId` | Current state, stop summary, breakpoint statuses, cleanup |
+| `set_debugger_breakpoint` | `debugSessionId`, `className`, `line` | Breakpoint ID, requested/resolved locations, `pending`/`verified`/`rejected` |
+| `remove_debugger_breakpoint` | `debugSessionId`, `breakpointId` | Removal outcome; repeated removal of an owned ID succeeds |
+| `wait_for_debugger_event` | `debugSessionId`, `afterSequence?` | Ordered events, next cursor and explicit overflow indication |
+| `get_debugger_stack` | `debugSessionId`, `stopId`, `threadId`, `offset?`, `limit?` | Frames, opaque frame IDs and pagination |
+| `get_debugger_locals` | `debugSessionId`, `stopId`, `frameId` | Bounded shallow local values and availability |
+| `step_debugger` | `debugSessionId`, `stopId`, `threadId`, `kind: into/over/out` | Acknowledged transition to running; await a later event separately |
+| `resume_debugger` | `debugSessionId`, `stopId` | Acknowledged resume |
+| `detach_debugger` | `debugSessionId` | Terminal state and cleanup; idempotent and usable for cleanup retry |
+
+`processId` and `line` are positive safe integers. Omitted process ID is allowed
+only when exactly one matching app process is JDWP-visible. Resolve package UID,
+process name, PID and process-start identity before and after attach; reject
+ambiguity, mismatch or PID reuse. Never select the first connected device.
+
+Responses use existing MCP text JSON serialization:
+`{success, debug_session_id, device, target, state, captured_at_ms, capabilities,
+limitations, cleanup, ...payload}`; pre-session fields may be null. Target includes
+app ID, PID, process name and process-start identity. Failures add
+`error: {code, message, retryable}`. Codes cover `INVALID_ARGUMENT`,
+`DEBUGGER_UNSUPPORTED`, `DEVICE_UNAVAILABLE`, `PROCESS_NOT_FOUND`,
+`PROCESS_AMBIGUOUS`, `PROCESS_CHANGED`, `DEBUGGER_BUSY`, `DEBUGGER_ATTACH_FAILED`,
+`DEBUGGER_NOT_FOUND`, `DEBUGGER_NOT_PAUSED`, `DEBUGGER_STALE_REFERENCE`,
+`DEBUGGER_LOCATION_UNAVAILABLE`, `DEBUGGER_DISCONNECTED`, `DEBUGGER_TIMEOUT`,
+`DEBUGGER_CANCELLED`, `DEBUGGER_WORKER_FAILED`, and `DEBUGGER_CLEANUP_FAILED`.
+No automatic retry of attach, step or resume. Do not claim command delivery
+establishes a later stop or UI outcome.
+
+## Stops, inspection and events
+
+States: `attaching`, `running`, `paused`, `detaching`, `detached`, `disconnected`,
+`failed`. Serialize state-changing commands per session; event polling must not
+block resume/detach. One active session per device, at most four per server.
+Reject an existing debugger attachment without replacing it.
+
+Breakpoints use exact binary class names and 1-based lines, without arbitrary
+source paths. Bind all matching executable locations in loaded class loaders;
+report class-loader identity and resolved source/line. Unloaded classes remain
+pending via class-prepare requests. Missing executable lines/debug metadata are
+explicitly unavailable; never silently move the breakpoint. Limit 100 breakpoints.
+
+Breakpoint and step events suspend all app threads. Retain owned EventSets and
+resume through their matching ownership; do not decrement unrelated suspension
+counts. Non-stop events are promptly released. Each new stop has a unique
+`stopId`, triggering thread ID, reason, locations and matching breakpoint IDs.
+Simultaneous events share a stop summary. Step uses one-shot line stepping on
+the chosen suspended thread; a competing breakpoint also completes that step
+attempt and removes its request. A step acknowledgement does not wait for a stop.
+
+Thread/frame IDs are stop-scoped. Resume, step, disconnect and detach invalidate
+all inspection references before further commands can use them. Stack pagination
+defaults to 20, maximum 100 per call and 1000 frames per stop. Locals return at
+most 100 entries: primitives, null, strings truncated to 256 characters, and
+object type/opaque identity summaries, without field traversal or `toString()`.
+Expose truncation and missing debug metadata; unavailable locals are distinct
+from a proven empty scope. Investigation found ART may return an empty variable
+table without distinguishing absent metadata from no variables; report availability
+as unknown with `EMPTY_OR_UNAVAILABLE_VARIABLE_METADATA`, rather than inferring an
+empty scope. No retained object pinning.
+
+Maintain a 256-event ring per session with increasing sequence, host receipt time,
+kind and optional stop summary. Default cursor is zero; return at most 100 events
+and a continuation cursor. Cursor overrun is explicit. Reject future cursors;
+an empty wait returns success with `timed_out: true`, without changing the session.
+
+## UI coordination and resource safety
+
+While a session is paused, conservatively block action dispatch, lifecycle/data
+management, and UI waits/assertions on that device with `DEBUGGER_PAUSED` before
+native work. Journeys stop with completed steps preserved and no automatic retry.
+Check at dispatch and within polling; a pause racing an already dispatched action
+must preserve delivery evidence and mark verification blocked. Do not queue inputs
+for resume. Use a device dispatch gate to serialize pause transitions with input
+submission; inputs already submitted cannot be retracted.
+
+Readiness tools return evidence-backed `debugger_paused` with debug session/target
+identity and host timestamp without acquiring a UI tree. This is device-scoped
+blocking evidence, not proof the paused app is foreground. Screenshots, raw trees
+and logs remain available within their existing bounds and carry the known pause
+annotation; their success does not establish readiness. Other devices and iOS
+retain existing behaviour. Unknown/disconnected debugger state cannot imply pause.
+
+Detach automatically after 60 seconds continuously paused, five minutes without
+client activity, or 30 minutes total session lifetime; polling cannot extend the
+pause/total limit. Emit the expiry reason. Timeouts/cancellation of inspection
+leave a known session intact; uncertain state-changing commands trigger teardown
+and invalidate references. Cancelling an event wait only cancels that wait.
+
+Cleanup has its own ten-second deadline: remove owned requests, release owned
+suspensions/dispose the JDI connection, stop the owned worker, and remove only
+the session's exact ADB forward. Never kill/restart the app, ADB server or another
+debugger. On worker failure, disconnect its transport and verify obtainable
+cleanup facts; never claim the app resumed without evidence. Report cleanup as
+`pending`/`complete`/`failed`, remaining resources and execution state as unknown
+when necessary. Block new sessions on that device until owned cleanup completes.
+The worker watches parent-pipe EOF; server shutdown also requests cleanup. Abrupt
+host/device loss may prevent confirmed cleanup and must be documented explicitly.
+
+Use argv-based subprocesses and a dedicated worker with bounded JSON-lines IPC
+(1 MiB/message), request IDs and stderr-only diagnostics. JDI runs through an
+owned loopback forward, never a public listener. Whitelist commands; do not log
+locals or protocol values. Locals may contain sensitive data and are returned
+only on request; no persistent inspection dump or upload. Retain up to 100 terminal
+session summaries for ten minutes, clearing locals, frames and events at teardown.
+
+## Acceptance and verification
+
+1. A dedicated debuggable Java fixture attaches on the selected device/process;
+   ambiguous, non-debuggable, replaced and already-debugged targets fail safely.
+2. Pending/loaded breakpoints stop at the expected line; stack and known local
+   values are correct; each step mode and resume produce observed execution.
+3. Old stop/frame/thread references fail after resume; missing metadata and
+   truncation are explicit.
+4. UI action/wait/readiness tools recognise pauses, including mid-journey stops;
+   another device is unaffected and resumed UI changes are independently verified.
+5. Explicit detach, expiry, cancellation, disconnect and worker failure invalidate
+   references and clean up owned resources without altering unrelated forwards.
+
+Use focused self-running unit tests plus a new isolated fixture with debug line
+and local-variable tables. Run `npm run verify`, `npm run test:device`, and focused
+end-to-end calls through the updated server. Record exact build/device and each
+journey as pass/fail/blocked/unrun. Current CI uses Node 18; manual Android CI uses
+JDK 17/API 30. Existing smoke tests do not prove debugger behaviour; add worker
+compilation/packaging checks and explicit debugger coverage.
+
+Affected areas: new debugger/worker modules, tool definitions/handlers, readiness,
+interaction dispatch/polling, lifecycle guards, shutdown, native-tool status,
+packaging, fixtures/tests and tool/README/changelog documentation. Correct existing
+JDWP capability reporting: ADB/device presence alone is not debugger readiness.
+
+## Investigation and approval
+
+Checkout 0.33.0 contains no debugger implementation. Host Java 23 and ADB 37.0.1
+are available; outside sandbox, `emulator-5554` is online (API 36 arm64). Existing
+latency fixture lacks `android:debuggable`; a dedicated fixture is required.
+No debugger session was attached and no debugging journey is verified yet.
+
+Primary references: [JDI VM lifecycle](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.jdi/com/sun/jdi/VirtualMachine.html),
+[EventSet suspension ownership](https://docs.oracle.com/en/java/javase/21/docs/api/jdk.jdi/com/sun/jdi/event/EventSet.html),
+[frame lifetime](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.jdi/com/sun/jdi/StackFrame.html),
+[step requests](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.jdi/com/sun/jdi/request/StepRequest.html),
+and [ADB](https://developer.android.com/tools/adb). ART/JDI interoperability must
+be established by fixture evidence; API documentation alone does not prove it.
+
+The user approved this complete specification with “yes” on 2026-10-30 in this
+conversation, including all-thread
+suspension, conservative device-wide UI blocking, shallow locals, JDK dependency,
+and automatic detach limits. Implementation is authorized within this scope.

package/docs/tools/TOOLS.md

@@ -8,7 +8,9 @@ This repository groups the MCP tools into four areas aligned with the codebase:
 - [system](system.md) — environment and health checks
 
 Correlation metadata and explicit action references are documented in
-[correlated evidence](evidence.md).
+[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).
 
 ## Agent guidance
 

package/docs/tools/debugger.md

@@ -0,0 +1,104 @@
+# Android runtime debugger
+
+Optional managed Java/Kotlin bytecode debugging through an independently developed
+JDI worker. Requires JDK 17+ (`java`, `javac`, `jdk.jdi`), Android platform-tools,
+an authorized device and an already-running JDWP-visible debuggable app.
+Android Studio JBR/standard JDK discovery follows existing Java helpers; `ADB_PATH`
+is supported. The worker is compiled on demand into a private source/JDK-keyed
+host temporary cache. Ordinary tools do not require Java or start a debugger.
+Cache directories named `mobile-debug-jdi-*` can be removed when the server exits.
+
+## Tools and flow
+
+1. `get_debugger_capabilities` with `platform: "android"`, explicit `deviceId`,
+   `appId`, and optional positive `processId` probes prerequisites/candidate processes.
+   General `get_system_status` does not establish target-specific debugger readiness.
+2. `attach_debugger` with the same target returns `debug_session_id`. If multiple
+   matching debuggable processes exist, provide `processId`. Package UID, process
+   name, PID and process-start identity are checked. Other debuggers are not replaced.
+3. `set_debugger_breakpoint` takes `debugSessionId`, exact binary `className` and
+   1-based executable `line`. It returns `result.breakpoint_id`, status and resolved
+   source locations/class-loader IDs. Unloaded classes remain `pending`; missing
+   line metadata is rejected explicitly. No automatic source search/line relocation.
+4. Trigger execution, then `wait_for_debugger_event` with `debugSessionId` and
+   `afterSequence` (initially zero). Retain `next_cursor`. Stop events contain
+   `stop_id`, `thread_id` and source locations. A step acknowledgement is not a stop.
+5. `get_debugger_stack` takes `debugSessionId`, `stopId`, `threadId`, optional
+   `offset` and `limit` (20 default, 100 maximum; 1000-frame cap).
+   `get_debugger_locals` takes `debugSessionId`, `stopId`, `frameId`. It returns
+   `result.availability`, up to 100 shallow locals, and truncation information.
+   Primitive values are textual; strings truncate at 256 characters; objects have
+   type/identity summaries. Missing variable metadata is explicit. ART can return an empty table without
+   distinguishing absent metadata from a genuinely empty scope; these responses
+   use `availability: "unknown"`, `reason: "EMPTY_OR_UNAVAILABLE_VARIABLE_METADATA"`.
+6. `step_debugger` takes `debugSessionId`, current `stopId`, `threadId` and
+   `kind: "into" | "over" | "out"`. It resumes and requests one line step.
+   `resume_debugger` takes `debugSessionId`, `stopId`. Both expire all old stop,
+   thread and frame references. Await the next stop using the event cursor.
+7. `remove_debugger_breakpoint` takes `debugSessionId`, `breakpointId` and is
+   idempotent for an owned ID. `get_debugger_state` reads stop, breakpoint, terminal
+   reason and cleanup status. `detach_debugger` disposes the session and supports
+   repeated calls/retrying incomplete cleanup.
+
+Every tool accepts integer `timeoutMs`, 100–30000 (default 10000; event waits
+1000). Unknown arguments are rejected. Other strings are limited to 512 characters.
+All session tools use camelCase input IDs; response fields use snake_case.
+Successful operation payloads are under `result` where applicable; common fields
+include `success`, `debug_session_id`, `device`, `target`, `state`,
+`captured_at_ms`, `capabilities`, `limitations`, `cleanup`, `reason`, and `stop`.
+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.
+
+## Suspension, limits and cleanup
+
+Stops suspend all app threads. UI actions, app lifecycle/data changes, waits and
+assertions on that device return `DEBUGGER_PAUSED`; inputs are not queued. A pause
+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
+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.
+
+The worker and host enforce automatic detach after 60 seconds continuously paused,
+five minutes without client commands or 30 minutes total. Polling cannot extend
+the pause or total limit. One active session per device, four per server; at most
+100 distinct breakpoint IDs per session. Terminal summaries expire after ten
+minutes and are capped at 100; inspection values and event history are cleared.
+
+Detach releases debugger-owned suspension and removes only owned requests,
+worker and the exact ADB forward. Cleanup is bounded separately to ten seconds;
+retry `detach_debugger` if `cleanup.status` is `failed`. Never kill an app or ADB
+server to clean up. Unexpected worker/transport loss reports execution state as
+unknown; no resumption claim is inferred. Hard host/device loss can prevent
+confirmed cleanup. Server shutdown and worker parent-pipe EOF request cleanup.
+
+MCP request cancellation is supported. Cancelling an event wait leaves the
+session intact. Inspection cancellation/timeouts preserve a known session;
+uncertain mutation/attach outcomes trigger teardown. Do not automatically retry
+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
+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.
+
+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
+# 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`.

package/docs/tools/evidence.md

@@ -73,7 +73,10 @@ after it, or causality. No implicit action-window filtering is applied.
 
 Existing payloads, image blocks, and log blocks remain available. Snapshot evidence
 sits alongside `raw` and `semantic`. Android ADB and supported iOS simulators share
-this contract; existing provider limitations still apply. `trace_context` reports
-`{ "supported": false, "trace_id": null, "markers": [] }` for future trace linkage.
+this contract; existing provider limitations still apply. `trace_context` defaults
+to `{ "supported": false, "trace_id": null, "markers": [] }`. Journeys explicitly
+linked to an active Android [system trace](system-traces.md) and their steps expose
+`{ "supported": true, "trace_id": "…", "markers": [] }`; association does not align
+clocks or inject device markers.
 Correlation history stores identifiers, scope, timing, and ordering only, without
 captured content, arguments, persistence, or telemetry.

package/docs/tools/observe.md

@@ -13,6 +13,9 @@ They are **not** the primary success signal when an applicable `expect_*` tool e
 Covered observations support optional `actionRef` and return acquisition/freshness
 metadata; see [correlated evidence](evidence.md).
 
+Android performance investigations can use [system traces](system-traces.md)
+to bracket a journey and retrieve a local Perfetto artifact.
+
 ## get_logs
 
 Fetch recent logs as structured entries optimized for AI agents.
@@ -240,7 +243,8 @@ Both return `success`, resolved `device`, `readiness`, `elapsed_ms`, and a
 or settled; wait succeeds only for settled. Codes are `READINESS_UNAVAILABLE`,
 `READINESS_TIMEOUT`, and `DEVICE_UNAVAILABLE`. Invalid/unknown inputs are rejected.
 
-`readiness.state` is loading, transitioning, settled, or unknown. Visible native
+`readiness.state` is loading, transitioning, settled, unknown, or debugger_paused
+for an owned Android debugger stop. Visible native
 progress indicators establish loading; exact Loading / Please wait labels
 (ignoring case, whitespace and trailing dots/ellipsis) are heuristic loading.
 Loading takes priority over unchanged trees. Two different valid signatures show
@@ -252,12 +256,15 @@ keywords such as a button named Progress are not sufficient loading evidence.
 The summary includes `basis` (observed/heuristic/insufficient), `scope: device_ui`,
 latest successful capture time and snapshot session/revision, sample
 count, `stable_for_ms`, up to eight signal-code evidence records, limitations,
-and capability flags. Evidence excludes UI text and full trees. Unresponsive and
-debugger-paused detection are explicitly unsupported on both platforms; neither
-slow hierarchy retrieval nor a deadline expiry proves either state.
+and capability flags. Evidence excludes UI text and full trees. Managed Android
+[debugger pauses](debugger.md) are reported from session evidence without acquiring
+a UI tree; readiness waits fail with `DEBUGGER_PAUSED`. External-debugger and iOS
+pause detection remain unsupported. Unresponsive detection is unsupported; neither
+slow hierarchy retrieval nor a deadline expiry proves a pause or unresponsiveness.
 
 Tree responses (including compact and nested trees) add a single-sample readiness
-summary without extra reads. Such a summary reports loading or unknown; it does
+summary without extra reads. It reports an owned debugger pause when known;
+otherwise a single-sample summary reports loading or unknown; it does
 not inherit stability from an earlier request. Existing loading/delta fields and
 compact error evidence are preserved.
 

package/docs/tools/system-traces.md

@@ -0,0 +1,126 @@
+# Android system traces
+
+Use system traces to collect scheduling and system annotations around a slow
+interaction. Capture is optional, device-wide and Android-only; 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,
+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.
+
+| 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_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. |
+
+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
+IDs. Repeated terminal operations return the stored outcome.
+
+## Agent workflow and interpretation
+
+Trace a reproducible slow or stalled interaction when existing UI timing/state
+and logs leave a performance question unresolved. Check tool discovery first:
+older installed servers may not expose these tools. Capability failure is a
+reported limitation; it is not evidence that the app is frozen.
+
+Establish the initial UI state and include an outcome assertion in the journey.
+The launch-only example below demonstrates bracketing; it does not prove an app
+outcome. Use a fresh screenshot or semantic assertion appropriate to the actual
+screen. Settings, for example, may resume a subpage rather than show its main
+title. Allow enough capture time for complete observations as well as inputs.
+
+Always finalise an owned recording, including when a journey fails. Stop to keep
+diagnostic evidence; cancel to discard it. Check both `state` and `cleanup`, and
+use status/retry for an unresolved session before starting another capture.
+Do not rely on automatic duration expiry as routine cleanup.
+
+A useful report identifies the device, journey and assertion outcomes, trace ID,
+linked correlation IDs, coverage, artifact path and cleanup outcome. `covered`
+describes the capture session lifetime, not proof that every event survived the
+ring buffer. Capture success and valid trace contents are separate from a
+performance diagnosis. These tools do not return CPU summaries, frame metrics,
+blocked-thread analysis or a root cause. Inspect the artifact with an available
+analyser before making those claims; otherwise report analysis **unrun** and
+provide the local artifact for follow-up. Host/device clocks remain unaligned.
+
+## Bracket a journey
+
+1. `get_system_trace_capabilities({"platform":"android","deviceId":"emulator-5554"})`
+2. `start_system_trace({"platform":"android","deviceId":"emulator-5554","durationMs":30000})`
+3. Use the returned `trace_id` as `systemTraceId`:
+
+```json
+{
+  "platform": "android",
+  "deviceId": "emulator-5554",
+  "systemTraceId": "<trace_id>",
+  "steps": [
+    { "id": "launch", "type": "start_app", "appId": "com.android.settings", "verificationMode": "none" }
+  ]
+}
+```
+
+4. `stop_system_trace({"traceId":"<trace_id>"})` returns `artifact.path` for local
+   inspection in Perfetto. Delete the file/directory when finished.
+
+An invalid, inactive, foreign-server or different-device reference prevents all
+journey steps. A failed journey leaves the capture available to stop or cancel;
+journeys do not control its lifetime. Without `systemTraceId`, journey behaviour
+and evidence remain unchanged. Linked journey/step evidence has
+`trace_context: {"supported":true,"trace_id":"…","markers":[]}`. The journey
+returns `system_trace` with `trace_id`, `coverage` (`covered` or `partial` if
+capture ended during execution), and `clock_alignment:"unknown"`. Trace results
+list linked `correlation_ids`. These are associations, not injected markers or
+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),
+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` contains absolute `path`, `format:"perfetto"` and `size_bytes`.
+`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
+`INVALID_ARGUMENT`, `UNSUPPORTED_PLATFORM`, `TRACE_UNSUPPORTED`, `TRACE_BUSY`,
+`TRACE_NOT_FOUND`, `TRACE_START_FAILED`, `TRACE_STOP_FAILED`,
+`TRACE_ARTIFACT_FAILED`, `ACTION_TIMEOUT`, and `TRACE_CANCELLED`.
+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
+
+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
+reported; missing sched/input rejects start. No arbitrary config, wildcard app
+annotations, heap, screenshot or logcat sources are enabled. Device/system
+annotations may still contain sensitive information; this is not app-private data.
+
+Capture has a device-side duration limit and a server finalisation timer. Start
+acknowledgement has a 35-second budget, graceful stop 10 seconds, and transfer
+30 seconds. Only the recorded PID/start-time/output-path owner can be signalled;
+no kill-by-name cleanup. A device disconnect or uncertain stop reports failure,
+never a successful artifact. Partial transfers are discarded; bounded device
+output remains retryable. Successful transfers remove owned device files.
+
+Host artifacts use unique restricted temporary directories and remain for
+user-managed deletion. Nothing is uploaded or returned as base64. Normal server
+shutdown attempts owned cleanup for up to 10 seconds. A server crash can leave
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {

package/src/debugger/android.ts

@@ -0,0 +1,65 @@
+import { resolveAdbCmd } from '../utils/android/utils.js'
+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 DebugNative {
+  candidates(device: string, app: string): Promise<DebugTarget[]>
+  identity(device: string, target: DebugTarget): Promise<DebugTarget>
+  forward(device: string, pid: number): Promise<number>
+  removeForward(device: string, port: number, pid: number): Promise<void>
+}
+export class AndroidDebugNative implements DebugNative {
+  async adb(device: string, args: string[]) {
+    try { return (await exec(resolveAdbCmd(), ['-s', device, ...args], { timeout: debuggerRemaining(5000), signal: debuggerSignal(), maxBuffer: 1024 * 1024 })).stdout.trim() }
+    catch (e) { throw nativeError(e, 'DEVICE_UNAVAILABLE') }
+  }
+  async identity(device: string, target: DebugTarget): Promise<DebugTarget> {
+    try {
+      const stat = await this.adb(device, ['shell', 'cat', `/proc/${target.pid}/stat`])
+      const fields = stat.slice(stat.lastIndexOf(')') + 2).split(/\s+/)
+      const status = await this.adb(device, ['shell', 'cat', `/proc/${target.pid}/status`])
+      const uid = Number(/^Uid:\s+(\d+)/m.exec(status)?.[1])
+      const name = (await this.adb(device, ['shell', 'cat', `/proc/${target.pid}/cmdline`])).split('\0')[0]
+      if (!/^\d+$/.test(fields[19] ?? '') || uid !== target.uid || name !== target.process_name || (target.start_identity && fields[19] !== target.start_identity)) throw new Error('identity')
+      return { ...target, start_identity: fields[19] }
+    } catch (e) { if (e instanceof DebuggerError && ['DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED', 'DEVICE_UNAVAILABLE'].includes(e.code)) throw e; throw new DebuggerError('PROCESS_CHANGED') }
+  }
+  async candidates(device: string, app: string) {
+    if (!/^[A-Za-z][\w]*(?:\.[A-Za-z][\w]*)+$/.test(app)) throw new DebuggerError('INVALID_ARGUMENT')
+    const packages = await this.adb(device, ['shell', 'cmd', 'package', 'list', 'packages', '-U', app])
+    const uid = Number(new RegExp(`^package:${app.replaceAll('.', '\\.')} uid:(\\d+)$`, 'm').exec(packages)?.[1])
+    if (!Number.isSafeInteger(uid)) throw new DebuggerError('PROCESS_NOT_FOUND')
+    // `adb jdwp` is a subscription, not a one-shot command. Bound the sample.
+    let jdwpOutput: string
+    try { jdwpOutput = (await exec(resolveAdbCmd(), ['-s', device, 'jdwp'], { timeout: debuggerRemaining(500), signal: debuggerSignal(), maxBuffer: 1024 * 1024 })).stdout }
+    catch (e: any) {
+      if (debuggerSignal()?.aborted) throw new DebuggerError('DEBUGGER_CANCELLED')
+      debuggerRemaining(1)
+      if (!e.killed || e.stderr?.trim()) throw nativeError(e, 'DEVICE_UNAVAILABLE')
+      jdwpOutput = e.stdout ?? ''
+    }
+    const jdwp = new Set(jdwpOutput.split(/\s+/).filter(id => /^\d+$/.test(id)))
+    const ps = await this.adb(device, ['shell', 'ps', '-A', '-o', 'PID,NAME'])
+    const result: DebugTarget[] = []
+    for (const line of ps.split('\n').slice(1)) {
+      const [pid, name] = line.trim().split(/\s+/)
+      if (jdwp.has(pid) && (name === app || name.startsWith(app + ':'))) result.push(await this.identity(device, { app_id: app, pid: Number(pid), process_name: name, start_identity: '', uid }))
+    }
+    return result
+  }
+  async forward(device: string, pid: number) {
+    const port = Number(await this.adb(device, ['forward', '--no-rebind', 'tcp:0', `jdwp:${pid}`]))
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) throw new DebuggerError('DEBUGGER_ATTACH_FAILED')
+    return port
+  }
+  async removeForward(device: string, port: number, pid: number) {
+    const list = await this.adb(device, ['forward', '--list'])
+    const entry = list.split('\n').find(line => line.trim().split(/\s+/)[1] === `tcp:${port}`)
+    if (!entry) return
+    const [serial, local, remote] = entry.trim().split(/\s+/)
+    if (serial !== device || local !== `tcp:${port}` || remote !== `jdwp:${pid}`) throw new DebuggerError('DEBUGGER_CLEANUP_FAILED')
+    await this.adb(device, ['forward', '--remove', `tcp:${port}`])
+  }
+}

package/src/debugger/guard.ts

@@ -0,0 +1,26 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { DebuggerError } from './worker.js'
+let pauseProvider: (device: string) => any = () => 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>) {
+  return context.run({ platform, device, dispatched: false }, 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 (dispatch) current.dispatched = true
+}
+export function guardDispatched() { return context.getStore()?.dispatched ?? false }
+export function pausedReadiness(device: string) {
+  const paused = pauseProvider(device)
+  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,
+    evidence: [{ code: 'DEBUGGER_PAUSED', source: 'debugger', captured_at_ms: paused.captured_at_ms, snapshot_revision: null }],
+    limitations: ['FOREGROUND_APP_UNVERIFIED', 'DEVICE_WIDE_UI_GUARD'],
+    capabilities: { loading: true, transitioning: true, settled: true, unresponsive: false, debugger_paused: true },
+    debug_session_id: paused.debug_session_id, target: paused.target }
+}