mobile-debug-mcp 0.35.0 → 0.37.0

package/docs/benchmarks/end-to-end-latency/smoke.md

@@ -0,0 +1,21 @@
+# End-to-end latency smoke (not performance evidence)
+
+Status: finished. Build: 8f3a9bc8f498181686362c829e7395f301e85681d8ea1667692e2b33c18d011c.
+
+| Case | Successful/measured | p50 ms | p95 ms | Failures | Warm-up failures |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| standalone | 1/1 | 146335.1 | 146335.1 | 0 | 0 |
+| full-debug | 1/1 | 84684.9 | 84684.9 | 0 | 0 |
+| full-compact | 1/1 | 85400.3 | 85400.3 | 0 | 0 |
+| light-debug | 1/1 | 65161.8 | 65161.8 | 0 | 0 |
+| light-compact | 1/1 | 50780.4 | 50780.4 | 0 | 0 |
+| screenshot-on | 1/1 | 884.2 | 884.2 | 0 | 0 |
+| screenshot-off | 1/1 | 658.8 | 658.8 | 0 | 0 |
+| tree-on | 1/1 | 2611.1 | 2611.1 | 0 | 0 |
+| tree-off | 1/1 | 2509.6 | 2509.6 | 0 | 0 |
+| snapshot-on | 1/1 | 4575.6 | 4575.6 | 0 | 0 |
+| snapshot-off | 1/1 | 4667.2 | 4667.2 | 0 | 0 |
+
+See smoke.json for exact source/build hashes, environment, phase durations, attempt order, inclusive components and failure records. Percentiles use the successful measured count shown for each case. With 1–19 successful samples, nearest-rank p95 is the sample maximum. Zero successful samples yield no percentiles. Failed attempts are excluded from percentiles, retained in raw data, and fail the run.
+
+Intervals can overlap; component sums are not an additive latency budget. Client-minus-handler includes scheduling, transport and uninstrumented work. Handler residual excludes the union of recorded spans. Tree acquisition/parse/retry events are separate nested diagnostics. Application work inside requests remains included. Startup, fixture builds/resets and external validation are excluded from steady-state round trips. SDK wire serialization is not isolated.

package/docs/code-structure.md

@@ -111,7 +111,9 @@ requires reviewing its exception rather than silently transferring it.
   it is not packet capture or a proxy. Results depend on the app logging requests,
   and the current implementation does not measure request duration.
 - `src/debugger/protocol.ts` validates worker messages. The session manager owns
-  serialized transitions and cleanup; the Java worker owns JDI operations.
+  serialized transitions and cleanup; the Java worker owns Android JDI operations.
+  The optional `lldb/` Python worker owns iOS simulator LLDB operations and static
+  inspection; `ios.ts` verifies simulator/app/process membership before attach.
 
 The [refactoring plan](specs/026-code-structure-and-quality-gates/plan.md) records
 progress and verification. The [follow-on health cleanup](specs/026-code-structure-and-quality-gates/health-plan.md)

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,166 @@
+# 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`.
+
+
+## Shutdown cleanup repair — 2026-11-05
+
+A simulator run exposed a discarded trace directory left after recorder stop
+failed. Finalization skipped artifact cleanup on any stop exception, including
+when the owned recorder had already exited (such as after forced termination).
+The fix removes discarded files only after confirmed recorder exit and preserves
+the failed state/reason; a possibly live recorder still retains its directory for
+retry. Storage-limit cleanup retains its existing behaviour.
+
+Regression coverage proves both the live-writer safety case and shutdown after
+stop failure with confirmed exit. The latter failed before the fix and passed
+afterward. The complete simulator trace regression and `npm run verify` passed. The
+original shutdown deadline and assertions were unchanged. The repaired run
+established tap-to-Done via a fresh UI-tree assertion, 59 exported sample rows,
+cancel/expiry/stale-ID handling, server shutdown directory removal and complete
+owned trace/fixture cleanup. It used the documented test-owned compatibility
+companion; the default idb/Xcode HID limitation remains separate. The baseline `MCP_READINESS_DEVICE=emulator-5554 npm run test:device` suite also
+passed, with optional fixture skips reported separately. The full affected iOS
+trace smoke was run explicitly above rather than inferred from the baseline
+suite. The test-owned companion/alias was removed and simulator shutdown restored.
+
+Logs: `/tmp/ios-shutdown-fixed-device.log`,
+`/tmp/ios-shutdown-fixed-evidence.json`, `/tmp/ios-shutdown-verify.log`,
+`/tmp/ios-shutdown-device-suite.log`.
+Existing readiness verification edits in spec 033 and debugger device tests are
+preserved separately; no physical-device operations are needed for this repair.

package/docs/specs/031-ios-system-traces/pr102-monitor-evidence.json

