Add exact window discovery, activation, and bounds control

[zengfanfan]

Summary

• add an exact Window tool with find, activate, and bounds modes
• identify windows by native handle, PID, exact process basename, and exact-or-contains title matching
• return native structured window identity with title, process path, status, and outer/client bounds
• verify foreground readback after activation and actual geometry after bounds changes
• validate identity and geometry arguments before desktop access

Motivation

The existing App tool is intentionally convenience-oriented and supports name-based workflows.
Deterministic automation also needs a separate path that never fuzzy-selects a similarly named or
titled window and that reports the actual identity and geometry Windows applied.

This replaces the withdrawn draft #317 and continues the focused proposal from #316. The branch was
rebuilt directly on current main; it does not contain the earlier draft history.

Public API

Window(mode="find", title="Untitled - Notepad", title_match="contains", process="notepad.exe")
Window(mode="activate", handle=123456, process_id=7890, process="notepad.exe")
Window(mode="bounds", handle=123456, process_id=7890, outer=[x, y, width, height])
Window(mode="bounds", handle=123456, process_id=7890, client=[x, y, width, height])

App behavior is unchanged. Bounds operations report the actual outer and client rectangles after
Windows applies frame, DPI, menu, and minimum-size constraints.

Safety and compatibility

• activation and bounds modes require an explicit positive window handle
• optional PID, process, and title assertions must still match the same live window
• stale handles and ambiguous or mismatched identities fail closed
• activation is verified against foreground readback
• bounds changes wait for the requested geometry and report the last observed geometry on timeout
• the tool is marked destructive because activation and bounds modes mutate desktop state

Testing

• changed-file ruff check: passed
• changed-file ruff format --check: passed
• focused exact-window tests: 30 passed
• full suite on this branch: 382 passed, 3 failed
• full suite on unmodified upstream/main: 352 passed, 3 failed
• the same three tests/test_iserror_compliance.py import failures occur on unmodified
  upstream/main

Real Windows smoke validation with a clean Notepad process passed:

• strict launch returned the launched PID and unique native window handle
• exact find returned one matching handle/PID/process record
• activation foreground readback matched the requested handle
• outer bounds reached 800x600
• client bounds reached exactly 700x480
• stable-bounds polling succeeded
• guarded close and exact window-disappearance polling succeeded

Dependencies and overlap

None. This branch is based directly on current main and is independent of input guards and strict
executable launch. Issue #233 concerns screenshot targeting and does not provide exact discovery,
verified activation, or outer/client bounds control.

[qodo-code-review]

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →