[cryptotavares]

Summary: Follow-up to #43. Report a command that fails during backend disposal as an interruption, not as a missing companion. Resend on uncertain delivery only for known read-only idb commands. Remove HID and verdict checks that idb stderr can never match.

Problem

#43 added one reconnect and one resend for a lost companion or an invalidated simulator HID connection. Review found four problems.

1. Disposal during a command gives wrong advice. Disposal can start while a tool call runs. Triggers are the core request queue after a 30 s timeout, core stop(), and device-mcp's own SIGINT, SIGTERM or stdin EOF shutdown. The failed command then calls reconnect(), which throws because the backend is disposed. #idb() wraps that error:

IDB_COMPANION_UNAVAILABLE: iOS simulator <udid>: IDB backend has been disposed. The private idb_companion cannot be reached even after a restart. Check that the simulator is booted (xcrun simctl list devices booted) and that idb_companion is installed, then recreate the session.

The companion is installed. The session ended.

2. launch and terminate are resent on uncertain delivery. isMutatingIdbCommand treats only ui input commands as mutating. On StatusCode.UNAVAILABLE, the request may have arrived, but top-level launch and terminate are sent again.

3. A failed cleanup hides the connect error. In createBackend() and IdbBackend.#connect(), a dispose() that throws replaces the real connect error.

4. Dead patterns and an overstated guarantee. The facebook/idb v1.7.1 source shows:

Pattern or claim	Evidence in facebook/idb v1.7.1	Result
dtuhidd ... interrupted	FBSimulatorControl/HID/SimulatorDTUHIDConnection.swift: only a companion log line. XPC reconnects on the next send.	Never in idb stderr
dtuhidd ... did not answer	Same file, connect(): the per-attempt line is a log line. The thrown dtuhidUnresponsive text (SimulatorHIDError.swift) ends with would be discarded without error.	Already matched by the would be discarded pattern
retry: unsafe	idb/cli/main.py: printed only with --retry-verdict. The verdict covers UI automation failures, not HID failures.	device-mcp never passes the flag
"The resend cannot repeat a tap"	write() throws dtuhidConnectionInvalidated for the refused event only. ui text sends one down/up pair per character (idb/common/hid.py).	A partial command can land if the simulator dies midway

Solution

1. Detect disposal before recovery. If the backend is disposed after the first failure, do not resend. Throw a teardown error that keeps the first idb error as cause. Non-strict callers get the first result, as before.
2. Invert the resend list. Keep an explicit list of read-only commands. Treat every other command as mutating.
3. Make cleanup best-effort. Ignore a cleanup failure and rethrow the original connect error.
4. Match only thrown idb errors. Keep dtuhidd connection .*has been invalidated and events? sent (?:on|to) it would be discarded. Remove interrupted, did not answer and retry: unsafe. Correct the notDelivered and #idb() documentation.

flowchart TD
    A[idb command] --> B{Classified failure?}
    B -->|no| Z[Return result]
    B -->|yes| C[Reconnect or join newer companion]
    C --> D{Backend disposed?}
    D -->|yes| E["Error: IDB command interrupted<br/>cause = first idb error"]
    D -->|no, reconnect failed| F[IDB_COMPANION_UNAVAILABLE]
    D -->|no, reconnected| G{"notDelivered, or command on read-only list?"}
    G -->|yes| H[Send once more]
    G -->|no| I[IdbUnavailableError: action may have run]

    classDef new fill:#fff3cd,stroke:#d39e00
    classDef stop fill:#f8d7da,stroke:#c82333
    class D,G new
    class E,F,I stop

Loading

Yellow boxes are new or changed. Red boxes stop the call.

What changes

