Sentinel Tray and Degraded Desktop Behavior

1. The problem: a green icon must not become a health oracle

Assume the main window is closed, the desktop process is still alive, the background worker continues running, the coordinator becomes unreachable for several minutes, and a credential expires during the outage. A tray that checks only process existence may remain green and present a dangerously false success state. This lesson turns the tray from a source of truth into a projection of explicit runtime evidence.

2. Owned boundary: what LOC-004 owns and what it does not

This lesson owns the sentinel tray and degraded/offline desktop contract: evidence fields, freshness, state reduction, rendering, action gates, reconnect, and recovery. Native command authorization belongs to LOC-002, Tauri capability/CSP exposure belongs to LOC-003, and headless break-glass administration belongs to LOC-005. Do not absorb those outcomes here.

3. Keep five runtime signals independent

At minimum, keep window_state, worker_state, coordinator_state, network_state, and credential_state separate. A closed window does not imply a stopped worker. An online network does not prove coordinator reachability. A reachable coordinator does not make an expired credential valid. Every later decision depends on preserving these distinctions.

4. Evaluate freshness before choosing an icon

A heartbeat is health evidence only while it is inside its declared freshness window. Once its age exceeds freshness_window, the UI must not continue displaying the last known good result as current truth. Preserve a typed STALE or UNKNOWN state and fail closed for sensitive actions until fresh evidence returns.

5. Use a deterministic, typed health reducer

Instead of scattering ad-hoc conditions across UI handlers, create one reducer that maps evidence into states such as ONLINE, DEGRADED, OFFLINE, STALE, UNKNOWN, and CREDENTIAL_BLOCKED. Attach an explicit degraded_reason so rendering, logging, and action gating all consume the same decision.

6. Desktop process, window, and worker are different things

The desktop process may be alive while its window is hidden or closed. A worker may continue after the window closes. Conversely, the tray may still exist while the worker has stopped. Therefore tray presence and worker health are independent claims and must never be collapsed.

7. Fresh worker plus unreachable coordinator is not a dead worker

When the worker heartbeat is fresh but the coordinator or network is unavailable, local worker evidence may still be healthy even though the remote control path is down. The truthful render is a degraded/offline state, not a fabricated worker failure. This distinction prevents the wrong recovery action.

8. Expired credentials are not network failures

The network and coordinator can both be healthy while the credential has expired. In that case remote-required or privileged actions should enter CREDENTIAL_BLOCKED; the UI should not claim the network is down. Accurate reasons produce accurate recovery paths.

9. Action gating is separate from status rendering

Status describes conditions. action_gate decides what can run now. In degraded mode, local-safe actions such as viewing local logs or exporting diagnostics may remain available while remote synchronization or privileged actions stay blocked until their own prerequisites are restored.

10. Offline mode does not manufacture emergency authority

Going offline must not create a privilege shortcut. If an action normally requires remote authority, a valid credential, or another authorization boundary, loss of connectivity does not erase that requirement. Degraded UX should preserve only genuinely local-safe functions and explicitly block or defer the rest.

11. Reconnect and recovery should follow the cause

Coordinator unreachability may call for reconnect. A stopped worker may call for worker restart. An expired credential requires re-authentication. Stale evidence requires observation refresh. A generic “Fix” button without a typed reason invites the wrong recovery action.

12. Tauri tray APIs: do not assume platform parity

Official Tauri v2 documentation provides tray APIs and tray events, but documents an important platform-specific boundary: tray icon events are not emitted on Linux even though the icon can still be shown and a context menu can be displayed on right click. A Windows interaction that relies on a tray click therefore needs a supported Linux alternative.

13. Managed state is coordination machinery, not health-model proof

Tauri managed state can be retrieved through Manager/AppHandle from handlers such as window events. That is useful for connecting UI code to a shared reducer, but it does not prove that the health model is correct or that every concurrency strategy is safe. Evidence semantics and synchronization remain design responsibilities.

14. Lab: Sentinel Tray Degraded-State Contract v1

Eight synthetic fixtures require you to derive health_evidence_state, degraded_reason, status_render_state, action_gate, reconnect_state, recovery_action, decision, and reason. Expected labels are not included in learner-visible files. No real tray, network, credential, privileged action, or operating-system change is required.

15. Transfer: Linux without weakening the gates

Assume the Windows prototype opens recovery UI from a tray click, but that tray event is unavailable on Linux. Rebuild the interaction around the supported context menu or another supported path while keeping the runtime reducer and action prerequisites unchanged. Platform variance should change interaction mechanics, not the truth model.