mobile-debug-mcp 0.35.0 → 0.37.0

package/docs/specs/034-app-installation-status/plan.md

@@ -0,0 +1,73 @@
+# Implementation plan
+
+Intent and spec approved by user (“yes”, then “ok”) on 2026-11-05 in this chat.
+
+- [x] Add shared installation observations and bounded platform probes.
+- [x] Update inventory, system status, schema and selection diagnostics.
+- [x] Cover status semantics, targeting, serialization and failures with fake tooling.
+- [x] Align documentation and tool-definition fixture.
+- [x] Run focused tests, npm run verify and npm run test:device.
+- [x] Record Android installed/running, absent and no-context journeys; verify iOS separately.
+
+Acceptance 1–3: native probes against checkout/build, recording exact device and scope.
+Acceptance 2/4: deterministic unit tests with fake executable responses and selection fixtures.
+Acceptance 5: verify (lint/build/unit/plugin), device suite and focused updated-server calls.
+Node >=22 required; CI uses Node 22, additionally compiles/packages debugger workers;
+Android CI is manual. Local default is Node 23.11.0; inspect available Node 22.
+Android Pixel and emulator available; iOS simulator must be booted for conclusive checks.
+No installation or app lifecycle changes required. Existing operation deadlines cap probes.
+
+## Results (2026-11-05)
+
+Implementation complete on `bugfix/app-installed`, uncommitted. Intent/spec approval
+recorded in their documents. Shared bounded probes cover Android inventory and
+system status plus iOS simulator inventory. Schema/handler, serialization,
+selection diagnostics, compatibility fixture, guides and changelog are aligned.
+Startup healthcheck logging now safely handles the existing error-result variant
+with missing platform fields; making unknown installation fields optional exposed
+that union during TypeScript compilation.
+
+Native discovery showed Android `pm path` returns a silent nonzero exit for
+missing packages. Added a successful targeted package-list fallback, within the
+same deadline, to establish absence. Failed fallback remains unknown. This is an
+implementation refinement of the accepted installed/absent/unknown semantics.
+
+[Native evidence](native-evidence.json) records final MCP stdio calls, build hashes,
+per-device results, baseline reproduction and cleanup. Automated assertions over
+those saved calls passed. Physical Pixel 9 Pro (Android 17), emulator-5554
+(Android 16) and iPhone 17 Pro simulator (iOS 26.4) passed installation observations:
+
+- Android missing app context: unknown, no boolean; unchanged HEAD reproduced false.
+- Modul8 dev package: installed on both Android targets; emulator process PID 4064
+  was observed before device-suite execution (no claim of foreground readiness).
+- Nonexistent package: absent on both Android targets using successful fallback.
+- Safari installed and nonexistent bundle absent on the booted iOS simulator.
+- Multiple-device system status: per-device installed results, no global boolean.
+- Other unbooted simulators: unknown DEVICE_UNAVAILABLE, without attempted app queries.
+
+Focused fake-tool tests pass: installed/absent, missing/invalid context, failed and
+malformed queries, deadline timeout, per-device divergence, single/multiple system
+aggregation and iOS plist parsing (macOS). Selection tests protect unknown status
+and different-app isolation. Actual disconnected/unauthorized device failures
+were not induced; these paths use deterministic failed-query/unavailable coverage.
+The original agent request is unavailable; only the identified missing-context
+failure path was reproduced. Physical iOS remains unsupported.
+
+`npm run test:device`: PASS for executed checks (Android/iOS screenshots, logs,
+UI trees and correlated evidence; Android trace lifecycle). The runner explicitly
+reported coroutine/debugger, interaction/readiness fixtures and iOS tracing UNRUN
+where environment selectors/dependencies were unset. These are not installation
+coverage claims. Simulator restored to original Shutdown; suite leaves Android
+Settings foreground, changes no app data or security settings. Native installed
+checks and inventory do not launch or install apps.
+
+`npm run verify`: PASS on both complete runs, including final regression coverage.
+Final lint/architecture and build PASS; focused updated installation/selection
+checks PASS. Runtime Node 23.11.0 (supported >=22), whereas CI uses Node 22.
+CI additionally checks optional debugger compilation/package contents; those
+unrelated checks were not rerun locally. Sandbox blocks tsx IPC/native services;
+required suite/native commands succeeded with approved escalation.
+
+Focused review found no remaining blocker: unknown booleans omitted, query
+arguments device-scoped, malformed/native failures preserved, shared deadline
+caps fallback/conversion, and no persistent app inventory/cache introduced.

package/docs/specs/034-app-installation-status/spec.md

