mobile-debug-mcp 0.34.0 → 0.35.0

package/docs/specs/020-conditional-actions/plan.md

@@ -1,8 +1,10 @@
 # Plan: conditional actions
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md) · [Intent](intent.md) · [Specification](spec.md)
+
 Date: 2026-10-29. Status: complete — implementation and required verification passed.
 Intent: [intent.md](intent.md). Specification: [spec.md](spec.md).
-Both approved by the originator's separate “yes” replies in this conversation;
+Both approved by the originator's separate “yes” replies during design review;
 the latest approval authorises implementation of spec 020.
 
 ## Implementation sequence
@@ -98,18 +100,16 @@ minimum is >=18; CI's Node 18 run has not been executed locally).
   All elements contribute to revision checks beyond the bounded delta history.
 - `npm run sync:agent-plugin`: PASS; no generated manifest differences.
 - Final `npm run verify`: PASS (lint, build, 59 unit-test files, plugin consistency).
-  Log: `/tmp/mobile-debug-conditional-verify-final.log`.
 - Initial `npm run test:device`: FAIL at iOS UI-tree smoke (`Invalid UI tree resolution`) while the original simulator was booting.
   Android screenshot/log/tree wrappers passed. iOS screenshot wrapper passed;
   the iOS log wrapper also reported pass but its underlying log retrieval printed
   `getpwuid_r` / unavailable log-store errors, so this is not evidence of usable
   iOS logs. These wrappers use automatic device selection; focused tests below
-  pin their simulator explicitly. Full log: `/tmp/mobile-debug-conditional-device-suite.log`.
+  pin their simulator explicitly.
 
 - Final `npm run test:device`: PASS after the replacement iPhone 17 Pro finished
   booting. All six Android/iOS screenshot, log, and tree smoke wrappers passed,
-  without the earlier iOS log-store diagnostics. Log:
-  `/tmp/mobile-debug-conditional-device-suite-final.log`.
+  without the earlier iOS log-store diagnostics.
 - Final documentation relative-link checks and `git diff --check`: PASS.
 - Final lint after the device helper's selector/start-state correction: PASS.
 
@@ -138,7 +138,7 @@ Starting state: system Settings root, with Network & internet visible.
 | Journey stop, compact | Successful wait for Internet, conditional back tap with root expectation, later tap | Earlier wait passed, guarded step failed with fresh tree, later step `not_run`; destination remained | PASS |
 | Journey stop, debug | Same sequence in debug mode | Same stop and preserved evidence | PASS |
 
-Full structured evidence: `/tmp/mobile-debug-conditional-android.json`.
+The temporary raw output was not retained in the repository; results are summarised here.
 The five scenarios were rerun successfully against the final built server after
 the compact-error and metadata-validity fixes and the helper selector correction.
 The helper is reproducible and requires a deliberately prepared safe system
@@ -175,7 +175,7 @@ Starting state: Settings root with General visible, About absent.
 | Journey stop, compact | Successful wait for About, stale conditional tap on `resource_id: BackButton`, later back tap | Wait passed; condition failed; later step `not_run`; General remained visible | PASS |
 | Journey stop, debug | Same sequence in debug mode | Same stop and fresh condition evidence | PASS |
 
-Structured evidence: `/tmp/mobile-debug-conditional-ios.json`.
+The temporary raw output was not retained in the repository; results are summarised here.
 An initial helper attempt selected the application container sharing the Settings
 label and correctly stopped with `ELEMENT_NOT_INTERACTABLE` / `not_checked`;
 this was not counted as a conditional-journey pass. The helper now prefers the
@@ -210,5 +210,4 @@ Limits: live simulator checks cover conditional taps and journey stops; conditio
 swipes and Android typing/back use production-adapter tests with fake native
 tools. Physical devices were not used for mutation checks. UI normalization, the observation-to-OS-input race, and concurrent external
 input remain explicit spec limits. No mutation testing was performed. No tests
-or validation rules were weakened. Existing uncommitted process/skill relocation
-work was preserved. No package was published and nothing was committed/pushed.
+or validation rules were weakened. No published-package verification was performed.

package/docs/specs/020-conditional-actions/spec.md

@@ -1,8 +1,10 @@
 # Spec 020: conditional actions
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md) · [Intent](intent.md) · [Plan and verification](plan.md)
+
 Date: 2026-10-29.
 Status: approved — implementation authorised.
