feat(sim,engine): @linkcode/sim SDK + SimulatorBackend with per-session device ownership (CODE-393)

[AprilNEA]

Supersedes #249 (auto-closed when its stacked base branch was deleted during the #247 merge). Same branch, now rebased onto master with the review-comment fixes folded in.

@linkcode/sim typed sidecar client + engine SimulatorBackend port + SimulatorService (per-session device ownership, caps, idle reclaim), wired into the daemon.

Review fixes (from the #249 bot review)

• Stale sidecar-child events: every child listener is now scoped to its own child, so an old child's delayed exit/error/data after a crash-respawn no longer tears down (or feeds stale bytes into) the replacement.
• Write failures waited out the deadline: a synchronous writeFrame failure now fails the request immediately instead of leaving it pending until the reply timeout.
• Boot/ownership race: if the owning session stops mid-boot, the booted device is re-tracked for idle reclaim instead of being left running untracked.
• Reclaim freed the device too early: the idle reclaim now shuts the device down before releasing its claim, closing the window where another session could grab and boot the same udid mid-shutdown. New regression tests cover both races.

CODE-393. Stacked under #251.

[linear-code]

CODE-393

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1d235267bd

ℹ️ 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

Adds the simulator host stack and daemon integration.

• Introduces the typed @linkcode/sim framed sidecar client.
• Adds engine-side simulator ownership, per-session limits, idle reclaim, and shutdown handling.
• Resolves and injects the simulator sidecar in daemon and packaged-desktop environments.
• Adds unit, codec, lifecycle-race, and opt-in end-to-end tests.

Confidence Score: 4/5

The PR is not yet safe to merge because resuming a simulator session during reclaim can leave it operating against a device that is still being shut down.

The reclaim fix preserves the ownership entry but does not synchronize with or reverse the shutdown already in flight, so the resumed session can receive operation failures or retain a stopped device.

packages/host/engine/src/simulator/service.ts

T-Rex Logs

What T-Rex did

• Reproduced the resume race reclaim scenario using the deterministic focused Vitest race harness.
• Observed that the operation resumed during shutdown and completed with the device in Shutdown while session-1 still owned it, with no subsequent boot occurring.
• Compared test counts and coverage, noting 19 tests before and 20 tests after adding reclaim regression coverage, and confirmed the TypeScript checks completed successfully.
• Collected and linked artifacts that support both proofs, including the reproducible harness, focused Vitest configuration, and the test logs plus typecheck results.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
packages/host/engine/src/simulator/service.ts	Adds ownership and reclaim policy, but a session resuming during an in-flight reclaim shutdown can retain a claim to a device that is still shut down.
packages/host/sim/src/client.ts	Adds the framed sidecar client with request correlation, child-generation isolation, timeout handling, and immediate synchronous write-failure rejection.
packages/host/sim/src/codec.ts	Implements bounded incremental frame decoding, request framing, and binary screenshot decoding.
packages/host/engine/src/engine.ts	Wires the optional simulator service into session release and engine shutdown.
apps/daemon/src/index.ts	Injects the simulator sidecar backend when supported and configured.
apps/desktop/src/main/daemon-supervisor.ts	Supplies the packaged macOS simulator sidecar path to the supervised daemon.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Session[Session operation] --> Service[SimulatorService]
  Service --> Claim[Device ownership claim]
  Claim --> Client[SimSidecarClient]
  Client --> Sidecar[linkcode-sim sidecar]
  Sidecar --> Simulator[iOS Simulator]
  SessionStop[Session stops] --> Idle[Idle reclaim timer]
  Idle --> Shutdown[Shutdown device]
  Shutdown --> Release[Release claim]

Loading

_{Reviews (2): Last reviewed commit: "fix(sim): reconcile boot ownership on fa..." | Re-trigger Greptile}

[AprilNEA]

Addressed the review in abc79e1: boot ownership is now reconciled in a finally so a boot that fails after CoreSimulator started the device is still reclaimed; the idle reclaim carries a reclaiming flag so a session that resumes mid-shutdown keeps its re-acquired claim; and foxts is now declared in @linkcode/sim's dependencies. Added a regression test for the resume-during-reclaim case.

[greptile-apps]

Resume races reclaim shutdown

When the owning session performs another simulator operation after idle reclaim has started, claim() clears reclaiming but allows the operation to proceed while shutdownDevice() remains in flight. The operation can fail against a device being shut down, or the pending shutdown can leave the session owning a stopped device; no subsequent reboot occurs here despite the comment.

Artifacts

Repro: deterministic focused Vitest race harness

• Evidence file captured while the check ran.

Repro: focused Vitest configuration

• Evidence file captured while the check ran.

Repro: verbose failing test output with backend call ordering and assertion trace

• The full error output from the failing run.

_{Ran code and verified through T-Rex}