# Troubleshooting Record the release version or commit, Windows edition/build, architecture, selected profile, relevant settings, and the smallest reproducible sequence. Remove credentials, private work data, and managed-device details before sharing diagnostics. ## Build and test Use a Windows developer PowerShell with Visual Studio 2019 or newer. For Visual Studio 2019 Build Tools: ```powershell cmake -S . -B build/x64 -G "Visual Studio 16 2019" -A x64 -DIDLEHARBOR_BUILD_TESTS=ON cmake --build build/x64 --config Release --parallel ctest --test-dir build/x64 -C Release --output-on-failure .\packaging\Test-Packaging.ps1 ``` With Visual Studio 2022, substitute generator `Visual Studio 17 2022`. The optional native viewport smoke needs an interactive desktop, briefly positions the pointer over the settings body, and must run with no other IdleHarbor instance open: ```powershell .\tests\Test-NativeViewportRepaint.ps1 -Executable .\build\x64\Release\IdleHarbor.exe ``` The project is Windows-only. CI additionally builds ARM64 and Win32; release packaging currently targets x64 and ARM64. ## The application does not appear - Start without `--minimized` and confirm the process is not already running. - If a previous instance owns the single-instance mutex, use `IdleHarbor.exe --show`. - If Explorer has restarted, the tray icon may not be present; use `--show` or restart the owner. - Check that the executable is not blocked by endpoint policy. Do not weaken security controls to force an unverified binary to run. ## Settings controls leave fragments after scrolling Record the Windows display scale and whether the session was Running or Stopped. Resize once to force a complete repaint, then repeat the same wheel or scrollbar movement. Current builds repaint the settings viewport and all descendant controls after layout, scrolling, and enabled-state changes. If fragments return, attach before/after screenshots and run the native viewport smoke above from the same build. ## It does not keep the intended state active Read the visible pause reason first. Check genuine-input cooldown, lock/disconnect state, battery threshold, fullscreen policy, active hours, and maximum duration. Motion and power are separate: - `motion=off` with `power=system` or `power=display` uses a Windows power request without pointer movement; - `motion=normal`, `circle`, or `linear` with `power=none` relies on visible input for applications with their own idle detection; - `motion=zen` uses marked virtual input and is not guaranteed to work everywhere. If a power request or input pulse fails, IdleHarbor should show a stopped error. The failure may be caused by Windows integrity boundaries, endpoint policy, or an application that ignores injected input. ## Genuine input and session safeguards The input observer uses Windows low-level hooks and ignores IdleHarbor-marked input. A hook may be unavailable in a restricted environment; the status identifies observer availability. Lock and connect/disconnect handling depends on Windows session notifications. Test these transitions in a non-critical session before relying on them. ### "IdleHarbor could not establish the current lock/disconnect state" The lock state is read from the input desktop, and while the workstation is locked that desktop belongs to Windows rather than to the signed-in user, so the read is refused. Up to and including `v0.2.0` IdleHarbor asked for that state once, during startup, and kept the answer for the life of the process -- so a copy that started while the lock screen still owned the desktop reported the state unavailable forever. Start then refuses any session with the lock or disconnect safeguard enabled, and no action inside the running window clears it. The usual way to land in it is a relaunch at sign-in after a shutdown, restart, or hibernate -- from automatic startup, or from Windows restoring apps that were open -- and launching IdleHarbor by hand in the seconds right after unlocking can do it too. On `v0.2.0` the fix is to exit and start again: choose **Exit** from the tray menu, then launch IdleHarbor while signed in. Closing the window with the red **X** does not do it -- with close-to-tray enabled that only hides the window, and the same process keeps running with the same stale answer. After `v0.2.0` a Start that needs the lock or disconnect safeguard re-reads the state first, and every lock, unlock, connect, and disconnect notification is another chance to read it, so pressing Start again is normally enough. The read still needs the ordinary desktop back, so it can only succeed once the workstation is genuinely unlocked. ## Settings and INI Normal settings live under the user's local application-data directory. Portable mode stores `IdleHarbor.ini` beside the executable; `--config PATH` takes precedence at owner-instance launch. Settings are validated, unknown keys are ignored, and writes use a temporary file followed by an atomic replacement. If an INI value is repeated, not an integer, malformed, out of range, unsupported, or conflicts with another value, IdleHarbor shows every recovery warning, keeps the settings window visible and Stopped, and blocks automatic `--start` or stopped `--toggle` commands. A settings path that exists but cannot be opened is reported the same way, rather than treated as a first run. Review the fallback values, correct the offending key, and press **Save** before relying on automatic startup. An explicit Start action remains user-controlled. For active hours, use minutes from midnight: ```ini active_hours_enabled=true active_hours_start_minute=540 active_hours_end_minute=1080 ``` ## Installation and startup Run the installer with `-WhatIf` first. A Start Menu launcher is created by default; automatic startup is disabled by default and, if enabled, creates only the selected per-user Task Scheduler, Startup-folder, or HKCU Run entry. Use `-StartMenu None` to remove only an unchanged launcher claimed by the install marker. A matching uninstaller preserves a changed or foreign launcher with a warning and removes entries/files only when ownership is proven. The Start Menu link is checked before mutation: directories, reparse points, multiply-linked files, and foreign links are refused where ownership cannot be proven. Caught install/update failures restore the previous managed files, startup state, and exact Start Menu shortcut bytes. Linked managed paths are rejected rather than followed outside the install root. Settings are preserved unless `-PurgeData` is explicitly supplied. ## Report a bug Use the repository bug form with diagnostics and reproduction steps. Security concerns belong in the private advisory flow in [`SECURITY.md`](../SECURITY.md), not a public issue.