What it does ADO #582
The TATER Agent (v2.4.15+) continuously watches OneDrive for Business sync health on Windows endpoints and reports problems centrally - the "files aren't where I left them" / "OneDrive icon is gone" / "nothing is syncing" class of help-desk tickets that are otherwise invisible until a user complains. It ships in three layers that build on each other:
- Detect & report - the agent runs 10 health checks every hour and reports the worst grade plus the specific failing signals.
- Admin alerting - confirmed problems appear as Application Monitoring findings and can fire configured SIEM and automation events. Creating an Ops task is opt-in.
- Self-heal & notify (opt-in) - safe inline fixes for the common cases, a desktop toast for the signed-in user, and admin-dispatched scripts for the destructive heals.
The 10 health checks
| Signal | Grade | Meaning | Suggested heal |
|---|---|---|---|
od.client.missing | fail | OneDrive.exe not installed | REM_OD_001 |
od.client.not-running | fail | OneDrive process not running for the active user | REM_OD_003 (Tier 1) |
od.client.buggy-version | warn | Client is on a known data-loss version (e.g. 26.74, ADO #564) | REM_OD_002 |
od.registry.no-business1 | fail | No Business1 account registered - user not signed in | REM_OD_004 |
od.registry.sync-paused | warn | Sync is paused | REM_OD_005 (Tier 1) |
od.cldflt.disabled | critical | Cloud Files filter driver not running - placeholders inaccessible / 0-byte | REM_OD_006 (Tier 1) |
od.cldflt.reparse-orphans | critical | Reparse points with no sync provider - "files not where I left them" | REM_OD_009 (destructive) |
od.kfm.misconfigured | warn | Known Folder Move target mismatch | REM_OD_007 |
od.policy.conflicting | warn | Local ClientPolicy.ini overrides managed Intune ADMX | REM_OD_008 |
od.hydration.fails | fail | Attempted file hydration returned an error | REM_OD_010 (destructive) |
The overall device grade is the worst of any signal: critical > fail > warn > ok.
2-cycle hysteresis - no cry-wolf
OneDrive routinely reports a momentary warning during a reboot, network blip, or large download. To avoid paging IT on transient noise, a signal must appear on two consecutive hourly polls before it is marked confirmed. Only confirmed signals drive alerts, tasks, and heals. The agent persists its cycle state at %ProgramData%\TATER\onedrive-state.json.
Admin alerting
When a confirmed signal reaches the alert threshold (default fail or worse), TATER evaluates the following for an enabled, targeted device:
- Records an Application Monitoring finding with the confirmed problems and suggested heal scripts.
- Creates an Ops task only when
autoCreateTasksis enabled. This setting defaults tofalse. The task groups the device's confirmed problems rather than creating a separate task per signal; eligible tasks are updated as signals change and closed on recovery. - Forwards a
onedrive.health.degradedevent to configured SIEM destinations (andonedrive.health.recoveredon recovery).
Per-org configuration
Detection and finding creation do not require opting in to task creation. An Admin can tune Settings → integrations → onedriveHealth:
| Field | Default | Effect |
|---|---|---|
enabled | true | Master switch for alerting |
minGradeForAlert | fail | Lowest confirmed grade that triggers finding and event evaluation (warn | fail | critical) |
autoCreateTasks | false | Whether to open Ops tasks (SIEM event still fires when off) |
taskAssignee | (none) | Optional email to assign auto-created tasks to |
suppressedDevices | [] | Hostnames that never alert |
Suppressing a noisy device
In Ops → Application Monitoring, find the OneDrive finding and select Suppress. Choose a duration (7, 30, or 90 days) or indefinite suppression. This removes that finding from the open queue and prevents the same finding from re-raising during suppression.
Finding suppression does not disable the OneDrive detector or silence its separate SIEM and automation events. Use the monitor's targeting settings to control which devices it evaluates; see Application Monitoring.
The separate Admin REST endpoint POST /api/onedrive-health/suppress maintains a case-insensitive hostname exclusion with a boolean suppress value. It skips later OneDrive alert evaluation for that hostname, including finding updates, task creation, and SIEM/automation events. Health reports remain stored; this action does not remove existing findings or close existing tasks.
Self-heal & user notification (opt-in)
Self-heal is off by default. Enable it per device by setting onedriveSelfHeal: true in the agent config.json. When on, the agent attempts safe Tier 1 fixes the moment a signal confirms:
| Signal | Tier 1 action | Context |
|---|---|---|
| sync-paused | clear the pause flag + nudge the client | user session |
| client not-running | relaunch OneDrive.exe /background | user session |
| cldflt disabled | start the cldflt service | machine (SYSTEM) |
Every heal is gated for safety: it is never attempted on a known-buggy client version, user-session heals are skipped when the agent runs as SYSTEM (service mode), and the same action is not retried within 6 hours. Outcomes (✅ success / ❌ failed / ⏭️ skipped, with reason) are reported back and visible in the fleet view and the list_onedrive_issues MCP tool.
User notification (Tier 2)
In tray mode, when a confirmed user-impacting issue persists the signed-in user gets a non-alarming Windows toast - framed as "fixed automatically" if a heal succeeded, otherwise "needs attention - IT has been notified; your files are safe." Throttled to at most once per 4 hours.
Destructive heals - admin-dispatch only
The two destructive remediations are never run automatically. They are shipped as scripts an admin dispatches deliberately (e.g. via execute_script targeting the hostname), and each self-gates against known-buggy client versions - running them on a buggy build is the exact data-loss scenario ADO #564 documented.
| Script | What it does | Safety |
|---|---|---|
OneDrive/REM_OD_009_UnregisterSyncRoot.ps1 | Clears orphaned cldflt reparse points via CfUnregisterSyncRoot | SYSTEM context required; version-gated; placeholders carry no local content so no user data is deleted |
OneDrive/REM_OD_010_ResetClient.ps1 | Full onedrive.exe /reset for deep corruption | Version-gated; non-destructive to cloud data; rebuilds the local cache |
Triage workflow (MCP)
For an AI agent (Claude / Copilot) connected to TATER's MCP, the help-desk path is:
list_onedrive_issues- see every endpoint with a OneDrive problem, the confirmed signals (✓), and recent heal outcomes.find_device_by_user(query)- map a user's complaint ("Maria can't open her files") to a hostname.execute_script(hostname, "OneDrive/REM_OD_00X...")- dispatch the suggested heal.- Per the Three-Doc Rule, file a Tasker task documenting the user impact and write a TATERpedia page if the pattern recurs across the fleet.
Platform & scope
OneDrive sync health is Windows-only - macOS and Linux agents run the monitor as a no-op (there is no Microsoft OneDrive sync engine to watch). Data is retained for 30 days per device (Cosmos TTL on the OnedriveHealthInventories container).
Related
- Agent Deployment - install the agent + the v2.4.16 heartbeat/health goroutines
- Fleet Management - the Devices page where OneDrive grades surface
- MCP Setup - connect Claude / Copilot for AI-driven triage