mobile-debug-mcp 0.35.0 → 0.36.0

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.

package/docs/specs/032-ios-runtime-debugger/evidence.json

@@ -0,0 +1,176 @@
+{
+  "date": "2026-11-04",
+  "status": "PASS",
+  "transport": "MCP stdio",
+  "runtime": "v23.11.0",
+  "deviceId": "F9243BAF-62A8-4990-8A99-17F527F56FDA",
+  "server_sha256": "6a00a33d994a449ecbb54d5dbf894780f48a1c0e5a89fc871b91dd7048f4ecdc",
+  "source_sha256": "295ff0f30f5670530f9cdd7073b958917c1c574ccca9c7b921e295d0d902b699",
+  "xcode": "Xcode 27.2\nBuild version 27B52",
+  "lldb": "lldb-2103.0.34.407\nApple Swift version 6.4.2 (swiftlang-6.4.2.1.9 clang-2100.4.1.1)",
+  "fixture": "test/fixtures/ios-debugger-app/Main.swift",
+  "fixture_triggers": "Atomic command file; installed idb HID backend unavailable; not proof of successful MCP tap injection",
+  "extended_pause_expiry": true,
+  "process_exit": true,
+  "server_shutdown_recovery": true,
+  "tests_sha256": "37fbda265b5735b1b826aa448aa937359c45db0e55f8f1998a169b1aa3073acc",
+  "observations": [
+    {
+      "reason": "breakpoint",
+      "line": 49,
+      "method": "DebuggerFixture.Controller.calculate() -> ()"
+    },
+    {
+      "reason": "step",
+      "line": 8,
+      "method": "DebuggerFixture.helper(Swift.Int) -> Swift.Int"
+    },
+    {
+      "reason": "step",
+      "line": 9,
+      "method": "DebuggerFixture.helper(Swift.Int) -> Swift.Int"
+    },
+    {
+      "reason": "step",
+      "line": 49,
+      "method": "DebuggerFixture.Controller.calculate() -> ()"
+    },
+    {
+      "reason": "breakpoint",
+      "line": 20,
+      "method": "(1) suspend resume partial function for DebuggerFixture.AsyncWork.calculate(Swift.Int) async -> Swift.Int"
+    },
+    {
+      "reason": "breakpoint",
+      "line": 21,
+      "method": "(3) suspend resume partial function for DebuggerFixture.AsyncWork.calculate(Swift.Int) async -> Swift.Int"
+    },
+    {
+      "reason": "breakpoint",
+      "line": 20,
+      "method": "(1) suspend resume partial function for DebuggerFixture.AsyncWork.calculate(Swift.Int) async -> Swift.Int"
+    },
+    {
+      "reason": "step",
+      "line": 21,
+      "method": "(3) suspend resume partial function for DebuggerFixture.AsyncWork.calculate(Swift.Int) async -> Swift.Int"
+    },
+    {
+      "reason": "breakpoint",
+      "line": 66,
+      "method": "(3) suspend resume partial function for closure #1 () async -> () in DebuggerFixture.Controller.startCancellation() -> ()"
+    },
+    {
+      "reason": "breakpoint",
+      "line": 49,
+      "method": "DebuggerFixture.Controller.calculate() -> ()"
+    },
+    {
+      "reason": "breakpoint",
+      "line": 49,
+      "method": "DebuggerFixture.Controller.calculate() -> ()"
+    }
+  ],
+  "locals": [
+    [
+      {
+        "name": "known",
+        "type": "Swift.Int",
+        "value": "41"
+      }
+    ],
+    [
+      {
+        "name": "seed",
+        "type": "Swift.Int",
+        "value": "42"
+      },
+      {
+        "name": "known",
+        "type": "Swift.Int",
+        "value": "42"
+      }
+    ],
+    [
+      {
+        "name": "seed",
+        "type": "Swift.Int",
+        "value": "42"
+      },
+      {
+        "name": "known",
+        "type": "Swift.Int",
+        "value": "42"
+      },
+      {
+        "name": "after",
+        "type": "Swift.Int",
+        "value": "43"
+      }
+    ],
+    [
+      {
+        "name": "cancelled",
+        "type": "Swift.Bool",
+        "value": "true"
+      }
+    ]
+  ],
+  "async_boundary_step": {
+    "expected_line": 21,
+    "observed": {
+      "source_file": "test/fixtures/ios-debugger-app/Main.swift",
+      "line": 21,
+      "method_name": "(3) suspend resume partial function for DebuggerFixture.AsyncWork.calculate(Swift.Int) async -> Swift.Int",
+      "class_name": null
+    }
+  },
+  "assertions": [
+    "Exact source binding and pending source creation",
+    "Known primitive locals",
+    "Into/over/out",
+    "Stop/frame stale rejection",
+    "Paused tap rejected before dispatch",
+    "Paused readiness without UI acquisition",
+    "Cancelled event wait preserves session",
+    "Before/after await values and nested async child",
+    "Step over await reaches after-await source line",
+    "Task cancellation and fresh Task cancelled UI",
+    "Real 60-second pause expiry and fresh result UI",
+    "Target self-exit, disconnected state and complete cleanup",
+    "Idempotent detach with no remaining resources",
+    "Server shutdown while paused then independent UI recovery"
+  ],
+  "unrun": [
+    "physical iOS devices",
+    "other Xcode/Swift versions",
+    "optimized apps",
+    "installed/published package",
+    "forced host termination",
+    "real device disconnect",
+    "live idle/absolute expiry",
+    "late-loaded-image binding"
+  ],
+  "scope": "Focused real MCP iOS simulator debugger journey, including extended pause expiry",
+  "repository_verification": {
+    "status": "PASS",
+    "unit_files": 96,
+    "command": "npm run verify"
+  },
+  "broader_device_suite": {
+    "status": "FAIL",
+    "observations": [
+      "Initial Android interaction SDK timeout; isolated unchanged retry passed",
+      "Retry failed Android Perfetto shutdown-artifact assertion; isolated baseline and current checks passed"
+    ],
+    "root_cause": "unestablished",
+    "full_suite_pass_claimed": false
+  },
+  "cleanup": {
+    "ios_simulator": "restored to initial shutdown state",
+    "swift_fixture_build_directories_remaining": 0,
+    "owned_adb_forwards_remaining": 0,
+    "owned_perfetto_artifacts_remaining": 0,
+    "unrelated_installed_fixtures": "preserved"
+  }
+}

