mobile-debug-mcp 0.33.0 → 0.35.0

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

@@ -0,0 +1,41 @@
+# Intent: Android runtime debugger
+
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md) · [Specification](spec.md) · [Plan and verification](plan.md)
+
+Originator: clivejefferies, through GitHub roadmap issue #68 and maintainer design review.
+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 during design review. See the linked specification for its separate approval record.

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

@@ -0,0 +1,106 @@
+# Plan: Android runtime debugger
+
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md) · [Intent](intent.md) · [Specification](spec.md)
+
+2026-10-30. [Intent](intent.md) and [spec](spec.md) explicitly approved by the
+user's successive “yes” responses during design review. 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.

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

@@ -0,0 +1,183 @@
+# Specification: Android runtime debugger
+
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md) · [Intent](intent.md) · [Plan and verification](plan.md)
+
+Date: 2026-10-30. Status: approved.
+Intent: [approved intent](intent.md), approved by the user's “yes” during design review.
+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 during design review, 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/026-code-structure-and-quality-gates/health-plan.md

@@ -0,0 +1,88 @@
+# Follow-on codebase health cleanup
+
+[Completed structural refactor](plan.md) · [Quality and ownership](../../code-structure.md)
+
+Status: complete. Source: the maintainer requested fixing the remaining code
+and dependency debt identified in the health review, excluding additional
+verification-environment coverage (point 4). This is behaviour-preserving
+maintenance under the shared process. On 2026-10-30 the maintainer explicitly
+approved raising the minimum runtime to Node 22 to permit patched dependencies.
+
+## Scope
+
+- [x] Triage the 20 dependency audit findings and update compatible dependencies.
+- [x] Upgrade Sharp and Zod, preserve complete public tool-definition parity,
+  and clear the remaining tsx/esbuild advisory.
+- [x] Update the declared runtime and CI configuration to Node 22.
+- [x] Replace the oversized Android/iOS observation classes with cohesive services.
+- [x] Decompose snapshot collection, normalization and semantic summary generation.
+- [x] Decompose iOS build discovery, command preparation, execution and diagnostics.
+- [x] Reduce environment diagnostics complexity and remaining unsafe boundaries.
+- [x] Remove resolved legacy exceptions without moving or enlarging allowances.
+- [x] Run focused regressions, complete verification on Node 22, and relevant
+  existing device checks; record results and cleanup.
+
+The initial baseline contained 136 exceptions; it is now empty. Existing exported entrypoints,
+response shapes, schema strictness, retry order, deadlines, resource ownership and
+error behaviour must remain compatible. In particular, retain platform-specific
+screenshot alpha/fallback policy and concurrent snapshot acquisition behaviour.
+
+Additional hosted CI, physical-device journeys and new interactive iOS coverage
+remain outside this request. Existing runnable regression checks still apply to
+changed code. No commit, push, package publication or plugin pin change is implied.
+
+## Verification
+
+Local runtime: Node v22.23.4. Verification took place on 2026-10-30.
+
+| Check | Result |
+| --- | --- |
+| `npm run verify` under Node 22 | **Pass**: lint, quality, four architecture rules, build, 85 unit files and plugin consistency |
+| Complete public tool-definition fixture | **Pass**: all 52 definitions retain their existing shapes and defaults |
+| Screenshot encoding regressions | **Pass**: Android/iOS transparency policy, fallback formats and conversion failure |
+| Snapshot log regressions | **Pass**: numeric/string timestamps, stream precedence and severity normalization |
+| `npm audit --json` | **Pass**: 20 findings reduced to zero, including development dependencies |
+| `npm pack --dry-run --json` | **Pass**: extracted runtime services and Java worker included; nothing published |
+| Documentation and whitespace checks | **Pass**: relative links, anchors, skill metadata and changed-file whitespace |
+| `npm run test:device` under Node 22 | **Pass**: all 10 files on the final uninterrupted run |
+
+The first device run passed the debugger, interaction, screenshots and correlated
+observations, then exposed an undeclared `minimist` import in the existing log
+helper. The dependency is now declared explicitly in development dependencies;
+the dependency audit remains clear. The final device run is recorded below.
+
+Review confirmed that retry order, watchdog cleanup, platform screenshot policy,
+evidence freshness ordering and snapshot parallelism remain in their existing
+owners or explicit extracted services. One type-only compatibility export was
+corrected after the Node 22 ESM unit run exposed it. No replacement quality
+allowances or rule suppressions were added.
+
+## Device results and limits
+
+The final suite used Android emulator `emulator-5554` (API 36 / Android 16)
+and booted iOS simulator `F9243BAF-62A8-4990-8A99-17F527F56FDA` (iOS 26.4).
+Both ran against the local 0.34.0 build under Node v22.23.4.
+
+- **Pass, Android:** isolated fixture debugger attach, breakpoints, stack/locals,
+  pause guards, stepping, stale references, resume and owned detach; clickable
+  waits, handle taps, visible/state assertions and labelled SeekBar convergence.
+- **Pass, Android and iOS:** screenshots, logs, UI trees and correlated observation
+  evidence, including omitted components and foreign-session rejection.
+- **Pass, Android Perfetto:** Settings visibility assertion, explicit correlation,
+  trace content structure, stop, cancellation, duration expiry and active shutdown.
+- **Cleanup:** owned fixture apps/build directories, debugger forwards, device
+  captures and host trace artifacts removed. Settings remains foreground without
+  settings changes. No observation content was retained by the correlation tests.
+
+The full compiled TypeScript plus Java-source fingerprint reported by the debugger
+journey is `f035f362ed32b10ef247f918df8523974e06fb153389de3e6b50ca51cdacf8ae`.
+The trace-specific subset fingerprint is
+`e90ed0831de4059f1e2b213ed0c050298cf2e55c0cc0aef9ff4ea2a38b6062a0`.
+Raw local command output is in `/tmp/health-verify.log`,
+`/tmp/health-device-final.log` and `/tmp/health-final-audit.json`; these temporary
+files are not repository artifacts.
+
+Hosted CI, physical-device journeys, new interactive iOS coverage and the extended
+Android debugger expiry journey remain **unrun**, as excluded in point 4. The
+existing simulator observation checks above do not establish those outcomes.
+No commit, push or publication was performed.

