mobile-debug-mcp 0.35.0 → 0.36.0

package/dist/server/schemas/system-trace-schema.js

@@ -1,17 +1,22 @@
 import { z } from 'zod';
-const target = { platform: z.enum(['android', 'ios']), deviceId: z.string().min(1).optional() };
-export const traceTargetSchema = z.object(target).strict();
-export const traceStartSchema = z.object({ ...target, durationMs: z.number().int().min(1000).max(120000).default(30000) }).strict();
+const target = { platform: z.enum(['android', 'ios']), deviceId: z.string().min(1).optional(), appId: z.string().regex(/^[a-zA-Z0-9._-]+$/).optional(), template: z.enum(['System Trace', 'Time Profiler', 'Animation Hitches', 'Hangs']).optional() };
+const validTarget = (value) => value.platform === 'ios' ? !!value.deviceId : value.appId === undefined && value.template === undefined;
+export const traceTargetSchema = z.object(target).strict().refine(validTarget);
+export const traceStartSchema = z.object({ ...target, durationMs: z.number().int().min(1000).max(120000).default(30000) }).strict().refine(validTarget).refine(value => value.platform !== 'ios' || !!value.appId);
 export const traceControlSchema = z.object({ traceId: z.string().uuid() }).strict();
-const properties = { platform: { type: 'string', enum: ['android', 'ios'] }, deviceId: { type: 'string', minLength: 1 } };
+const properties = { platform: { type: 'string', enum: ['android', 'ios'] }, deviceId: { type: 'string', minLength: 1 }, appId: { type: 'string', minLength: 1, pattern: '^[a-zA-Z0-9._-]+$', description: 'iOS only: running development app bundle identifier; required for iOS start.' }, template: { type: 'string', enum: ['System Trace', 'Time Profiler', 'Animation Hitches', 'Hangs'], description: 'iOS only. Default Time Profiler; initial simulator support is Time Profiler only.' } };
+const platformRules = (start) => ({ oneOf: [
+        { properties: { platform: { const: 'android' } }, not: { anyOf: [{ required: ['appId'] }, { required: ['template'] }] } },
+        { properties: { platform: { const: 'ios' } }, required: start ? ['deviceId', 'appId'] : ['deviceId'] }
+    ] });
 export const systemTraceTools = [
-    { name: 'get_system_trace_capabilities', description: 'Probe Android Perfetto prerequisites without recording. Device-wide system tracing is optional; iOS is unsupported.',
-        inputSchema: { type: 'object', additionalProperties: false, required: ['platform'], properties } },
-    { name: 'start_system_trace', description: 'Start bounded Android Perfetto recording, returning an owned trace_id. Run an existing journey with systemTraceId, then stop to retrieve a local artifact or cancel to discard. Device-wide traces may contain sensitive system annotations; no upload.',
-        inputSchema: { type: 'object', additionalProperties: false, required: ['platform'], properties: { ...properties, durationMs: { type: 'integer', minimum: 1000, maximum: 120000, default: 30000 } } } },
+    { name: 'get_system_trace_capabilities', description: 'Probe Android Perfetto or iOS Instruments prerequisites without recording. iOS requires explicit booted simulator deviceId; reports template matrix and unknown profiling permissions.',
+        inputSchema: { type: 'object', additionalProperties: false, required: ['platform'], properties, ...platformRules(false) } },
+    { name: 'start_system_trace', description: 'Start bounded Android Perfetto or iOS simulator Time Profiler recording, returning an owned trace_id after readiness. iOS requires explicit deviceId and running appId. Run an existing journey with systemTraceId, then stop to retrieve a local artifact or cancel to discard. Traces can contain sensitive system metadata, logs and paths; local user-managed retention, no upload.',
+        inputSchema: { type: 'object', additionalProperties: false, required: ['platform'], properties: { ...properties, durationMs: { type: 'integer', minimum: 1000, maximum: 120000, default: 30000 } }, ...platformRules(true) } },
     ...['get_system_trace_status', 'stop_system_trace', 'cancel_system_trace'].map(name => ({ name,
         description: name === 'get_system_trace_status' ? 'Reconcile an owned trace and retrieve its state; finalise duration-completed capture.' :
-            name === 'stop_system_trace' ? 'Stop owned capture gracefully and retrieve a local Perfetto artifact. Retry after a transfer/cleanup failure.' : 'Stop owned capture and discard partial files. Already completed local artifacts are retained.',
+            name === 'stop_system_trace' ? 'Stop owned capture gracefully and retrieve a local Perfetto file or validated Instruments .trace bundle. Retry after a transfer/cleanup failure.' : 'Stop owned capture and discard partial files. Already completed local artifacts are retained.',
         inputSchema: { type: 'object', additionalProperties: false, required: ['traceId'], properties: { traceId: { type: 'string', format: 'uuid' } } }
     }))
 ];

package/dist/server-core.js

@@ -6,7 +6,7 @@ import { handleToolCall } from './server/handlers/tool-handlers.js';
 export { wrapResponse, toolDefinitions, handleToolCall };
 export const serverInfo = {
     name: 'mobile-debug-mcp',
-    version: '0.35.0'
+    version: '0.36.0'
 };
 export function createServer() {
     const server = new Server(serverInfo, {

package/dist/server.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { debuggerSessions } from './debugger/sessions.js';
+import { debuggerSessions, iosDebuggerSessions } from './debugger/sessions.js';
 import { systemTraces } from './observe/system-trace.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createServer } from './server-core.js';
@@ -19,10 +19,10 @@ async function shutdown() {
     const deadline = setTimeout(() => { console.error('System trace shutdown cleanup timed out; owned device captures remain duration-bounded.'); process.exit(1); }, 10000);
     let exitCode = 0;
     try {
-        const [remaining, debuggers] = await Promise.all([systemTraces.shutdown(), debuggerSessions.shutdown()]);
-        if (debuggers.length) {
+        const [remaining, debuggers, iosDebuggers] = await Promise.all([systemTraces.shutdown(), debuggerSessions.shutdown(), iosDebuggerSessions.shutdown()]);
+        if ((debuggers.length + iosDebuggers.length)) {
             exitCode = 1;
-            console.error('Debugger shutdown cleanup incomplete', debuggers.map(s => s.cleanup));
+            console.error('Debugger shutdown cleanup incomplete', [...debuggers, ...iosDebuggers].map(s => s.cleanup));
         }
         if (remaining.length) {
             exitCode = 1;

package/dist/utils/ios/utils.js

@@ -1,3 +1,4 @@
+import { checkDebuggerGuard } from '../../debugger/guard.js';
 import { remainingBudget } from '../operation-budget.js';
 import { execFile, spawn, execSync, spawnSync } from "child_process";
 import { promises as fsPromises } from 'fs';
@@ -94,6 +95,7 @@ export function execCommand(args, deviceId = "booted") {
     return new Promise((resolve, reject) => {
         // Use spawn for better stream control and consistency with Android implementation
         const budgetMs = remainingBudget();
+        checkDebuggerGuard();
         const child = spawn(getXcrunCmd(), args);
         let stdout = '';
         let stderr = '';
@@ -135,6 +137,7 @@ export function execCommandWithDiagnostics(args, deviceId = "booted") {
     const DEFAULT_XCRUN_LOG_TIMEOUT = parseInt(process.env.MCP_XCRUN_LOG_TIMEOUT || '', 10) || 30000;
     const DEFAULT_XCRUN_CMD_TIMEOUT = parseInt(process.env.MCP_XCRUN_TIMEOUT || '', 10) || 60000;
     const timeoutMs = budgetMs || (args.includes('log') ? DEFAULT_XCRUN_LOG_TIMEOUT : DEFAULT_XCRUN_CMD_TIMEOUT);
+    checkDebuggerGuard();
     const res = spawnSync(getXcrunCmd(), args, { encoding: 'utf8', timeout: timeoutMs });
     const runResult = {
         exitCode: typeof res.status === 'number' ? res.status : null,

package/docs/CHANGELOG.md

@@ -8,7 +8,29 @@ and [tool reference](tools/TOOLS.md) for the current checkout.
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
-## Unreleased
+## [0.36.0]
+
+- Updated the agent plugin to `0.0.6`, pinned to MCP `0.36.0`.
+
+- Add an optional iOS simulator LLDB backend to the existing debugger tools,
+  including exact source-file breakpoints, bounded static inspection, stepping,
+  platform-scoped pause guards and owned cleanup. A separate Swift concurrency
+  fixture checks inspection around await, cancellation and recovery; verification
+  coverage is recorded in specification 032. Physical iOS devices remain unsupported.
+
+- Preserve iOS trace capture through isolated monitoring command failures; require
+  three consecutive non-definitive failures before discarding, while identity and
+  storage failures remain immediate and capture expiry still reconciles.
+
+- Add optional iOS simulator Time Profiler capture through Instruments, with explicit
+  device/app targeting, recording-start notification, local `.trace` validation,
+  journey evidence linkage and owned cleanup. Physical devices and other templates
+  remain unsupported in the initial matrix. Android tracing retains its preset.
+
+
+- Added plugin `0.0.5` Antigravity compatibility and a standalone distribution
+  export. Generated a Cursor-native package for its supported path variables,
+  and checked/refined installation instructions for all four clients.
 
 ## [0.35.0]
 

package/docs/agent-plugin-installation-verification.md

@@ -0,0 +1,39 @@
+# Agent plugin installation verification
+
+Checked 2026-11-02 for plugin 0.0.5 and published MCP 0.35.0. This record separates
+command/schema checks from installation and live device evidence.
+
+| Client | Evidence | Limit |
+| --- | --- | --- |
+| Codex CLI 0.166.0-alpha.5.1 | Marketplace-add and plugin-add syntax confirmed with installed CLI help and official docs; catalog paths checked by repository verification | No new Codex installation or agent journey performed |
+| Claude Code 2.1.285 | Native strict validation passes for the marketplace, compatibility manifest and complete plugin folder; shell command syntax confirmed | No new Claude Code installation or agent journey performed |
+| Cursor | Native package and catalog generated from the canonical skill; uses documented CURSOR_PLUGIN_ROOT; local-copy instructions preserve hidden files | Host loading in Cursor is unrun |
+| Antigravity CLI 1.4.12 | Standalone export passes strict validation with zero warnings; local install discovers one skill and one MCP server | An agent print-mode attempt was denied by plan-mode MCP policy; a narrowly permitted read-only attempt timed out, so no agent tool-call success is claimed |
+
+The Antigravity export contains native `plugin.json`, `mcp_config.json`, README,
+license, logo and the shared skill. It excludes foreign client manifests and
+Finder metadata. Export destinations must be new directories. Regression coverage
+checks inventory, canonical skill/license bytes and refusal to overwrite existing
+files. Cursor's generated skill/license are checked against their canonical
+sources by `npm run check:agent-plugin`.
+
+A separate SDK test launched the exact exported npx command from an expanded
+PLUGIN_DATA working directory. It connected to published MCP 0.35.0, discovered
+52 tools, selected emulator-5554 (Android 16/API 36), launched Settings and asserted
+a fresh UI tree contained a visible Settings-owned resource. **PASS**; this is an
+exported-config/device check, not an Antigravity agent interaction. Log:
+`/tmp/antigravity-published-mcp-check.log`. The emulator remains running.
+
+`npm run verify` **PASS**, all 91 unit files, including the exporter regression,
+lint/quality/architecture, build and plugin consistency. Native Antigravity strict
+validation and Claude strict validation also **PASS**. Markdown links and diff
+whitespace were checked. No production server code or dependencies changed.
+GitHub/local distribution does not require the optional Marketplace intake form;
+no application was submitted.
+
+## Primary documentation
+
+- [OpenAI plugin packaging](https://developers.openai.com/plugins/build/plugins)
+- [Claude Code installation](https://code.claude.com/docs/en/discover-plugins)
+- [Cursor plugins and local testing](https://cursor.com/docs/plugins)
+- [Antigravity plugin building and validation](https://antigravity.google/docs/build-plugins)

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,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`.

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
+  }
+}