Skip to content

perf(ios): optimize observation lifecycle and prove proxy parity #2198

Description

@thymikee

Parent: #2188

Blocked by: #2189, #2197

Outcome

Remove XCTest startup/readiness from bridge-eligible observation and relaunch paths without delaying
the first runner-dependent interaction, then prove the resulting architecture works through
agent-device proxy with semantic parity, lease isolation, cancellation, version skew, and measured
remote performance.

This issue owns end-to-end latency and remote acceptance. It must not expose bridge internals or move
acquisition/presentation to the remote client.

Runner-demand policy

Add an internal execution-plan decision:

  • runnerDemand: 'none': a proven observation-only plan does not prewarm or retain a runner;
  • runnerDemand: 'required': a known runner-dependent plan prepares readiness at the owning point;
  • runnerDemand: 'possible': future use is unknown, so background prewarm may continue but
    bridge-eligible observation does not await it.

No public CLI flag controls this policy. Derive it from the command/workflow plan and declared
interaction requirements.

For bridge-eligible local Simulator flows:

  • start bridge work and optional runner prewarm in parallel;
  • do not await runner readiness before the first observation;
  • remove the open --relaunch runner-prewarm wait from the observation path;
  • await only the unamortized runner readiness at the first runner-dependent command;
  • preserve its existing typed errors, cancellation, deadline, and interaction guarantees;
  • cancel/release speculative runner work when a proven observation-only session no longer needs it.

Proxy architecture

The required path is:

remote client → proxy → macOS daemon → bridge/runner acquisition → host presentation → published snapshot → proxy → client

  • Acquisition, geometric presentation, semantic compaction, quality classification, and invariants
    execute on the daemon host.
  • The proxy receives only the existing command request and published response. The internal acquired
    tree, lineage, target-generation facts, and runner quality payload are not separate/intermediate
    wire payloads.
  • The bridge remains private host infrastructure. Add no bridge/helper/admin proxy route.
  • Internal stage/hint/residue contracts do not become required RPC fields. Any intentional additive
    field follows ADR 0006; any breaking wire change needs the enforced protocol-version path.
  • Bridge helper ownership stays below the admitted remote device lease. Capture data and comparison
    baselines cannot cross tenant, client, session, lease expiry, reacquisition, or generation.

Performance protocol

Use #2189's exact corpus and raw-result schema. Report:

  • daemon-resident request;
  • local fresh-process CLI wall;
  • proxy persistent-client wall;
  • proxy fresh-process CLI wall.

Run proxy points at controlled approximately 0 ms, 20 ms, and 80 ms RTT and report bandwidth,
packet loss, regular/raw response bytes, median, p95, failures, and raw samples. Remote numbers do not
replace local targets; separate bridge performance from health compatibility, RPC round trips,
network transfer, client startup, and output formatting.

The regular-snapshot trace must prove the bridge adds no network round trip and transfers only the
published response. Compare against #2189's current-proxy baseline rather than an ad-hoc local run.

Proxy and lifecycle acceptance

  • Direct-daemon and proxy execution over the same deterministic acquisition fixture publish
    semantically identical regular/raw snapshots, warnings, typed errors, and fallback residue;
    transport timing/request ids are excluded from equality.
  • Two clients contending for one device fail through existing lease admission before platform work.
  • Lease heartbeat, expiry, session cleanup, device reacquisition, and new-generation capture do not
    reuse prior capture/comparison state.
  • Cancellation propagates through proxy, daemon, bridge, and fallback; fallback remains at most once
    inside the original deadline.
  • Supported older/newer package combinations follow ADR 0006. Incompatible RPC versions fail at
    health compatibility before command RPC; additive optional response evolution stays compatible.
  • Proxy failures preserve typed error, hint, diagnosticId, logPath, warnings, request id, and
    typed details rather than becoming a generic transport failure.
  • Proven observation-only flows do not start/retain a runner; unknown flows prewarm without blocking
    observation; the first required interaction waits correctly and preserves guarantees.
  • Cold, warm, and relaunch results meet iOS snapshot backend convergence and fast Simulator observation #2188's accepted local targets with no increase in wrong-tree,
    stale-tree, unreadable-tree, lease, or interaction failures.

Non-goals

  • No new proxy route, authentication model, lease model, public runner-demand flag, public backend
    flag, or daemon RPC redesign.
  • No physical-iPhone, provider, custom-action, or XCTest interaction implementation change.
  • Do not remove the runner; it remains required for interactions and typed fallback.

Validation

  • Focused open/relaunch, runner lifecycle, interaction-guarantee, lease, daemon-proxy, HTTP client,
    wire-compat, cancellation, and fallback suites.
  • Planted-red proof for observation accidentally awaiting runner readiness and for bridge state
    crossing an expired/reacquired lease.
  • Controlled-RTT benchmark artifacts and direct/proxy semantic-differential output.
  • Simulator live smoke, proxy integration, protocol-compatibility, and
    pnpm check:affected --run on the exact head.

Worker stop conditions

  • Stop if remote performance is reported without test(ios): establish snapshot convergence baselines and permanent evidence #2189's baseline and controlled network profile.
  • Stop if bridge state must be exposed through proxy or public RPC to make the test pass.
  • Stop if skipping prewarm changes the first runner-dependent interaction guarantee or error shape.
  • Stop if physical-device behavior or performance changes.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions