feat(schema,engine,client-core): simulator wire contract — availability, device commands, screenshot (CODE-394)

[AprilNEA]

Summary

Stacked on #249. The simulator surface reaches the wire (WIRE_PROTOCOL_VERSION 43 → 44):

• schema: simulator.* variants — status/status.result (the capability gate: available:false is an answer, never an error), list/listed, devices.changed broadcast, and session-scoped commands boot/shutdown/install/launch(→launched pid)/terminate/open-url/screenshot(→screenshotted base64). Model shapes in model/simulator.ts.
• engine: SimulatorRequestHandler routes commands through SimulatorService (ownership/cap/reclaim enforced there); after boot/shutdown it re-lists and broadcasts simulator.devices.changed best-effort (the engine has no CoreSimulator watcher — its own commands are the only observable change source). service.status() caches a successful probe, re-probes failures so installing Xcode heals the capability without a restart.
• client-core: typed simulator* methods on LinkCodeClient/ControlChannel via the shared PendingRegistry correlation, plus subscribeSimulatorDevicesChanged.

Availability is request/reply (simulator.status) rather than an unsolicited broadcast — it's connection-constant per host, mirroring agent-runtime.list; the dynamic part (device state) is what broadcasts.

Verification

• Schema contract tests (15 accepted / 3 rejected shapes) + engine wire-injection tests (no-backend unavailable + unsupported, status/list/boot→devices.changed, launch/screenshot replies, cross-session conflict). pnpm check:ci + pnpm test (1772) green.
• Live acceptance against a dev daemon over real socket.io: simulatorStatus → available with simctl path; 11 devices listed; boot → devices.changed push shows iPhone 17: Booted; screenshot 505 KB JPEG over base64 round-trips and decodes; shutdown → second push shows Shutdown.

[linear-code]

CODE-394

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 22b07391da

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[greptile-apps]

Greptile Summary

This PR adds the simulator wire contract across the schema, engine, and client packages. The main changes are:

• Simulator availability, device, command, launch, and screenshot payloads.
• Engine routing, ownership checks, claim rollback, and device-change broadcasts.
• Typed client methods, request correlation, and device-change subscriptions.
• Wire protocol version 44 and simulator contract tests.

Confidence Score: 5/5

This looks safe to merge.

No additional blocking issue met the follow-up review criteria.

T-Rex Logs

What T-Rex did

• Validated the simulator wire validation to produce a fresh runtime output that captures the exact command, working directory, exit code, and Vitest totals.
• Opened and examined the simulator-wire-validation.log artifact to verify the captured details from the validation run.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
packages/host/engine/src/simulator/service.ts	Adds availability probing, live-session validation, ownership handling, and rollback for failed commands.
packages/host/engine/src/simulator/request-handler.ts	Routes simulator requests, sends correlated replies, and broadcasts updated device lists.
packages/foundation/schema/src/wire/simulator.ts	Defines simulator request, response, and broadcast payloads.
packages/client/core/src/client/control-channel.ts	Adds typed simulator commands through the shared pending-request registry.

_{Reviews (2): Last reviewed commit: "fix(sim): reject unknown sessions and ro..." | Re-trigger Greptile}

[AprilNEA]

Rebased onto master (which now carries the #247+#266 sidecar/service fixes) and addressed this PR's findings in d5c2466:

• Reject commands for nonexistent sessions: the service now takes a hasSession predicate (wired to the engine's live-session registry, mirroring TerminalService) and claim() rejects an unknown session with not_found before it can claim a device that would never be released.
• Failed commands retain claims: mutating commands run through withClaim, which rolls back a claim the failed command created (a refreshed pre-existing claim is left intact). Boot is the deliberate exception — it reconciles ownership itself, since a failed boot may still have started the device server-side.
• Boot ownership / session-release races: fixed in the service on feat(sim,engine): @linkcode/sim SDK + SimulatorBackend with per-session device ownership (CODE-393) #266 and inherited here via the rebase.

Added regression tests for session rejection and claim rollback; the wire request-handler test now drives real sessions.