package/docs/specs/032-ios-runtime-debugger/intent.md

@@ -0,0 +1,38 @@
+# iOS runtime debugger — intent
+
+- Source: [issue #70](https://github.com/clivejefferies/mobile-debug-tools/issues/70), and the user's 2026-11-04 request to take the next Ready ticket with Android-equivalent functionality, including async debugging.
+- Originator: user in this chat.
+- Captured: 2026-11-04.
+- Status: intent approved by the user's “ok” on 2026-11-04 in response to the scope and approval request in this chat. Specification also approved in this chat on 2026-11-04; see spec.md. Issue #70 matches the roadmap and current branch; Ready-column membership could not be checked because GitHub authentication lacks `read:project`.
+
+## Problem and outcome
+
+MCP clients can debug Android development apps but lack equivalent iOS runtime
+inspection. Add an LLDB-backed debugger for iOS simulator development apps,
+reusing the existing debugger tools and session/evidence conventions where
+appropriate. Support attach, source breakpoints and events, bounded stacks and
+shallow locals, stepping, resume and detach, with explicit capabilities and
+actionable setup failures.
+
+## Async parity and success
+
+Verify a deterministic Swift concurrency fixture with source stops and useful
+locals before and after `await`, resumed execution, nested task work, task
+cancellation and application recovery. Assess stepping across suspension and
+report its observed limits. Android's existing coroutine assessment establishes
+execution inspection, not reconstruction of suspended tasks or logical async
+stacks; distinguish those capabilities explicitly on iOS too.
+
+Preserve stale-reference rejection, pause-aware interaction guards, bounded
+waits/cancellation, session isolation, expiry and owned cleanup. Prove the journey
+through actual MCP calls and independent fixture outcomes, and retain Android
+regression coverage. Report unavailable environments honestly.
+
+## Constraints and questions
+
+Physical-device support follows separately. Evaluation, mutation, arbitrary LLDB
+commands and generic suspended-task reconstruction are excluded from this initial
+scope. Inspect LLDB/Xcode support for async frames and stepping before proposing
+the exact capability contract. Debug values remain bounded and sensitive; avoid
+persisting app data in public evidence. Specification approval follows intent
+acceptance under the repository process.

package/docs/specs/032-ios-runtime-debugger/plan.md

@@ -0,0 +1,95 @@
+# iOS runtime debugger — implementation and verification
+
+Scope: [intent](intent.md) and [specification](spec.md), both approved by the user
+on 2026-11-04. Use the repository MCP Builder and Test Authoring skills.
+
+## Implementation
+
+- [x] Establish LLDB Python loading and explicit simulator/process attribution.
+- [x] Add structured LLDB worker, safe inspection, exact breakpoints and watchdogs.
+- [x] Reuse session lifecycle with platform-specific native/worker configuration;
+      update schemas, dispatch, diagnostics, guards and readiness.
+- [x] Add deterministic Swift simulator fixture and MCP runtime/async journeys.
+- [x] Add contract, identity, lifecycle and guard regression tests; update tool
+      compatibility golden only for approved schema changes.
+- [x] Align debugger guide, tool reference, README, changelog and packaging.
+- [x] Review diff, execute required verification and record actual results below.
+      Full-suite success remains unestablished; see the failed checks below.
+
+## Verification matrix
+
+| Spec criterion | Check |
+| --- | --- |
+| Core runtime flow | `MCP_IOS_DEBUGGER_DEVICE=<UDID> node --import tsx test/device/automated/debugger/runtime.ios.test.ts` through built stdio server |
+| Async/cancellation | Same journey with controlled before/after-await values, nested work, cancellation and fresh UI assertions; separate step-boundary result |
+| Identity, failure, references and guards | Focused `test/unit/debugger/*.test.ts`, simulator invalid PID/foreign target, stale frame/stop, guarded input/readiness, event cancellation and detach |
+| Expiry and shutdown | Worker watchdog unit checks plus real pause expiry and server EOF cleanup in fixture journey |
+| Contract/Android regression | `npm run verify`; existing runtime, Kotlin and coroutine Android MCP checks on explicit emulator |
+| Broader device compatibility | `npm run test:device` with selected targets; report the actual covered platforms and skipped prerequisites |
+
+Required: Node 22+, installed Xcode 27.2/Swift 6.4.2/LLDB 2103.0.34.407,
+simulator runtime, development fixture compiled with debug metadata and no
+optimisation. Android regressions require existing JDK/SDK/Kotlin dependencies.
+No physical-device iOS support is claimed. Hosted CI is separate from local checks.
+
+Select existing simulator F9243BAF-62A8-4990-8A99-17F527F56FDA (iPhone 17 Pro,
+iOS 26.4), initially shut down. Boot it for the fixture; preserve existing apps
+and settings, install/remove only fixture-owned app/build files, detach owned
+debuggers, and restore the initial shutdown state. Record exact server/fixture
+hashes, observed stops/locals, independent UI state and cleanup. Simulator access
+requires outside-sandbox native commands; the authorised inventory read succeeded.
+If a prerequisite is unavailable, retain the acceptance criterion and record a
+concrete blocker. Do not treat mock/native readiness checks as live verification.
+
+## Results
+
+- **PASS** `npm run verify`: lint/quality/architecture, build, all 96 unit files,
+  plugin consistency, Node 23.11.0. Log `/tmp/ios-debugger-final-verify.log`.
+- **PASS** `MCP_IOS_DEBUGGER_DEVICE=F9243BAF-62A8-4990-8A99-17F527F56FDA MCP_IOS_DEBUGGER_EXTENDED=1 node --import tsx test/device/automated/debugger/runtime.ios.test.ts`.
+  Exact stable-build hash, stops, locals and asserted cleanup/recovery are in
+  [evidence.json](evidence.json). No HID success is inferred from fixture control.
+- **PASS** focused Android runtime, Kotlin locals and coroutine MCP regressions
+  using the existing fixture/compiler dependencies. The broader suite also reran
+  the final Android runtime debugger successfully.
+- **PASS** unchanged standalone iOS screenshot, log and UI-tree smoke checks.
+- **PASS** package dry-run contents, plugin generation/consistency and diff/link
+  checks. No publication or installed-package verification occurred.
+- **FAIL** broader `ADB_PATH=/Users/clivejefferies/Library/Android/sdk/platform-tools/adb MCP_DEBUGGER_DEVICE=emulator-5554 npm run test:device`: initial Android
+  interaction request timeout; focused unchanged retry passed. The full-suite
+  retry passed that branch and both-platform observations/correlated evidence,
+  then failed Android Perfetto active-shutdown artifact removal. The isolated
+  Perfetto check passed on both unchanged HEAD and current build. These failures
+  remain unreproduced and unexplained; no full-suite pass is claimed.
+- Full-suite opt-in Kotlin/coroutine/iOS debugger checks were **UNRUN** in that
+  invocation; each passed its separate focused run above. iOS system tracing was
+  **UNRUN** (no `IOS_SYSTEM_TRACE_DEVICE` supplied); it is outside this feature.
+- **PASS** owned cleanup: no MCP device trace files or ADB forwards remained;
+  debugger/coroutine packages and Swift build directories removed. Unrelated
+  fixtures preserved; iOS simulator restored to shutdown; Android emulator left
+  running. Temporary baseline source/build copy removed.
+
+See [verification report](report.md) for evidence boundaries, resolved findings,
+unrun variants and original failed observations.
+
+
+## PR #103 review repair
+
+- [x] Cache shared iOS preparation and reset rejected preparation for retry.
+- [x] Add fake-toolchain coverage for concurrent reuse, retry and worker creation.
+- [x] Check real Xcode cached preparation and rerun the focused iOS MCP journey.
+- [x] Complete quiet repository verification (97 unit files); publish the repair to PR #103.
+
+See the [report follow-up](report.md#pr-103-preparation-cache-follow-up--2026-11-04)
+for exact evidence and retained broader-suite limitations.
+
+
+## PR #103 stored-handle pause guard repair
+
+- [x] Validate guard targets through the stored-handle execution lookup.
+- [x] Cover omitted/partial hints, known/racing pauses, platform/device isolation,
+      and explicit mismatches; prove regression detects the original route.
+- [x] Run `npm run verify` (98 unit files) and the updated real iOS MCP journey.
+- [x] Restore fixture/device state and prepare the narrow repair for PR publication.
+
+The finding is in an outside-diff review summary, with no new inline thread to
+resolve. See the [report](report.md) for exact evidence and retained limitations.

package/docs/specs/032-ios-runtime-debugger/report.md

@@ -0,0 +1,205 @@
+# iOS runtime debugger verification — issue #70
+
+Date: 2026-11-04. Scope: [approved specification](spec.md).
+Implementation: existing eleven MCP debugger tools gain the optional simulator
+LLDB backend; Android remains on JDI. This is local source/build verification,
+not hosted CI, an installed package, a publication or physical-device evidence.
+
+## Environment and method
+
+macOS, Node 23.11.0 (repository requires >=22; hosted CI selects Node 22),
+Xcode 27.2/27B52, LLDB 2103.0.34.407 and Swift 6.4.2. Simulator:
+F9243BAF-62A8-4990-8A99-17F527F56FDA, iPhone 17 Pro, iOS 26.4.
+The disposable Swift fixture uses `-g -Onone`, targeting iOS 18 simulator.
+
+The runner communicates with a freshly built stdio MCP server. It checks actual
+source stops, stack frames and synthetic known-value locals; independent fresh
+MCP UI-tree assertions establish completion/cancellation and recovery. It does
+not infer logical task identity from opaque thread IDs or task/thread names.
+
+Installed idb can read UI trees but cannot inject HID with this Xcode: its
+SimulatorKit framework path is absent. Therefore fixture actions use a private
+command file, delivered by atomic rename and handled by the fixture main-loop
+timer. This is independent fixture control, not proof of successful MCP tap
+injection. Paused MCP taps are checked for rejection before dispatch. No
+production app instrumentation, source evaluation or security changes are used.
+
+## Evidence and results
+
+The final stable-build simulator journey **PASS**ed with real pause expiry enabled.
+[Compact evidence](evidence.json) records the exact server/fixture/test hashes,
+source stops and bounded synthetic values. Recomputing the final source/build hash
+matched the runtime fingerprint. Log: `/tmp/ios-debugger-final.log`.
+
+| Check | Result |
+| --- | --- |
+| Exact source binding; pending source; non-executable line rejection | PASS |
+| Core stack/locals and into/over/out | PASS: known=41, fresh result=42 UI |
+| Pause guard/readiness and stale references | PASS |
+| Cancelled event wait and usable running session | PASS |
+| Before/after await with nested async child and actor/main-actor transitions | PASS: known=42, after=43, fresh Async result 44 UI |
+| Step over await | PASS: source line 20 to line 21 in the resumed partial function |
+| Task cancellation | PASS: cancelled=true and fresh Task cancelled UI |
+| Real 60-second pause expiry | PASS: pause_limit, complete cleanup and fresh result UI |
+| Target process exit | PASS: disconnected state, complete cleanup and fixture relaunch |
+| Idempotent detach and server shutdown while paused | PASS: no remaining resources; independent fresh result UI |
+
+`npm run verify` **PASS**: lint/structural/architecture checks, TypeScript build,
+all 96 unit files and generated plugin consistency. Log:
+`/tmp/ios-debugger-final-verify.log`. The portable usage skill and generated Cursor
+copy now describe the advertised iOS backend; this does not install/update a
+connected or pinned published server.
+
+The broader device suite passed the final Android debugger regression, then
+**FAIL**ed on an Android interaction SDK request timeout (120000 ms); its original
+log does not identify the call. A focused assertion-identical retry with tool-name
+and elapsed-time logging **PASS**ed every call (approximately 47 seconds total).
+The timeout was not reproduced and its cause is unknown; no assertion, timeout,
+retry policy or interaction implementation was changed. Original and retry logs:
+`/tmp/ios-debugger-device-suite.log` and
+`/tmp/ios-debugger-interaction-retest.log`. The unchanged full-suite retry passed the Android debugger/interaction checks and
+both-platform screenshot/log/tree/correlated-evidence checks, then **FAIL**ed the
+last Android Perfetto active-shutdown cleanup assertion (one owned capture file
+still existed). Log: `/tmp/ios-debugger-device-suite-retry.log`.
+
+The same isolated Perfetto test then **PASS**ed on both unmodified HEAD
+`8bafc318a6342cf4585621d2108353836d40f72d` (archived and compiled in a temporary
+copy using the same dependencies) and the current build. Logs:
+`/tmp/ios-debugger-trace-baseline.log`, `/tmp/ios-debugger-trace-current.log`.
+This does not establish the original timeout/cleanup cause or prove it fixed.
+No tracing source, assertion or deadline was changed; no full device-suite pass
+is claimed. The failed check's exact owned artifact was removed through the
+existing identity-checking trace adapter. Final checks found no MCP capture files
+or ADB forwards. Debugger/coroutine test packages and Swift build directories were
+removed; unrelated installed fixtures were preserved. The iOS simulator was
+returned to its initial shutdown state; the Android emulator remains running.
+
+Independent unchanged iOS screenshot, log and UI-tree smoke checks **PASS**ed.
+Log: `/tmp/ios-debugger-ios-observations.log`. These establish observation delivery
+and structure, not a layout claim or successful HID input.
+
+The initial Android runtime, Kotlin locals and coroutine MCP regressions passed
+on emulator-5554, Android 16/API 36. Kotlin/stdlib 2.0.21, coroutines 1.9.0 and
+fixture JDK 17.0.11 used existing cached dependencies and `/tmp/pr96-kotlinc`.
+The debugger uses its ordinary Android Studio JBR discovery. Raw local logs:
+`/tmp/ios-debugger-android-regression.log`,
+`/tmp/ios-debugger-kotlin-regression.log`,
+`/tmp/ios-debugger-coroutine-regression.log`.
+
+`npm pack --dry-run --json` and explicit contents assertions passed for all three
+LLDB Python modules and compiled iOS backend modules. CI packaging assertions now
+cover these resources. This does not establish installed-package loading.
+
+## Findings resolved during development
+
+- Ignore internal LLDB transitions without stopped-thread evidence; consume LLDB
+  process events before reading public process/thread snapshots.
+- Keep fixture variables live across await. The original constant's scope had no
+  location in a resume partial function; requiring its later use preserved actual
+  `known=42` inspection. Assertions were retained, not replaced by availability.
+- Use LLDB's invalid-line sentinel for the error-reporting StepInto overload;
+  line zero is not that sentinel. Check native step errors before acknowledging.
+- Normalize Swift Bool static storage to textual true/false; never evaluate a
+  getter, formatter, expression or object description.
+- Preserve known suspension when a stale/invalid step is rejected. Diagnostic
+  lifecycle fallbacks cannot bypass pause guards.
+- Bound and reuse frame references; preserve cleanup uncertainty after lost worker
+  or process handles instead of treating process closure as confirmed release.
+- Classify signals/exceptions separately from completed steps. A synchronous
+  `simctl terminate` probe timed out while attached; the fixture now exits itself
+  to test actual process-exit cleanup without blocking the runner on a signal stop.
+- URL-based fixture control encountered a system confirmation. The simulator was
+  rebooted to clear this fixture-created prompt; URL control was removed. Atomic
+  file delivery avoids the timer observing a partially written command.
+
+These failed development observations remain distinct from successful reruns;
+none is represented as evidence that all environments or timings are covered.
+
+## Limits and review
+
+Physical iOS devices, other Xcode/Swift/runtime versions, optimized builds,
+installed/published-package operation, real device disconnect, forced host kill,
+long idle/absolute expiry and a late-loaded-image binding journey remain unrun.
+Pause expiry is checked live; idle/absolute expiry logic also has deterministic
+worker/host unit coverage. Pending source creation is checked independently.
+
+Swift strings and other aggregate locals expose type/opaque reference summaries;
+standard supported numeric/bool wrappers use static storage. Missing debug values
+remain explicitly unavailable. No suspended-task enumeration or complete logical
+async-stack reconstruction is exposed. Async stepping evidence is the tested
+step-over-await route, not every Swift concurrency construct.
+
+Focused review covers target membership/start identity, source resolution, strict
+schema/dispatch parity, bounded IPC/inspection, stop epochs, diagnostic privacy,
+platform guards, expiry and owned teardown. Android contract compatibility remains
+covered by its existing fixture and unit tests; iOS scope is simulator-only.
+
+
+## PR #103 preparation-cache follow-up — 2026-11-04
+
+[Review comment](https://github.com/clivejefferies/mobile-debug-tools/pull/103#discussion_r4470121366)
+identified duplicated prerequisite subprocesses during attach. Preparation now
+shares its in-flight/successful promise per server process and clears a rejected
+promise, preserving platform checks, readiness validation and worker configuration.
+No tool schema, timeout or inspection behaviour changes.
+
+- **PASS** isolated fake-toolchain regression: concurrent calls share preparation,
+  failure permits retry, successful configuration is reused, and worker creation
+  adds no extra prerequisite probes.
+- **PASS** real Xcode preparation followed by cached reuse within a 100 ms budget;
+  no app was attached by that probe.
+- **PASS** focused real iOS MCP runtime/async/cancellation/process-exit/shutdown
+  journey on the same simulator/toolchain. Build fingerprint:
+  `0200deeb0cff9f04b54ed929258ebd19185c8be86e2badb6cdcbfa21f798fdb1`.
+  Source fingerprint remains `295ff0f30f5670530f9cdd7073b958917c1c574ccca9c7b921e295d0d902b699`.
+  Log: `/tmp/pr103-cache-ios.log`. Extended pause expiry was not repeated for
+  this preparation-only fix; the earlier extended evidence remains above.
+- **PASS** quiet `npm run verify`: lint/quality/architecture, build, all 97 unit
+  files and plugin consistency. Log: `/tmp/pr103-cache-verify-final.log`.
+  A prior run alongside native testing failed the unchanged conditional-action
+  timing assertion. Its isolated retry passed, as did the quiet full verification;
+  no assertion or timeout was modified. Original/retry logs:
+  `/tmp/pr103-cache-verify.log`, `/tmp/pr103-cache-conditional-retest.log`.
+
+The regression child loads its TypeScript toolchain before platform emulation,
+so the host retains its native compiler selection on Linux. This test-only ordering
+adjustment also passed all 97 files in `npm run verify` (log:
+`/tmp/pr103-cache-portable-verify.log`). The preparation fix was published in
+`f00e9fd`, and its review thread was resolved; both hosted unit-test runs passed
+that commit. Later PR-head checks must be assessed separately.
+
+The broader device-suite failures above remain separate; this fix does not claim
+that their causes were established or corrected. Simulator shutdown was restored.
+
+
+## PR #103 stored-handle guard follow-up — 2026-11-04
+
+[Outside-diff review finding](https://github.com/clivejefferies/mobile-debug-tools/pull/103#pullrequestreview-5772655824):
+`tap_element` could execute on its stored iOS handle's device while the central
+guard selected Android when platform hints were omitted. The guard now obtains
+its target through the same handle/platform/device validation used by execution.
+Other tool defaults remain unchanged; explicit conflicting hints still reject
+handle use rather than retargeting input.
+
+- **PASS** regression using real handle creation with mocked device/UI/input
+  boundaries: omitted/partial hints select the stored iOS device, known pauses
+  prevent UI reads/input, a racing pause prevents native dispatch, and unrelated
+  platforms/devices remain usable. Mismatched and missing handles retain rejection.
+- **PASS** mutation check: restoring the original Android-default guard route
+  makes that regression fail; fixed source was restored before verification.
+- **PASS** `npm run verify`: lint/quality/architecture, build, all 98 unit files,
+  and plugin consistency. Log: `/tmp/pr103-handle-verify.log`.
+- **PASS** updated real simulator MCP journey: obtain an iOS handle while running,
+  stop at a source breakpoint, then call `tap_element` with only that handle and
+  controls, omitting both platform and device ID. Observed `DEBUGGER_PAUSED`,
+  `delivery_status: not_delivered`, `dispatch_started: false`, and the correct
+  iOS debugger/device metadata. This proves pause rejection, not successful HID
+  injection. The existing core/async/cancellation/process-exit/shutdown journey
+  also passed on the same Xcode/LLDB/Swift/runtime matrix.
+
+Native build fingerprint:
+`28e56d77b9ba4caad778c223306609c3bb284b210b1ea996b927aca47134cf55`.
+Log: `/tmp/pr103-handle-ios.log`. No fixture source change or timeout/assertion
+weakening was needed. Device tests were run after repository verification to keep
+the checks separate. The fixture was removed and simulator shutdown restored.
+The earlier broader-suite limitations remain recorded above.