[iamnbutler]

desktop_click, desktop_key, desktop_system_key, desktop_drag and desktop_insert now take an optional expect: one desktop_wait condition with its arguments, naming what the action should change. From the #75 refresh (top 3, item 3).

• Before input, the condition is read once with the same checker desktop_wait uses. If it already holds, or can't be read reliably (the read fails, or the poll reports an error), the action is refused with nothing sent, because a match afterward wouldn't show the action's effect. For text_changes, that read is the baseline, so the change is measured from before input.
• An unknown outcome polls the condition with desktop_wait's backoff for timeout_ms: 3 s by default, 10 s at most.
  • Holds: the outcome becomes completed, with action.native_outcome: "unknown" and expectation (status matched, the match, and a fresh snapshot for element_appears).
  • Doesn't hold: the outcome stays unknown, with expectation.last_observation.
  • Interrupted: the outcome stays unknown, with expectation status interrupted.
• A completed or refused outcome is returned unchanged, with no polling.
• Input is sent once and never repeated.
• The opt-in is generic. DESKTOP_EXPECT_OPS in protocol.ts lists the ops, the schema is the shared waitCondition plus timeout_ms, and expectAfter(reads, condition, act) in wait.ts wraps any action. A direct client request with expect on another op is refused before input.
• Refactor. waitFor and expectAfter now share poll() and report(), and validateWait takes the timeout cap.
• Scope. TS and docs only. No native change and no patch.

Tests: test/expect.test.mjs has 9 tests, covering the cases below. npm test passes 35 of 35, and npm run check passes.

• upgrade to completed
• timeout stays unknown
• already holds is refused before input
• completed and refused are passed through without polling
• the text_changes baseline comes from before input
• an unreadable condition is refused
• validation
• which tools take expect
• refusal for an op that doesn't take expect

Live checks are pending: screen locked; they're added to #42:

• Command-Space with expect: {until: "window_appears", bundle_id: "com.apple.Spotlight"} should be completed.
• A Finder Command-click with expect element_appears is either completed, or unknown with the last observation.
• A condition that already holds is refused with no keypress.