-Intent: [intent.md](intent.md), approved in the current conversation by the
+Intent: [intent.md](intent.md), approved during design review by the
 originator's “yes” in response to the captured intent.
 
 ## Outcome
@@ -296,6 +298,6 @@ separately. Record exact test routes and cleanup in the implementation plan.
 
 ## Approval
 
-Approved by the originator on 2026-10-29 in the current conversation: “yes”,
+Approved by the originator on 2026-10-29 during design review: “yes”,
 in direct response to the linked complete spec and the listed first-version
 scope. Implementation is authorised within that scope.

package/docs/specs/021-app-readiness-signals/intent.md

@@ -1,6 +1,8 @@
 # Intent: app readiness signals
 
-Originator: repository maintainer (current conversation).
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md) · [Specification](spec.md) · [Plan and verification](plan.md)
+
+Originator: repository maintainer (design review).
 Date: 2026-10-29. Status: approved.
 Source: [GitHub issue #65: App readiness signals](https://github.com/clivejefferies/mobile-debug-tools/issues/65), roadmap priority 2 of 9.
 
@@ -37,4 +39,4 @@ unsupported signals, API placement, and how long observations remain current.
 ## Approval
 
 Approved on 2026-10-29 by the originator’s “yes” in direct response to the
-complete intent summary and linked artifact in this conversation.
+complete intent summary and linked artifact during design review.

package/docs/specs/021-app-readiness-signals/plan.md

@@ -1,8 +1,10 @@
 # Plan: app readiness signals
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md) · [Intent](intent.md) · [Specification](spec.md)
+
 Date: 2026-10-29. Status: complete — implementation and required verification passed.
-[Intent](intent.md) and [spec](spec.md) separately approved in this conversation;
-“yep” authorises implementation of spec 021. Preserve existing uncommitted work.
+[Intent](intent.md) and [spec](spec.md) separately approved during design review;
+“yep” authorises implementation of spec 021.
 
 ## Implementation
 
@@ -47,8 +49,8 @@ Node v23.11.0. This is local evidence, not a published package or Node 18 CI run
 | --- | --- |
 | Classifier, schemas, opt-in waits | PASS: state precedence, monotonic stability, invalid/error continuity, no extra predicate reads, explicit unsupported states, timeout uncertainty |
 | Production Android/iOS observation adapters with fake binaries | PASS: two-sample stability, native loaders, timeout child closure, and killing a hung iOS metadata probe; simulated error evidence |
-| Maintainer checks | PASS: final `npm run verify` (lint, build, 62 unit-test files, plugin consistency); `/tmp/mobile-readiness-verify-complete.log` |
-| Existing `npm run test:device` | PASS: all six Android/iOS screenshot, log, and tree smoke wrappers; `/tmp/mobile-readiness-device-suite.log` |
+| Maintainer checks | PASS: final `npm run verify` (lint, build, 62 unit-test files, plugin consistency) |
+| Existing `npm run test:device` | PASS: all six Android/iOS screenshot, log, and tree smoke wrappers |
 | Native fixture journeys through built MCP stdio | PASS: six on each simulator; evidence linked below |
 
 Focused device commands (each builds, installs, and uninstalls its own offline
@@ -78,8 +80,7 @@ starts a 12-second loader while Ready stays visible; completion displays Done.
 All twelve device scenarios passed. Both fixture apps were uninstalled, build
 folders removed, Android’s original foreground app restored, and iOS returned
 to Home. No settings, permissions, accounts, or production app data were changed.
-Structured evidence: `/tmp/mobile-readiness-android.json` and
-`/tmp/mobile-readiness-ios.json`.
+Temporary raw outputs were not retained in the repository; results are summarised here.
 
 Review covered classification/normalization, schema parity, serialization,
 request-local state, ancestor budgets, native acquisition and cleanup, existing

package/docs/specs/021-app-readiness-signals/spec.md

@@ -1,8 +1,10 @@
 # Spec 021: app readiness signals
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md) · [Intent](intent.md) · [Plan and verification](plan.md)
+
 Date: 2026-10-29. Status: approved — implementation authorised.
 Source: [issue #65](https://github.com/clivejefferies/mobile-debug-tools/issues/65).
-[Intent](intent.md) approved by the originator’s “yes” in this conversation.
+[Intent](intent.md) approved by the originator’s “yes” during design review.
 
 ## Behaviour and scope
 

package/docs/specs/022-correlated-evidence/intent.md

@@ -1,6 +1,8 @@
 # Intent: correlated evidence
 
-Originator: repository maintainer (current conversation).
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md) · [Specification](spec.md) · [Plan and verification](plan.md)
+
+Originator: repository maintainer (design review).
 Date: 2026-10-29. Status: approved.
 Source: [issue #66](https://github.com/clivejefferies/mobile-debug-tools/issues/66), roadmap priority 3 of 9.
 
@@ -32,6 +34,4 @@ handling, building on existing helpers.
 
 ## Approval
 
-The maintainer’s “yes” on 2026-10-29 approved the complete linked intent in this
-conversation. This shorter version preserves that scope; specification approval
-remains pending.
+The maintainer’s “yes” on 2026-10-29 approved the complete linked intent during design review. See the linked specification for its separate approval record.

package/docs/specs/022-correlated-evidence/plan.md

@@ -1,7 +1,9 @@
 # Plan: correlated evidence
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md) · [Intent](intent.md) · [Specification](spec.md)
+
 Authorisation: [intent](intent.md), then [spec](spec.md), explicitly approved by
