[iamnbutler]

Closes #25.

If a window was minimized after inspection, desktop_insert into it was refused with a raw AX error ("The exact target window could not be verified: AXWindows failed with AX error -25204."). The agent only found the real cause by listing windows.

Change

• When. After any snapshot action in nativeAction (click, scroll, key, type, select, hover, press, element actions, insert) is refused and its exact-window receipt is known, the client reads the app's window mutation inventory once.
• The new refusal. If that window, of the same process generation, is minimized, the error becomes:
  • code: "WINDOW_MINIMIZED", with the message "The target window is minimized, so nothing was sent to it."
  • Hint: "Restore it with desktop_restore, using its target from desktop_windows, then inspect it again before acting."
  • cause keeps the original low-level message.
  • requires_fresh_observation is set to true.
• No cost on success. The check runs only after a refusal, so successful actions pay nothing. unknown and completed results are never rewritten.
• No patch. The check is client-side.
• Not covered. desktop_drag between windows (to_snapshot) isn't covered. Its refusals come from the source and destination checks, before any receipt exists. It could follow the same pattern if needed.
• Docs. docs/tools.md has a sentence on WINDOW_MINIMIZED.

Tests

npm run check passes, and the native build is green. This repo has no client-side Swift tests.

Live checks (pending: screen locked)

• TextEdit: inspect a window with a focused text view, desktop_minimize it, then desktop_insert with the old snapshot → refused, WINDOW_MINIMIZED, and a cause naming the AX failure.
• The same for desktop_click and desktop_key.
• desktop_restore, inspect, insert → completed.
• A refusal on a window that isn't minimized (for example an element ID that isn't in the snapshot) keeps its original message.

🤖 Generated with Claude Code