feat: add Guacamole stale-session repair action

docs/implementation-plan.v1.md

@@ -893,6 +893,9 @@ watchdog/tunnel is bound
 only to the helper's private Docker gateway. Stop the helper before the normal
 `test-host reset`. It is a recovery interface, not a product component or a
 replacement for Guest Control/native test automation.
+The helper's `repair` action may restart only guacd when a dropped browser
+leaves a stale worker holding the fixture's single VRDE slot; it must not
+restart or mutate the Windows VM automatically.
 Because Windows can power off the virtual monitor while the VM remains
 running, `test-host prepare` must also reapply the disposable display/sleep
 keepalive and record `prepare-display-keepalive`. A zero-bpp VRDE framebuffer

test/rdp-access/README.md

@@ -149,6 +149,17 @@ VRDE server. Do not switch the helper to native Windows RDP:
 unusable, stop this helper and use Guest Control for the deterministic portion
 of the work; record the blocked interactive step in the native test report.
 
+If guacd has a stale worker and the VM reports that multiple connections are
+disabled, run:
+
+```sh
+test/rdp-access/rdp-access repair
+```
+
+`repair` restarts only guacd, retains the VM, SSH tunnel, gateway, and IPv6
+forward, and does not alter the Windows guest. Close old browser tabs and sign
+in again after it completes.
+
 The helper requires Docker/Docker Compose, `socat` for the optional public
 dual-stack forward, SSH access through the existing `helium-remote` alias, and
 the fixture password file documented in

test/rdp-access/rdp-access

@@ -30,6 +30,7 @@ usage: test/rdp-access/rdp-access ACTION [OPTIONS]
 Actions:
   up       start a private VRDE SSH tunnel and self-signed HTTPS Guacamole
   status   show gateway, tunnel, and fixture status without changing anything
+  repair   restart only guacd to release a stale single-VRDE-slot worker
   url      print the current browser URL
   logs     follow or print Compose logs (pass Docker Compose log options)
   down     stop containers and the private SSH watchdog/tunnel; retain generated state
@@ -534,6 +535,16 @@ case $action in
         fi
         ipv6_forward_status
         ;;
+    repair)
+        [ "$#" -eq 0 ] || { usage >&2; fail "repair accepts no options"; }
+        docker version >/dev/null
+        docker compose version >/dev/null
+        assert_fixture_running
+        [ -n "$(compose ps -q guacd 2>/dev/null || true)" ] || fail "Guacamole stack is not running; run up first"
+        compose restart guacd >/dev/null
+        wait_for_gateway || fail "Guacamole gateway did not become ready after guacd repair"
+        printf 'guacd restarted; stale VRDE workers released. Close any old browser tab and sign in again.\n'
+        ;;
     url)
         [ "$#" -eq 0 ] || { usage >&2; fail "url accepts no options"; }
         [ -f "$session_file" ] || fail "no saved gateway session; run up first"