-“yes” and “approve” respectively in this conversation on 2026-10-29.
+“yes” and “approve” respectively during design review on 2026-10-29.
 
 ## Implementation
 
@@ -42,8 +44,8 @@ Use fresh device discovery. Exercise disabled/partial snapshot and invalid
 reference without changing app data. Record pass/fail/blocked/unrun plus metadata
 in this directory; avoid saving screenshot/log contents. Restore changed settings,
 stop only owned streams, and remove temporary test data. No settings change is
-needed. Android log healthcheck was degraded: targeted read is the next check;
-if unavailable, record its concrete error and verify metadata failure behaviour.
+needed. The initial Android log healthcheck was degraded; the targeted read
+subsequently passed, as recorded below.
 iOS physical-device coverage is outside existing simulator support.
 
 ## Results
@@ -77,10 +79,8 @@ contains no capture content; later Modul8 testing below records selector limits.
 - Physical-device correlation, installed/published-package verification: **unrun**.
   No release or deployment was requested.
 
-Validation logs for this local run: `/tmp/mobile-debug-correlated-verify.log` and
-`/tmp/mobile-debug-correlated-device.log`. The `tsx` CLI requires local IPC blocked
-by the sandbox; required npm checks ran with approved escalation. Focused checks
-also passed via `node --import tsx` without that socket.
+Required npm checks passed with local IPC enabled. Focused checks also passed
+via `node --import tsx`.
 
 ## Modul8 follow-up verification — 2026-10-30
 
@@ -146,8 +146,7 @@ conditional dispatch guards intact. Preserve unrelated correlated-evidence work.
   Modul8 and semantically confirmed the original Subscription screen. No app data
   or device settings changed; temporary cleanup client removed.
 - Historical failures in `modul8-evidence.json` are retained as before-fix evidence;
-  this repair supersedes their unresolved-selector status. Validation logs:
-  `/tmp/mobile-debug-selector-fix-verify.log`, `/tmp/mobile-debug-selector-fix-device.log`.
+  this repair supersedes their unresolved-selector status.
 
 ## Remaining readiness test flake — 2026-10-30
 
@@ -166,6 +165,6 @@ restored in `finally`. No production timing or readiness behaviour changed.
 - Focused check: Node 23 pass; 25 separate Node 18.20.8 test-process runs pass.
 - Full Node 18 maintainer verification with unavailable native defaults: **pass**
   (65 unit files, lint, build, agent-plugin consistency). Changed whitespace and
-  local document links also pass; log: `/tmp/mobile-debug-readiness-clock-verify.log`.
+  local document links also pass.
 - Native device suite not repeated for this test-only change; prior runtime
-  device results remain applicable. GitHub CI requires pushing this local repair.
+  device results remain applicable. Hosted CI was not rerun for this repair at the time of this record.

package/docs/specs/022-correlated-evidence/spec.md

