mobile-debug-mcp 0.32.4 → 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/specs/process.md

@@ -0,0 +1,213 @@
+# Development process
+
+This is the required development workflow for all agents contributing to
+`mobile-debug-mcp`. Read it before planning, editing, or reviewing changes,
+including work delegated to another agent. [AGENTS.md](../../AGENTS.md) is the
+shared entrypoint; tool-specific instructions must point here rather than
+maintain a competing workflow. Explicit user instructions take precedence.
+
+The agent owns investigation, implementation, and verification. The user or
+explicitly designated maintainer owns product decisions and approval. Existing
+explicit approval in the current conversation counts for unchanged scope; do
+not ask for it again. Never invent approval or treat silence as approval.
+
+## Choose the path
+
+Use the full process for new MCP capabilities, material tool behaviour or
+contract changes, and significant architecture changes. Use the lightweight
+path for fixes restoring agreed behaviour, refactors that preserve contracts,
+small maintenance changes, and documentation-only work. Move to the full path
+if investigation exposes new behaviour or unresolved product decisions.
+
+For the lightweight path:
+
+1. State the intended outcome and scope in the conversation.
+2. Inspect the relevant code, contracts, tests, and instructions.
+3. Make focused changes and run applicable verification below.
+4. Report the changes, evidence, and remaining limitations.
+
+Separate intent, spec, and plan files and approval stages are not required for
+the lightweight path. Documentation-only changes require a diff, link/path,
+and consistency check; application builds and device tests are unnecessary.
+
+For the full path, keep `intent.md`, `spec.md`, and `plan.md` together under
+`docs/specs/<next-number>-<feature>/`, following existing directory naming.
+Reuse the relevant feature directory where appropriate. Do not rewrite old
+specs retrospectively; add only what is needed for the current scope.
+
+## Keep artifacts concise
+
+Use these writing defaults for the full path:
+
+- `intent.md`: about 200 words covering the problem, outcome, scope, and open
+  questions, with the required source and status information.
+- `spec.md`: about 800 words focused on behaviour, contracts, failure handling,
+  acceptance criteria, and decisions needing approval.
+- `plan.md`: a short implementation checklist and verification table. Append
+  actual results as work finishes.
+
+These are defaults, not limits. Add detail when complexity or risk requires it;
+retain all applicable stage requirements and approval gates below. Record each
+decision once and reference it from later documents instead of repeating it.
+Use examples only where a contract would otherwise be ambiguous. Link detailed
+logs and evidence rather than copying them, while keeping enough result detail
+in the plan to assess coverage and any remaining failures or blockers.
+
+## 1. Capture intent
+
+Write `intent.md` with:
+
+- The original problem and its source, preserving the originator's meaning.
+- Desired outcome, affected MCP clients, platforms, and observable success criteria.
+- Constraints, exclusions, assumptions, and open questions.
+- Originator, date, and status; do not invent identities.
+
+Show the captured intent and obtain explicit agreement before drafting the
+spec. A clarification about one detail does not approve the complete intent.
+Record the approving response and its scope. While approval is pending,
+continue only investigation or independent work that does not assume it.
+
+**Exit:** the user has accepted the problem and scope, and questions blocking
+specification are answered.
+
+## 2. Investigate and specify
+
+Inspect the current checkout and preserve unrelated changes. Ground the design
+in existing code, tests, and [tool contracts](../tools/TOOLS.md). Reuse helpers
+and conventions rather than introducing new frameworks without a concrete need.
+
+Load applicable repository skills from [.agents/skills/](../../.agents/skills/README.md):
+
+- [Test authoring](../../.agents/skills/test-authoring/SKILL.md) before creating or updating tests.
+- [MCP builder](../../.agents/skills/mcp-builder/SKILL.md) for build, installation, or native toolchain work.
+- [Spec review](../../.agents/skills/spec-review/SKILL.md) when reviewing an RFC or spec draft.
+
+For device-dependent behaviour, inspect the current tool flow on an available
+device or emulator when practical. Record the platform, device, server build,
+observed behaviour, and inaccessible states. If unavailable, record the concrete
+blocker and available code/test evidence; plan a runnable device check.
+
+Write `spec.md` defining:
+
+- Required behaviour and plain-language acceptance criteria linked to the intent.
+- Scope, exclusions, failure, recovery, cancellation, and timeout behaviour.
+- MCP tool names, input schemas, response/error shapes, and compatibility impact.
+- Android/iOS differences and unsupported environments where applicable.
+- Device/process targeting, resource ownership and cleanup, concurrency, and
+  subprocess handling where relevant.
+- Security and privacy implications, including arguments, logs, screenshots,
+  UI trees, credentials, and potentially destructive device actions.
+- Affected modules, risks, assumptions, and unresolved decisions.
+- Approval status and a reference to the actual approving decision.
+
+Show the complete spec and obtain explicit acceptance before planning
+implementation. An instruction to implement an already accepted spec authorises
+that scope.
+
+**Exit:** the spec is accepted and decisions blocking correctness or scope are resolved.
+
+## 3. Plan implementation and verification
+
+Save `plan.md` with:
+
+- References to intent, spec, and approval decisions.
+- Affected files/modules and an ordered implementation checklist.
+- Dependencies, risks, compatibility, rollout, and cleanup steps as applicable.
+- Each acceptance criterion mapped to a meaningful automated or device check.
+- Exact verification commands and required runtime/toolchain versions.
+- For device checks: platform/device, starting state, actions, expected result,
+  evidence to capture, fixture requirements, and cleanup.
+- Unavailable prerequisites, their owner where known, and how to obtain them or
+  perform an equivalent check.
+
+Use the existing lightweight self-running `tsx` test pattern. No separate
+scenario language, scenario-approval stage, or new test framework is required.
+Routine technical planning choices do not need separate approval.
+
+Check scarce prerequisites early. Treat missing access as a planning blocker
+only when an essential acceptance criterion has no credible verification route.
+Do not describe readiness checks as verification of unimplemented behaviour.
+
+**Exit:** implementation is authorised within the accepted spec, the plan has
+no unresolved blocking dependency, and essential criteria have credible checks.
+
+## 4. Implement and handle discoveries
+
+Implement the agreed scope, add meaningful regression coverage where needed,
+and update the plan as work completes. Place tests according to the test-authoring
+skill: automated unit tests in `test/unit/`, automated device checks in
+`test/device/automated/`, and manual/debug helpers in `test/device/manual/`.
+
+Review changed code, tests, and relevant callers for contract consistency,
+platform differences, error handling, subprocess safety, resource cleanup,
+state ownership, and reliable assertions. Review depth should match the risk.
+
+When new evidence changes the work:
+
+- Update the plan for routine implementation choices.
+- Update the spec for design or contract changes. Obtain agreement before
+  implementing material changes to behaviour, scope, permissions, data handling,
+  compatibility, or acceptance criteria.
+- Update intent only if the problem or intended outcome changes; preserve the
+  original statement and record the accepted revision.
+- Record blockers and continue independent work. Do not silently weaken requirements.
+
+Keep [tool documentation](../tools/TOOLS.md), [README](../../README.md), and
+[changelog](../CHANGELOG.md) aligned when usage or behaviour changes.
+
+**Exit:** agreed implementation and relevant documentation are ready for verification.
+
+## 5. Verify and report
+
+For code or test changes, run focused checks during iteration and complete the
+maintainer verification command from the repository root:
+
+```sh
+npm run verify
+```
+
+This currently runs lint, TypeScript build, all automated unit tests, and the
+agent-plugin consistency check. Confirm scripts in [package.json](../../package.json)
+and applicable [CI workflows](../../.github/workflows) in the current checkout;
+report any difference between local validation and CI coverage.
+
+For changes affecting native device interaction, platform tooling, or runtime
+behaviour, also run applicable automated device checks:
+
+```sh
+npm run test:device
+```
+
+Confirm which platforms and behaviours the suite actually covers. Supplement
+it with focused end-to-end tool calls on the updated server where required by
+the acceptance criteria. A passing Android check does not establish iOS support;
+a dispatched action or mocked subprocess does not prove a real device outcome.
+
+For each relevant device journey, record the platform/device and server build,
+starting state, actions/tool calls, expected and observed result, evidence, and
+**pass**, **fail**, **blocked**, or **unrun** status. Include failure, recovery,
+interruption, and cleanup paths where relevant. Restore device settings and
+remove temporary test data after verification. If a platform or prerequisite is
+unavailable, state the concrete blocker and next step rather than claiming full
+verification.
+
+For schema changes, check registration, dispatch, runtime validation, response
+serialization, documentation, and callers/fixtures together. Distinguish local
+compatibility checks from testing an installed or published package.
+
+Investigate failures against the agreed contract. Do not weaken assertions,
+skip tests, add suppressions, or lower validation rules merely to get a pass.
+Distinguish pre-existing failures from regressions with evidence; neither is a
+pass. Fix issues introduced by the change and report unrelated findings separately.
+
+For documentation-only work, inspect the diff, validate changed relative links
+and referenced paths/commands, and check consistency across agent entrypoints.
+Required pull-request CI checks still apply.
+
+**Exit:** all agreed work and applicable checks have passed. Otherwise, report
+partial completion and identify failed, blocked, or unrun checks explicitly.
+
+The final report states what changed, verification commands and outcomes,
+relevant device evidence, focused review findings, and remaining limitations.
+Summarise successful output rather than pasting full logs. Commit, push, publish,
+and release only within the user's authorised workflow.

