HyperHand 0.2.0

Added

• vm_type supports mode: keys through guest Unicode SendInput, preserving the clipboard, limiting text to 16384 UTF-8 bytes and rechecking the selected foreground window between characters. vm_type and vm_key accept optional window selectors; vm_key also accepts an ordered sequence of up to 256 combinations. Partial input is reported without automatic retry.
• vm_screenshot supports a region crop and max_size downscaling, with JSON dimensions, crop origin, actual per-axis scales, VM identity and source/session coordinate metadata. Unknown or non-console agent captures are not marked compatible with console input.
• Read-only vm_controls returns a bounded UI Automation control-view tree for a selected window. A separate helper has a 10-second timeout; password names and subtrees are not read.
• vm_focus_window, window-relative vm_click and window conditions in vm_wait share window selection by handle, PID and case-insensitive title, with optional exact full-title matching. A PID can select a window alone or restrict a title or handle match.
• vm_wait conditions window_exists, window_gone and window_foreground, polled by the host without holding the agent connection between checks. Successful appearance and foreground waits return the window's handle and title; disappearing includes windows that become hidden or cloaked. These use the existing agent list_windows operation without a guest protocol change.
• Dedicated HyperHandService Windows service under NT SERVICE\HyperHandService, with Hyper-V rights assigned to the service account and an access-controlled local named pipe for specific VM operations and the guest socket tunnel.
• Host tray restart action: restarts the ordinary tray/MCP process without restarting the service or any VM; in-progress requests are interrupted.
• vm_start waits until the desktop is usable: the guest agent answers (up to 90 seconds) and the session is unlocked. A session Windows locked after signing in is unlocked with the password stored for the VM; otherwise the error says why the desktop is not usable.
• vm_status reports a VM's power state, the agent, the session lock state, a non-console session, an open UAC prompt and whether an unlock password is stored.
• vm_unlock unlocks a locked session with the stored password. The password is typed once, only after the agent confirms the session is locked, is the console session, shows the sign-in screen with keyboard input on its secure desktop and has no UAC prompt open.
• Host settings window, opened by clicking the tray icon or from its Settings... menu item: the MCP endpoint and port (the port can be changed and is saved per user; -port still overrides it), the service status and a Virtual machines list with the Hyper-V VMs and their state, with Set unlock password... and Clear unlock password per VM (stored in Windows Credential Manager for the current user).
• Open console per VM in the settings window opens Virtual Machine Connection without a UAC prompt, or brings an already open one to the front; Open console when started opens it whenever vm_start starts that VM. install registers the on-demand HyperHand Console task for this, which runs vmconnect.exe with the installing user's highest privileges; uninstall removes it.
• Agent op session_state.
• vm_focus_window and vm_click with a window name the locked session as the reason when they fail on a locked guest.
• vm_windows lists the guest's visible top-level windows with handle, title, class, process, position, enabled, foreground, owner and modal state.
• vm_focus_window accepts a window handle and returns the focused window's handle.
• vm_click accepts window or handle: coordinates are then relative to that window, and the click is refused unless it is the enabled foreground window and the point is inside it, on screen and not covered by another window.

Changed

• vm_status reports busy when this host already has an agent request in progress, without queueing its probe behind that request. Connection and response failures leave the guest state unknown rather than claiming the agent is offline.
• vm_screenshot now returns JSON metadata instead of the former <width>x<height> text item. Cropped and scaled coordinates must be mapped before console input; old agents can still supply images but cannot establish coordinate compatibility.
• Breaking: vm_focus_window now rejects multiple matching windows instead of focusing the first match. All focus requests require an agent supporting list_windows; older agents must be updated, with no fallback to title-only focus. Window clicks and waits also reject ambiguous selection, including disappearance waits.
• Breaking: vm_stop is replaced by vm_shutdown, which shuts the guest down normally through the Hyper-V shutdown integration service and waits up to 3 minutes until the VM is off (failing, without turning it off, when a program blocks shutdown), and vm_turn_off, which turns the VM off immediately as vm_stop did.
• Host tray menu text is in English.
• hyperhand.exe, its tray icon and the settings window use a new gripper icon, from the executable's resources at the system's small and large icon sizes. hyperhand-agent.exe and its tray icon use it too.
• The guest agent tray uses the same notification icon code as the host instead of fyne.io/systray, so it also survives a taskbar that is not ready at logon; a left click opens its menu as before.
• hyperhand-agent.exe uninstall no longer starts a PowerShell helper to delete the folder it runs from after it exits: it moves its own executable to %TEMP% and deletes the folder at once.
• Normal host tray startup no longer requests elevation. Installation, updates and uninstallation still require administrator approval.
• hyperhand.exe install installs both executables under %ProgramFiles%\HyperHand, records the owner under %ProgramData%\HyperHand, and migrates the HyperHand logon task from highest privileges to least privilege. Repeating install updates the installation.
• Host file transfers use the ordinary tray user's permissions. The local MCP endpoint remains unauthenticated; the broker pipe ACL is not MCP authentication.
• scripts/restart-tray.ps1 now invokes installation/update of the built executables instead of terminating every process named hyperhand.exe.
• install and uninstall no longer run an embedded PowerShell script: the elevated hyperhand.exe does the work itself through the service control manager, Task Scheduler, local group and security APIs. Uninstalling from the installed hyperhand.exe leaves %ProgramData%\HyperHand\uninstall-cleanup.exe until the next restart.

Fixed

• Window click checks, focus changes, keyboard sequences and clipboard writes share the input lock, so another MCP input operation cannot invalidate a queued click check or replace text between clipboard setup and paste.
• Elevated command cleanup could hang when an early launcher failure raced a pending named-pipe accept, even after the request deadline. Pin go-winio to Microsoft's listener shutdown fix, which preserves the close signal; the fix is not yet in a tagged release. A repeated early-failure regression test covers this path.
• Reinstalling could stop with "Access is denied" after stopping the service, leaving the service stopped and no tray: setup tried to end the service's process, which runs as the service account. It now waits for that process to exit.
• The host tray icon no longer stays an empty placeholder without menu when the tray starts at logon before the taskbar is ready. The tray now uses its own notification icon code instead of fyne.io/systray: a failed add is retried every 5 seconds and whenever the taskbar is created, and every add carries the icon, tooltip and callback message and selects version 4 behaviour.
• VM start and stop wait up to 45 seconds for asynchronous Hyper-V jobs and report failures or timeouts without automatically resending the operation.
• vm_focus_window no longer puts ribbon programs such as AutoCAD into key-tip mode. When the window did not come to the front at once, the agent simulated an Alt press, which arrived after the switch in the focused window; it now injects a zero-distance mouse move instead.