@@ -1,9 +1,11 @@
 # Specification: correlated evidence
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md) · [Intent](intent.md) · [Plan and verification](plan.md)
+
 Date: 2026-10-29. Status: approved.
 Source: [issue #66](https://github.com/clivejefferies/mobile-debug-tools/issues/66).
 [Intent](intent.md) approved by “yes”; this specification approved by the
-maintainer’s “approve” on 2026-10-29 in this conversation.
+maintainer’s “approve” on 2026-10-29 during design review.
 
 ## Scope and association
 

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

@@ -1,5 +1,7 @@
 # Intent: Android system traces
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md) · [Specification](spec.md) · [Plan and verification](plan.md)
+
 Originator: repository maintainer, through GitHub roadmap issue #67.
 Date: 2026-10-30. Status: approved.
 Source: [issue #67](https://github.com/clivejefferies/mobile-debug-tools/issues/67), roadmap priority 4 of 9.
@@ -36,5 +38,4 @@ Android CLI integration is provisional and requires investigation.
 
 ## Approval
 
-The maintainer approved the complete captured intent with “yes” in this
-conversation on 2026-10-30. Specification approval remains pending.
+The maintainer approved the complete captured intent with “yes” during design review on 2026-10-30. See the linked specification for its separate approval record.

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

@@ -1,7 +1,9 @@
 # Plan: Android system traces
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md) · [Intent](intent.md) · [Specification](spec.md)
+
 Authorised by [intent](intent.md) (“yes”) and [specification](spec.md)
-(“looks good”, followed by “great”), 2026-10-30 in this conversation.
+(“looks good”, followed by “great”), 2026-10-30 during design review.
 
 ## Implementation
 
@@ -43,9 +45,8 @@ installed/published package remain separate from emulator evidence.
 
 ## Results
 
-Implementation and focused review completed on 2026-10-30 on
-`codex/android-system-traces`, based on `a74238b`. Changes remain uncommitted;
-no push, publication or installed-package update was requested.
+Implementation and focused review completed on 2026-10-30, based on
+`a74238b`. The results below cover the local build, not a published package.
 
 - Local runtime: Node 23.11.0 / npm 10.9.2. CI's Node 18 runtime remains **unrun**
   locally; the final CI workflow was not invoked. Existing CI uses Node 18 and
@@ -97,9 +98,6 @@ no push, publication or installed-package update was requested.
   explicitly unsupported, with rejection tested. Installed/published-package and
   full trace-analysis verification remain **unrun**.
 
-Validation logs: `/tmp/mobile-debug-system-traces-verify.log`,
-`/tmp/mobile-debug-system-traces-device.log`, and
-`/tmp/mobile-debug-system-traces-focused-device.log`.
 Changed documentation links, evidence JSON and whitespace checks pass.
 
 ## Emulator recheck — 2026-10-30

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

@@ -1,8 +1,10 @@
 # Specification: Android system traces
 
+[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.
 Source: [issue #67](https://github.com/clivejefferies/mobile-debug-tools/issues/67).
-[Intent](intent.md) approved by the maintainer’s “yes” in this conversation.
+[Intent](intent.md) approved by the maintainer’s “yes” during design review.
 Specification approved by “looks good” followed by “great” on 2026-10-30.
 
 ## Backend and boundaries

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

@@ -1,6 +1,8 @@
 # Intent: Android heap dump capture
 
-Originator: clivejefferies, through GitHub roadmap issue #69 and the current conversation.
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md)
+
+Originator: clivejefferies, through GitHub roadmap issue #69 and maintainer design review.
 Date: 2026-10-30. Status: parked; intent not approved.
 Source: [issue #69](https://github.com/clivejefferies/mobile-debug-tools/issues/69), roadmap priority 6 of 9.
 

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

@@ -1,6 +1,8 @@
 # Intent: Android runtime debugger
 
-Originator: clivejefferies, through GitHub roadmap issue #68 and the current conversation.
+[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.
 
@@ -36,5 +38,4 @@ concurrency, crash recovery, privacy, and runnable fixture coverage.
 ## Approval
 
 The user selected Android runtime debugger work with “ok, lets pick that up” and
-approved the complete captured intent with “yes” on 2026-10-30 in this
-conversation. Specification approval remains pending.
+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

@@ -1,7 +1,9 @@
 # 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 in this conversation. Implementation authorized.
+user's successive “yes” responses during design review. Implementation authorized.
 
 ## Implementation
 

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

@@ -1,7 +1,9 @@
 # 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” in this conversation.
+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
@@ -176,7 +178,6 @@ Primary references: [JDI VM lifecycle](https://docs.oracle.com/en/java/javase/17
 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
+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.