Call or condition	Before	After
Strict command fails, then the backend is disposed	IDB_COMPANION_UNAVAILABLE with install advice	Error: IDB command interrupted: the backend was disposed during the call; no resend
Non-strict command fails, then the backend is disposed	First result returned	First result returned; no resend (unchanged)
launch / terminate fail with StatusCode.UNAVAILABLE	Resent once	Not resent; falls back to simctl as before
describe, list-apps, screenshot, log, ui describe*, ui wait fail with StatusCode.UNAVAILABLE	Resent once	Resent once (unchanged)
Connect fails and the cleanup also fails	Cleanup error thrown	Connect error thrown
dtuhidd ... was interrupted / did not answer the liveness probe (attempt N of 5) text	Classified as IDB_HID_UNAVAILABLE	Not classified (companion log lines only)
dtuhidd did not answer a liveness probe in 5 attempts ... would be discarded without error	IDB_HID_UNAVAILABLE	IDB_HID_UNAVAILABLE (unchanged)

Decisions for reviewers

Decision	Reason
Throw a new Error with cause, not rethrow the first error	The first error is a raw idb failure, for example Failed to connect to companion. Alone, it looks like a device fault. The new message names the real reason, and cause keeps the detail.
Plain Error, not a new IdbUnavailableError code	Disposal is not a transport fault and has no remediation. A new code would extend the exported type for a teardown path.
Keep one reconnect and one resend for HID invalidation	In the observed incident the connection was already stale, so the first event failed and nothing landed. Only the documentation changes.
Remove retry: unsafe handling	It is unreachable: device-mcp never passes --retry-verdict, and the verdict does not cover HID failures.
Read-only list: describe, list-apps, screenshot, log, ui describe-all, ui describe-point, ui describe, ui wait	It covers every read-only idb command that idb-backend.ts sends. An unknown or new command defaults to "no resend".
Discard the cleanup error instead of attaching it	The connect error is the actionable one. dispose() errors stay visible on explicit disposal.
Mark the #43 selectDevice() entry as BREAKING:	#43 is not released yet, so its entries can still be edited.

Review guide

#	File	What to check
1	src/backends/idb-errors.ts	HID_PATTERNS and their source comments; notDelivered JSDoc
2	src/backends/idb-backend.ts	#idb() disposed checks and interrupted(); isMutatingIdbCommand; #connect() catch
3	src/backends/index.ts	createBackend() catch
4	Tests	idb-errors.test.ts, idb-backend.test.ts (companion recovery block), lazy-backend.test.ts (error propagation)
5	README.md	Recovery table

Testing

• yarn build passes.
• yarn lint passes, including ESLint, formatting, constraints, dependency checks, and changelog validation.
• yarn test passes: 31 files, 663 passed tests, 6 SDK-gated skips. Typechecking and coverage thresholds pass. idb-errors.ts has 100 % coverage.
• New tests, each fails on main and passes on this branch:
  • disposal during a pending ui tap whose first attempt then fails with Failed to connect to companion: rejects with the interruption error, not IdbUnavailableError, no install advice, cause is the first error, one tap only;
  • disposal after a failed command joins a companion that another caller replaced: interruption error, one tap only;
  • launch and terminate on StatusCode.UNAVAILABLE: sent once, then the simctl fallback runs;
  • failed connect with a failing cleanup, in IdbBackend and in createBackend(): the connect error is thrown;
  • the interrupted and per-attempt liveness log lines are not classified.
• Other new tests: describe, list-apps, screenshot and log are still resent once on StatusCode.UNAVAILABLE; a non-strict command whose first attempt fails during disposal is not resent; the 5-attempt liveness error is still classified as IDB_HID_UNAVAILABLE.
• No live simulator run. All changes are in error handling paths that the unit tests drive with mocked exec and companion connections.

Possible follow-ups (out of scope)

• reconnect() stops an active screen recording.
• The selectDevice() hint when the previous backend fails to dispose.
• The simctl lookup in src/utils/platform.ts.
• Cache the companion executable path.
• Classify failures on stderr only.
• unref() the companion stdio.
• Detect a minimum companion version.