mobile-debug-mcp 0.34.0 → 0.35.0

package/docs/specs/026-code-structure-and-quality-gates/verification-thin-facade.json

@@ -0,0 +1,154 @@
+{
+  "date": "2026-10-30",
+  "scope": "ToolsInteract thin-facade continuation",
+  "status": "pass",
+  "class_budget": {
+    "class": "ToolsInteract",
+    "counted_lines": 189,
+    "maximum": 300,
+    "physical_file_lines": 267,
+    "legacy_exceptions": 0,
+    "refactored_interaction_modules_without_exceptions": 41
+  },
+  "maintainer": {
+    "command": "npm run verify",
+    "status": "pass",
+    "unit_files": 81,
+    "node": "v23.11.0"
+  },
+  "device": {
+    "command": "MCP_DEBUGGER_DEVICE=emulator-5554 npm run test:device",
+    "status": "pass",
+    "device_files": 10,
+    "records": [
+      {
+        "status": "PASS",
+        "build_sha256": "3a6b4e2f1e806c2d98968e63595dba9f5f23a1fe32a86943f208143c75fb8924",
+        "device": "emulator-5554",
+        "api": "36",
+        "runtime": "v23.11.0",
+        "transport": "MCP stdio",
+        "extended": false
+      },
+      {
+        "status": "PASS",
+        "server": {
+          "name": "mobile-debug-mcp",
+          "version": "0.34.0"
+        },
+        "device": "emulator-5554",
+        "api": "36",
+        "runtime": "v23.11.0",
+        "journey": "clickable wait, resolved-handle tap, visible assertion, selector journey and stable enabled-state assertion",
+        "evidence": "Result 43 and enabled=true established by fresh hierarchy assertions",
+        "cleanup": "Owned fixture removed in finally; no other app data or device settings changed"
+      },
+      {
+        "status": "PASS",
+        "server": {
+          "name": "mobile-debug-mcp",
+          "version": "0.34.0"
+        },
+        "platform": "android",
+        "device": "emulator-5554",
+        "osVersion": "16",
+        "startingApp": "com.android.settings",
+        "actionId": "11ac289e-7cad-4703-9244-a857de31999d",
+        "phases": {
+          "dispatchStarted": 1793385281935,
+          "dispatchCompleted": 1793385282207,
+          "screenshotStarted": 1793385282799,
+          "screenshotCompleted": 1793385283084
+        },
+        "screenshot": "captured",
+        "logs": "captured",
+        "uiTree": "captured",
+        "disabledComponents": "omitted",
+        "foreignReference": "unavailable",
+        "cleanup": "No settings, app data or streams changed; Settings remains foreground. No content artifacts saved."
+      },
+      {
+        "status": "PASS",
+        "server": {
+          "name": "mobile-debug-mcp",
+          "version": "0.34.0"
+        },
+        "platform": "ios",
+        "device": "F9243BAF-62A8-4990-8A99-17F527F56FDA",
+        "osVersion": "iOS 26.4",
+        "startingApp": "com.apple.Preferences",
+        "actionId": "d4c7ae0a-dda5-4606-a9bf-46356b9f378a",
+        "phases": {
+          "dispatchStarted": 1793385290788,
+          "dispatchCompleted": 1793385291152,
+          "screenshotStarted": 1793385291585,
+          "screenshotCompleted": 1793385292091
+        },
+        "screenshot": "captured",
+        "logs": "captured",
+        "uiTree": "captured",
+        "disabledComponents": "omitted",
+        "foreignReference": "unavailable",
+        "cleanup": "No settings, app data or streams changed; Settings remains foreground. No content artifacts saved."
+      },
+      {
+        "status": "PASS",
+        "build_sha256": "370254feb4bc933c650c00625e0ca2a1ec32567ea35190098710a16c50e9c4c5",
+        "runtime": "v23.11.0",
+        "server": {
+          "name": "mobile-debug-mcp",
+          "version": "0.34.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": "92d9e705-4655-4797-97c2-dbbbe0a89ab0",
+        "correlation_id": "f762ca72-67b8-4314-8af0-7a3f5c59c3fe",
+        "phases": {
+          "capture_started_at_ms": 1793385324309,
+          "capture_completed_at_ms": 1793385331115
+        },
+        "artifact_bytes": 1102735,
+        "content": {
+          "packets": 252,
+          "ftrace_bundles": 234,
+          "events": 24912,
+          "compact_sched_bundles": 234,
+          "validation": "local protobuf structure, trace config duration and timestamped ftrace/compact scheduler content; not full Perfetto analysis"
+        },
+        "durationContent": {
+          "packets": 47,
+          "ftrace_bundles": 31,
+          "events": 2790,
+          "compact_sched_bundles": 31,
+          "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."
+      }
+    ]
+  },
+  "contract": {
+    "status": "pass",
+    "tool_definitions": 52,
+    "comparison": "Complete pre-refactoring definition fixture, including schemas/defaults/descriptions/order"
+  },
+  "quality": {
+    "status": "pass",
+    "legacy_exceptions_remaining_elsewhere": 162,
+    "regression": "Refactored interaction modules must meet defaults even if a legacy allowance is added"
+  },
+  "package": {
+    "command": "npm pack --dry-run --json",
+    "status": "pass"
+  },
+  "unrun": [
+    "Hosted CI and local Node 18 runtime",
+    "Physical-device interaction journey",
+    "Interactive iOS navigation/state journey (iOS observation and correlation suite passed)",
+    "Native adjustable-control convergence fixture (unit and injected-strategy coverage passed)"
+  ]
+}

package/docs/specs/026-code-structure-and-quality-gates/verification.json

@@ -0,0 +1,136 @@
+{
+  "date": "2026-10-30",
+  "status": "verified checkpoint; full refactoring scope remains in progress",
+  "node": "v23.11.0",
+  "maintainer": {
+    "command": "npm run verify",
+    "status": "pass",
+    "unit_files": 78
+  },
+  "device_suite": {
+    "command": "MCP_DEBUGGER_DEVICE=emulator-5554 npm run test:device",
+    "status": "pass",
+    "records": [
+      {
+        "status": "PASS",
+        "build_sha256": "b43dc571fa4ad37bfa5a77af61425286d47cd4f0b738c3cb7e013d2c4cf01d9a",
+        "device": "emulator-5554",
+        "api": "36",
+        "runtime": "v23.11.0",
+        "transport": "MCP stdio",
+        "extended": false
+      },
+      {
+        "status": "PASS",
+        "server": {
+          "name": "mobile-debug-mcp",
+          "version": "0.34.0"
+        },
+        "platform": "android",
+        "device": "emulator-5554",
+        "osVersion": "16",
+        "startingApp": "com.android.settings",
+        "actionId": "77b18501-7594-4ff7-ab67-53c8a91b75e4",
+        "phases": {
+          "dispatchStarted": 1793379545096,
+          "dispatchCompleted": 1793379545495,
+          "screenshotStarted": 1793379545858,
+          "screenshotCompleted": 1793379546511
+        },
+        "screenshot": "captured",
+        "logs": "captured",
+        "uiTree": "captured",
+        "disabledComponents": "omitted",
+        "foreignReference": "unavailable",
+        "cleanup": "No settings, app data or streams changed; Settings remains foreground. No content artifacts saved."
+      },
+      {
+        "status": "PASS",
+        "server": {
+          "name": "mobile-debug-mcp",
+          "version": "0.34.0"
+        },
+        "platform": "ios",
+        "device": "F9243BAF-62A8-4990-8A99-17F527F56FDA",
+        "osVersion": "iOS 26.4",
+        "startingApp": "com.apple.Preferences",
+        "actionId": "75efedc5-eb5c-45e3-8b4e-5c1e5dcb6d6d",
+        "phases": {
+          "dispatchStarted": 1793379554471,
+          "dispatchCompleted": 1793379554924,
+          "screenshotStarted": 1793379555463,
+          "screenshotCompleted": 1793379555970
+        },
+        "screenshot": "captured",
+        "logs": "captured",
+        "uiTree": "captured",
+        "disabledComponents": "omitted",
+        "foreignReference": "unavailable",
+        "cleanup": "No settings, app data or streams changed; Settings remains foreground. No content artifacts saved."
+      },
+      {
+        "status": "PASS",
+        "build_sha256": "370254feb4bc933c650c00625e0ca2a1ec32567ea35190098710a16c50e9c4c5",
+        "runtime": "v23.11.0",
+        "server": {
+          "name": "mobile-debug-mcp",
+          "version": "0.34.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": "69cec918-2d8c-4241-8192-1e15d937300d",
+        "correlation_id": "e096888b-fd9d-4385-bcbc-acefc56f717a",
+        "phases": {
+          "capture_started_at_ms": 1793379585269,
+          "capture_completed_at_ms": 1793379591151
+        },
+        "artifact_bytes": 1103332,
+        "content": {
+          "packets": 240,
+          "ftrace_bundles": 223,
+          "events": 25402,
+          "compact_sched_bundles": 223,
+          "validation": "local protobuf structure, trace config duration and timestamped ftrace/compact scheduler content; not full Perfetto analysis"
+        },
+        "durationContent": {
+          "packets": 55,
+          "ftrace_bundles": 39,
+          "events": 2884,
+          "compact_sched_bundles": 39,
+          "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."
+      }
+    ]
+  },
+  "java_compile": {
+    "status": "pass",
+    "command": "javac --release 17 --add-modules jdk.jdi",
+    "host_java_major": 23
+  },
+  "package": {
+    "status": "pass",
+    "command": "npm pack --dry-run --json",
+    "required_files": [
+      "src/debugger/java/DebuggerWorker.java",
+      "dist/debugger/worker.js",
+      "dist/debugger/protocol.js",
+      "dist/runtime/action-results.js",
+      "dist/server/definitions/input.js",
+      "dist/server/debugger-schema.js"
+    ]
+  },
+  "unrun": [
+    "Node 18 locally; existing CI job retains Node 18",
+    "Hosted CI",
+    "Android physical-device debugger journey",
+    "Real-device adjustable-control journey (no adjustable-control fixture in the current device suite)",
+    "Extended 60-second debugger expiry run",
+    "JDK 17 runtime execution (Java 17 release compilation passed)"
+  ]
+}

package/docs/specs/027-debugger-failure-diagnostics/intent.md

@@ -0,0 +1,43 @@
+# Intent: debugger failure diagnostics
+
+[Documentation](../../README.md) · [Development process](../process.md)
+
+Originator: repository maintainer through GitHub issue #81.
+Date: 2026-11-02. Status: approved.
+Source: [issue #81](https://github.com/clivejefferies/mobile-debug-tools/issues/81),
+current roadmap priority 1 of 13; maintainer request to pick up the next ticket.
+
+## Problem and outcome
+
+Intermittent `DEBUGGER_WORKER_FAILED` responses do not give MCP clients enough
+evidence to distinguish worker startup, compilation, IPC/protocol, JDI attach,
+and transport failures. Issue #80 did not reproduce on retest; this work improves
+diagnosis without claiming to fix its unknown cause.
+
+Give Android debugger clients bounded, sanitized failure classification and
+actionable recovery guidance. Identify the stage and safe reason only where
+evidence supports them, retaining explicit uncertainty otherwise.
+
+## Scope and success criteria
+
+Preserve existing error codes, successful operations, session ownership and
+cleanup. Specify compatible additive diagnostics before implementation. Never
+expose raw stderr, environment secrets, app locals or unbounded exception text
+in MCP responses or logs.
+
+Verify startup/process failure, malformed IPC, attach failure and
+timeout/cancellation with deterministic regression checks and cleanup assertions.
+Retain a verified Android attach/inspect/detach journey and document diagnostic
+fields and limitations. Report unavailable device coverage explicitly.
+
+## Boundaries and open decisions
+
+No compact-response redesign, arbitrary evaluation, new debugging capability,
+or implementation of iOS debugging. Keep the design reusable for later iOS work
+without promising platform parity. The specification will settle diagnostic
+fields, classification evidence, bounded output and recovery guidance.
+
+## Approval
+
+The maintainer approved the captured intent and scope with “looks good” in this
+chat on 2026-11-02. Specification acceptance remains a separate gate.

package/docs/specs/027-debugger-failure-diagnostics/plan.md

@@ -0,0 +1,86 @@
+# Plan: debugger failure diagnostics
+
+[Intent](intent.md) · [Accepted specification](spec.md)
+
+Intent approved with “looks good”; specification accepted with “ok” in this chat
+on 2026-11-02. No publication, commit or push requested.
+
+## Implementation
+
+- [x] Add a bounded static diagnostic catalog and typed error propagation.
+- [x] Classify preparation, subprocess, IPC and Java attach/transport failures.
+- [x] Preserve diagnostics through sessions, cleanup, capabilities and MCP wrapping.
+- [x] Add isolated worker/protocol/privacy and lifecycle regression coverage.
+- [x] Align tool docs, changelog and packaged usage skill.
+
+## Verification
+
+Node >=22, JDK >=17; Android fixture additionally needs SDK/build-tools 36.
+
+| Criteria | Check |
+| --- | --- |
+| 1, 2, 4 | Focused self-running diagnostic, protocol and MCP tests with hostile input and fake workers |
+| 3 | Session tests: timeout/cancellation, event race, cleanup retry, isolation, shutdown |
+| 1–4 | `npm run verify` (lint/quality/architecture, build, all units, plugin consistency) |
+| 5 | `npm run test:device`; then `MCP_DEBUGGER_DEVICE=<serial> npx tsx test/device/automated/debugger/runtime.android.test.ts` |
+| 6 | Docs diff, local links and `npm run check:agent-plugin` |
+
+Device journey: explicitly selected authorized Android target; install the isolated
+fixture, attach, set/trigger breakpoint, inspect known stack/locals, step/resume,
+assert Result 43 in a fresh UI tree, detach and compare forwards. Existing runner
+records server fingerprint/device/API and removes its package/temp data in finally.
+Do not use a user app as a failure fixture. Physical Android and iOS evidence remain
+separate. Fault injection uses isolated fake workers, never a production app.
+
+Initial ADB discovery was blocked by sandbox binding restrictions. Retry discovery
+with execution access; if no authorized target is available, record the concrete
+blocker and leave live verification incomplete. Hosted CI is separate from local
+checks. No dependency or release version changes are planned.
+
+## Results
+
+Implemented and locally verified on 2026-11-02. All checks below passed unless
+explicitly marked unrun.
+
+| Check | Outcome and evidence |
+| --- | --- |
+| `npm run verify` with Node 22.23.4 | **Pass**: ESLint, structural gates (no exceptions), architecture, TypeScript build, all 88 unit files, plugin consistency. Log: `/tmp/mobile-debug-81-verified.log`. |
+| Three new debugger unit files | **Pass**: isolated real fake-worker spawn/exit/write errors, malformed/oversized IPC, attach refusal, timeout/cancellation, static catalog bounds, hostile error/diagnostic fields, fake-JDK prerequisite/compile failures, MCP wrapping, terminal retention, event/rejection race, device isolation, cleanup retry and shutdown. |
+| `MCP_DEBUGGER_DEVICE=emulator-5554 npm run test:device` with Node 22.23.4 | **Pass**, 10 files. Includes Android debugger/interaction, Android+iOS screenshots/logs/UI trees/correlated evidence, and Android system traces. Log: `/tmp/mobile-debug-81-final-device.log`. |
+| Final focused debugger fixture, Node 22.23.4 | **Pass**, MCP stdio, emulator-5554, Android 16/API 36. Exact final build SHA-256: `9528d796df4e01ca9d7668c32715a7ceff945a06a2f097fe4d57f16705f52eb3`. Log: `/tmp/mobile-debug-81-fixture-final.log`. |
+| Actual Java JDI refusal check | **Pass**, Android Studio JBR OpenJDK 25.0.3; compiled worker contacted an explicitly closed temporary loopback port. Existing `DEBUGGER_WORKER_FAILED` retained, diagnostic `attach/connection_refused`; worker closed in finally. No app or device targeted. |
+| Documentation | **Pass**: diff whitespace, relative links/paths, schema/recovery limits and packaged usage skill consistency. |
+
+The final focused fixture started by installing/launching only the isolated debug
+app. It verified a source breakpoint and stop, stack method, known local `42`,
+bounded string/object summaries, pause guards, into/over/out stepping, stale
+references, resume established by fresh UI-tree `Result 43`, missing variable
+metadata, pending/removed breakpoints, event cancellation, repeated detach,
+process loss and active paused-server shutdown. Exact owned forwards were removed;
+unrelated forwards were preserved. Fresh UI evidence established execution after
+shutdown, and the fixture package/temp data were removed in finally. The broader
+suite leaves system Settings foreground and removes its own trace artifacts.
+
+The broad device run preceded the last host-only pipe-failure consolidation and
+terminal-command/cancellation diagnostic refinements; the full maintainer command
+and focused Android fixture were rerun against the final code. Broader unaffected
+observation/trace checks were not repeated. Preliminary Node 23 checks also passed;
+final maintainer and focused debugger results above use Node 22.
+
+## Focused review and limitations
+
+Reviewed worker/Java protocol, error serialization, budget/cancellation paths,
+capability probe compatibility, per-device ownership and cleanup races. Retained
+legacy error codes (including generic prerequisite startup failures), fixed
+phase attribution across attach deadlines, routed synchronous/asynchronous pipe
+failures through one pending-request settlement path, and retained terminal
+failure diagnostics on later rejected commands. No raw worker/compiler output
+enters the new diagnostic fields. Public tool-definition parity passed.
+
+Physical-device debugger coverage, real 60-second pause expiry in this run,
+JDK 17 compilation/runtime and hosted CI are **unrun**. iOS observation smoke
+coverage does not establish iOS debugger support. The earlier sandbox ADB/tsx
+socket blockers were resolved with execution access. This implementation does
+not establish the unknown cause of issue #80. Changes remain local, uncommitted,
+unpushed and unpublished; the GitHub ticket has not been closed.
+

package/docs/specs/027-debugger-failure-diagnostics/spec.md

@@ -0,0 +1,133 @@
+# Specification: debugger failure diagnostics
+
+[Intent](intent.md) · [Development process](../process.md)
+
+Date: 2026-11-02. Status: accepted by the maintainer with “ok” in this chat on 2026-11-02.
+Intent approved by the maintainer with “looks good” in this chat on 2026-11-02.
+Source: [issue #81](https://github.com/clivejefferies/mobile-debug-tools/issues/81).
+
+## Outcome and scope
+
+Existing Android debugger tools will explain failed operations using bounded,
+sanitized evidence. Diagnostics distinguish the operation stage from its known
+failure reason; they do not claim to determine the cause of issue #80.
+
+All eleven debugger tool names, input schemas, defaults, deadlines, error codes,
+`error.message`, `error.retryable`, MCP `isError` behavior, and successful debug
+payloads remain compatible. No opt-in argument is needed. iOS remains unsupported;
+these diagnostic concepts may be reused by a future backend. Compact responses,
+new debugging capabilities and automatic retries are excluded.
+
+## Additive response contract
+
+A debugger failure carries `error.diagnostic` with exactly these fields:
+
+| Field | Values and meaning |
+| --- | --- |
+| `stage` | `prerequisite`, `compilation`, `worker_start`, `ipc`, `target_resolution`, `forwarding`, `attach`, `command`, `transport`, `cleanup`, `unknown` |
+| `reason` | `unavailable`, `unsupported`, `spawn_failed`, `process_exited`, `invalid_message`, `message_limit`, `write_failed`, `connection_refused`, `transport_lost`, `timeout`, `cancelled`, `operation_failed`, `unknown` |
+| `recovery` | Fixed guidance from the stage/reason catalog, at most 240 ASCII characters |
+
+No additional free-text details, paths, command arguments, identifiers, exception
+classes, stderr excerpts or numeric process metadata enter this object. Its
+serialized UTF-8 size must not exceed 512 bytes. Existing targeting fields remain
+the source of device/process identity. Unknown evidence produces `unknown`, not
+a guessed cause. Ordinary argument, stale-reference and pause/state validation
+errors need not gain diagnostics.
+
+`get_debugger_capabilities` retains its successful probe envelope, `supported`
+and `reasons`. When probes fail, an optional top-level `diagnostics` array contains
+at most two diagnostic objects in JDK-then-target probe order. It is absent when
+both probes succeed. It does not turn an unsupported probe into an MCP error.
+
+Failed attach and command responses, thrown errors handled by the MCP wrapper,
+and terminal `get_debugger_state` failures preserve the applicable diagnostic.
+Asynchronous worker failure/disconnection retains one diagnostic in the owning
+session until normal terminal-summary pruning. Diagnostic state is separate from
+inspection data, which cleanup continues to clear. Event polling retains existing
+cursor, overflow and event semantics; no new event type is introduced.
+
+## Classification and uncertainty
+
+Classification uses host operation context, structured child-process error codes,
+validated worker fields and known Java exception types. Raw message matching is
+not a diagnostic source. The Java bridge supplies only allowlisted diagnostic
+values; the TypeScript boundary validates and reconstructs them, dropping unknown
+fields. Malformed diagnostic values are a protocol failure, without echoing input.
+
+JDK discovery/version checks use `prerequisite`; source/cache preparation and
+`javac` use `compilation`; spawn errors use `worker_start/spawn_failed`.
+Unexpected child exit uses `worker_start/process_exited` before the first valid
+worker reply, otherwise `ipc/process_exited`; this is a phase convention, not
+proof that startup succeeded or failed. Malformed/oversized IPC and stdin write
+errors use `ipc` with the corresponding fixed reason. JDI attach refusal uses
+`attach/connection_refused` only with an explicit connection-refused exception;
+other attach exceptions use `attach/operation_failed`. Structured transport loss
+uses `transport/transport_lost`; unclassified exceptions use the known stage and
+`unknown`. Target discovery and ADB forwarding retain distinct stages.
+
+Timeout/cancellation keeps the stage active when observed and uses `timeout` or
+`cancelled`; it does not imply that the command was never dispatched. An operation
+that never started may use `unknown`. Preserve the first causal failure across
+the worker-event/rejected-request race. Cleanup must not replace it with a
+secondary EOF or exit failure. If the existing error code reports cleanup failure,
+its diagnostic is `cleanup/operation_failed`; original session reason and
+`cleanup.remaining_resources` remain available under their existing contracts.
+
+## Recovery, ownership and privacy
+
+Guidance is a static catalog: check JDK 17+/javac for prerequisites; check the
+compiler/toolchain for compilation; check worker launch availability for startup;
+inspect session state and detach before a fresh attach for IPC/transport failure;
+check the explicit running debuggable target and debugger contention for attach.
+Timeout/cancellation guidance states that execution may be uncertain and requires
+state/cleanup inspection before another state-changing command. Cleanup guidance
+requests retrying `detach_debugger` and checking remaining resources. Unknown
+failures direct clients to session state and cleanup without claiming a cause.
+
+Existing per-device ownership, four-session limit, serialization, pause guards,
+reference invalidation, independent cleanup budget, expiry and shutdown rules
+remain unchanged. Never kill the target app/ADB server, remove unrelated forwards,
+retry attach/step/resume automatically, or claim resumed execution after loss.
+Retain bounded subprocess/IPC handling and drain stderr without retaining it.
+No new logging, persistence, telemetry, UI capture or collection of app values.
+
+## Acceptance and verification
+
+1. Deterministic checks distinguish prerequisite/compile/startup, malformed and
+   oversized IPC, write/exit, attach and transport failures without changing codes.
+2. Unknown exceptions and hostile protocol/error text cannot expose secrets,
+   locals, paths or raw output in diagnostics, responses or new logging.
+3. Timeout/cancellation preserve deadlines and session policy; races, concurrent
+   sessions, cleanup failure/retry and shutdown preserve owned resources and the
+   appropriate diagnostic. Terminal summaries retain sanitized failure evidence.
+4. MCP serialization and capability probes satisfy the additive contract and
+   bounds; successful payloads and validation/reference errors remain compatible.
+5. Run `npm run verify`, `npm run test:device`, and the explicitly selected Android
+   fixture journey against the updated server: attach, breakpoint, stop, stack,
+   known locals, step/resume, detach and forward-ownership checks. Record server
+   fingerprint and target; distinguish emulator from physical-device evidence.
+6. Update tool documentation, changelog and usage skill with fields, recovery,
+   uncertainty and platform limits; keep packaged skill copies consistent.
+
+Current investigation inspected worker, Java bridge, protocol, sessions, MCP
+handler, tool docs and existing unit/device fixtures at checkout
+`803409a7a784669b68844e8af5b21cd822ffd599`. ADB 37.0.1 is installed, but the
+sandbox prevented its daemon from binding port 5037 (`Operation not permitted`).
+No live device baseline or new behavior is verified. Implementation verification
+must retry device discovery with appropriate execution access; unavailable device
+coverage must be reported as blocked, with the fixture command documented.
+
+## Affected areas, risks and approval
+
+Changes are expected in `src/debugger/{worker,protocol,sessions,android}.ts`,
+`src/debugger/java/DebuggerWorker.java`, the debugger MCP handler, focused tests,
+tool documentation and usage skill. Reuse existing typed error/budget machinery;
+extract cohesive diagnostic helpers where structural limits require it. Main
+risks are losing diagnostics during wrapping, race-dependent attribution and
+accidental private-data propagation. Boundary and lifecycle checks address them.
+
+Accepted decisions: always-additive failure diagnostics,
+the fixed schema/catalog above, capability-probe diagnostics, and sanitized
+terminal-session retention. The maintainer accepted this complete specification with “ok” on 2026-11-02;
+implementation is authorized within this scope.

package/docs/specs/028-compact-debugger-responses/intent.md

@@ -0,0 +1,41 @@
+# Intent: compact debugger responses
+
+[Documentation](../../README.md) · [Development process](../process.md)
+
+Originator: repository maintainer through GitHub issue #82.
+Date: 2026-11-02. Status: approved.
+Source: [issue #82](https://github.com/clivejefferies/mobile-debug-tools/issues/82),
+priority 2 of 13, and the maintainer's request to pick up the next ticket.
+GitHub Projects status could not be verified: the available token lacks
+`read:project`. Selection follows the issue's published priority order.
+
+## Problem and outcome
+
+Debugger responses repeat target, capability and session metadata during long
+investigations. Provide an opt-in compact mode for existing debugger tools so
+MCP clients receive less repeated data while retaining everything required to
+understand the result and safely continue debugging.
+
+## Scope and success criteria
+
+Preserve existing default responses and client compatibility. Compact responses
+must retain operation results, continuation identifiers, execution state, errors,
+uncertainty, truncation and unresolved cleanup. Keep actionable diagnostics from
+issue #81 available in either mode; retain full responses on request.
+
+Compare serialized output for the same attach → breakpoint → stop → stack →
+locals → step → resume → detach journey, reporting measured savings without
+inventing a reduction target. Verify success, failure, stale references and
+incomplete cleanup, and document when clients need full responses.
+
+## Boundaries and open decisions
+
+Scope is response presentation for current debugger tools. Other tools, new
+debugging capabilities, session lifecycle changes and iOS debugger implementation
+are excluded. The specification will settle mode naming in line with existing
+`compact`/`debug` conventions, tool coverage and exact field retention.
+
+## Approval
+
+The maintainer approved this intent with “yes” in this chat on 2026-11-02.
+Specification acceptance remains a separate gate.