mobile-debug-mcp 0.33.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/device-evidence.json

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

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

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

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

@@ -0,0 +1,41 @@
+# 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.
+
+## Problem and outcome
+
+MCP clients investigating slow or frozen Android interactions need system-level
+performance evidence alongside existing journey and observation evidence.
+The server currently has no system-trace capture capability.
+
+Enable clients to start a bounded Android system trace, run an existing journey,
+stop capture, and obtain a local Perfetto artifact with device, capture timing,
+and correlation metadata. Detect available profiling capabilities explicitly and
+report unsupported environments, failures, cancellation, and cleanup outcomes.
+
+## Scope and success criteria
+
+- Android capture around existing journeys, reusing established device targeting
+  and correlated-evidence conventions.
+- Optional profiling tooling with explicit capability and prerequisite reporting.
+- Local artifact handling and bounded capture/resource ownership.
+- Successful start/stop and artifact retrieval on a supported Android fixture.
+- Explicit failure/cancellation outcomes and cleanup of session-owned resources.
+
+## Exclusions and open decisions
+
+Exclude iOS tracing, runtime debugging, heap dumps, automatic performance diagnosis,
+and changes to journey interaction semantics. Do not upload trace contents.
+
+Specification must establish the supported backend/tooling, tool contracts,
+capture limits/configuration, concurrent-session rules, cancellation/recovery,
+artifact retention, privacy handling, and verification prerequisites. The issue's
+Android CLI integration is provisional and requires investigation.
+
+## Approval
+
+The maintainer approved the complete captured intent with “yes” 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

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

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

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

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

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