mobile-debug-mcp 0.33.0 → 0.34.0

package/docs/specs/023-android-system-traces/device-evidence.json

@@ -0,0 +1,38 @@
+{
+  "status": "PASS",
+  "build_sha256": "f59ec5112751295517ce3fd6fafe78e06ca009f30ecfcc560c872bfbf1cf86ee",
+  "runtime": "v23.11.0",
+  "server": {
+    "name": "mobile-debug-mcp",
+    "version": "0.33.0"
+  },
+  "device": "emulator-5554",
+  "osVersion": "16",
+  "starting_state": "System Settings fixture",
+  "journey": "start Settings, assert baseline Settings-owned resource visible in UI tree; explicit trace association",
+  "trace_id": "7a0bdca9-f64f-4c4f-b204-5c9b7527c2c6",
+  "correlation_id": "6622a71c-e556-4e27-b228-1eb0328f0637",
+  "phases": {
+    "capture_started_at_ms": 1793359970395,
+    "capture_completed_at_ms": 1793359976096
+  },
+  "artifact_bytes": 870332,
+  "content": {
+    "packets": 227,
+    "ftrace_bundles": 210,
+    "events": 19833,
+    "compact_sched_bundles": 210,
+    "validation": "local protobuf structure, trace config duration and timestamped ftrace/compact scheduler content; not full Perfetto analysis"
+  },
+  "durationContent": {
+    "packets": 51,
+    "ftrace_bundles": 35,
+    "events": 4596,
+    "compact_sched_bundles": 35,
+    "validation": "local protobuf structure, trace config duration and timestamped ftrace/compact scheduler content; not full Perfetto analysis"
+  },
+  "cancel": "PASS",
+  "expired_journey": "PASS",
+  "active_shutdown": "PASS",
+  "cleanup": "Device capture files removed; test host artifacts removed in finally. No settings or app data changed. Settings remains foreground."
+}

package/docs/specs/023-android-system-traces/emulator-recheck.json

@@ -0,0 +1,38 @@
+{
+  "status": "PASS",
+  "build_sha256": "f59ec5112751295517ce3fd6fafe78e06ca009f30ecfcc560c872bfbf1cf86ee",
+  "runtime": "v23.11.0",
+  "server": {
+    "name": "mobile-debug-mcp",
+    "version": "0.33.0"
+  },
+  "device": "emulator-5554",
+  "osVersion": "16",
+  "starting_state": "System Settings fixture",
+  "journey": "start Settings, assert baseline Settings-owned resource visible in UI tree; explicit trace association",
+  "trace_id": "af7507e9-90ee-48e1-af43-f81bf3a66840",
+  "correlation_id": "dfe3e3ae-54f1-4c7a-afad-0c5ee76ede12",
+  "phases": {
+    "capture_started_at_ms": 1793360613568,
+    "capture_completed_at_ms": 1793360619070
+  },
+  "artifact_bytes": 996053,
+  "content": {
+    "packets": 230,
+    "ftrace_bundles": 213,
+    "events": 23054,
+    "compact_sched_bundles": 213,
+    "validation": "local protobuf structure, trace config duration and timestamped ftrace/compact scheduler content; not full Perfetto analysis"
+  },
+  "durationContent": {
+    "packets": 54,
+    "ftrace_bundles": 36,
+    "events": 3094,
+    "compact_sched_bundles": 36,
+    "validation": "local protobuf structure, trace config duration and timestamped ftrace/compact scheduler content; not full Perfetto analysis"
+  },
+  "cancel": "PASS",
+  "expired_journey": "PASS",
+  "active_shutdown": "PASS",
+  "cleanup": "Device capture files removed; test host artifacts removed in finally. No settings or app data changed. Settings remains foreground."
+}

package/docs/specs/023-android-system-traces/intent.md

