fix: refuse actions on a minimized window with a restore hint (#59)

Co-authored-by: Claude <noreply@anthropic.com>

Author: iamnbutler

docs/tools.md

@@ -82,6 +82,8 @@ With `ocr: true`, `desktop_inspect` (in either mode) and `desktop_screen` also r
 
 `desktop_system_key` is for shortcuts that belong to macOS rather than a window: Spotlight (Command-Space), the app switcher (Command-Tab), Mission Control (Control-Up), the screenshot tools (Command-Shift-4 and 5) and the next input source (Control-Space). It takes the same keys and modifiers as `desktop_key`, but no snapshot. The keys are posted as ordinary keyboard input, so they reach whatever is frontmost, and they often move focus, activate an app or open system UI. Nothing reads back what a shortcut did, so the result is `unknown` even after delivery; observe with `desktop_screen`, `desktop_apps` or `desktop_windows`. Any chord with Command and W, Q, H or M is refused before anything is sent, including Command-Shift-Q (log out).
 
+An action refused because its window was minimized after inspection reports `WINDOW_MINIMIZED`, with the low-level reason as its `cause`. Restore the window with `desktop_restore`, then inspect it again.
+
 ## Not supported
 
 - **Insertion outside text fields.** `desktop_insert` needs an observed focused text control with a readable selection.

native/sources/client/actions.swift

@@ -359,6 +359,7 @@ func nativeAction(_ client: PeekabooBridgeClient, handshake: PeekabooBridgeHands
 			else {
 				throw ActionError("Literal insertion returned without its expected exact-window receipt. Inspect before retrying.")
 			}
+			await explainMinimized(client, &result, receipt: receipt)
 			return try JSONEncoder().encode(ActionReply(data: result, target_receipt: receipt))
 		}
 		let window = try UIAutomationTarget.ExactWindow(identity: identity, bounds: bounds)
@@ -549,9 +550,30 @@ func nativeAction(_ client: PeekabooBridgeClient, handshake: PeekabooBridgeHands
 		)
 		// Unknown completion leaves the host's pending lease in place, including client death or response loss.
 	}
+	await explainMinimized(client, &result, receipt: receipt)
 	return try JSONEncoder().encode(ActionReply(data: result, target_receipt: receipt))
 }
 
+/// Replaces a refusal's low-level cause when the target window turns out to be minimized.
+///
+/// A minimized window can't take input, and Accessibility reads of it fail with raw errors; the check
+/// runs only after a refusal, so actions that succeed pay nothing for it.
+private func explainMinimized(_ client: PeekabooBridgeClient, _ result: inout ActionResult, receipt: Receipt?) async {
+	guard result.outcome == "refused", let receipt, let windowID = receipt.window_id,
+		let inventory = try? await client.listWindowMutationInventory(target: .application("PID:\(receipt.pid)")),
+		let window = inventory.items.first(where: { $0.windowID == windowID }),
+		window.mutationIdentity.map({ String($0.ownerProcessStartIdentity) }) == receipt.process_start_identity_decimal,
+		window.isMinimized
+	else { return }
+	result.error = ActionMessage(
+		code: "WINDOW_MINIMIZED",
+		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: result.error?.message
+	)
+	result.requires_fresh_observation = true
+}
+
 /// Drags from one window into another, in the same app or another one.
 ///
 /// Exact-window delivery can't leave its window, so this moves the real pointer with global events, and