mobile-debug-mcp 0.34.0 → 0.36.0

package/docs/specs/030-android-coroutine-validation/report.md

@@ -0,0 +1,240 @@
+# Android coroutine debugger assessment — issue #93
+
+Date: 2026-11-02. Source: [issue #93](https://github.com/clivejefferies/mobile-debug-tools/issues/93).
+Scope: [accepted specification](spec.md); [fixture/reproduction](../../../test/fixtures/coroutine-app/README.md).
+
+## Method and evidence boundaries
+
+The fixture uses explicit CompletableDeferred gates, two named single-thread
+executor dispatchers, a nested async child and a cancellation/finally path.
+It uses no debug probes or app instrumentation. The runner uses the existing
+MCP stdio server and records source/APK/server/worker/dependency fingerprints,
+compiler line/local tables and actual stops, stacks and locals. Fresh UI-tree
+assertions independently establish completion and cancellation recovery.
+Opaque MCP thread IDs are scoped to each stop; different ID strings alone do
+not establish a dispatcher change. Live synthetic thread-name locals and fixture
+checks establish the named dispatcher execution instead.
+
+Environment selected: emulator-5554, Android 16/API 36; Node 22.23.4;
+Kotlin compiler/stdlib 2.0.21; kotlinx-coroutines-core-jvm 1.9.0;
+fixture compiler JDK 17.0.11; Android SDK/build-tools 36. The debugger's existing
+Java discovery selects Android Studio JBR, which reports 25.0.3 on this host;
+setting fixture JAVA_HOME does not override that debugger discovery order.
+The local run used a temporary wrapper around the cached Kotlin embeddable
+compiler; the fixture README documents a standard Kotlin CLI installation.
+No result is inferred for other compiler/runtime versions.
+
+## Results
+
+Focused emulator journey: **PASS**. Full local output:
+`/tmp/mobile-debug-93-emulator.log`; compact checked-in [evidence](evidence.json).
+
+| Check | Observed result |
+| --- | --- |
+| Before/after gate suspension | PASS: source stops; `known=42` readable on both sides |
+| Dispatcher change | PASS: live locals `fixture-first` then `fixture-second` |
+| Nested child work | PASS: helper argument `43`; final `answer=44` |
+| Into/over/out | PASS inside the synchronous helper/increment calls |
+| Suspension-boundary step | Observed stop at `completeWork` entry, line 50; no logical-coroutine-following claim |
+| Safety and recovery | PASS: pause guard, stale-frame rejection, cancelled event wait with usable session |
+| Job cancellation | PASS: child finally source stop, joined cancellation, fresh `Coroutine cancelled` UI |
+| Completion/recovery | PASS: fresh `Coroutine result 44` UI after detach |
+| Owned cleanup | PASS: complete detach, forwards preserved, package/build directory removed |
+| Physical-device journey | UNRUN; explicit serial selection is required |
+
+Source SHA-256: `5978b835673876642c256b1c688975e78018addc1f68219371bc47c8cc29a92b`.
+Built server/dist SHA-256: `4f7bf452fc0022c8feb492f11a25c34ac5e360baff9f77d752dd0d248105d581`.
+Worker source SHA-256: `fb15e7add65fb3682d86153818d02378084a46fcd49b2c23c0eafdba290f8323`.
+Compiler/APK/dependency metadata and hashes are in the evidence file. APK signing
+is ephemeral, so subsequent APK hashes can differ.
+
+Initial cancellation recovery failed to reach its expected UI state while
+retaining the prior completion text. The test now starts cancellation from a
+fresh fixture process after detaching the boundary-step assessment. This is
+fixture-owned lifecycle isolation, not a debugger cleanup operation.
+An initial thread-name assertion also exposed compiler elimination of unused
+locals; the fixture now uses those values after the breakpoint so their emitted
+scope covers inspection. Assertions were not weakened to treat absent values
+as a dispatcher proof.
+
+## Interpretation and follow-up recommendation
+
+Existing source breakpoints can be a useful way to inspect separately executing
+parts of a coroutine. Source bindings must include generated binary class names
+from the actual compiler output. A shallow locals result and current-thread stack
+are execution evidence; they do not enumerate suspended coroutines, establish a
+parent/child job identity or recover an asynchronous logical stack. A local spilled
+into a continuation field need not appear in the current frame's local table.
+
+**No-go for implementing generic coroutine reconstruction in this ticket.** A
+separate feasibility design should first prove Android-compatible discovery of
+active and suspended continuations, stable job identity and ownership/parent-child
+relationships, and a versioned mapping from DebugMetadata/state labels to logical
+source frames. This would require inspection beyond the existing shallow locals
+API, or explicitly agreed app instrumentation, with privacy and compatibility
+limits. No such mechanism has been validated here.
+
+The upstream [kotlinx-coroutines-debug documentation](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-debug/)
+describes JVM agent-based coroutine tracking and explicitly identifies Android
+instrumentation limitations. It is not evidence that installing that JVM agent
+would supply an Android solution. The [DebugProbes API](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/)
+describes tracking creation, suspension and resumption with instrumentation and
+overhead; this fixture does not enable it. Android-specific alternatives and
+metadata compatibility remain design questions. Defer that capability design
+until after the bounded assessment and iOS parity, as the issue requires.
+
+## Limits
+
+Physical-device verification, other Kotlin/coroutine versions, optimized or
+obfuscated apps, inline suspend functions, process/device disconnect and forced
+host termination are unrun unless separately recorded below. Signal handling
+requests MCP cancellation then finally attempts owned cleanup; SIGKILL/host loss
+cannot run finally. No iOS runtime-debugger support is claimed. Hosted CI has not
+run; it separately compiles the worker with JDK 17 and checks package contents,
+and its ordinary device workflow does not provision this opt-in Kotlin compiler.
+Local build/test evidence is not an installed or published-package check.
+
+## Repository verification
+
+`npm run verify` **PASS** on Node 22.23.4: lint, structural/architecture checks,
+TypeScript build, all 89 unit files and plugin consistency. Final log:
+`/tmp/mobile-debug-93-final-verify.log`. The sandbox blocked tsx IPC creation;
+verification passed in the authorized run outside the sandbox without changing
+checks. Changed relative links, new-file whitespace and `git diff --check` passed.
+
+The focused review found no required production-code or schema change. Fixture
+subprocesses/polls are bounded; package targeting is explicit; the runner refuses
+pre-existing fixture installations and keeps normal debugger cleanup separate
+from resetting its own app between independent cases. At the original verification,
+changes were local, uncommitted and unpushed.
+
+Full `npm run test:device` **PASS**, all 12 files, with
+`MCP_COROUTINE_DEVICE=emulator-5554 MCP_KOTLIN_DEVICE=emulator-5554 MCP_DEBUGGER_DEVICE=emulator-5554`
+and the documented local compiler/stdlib/coroutine paths set. Log:
+`/tmp/mobile-debug-93-device.log`. The coroutine assessment passed again on the
+same source/server/worker fingerprints (ephemeral APK signing produced SHA-256
+`6cc95ae8ad9d254444e9704a7526d62a0ab1c8354a5624d6695789eedd429f82`).
+Existing Kotlin/Java debugger, interaction, Android/iOS observation smoke,
+correlated-evidence and Android system-trace checks passed. These iOS checks do
+not verify iOS runtime debugging. The new fixture's package, temporary outputs
+and owned forwards were removed; no physical-device coroutine check ran.
+
+## PR #96 repair evidence
+
+The original results above predate the readiness-race fix: they establish the
+recorded locations/values, but the original UI readiness alone did not prove
+that the gate wait had suspended before release/cancellation. New readiness
+runs as queued work behind the coroutine on its own single-thread executor,
+which cannot execute until that coroutine yields. The repaired dispatcher
+breakpoint class is `MainActivity$completeWork$3`.
+
+Overall JSON PASS now follows cleanup, and cleanup failures are reported as FAIL.
+Forward comparisons select only the target serial and sort entries. The new
+unit regressions and repository verification passed (90 unit files, Node 22.23.3;
+`/tmp/pr96-verify.log`). The first attempt on a restored emulator
+snapshot hit install/uninstall timeouts; that real cleanup failure emitted JSON FAIL
+without an overall PASS (`/tmp/pr96-device.log`). The task-owned leftover package
+was removed after a cold start. Final device-rerun evidence is recorded below;
+the original suspension-readiness evidence is superseded.
+
+Final repair verification: `npm run verify` **PASS**, all 90 unit files, Node
+22.23.3 (`/tmp/pr96-final-verify.log`). Unit checks cover successful cleanup before
+PASS, work failure, cleanup failure, simultaneous failures without losing either
+error, exact serial filtering, other-device churn and order normalization.
+
+Full device-suite attempts **FAIL** during installation/cleanup on the restored
+and cold-started emulator (`/tmp/pr96-device.log`, `/tmp/pr96-device-cold.log`).
+Incremental installation continued after host-side timeout, leaving a differently
+signed package; the task-owned package was removed. A focused streamed-install
+run used an external temporary ADB_PATH wrapper adding `--no-incremental` only
+for install, without changing repository timeouts or assertions.
+
+That focused run **passed** completion, verified the queued readiness and updated
+`completeWork$3` breakpoints, named dispatchers, known values, synchronous steps,
+stale/pause guards, cancelled wait recovery and the bounded suspension-step
+observation. It then **failed** at `am start -W` restarting the fixture before
+cancellation, followed by an uninstall timeout. Its overall JSON FAIL preserves
+both errors (`/tmp/pr96-focused-streamed.log`). Repaired cancellation readiness
+is compiler-checked but its device journey is **UNRUN**; remaining suite checks
+were not reached. No full native pass is claimed for this repair.
+
+Current fixture source SHA-256:
+`d4656e3736cc245230bc000c6574288b145df47957dd7ee511ea98717afde4df`.
+Final independent package query returned no owned fixture package; no ADB forwards
+remained and temporary build output was removed. The review fixes introduce no
+production server behaviour or contract change. Physical-device checks and hosted
+CI are unrun for this revision.
+
+## Successful retry on the maintainer's running emulator
+
+The repaired coroutine assessment **PASS**ed in full on emulator-5554, Android
+16/API 36, commit `1497693`, Node 22.23.3. This supersedes the earlier incomplete
+cancellation verification: queued readiness, cancellation/finally, cancelAndJoin,
+fresh `Coroutine cancelled` UI, completion, stepping, guards, cancelled event wait
+and owned cleanup all passed. The overall JSON PASS followed successful cleanup.
+Log: `/tmp/pr96-user-emulator.log`.
+
+Fixture source SHA-256 remains
+`d4656e3736cc245230bc000c6574288b145df47957dd7ee511ea98717afde4df`;
+server/dist remains `4f7bf452fc0022c8feb492f11a25c34ac5e360baff9f77d752dd0d248105d581`.
+APK SHA-256: `3ec87db96cd87f9bd7ca27472dde8c1b57d2789d9f808714362ca4ba2ee95c83`.
+Kotlin/stdlib 2.0.21, coroutines 1.9.0 and fixture JDK 17.0.11 were unchanged.
+Local setup used the temporary ADB_PATH wrapper for streamed installation and
+`JAVA_TOOL_OPTIONS='-Xmx512m -XX:TieredStopAtLevel=1'` for host JVM startup.
+No assertions or deadlines changed. The user-started emulator remains running;
+only fixture-owned resources were removed. Physical-device coroutine validation
+remains unrun.
+
+The full device-suite retry passed coroutine, Kotlin/Java debugger, interaction
+and Android screenshot checks before failing the iOS screenshot test's ambiguous
+target selection (`/tmp/pr96-user-device-suite.log`). Separate Android logs,
+UI-tree and correlated-evidence checks passed; the correlation script then failed
+its iOS prerequisite because no iOS simulator was running
+(`/tmp/pr96-user-android-remaining.log`). Full-suite status remains **FAIL** for
+those iOS setup requirements, while the repaired Android coroutine journey is
+verified **PASS**, including cancellation and cleanup.
+
+A separate Android system-trace check failed its cancellation-state assertion
+(`failed` / `ACTION_TIMEOUT`, expected `cancelled`); its finally cleanup retry
+completed. Log: `/tmp/pr96-user-trace.log`. This is an additional observed
+limitation in the broader smoke checks; it does not invalidate the coroutine
+journey's successful cancellation and cleanup. No trace code or assertions were
+changed, and no complete device-suite pass is claimed.
+
+## Perfetto timeout investigation — 2026-11-02
+
+The earlier `cancel_system_trace` failure reported ACTION_TIMEOUT in the bounded
+stop/termination phase. Its original log does not identify which ADB command or
+process-exit wait exhausted the budget, so the root cause remains undetermined.
+No tracing source or smoke-test changes appear in PR #96.
+
+On the same running Android 16/API 36 emulator-5554 and server build
+`e90ed0831de4059f1e2b213ed0c050298cf2e55c0cc0aef9ff4ea2a38b6062a0`:
+
+- Three direct native/session start-cancel probes **PASS**ed with complete cleanup;
+  cancellation took 372, 373 and 390 ms. Log: `/tmp/pr96-perfetto-probe.log`.
+- Three full MCP smoke journeys **PASS**ed: Settings journey assertion, readable
+  trace content, explicit stop, cancellation, automatic duration completion,
+  stale-trace rejection and active shutdown cleanup. Logs:
+  `/tmp/pr96-perfetto-retest.log`, `/tmp/pr96-perfetto-instrumented-1.log`,
+  `/tmp/pr96-perfetto-instrumented-2.log`.
+- The final run used an assertion-identical temporary test copy with a server
+  preloader recording native-command timing. Across 71 commands, the only
+  nonzero exits were five expected Perfetto help probes (exit 1 is supported).
+  Maximum process lookup was 111 ms; maximum signal command 63 ms; maximum start
+  247 ms. No command timed out. Log: `/tmp/pr96-perfetto-mcp-timings.log`.
+- The first attempted instrumentation relied on NODE_OPTIONS, which the SDK's
+  default subprocess environment did not forward to the server. That smoke pass
+  remains valid but supplies no server timing evidence. The final run explicitly
+  preloaded the diagnostic module in both server subprocesses.
+- Final independent checks found no MCP trace files and no forwards on the
+  emulator. Host test artifacts were removed by each smoke journey. The emulator
+  remains running; no settings or user-app data were changed.
+
+Classification: the previously observed timeout is **not reproduced**, with an
+intermittent timing failure still possible. Passing reruns do not establish its
+cause or prove it fixed. No production change, timeout increase, assertion change
+or test suppression was made. Current Perfetto verification passes; the earlier
+failed observation is retained rather than reclassified as a pass. Any recurrence
+needs command timings at the failing invocation to distinguish ADB transport,
+process identity lookup, signalling and process-exit delay.

package/docs/specs/030-android-coroutine-validation/spec.md

@@ -0,0 +1,107 @@
+# Android coroutine validation specification — issue #93
+
+Status: accepted by the maintainer’s second “ok” in this chat on 2026-11-02. Implements the
+[accepted intent](intent.md), approved by “ok” in this chat on 2026-11-02.
+
+## Outcome and compatibility
+
+Establish what the existing Android JDI tools actually expose for an isolated
+Kotlin coroutine, and publish a reproducible assessment. No server capability,
+schema, response shape, error code or default changes. Android only; iOS runtime
+debugging remains unsupported. Java and synchronous Kotlin fixture journeys
+retain their current behaviour. Any reproduced production defect is reported
+with evidence and handled separately through the shared process.
+
+## Fixture and prerequisites
+
+Add an opt-in coroutine variant of the disposable debugger fixture, built from
+checked-in source using the existing direct Kotlin/D8/aapt2 pipeline. Initially
+target Kotlin compiler/stdlib 2.0.21, kotlinx-coroutines-core-jvm 1.9.0, JDK 17,
+Android SDK/build-tools 36 and Node 22+. Require explicit local dependency paths;
+do not download dependencies at test runtime, add server dependencies, enable
+debug probes or instrument user apps. Record actual versions and dependency
+hashes. Missing or incompatible prerequisites produce an actionable blocked
+result, not a pass.
+
+Use a separate fixture package so the coroutine journey cannot replace the
+existing Java/Kotlin fixture. Refuse installation if that package is already
+present; remove only the package installed by this run. Run sequentially on an
+explicit device serial. Initial target is emulator-5554; an attached Pixel 9 Pro
+is a separate optional verification target, never selected automatically.
+
+The fixture owns two named single-thread executor dispatchers. This makes a
+thread change observable without relying on scheduler chance. A run exposes a
+known local, suspends on a controllable gate, continues on the other dispatcher,
+performs nested child work, then completes with a fixed visible result. A
+separate cancellation run suspends a child, cancels and joins it, executes its
+finally block and shows a cancellation result. Gates and UI state establish
+ordering; arbitrary sleeps do not establish suspension. Close jobs/executors
+on activity destruction. Use compiler-emitted line/class metadata to identify
+generated continuation classes; do not assume every source line belongs to
+MainActivity or has a usable breakpoint.
+
+## Existing MCP workflow
+
+Use `get_debugger_capabilities`, `attach_debugger`,
+`set_debugger_breakpoint`, `wait_for_debugger_event`, `get_debugger_stack`,
+`get_debugger_locals`, `step_debugger`, `resume_debugger`,
+`remove_debugger_breakpoint`, `get_debugger_state` and `detach_debugger` with
+their current inputs and response contracts in the [debugger guide](../../tools/debugger.md).
+Keep session IDs, stop/thread/frame IDs and event cursors scoped to that run;
+reject overflow as incomplete evidence. Inspect thread-based frames and shallow
+locals without evaluating expressions or traversing continuation objects.
+
+Verify source stops before and after suspension and across the dispatcher
+change; compare known values with compiler scope tables. Report missing or
+unavailable locals honestly. Compiler spilling into continuation fields does
+not imply the locals API exposes those fields. Compare observed thread IDs and
+stack locations, without calling a thread stack a logical coroutine stack.
+
+Exercise into/over/out on a deterministic synchronous helper inside the coroutine.
+Separately attempt a bounded step across a suspension boundary and record where
+the event actually stops, including generated/runtime code or absence of a stop.
+Do not require that step to follow the coroutine; remove the step request through
+normal detach if it cannot make useful progress. A fresh session can then verify
+the before/after source-breakpoint workaround independently.
+
+## Safety, failure and cleanup
+
+All stops suspend the app. Verify an MCP interaction is rejected with the existing
+`DEBUGGER_PAUSED` result; no UI action is needed to release a gate while paused.
+Resume before further input. Old stop/frame references must return
+`DEBUGGER_STALE_REFERENCE` after execution resumes. Cancel an event wait and
+confirm the session remains usable; distinguish MCP request cancellation from
+fixture job cancellation.
+
+Bound subprocesses and polls with explicit deadlines. Keep normal inspection
+below the existing 60-second pause limit. On timeout, failure or interruption,
+attempt bounded detach, close the client, remove only owned forwards/package
+and temporary build output, and report unresolved cleanup. Never kill ADB,
+unrelated debugger sessions or user apps, nor automatically retry uncertain
+attach/step/resume operations. Preserve unrelated forwards. After normal detach,
+use a fresh UI-tree assertion of the expected completion/cancellation text to
+prove app recovery; detach acknowledgement alone is insufficient.
+
+## Acceptance and assessment
+
+1. A reproducible opt-in runner records source/APK/server fingerprints, dependency
+   versions, Android target and per-journey pass/fail/blocked/unrun results.
+2. Completion, cancellation, breakpoint workaround, stepping observations,
+   stale references, pause guards, cancelled wait recovery and owned cleanup
+   have explicit evidence. An unsupported debugging observation is an assessment
+   finding; a failed safety or cleanup assertion remains a failure.
+3. Emulator and physical-device evidence are separate. No physical run or
+   version compatibility is inferred from emulator success.
+4. Tool docs, usage skill and fixture README explain verified behaviour,
+   limitations and reproduction. Existing journeys and `npm run verify` pass;
+   applicable `npm run test:device` coverage and skips are reported.
+5. A report recommends go/no-go for separately scoped inspection of active and
+   suspended coroutine state, parent/child identity and logical stacks. Describe
+   metadata/probe requirements and setup friction as evidence or open questions.
+   No follow-up capability is implemented or approved by this specification.
+
+Only synthetic fixture values are collected. Retain local evidence intentionally;
+do not upload app data. Principal risks are compiler source mapping, ART variable
+metadata and scheduler/debugger interaction. No live coroutine behaviour has been
+verified yet. Prerequisite discovery found the proposed compiler/coroutine jars,
+JDK 17 and an authorized emulator; this is availability evidence only.

package/docs/specs/031-ios-system-traces/intent.md

@@ -0,0 +1,38 @@
+# iOS system traces — intent
+
+- Source: [GitHub issue #78](https://github.com/clivejefferies/mobile-debug-tools/issues/78), authored by clivejefferies.
+- Captured: 2026-11-04.
+- Status: intent approved by the user's “ok” on 2026-11-04, responding to the
+  complete scope and approval request in this chat. Specification approval pending.
+
+## Problem and outcome
+
+MCP clients need optional iOS performance evidence around an existing journey
+to investigate slow interactions, hangs and rendering hitches. Add bounded
+Apple Instruments capture through `xcrun xctrace` on macOS with Xcode, returning
+a readable local `.trace` artifact with explicit iOS target/app metadata and
+journey/evidence correlation identifiers.
+
+## Scope and constraints
+
+Investigate System Trace, Time Profiler, Hangs and Animation Hitches availability
+and distinct coverage, then propose an initial supported target/template matrix.
+Assess simulators and physical devices independently. Require explicit target
+UDIDs, recording readiness before journey input, artifact validation, bounded
+resource use, and cleanup of session-owned processes. Keep trace contents local,
+explain sensitive-data and retention implications, and report setup/permission
+failures without bypassing them. Reuse Android tracing conventions where suitable
+and preserve existing Android and untraced-journey behaviour.
+
+Success requires at least one development fixture completing start → asserted
+journey → stop with a readable artifact and matching correlation metadata.
+Report unsupported, blocked and unrun coverage separately.
+
+Automatic diagnosis, performance summaries, arbitrary queries, general export
+APIs and runtime debugging are excluded.
+
+## Questions for investigation
+
+Which target/template combinations are usable, how is recording readiness
+established, and which fixture and export tables can prove useful capture?
+These choices require specification approval after intent acceptance.

package/docs/specs/031-ios-system-traces/investigation.md

@@ -0,0 +1,92 @@
+# iOS tracing investigation
+
+2026-11-04. Native CLI feasibility only; no new MCP behaviour implemented.
+Xcode 27.2 (27B52), Instruments 27.2; iPhone 17 Pro simulator, iOS 26.4.1,
+UDID `F9243BAF-62A8-4990-8A99-17F527F56FDA`.
+
+`xcrun xctrace help record`, `help export`, `list templates`, `list devices`,
+and `record --template 'Time Profiler' --device <UDID>
+--show-recording-options` were inspected. Listing required execution outside
+the workspace sandbox because Instruments writes its normal cache. No physical
+iOS device was listed. No permission bypass or `--no-prompt` was used.
+
+The existing `test/fixtures/readiness-app` was built, installed and launched on
+the explicitly selected simulator. It was previously shut down. Three-second
+recordings used `record --template <name> --device <UDID> --attach Readiness
+--time-limit 3s --output <unique local path>`. Initial PID attachment failed
+with “Cannot find process”; later name attachment resolved fixture PID 22313.
+This argues for exact app identity resolution and fail-closed readiness, not
+blind PID/name retries. No journey or UI assertion ran during these probes.
+
+| Template | Result | Artifact validation |
+| --- | --- | --- |
+| Time Profiler | exit 0 | TOC confirms simulator UDID, fixture PID and template; `time-sample` export contains 5 rows |
+| System Trace | exit 0 | TOC confirms target/template, but `context-switch` export has 0 rows; scheduling coverage unproven |
+| Animation Hitches | exit 2 | explicit “Hitches is not supported on this platform”; saved failed artifact is not success |
+| Hangs | no standalone template | Time Profiler recording options and TOC include Hangs; hang detection itself unverified |
+
+Successful recordings warned that one table lacked a known input source.
+Preserve such warnings; readable output does not establish every instrument works.
+`--notify-tracing-started` is documented by the installed CLI; notification-based
+readiness and graceful interruption remain unverified implementation checks.
+
+Artifacts are local temporary investigation data under `/private/tmp/`:
+`mcp-ios-time-profiler-name-01a1a646.trace`,
+`mcp-ios-system-trace-01a1a646.trace`, `mcp-ios-animation-01a1a646.trace`.
+Exports: `mcp-ios-time-samples-01a1a646.xml`,
+`mcp-ios-system-toc-01a1a646.xml`, `mcp-ios-context-switch-01a1a646.xml`.
+These were temporary investigation artifacts, subsequently removed during task cleanup; they are not tracked repository artifacts.
+Fixture uninstall and simulator shutdown both passed; no recording remained active.
+
+Owning code inspected: `src/observe/system-trace.ts`,
+`src/server/handlers/diagnostic.ts`, `src/server/handlers/journey.ts`,
+`src/server/schemas/system-trace-schema.ts`, and `src/utils/resolve-device.ts`.
+Current session metadata and journey validation hardcode Android; existing APIs
+must be extended consistently rather than routing iOS into the Perfetto adapter.
+
+## Updated-server verification and input tooling
+
+The default Homebrew `idb_companion` 1.1.8 (built 2022-08-12) can read this
+simulator hierarchy but its HID input fails because it loads SimulatorKit from
+`Contents/Developer/Library/PrivateFrameworks/SimulatorKit.framework`. Xcode 27.2
+ships it under `Contents/SharedFrameworks/SimulatorKit.framework` instead.
+A direct tap on the offline fixture reproduced that failure without tracing.
+The early full smoke runs therefore failed; their assertions were not weakened.
+
+For the successful input verification, a **test-owned** companion used a private
+layout alias under `/private/tmp/mcp-idb-xcode-o6ks8j9h/Contents/Developer`:
+other Xcode contents were symlinks to the installed Xcode, with an additional
+`Developer/Library/PrivateFrameworks/SimulatorKit.framework` link to the actual
+SharedFrameworks location. `DEVELOPER_DIR` was set only for that companion.
+The installed Xcode and existing companion were not modified or replaced.
+
+The isolated companion command was:
+
+```sh
+DEVELOPER_DIR=<private-alias>/Contents/Developer idb_companion \
+  --udid F9243BAF-62A8-4990-8A99-17F527F56FDA \
+  --grpc-domain-sock /private/tmp/mcp-ios-trace-idb.sock --log-level info
+```
+
+The smoke passes `IDB_COMPANION=/private/tmp/mcp-ios-trace-idb.sock` explicitly
+into the built server, using the installed idb client's supported companion
+option. Instruments uses the real selected Xcode. This is verification-specific
+tooling setup, not a new shipped input backend or proof that default idb HID works
+with Xcode 27.2. Environments need a compatible idb companion for input journeys.
+Capture-only use does not require idb input. See [plan](plan.md) and the final
+[simulator evidence](simulator-evidence.json) for exactly what passed and cleanup.
+
+A later long smoke run passed tap → Done (66 exported sample rows), cancellation,
+expiry and failed-journey handling, then returned `TRACE_UNSUPPORTED` starting an
+independent shutdown probe. Its exact prerequisite cause was not established;
+a subsequent standalone capability read found all capture prerequisites available.
+The original smoke then incorrectly reported expired completed metadata as failed
+cleanup after ten minutes. [That failed report](late-run-failure-evidence.json)
+is retained. The harness now tracks only sessions that still require cleanup and
+queries explicit capabilities before the separate shutdown probe. The prerequisite
+failure is not attributed to CPU load or a particular permission without evidence.
+
+Final cleanup verified the simulator returned to Shutdown and no Readiness.app
+fixture remained. The test-owned companion, layout alias, socket and private log
+were removed. The final standalone combined smoke passed; its exact build and
+outcomes are recorded in plan.md and simulator-evidence.json.

package/docs/specs/031-ios-system-traces/late-run-failure-evidence.json

@@ -0,0 +1,32 @@
+{
+  "linked_baseline": "PASS; Ready asserted via built-server journey",
+  "journey": {
+    "status": "PASS",
+    "trace_id": "ec906d78-08bf-495b-a824-2cdaf84536ba",
+    "correlation_id": "78d5c21f-435e-4b9c-822a-1cdfb23a1d63",
+    "ready_at_ms": 1793794165955,
+    "journey_submitted_at_ms": 1793794170369,
+    "outcome": "Done visible via journey UI-tree assertion",
+    "sample_rows": 66,
+    "artifact_bytes": 12304469,
+    "warnings": [
+      "INSTRUMENTS_RUN_WARNING: one or more Instruments warnings; coverage may be incomplete."
+    ]
+  },
+  "stale_id": "PASS; rejected tap left prior fixture label visible",
+  "cancel": "PASS",
+  "expiry": "PASS",
+  "failed_journey": "PASS; failure retained capture for explicit stop",
+  "status": "FAIL",
+  "error": "AssertionError [ERR_ASSERTION]: {\"error\":{\"tool\":\"start_system_trace\",\"code\":\"TRACE_UNSUPPORTED\",\"message\":\"TRACE_UNSUPPORTED\"}}\n+ actual - expected\n\n+ undefined\n- 'recording'\n",
+  "cleanup": {
+    "trace_errors": [
+      "ec906d78-08bf-495b-a824-2cdaf84536ba",
+      "7f89df16-af5c-4c1f-a21d-bb1f5b702dc5",
+      "379e63fc-d780-4a80-96d3-1eca3cda1c28"
+    ],
+    "fixture_removed": true,
+    "simulator_shutdown": false,
+    "host_artifacts_removed": true
+  }
+}

package/docs/specs/031-ios-system-traces/plan.md

@@ -0,0 +1,138 @@
+# iOS system traces implementation plan
+
+[Intent](intent.md) and [specification](spec.md) approved in this chat on
+2026-11-04. Implementation is local on `feature/ios-system-traces`; no publication
+or push requested. Preserve Android contracts and unrelated work.
+
+## Implementation
+
+- [x] Add bounded owned subprocess and Darwin-notification helper support.
+- [x] Add simulator/app capability discovery and validated Instruments artifacts.
+- [x] Add iOS sessions and shared platform routing, limits and journey linkage.
+- [x] Extend schemas, public definitions, fixtures and documentation/usage skill.
+- [x] Add deterministic lifecycle/native/contract tests and explicit simulator smoke.
+- [x] Review resource ownership, failure/retry paths, schemas and Android callers.
+
+## Verification
+
+Node >=22 (use installed Node 22 where needed), Xcode 27.2 and iOS 26.4.1
+simulator `F9243BAF-62A8-4990-8A99-17F527F56FDA`. Boot only that simulator,
+install the existing offline readiness fixture, launch, start Time Profiler,
+run a journey tapping Show loader and asserting Done, stop and validate target,
+IDs, readiness ordering, TOC and sample rows. Also exercise expiry, cancel and
+failed journey. Remove fixture and restore simulator shutdown afterward.
+
+| Criteria | Checks |
+| --- | --- |
+| 1 capability/input safety | injected native probes, handler/schema and definition goldens |
+| 2 validated linked capture | updated-server simulator smoke with outcome assertion and artifact exports |
+| 3 lifecycle and ownership | deterministic native/session failure, concurrency, stale/mismatch, retry tests |
+| 4 real lifecycle evidence | simulator explicit stop, expiry, cancellation and journey failure |
+| 5 compatibility | Android session tests, existing device suite, full maintainer verification |
+
+Commands: focused `node --import tsx test/unit/...` checks, `npm run verify`,
+`npm run test:device`, opt-in iOS trace smoke with an explicit simulator UDID.
+CI workflows will be checked for coverage differences. Physical-device capture
+is outside the initial matrix and unrun; none is connected. Notification helper
+compilation/readiness, PID identity resolution and finalisation deadlines require
+early native checks. No test result is implied by the prior feasibility probes.
+
+## Results
+
+Implementation and focused review complete locally. No commit, push or release.
+
+| Check | Result and scope |
+| --- | --- |
+| Focused native/session/router/tool contracts | PASS: identity/executable matching, notification-before-readiness, stale and mismatched links, shared pending reservations, expiry, cancellation, export retry without restart, storage and subprocess deadlines |
+| `npm run verify` | PASS on Node 23.11.0: lint, structural gates, architecture, TypeScript, 94 unit files, agent-plugin consistency. Final post-fix run also passed, including the corrected smoke cleanup harness. |
+| `npm run test:device` | PASS on the local emulator/simulator: Android Perfetto capture/readability, explicit stop/cancel/expiry/shutdown plus Android+iOS observation/evidence smoke. 13 files visited; opt-in debugger/coroutine/Kotlin/interaction and iOS trace files report UNRUN without their explicit environment. |
+| Focused built-server iOS trace smoke | Full fixture tap → Done UI-tree assertion and sample export passed using the isolated input companion documented in investigation.md. Final standalone combined lifecycle/shutdown run PASS; see simulator-evidence.json. |
+| Real iOS shutdown recheck | PASS after allowing recorder finalisation up to eight seconds inside the ten-second server budget. Earlier one-second forced-stop run failed cleanup; that failure was investigated and fixed. |
+| Physical device / real native failure injection | UNRUN. Physical capture is outside the accepted initial matrix; disconnect/permission/start/export/storage failure branches have deterministic coverage, not real-device proof. |
+
+Logs: `/private/tmp/mobile-debug-ios-trace-verify-final.log` and
+`/private/tmp/mobile-debug-ios-trace-device.log`. CI uses Ubuntu/Node 22/JDK 17;
+local validation used macOS/Node 23.11.0 and installed toolchains. Hosted CI is
+unrun. No hosted-CI or installed/published-package compatibility claim is made.
+
+Review: schemas, registration goldens, dispatch, response serialization and callers
+were checked together. Android adapter/session logic remains intact behind routing.
+Recorder handles are owned, process identity is revalidated, artifacts validate
+UUID/PID/executable/template/table data, and temporary exports/helpers are removed.
+Forced-stop deadlines, incomplete shutdown reporting and oversized-output disposal
+were reviewed. No remaining actionable code review finding is recorded.
+
+Local limitations: default idb 1.1.8 HID is incompatible with the Xcode 27.2
+framework layout. Successful input evidence uses a test-owned companion with a
+private path alias; capture itself uses the actual selected Xcode. Instruments
+reported a bounded run warning; successful CPU sample export does not verify all
+bundled instruments, scheduling data, symbolication or hang detection.
+
+
+## Final device result and cleanup
+
+The final standalone built-server smoke passed with build SHA-256
+`48eee7b1f71403645ab301def8d83dd14585eec099b221f8ac4f6aaba0941282`.
+The UI-tree assertion established Done after tapping Show loader, with readiness
+before journey submission, matching correlation identifiers and 70 exported CPU
+sample rows in an 11,961,327-byte readable Instruments bundle. Explicit stop,
+stale rejection, cancel, duration expiry, failed-journey retention, real server
+shutdown and target-app survival passed. The generated report is
+[simulator-evidence.json](simulator-evidence.json).
+
+The earlier long-run failure is retained as
+[late-run-failure-evidence.json](late-run-failure-evidence.json); it is not called
+a pass. The final run used corrected active-session cleanup tracking and explicit
+shutdown capability checks, after maintainer verification had finished.
+
+Final `npm run verify`: PASS, 94 unit files, on Node 23.11.0. The native forced-stop
+nonclosure case has a bounded deterministic test. The existing device suite's
+passed checks and opt-in UNRUN entries are scoped above. Hosted CI remains unrun.
+
+All task-owned fixture installations and trace/probe artifacts were removed. The
+test-owned companion was stopped only after verifying its exact command/PID;
+its path alias, socket and private diagnostic log were removed. The simulator's
+original Shutdown state and fixture absence were verified with simctl and the
+filesystem. The original companion and installed Xcode were unchanged. No active
+task recording remains. Changes are uncommitted and unpushed.
+
+## PR #102 review repair — 2026-11-04
+
+The three review findings were checked against the current branch. Clarified
+artifact retention wording in the canonical and generated Cursor skills, and
+separated Android/iOS capability and session fields in the tool guide.
+
+Monitoring now tolerates two consecutive non-definitive failures, resets the
+counter on success, and preserves COMMAND_FAILED/ACTION_TIMEOUT classifications.
+Unknown failures use bounded TRACE_MONITOR_FAILED rather than claiming a target
+disconnect. Storage, changed identity and missing-app failures remain immediate.
+Tolerated failures still reconcile expiry and recorder exit; retries retain the
+same device/app/recording and never restart capture.
+
+Deterministic tests cover reset, third-failure cleanup, immediate failures,
+reason privacy, pinned recording identity and deadline/recorder fall-through.
+Fresh maintainer/device results and focused simulator evidence are recorded
+below after validation; previous feature evidence remains scoped to its build.
+
+PR repair validation:
+
+- `npm run verify`: PASS on Node 23.11.0, including 94 unit files and plugin sync.
+- `npm run test:device`: Android+iOS observation/evidence checks passed; the
+  Android system-trace shutdown assertion failed in the full run. Its uniquely
+  owned leftover trace was removed. The unchanged Android trace smoke passed
+  independently afterward, including active shutdown. The initial suite failure
+  remains recorded; its exact cause was not established.
+- Focused iPhone 17 Pro / iOS 26.4 simulator check: PASS using built iOS adapters,
+  real Time Profiler recording, and explicitly injected monitor failures. Two
+  COMMAND_FAILED polls preserved capture and yielded seven exported sample rows;
+  three ACTION_TIMEOUT polls failed with that reason and complete cleanup.
+  See [pr102-monitor-evidence.json](pr102-monitor-evidence.json) for its build hash.
+  This checks monitoring and native capture, not a new UI-input journey or real
+  device disconnection. Deterministic tests establish expiry/reset/identity cases.
+- Fixture and test host artifacts removed; simulator returned to Shutdown.
+  Physical devices and hosted CI are not established by these local checks.
+
+Logs: `/private/tmp/mobile-debug-pr102-verify.log`,
+`/private/tmp/mobile-debug-pr102-device.log`,
+`/private/tmp/mobile-debug-pr102-android-rerun.log` and
+`/private/tmp/mobile-debug-pr102-monitor.log`.