package/docs/specs/026-code-structure-and-quality-gates/intent.md

@@ -0,0 +1,47 @@
+# Intent: code structure and quality gates
+
+[Documentation](../../README.md) · [Development process](../process.md)
+
+Originator: repository maintainer. Date: 2026-10-30.
+Status: approved on 2026-10-30.
+Source: maintainer request to address oversized classes, weak type boundaries,
+tight coupling, duplicated contracts, and dense lifecycle code, and add tooling
+that prevents recurrence.
+
+## Problem and outcome
+
+The current lint configuration checks unused imports and variables, but has no
+size, complexity, or type-safety gates. `ToolsInteract` combines target resolution,
+control adjustment, waits, assertions, and shared state in about 3,700 lines.
+Separately maintained schemas, handler types, and validation can drift. Static
+method replacement makes tests depend on implementation details.
+
+Make responsibilities easier to locate, change, and verify while preserving MCP
+contracts, defaults, platform behaviour, cancellation, timing, and cleanup.
+
+## Scope and success criteria
+
+- Extract cohesive interaction services behind compatible public entrypoints.
+- Replace unsafe types at extracted boundaries and introduce narrow dependency
+  injection where it improves isolation.
+- Reduce schema/type/validation duplication without changing accepted inputs.
+- Make debugger lifecycle transitions and cleanup readable and explicitly typed.
+- Enforce source file, class, function, complexity, nesting, and type-safety limits
+  in local verification and CI. Define reviewed, narrow legacy exceptions that
+  cannot grow silently; do not disable existing checks or hide new violations.
+- Cover extracted behaviour and guardrail failures with deterministic tests;
+  supplement with relevant device checks and record unavailable coverage.
+
+## Boundaries and specification decisions
+
+No new MCP capabilities, framework migration, public API redesign, or incidental
+product fixes. Preserve current unrelated documentation edits and removals.
+Specify thresholds, legacy-debt handling, module dependencies, extraction order,
+contract parity checks, and verification before implementation. Do not treat code
+size alone as proof of good design or split methods merely to satisfy metrics.
+
+## Approval
+
+The maintainer approved this captured problem and scope with “looks good” on
+2026-10-30. Implementation requires a separately accepted
+[specification](spec.md) under the development process.