@@ -0,0 +1,114 @@
+# Specification: trustworthy app installation status
+
+Status: approved by user “ok” in this chat on 2026-11-05; implementation authorised.
+Intent: [approved scope](intent.md), user response “yes”, 2026-11-05.
+Source: [issue #98](https://github.com/clivejefferies/mobile-debug-tools/issues/98).
+
+## Behaviour and scope
+
+Installation is an observation about one app on one device, not a claim that
+the app is running, visible or ready. Fix inventory and Android system-status
+reporting without adding a tool or broadening device support. Existing iOS
+inventory covers simulators; physical iOS installation checks remain unsupported.
+
+`list_devices` retains its `{ devices: DeviceInfo[] }` wrapper. Publish the
+already-handled optional `appId: string` input alongside optional `platform`.
+Use only that explicit app ID for inventory checks; do not silently substitute
+environment configuration. Reject blank/invalid identifiers before native calls.
+Accept conventional Android package and iOS bundle identifiers (letters, digits,
+underscores, hyphens and periods); use argument arrays, never shell interpolation.
+
+Every returned device gains `appInstallation`:
+
+```ts
+{
+  status: 'installed' | 'absent' | 'unknown';
+  appId: string | null;
+  deviceId: string;
+  scope: 'android-current-user' | 'ios-simulator';
+  checkedAt: string | null; // UTC ISO timestamp when a native check finished
+  reason?: 'APP_ID_NOT_PROVIDED' | 'DEVICE_UNAVAILABLE' |
+    'CHECK_FAILED' | 'UNRECOGNIZED_RESPONSE';
+}
+```
+
+`installed` and `absent` require a successful authoritative query. Unknown
+always includes a reason. `checkedAt` is null when no native check ran.
+Keep legacy `appInstalled: true/false` only for confirmed installed/absent;
+omit it for unknown. This corrects false negatives while retaining boolean
+compatibility for conclusive checks. It intentionally changes callers that
+incorrectly treat a missing boolean as confirmed absence; document this clearly.
+Do not emit raw native errors or app-container paths in this diagnostic object.
+
+## Platform evidence
+
+Android: query `pm path <appId>` with explicit serial. A successful result
+containing valid package-path lines confirms installed. Successful empty output
+confirms absence for the device's current Android user; other Android users and
+work profiles are outside that observation. A silent nonzero `pm path` result may be followed by a successful
+`pm list packages <appId>` query: exact membership confirms installation and
+absence from a valid returned package list confirms absence. Otherwise nonzero
+exit, timeout, disconnected,
+offline or unauthorized device means unknown. Unexpected nonempty output means
+unknown, never absent. Metadata failures must not manufacture absence.
+
+iOS: for a simulator known to be booted, query `simctl listapps <udid>` using
+its property-list output converted to JSON by macOS `plutil`, and check exact
+bundle-identifier membership. A successfully parsed
+app dictionary confirms installed or absent. Failed queries, malformed responses,
+and simulators without confirmed booted state mean unknown. Replace the current
+`get_app_container` failure-to-absence inference. Do not boot simulators as a
+side effect of inventory. Preserve existing simulator inventory ordering.
+
+## System status and selection
+
+`get_system_status` keeps its input schema and existing toolchain status fields.
+Use the existing `MCP_TARGET_PACKAGE`, then `MCP_TARGET_APP_ID` precedence for
+Android app context. Add top-level `appInstallations`, an array of the same
+per-device observations for enumerated Android devices, including unavailable
+devices as unknown. With no app context, observations are unknown with null app ID.
+
+Legacy top-level `appInstalled` is present only when exactly one Android device
+was enumerated and its result is conclusive. With multiple devices, no devices,
+missing context or failed query, omit the global boolean. Never run an untargeted
+package query. Report confirmed absence as a device-specific issue; report query
+failures as check failures, not “app not installed”. No iOS app check is implied
+by Android system-status fields. Invalid environment app IDs produce unknown
+CHECK_FAILED observations and a configuration issue, without a subprocess.
+
+Device selection may prefer only confirmed installed results for the requested
+app. Retain existing remaining preference rules; unknown must not become an
+absence assertion. Include check context in ambiguity diagnostics. Do not reuse
+installation observations across apps, devices or inventory calls.
+
+## Failure, ownership and privacy
+
+Each native installation query has a five-second maximum, capped by any enclosing
+operation deadline, using existing subprocess cleanup. Deadline expiry or interrupted
+checks cannot yield installed/absent. No retries, persistent cache, background
+processes or changed cancellation protocol. Partial inventory retains device rows
+and marks failed checks unknown. Whole inventory-enumeration failures retain the
+existing empty-list behaviour; this does not establish app absence.
+
+Checks are read-only: no installs, uninstalls, launches, unlocks or settings changes.
+Return only requested app identity, device identity and bounded status metadata;
+discard unrelated iOS app inventory after exact membership lookup.
+
+## Acceptance and verification
+
+1. Reproduce Android's missing-context false result on the current checkout;
+   compare explicit installed and absent app checks on available devices. Record
+   limits preventing reconstruction of the original agent session.
+2. Verify installed/running, absent, missing context, multiple devices, query
+   failures, malformed output and unavailable devices without false absence.
+3. Verify iOS installed/absent on a booted simulator separately; shutdown and
+   failed-listapps paths remain unknown. Physical iOS is explicitly unsupported.
+4. Test schemas, dispatch, serialized omission of unknown booleans, system-status
+   aggregation, and selection consumers together using deterministic fake tooling.
+5. Update tool descriptions, management/system guides and changelog. Run
+   `npm run verify`, `npm run test:device`, and focused calls against the updated
+   server. Report exact device/build evidence and unrun coverage separately.
+
+Initial prerequisites: Android emulator and Pixel 9 Pro are connected; no iOS
+simulator is currently booted. Native inventory required sandbox escalation.
+These are readiness observations, not verification of this proposed behaviour.

package/docs/specs/035-compact-interaction-results/baseline.md

@@ -0,0 +1,45 @@
+# Baseline investigation — 2026-11-05
+
+Local source fixtures executed using Node v23.11.0 and `node --import tsx` against
+current actionHandler, correlation, evidence and readiness code. Native calls were
+replaced by fixtures. These are response/serialization evidence, not device success.
+Four cases used a concrete fixture device, awake/unlocked readiness, UUID IDs,
+monotonic dispatch evidence and (for observed) one post-dispatch fingerprint capture.
+The failure fixture marked dispatch started and returned ACTION_TIMEOUT; the blocked
+fixture returned ELEMENT_NOT_FOUND without dispatch. Timings vary slightly per run.
+
+| Fixture | Current bytes | Proposed projection bytes | Reduction |
+| --- | ---: | ---: | ---: |
+| Dispatch-only success | 1129 | 836 | 26% |
+| Success with one observed fingerprint | 1639 | 854 | 48% |
+| Failed after dispatch | 1157 | 864 | 25% |
+| Blocked before dispatch | 1106 | 831 | 25% |
+
+Projection numbers are serialized design prototypes, not implemented behaviour.
+They preserve action fields; remove readiness evidence entries and evidence timing/
+observation arrays; add observed_state and diagnostics UUID references. They establish
+feasibility for a 1,280-byte budget, not validation of the complete contract. Exact
+semantic tests and the full adversarial budget matrix remain implementation work.
+Token estimates use ceil(bytes/4); no tokenizer measurement has been performed.
+
+All fixtures currently retain action_id/type, success, lifecycle_state,
+delivery_status, dispatch_started, verification, total timing, full device_readiness
+and full evidence envelope. Failure/blocked fixtures also retain failure_code and
+retryable. Full evidence repeats device/IDs/timestamps per observation. Compact
+currently drops detailed errors even when internally available. Light mode may add
+state_delta arrays; failed conditions can retain an entire observed tree. Journey
+results nest per-action envelopes. These variable-size paths require budget tests.
+
+## Connected server/device evidence
+
+The connected MCP server listed Android emulator-5554 (Android 16) and Pixel 9 Pro
+(Android 17); all listed iOS simulators were shut down. A screenshot on emulator-5554
+showed Android Settings. One tap on blank header space (360,80), compact/none,
+reported dispatch delivered and verification not_requested. No post-action UI read
+was performed, so resulting UI state is unknown. No setting change was requested.
+
+The connected tap returned 831 UTF-8 bytes (208 tokens using the bytes/4 estimate).
+The connected tap omitted device_readiness, unlike the local checkout. Its exact
+server build is unavailable through this call, so it is not current-source proof.
+The response had full evidence envelope and no observations. Physical Android and
+iOS interaction paths were unrun. No performance conclusion follows from this call.

package/docs/specs/035-compact-interaction-results/intent.md

@@ -0,0 +1,38 @@
+# Intent: concise, trustworthy compact interaction results
+
+Status: intent and specification approved; implementation and verification complete locally.
+Originator: GitHub issue #99; author identity not independently checked.
+Captured: 2026-11-05.
+Source: https://github.com/clivejefferies/mobile-debug-tools/issues/99
+
+## Problem
+
+Recent agent feedback reports that routine taps return substantial metadata even
+in compact mode. Clients need the action outcome, observed resulting UI state,
+and actionable readiness blockers without repeatedly consuming detailed diagnostics.
+Issue #82 addressed debugger responses; this work concerns ordinary interactions.
+
+## Desired outcome and scope
+
+Audit existing compact interaction and journey results on Android and iOS. Record
+representative successful, failed, and blocked response sizes and retained fields.
+Specify and validate an explicit compact output budget, with measured byte/token
+reductions against that baseline. Retain action outcome, verification status,
+observed state or explicit unknown, actionable blockers, and evidence correlation.
+Keep detailed failure diagnostics accessible through an explicit supported path.
+
+Check callers, serialization, documentation, and compact/debug compatibility
+together. Device evidence must distinguish actual observations from dispatch-only
+success; no screen may be described as current without an observation.
+
+## Constraints and open questions
+
+Exclude debugger redesign, latency optimization, and new interaction capabilities.
+Investigation will establish the budget, retained fields, diagnostics access path,
+and any compatibility impact for specification approval. Preserve verification and
+readiness semantics; concise output must not imply stronger success evidence.
+
+## Approval
+
+The user approved this intent with “ok” in this chat on 2026-11-05.
+This approves the problem and scope; the response contract was subsequently approved with “ok” in this chat.

package/docs/specs/035-compact-interaction-results/plan.md

@@ -0,0 +1,43 @@
+# Implementation plan
+
+[Intent](intent.md) and [specification](spec.md) approved by the user's two “ok”
+responses on 2026-11-05. Implement on existing feature/compact-interact-results;
+preserve unrelated edits. Compact shape changes are intentional; debug is compatible.
+
+## Ordered work
+
+- [x] Preserve full internal action/journey diagnostics until final response boundary.
+- [x] Add bounded session result store, strict diagnostics schema/tool and dispatch.
+- [x] Project final action/child/journey payloads with explicit freshness and byte bounds.
+- [x] Update consumers, contract fixture, tool docs, README, changelog and plugin guidance.
+- [x] Verify regressions, store limits, errors, final serialized budgets and debug parity.
+- [x] Run native checks and record evidence, review diff and report limitations.
+
+## Verification map
+
+| Criteria | Checks |
+| --- | --- |
+| Baselines and byte reductions | Existing baseline plus deterministic fixture matrix; UTF-8 bytes and labelled bytes/4 estimate |
+| Bounds and semantics | Final handleToolCall responses; conditional/delta-heavy/multibyte cases, 50 steps, paused/throwing errors, stale/unknown/overlapping evidence |
+| Diagnostics | Fidelity, no replay, injectable clock expiry, count/byte eviction, oversized rejection, invalid UUID/session and concurrent IDs |
+| Compatibility | npm run verify; schema/definition fixture; debug shape, existing journey and correlation tests; docs/plugin consistency |
+| Native | npm run test:device; updated dist server through MCP stdio on emulator-5554 and booted iOS simulator |
+
+Node >=22 required (local v23.11.0); existing TypeScript/tsx dependencies. Use
+`node --import tsx` for focused tests if tsx IPC is restricted. Native checks need
+ADB/emulator and Xcode/simctl/idb. Before native runs inspect connected devices and
+fixture availability. Start from Settings or isolated fixture app; exercise harmless
+dispatch-only input, post-observation, blocked selector, journey and lookup. Capture
+server commit+working diff, device/OS, response bytes, evidence freshness, unknown
+states, failures and cleanup. Restore starting screen and shut down simulators booted
+for this task. Use deterministic fixtures for unsafe native failure/cancellation paths.
+
+CI uses Node 22 on Ubuntu, lint/build/unit, Java worker compilation and package-file
+checks. Android integration is workflow_dispatch only; iOS checks are not in CI.
+Local verify additionally runs agent-plugin consistency. No publish/push authorised.
+
+## Results
+
+`npm run verify` and final `npm run test:device` passed. See
+[verification record](verification.md) for exact coverage, byte measurements,
+the intermittent trace-shutdown investigation and unrun optional fixtures.

package/docs/specs/035-compact-interaction-results/spec.md

@@ -0,0 +1,118 @@
+# Specification: compact interaction results
+
+Status: approved. Intent approved by the user's “ok” in
+this chat on 2026-11-05; see [intent](intent.md). Source: issue #99.
+
+## Behaviour and scope
+
+Apply one compact projection after final evidence assembly to existing actionHandler
+interactions (including lifecycle actions using that wrapper) and run_journey.
+Keep responseMode defaults, inputs, execution, targeting, budgets, verification,
+conditional-action protection and journey stop behaviour unchanged. Other tools,
+including debugger and UI-tree observation output, retain their existing contracts.
+
+Retain action_id, action_type, success, lifecycle_state, delivery_status,
+dispatch_started, verification, failure_code/retryable when applicable, and total
+elapsed time. No dispatch acknowledgement becomes verified success. Retain
+verification-unavailable diagnostics and condition status/reason. Replace raw
+condition observations, state_delta element arrays and repeated evidence metadata
+with bounded summaries and a diagnostics reference. This intentionally changes
+opt-in compact shapes; debug remains compatible. Update existing callers and
+fixtures that inspect compact evidence, conditions or deltas.
+
+Evidence retains session_id, correlation_id, action_id, device and linked trace_id
+when present; action_id remains usable as actionRef with the evidence session ID.
+Retain association failures/reasons where applicable. Readiness retains wakefulness,
+lock_state, input_ready, blockers and limitations, omitting probe evidence entries.
+Never infer input_ready=true from awake/unlocked or treat unknown as ready.
+
+Add observed_state: status observed or unknown. Observed requires an actual
+successful same-device post-dispatch observation; include kind, captured_at_ms,
+freshness and snapshot session/revision when available. A precondition tree is
+pre-action evidence, never resulting state. No observation, failed capture,
+unknown timing, overlap or supersession must be represented conservatively with a
+reason. Only fresh post-action evidence permits status observed; other cases use
+unknown while retaining the evidence classification. Fingerprint evidence describes
+an observation, not a named screen or proof of an intended outcome. State deltas
+retain revision IDs, counts of added/removed/changed items, truncation and omitted
+counts; detailed elements are retrieved separately. No new hierarchy read is added.
+
+Journey retains success, stopped_at_step_id and every step's id/type/status/success,
+reason for unrun steps and compact result. Preserve assertion outcomes, matched
+counts and bounded actual-state summaries. Finalize shared light-verification
+and child evidence before projection. Do not project a child twice or lose its
+original diagnostics. Trace linking and cleanup remain unchanged.
+
+## Bounds and diagnostics
+
+Measure UTF-8 bytes of the final MCP text item after correlation and serialization,
+not just an internal result. Caller-ID allowances count their UTF-8 JSON wire
+encoding, including necessary escapes, so IDs are preserved verbatim. Each standalone compact result must fit 1,280 bytes
+plus device-ID bytes. Each journey must fit 1,280 + 1,280 per supplied step, plus
+UTF-8 bytes of supplied step IDs and device ID occurrences. Routine four-fixture
+results must also reduce bytes by at least 20% each against the baseline below.
+Report bytes and ceil(bytes/4) as a labelled token estimate, never actual tokens.
+
+Use allowlists, bounded scalar strings (128 UTF-8 bytes per display value) and
+count summaries; mark omitted display data with truncated=true. Preserve original
+caller IDs, fixed outcome/status codes, all known blocker codes and correlation
+references. If optional summaries would exceed the budget, omit them with
+truncated=true and observed_state unknown when necessary; never silently drop
+outcomes, blockers or diagnostics access. Test multibyte strings, huge trees,
+conditions, deltas and all 50 journey steps. Debug output has no new output cap.
+
+Add get_interaction_diagnostics({sessionId,resultId}), both UUID strings, strict
+runtime validation and matching tool JSON schema. Every compact action/journey
+and executed child result carries diagnostics {session_id,result_id,available}.
+The lookup returns success:true and result containing the original diagnostic
+payload and final full evidence, without replaying or observing the device.
+Retain the pre-projection payload, including details already available internally
+but previously omitted by compact mode; do not fabricate omitted debug captures.
+Explicit debug mode remains the path for requesting additional diagnostic capture
+at execution time. Lookup does not promise a debug rerun's additional observations.
+
+Store at most 100 results, ten minutes from completion, and 16 MiB total in process
+memory; cap each entry at 1 MiB. Serialize once and use oldest-completed eviction.
+Oversized entries return available:false, reason:RESULT_TOO_LARGE in the compact
+reference; never evict the useful summary. Lookup errors use success:false and
+error {code,message}: SESSION_MISMATCH, RESULT_UNAVAILABLE (expired, evicted,
+unknown or restarted), INVALID_ARGUMENT. No disk persistence, automatic retries,
+subprocesses or device selection. Concurrent results receive unique IDs; reads do
+not extend retention. Return explicit unavailability rather than rerunning input.
+
+## Platform, failure and privacy
+
+Projection is platform-neutral; preserve Android/iOS readiness unknown/unsupported
+semantics. Route guarded failures and thrown errors through the same compact
+boundary where these tools currently return errors, preserving MCP error signalling.
+Timeouts retain uncertain delivery and retryability. Cancellation retains existing
+execution semantics and never triggers replay; completed retained results expire
+normally. No new permissions, device actions or native dependencies are introduced.
+
+Diagnostic payloads may contain UI text, paths and errors. Retention is session-local,
+bounded and nonpersistent; compact mode is not redaction. Do not log stored content
+or expose unrelated sessions. Document expiry and that lookup is read-only.
+
+## Acceptance and verification
+
+1. Record baseline/projection sizes and field differences, including successful,
+   failed, blocked, conditional, delta-heavy and journey cases.
+2. Assert byte bounds on final serialized results and >=20% fixture reduction;
+   check semantic fields, unknown observations and freshness independently.
+3. Verify lookup fidelity, expiry, size rejection, eviction, session mismatch,
+   concurrency, validation and absence of device calls or replay.
+4. Verify registration/dispatch/schema parity, existing callers, debug compatibility,
+   docs and plugin instructions together. Run npm run verify and test:device;
+   inspect current CI for coverage differences during implementation planning.
+5. Exercise updated local server on Android and a booted iOS simulator: dispatch-only,
+   actual post-observation, failed/blocked action, journey and diagnostics lookup.
+   Record build/device, evidence and cleanup. Native failure paths unsafe to induce
+   use deterministic fixtures, labelled separately. iOS is currently unrun: listed
+   simulators are shut down; boot one during implementation verification.
+
+Affected areas: action-execution, correlation, journey, evidence assembly, new bounded
+result store and diagnostics handler/schema/definition, tool dispatch, tests and docs.
+Main risks are compact consumers relying on removed metadata, freshness mistakes,
+projection before journey evidence finalization and unintended diagnostic retention.
+The user approved this complete specification with “ok” in this chat on
+2026-11-05; implementation within this scope is authorised.

package/docs/specs/035-compact-interaction-results/verification.md

@@ -0,0 +1,111 @@
+# Verification record — 2026-11-05
+
+Implementation is local on feature/compact-interact-results, based on commit
+04f082a4c03f20b64a8fb13aed2b155225cad6cc plus this ticket's working-tree changes.
+Nothing was committed, pushed, published or installed as a released package.
+
+## Automated checks
+
+- `npm run verify`: PASS; ESLint, structural limits, architecture, TypeScript,
+  108 unit-test files, and agent-plugin consistency.
+- Focused compact tests: PASS; final serialized budgets, >=20% reduction for
+  each baseline fixture, huge conditions/deltas, multibyte/control-character IDs,
+  maximal 50-step results, retained diagnostics, automatic expiry, count/byte
+  eviction, oversized rejection, session mismatch, concurrency and strict UUID
+  schema, no replay, debug compatibility, guarded failures and MCP error signalling.
+- Journey evidence regression: PASS; shared assertion observations attach to the
+  preceding light tap; later actions invalidate both tap/assertion freshness before
+  projection and diagnostics retention. Missing capture times remain unknown.
+- Tool-definition compatibility fixture intentionally updated for the new tool and
+  revised compact descriptions. Existing conditional, selector, debugger-guard,
+  correlation and trace assertions now retrieve detailed metadata through diagnostics.
+- Relative documentation links, whitespace/diff checks and plugin mirror: PASS.
+
+Local runtime: Node v23.11.0; CI uses Node 22. CI additionally compiles the Java
+worker and checks package contents; those CI-specific steps were not run locally.
+No Java or packaging configuration was changed.
+
+## Native evidence
+
+`npm run test:device`: PASS on final retry; 16 test files loaded. Seven optional
+fixture files reported UNRUN: Android coroutine/Kotlin/runtime debugger, iOS runtime
+debugger, isolated Android interaction fixture, disposable-device readiness, and
+iOS system trace. Their explicit environment variables/toolchain selections were
+not supplied. This does not establish coverage for those journeys or physical devices.
+
+The new compact smoke uses MCP stdio against rebuilt dist/server.js (server
+0.36.0), rather than the connected older MCP instance. Settings was the starting
+and ending app; no settings or app data were modified. Checks passed on:
+
+| Platform/device | Observed evidence | Status |
+| --- | --- | --- |
+| Android 16, emulator-5554 | Dispatch-only launch unknown; light launch fresh post-action UI tree; absent selector fails before dispatch; two-step launch/assert journey; original/child lookup | PASS |
+| iOS 26.4, iPhone 17 Pro simulator F9243BAF-62A8-4990-8A99-17F527F56FDA | Same structured checks, preserving unknown/unsupported iOS readiness signals | PASS |
+
+These are UI-tree semantic/state checks, not screenshot layout assertions. The
+older baseline screenshot established only the initial Settings layout.
+
+Final fixture sizes were 830–864 bytes versus 1,106–1,639 baseline bytes (25–48%
+reduction, timing-dependent by a few bytes). Token counts use ceil(bytes/4), not a
+tokenizer. Device response sizes are recorded below after the final focused run.
+
+The compact build hash is SHA-256
+c2f93bf6a45b774f1fd2d57d721c855cb91e69f6ecbee46d860c12a00f2d151a,
+computed over dist/server.js, dist/server/handlers/compact-interaction.js,
+dist/server/handlers/compact-state.js,
+dist/server/handlers/interaction-diagnostics.js, and dist/observe/evidence.js
+in that order. This identifies a local build, not a release.
+
+## Failure investigation and review
+
+An earlier device-suite attempt found one Android trace-shutdown file-removal
+failure. A complete unmodified HEAD trace smoke passed; the modified trace smoke
+then passed in isolation and within the final full device suite. Root cause remains
+unproven; no trace implementation or assertion was weakened. The exact task-owned
+leftover file was removed after its capture duration elapsed and absence verified.
+This intermittent failure is recorded rather than classified as pre-existing.
+
+Focused review checked final projection after guards/correlation and journey
+refresh, post-dispatch/same-device/freshness requirements, fixed outcome/blocker
+preservation, optional-summary truncation, retained-original fidelity, strict lookup
+validation, bounded memory/automatic expiry, and absence of replay/native work in
+lookup. Debug payloads and execution controls remain compatible. Compact clients
+must migrate detailed metadata reads to the new lookup. Diagnostics may expire or
+be evicted and oversized entries are explicitly unavailable; this is documented.
+
+Simulator shutdown and final focused build confirmation are recorded below.
+
+## Final focused build run
+
+| Platform | Dispatch-only bytes | Observed bytes | Blocked bytes | Journey bytes |
+| --- | ---: | ---: | ---: | ---: |
+| android | 839 | 972 | 952 | 2184 |
+| ios | 893 | 1034 | 925 | 2284 |
+
+Both platform journeys and original/child lookups passed on the final rebuilt
+server. Android Settings remains foreground with no data/settings changes.
+The iPhone 17 Pro simulator was shut down and booted-device inventory checked,
+restoring its initial state.
+
+## PR #106 review repairs — 2026-11-06
+
+Both attached review findings were confirmed against PR head 0fe5720. Failed compact
+wait/assert operations now carry their step-scoped acquisition evidence through a
+typed error wrapper into the failure result and retained diagnostics. The original
+failure remains the cause; no mutation of thrown values is required. Wait operations
+are awaited so rejected promises reach the step failure handler. Successful operations
+and returned timeout payloads retain their existing behaviour. Shortened journey error
+messages now set truncated=true even when the whole result fits its byte budget.
+
+`compact-review-regressions.test.ts` covers a captured tree followed by a deterministic
+remainingBudget() rejection, child/journey diagnostics fidelity, no replay, returned
+timeouts, debug compatibility, and ASCII/UTF-8 truncation boundaries. These thrown
+failure paths are fixture evidence, not induced native timeouts.
+
+`npm run verify`: PASS (109 unit-test files, lint/architecture, build, plugin consistency).
+`npm run test:device`: PASS (16 files; the same seven optional fixture files reported
+UNRUN for missing explicit environment selections). Rebuilt-server compact journeys,
+lookup, screenshots, logs and UI-tree checks passed on Android 16 emulator-5554 and
+iOS 26.4 simulator F9243BAF-62A8-4990-8A99-17F527F56FDA; Android trace lifecycle,
+cancellation and shutdown passed. No settings/app data changes or layout claims were
+made. The iOS simulator was restored to its initial shut-down state after the run.

package/docs/specs/036-end-to-end-interaction-latency/android-snapshot-amendment.md

@@ -0,0 +1,60 @@
+# Android debug snapshot tree reuse
+
+Status: accepted on 2026-11-10. The user replied “yes” when asked to approve
+this amendment in this chat.
+
+The [ticket #100 measurements](../../benchmarks/end-to-end-latency/investigation.md)
+recorded 36 physical read attempts across nine successful Android debug snapshots
+with screenshots and logs disabled. Eighteen reads failed before recovery. The
+snapshot median was 4.19 s. The snapshot currently starts a tree read and a
+fingerprint request in parallel, and the Android fingerprint request reads its
+own tree. The Android run ended before the planned tenth sample per case.
+
+## Proposed behavior
+
+For `capture_debug_snapshot` on a resolved Android target, collect one fresh
+tree using the existing acquisition path. Return that tree in `raw.ui_tree` and
+derive `raw.fingerprint` from the same tree using the existing Android hash
+algorithm and its post-tree activity lookup. Preserve the independent Android
+`raw.activity` result and its error handling. This applies when the platform
+is inferred as well as when Android is specified explicitly. It covers all
+screenshot and log flag combinations.
+
+Keep sharing scoped to the resolved device and the current snapshot request.
+Each new snapshot starts its own acquisition. Preserve the captured tree's
+revision, timestamp, and evidence provenance. The tree and fingerprint share
+a source observation. Other snapshot components can still describe different
+instants within the request. Keep the public inputs and response shape, iOS
+collection, standalone fingerprint and tree tools, and journey verification
+paths as they are.
+
+The existing tree acquisition owns its retries, deadlines, and child-process
+cleanup. If it fails, report both the tree error and fingerprint unavailability
+using the existing per-component error fields. A second tree collection solely
+for the fingerprint would defeat the intended sharing. Preserve independent
+screenshot, activity, and log results. Preserve the existing fingerprint
+fallback when the post-tree activity query fails, and report a fingerprint
+calculation failure without discarding a successful tree. Capture only
+timing, counts, build identity, and sanitized failure categories in the paired
+benchmark artifacts.
+
+## Acceptance
+
+1. A successful Android snapshot makes one logical tree acquisition. Verify
+   that the returned fingerprint matches the existing algorithm applied to
+   the returned tree and the post-tree activity. Verify repeated captures
+   after a state change, device isolation, and unchanged response fields.
+2. Verify tree failure, activity failure, timeout, and partial results without
+   an extra fingerprint-driven tree acquisition. Retain the current native
+   acquisition and its cleanup path. Verify the unchanged iOS dispatch path
+   in unit coverage and report native iOS availability separately.
+3. Run a focused paired comparison of screenshot/log-free snapshots on the same
+   stable Android emulator and fixture screen. Use three warm-ups and ten
+   measured attempts per build, alternate order, and retain failures and read
+   attempts. Require fewer physical read attempts and a lower p95 with no
+   p50 regression or additional tool failures. Record build and fixture hashes.
+   The historical partial run motivates the candidate. The acceptance comparison
+   uses a newly measured baseline and candidate under matching conditions.
+4. Run `npm run verify`, applicable `npm run test:device` coverage, and a focused
+   native snapshot check. Record blocked checks and withhold any speedup claim
+   if the paired run is incomplete or correctness checks fail.

package/docs/specs/036-end-to-end-interaction-latency/android-snapshot-plan.md

@@ -0,0 +1,32 @@
+# Android debug snapshot verification plan
+
+The user accepted the [amendment](android-snapshot-amendment.md) on 2026-11-10.
+
+1. Build and freeze the current baseline before editing production source.
+2. Share the Android fingerprint calculation with snapshot collection. Use the
+   existing tree handler and retain the Android activity lookups and iOS branch.
+3. Extend snapshot tests to cover hashing, ordering, target resolution, fresh
+   requests, partial errors, timeouts, and iOS dispatch. Keep native subprocess
+   ownership with the existing acquisition path.
+4. Run `node --import tsx test/unit/observe/capture_debug_snapshot.test.ts`,
+   `npm run verify`, and `npm run test:device` on the candidate.
+5. Use Node 22 or newer and the existing Android API 36 fixture tooling for
+   paired measurement. Run `node --import tsx test/device/automated/latency/snapshot-pair.ts`
+   with `LATENCY_DEVICE_ID`, `SNAPSHOT_BASELINE_SERVER`, and
+   `SNAPSHOT_BASELINE_SOURCE_SHA` set. Use the same dedicated fixture screen and
+   flags for both builds. Count acquisitions and physical attempts, assert the
+   candidate fingerprint and tree, record p50/p95 and failures, and close owned
+   server groups. Restore fixture state and stop any emulator started for testing.
+
+## Verification results
+
+- The focused snapshot unit test and `npm run verify` passed locally on Node
+  23.11.0. Hosted CI was not run.
+- The [paired Android benchmark](../../benchmarks/end-to-end-latency/android-snapshot-pair.md)
+  passed with ten measured snapshots per build. Median latency fell from
+  3.805 s to 2.364 s, and p95 fell from 3.949 s to 2.423 s. The candidate
+  performed one tree acquisition per call and returned fresh evidence after
+  navigation. Both server groups exited and the fixture was cleaned up.
+- Android compact results and correlated evidence passed. The full device suite
+  and the separate correlated evidence smoke both stopped at the iOS simulator
+  prerequisite. Environment-gated debugger fixtures were skipped.