@@ -0,0 +1,22 @@
+{
+  "source": "built dist iOS sessions/native adapter; injected monitor failures, real Instruments capture",
+  "device": "F9243BAF-62A8-4990-8A99-17F527F56FDA",
+  "runtime": "v23.11.0",
+  "transient_recovery": {
+    "status": "PASS",
+    "injected_command_failures": 2,
+    "trace_id": "a979b090-3ebb-4a95-92d0-9060c8105d45",
+    "pid": 90191,
+    "sample_rows": 7,
+    "artifact_bytes": 10898587
+  },
+  "repeated_timeout": {
+    "status": "PASS",
+    "reason": "ACTION_TIMEOUT",
+    "cleanup": "complete"
+  },
+  "status": "PASS",
+  "build_sha256": "e735ac25c9b0065797b748934efa5f3fc977a538fffef50e464b31ca4603c64a",
+  "cleanup": "Owned captures stopped; fixture and host artifacts removed; simulator shutdown restored separately",
+  "simulator_restored_to_shutdown": true
+}

package/docs/specs/031-ios-system-traces/simulator-evidence.json

@@ -0,0 +1,47 @@
+{
+  "linked_baseline": "PASS; Ready asserted via built-server journey",
+  "journey": {
+    "status": "PASS",
+    "trace_id": "742664b0-c676-4fe8-9231-26cca3c41009",
+    "correlation_id": "5affcc93-6944-4b58-a4a9-0d6cd0a55954",
+    "ready_at_ms": 1793796042115,
+    "journey_submitted_at_ms": 1793796046237,
+    "outcome": "Done visible via journey UI-tree assertion",
+    "sample_rows": 70,
+    "artifact_bytes": 11961327,
+    "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",
+  "shutdown": "PASS; owned recording and partial directory removed",
+  "app_survived_cleanup": "PASS",
+  "status": "PASS",
+  "build_sha256": "48eee7b1f71403645ab301def8d83dd14585eec099b221f8ac4f6aaba0941282",
+  "runtime": "v23.11.0",
+  "device": "F9243BAF-62A8-4990-8A99-17F527F56FDA",
+  "server": {
+    "name": "mobile-debug-mcp",
+    "version": "0.35.0"
+  },
+  "physical_device": "UNRUN; unsupported initial matrix",
+  "native_failure_injection": "UNRUN on real target; deterministic unit tests separate",
+  "input_toolchain": "Explicit test companion via IDB_COMPANION; see investigation.md",
+  "cleanup": {
+    "trace_errors": [],
+    "fixture_removed": true,
+    "simulator_shutdown": false,
+    "host_artifacts_removed": true
+  },
+  "task_cleanup": {
+    "original_simulator_state": "Shutdown",
+    "restored_simulator_state": "Shutdown",
+    "fixture_absent": true,
+    "temporary_companion_stopped": true,
+    "temporary_framework_alias_removed": true,
+    "named_probe_artifacts_removed": true
+  }
+}

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

@@ -0,0 +1,135 @@
+# iOS system traces — proposed specification
+
+2026-11-04. **Approved** by the user's second “ok” in this chat, responding to
+the complete specification and implementation approval request.
+[Intent](intent.md) approved by the user's “ok” in this chat.
+Source: [issue #78](https://github.com/clivejefferies/mobile-debug-tools/issues/78).
+[Native investigation and limits](investigation.md).
+
+## Supported scope
+
+Extend the existing five system-trace tools with an Instruments backend on macOS
+with full Xcode. Initial supported combination: booted iOS simulator and Time
+Profiler, attached to an already running development app. Baseline is Xcode 27.2
+and iOS 26.4.1. Other versions require successful prerequisite checks and artifact
+validation; installed templates alone do not establish support.
+
+System Trace is discoverable but not enabled initially: the simulator probe did
+not establish scheduling data. Animation Hitches is unsupported on the tested
+simulator. Hangs is an instrument within Time Profiler here, not a selectable
+standalone template; do not promise detected hangs. Physical-device capture is
+explicitly unsupported in this initial release, with verification unrun because
+no device is available. Report pairing, Developer Mode, signing/profiling and
+symbol prerequisites as applicable setup guidance, never as completed checks.
+Expanding this matrix requires evidence and a specification revision.
+
+No host recording, all-processes mode, custom templates, app launching, automatic
+diagnosis, summaries, arbitrary queries, or public export API. Android retains
+its existing preset, inputs, results and verification requirements.
+
+## Tools and contracts
+
+Keep existing names and strict schemas. Extend capabilities and start inputs with
+optional `appId` (nonblank bundle identifier) and `template` enum
+`System Trace | Time Profiler | Animation Hitches | Hangs`. These fields are
+iOS-only; reject them on Android. iOS start requires explicit `deviceId` and
+`appId`; omitted template defaults to Time Profiler. Capabilities require explicit
+`deviceId` on iOS; `appId` optionally probes running-app readiness. Duration stays
+1,000–120,000 ms, default 30,000. Controls still accept only `traceId`.
+
+iOS capabilities return `backend:xctrace`, resolved simulator/device metadata,
+Xcode version, discovered templates, per-template support/reasons/coverage,
+prerequisite states (`available`, `missing`, `unknown`), and actionable recovery.
+Discovery starts no recording and grants no permissions. Distinguish unavailable
+tooling/target, unsupported matrix, app not running, permission failure and checks
+that only a recording can establish. Do not label unknown permissions as granted.
+
+Reuse session state, completion reasons, IDs, host bounds, cleanup and correlation
+fields. Extend result unions to iOS, `backend:xctrace`, and artifact
+`format:instruments` with absolute `.trace` path, recursive `size_bytes`, and
+`kind:directory|file`. Include pinned `app_id`, PID, executable identity,
+selected template, target type, warnings and validation result. Never return raw
+trace data. Unreached fields are null. Errors use existing MCP `isError` and
+TRACE_* codes; bounded reason/recovery values distinguish setup, permission,
+target disconnect, readiness, export and storage failures without raw stderr.
+
+Resolve bundle identity to one current executable/PID on the pinned simulator;
+ambiguous/missing identity fails. Always pass `--device <UDID>` and revalidate
+identity before starting. Do not retry against a different process/name, template,
+device or host. Exported target UUID, PID and template must match the session.
+
+## Lifecycle, limits and privacy
+
+Use uniquely owned mode-0700 temporary directories and fixed argument arrays.
+Spawn the recorder with `--time-limit`, unique output and unique
+`--notify-tracing-started` notification. Register an owned Darwin-notification
+listener before spawning; return recording only after that notification while
+the recorder remains live. Console “Starting recording” alone is insufficient.
+Notification helper availability is a prerequisite, never a silent fallback.
+
+Allow 35 seconds for readiness, 30 seconds for graceful stop/finalisation and
+30 seconds for validation. Bound every child process and cap captured diagnostic
+output. At requested duration, reconcile and finalise automatically. SIGINT only
+the session-owned recorder; after its grace deadline terminate that owned child
+and report failure/partial output. Never signal the app, by process name, or an
+unrelated Instruments recording. On server shutdown cancel owned sessions under
+one 10-second overall deadline; forced cleanup may leave an unreadable artifact
+and must report that. Crashes provide no cleanup guarantee; no restart-wide sweep.
+
+Share the existing one-session-per-device, four-active-session server limit across
+backends. Serialise controls; retain 100 terminal metadata records for ten minutes.
+Stale/other-server IDs fail. Completed controls are idempotent. Disconnect,
+premature recorder exit and journey failure have explicit outcomes; journey failure
+does not cancel capture. Retry validation only on an existing finalised owned
+bundle, never restart recording. Cancel removes owned partial output; completed
+artifacts remain user-managed.
+
+Poll recursive output size every second; stop/discard on exceeding 256 MiB per
+iOS session, reject starts with less than 1 GiB free in its output filesystem.
+Finalisation can temporarily overshoot the polling threshold: report this as a
+soft bound, reject oversized final output and remove it. No symlink traversal.
+Apply restrictive permissions recursively before returning validated output.
+Instruments may contain system-wide metadata, paths, symbols, logs and signposts
+despite app attachment. Disclose this in tool/skill documentation. No upload,
+telemetry or permission bypass, including `--no-prompt`. User handles any required
+OS permissions outside the tool.
+
+## Artifact and journey evidence
+
+Require successful recorder exit, nonempty bounded output, parseable
+`xctrace export --toc`, matching target/app/template metadata, expected
+`time-sample` schema and successful table export. Record row count, including zero;
+zero samples means no CPU sample evidence, not diagnosed inactivity. Do not call
+a failed recording valid merely because a readable partial bundle exists.
+Expose warnings and unavailable instruments; do not claim symbolication unless
+verified. Validation exports are private temporary data removed after validation.
+
+Keep `run_journey.systemTraceId` explicit. Validate active same-server,
+same-platform/same-UDID session before any journey input. Link journey and step
+evidence through existing trace context and correlation IDs. The trace pins the
+profiled app; journey actions retain their existing targeting semantics and may
+leave that app. Report that limitation. Duration expiry or stop during the journey
+means partial coverage. Host capture bounds and unknown device-clock alignment
+establish association only; no device markers or causal inference.
+
+## Acceptance and verification
+
+1. Capability matrix and rejected inputs are side-effect-free, with exact target
+   and actionable prerequisite reasons; unknown permissions stay unknown.
+2. Updated-server simulator Time Profiler start → existing fixture journey tapping
+   Show loader and asserting Done → stop yields matching IDs, target/app metadata,
+   notification-before-input evidence, readable bundle and exported sample rows.
+3. Deterministic checks cover stale/mismatched IDs preventing all input, ownership,
+   concurrency, expiry, cancellation, partial coverage, disconnect, identity races,
+   notification/start/stop/export/storage failures, retries and shutdown cleanup.
+4. Real simulator checks cover explicit stop, expiry, cancellation and failed
+   journey; unavailable physical/failure-injection evidence is separate from mocks.
+5. Existing Android traces and untraced journeys pass regression checks. Run
+   `npm run verify`, applicable `npm run test:device`, and focused updated-server
+   calls; report actual suite coverage and unrun platforms.
+
+Affected: trace sessions/adapters/types, schemas/registration/handlers, journey and
+evidence integration, shutdown, tests/goldens, tool docs, README, changelog and
+packaged usage skill. Main implementation risks remain notification readiness,
+reliable app identity resolution and finalisation deadlines; feasibility probes
+do not establish these acceptance criteria.