@@ -0,0 +1,40 @@
+# Intent: Android system traces
+
+Originator: repository maintainer, through GitHub roadmap issue #67.
+Date: 2026-10-30. Status: approved.
+Source: [issue #67](https://github.com/clivejefferies/mobile-debug-tools/issues/67), roadmap priority 4 of 9.
+
+## Problem and outcome
+
+MCP clients investigating slow or frozen Android interactions need system-level
+performance evidence alongside existing journey and observation evidence.
+The server currently has no system-trace capture capability.
+
+Enable clients to start a bounded Android system trace, run an existing journey,
+stop capture, and obtain a local Perfetto artifact with device, capture timing,
+and correlation metadata. Detect available profiling capabilities explicitly and
+report unsupported environments, failures, cancellation, and cleanup outcomes.
+
+## Scope and success criteria
+
+- Android capture around existing journeys, reusing established device targeting
+  and correlated-evidence conventions.
+- Optional profiling tooling with explicit capability and prerequisite reporting.
+- Local artifact handling and bounded capture/resource ownership.
+- Successful start/stop and artifact retrieval on a supported Android fixture.
+- Explicit failure/cancellation outcomes and cleanup of session-owned resources.
+
+## Exclusions and open decisions
+
+Exclude iOS tracing, runtime debugging, heap dumps, automatic performance diagnosis,
+and changes to journey interaction semantics. Do not upload trace contents.
+
+Specification must establish the supported backend/tooling, tool contracts,
+capture limits/configuration, concurrent-session rules, cancellation/recovery,
+artifact retention, privacy handling, and verification prerequisites. The issue's
+Android CLI integration is provisional and requires investigation.
+
+## Approval
+
+The maintainer approved the complete captured intent with “yes” in this
+conversation on 2026-10-30. Specification approval remains pending.

package/docs/specs/023-android-system-traces/plan.md

@@ -0,0 +1,117 @@
+# Plan: Android system traces
+
+Authorised by [intent](intent.md) (“yes”) and [specification](spec.md)
+(“looks good”, followed by “great”), 2026-10-30 in this conversation.
+
+## Implementation
+
+- [x] Implement ADB capability/capture adapter with PID identity and bounded files.
+- [x] Implement serialised sessions, deadlines, retries, retention and shutdown.
+- [x] Register strict schemas/tools, link journeys and propagate trace evidence.
+- [x] Add regression/device tests and align README/tool docs/changelog.
+- [x] Review ownership/failure/concurrency/contracts; run verification below.
+
+Use existing device resolver, ADB path helper, execution helper and async-local
+evidence context. Node >=18; CI uses Node 18 and local runtime is recorded below.
+No installation, publishing, commit or push is required. Android CLI absent;
+ADB/Perfetto available on emulator-5554 API 36. Inspect trace content with a local
+parser or Perfetto UI; missing viewer/parser blocks artifact-format proof, not
+implementation. Avoid downloading tooling without need.
+
+## Verification
+
+| Criteria | Evidence |
+| --- | --- |
+| 1 capability/no side effects | Fake adapter/ADB tests, strict runtime/registration schemas, iOS rejection. |
+| 2 artifact/correlation | Updated stdio server: emulator start, Settings journey, stop, nonempty bounded artifact and Perfetto content inspection. |
+| 3 lifecycle/isolation | Deterministic injected adapter/clock tests: duration, cancel, repeated controls, contention, stale IDs, reused PID, concurrent devices. |
+| 4 failures/cleanup | Tests: missing tool/service, start/stop/pull timeout, disconnect, partial transfer, shutdown and mismatch without journey dispatch; real cancel/expiry. |
+| 5 compatibility | Existing unit/device suites and additive schema/serialization assertions. |
+
+Commands: `node --import tsx test/unit/observe/system-trace.test.ts`,
+`node --import tsx test/unit/server/system-trace.test.ts`, `npm run verify`,
+`npm run test:device`. Local verify adds plugin checks beyond CI; CI device
+workflow is manual and Android API 30, local suite additionally requires iOS.
+
+Device smoke: fresh discovery, explicit Android emulator, rebuilt 0.33.0 stdio
+server. Start in Settings; capture a start_app Settings journey; assert identifiers,
+state, artifact size and cleanup. Repeat cancellation, duration expiry and invalid
+journey reference. Inspect resulting Perfetto packets; save metadata only in this
+directory. Remove test-owned host artifacts; no app data/settings changes. State
+pass/fail/blocked/unrun, build hash, device and gaps. Physical-device capture and
+installed/published package remain separate from emulator evidence.
+
+## Results
+
+Implementation and focused review completed on 2026-10-30 on
+`codex/android-system-traces`, based on `a74238b`. Changes remain uncommitted;
+no push, publication or installed-package update was requested.
+
+- Local runtime: Node 23.11.0 / npm 10.9.2. CI's Node 18 runtime remains **unrun**
+  locally; the final CI workflow was not invoked. Existing CI uses Node 18 and
+  manual Android API 30 integration; local device evidence uses API 36.
+- Focused session, Android adapter and tool/journey contract checks: **pass**.
+  Cover strict input/error flags, unsupported iOS/no dispatch, missing native
+  prerequisites, bounded capture, successful transfer permissions, cancellation,
+  automatic duration completion, failed/empty/oversized/partial transfers,
+  stop/start timeouts, unavailable devices, retry, PID reuse, naturally exiting
+  processes, simultaneous control calls, parallel devices, active shutdown,
+  shutdown racing start, metadata expiry/eviction and trace evidence isolation.
+- `npm run verify`: **pass** on the final code (68 unit files, lint, TypeScript
+  build, plugin consistency). The tsx CLI requires local IPC
+  blocked by the sandbox, so the required command ran with approved escalation.
+- `npm run test:device`: **pass** on the final runtime code, eight smoke files.
+  Existing Android/iOS screenshot, tree, log and correlation checks pass; correlation
+  pins emulator-5554 and iPhone 17 Pro simulator
+  F9243BAF-62A8-4990-8A99-17F527F56FDA (iOS 26.4). The six older platform smokes use
+  automatic targeting and do not all identify the selected device.
+- Focused updated stdio-server trace journeys: **pass** on Android 16
+  emulator-5554, local package 0.33.0. Final combined runtime hash:
+  `f59ec5112751295517ce3fd6fafe78e06ca009f30ecfcc560c872bfbf1cf86ee`.
+  Fresh Settings baseline, traced launch and semantic assertion of a visible
+  Settings-owned resource, matching trace/journey/step IDs, local artifact,
+  idempotent stop, inactive reference rejection, cancellation, 1,001 ms duration
+  expiry, and closing another server during active capture all pass.
+- Artifact format/content: **pass** using the local protobuf decoder: complete
+  Trace.packet boundaries, embedded requested duration, timestamped ftrace events
+  and compact scheduler bundles. Final full-suite artifact: 870,332 bytes,
+  227 packets, 19,833 timestamped events and 210 compact scheduler bundles.
+  This is structural/content evidence, not full Perfetto UI/SQL analysis.
+- Device metadata is in [device-evidence.json](device-evidence.json), without
+  trace contents, UI text, screenshots or logs. Test-owned device/host capture
+  artifacts are removed. No device settings or app data changed; Settings remains
+  foreground. Final device-directory inspection confirms no test trace files
+  remain. The first shutdown regression test's bounded leftover file was
+  removed individually after confirming its process had exited.
+- Review corrected stdin-end cleanup (the SDK does not emit transport close on
+  stdin EOF), process-exit races around identity reads/SIGTERM, error flags for
+  unsupported action-control fields, and conservative journey coverage when
+  capture state becomes unavailable. Unreadable/reused live identity still fails
+  closed. No outstanding findings in the implemented scope.
+- The initial extra UI assertion expected a Settings title, but Settings resumed
+  Network & internet. The smoke now establishes a fresh Settings-owned resource
+  baseline and proves that element is visible during the journey. No assertion
+  was removed, and no fixture settings were changed.
+- Physical Android capture, actual unplug/disconnect and hard-crash recovery:
+  **unrun**; deterministic adapter/session failure coverage passes. iOS tracing is
+  explicitly unsupported, with rejection tested. Installed/published-package and
+  full trace-analysis verification remain **unrun**.
+
+Validation logs: `/tmp/mobile-debug-system-traces-verify.log`,
+`/tmp/mobile-debug-system-traces-device.log`, and
+`/tmp/mobile-debug-system-traces-focused-device.log`.
+Changed documentation links, evidence JSON and whitespace checks pass.
+
+## Emulator recheck — 2026-10-30
+
+User requested a fresh emulator test. Rebuilt with `npm run build` (**pass**),
+then ran `SYSTEM_TRACE_EVIDENCE_PATH=docs/specs/023-android-system-traces/emulator-recheck.json node --import tsx test/device/automated/observe/system-trace.smoke.ts`
+on emulator-5554, Android 16, local stdio server 0.33.0, same runtime hash as above.
+**Pass:** fresh Settings UI baseline, traced launch and semantic visibility
+assertion, correlated IDs, nonempty Perfetto artifact with timestamped kernel and
+scheduler content, repeated stop, inactive reference rejection, cancellation,
+1,001 ms expiry, and active-capture server shutdown cleanup. Artifact: 996,053
+bytes, 230 packets, 23,054 timestamped ftrace events. Test-owned host/device trace
+files removed; no settings or app data changed. Settings remains foreground.
+Metadata: [emulator-recheck.json](emulator-recheck.json). Full Perfetto analysis,
+physical devices and failure-by-unplug were not part of this recheck.

package/docs/specs/023-android-system-traces/spec.md

@@ -0,0 +1,120 @@
+# Specification: Android system traces
+
+Date: 2026-10-30. Status: approved.
+Source: [issue #67](https://github.com/clivejefferies/mobile-debug-tools/issues/67).
+[Intent](intent.md) approved by the maintainer’s “yes” in this conversation.
+Specification approved by “looks good” followed by “great” on 2026-10-30.
+
+## Backend and boundaries
+
+Use the device’s Perfetto CLI through existing ADB discovery/execution helpers.
+Require Android API 29+, authorised ADB, supported background-wait options,
+tracing services, and writable trace storage. Probe capabilities without starting
+capture. No SDK installation, root, external downloads, Android CLI dependency,
+or fallback to legacy systrace. iOS returns unsupported before side effects.
+Android CLI is absent locally; official Android documentation supports direct
+ADB capture. Analysis skills/SQL and trace interpretation remain out of scope.
+
+## Tools and schemas
+
+All objects reject unknown fields. IDs are opaque server-generated UUIDs.
+
+- `get_system_trace_capabilities({platform, deviceId?})`: resolve one device;
+  return supported/backend, resolved device, prerequisites, limitations, reasons.
+- `start_system_trace({platform, deviceId?, durationMs?})`: integer duration
+  1,000–120,000, default 30,000. Return recording session only after Perfetto’s
+  data-source-start acknowledgement; otherwise return failure and cleanup result.
+- `get_system_trace_status({traceId})`: reconcile owned process/deadline and return
+  current state; finalise automatically completed capture when queried.
+- `stop_system_trace({traceId})`: gracefully stop, retrieve and finalise artifact.
+- `cancel_system_trace({traceId})`: stop and discard owned device/partial local
+  files; return cancelled plus cleanup outcome. Completed artifacts are retained.
+
+Trace ID determines the pinned device; control calls cannot redirect it. Unknown,
+expired, or previous-server IDs return `TRACE_NOT_FOUND`. One recording per device,
+maximum four server-wide; reject excess with `TRACE_BUSY`. Concurrent operations
+on one session serialise; repeated terminal operations return the stored outcome.
+Retain at most 100 terminal records for 10 minutes; expiry never deletes completed
+artifacts. Starting/active records are not evicted.
+
+Responses use JSON text with `trace_id`, `session_id`, `device`, `backend: perfetto`,
+`state` (starting/recording/stopping/completed/cancelled/failed), `reason`,
+`capture_started_at_ms`, `capture_completed_at_ms`, `completion_reason`
+(requested/duration_limit/cancelled/error), `artifact`, `cleanup`, and
+`correlation_ids`. Unreached values are null. Artifact is null or contains absolute
+`path`, `format: perfetto`, and `size_bytes`. Cleanup reports pending/complete/failed
+and remaining owned resources. Errors retain known session metadata, use MCP
+`isError`, and distinguish 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 queries with unsupported prerequisites are normal supported:false results.
+
+## Capture and lifecycle
+
+Use a fixed scheduling/input/rendering preset (sched, freq, idle, am, wm, gfx,
+view, input), 16 MiB ring buffer, and maximum output 32 MiB. Report enabled sources
+and unavailable categories; unavailable required sched/input categories reject
+start. No arbitrary config, package wildcard annotations, heap, screenshots, or
+logcat data sources. This is device-wide evidence, not app-private capture.
+
+Generate unique device paths under `/data/misc/perfetto-traces/`. Start with
+background-wait and device-side duration limit. Record PID and process identity;
+before SIGTERM validate both identity and unique output path. Never kill by process
+name or signal a reused/unverified PID. Poll boundedly for termination before pull;
+uncertain stop yields failure, never a successful artifact. Allow 35 seconds for
+start acknowledgement, 10 for stop, and 30 for pull; subprocesses must terminate
+on deadlines. Failed cleanup is explicit and retryable through control calls.
+
+A server timer stops/finalises at duration; device duration also bounds capture
+if the server dies. Normal shutdown attempts owned cleanup within 10 seconds;
+crash recovery is not promised. A crash may leave its uniquely named device file
+for manual removal; no restart-wide sweep. Host subprocess termination alone is
+never reported as stopping device capture.
+
+Pull into a unique server-created temporary directory with restrictive permissions;
+rename only after successful transfer and nonempty size <=32 MiB. Return paths,
+never binary/base64 contents. Remove owned device files after verified pull, retain
+local artifacts for user-managed deletion. Pull failure retains bounded device
+output for retry; cancelled partial files are removed. No upload or telemetry.
+
+## Journey and evidence association
+
+Add optional `systemTraceId` to `run_journey`. Validate active same-server,
+same-device recording before any journey input; mismatch/inactive ID fails without
+executing steps. Preserve existing journey semantics and correlation IDs. It is
+explicit bracketing: start, run journey, stop; journeys do not own trace lifetime.
+A failed journey leaves capture available for stop/cancel or duration expiry.
+
+Extend evidence `trace_context` for explicitly linked journey/step observations:
+`supported:true`, `trace_id`, `markers:[]`. Otherwise preserve the existing
+unsupported/null context. Record linked journey correlation IDs in trace metadata;
+report capture ending during a journey as partial coverage. No injected device
+markers, clock synchronisation, causal claims, or inferred associations. Host UTC
+intervals and monotonic duration do not claim alignment with device trace clocks.
+
+## Acceptance and verification
+
+1. Capability detection and invalid arguments cause no recording side effects.
+2. Emulator start → existing Settings journey → stop produces a nonempty local
+   Perfetto artifact and matching trace/journey evidence IDs; inspect with an
+   available trace parser/viewer before claiming valid Perfetto content.
+3. Duration completion, explicit cancel, repeated controls, same-device contention,
+   concurrent devices, stale IDs, PID reuse and cleanup failures have deterministic tests.
+4. Test missing tools/services, start/stop/pull timeout, device disconnect, partial
+   transfer, shutdown, and journey mismatch; report real-device gaps explicitly.
+5. Existing clients without tracing retain contracts. Run maintainer verification,
+   automated device suite, and focused updated-server trace journeys.
+
+Affected: new observe/session adapter, tool registration/validation/handlers,
+journey schema/execution, evidence context/types, lifecycle shutdown, tests,
+README/tool docs/changelog. Main risks: platform source availability, process
+ownership races, finalisation correctness, storage/privacy, and absent parser.
+
+Baseline: local package 0.33.0; emulator-5554 Android API 36 exposes Perfetto
+background-wait, bounded output, and graceful PID-stop options. Pixel 9 Pro is
+also connected but untested. ADB inspection passed after sandbox escalation;
+no capture or new behaviour has been verified. Physical-device and iOS tests
+remain unrun. Approval of this complete specification authorises implementation.
+
+Sources: [Android Perfetto CLI](https://developer.android.com/tools/perfetto),
+[Perfetto background capture](https://perfetto.dev/docs/learning-more/tracing-in-background).

package/docs/specs/024-android-heap-dump-capture/intent.md

@@ -0,0 +1,39 @@
+# Intent: Android heap dump capture
+
+Originator: clivejefferies, through GitHub roadmap issue #69 and the current conversation.
+Date: 2026-10-30. Status: parked; intent not approved.
+Source: [issue #69](https://github.com/clivejefferies/mobile-debug-tools/issues/69), roadmap priority 6 of 9.
+
+## Problem and outcome
+
+MCP clients investigating Android memory growth and out-of-memory failures need
+a heap dump they can inspect with external analysis tools. Provide capture of a
+supported running Android app's heap and return a local artifact with device,
+app, capture-time, and artifact-path metadata.
+
+## Scope and success criteria
+
+- Capture and retrieve an Android heap dump for an explicitly targeted app/process.
+- Report device, app/process identity, capture timing, and the local artifact path.
+- Detect unsupported configurations and report failed, cancelled, and timed-out
+  captures clearly.
+- Bound capture work and clean up capture-owned temporary resources.
+- Verify successful artifact retrieval on a supported Android fixture, alongside
+  meaningful failure and cleanup checks.
+
+## Exclusions and open decisions
+
+Exclude iOS capture, deep heap analysis, leak diagnosis, automatic uploads, and
+changes to app behaviour or permissions to enable capture.
+
+Specification must resolve supported app/device configurations, capture backend
+(including whether optional Android CLI tooling is useful), process selection,
+tool contracts, limits, cancellation, concurrency, artifact retention, privacy,
+and device-verification prerequisites. Heap contents can include sensitive app
+data; capture and artifact handling must make their ownership explicit.
+
+## Approval
+
+The user switched to Android runtime debugger work before approving this intent.
+Heap capture remains parked pending explicit agreement on the complete intent. No specification or
+implementation approval is recorded.

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

@@ -0,0 +1,40 @@
+# Intent: Android runtime debugger
+
+Originator: clivejefferies, through GitHub roadmap issue #68 and the current conversation.
+Date: 2026-10-30. Status: approved.
+Source: [issue #68](https://github.com/clivejefferies/mobile-debug-tools/issues/68), roadmap priority 5 of 9.
+
+## Problem and outcome
+
+MCP clients investigating incorrect Android app behaviour need runtime evidence
+to test hypotheses: where execution stopped, how it got there, and the values
+available at that point. Enable a bounded debugging session against an explicitly
+selected debuggable app process on a specific Android device.
+
+## Scope and success criteria
+
+- Attach and detach, set source breakpoints, and report stop events.
+- Inspect stacks and locals while paused; step and resume execution.
+- Bind sessions to device/process identity and invalidate inspection references
+  when execution resumes or the session ends.
+- Coordinate UI actions and verification with known debugger pauses.
+- Report unsupported configurations and setup/runtime failures explicitly.
+- On detach or failure, clean up only session-owned resources and handle
+  debugger-owned suspension explicitly.
+- Verify the complete journey on a debuggable Android fixture.
+
+## Exclusions and open decisions
+
+Defer arbitrary expression evaluation, value mutation, coroutine reconstruction,
+native debugging, iOS debugging, heap capture, and production-app enablement.
+
+The ticket proposes an independently developed JDI worker. Specification must
+validate that backend and establish prerequisites, MCP contracts, source/line
+mapping limits, suspension policy, event delivery, timeouts, cancellation,
+concurrency, crash recovery, privacy, and runnable fixture coverage.
+
+## Approval
+
+The user selected Android runtime debugger work with “ok, lets pick that up” and
+approved the complete captured intent with “yes” on 2026-10-30 in this
+conversation. Specification approval remains pending.

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

@@ -0,0 +1,104 @@
+# Plan: Android runtime debugger
+
+2026-10-30. [Intent](intent.md) and [spec](spec.md) explicitly approved by the
+user's successive “yes” responses in this conversation. Implementation authorized.
+
+## Implementation
+
+- [x] Build optional JDK 17+ worker compilation/cache and bounded JSON-lines client.
+- [x] Implement JDI attach, breakpoint events, bounded inspection, step/resume,
+  reference epochs, expiry and owned cleanup.
+- [x] Implement explicit Android process identity/JDWP targeting and owned forwarding.
+- [x] Register strict MCP contracts and serialize session transitions.
+- [x] Integrate pause evidence, dispatch/wait/lifecycle guards and shutdown.
+- [x] Add isolated debuggable fixture, regression tests and native journeys.
+- [x] Align capabilities, packaging, tools, README and changelog; review consistency.
+
+## Verification
+
+| Criteria | Checks |
+| --- | --- |
+| Explicit targeting/unsupported/ambiguity | Native adapter tests; emulator fixture attach and capability calls |
+| Breakpoints/stacks/locals/steps | Real Android fixture through built MCP stdio; no separate JVM debuggee required |
+| Stale references/bounds/metadata | Unit contract checks plus Android stale inspection, bounded locals and source metadata checks |
+| UI pause and races | Guard/readiness unit checks; paused fixture action, wait and journey; resumed UI assertion |
+| Detach/failure/expiry/ownership | Unit worker/session tests, native disconnect and forward comparison |
+| Packaging/compatibility | npm pack --dry-run; npm run verify; worker compile --release 17 |
+| Existing runtime | npm run test:device; inspect actual platform coverage |
+
+Prerequisites: Node >=18, JDK >=17 with javac/jdk.jdi; Android SDK platform/build-tools
+36 for fixture, platform-tools. Host currently Java 23/ADB 37.0.1; emulator-5554
+API 36 arm64 online outside sandbox. Existing CI: Node 18, manual Android JDK17/API30.
+Use separate dev.mobiledebugmcp.debugfixture app with javac -g. Capture source-line
+and known-local evidence; remove fixture, temporary outputs and owned forwards.
+Physical device and iOS debugger verification are not required by this Android
+scope; report them unrun/unsupported. Never treat readiness probes as debug proof.
+
+## Results
+
+Implemented and reviewed locally. No commit, push, release or hosted CI run performed.
+
+- **PASS** `npm run verify`: lint, TypeScript build, all self-running unit tests,
+  agent-plugin consistency. Focused debugger tests cover schema strictness,
+  identity/PID reuse, exact-forward ownership, event wait concurrency/overflow,
+  stale stops, inspection versus mutation timeout policy, worker failure,
+  cleanup retry, no-read paused readiness and mid-journey preservation.
+- **PASS** `npm run test:device`: existing Android/iOS screenshot, log, hierarchy
+  and correlated-evidence smoke checks; Android Perfetto journeys. The debugger
+  case reports **UNRUN** without its explicit device environment variable and is
+  independently verified below. Generic observations do not prove iOS debugging.
+- **PASS** `MCP_DEBUGGER_DEVICE=emulator-5554 npx tsx test/device/automated/debugger/runtime.android.test.ts`:
+  built server 0.33.0 over actual MCP stdio; Node 23.11.0, worker JBR 25.0.3,
+  API 36/Android 16 arm64 emulator. Final full dist/worker fingerprint:
+  `5281d7127822e83355f6be1fcf81555827a078839364fb5115d4644d63d6048d`.
+  Isolated fixture starts at Ready; explicit attach, correct source breakpoint,
+  known local 42, 256-character string truncation and shallow object identity pass.
+  A separately compiled fixture with no local-variable tables establishes explicit
+  ART metadata uncertainty rather than an inferred empty scope. Removed pending
+  breakpoints remain removed when another request prepares the same class.
+  Into/over/out, stale frame rejection and resume pass; a fresh UI tree establishes
+  Result 43. Pending class resolves and stops; invalid line is rejected. Capability
+  deadline and missing app outcomes are explicit. Paused input/wait/lifecycle/journey
+  calls block; MCP event-wait cancellation leaves the stop intact. Reattach after
+  detach and process-exit cleanup pass. Closing MCP while actively paused removes
+  the owned forward; an independent fresh server observes Result 43 afterward.
+  Fixture package, temporary outputs and owned forwards are removed; pre-existing
+  forwards and device display settings are preserved.
+- **PASS** extended stdio journey with `MCP_DEBUGGER_EXTENDED=1`: real 60-second
+  continuous-pause expiry despite repeated client polling, with complete owned
+  cleanup. Core-build fingerprint at that earlier checkpoint:
+  `76c0937b01aa296839783651bd9f445b0a1855f3e5416a4f3d41cf8a04a4757d`.
+  Later bounded-memory/heartbeat changes are covered by the final native journey;
+  pause-limit logic was unchanged. This earlier hash covers the named debugger
+  modules/worker, unlike the final complete dist/worker fingerprint.
+- **PASS** standalone `javac --release 17 --add-modules jdk.jdi` compilation;
+  `npm pack --dry-run --json` includes worker source and built debugger/schema modules.
+  CI YAML parses; unit CI now compiles the worker on JDK 17 and checks packaging;
+  manual Android CI installs fixture SDK prerequisites and selects its emulator.
+  Hosted CI and JDK 17 runtime execution remain **UNRUN** locally.
+
+Focused review corrected bounded JDWP subscription discovery, integer IPC,
+terminal-state/cleanup races, import-order coupling, MCP stdout diagnostic leakage,
+mutation cancellation/deadlines, device-specific guards, and event-poll activity
+accounting, removed pending-breakpoint rebinding, per-location code-index identity,
+and ART empty-table uncertainty. Test fixture content was moved below Android edge-to-edge system bars.
+
+Remaining limits: physical-device debugging, API 30 CI execution, Windows/Linux
+native runtime, Kotlin-specific metadata, and concurrent class-loader breakpoint
+variants are **UNRUN**. ART empty/absent-variable metadata ambiguity is native-verified; the distinct JDI
+AbsentInformationException path is code-inspected.
+String truncation is native-verified; multi-device/race paths have unit coverage,
+not exhaustive native coverage. Real
+five-minute idle and 30-minute total expiry have not been wall-clock exercised;
+all host expiry boundaries have deterministic unit checks;
+the real pause expiry has. iOS/native/evaluation/mutation/coroutine debugging are
+excluded. Abrupt host loss cannot guarantee confirmed device resumption.
+
+
+Verification note: one late full run failed the unchanged conditional-action
+150 ms action-budget assertion (`condition read does not consume the action
+budget`). The focused test passed unchanged on both the current implementation
+and an isolated HEAD archive; this does not prove the intermittent failure
+predates this change. The final full `npm run verify` run passed in isolation, including the unchanged
+conditional-action test. No timeout,
+assertion, validation rule or test selection was weakened.