package/docs/tools/TOOLS.md

@@ -7,6 +7,11 @@ This repository groups the MCP tools into four areas aligned with the codebase:
 - [interact](interact.md) — UI resolution, actions, waits, and deterministic verification
 - [system](system.md) — environment and health checks
 
+Correlation metadata and explicit action references are documented in
+[correlated evidence](evidence.md). Android performance capture is documented in
+[system traces](system-traces.md). Android bytecode debugging is documented in
+[runtime debugger](debugger.md).
+
 ## Agent guidance
 
 For interactive flows, the intended deterministic pattern is:

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

@@ -0,0 +1,82 @@
+# Correlated evidence
+
+Covered actions (`start_app`, `restart_app`, `tap`, `tap_element`, `swipe`,
+`scroll_to_element`, `type_text`, `press_back`, `adjust_control`) return an
+additive `evidence` object in their first JSON content block. Journey steps have
+individual action IDs and share the journey correlation ID.
+
+To associate a later observation, copy the action's `evidence.session_id` and
+`evidence.action_id` into `actionRef`:
+
+```json
+{
+  "platform": "android",
+  "deviceId": "emulator-5554",
+  "actionRef": { "sessionId": "<evidence.session_id>", "actionId": "<evidence.action_id>" }
+}
+```
+
+Supported observation tools: `capture_screenshot`, `get_ui_tree`,
+`get_screen_fingerprint`, `capture_debug_snapshot`, `get_logs`, `read_log_stream`.
+The reference object accepts only those two keys, each a string of 1–128
+characters. Malformed references fail before collection. References never select
+or redirect devices. A missing reference creates independent evidence; there is
+no automatic association with the latest action.
+
+Completed actions remain referenceable for 10 minutes, with at most 1,000 records
+per server process. Restart changes the session. Unknown, expired, foreign-session,
+or different-device references still collect independently: `association` is
+`unavailable`, `association_reason` explains why, and `action_id` is null.
+
+## Reading metadata
+
+`session_id`, `correlation_id`, `action_id`, `device`, and `association` identify
+the operation. Association is `self`, `explicit`, `internal`, `none`, or
+`unavailable`. Target scope is the resolved device; UI evidence is device-wide.
+`requested_action_ref` preserves an explicit reference, including unavailable ones.
+
+Phase fields are server UTC epoch milliseconds:
+
+- `operation_started_at_ms` / `operation_completed_at_ms`: this call.
+- `dispatch_started_at_ms` / `dispatch_completed_at_ms`: actual action dispatch,
+  first start through last completion for multi-input actions.
+- `verification_completed_at_ms`: verification attempt completion, including
+  failure or timeout; null when skipped. Read the existing verification status
+  to determine its outcome.
+
+Unreached/uninstrumented phases are null. Host monotonic time governs ordering
+and retention. A detected clock reversal yields unknown freshness and null age.
+
+`observations` contains separate screenshot, UI-tree, fingerprint, activity, and
+log records. Each has `evidence_id`, device, component status (`captured`, `failed`,
+`omitted`), acquisition start/completion, source capture time, age, freshness and
+reasons. Tree records retain snapshot session/revision references. Failed records
+preserve available errors; disabled captures are omitted. Snapshot components
+are collected independently, including fallback log reads; they are not atomic.
+
+Visual freshness is evaluated when the response is assembled:
+
+| Status | Meaning |
+| --- | --- |
+| `fresh` | Newly acquired with no known intervening covered dispatch; app state may still change. |
+| `stale` | Before the associated action or superseded by a later covered dispatch. |
+| `unknown` | Overlap, reuse, failure, unknown scope/timing, or clock discontinuity. |
+| `not_applicable` | Omitted logs. |
+
+Cached source times are preserved. `age_ms` is nullable; clients choose their own
+age limits. Freshness does not replace conditional-action safeguards.
+
+Log timestamps remain on their original device/unknown clock. Log records expose
+`clock: "device_or_unknown"`, `event_time_comparable: false`, and nullable earliest/
+latest parseable entry times. Collection after an action does not prove emission
+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` 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.