Skip to content
Mimic Docs

Windows Session Recovery

Use this runbook when a Windows agent locks unexpectedly or automation stops mid-run after a logoff event.

Path: docs/troubleshooting/LIVE_PATCH_LOCK_SCREEN_FIX.md

Why this exists

Mimic uses a guarded MimicSessionWatchdog that recovers locked sessions without killing active MimicRun_* automation tasks.

Guard rule:

  • If LogonUI.exe is detected and no MimicRun_* task is running, watchdog logs off the locked session to trigger auto-logon.
  • If any MimicRun_* task is running, watchdog skips logoff and writes a guard event to C:\ProgramData\mimic_unlock.log.

This preserves the RPA-first execution path for long-running deterministic jobs.

Script pack

Use JSON command files in /docs/troubleshooting/live-patch-scripts/ with AWS SSM:

  • step1_registry.json registry hardening
  • step2_dcv.json DCV lock/idle settings
  • step3a_unlock_script.json writes unlock script
  • step3b_unlock_task.json registers MimicUnlockSession
  • step4a_watchdog_script.json writes guarded watchdog
  • step4b_watchdog_task.json registers and starts guarded watchdog
  • verify.json post-patch verification
  • diagnose.json pre-patch diagnostics
  • patch_userdata.ps1 all-in-one EC2 User Data fallback

Standard patch flow

  1. Run step1_registry.json.
  2. Run step2_dcv.json.
  3. Run step3a_unlock_script.json, then step3b_unlock_task.json.
  4. Run step4a_watchdog_script.json, then step4b_watchdog_task.json.
  5. Run verify.json.

Fallback when SSM is broken

If SSM is ConnectionLost and cannot recover, stop the instance and apply /docs/troubleshooting/live-patch-scripts/patch_userdata.ps1 as EC2 User Data (base64-encoded), then start the instance.

Use this only for broken agents where the original bootstrap path is no longer recoverable.

Verification targets

Confirm all of the following:

  • MimicUnlockSession exists and is Ready
  • MimicSessionWatchdog exists and is Running
  • watchdog script contains MimicRun_* guard logic
  • DCV os-auto-lock=false
  • no persistent LogonUI.exe when the session is healthy