mobile-debug-mcp 0.33.0 → 0.35.0

package/docs/specs/030-android-coroutine-validation/report.md

@@ -0,0 +1,240 @@
+# Android coroutine debugger assessment — issue #93
+
+Date: 2026-11-02. Source: [issue #93](https://github.com/clivejefferies/mobile-debug-tools/issues/93).
+Scope: [accepted specification](spec.md); [fixture/reproduction](../../../test/fixtures/coroutine-app/README.md).
+
+## Method and evidence boundaries
+
+The fixture uses explicit CompletableDeferred gates, two named single-thread
+executor dispatchers, a nested async child and a cancellation/finally path.
+It uses no debug probes or app instrumentation. The runner uses the existing
+MCP stdio server and records source/APK/server/worker/dependency fingerprints,
+compiler line/local tables and actual stops, stacks and locals. Fresh UI-tree
+assertions independently establish completion and cancellation recovery.
+Opaque MCP thread IDs are scoped to each stop; different ID strings alone do
+not establish a dispatcher change. Live synthetic thread-name locals and fixture
+checks establish the named dispatcher execution instead.
+
+Environment selected: emulator-5554, Android 16/API 36; Node 22.23.4;
+Kotlin compiler/stdlib 2.0.21; kotlinx-coroutines-core-jvm 1.9.0;
+fixture compiler JDK 17.0.11; Android SDK/build-tools 36. The debugger's existing
+Java discovery selects Android Studio JBR, which reports 25.0.3 on this host;
+setting fixture JAVA_HOME does not override that debugger discovery order.
+The local run used a temporary wrapper around the cached Kotlin embeddable
+compiler; the fixture README documents a standard Kotlin CLI installation.
+No result is inferred for other compiler/runtime versions.
+
+## Results
+
+Focused emulator journey: **PASS**. Full local output:
+`/tmp/mobile-debug-93-emulator.log`; compact checked-in [evidence](evidence.json).
+
+| Check | Observed result |
+| --- | --- |
+| Before/after gate suspension | PASS: source stops; `known=42` readable on both sides |
+| Dispatcher change | PASS: live locals `fixture-first` then `fixture-second` |
+| Nested child work | PASS: helper argument `43`; final `answer=44` |
+| Into/over/out | PASS inside the synchronous helper/increment calls |
+| Suspension-boundary step | Observed stop at `completeWork` entry, line 50; no logical-coroutine-following claim |
+| Safety and recovery | PASS: pause guard, stale-frame rejection, cancelled event wait with usable session |
+| Job cancellation | PASS: child finally source stop, joined cancellation, fresh `Coroutine cancelled` UI |
+| Completion/recovery | PASS: fresh `Coroutine result 44` UI after detach |
+| Owned cleanup | PASS: complete detach, forwards preserved, package/build directory removed |
+| Physical-device journey | UNRUN; explicit serial selection is required |
+
+Source SHA-256: `5978b835673876642c256b1c688975e78018addc1f68219371bc47c8cc29a92b`.
+Built server/dist SHA-256: `4f7bf452fc0022c8feb492f11a25c34ac5e360baff9f77d752dd0d248105d581`.
+Worker source SHA-256: `fb15e7add65fb3682d86153818d02378084a46fcd49b2c23c0eafdba290f8323`.
+Compiler/APK/dependency metadata and hashes are in the evidence file. APK signing
+is ephemeral, so subsequent APK hashes can differ.
+
+Initial cancellation recovery failed to reach its expected UI state while
+retaining the prior completion text. The test now starts cancellation from a
+fresh fixture process after detaching the boundary-step assessment. This is
+fixture-owned lifecycle isolation, not a debugger cleanup operation.
+An initial thread-name assertion also exposed compiler elimination of unused
+locals; the fixture now uses those values after the breakpoint so their emitted
+scope covers inspection. Assertions were not weakened to treat absent values
+as a dispatcher proof.
+
+## Interpretation and follow-up recommendation
+
+Existing source breakpoints can be a useful way to inspect separately executing
+parts of a coroutine. Source bindings must include generated binary class names
+from the actual compiler output. A shallow locals result and current-thread stack
+are execution evidence; they do not enumerate suspended coroutines, establish a
+parent/child job identity or recover an asynchronous logical stack. A local spilled
+into a continuation field need not appear in the current frame's local table.
+
+**No-go for implementing generic coroutine reconstruction in this ticket.** A
+separate feasibility design should first prove Android-compatible discovery of
+active and suspended continuations, stable job identity and ownership/parent-child
+relationships, and a versioned mapping from DebugMetadata/state labels to logical
+source frames. This would require inspection beyond the existing shallow locals
+API, or explicitly agreed app instrumentation, with privacy and compatibility
+limits. No such mechanism has been validated here.
+
+The upstream [kotlinx-coroutines-debug documentation](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-debug/)
+describes JVM agent-based coroutine tracking and explicitly identifies Android
+instrumentation limitations. It is not evidence that installing that JVM agent
+would supply an Android solution. The [DebugProbes API](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/)
+describes tracking creation, suspension and resumption with instrumentation and
+overhead; this fixture does not enable it. Android-specific alternatives and
+metadata compatibility remain design questions. Defer that capability design
+until after the bounded assessment and iOS parity, as the issue requires.
+
+## Limits
+
+Physical-device verification, other Kotlin/coroutine versions, optimized or
+obfuscated apps, inline suspend functions, process/device disconnect and forced
+host termination are unrun unless separately recorded below. Signal handling
+requests MCP cancellation then finally attempts owned cleanup; SIGKILL/host loss
+cannot run finally. No iOS runtime-debugger support is claimed. Hosted CI has not
+run; it separately compiles the worker with JDK 17 and checks package contents,
+and its ordinary device workflow does not provision this opt-in Kotlin compiler.
+Local build/test evidence is not an installed or published-package check.
+
+## Repository verification
+
+`npm run verify` **PASS** on Node 22.23.4: lint, structural/architecture checks,
+TypeScript build, all 89 unit files and plugin consistency. Final log:
+`/tmp/mobile-debug-93-final-verify.log`. The sandbox blocked tsx IPC creation;
+verification passed in the authorized run outside the sandbox without changing
+checks. Changed relative links, new-file whitespace and `git diff --check` passed.
+
+The focused review found no required production-code or schema change. Fixture
+subprocesses/polls are bounded; package targeting is explicit; the runner refuses
+pre-existing fixture installations and keeps normal debugger cleanup separate
+from resetting its own app between independent cases. At the original verification,
+changes were local, uncommitted and unpushed.
+
+Full `npm run test:device` **PASS**, all 12 files, with
+`MCP_COROUTINE_DEVICE=emulator-5554 MCP_KOTLIN_DEVICE=emulator-5554 MCP_DEBUGGER_DEVICE=emulator-5554`
+and the documented local compiler/stdlib/coroutine paths set. Log:
+`/tmp/mobile-debug-93-device.log`. The coroutine assessment passed again on the
+same source/server/worker fingerprints (ephemeral APK signing produced SHA-256
+`6cc95ae8ad9d254444e9704a7526d62a0ab1c8354a5624d6695789eedd429f82`).
+Existing Kotlin/Java debugger, interaction, Android/iOS observation smoke,
+correlated-evidence and Android system-trace checks passed. These iOS checks do
+not verify iOS runtime debugging. The new fixture's package, temporary outputs
+and owned forwards were removed; no physical-device coroutine check ran.
+
+## PR #96 repair evidence
+
+The original results above predate the readiness-race fix: they establish the
+recorded locations/values, but the original UI readiness alone did not prove
+that the gate wait had suspended before release/cancellation. New readiness
+runs as queued work behind the coroutine on its own single-thread executor,
+which cannot execute until that coroutine yields. The repaired dispatcher
+breakpoint class is `MainActivity$completeWork$3`.
+
+Overall JSON PASS now follows cleanup, and cleanup failures are reported as FAIL.
+Forward comparisons select only the target serial and sort entries. The new
+unit regressions and repository verification passed (90 unit files, Node 22.23.3;
+`/tmp/pr96-verify.log`). The first attempt on a restored emulator
+snapshot hit install/uninstall timeouts; that real cleanup failure emitted JSON FAIL
+without an overall PASS (`/tmp/pr96-device.log`). The task-owned leftover package
+was removed after a cold start. Final device-rerun evidence is recorded below;
+the original suspension-readiness evidence is superseded.
+
+Final repair verification: `npm run verify` **PASS**, all 90 unit files, Node
+22.23.3 (`/tmp/pr96-final-verify.log`). Unit checks cover successful cleanup before
+PASS, work failure, cleanup failure, simultaneous failures without losing either
+error, exact serial filtering, other-device churn and order normalization.
+
+Full device-suite attempts **FAIL** during installation/cleanup on the restored
+and cold-started emulator (`/tmp/pr96-device.log`, `/tmp/pr96-device-cold.log`).
+Incremental installation continued after host-side timeout, leaving a differently
+signed package; the task-owned package was removed. A focused streamed-install
+run used an external temporary ADB_PATH wrapper adding `--no-incremental` only
+for install, without changing repository timeouts or assertions.
+
+That focused run **passed** completion, verified the queued readiness and updated
+`completeWork$3` breakpoints, named dispatchers, known values, synchronous steps,
+stale/pause guards, cancelled wait recovery and the bounded suspension-step
+observation. It then **failed** at `am start -W` restarting the fixture before
+cancellation, followed by an uninstall timeout. Its overall JSON FAIL preserves
+both errors (`/tmp/pr96-focused-streamed.log`). Repaired cancellation readiness
+is compiler-checked but its device journey is **UNRUN**; remaining suite checks
+were not reached. No full native pass is claimed for this repair.
+
+Current fixture source SHA-256:
+`d4656e3736cc245230bc000c6574288b145df47957dd7ee511ea98717afde4df`.
+Final independent package query returned no owned fixture package; no ADB forwards
+remained and temporary build output was removed. The review fixes introduce no
+production server behaviour or contract change. Physical-device checks and hosted
+CI are unrun for this revision.
+
+## Successful retry on the maintainer's running emulator
+
+The repaired coroutine assessment **PASS**ed in full on emulator-5554, Android
+16/API 36, commit `1497693`, Node 22.23.3. This supersedes the earlier incomplete
+cancellation verification: queued readiness, cancellation/finally, cancelAndJoin,
+fresh `Coroutine cancelled` UI, completion, stepping, guards, cancelled event wait
+and owned cleanup all passed. The overall JSON PASS followed successful cleanup.
+Log: `/tmp/pr96-user-emulator.log`.
+
+Fixture source SHA-256 remains
+`d4656e3736cc245230bc000c6574288b145df47957dd7ee511ea98717afde4df`;
+server/dist remains `4f7bf452fc0022c8feb492f11a25c34ac5e360baff9f77d752dd0d248105d581`.
+APK SHA-256: `3ec87db96cd87f9bd7ca27472dde8c1b57d2789d9f808714362ca4ba2ee95c83`.
+Kotlin/stdlib 2.0.21, coroutines 1.9.0 and fixture JDK 17.0.11 were unchanged.
+Local setup used the temporary ADB_PATH wrapper for streamed installation and
+`JAVA_TOOL_OPTIONS='-Xmx512m -XX:TieredStopAtLevel=1'` for host JVM startup.
+No assertions or deadlines changed. The user-started emulator remains running;
+only fixture-owned resources were removed. Physical-device coroutine validation
+remains unrun.
+
+The full device-suite retry passed coroutine, Kotlin/Java debugger, interaction
+and Android screenshot checks before failing the iOS screenshot test's ambiguous
+target selection (`/tmp/pr96-user-device-suite.log`). Separate Android logs,
+UI-tree and correlated-evidence checks passed; the correlation script then failed
+its iOS prerequisite because no iOS simulator was running
+(`/tmp/pr96-user-android-remaining.log`). Full-suite status remains **FAIL** for
+those iOS setup requirements, while the repaired Android coroutine journey is
+verified **PASS**, including cancellation and cleanup.
+
+A separate Android system-trace check failed its cancellation-state assertion
+(`failed` / `ACTION_TIMEOUT`, expected `cancelled`); its finally cleanup retry
+completed. Log: `/tmp/pr96-user-trace.log`. This is an additional observed
+limitation in the broader smoke checks; it does not invalidate the coroutine
+journey's successful cancellation and cleanup. No trace code or assertions were
+changed, and no complete device-suite pass is claimed.
+
+## Perfetto timeout investigation — 2026-11-02
+
+The earlier `cancel_system_trace` failure reported ACTION_TIMEOUT in the bounded
+stop/termination phase. Its original log does not identify which ADB command or
+process-exit wait exhausted the budget, so the root cause remains undetermined.
+No tracing source or smoke-test changes appear in PR #96.
+
+On the same running Android 16/API 36 emulator-5554 and server build
+`e90ed0831de4059f1e2b213ed0c050298cf2e55c0cc0aef9ff4ea2a38b6062a0`:
+
+- Three direct native/session start-cancel probes **PASS**ed with complete cleanup;
+  cancellation took 372, 373 and 390 ms. Log: `/tmp/pr96-perfetto-probe.log`.
+- Three full MCP smoke journeys **PASS**ed: Settings journey assertion, readable
+  trace content, explicit stop, cancellation, automatic duration completion,
+  stale-trace rejection and active shutdown cleanup. Logs:
+  `/tmp/pr96-perfetto-retest.log`, `/tmp/pr96-perfetto-instrumented-1.log`,
+  `/tmp/pr96-perfetto-instrumented-2.log`.
+- The final run used an assertion-identical temporary test copy with a server
+  preloader recording native-command timing. Across 71 commands, the only
+  nonzero exits were five expected Perfetto help probes (exit 1 is supported).
+  Maximum process lookup was 111 ms; maximum signal command 63 ms; maximum start
+  247 ms. No command timed out. Log: `/tmp/pr96-perfetto-mcp-timings.log`.
+- The first attempted instrumentation relied on NODE_OPTIONS, which the SDK's
+  default subprocess environment did not forward to the server. That smoke pass
+  remains valid but supplies no server timing evidence. The final run explicitly
+  preloaded the diagnostic module in both server subprocesses.
+- Final independent checks found no MCP trace files and no forwards on the
+  emulator. Host test artifacts were removed by each smoke journey. The emulator
+  remains running; no settings or user-app data were changed.
+
+Classification: the previously observed timeout is **not reproduced**, with an
+intermittent timing failure still possible. Passing reruns do not establish its
+cause or prove it fixed. No production change, timeout increase, assertion change
+or test suppression was made. Current Perfetto verification passes; the earlier
+failed observation is retained rather than reclassified as a pass. Any recurrence
+needs command timings at the failing invocation to distinguish ADB transport,
+process identity lookup, signalling and process-exit delay.

package/docs/specs/030-android-coroutine-validation/spec.md

@@ -0,0 +1,107 @@
+# Android coroutine validation specification — issue #93
+
+Status: accepted by the maintainer’s second “ok” in this chat on 2026-11-02. Implements the
+[accepted intent](intent.md), approved by “ok” in this chat on 2026-11-02.
+
+## Outcome and compatibility
+
+Establish what the existing Android JDI tools actually expose for an isolated
+Kotlin coroutine, and publish a reproducible assessment. No server capability,
+schema, response shape, error code or default changes. Android only; iOS runtime
+debugging remains unsupported. Java and synchronous Kotlin fixture journeys
+retain their current behaviour. Any reproduced production defect is reported
+with evidence and handled separately through the shared process.
+
+## Fixture and prerequisites
+
+Add an opt-in coroutine variant of the disposable debugger fixture, built from
+checked-in source using the existing direct Kotlin/D8/aapt2 pipeline. Initially
+target Kotlin compiler/stdlib 2.0.21, kotlinx-coroutines-core-jvm 1.9.0, JDK 17,
+Android SDK/build-tools 36 and Node 22+. Require explicit local dependency paths;
+do not download dependencies at test runtime, add server dependencies, enable
+debug probes or instrument user apps. Record actual versions and dependency
+hashes. Missing or incompatible prerequisites produce an actionable blocked
+result, not a pass.
+
+Use a separate fixture package so the coroutine journey cannot replace the
+existing Java/Kotlin fixture. Refuse installation if that package is already
+present; remove only the package installed by this run. Run sequentially on an
+explicit device serial. Initial target is emulator-5554; an attached Pixel 9 Pro
+is a separate optional verification target, never selected automatically.
+
+The fixture owns two named single-thread executor dispatchers. This makes a
+thread change observable without relying on scheduler chance. A run exposes a
+known local, suspends on a controllable gate, continues on the other dispatcher,
+performs nested child work, then completes with a fixed visible result. A
+separate cancellation run suspends a child, cancels and joins it, executes its
+finally block and shows a cancellation result. Gates and UI state establish
+ordering; arbitrary sleeps do not establish suspension. Close jobs/executors
+on activity destruction. Use compiler-emitted line/class metadata to identify
+generated continuation classes; do not assume every source line belongs to
+MainActivity or has a usable breakpoint.
+
+## Existing MCP workflow
+
+Use `get_debugger_capabilities`, `attach_debugger`,
+`set_debugger_breakpoint`, `wait_for_debugger_event`, `get_debugger_stack`,
+`get_debugger_locals`, `step_debugger`, `resume_debugger`,
+`remove_debugger_breakpoint`, `get_debugger_state` and `detach_debugger` with
+their current inputs and response contracts in the [debugger guide](../../tools/debugger.md).
+Keep session IDs, stop/thread/frame IDs and event cursors scoped to that run;
+reject overflow as incomplete evidence. Inspect thread-based frames and shallow
+locals without evaluating expressions or traversing continuation objects.
+
+Verify source stops before and after suspension and across the dispatcher
+change; compare known values with compiler scope tables. Report missing or
+unavailable locals honestly. Compiler spilling into continuation fields does
+not imply the locals API exposes those fields. Compare observed thread IDs and
+stack locations, without calling a thread stack a logical coroutine stack.
+
+Exercise into/over/out on a deterministic synchronous helper inside the coroutine.
+Separately attempt a bounded step across a suspension boundary and record where
+the event actually stops, including generated/runtime code or absence of a stop.
+Do not require that step to follow the coroutine; remove the step request through
+normal detach if it cannot make useful progress. A fresh session can then verify
+the before/after source-breakpoint workaround independently.
+
+## Safety, failure and cleanup
+
+All stops suspend the app. Verify an MCP interaction is rejected with the existing
+`DEBUGGER_PAUSED` result; no UI action is needed to release a gate while paused.
+Resume before further input. Old stop/frame references must return
+`DEBUGGER_STALE_REFERENCE` after execution resumes. Cancel an event wait and
+confirm the session remains usable; distinguish MCP request cancellation from
+fixture job cancellation.
+
+Bound subprocesses and polls with explicit deadlines. Keep normal inspection
+below the existing 60-second pause limit. On timeout, failure or interruption,
+attempt bounded detach, close the client, remove only owned forwards/package
+and temporary build output, and report unresolved cleanup. Never kill ADB,
+unrelated debugger sessions or user apps, nor automatically retry uncertain
+attach/step/resume operations. Preserve unrelated forwards. After normal detach,
+use a fresh UI-tree assertion of the expected completion/cancellation text to
+prove app recovery; detach acknowledgement alone is insufficient.
+
+## Acceptance and assessment
+
+1. A reproducible opt-in runner records source/APK/server fingerprints, dependency
+   versions, Android target and per-journey pass/fail/blocked/unrun results.
+2. Completion, cancellation, breakpoint workaround, stepping observations,
+   stale references, pause guards, cancelled wait recovery and owned cleanup
+   have explicit evidence. An unsupported debugging observation is an assessment
+   finding; a failed safety or cleanup assertion remains a failure.
+3. Emulator and physical-device evidence are separate. No physical run or
+   version compatibility is inferred from emulator success.
+4. Tool docs, usage skill and fixture README explain verified behaviour,
+   limitations and reproduction. Existing journeys and `npm run verify` pass;
+   applicable `npm run test:device` coverage and skips are reported.
+5. A report recommends go/no-go for separately scoped inspection of active and
+   suspended coroutine state, parent/child identity and logical stacks. Describe
+   metadata/probe requirements and setup friction as evidence or open questions.
+   No follow-up capability is implemented or approved by this specification.
+
+Only synthetic fixture values are collected. Retain local evidence intentionally;
+do not upload app data. Principal risks are compiler source mapping, ART variable
+metadata and scheduler/debugger interaction. No live coroutine behaviour has been
+verified yet. Prerequisite discovery found the proposed compiler/coroutine jars,
+JDK 17 and an authorized emulator; this is availability evidence only.

package/docs/tools/TOOLS.md

@@ -1,25 +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).
+## 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.
+- [Android system traces](system-traces.md) — performance capture and local Perfetto artifacts.
+- [Android 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
@@ -73,7 +81,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/debugger.md

@@ -0,0 +1,180 @@
+# Android 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,
+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.
+
+## 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.
+This contract applies to the Android backend; iOS debugging remains unsupported.
+
+## 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.
+
+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.