Troubleshooting

1The companion won't start

The most common cause is a stuck previous-session process holding the pairing-key file open. The companion is single-instance — when one is already running (even without a visible window) the new launch silently exits.

1. Check the system tray first. Look at the bottom-right of your screen near the clock for a green "PC"-shaped icon. If it's there, the companion IS running — just double-click it to bring the window back.
2. Kill any stuck instance. Press Ctrl+Shift+Esc to open Task Manager. On the Details tab, look for WindowsHelperCompanion.exe. Right-click → End task. Repeat until none are listed.
3. Run the .exe again. Double-click from your Downloads folder. Within 2-3 seconds the window appears and the tray icon turns green.
4. Still nothing? Check the rolling diagnostic log at %APPDATA%\WindowsHelper\logs\ — the most recent companion-YYYYMMDD.ndjson file has the start-up record (or the error that prevented one). Open Notepad → File → Open and paste that path to see it.

2Pairing code is rejected

Pairing codes are valid for 5 minutes from when your phone shows them. If you took longer to type, or your phone refreshed the code (some screens rotate codes on every visit), the code your PC sees no longer matches.

1. Get a fresh code from your phone. Open WindowsHelper on your phone → tap PC Control in the bottom navigation. A new 8-character code appears (or the existing one is shown).
2. Watch for the most-easily-confused characters. Codes use uppercase letters and digits — but exclude I, O, 0, and 1 by design. If you typed any of those, you typed wrong.
3. Type the code in the companion window within a minute or two of seeing it on your phone.
4. Internet check. Both your phone and your PC need a working internet connection (the pairing handshake goes through Firestore). A flaky home WiFi can cause the same symptom — try disabling and re-enabling WiFi on whichever device is weaker.

3Commands aren't running on my PC

Three common causes: rate limit (10 commands per minute is the cap on both ends), a pre-flight safety check that refused the command before execution, or a signature mismatch from a stale pairing key after a phone-side re-pair.

1. Check the "Live commands" section in the companion window — every received command gets logged there with its result. If it shows "Pre-check failed" or "Rate limit reached", that's your reason. Wait 60 seconds for the rate window to clear.
2. If the companion never logged the command, the phone never delivered it. Open the WindowsHelper Companion log viewer (right-click tray icon → View logs...) and check for Firestore connection errors in the most recent entries.
3. Re-pair. If signature verification is rejecting your commands, the phone and PC keys are out of sync. Right-click the tray icon → New Pairing Code on the PC, then re-enter the new code on the phone's PC Control screen.
4. Test connectivity by tapping Test connection in the phone's PC Control screen. A successful ping replies in <500 ms with the companion version + uptime. Failure means the wire itself is broken — not your command.

4Phone says "PC offline"

The companion writes a heartbeat to Firestore every 30 seconds. The phone considers the PC offline if the most recent heartbeat is older than ~90 seconds. The most common cause is the PC was sleeping, the companion exited, or the PC's internet went down.

1. Confirm the companion is running. Look at your PC's system tray for the green icon. If it's missing, double-click the .exe in your Downloads folder to relaunch.
2. Wake the PC. If your PC was asleep, the heartbeat stops until it wakes. Move the mouse, then wait 30-60 seconds for the next heartbeat to arrive — the phone's pill flips back to green automatically.
3. Check the PC's internet. Open a browser on the PC and load any website. A failed page load means the heartbeat can't reach Firestore — fix the network, then the heartbeat resumes.
4. Tap Refresh on the phone. Pull-to-refresh on the PC Control screen forces a fresh check of the heartbeat doc. If the PC really is online, the pill updates immediately.

5Antivirus quarantined the .exe

Self-contained .NET .exes are a common false-positive for AV heuristics — they bundle the whole .NET runtime + your code into one file, which looks statistically similar to malware packers to engines that don't recognize the publisher. Code-signing eliminates this; we're working on it. In the meantime:

1. Add an exclusion BEFORE redownloading. Open your antivirus settings (Windows Defender: Settings → Privacy & Security → Windows Security → Virus & threat protection → Manage settings → Add or remove exclusions). Add an exclusion for either:
   • The folder you'll save the .exe to (e.g. C:\Users\YourName\Downloads), or
   • The specific filename WindowsHelperCompanion.exe.
2. Restore from quarantine if it was already removed. Most AV products have a quarantine view (Defender: Virus & threat protection → Protection history). Find the entry, click it, then Allow or Restore.
3. Verify the SHA-256 of your download. If you re-downloaded, confirm the hash matches the one published on /companion-version.json:

(Get-FileHash -Algorithm SHA256 ~\Downloads\WindowsHelperCompanion.exe).Hash

4. Last resort: try a different AV product temporarily. Some bargain-bin AVs flag almost everything; the gold-standard Windows Defender is generally the most accurate. If your AV is the only one flagging this, it's very likely a false positive.