Skip to content

YC (S26) | Open Computer History | Continuously record your company computer work, map your workflows, help you find work worth automating, and power your agents' context

fix(health): name why vision is down instead of always blaming permission (#6221)

Louis Beaumont86b8eeed610b
diff --git a/COVERAGE.md b/COVERAGE.md
index 8308f1ec0..013b5eedc 100644
--- a/COVERAGE.md
+++ b/COVERAGE.md
@@ -32,15 +32,15 @@ results and `cargo llvm-cov` data on top when judging release confidence.
- Mapped suites: 32
- Mapped Rust files: 321
-- Active test blocks: 3086
+- Active test blocks: 3098
- Ignored/manual test blocks: 137
-- Weighted coverage points: 2541.6
+- Weighted coverage points: 2550.9
| Platform | Suites | Active tests | Ignored tests | Weighted points | Layers | Flows | Critical score |
| --- | --- | --- | --- | --- | --- | --- | --- |
-| windows | 29 | 2955 | 132 | 2481.6 | 21 | 11 | 100% |
-| macos | 29 | 3008 | 112 | 2492.0 | 22 | 11 | 100% |
-| linux | 25 | 2631 | 105 | 2188.4 | 20 | 11 | 100% |
+| windows | 29 | 2967 | 132 | 2490.9 | 21 | 11 | 100% |
+| macos | 29 | 3020 | 112 | 2501.3 | 22 | 11 | 100% |
+| linux | 25 | 2643 | 105 | 2197.7 | 20 | 11 | 100% |
## Refresh
diff --git a/apps/screenpipe-app-tauri/src-tauri/src/health.rs b/apps/screenpipe-app-tauri/src-tauri/src/health.rs
index c8a3094ce..9f9051058 100644
--- a/apps/screenpipe-app-tauri/src-tauri/src/health.rs
+++ b/apps/screenpipe-app-tauri/src-tauri/src/health.rs
@@ -471,6 +471,11 @@ struct HealthCheckResponse {
last_ui_timestamp: Option<String>,
#[serde(default)]
frame_status: Option<String>,
+ /// Why vision is in `frame_status`. Absent on engines predating the
+ /// reason field, which is why every consumer below treats `None` as "no
+ /// information" and falls back to the old `frame_status` behavior.
+ #[serde(default)]
+ vision_reason: Option<String>,
/// Capture-loop stage the engine last entered, and its age. Explains a
/// `frame_status == "stale"` instead of leaving the incident with only a
/// frozen clock. Absent on engines predating the stage marker.
@@ -577,20 +582,43 @@ fn capture_failure_signals(
);
let unrecovered_vision_failure = vision_progress.observe(health.pipeline.as_ref());
+ // An intentional pixel pause must never raise a capture-failure incident:
+ // it produces no frames by design and would otherwise alarm forever.
+ let vision_paused = vision_intentionally_paused(health);
+
CaptureFailureSignals {
audio,
- vision: vision_status_failed
- || (health.vision_db_write_stalled && unrecovered_vision_failure),
+ vision: !vision_paused
+ && (vision_status_failed
+ || (health.vision_db_write_stalled && unrecovered_vision_failure)),
persistence: health.write_queue_degraded
&& (health.write_queue_consecutive_fatal >= WRITE_QUEUE_FAILURE_THRESHOLD
|| health.write_queue_consecutive_contention >= WRITE_QUEUE_FAILURE_THRESHOLD),
}
}
+/// Vision is off because screenpipe turned it off, not because anything
+/// failed. The engine reports the distinction in `vision_reason` (#5808);
+/// engines predating that field report `None`, which keeps the old behavior.
+///
+/// Load-bearing for the notification path: with `disableScreenshots` set, no
+/// pixel frame ever lands, so `frame_status` sits at `stale` forever. Without
+/// this check that steady, intended state raises a capture-failure incident
+/// and tells the user to go fix a permission that is already granted.
+fn vision_intentionally_paused(health: &HealthCheckResponse) -> bool {
+ matches!(
+ health.vision_reason.as_deref(),
+ Some("disabled_by_setting")
+ | Some("no_displays_expected")
+ | Some("screenshots_disabled_by_config")
+ | Some("screenshots_disabled_by_power_profile")
+ )
+}
+
/// Bare `frame_status == "stale"` — no unique frame AND no capture attempt for
/// 60s. Debounced separately from hard failures; see `crate::stale_tier`.
fn vision_frame_flow_stale(health: &HealthCheckResponse) -> bool {
- health.frame_status.as_deref() == Some("stale")
+ health.frame_status.as_deref() == Some("stale") && !vision_intentionally_paused(health)
}
/// Recovery requires positive proof that both enabled raw-capture paths are
@@ -2095,6 +2123,7 @@ mod tests {
last_audio_timestamp: None,
last_ui_timestamp: None,
frame_status: None,
+ vision_reason: None,
loop_stage: None,
loop_stage_age_secs: None,
audio_status: None,
@@ -2122,6 +2151,7 @@ mod tests {
last_audio_timestamp: None,
last_ui_timestamp: None,
frame_status: None,
+ vision_reason: None,
loop_stage: None,
loop_stage_age_secs: None,
audio_status: None,
@@ -2415,6 +2445,73 @@ mod tests {
// ==================== recording-overlay signal tests ====================
+ /// #5808: with `disableScreenshots` set, no pixel frame ever lands, so
+ /// `frame_status` sits at `stale` forever. That steady, intended state
+ /// used to raise a capture-failure incident and point the user at a
+ /// permission that was already granted.
+ #[test]
+ fn an_intentional_pixel_pause_never_raises_a_capture_failure() {
+ for reason in [
+ "screenshots_disabled_by_config",
+ "screenshots_disabled_by_power_profile",
+ "disabled_by_setting",
+ "no_displays_expected",
+ ] {
+ let mut health = healthy_health();
+ health.frame_status = Some("stale".to_string());
+ health.vision_reason = Some(reason.to_string());
+ health.audio_status = Some("ok".to_string());
+
+ assert!(
+ !vision_frame_flow_stale(&health),
+ "{reason} must not enter the stale-tier notification path",
+ );
+ assert!(
+ !capture_failure_signals(&health, &mut VisionProgressTracker::default()).vision,
+ "{reason} must not be reported as a vision failure",
+ );
+ }
+ }
+
+ /// The pause must not mask a genuine fault either — including the case
+ /// where the engine has separately proven the writer is stuck.
+ #[test]
+ fn a_real_vision_fault_still_reports_while_reasons_are_present() {
+ let mut health = healthy_health();
+ health.frame_status = Some("stale".to_string());
+ health.vision_reason = Some("capture_stalled".to_string());
+ health.audio_status = Some("ok".to_string());
+ assert!(vision_frame_flow_stale(&health));
+
+ health.frame_status = Some("not_started".to_string());
+ assert!(capture_failure_signals(&health, &mut VisionProgressTracker::default()).vision);
+
+ let mut health = healthy_health();
+ health.frame_status = Some("stale".to_string());
+ health.vision_reason = Some("permission_denied".to_string());
+ health.audio_status = Some("ok".to_string());
+ assert!(vision_frame_flow_stale(&health));
+ }
+
+ /// Engines predating `vision_reason` send `None`; behavior must not change
+ /// for them, or upgrading the desktop app ahead of the engine would
+ /// silence real stalls.
+ #[test]
+ fn a_missing_vision_reason_keeps_the_previous_behavior() {
+ let mut health = healthy_health();
+ health.frame_status = Some("stale".to_string());
+ health.vision_reason = None;
+ health.audio_status = Some("ok".to_string());
+ assert!(vision_frame_flow_stale(&health));
+
+ health.frame_status = Some("not_started".to_string());
+ assert!(capture_failure_signals(&health, &mut VisionProgressTracker::default()).vision);
+
+ // An unrecognized future reason is also treated as no information.
+ health.vision_reason = Some("some_future_reason".to_string());
+ assert!(capture_failure_signals(&health, &mut VisionProgressTracker::default()).vision);
+ }
+
#[test]
fn transcription_backlog_is_not_a_recording_failure() {
let mut health = healthy_health();
diff --git a/crates/screenpipe-engine/src/event_driven_capture.rs b/crates/screenpipe-engine/src/event_driven_capture.rs
index 404e49cc1..c18ed793e 100644
--- a/crates/screenpipe-engine/src/event_driven_capture.rs
+++ b/crates/screenpipe-engine/src/event_driven_capture.rs
@@ -867,6 +867,20 @@ fn record_loop_stage(
monitor.record_loop_stage(stage);
}
+/// Publish whether this loop is taking screenshots, and if not why, so
+/// `/health` can tell an intentional pixel pause apart from a capture failure
+/// (#5808). Both inputs are process-global (a config flag and the active power
+/// profile), so every monitor's loop writes the same value and last-writer-wins
+/// on the aggregate is correct.
+fn record_screenshot_capture_state(
+ aggregate: &screenpipe_screen::PipelineMetrics,
+ monitor: &screenpipe_screen::PipelineMetrics,
+ state: screenpipe_screen::ScreenshotCaptureState,
+) {
+ aggregate.record_screenshot_capture_state(state);
+ monitor.record_screenshot_capture_state(state);
+}
+
fn record_persisted_capture(
aggregate: &screenpipe_screen::PipelineMetrics,
monitor: &screenpipe_screen::PipelineMetrics,
@@ -926,6 +940,13 @@ pub(crate) async fn event_driven_capture_loop(
let screenshots_disabled_by_config = config.disable_screenshots;
let mut screenshot_disabled = screenshots_disabled_by_config;
+ // Publish the effective state so /health can name an intentional pixel
+ // pause instead of blaming Screen Recording permission for it (#5808).
+ record_screenshot_capture_state(
+ &vision_metrics,
+ &monitor_liveness,
+ screenpipe_screen::ScreenshotCaptureState::resolve(screenshots_disabled_by_config, false),
+ );
let mut visual_check_enabled = config.visual_check_interval_ms > 0 && !screenshot_disabled;
let mut visual_check_interval = Duration::from_millis(config.visual_check_interval_ms);
let mut visual_change_threshold = config.visual_change_threshold;
@@ -1466,6 +1487,14 @@ pub(crate) async fn event_driven_capture_loop(
visual_check_interval = Duration::from_millis(profile.visual_check_interval_ms);
visual_change_threshold = profile.visual_change_threshold;
screenshot_disabled = screenshots_disabled_by_config || profile.screenshot_disabled;
+ record_screenshot_capture_state(
+ &vision_metrics,
+ &monitor_liveness,
+ screenpipe_screen::ScreenshotCaptureState::resolve(
+ screenshots_disabled_by_config,
+ profile.screenshot_disabled,
+ ),
+ );
visual_check_enabled = profile.visual_check_interval_ms > 0 && !screenshot_disabled;
if visual_check_enabled && frame_comparer.is_none() {
frame_comparer =
diff --git a/crates/screenpipe-engine/src/permission_monitor.rs b/crates/screenpipe-engine/src/permission_monitor.rs
index 9382c2987..244ff21bd 100644
--- a/crates/screenpipe-engine/src/permission_monitor.rs
+++ b/crates/screenpipe-engine/src/permission_monitor.rs
@@ -338,6 +338,20 @@ pub fn screen_enumeration_denied() -> bool {
state.screen_enum_denied
}
+/// Last known screen-recording grant, as seen by the 5s poll and by
+/// capture-side enumeration. Cheap: a mutex read, never a TCC syscall, so
+/// `/health` can consult it on every request.
+///
+/// `false` means the most recent evidence says screen capture is not
+/// permitted — either the poll saw the grant revoked, or enumeration proved
+/// capture is broken while the preflight still (stale-ly) answers granted.
+/// Callers must not treat `true` as proof that capture is working; it only
+/// rules permission out as the explanation.
+pub fn screen_recording_granted() -> bool {
+ let state = STATE.lock().unwrap_or_else(|e| e.into_inner());
+ state.screen.granted && !state.screen_enum_denied
+}
+
/// Read-only probe of the OS keychain. Returns `true` if the encryption key
/// is currently readable (user has opted into encryption AND the keychain
/// hasn't locked us out). Non-macOS or missing-keychain environments report
diff --git a/crates/screenpipe-engine/src/routes/health.rs b/crates/screenpipe-engine/src/routes/health.rs
index d1a0b41e4..a2547ca86 100644
--- a/crates/screenpipe-engine/src/routes/health.rs
+++ b/crates/screenpipe-engine/src/routes/health.rs
@@ -229,6 +229,130 @@ pub(crate) fn classify_vision_stall(
}
}
+/// Why vision is not fully recording, in terms the user can act on.
+///
+/// Before this existed, `/health` had one "off" string (`"disabled"`) plus
+/// `"stale"`, and [`get_verbose_instructions`] answered every non-ok vision
+/// state with "check if screen recording permissions are enabled" — without
+/// ever consulting a permission result. A user whose pixels were off because
+/// screenpipe itself turned them off was sent to macOS System Settings to fix
+/// a permission that was already granted (#5808).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum VisionReason {
+ /// Vision is recording normally.
+ Ok,
+ /// `--disable-vision` / the `disableVision` setting. No vision at all.
+ DisabledBySetting,
+ /// Every selected display is user-paused, asleep, or inactive.
+ NoDisplaysExpected,
+ /// `disableScreenshots`: pixels are off on purpose, a11y text continues.
+ ScreenshotsDisabledByConfig,
+ /// The active power profile turned pixels off (low battery / low-power).
+ ScreenshotsDisabledByPowerProfile,
+ /// The OS is refusing screen capture. The only reason that warrants
+ /// permission advice.
+ PermissionDenied,
+ /// Capture is permitted and expected, but frames stopped arriving.
+ CaptureStalled,
+ /// Capture is permitted and expected, but never produced a first frame.
+ NotStarted,
+}
+
+impl VisionReason {
+ /// Stable wire name for the health response.
+ pub(crate) fn as_str(self) -> &'static str {
+ match self {
+ Self::Ok => "ok",
+ Self::DisabledBySetting => "disabled_by_setting",
+ Self::NoDisplaysExpected => "no_displays_expected",
+ Self::ScreenshotsDisabledByConfig => "screenshots_disabled_by_config",
+ Self::ScreenshotsDisabledByPowerProfile => "screenshots_disabled_by_power_profile",
+ Self::PermissionDenied => "permission_denied",
+ Self::CaptureStalled => "capture_stalled",
+ Self::NotStarted => "not_started",
+ }
+ }
+
+ /// Whether this reason is a fault the user should be told to fix.
+ /// Intentional pauses are not: they are the app doing what it was told.
+ pub(crate) fn is_fault(self) -> bool {
+ matches!(
+ self,
+ Self::PermissionDenied | Self::CaptureStalled | Self::NotStarted
+ )
+ }
+
+ /// The recovery step for this reason, or `None` when nothing is wrong.
+ /// Permission advice appears here for exactly one reason — the one backed
+ /// by an actual permission result.
+ pub(crate) fn instruction(self) -> Option<&'static str> {
+ match self {
+ Self::Ok => None,
+ // Deliberately avoids the phrase "screen recording": that is the
+ // name of the macOS permission, and reusing it here is what makes
+ // an intentional off-state read as a permission fault.
+ Self::DisabledBySetting => {
+ Some("Screen capture is turned off in screenpipe. Turn it back on in Settings → Recording.")
+ }
+ Self::NoDisplaysExpected => {
+ Some("No display is being recorded — every selected monitor is paused or asleep. Resume one in Settings → Recording.")
+ }
+ Self::ScreenshotsDisabledByConfig => {
+ Some("Screenshots are turned off in screenpipe, so only on-screen text is being captured. Re-enable them in Settings → Recording. This is not a permission problem.")
+ }
+ Self::ScreenshotsDisabledByPowerProfile => {
+ Some("Screenshots are paused to save power and will resume on their own once the battery recovers or the machine leaves low-power mode. Only on-screen text is being captured until then. This is not a permission problem.")
+ }
+ Self::PermissionDenied => {
+ Some("macOS is blocking screen capture. Grant Screen Recording to screenpipe in System Settings → Privacy & Security, then restart the app.")
+ }
+ Self::CaptureStalled => {
+ Some("Screen capture stopped producing frames. Restarting screenpipe usually clears it; if it returns, please send logs from the Help section.")
+ }
+ Self::NotStarted => {
+ Some("Screen capture has not produced a frame yet. If this persists, please send logs from the Help section.")
+ }
+ }
+ }
+}
+
+/// Classify vision into a single actionable reason.
+///
+/// Ordering is deliberate. Intentional off-states are checked before any
+/// fault, because a user who turned pixels off does not have a problem — and
+/// must not be handed a permission instruction for a permission that is fine.
+/// `permission_granted` is the last-known result from the permission monitor's
+/// 5s poll and capture-side enumeration, never a fresh syscall.
+pub(crate) fn classify_vision_reason(
+ vision_disabled: bool,
+ displays_expected: bool,
+ screenshot_state: screenpipe_screen::ScreenshotCaptureState,
+ permission_granted: bool,
+ frame_status: &str,
+) -> VisionReason {
+ use screenpipe_screen::ScreenshotCaptureState as S;
+
+ if vision_disabled {
+ return VisionReason::DisabledBySetting;
+ }
+ if !displays_expected {
+ return VisionReason::NoDisplaysExpected;
+ }
+ match screenshot_state {
+ S::DisabledByConfig => return VisionReason::ScreenshotsDisabledByConfig,
+ S::DisabledByPowerProfile => return VisionReason::ScreenshotsDisabledByPowerProfile,
+ S::Enabled => {}
+ }
+ // Only now can a missing frame be a real fault — and permission is only
+ // the answer when the permission monitor actually says so.
+ match frame_status {
+ "ok" | "disabled" => VisionReason::Ok,
+ _ if !permission_granted => VisionReason::PermissionDenied,
+ "not_started" => VisionReason::NotStarted,
+ _ => VisionReason::CaptureStalled,
+ }
+}
+
const SILENT_AUDIO_RMS_THRESHOLD: f64 = 0.001;
/// How recently the audio stream-timeout watchdog must have fired for the audio
@@ -462,6 +586,18 @@ pub struct HealthCheckResponse {
pub last_frame_timestamp: Option<chrono::DateTime<Utc>>,
pub last_audio_timestamp: Option<chrono::DateTime<Utc>>,
pub frame_status: String,
+ /// Why vision is in `frame_status`, as a stable machine-readable reason:
+ /// `ok`, `disabled_by_setting`, `no_displays_expected`,
+ /// `screenshots_disabled_by_config`,
+ /// `screenshots_disabled_by_power_profile`, `permission_denied`,
+ /// `capture_stalled`, `not_started`.
+ ///
+ /// `frame_status` alone collapses "screenpipe turned pixels off" and "the
+ /// OS is blocking capture" into the same value, which is how #5808 sent
+ /// users to the permission screen for a permission that was already
+ /// granted. Clients should prefer this field when choosing what to tell
+ /// the user; only `permission_denied` warrants permission guidance.
+ pub vision_reason: String,
/// Capture-loop stage last entered, and how long ago. A frozen loop is the
/// only thing that can make `frame_status` stale (it is a max of the DB
/// write, capture attempt and loop heartbeat clocks), so these two fields
@@ -775,6 +911,7 @@ fn degraded_response() -> HealthCheckResponse {
last_frame_timestamp: None,
last_audio_timestamp: None,
frame_status: "unknown".to_string(),
+ vision_reason: "unknown".to_string(),
loop_stage: "unknown".to_string(),
loop_stage_age_secs: None,
audio_status: "unknown".to_string(),
@@ -1269,6 +1406,16 @@ async fn health_check_inner(state: &Arc<AppState>) -> HealthCheckResponse {
"stale"
};
+ // Why vision is in that state, in terms the user can act on. Permission is
+ // only ever named when the permission monitor's last known result says so.
+ let vision_reason = classify_vision_reason(
+ state.vision_disabled,
+ vision_capture_expected,
+ state.vision_metrics.screenshot_capture_state(),
+ crate::permission_monitor::screen_recording_granted(),
+ frame_status,
+ );
+
// Cross-check: if audio is enabled, uptime > 2 min, but zero chunks were ever
// sent, the audio pipeline never started capturing (e.g. device retry loop).
// The per-device timestamp fallback would mask this as "ok", so override here.
@@ -1462,7 +1609,10 @@ async fn health_check_inner(state: &Arc<AppState>) -> HealthCheckResponse {
)
} else {
let mut unhealthy_systems = Vec::new();
- if frame_status != "ok" && frame_status != "disabled" {
+ // An intentional pixel pause is not an unhealthy system: it is the app
+ // doing what it was configured to do. Reporting it as a fault is what
+ // dragged users to the permission screen in #5808.
+ if frame_status != "ok" && frame_status != "disabled" && vision_reason.is_fault() {
unhealthy_systems.push("vision");
}
if vision_degraded && !unhealthy_systems.contains(&"vision") {
@@ -1552,7 +1702,7 @@ async fn health_check_inner(state: &Arc<AppState>) -> HealthCheckResponse {
(
"degraded",
msg,
- Some(get_verbose_instructions(&unhealthy_systems)),
+ Some(get_verbose_instructions(&unhealthy_systems, vision_reason)),
503,
)
};
@@ -1625,6 +1775,7 @@ async fn health_check_inner(state: &Arc<AppState>) -> HealthCheckResponse {
None
},
frame_status: frame_status.to_string(),
+ vision_reason: vision_reason.as_str().to_string(),
loop_stage: vision_loop_stage.as_str().to_string(),
loop_stage_age_secs: vision_loop_stage_entered_ts
.and_then(|ts| (ts > 0).then(|| now_ts.saturating_sub(ts))),
@@ -1772,11 +1923,25 @@ pub(crate) async fn audio_metrics_handler(
JsonResponse(state.audio_metrics.snapshot())
}
-pub(crate) fn get_verbose_instructions(unhealthy_systems: &[&str]) -> String {
+pub(crate) fn get_verbose_instructions(
+ unhealthy_systems: &[&str],
+ vision_reason: VisionReason,
+) -> String {
let mut instructions = String::new();
if unhealthy_systems.contains(&"vision") {
- instructions.push_str("Vision system is not working properly. Check if screen recording permissions are enabled.\n");
+ // Name the actual cause. This used to be an unconditional "check if
+ // screen recording permissions are enabled", which pointed users at
+ // System Settings even when screenpipe had turned pixels off itself.
+ match vision_reason.instruction() {
+ Some(step) => {
+ instructions.push_str(step);
+ instructions.push('\n');
+ }
+ None => instructions.push_str(
+ "Vision system is not working properly. Please send logs from the Help section.\n",
+ ),
+ }
}
if unhealthy_systems.contains(&"audio") {
@@ -1977,6 +2142,178 @@ mod vision_stall_classification_tests {
}
}
+/// #5808: `/health` blamed Screen Recording permission for every non-ok vision
+/// state, including the ones screenpipe itself caused. These pin the reason
+/// each state maps to, and that permission is only ever named when a
+/// permission result actually says so.
+#[cfg(test)]
+mod vision_reason_tests {
+ use super::*;
+ use screenpipe_screen::ScreenshotCaptureState as S;
+
+ const GRANTED: bool = true;
+ const DENIED: bool = false;
+
+ /// The reported case: permission is fine, screenpipe disabled screenshots
+ /// via config, capture goes stale because no pixel frame ever lands.
+ #[test]
+ fn config_disabled_screenshots_is_not_a_permission_problem() {
+ let reason = classify_vision_reason(false, true, S::DisabledByConfig, GRANTED, "stale");
+ assert_eq!(reason, VisionReason::ScreenshotsDisabledByConfig);
+ assert!(!reason.is_fault(), "an intentional pause is not a fault");
+
+ let instruction = reason.instruction().expect("names a recovery step");
+ assert!(instruction.contains("Settings → Recording"));
+ assert!(instruction.contains("not a permission problem"));
+ assert!(!instruction.to_lowercase().contains("screen recording"));
+ }
+
+ /// Low battery / OS low-power turns pixels off. It recovers on its own, so
+ /// the user must not be sent anywhere.
+ #[test]
+ fn power_profile_disabled_screenshots_is_not_a_permission_problem() {
+ let reason =
+ classify_vision_reason(false, true, S::DisabledByPowerProfile, GRANTED, "stale");
+ assert_eq!(reason, VisionReason::ScreenshotsDisabledByPowerProfile);
+ assert!(!reason.is_fault());
+
+ let instruction = reason.instruction().unwrap();
+ assert!(instruction.contains("resume on their own"));
+ assert!(instruction.contains("not a permission problem"));
+ }
+
+ /// The one case that earns the permission instruction.
+ #[test]
+ fn a_denied_permission_is_the_only_state_that_mentions_permission() {
+ let reason = classify_vision_reason(false, true, S::Enabled, DENIED, "stale");
+ assert_eq!(reason, VisionReason::PermissionDenied);
+ assert!(reason.is_fault());
+ assert!(reason.instruction().unwrap().contains("Screen Recording"));
+
+ // Every other reason must stay silent about permission.
+ for other in [
+ VisionReason::Ok,
+ VisionReason::DisabledBySetting,
+ VisionReason::NoDisplaysExpected,
+ VisionReason::ScreenshotsDisabledByConfig,
+ VisionReason::ScreenshotsDisabledByPowerProfile,
+ VisionReason::CaptureStalled,
+ VisionReason::NotStarted,
+ ] {
+ let text = other.instruction().unwrap_or("").to_lowercase();
+ assert!(
+ !text.contains("screen recording") && !text.contains("privacy & security"),
+ "{other:?} must not send the user to the permission screen: {text}"
+ );
+ }
+ }
+
+ /// Permission granted, pixels enabled, frames stopped: a real stall.
+ #[test]
+ fn a_genuine_capture_stall_is_reported_as_a_stall() {
+ let reason = classify_vision_reason(false, true, S::Enabled, GRANTED, "stale");
+ assert_eq!(reason, VisionReason::CaptureStalled);
+ assert!(reason.is_fault());
+
+ let reason = classify_vision_reason(false, true, S::Enabled, GRANTED, "not_started");
+ assert_eq!(reason, VisionReason::NotStarted);
+ assert!(reason.is_fault());
+ }
+
+ #[test]
+ fn intentional_off_states_outrank_any_frame_status() {
+ assert_eq!(
+ classify_vision_reason(true, true, S::Enabled, DENIED, "stale"),
+ VisionReason::DisabledBySetting,
+ "vision off by setting is not a permission story even if permission is denied",
+ );
+ assert_eq!(
+ classify_vision_reason(false, false, S::Enabled, DENIED, "stale"),
+ VisionReason::NoDisplaysExpected,
+ );
+ for reason in [
+ VisionReason::DisabledBySetting,
+ VisionReason::NoDisplaysExpected,
+ ] {
+ assert!(!reason.is_fault());
+ }
+ }
+
+ /// Config wins over the power profile: it is what the user set, and it
+ /// stays true after the battery recovers.
+ #[test]
+ fn config_outranks_the_power_profile_when_both_disable_pixels() {
+ assert_eq!(
+ S::resolve(true, true),
+ S::DisabledByConfig,
+ "the durable cause is the one worth naming",
+ );
+ assert_eq!(S::resolve(false, true), S::DisabledByPowerProfile);
+ assert_eq!(S::resolve(true, false), S::DisabledByConfig);
+ assert_eq!(S::resolve(false, false), S::Enabled);
+ }
+
+ #[test]
+ fn a_healthy_or_disabled_frame_status_reports_ok() {
+ for status in ["ok", "disabled"] {
+ assert_eq!(
+ classify_vision_reason(false, true, S::Enabled, GRANTED, status),
+ VisionReason::Ok,
+ );
+ }
+ assert_eq!(VisionReason::Ok.instruction(), None);
+ assert!(!VisionReason::Ok.is_fault());
+ }
+
+ /// The wire contract: every variant has a distinct, stable name.
+ #[test]
+ fn reason_names_are_distinct_and_snake_case() {
+ let all = [
+ VisionReason::Ok,
+ VisionReason::DisabledBySetting,
+ VisionReason::NoDisplaysExpected,
+ VisionReason::ScreenshotsDisabledByConfig,
+ VisionReason::ScreenshotsDisabledByPowerProfile,
+ VisionReason::PermissionDenied,
+ VisionReason::CaptureStalled,
+ VisionReason::NotStarted,
+ ];
+ let names: std::collections::HashSet<_> = all.iter().map(|r| r.as_str()).collect();
+ assert_eq!(names.len(), all.len(), "reason names must be unique");
+ for name in names {
+ assert!(
+ name.chars().all(|c| c.is_ascii_lowercase() || c == '_'),
+ "{name} is not snake_case",
+ );
+ }
+ }
+
+ /// The instruction the user actually sees, through the real entry point.
+ #[test]
+ fn verbose_instructions_name_the_cause_instead_of_permission() {
+ let config =
+ get_verbose_instructions(&["vision"], VisionReason::ScreenshotsDisabledByConfig);
+ assert!(config.contains("Screenshots are turned off in screenpipe"));
+ assert!(!config.to_lowercase().contains("screen recording"));
+
+ let denied = get_verbose_instructions(&["vision"], VisionReason::PermissionDenied);
+ assert!(denied.contains("Screen Recording"));
+
+ // Audio guidance is untouched, and both can appear together.
+ let both = get_verbose_instructions(
+ &["vision", "audio"],
+ VisionReason::ScreenshotsDisabledByPowerProfile,
+ );
+ assert!(both.contains("resume on their own"));
+ assert!(both.contains("microphone permissions"));
+
+ // No unhealthy system: vision guidance must not leak in.
+ let none = get_verbose_instructions(&[], VisionReason::PermissionDenied);
+ assert!(!none.contains("Screen Recording"));
+ assert!(none.contains("Discord"));
+ }
+}
+
#[cfg(test)]
mod tests {
use super::*;
@@ -2042,6 +2379,7 @@ mod tests {
last_frame_timestamp: None,
last_audio_timestamp: None,
frame_status: "ok".to_string(),
+ vision_reason: "ok".to_string(),
loop_stage: "unknown".to_string(),
loop_stage_age_secs: None,
audio_status: "ok".to_string(),
diff --git a/crates/screenpipe-screen/src/lib.rs b/crates/screenpipe-screen/src/lib.rs
index cadcc7b6c..6bd419557 100644
--- a/crates/screenpipe-screen/src/lib.rs
+++ b/crates/screenpipe-screen/src/lib.rs
@@ -23,7 +23,9 @@ pub mod utils;
#[cfg(target_os = "macos")]
pub use apple::perform_ocr_apple;
pub use core::RealtimeVisionEvent;
-pub use metrics::{CaptureLoopStage, MetricsSnapshot, OcrGateDecision, PipelineMetrics};
+pub use metrics::{
+ CaptureLoopStage, MetricsSnapshot, OcrGateDecision, PipelineMetrics, ScreenshotCaptureState,
+};
pub use utils::OcrEngine;
pub mod capture_screenshot_by_window;
pub use custom_ocr::perform_ocr_custom;
diff --git a/crates/screenpipe-screen/src/metrics.rs b/crates/screenpipe-screen/src/metrics.rs
index e3a886a6b..7ed4bdf3e 100644
--- a/crates/screenpipe-screen/src/metrics.rs
+++ b/crates/screenpipe-screen/src/metrics.rs
@@ -95,6 +95,71 @@ pub enum CaptureLoopStage {
HotCachePush = 12,
}
+/// Whether the capture loop is currently taking screenshots, and if not, why.
+///
+/// The loop derives this from `config.disable_screenshots || profile
+/// .screenshot_disabled`, and neither input was visible outside the loop's own
+/// stack. `/health` therefore could not tell "screenpipe turned pixels off on
+/// purpose" apart from "the OS is refusing to hand us frames", and told every
+/// user to go check Screen Recording permission. Publishing the effective
+/// state here lets health name the real cause.
+///
+/// Discriminants are stable: they are stored in an [`AtomicU8`], so only
+/// append new variants.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[repr(u8)]
+pub enum ScreenshotCaptureState {
+ /// Screenshots are being taken.
+ Enabled = 0,
+ /// `--disable-screenshots` / the `disableScreenshots` setting. The
+ /// accessibility walk continues, so text capture is unaffected.
+ DisabledByConfig = 1,
+ /// The active power profile turned pixels off (low battery / OS low-power).
+ /// Restores itself when the machine leaves that profile.
+ DisabledByPowerProfile = 2,
+}
+
+impl ScreenshotCaptureState {
+ /// Resolve the effective state from the two inputs the capture loop uses.
+ /// Config wins when both apply: it is the one the user set deliberately
+ /// and the one that stays true after the battery recovers.
+ pub fn resolve(disabled_by_config: bool, disabled_by_power_profile: bool) -> Self {
+ if disabled_by_config {
+ Self::DisabledByConfig
+ } else if disabled_by_power_profile {
+ Self::DisabledByPowerProfile
+ } else {
+ Self::Enabled
+ }
+ }
+
+ /// Stable wire name. Kept exhaustive so a new variant cannot silently
+ /// report as "enabled".
+ pub fn as_str(self) -> &'static str {
+ match self {
+ Self::Enabled => "enabled",
+ Self::DisabledByConfig => "disabled_by_config",
+ Self::DisabledByPowerProfile => "disabled_by_power_profile",
+ }
+ }
+
+ /// True when pixel capture is off for any reason.
+ pub fn is_disabled(self) -> bool {
+ !matches!(self, Self::Enabled)
+ }
+
+ fn from_u8(value: u8) -> Self {
+ match value {
+ 1 => Self::DisabledByConfig,
+ 2 => Self::DisabledByPowerProfile,
+ // Unknown discriminants mean a newer writer than this reader.
+ // Treating that as "enabled" keeps health from inventing an
+ // intentional-disable excuse for a state it cannot name.
+ _ => Self::Enabled,
+ }
+ }
+}
+
impl CaptureLoopStage {
/// Human-readable name for logs. Kept exhaustive so a new variant cannot
/// silently log as "unknown".
@@ -231,6 +296,11 @@ pub struct PipelineMetrics {
pub loop_stage: AtomicU8,
/// Unix timestamp (secs) at which `loop_stage` was last set.
pub loop_stage_entered_ts: AtomicU64,
+ /// Effective [`ScreenshotCaptureState`] discriminant, published by the
+ /// capture loop whenever it re-derives `screenshot_disabled`. Lets
+ /// `/health` distinguish an intentional pixel-capture pause from a real
+ /// capture failure instead of blaming OS permission for both.
+ pub screenshot_capture_state: AtomicU8,
/// Total number of capture operations attempted, regardless of outcome.
/// Pair with `frames_captured` (successful persists) to detect silent loss between
/// attempt and write — `attempts - captured - dedup_skips` over a window that should
@@ -287,6 +357,7 @@ impl PipelineMetrics {
capture_loop_heartbeats: AtomicU64::new(0),
loop_stage: AtomicU8::new(CaptureLoopStage::Unknown as u8),
loop_stage_entered_ts: AtomicU64::new(0),
+ screenshot_capture_state: AtomicU8::new(ScreenshotCaptureState::Enabled as u8),
capture_attempts: AtomicU64::new(0),
dedup_skips: AtomicU64::new(0),
frames_corrupt_black: AtomicU64::new(0),
@@ -347,6 +418,19 @@ impl PipelineMetrics {
)
}
+ /// Publish whether the capture loop is taking screenshots, and if not why.
+ /// Called by the loop every time it re-derives `screenshot_disabled`, so
+ /// `/health` always sees the state the loop is actually running under.
+ pub fn record_screenshot_capture_state(&self, state: ScreenshotCaptureState) {
+ self.screenshot_capture_state
+ .store(state as u8, Ordering::Relaxed);
+ }
+
+ /// Effective screenshot-capture state last published by the capture loop.
+ pub fn screenshot_capture_state(&self) -> ScreenshotCaptureState {
+ ScreenshotCaptureState::from_u8(self.screenshot_capture_state.load(Ordering::Relaxed))
+ }
+
/// Record that a frame was skipped by similarity check.
pub fn record_skip(&self) {
self.frames_skipped.fetch_add(1, Ordering::Relaxed);
@@ -730,6 +814,59 @@ mod tests {
use super::*;
use std::time::Duration;
+ /// #5808: the capture loop's effective screenshot state has to survive the
+ /// trip to /health, or health falls back to blaming OS permission.
+ #[test]
+ fn screenshot_capture_state_round_trips_through_the_atomic() {
+ let metrics = PipelineMetrics::new();
+ assert_eq!(
+ metrics.screenshot_capture_state(),
+ ScreenshotCaptureState::Enabled,
+ "a loop that never published must not look intentionally disabled",
+ );
+
+ for state in [
+ ScreenshotCaptureState::DisabledByConfig,
+ ScreenshotCaptureState::DisabledByPowerProfile,
+ ScreenshotCaptureState::Enabled,
+ ] {
+ metrics.record_screenshot_capture_state(state);
+ assert_eq!(metrics.screenshot_capture_state(), state);
+ assert_eq!(
+ state.is_disabled(),
+ state != ScreenshotCaptureState::Enabled
+ );
+ }
+ }
+
+ /// A newer writer may store a discriminant this reader does not know.
+ /// Reading it as "enabled" keeps health from inventing an
+ /// intentional-disable excuse for a state it cannot name.
+ #[test]
+ fn an_unknown_screenshot_state_reads_as_enabled() {
+ let metrics = PipelineMetrics::new();
+ metrics
+ .screenshot_capture_state
+ .store(200, Ordering::Relaxed);
+ assert_eq!(
+ metrics.screenshot_capture_state(),
+ ScreenshotCaptureState::Enabled,
+ );
+ }
+
+ #[test]
+ fn screenshot_state_names_are_stable_and_distinct() {
+ assert_eq!(ScreenshotCaptureState::Enabled.as_str(), "enabled");
+ assert_eq!(
+ ScreenshotCaptureState::DisabledByConfig.as_str(),
+ "disabled_by_config"
+ );
+ assert_eq!(
+ ScreenshotCaptureState::DisabledByPowerProfile.as_str(),
+ "disabled_by_power_profile"
+ );
+ }
+
#[test]
fn loop_heartbeat_advances_without_a_capture_attempt() {
let metrics = PipelineMetrics::new();
diff --git a/docs/coverage/CORE.md b/docs/coverage/CORE.md
index c9bf3ea0f..24ab3da44 100644
--- a/docs/coverage/CORE.md
+++ b/docs/coverage/CORE.md
@@ -9,10 +9,10 @@ confidence, and criticality.
- Tracked crates: screenpipe-engine, screenpipe-db, screenpipe-sqlite-coordinator, screenpipe-audio, screenpipe-screen, screenpipe-a11y
- Mapped suites: 32
- Mapped Rust files: 321
-- Active test blocks: 3086
+- Active test blocks: 3098
- Ignored/manual test blocks: 137
-- Declared test blocks: 3223
-- Weighted coverage points: 2541.6
+- Declared test blocks: 3235
+- Weighted coverage points: 2550.9
Confidence weights: strong=1.0, partial=0.7, conditional=0.4, smoke=0.3.
Criticality weights: high=1.0, medium=0.7, low=0.4.
@@ -23,19 +23,19 @@ are explicitly enabled in a runtime lane.
| Platform | Suites | Active tests | Ignored tests | Weighted points | Layers | Flows | Critical score |
| --- | --- | --- | --- | --- | --- | --- | --- |
-| windows | 29 | 2955 | 132 | 2481.6 | 21 | 11 | 100% |
-| macos | 29 | 3008 | 112 | 2492.0 | 22 | 11 | 100% |
-| linux | 25 | 2631 | 105 | 2188.4 | 20 | 11 | 100% |
+| windows | 29 | 2967 | 132 | 2490.9 | 21 | 11 | 100% |
+| macos | 29 | 3020 | 112 | 2501.3 | 22 | 11 | 100% |
+| linux | 25 | 2643 | 105 | 2197.7 | 20 | 11 | 100% |
## Crate Summary
| Crate | Suites | Integration files | Source unit files | Active tests | Ignored tests | Weighted points | Flows |
| --- | --- | --- | --- | --- | --- | --- | --- |
-| screenpipe-engine | 10 | 18 | 102 | 1457 | 42 | 1118.8 | 10 |
+| screenpipe-engine | 10 | 18 | 102 | 1466 | 42 | 1125.1 | 10 |
| screenpipe-db | 5 | 52 | 14 | 447 | 16 | 424.2 | 9 |
| screenpipe-sqlite-coordinator | 1 | 0 | 2 | 16 | 0 | 16.0 | 2 |
| screenpipe-audio | 6 | 25 | 51 | 591 | 43 | 517.4 | 5 |
-| screenpipe-screen | 6 | 9 | 18 | 241 | 9 | 216.9 | 4 |
+| screenpipe-screen | 6 | 9 | 18 | 244 | 9 | 219.9 | 4 |
| screenpipe-a11y | 4 | 2 | 28 | 334 | 27 | 248.3 | 3 |
## Line Coverage
@@ -68,21 +68,21 @@ bun run coverage:core -- --llvm-cov-summary ../../docs/coverage/core-llvm-cov-su
| database | 6 suites / 366 active / 12 ignored / 343.2 pts | 6 suites / 366 active / 12 ignored / 343.2 pts | 6 suites / 366 active / 12 ignored / 343.2 pts |
| db-search | 2 suites / 111 active / 9 ignored / 111.0 pts | 2 suites / 111 active / 9 ignored / 111.0 pts | 2 suites / 111 active / 9 ignored / 111.0 pts |
| engine-lifecycle | 6 suites / 208 active / 1 ignored / 183.6 pts | 6 suites / 208 active / 1 ignored / 183.6 pts | 5 suites / 202 active / 1 ignored / 181.9 pts |
-| local-api | 2 suites / 327 active / 9 ignored / 230.7 pts | 2 suites / 327 active / 9 ignored / 230.7 pts | 2 suites / 327 active / 9 ignored / 230.7 pts |
-| meeting | 6 suites / 1419 active / 19 ignored / 1161.6 pts | 6 suites / 1419 active / 19 ignored / 1161.6 pts | 4 suites / 1131 active / 15 ignored / 896.1 pts |
+| local-api | 2 suites / 336 active / 9 ignored / 237.0 pts | 2 suites / 336 active / 9 ignored / 237.0 pts | 2 suites / 336 active / 9 ignored / 237.0 pts |
+| meeting | 6 suites / 1428 active / 19 ignored / 1167.9 pts | 6 suites / 1428 active / 19 ignored / 1167.9 pts | 4 suites / 1140 active / 15 ignored / 902.4 pts |
| ocr | 4 suites / 124 active / 7 ignored / 118.3 pts | 4 suites / 128 active / 7 ignored / 123.8 pts | 3 suites / 119 active / 6 ignored / 114.8 pts |
| os-integration | 1 suites / 6 active / 0 ignored / 1.7 pts | 1 suites / 6 active / 0 ignored / 1.7 pts | - |
-| performance | 13 suites / 1376 active / 67 ignored / 1213.3 pts | 14 suites / 1474 active / 70 ignored / 1252.5 pts | 13 suites / 1376 active / 67 ignored / 1213.3 pts |
+| performance | 13 suites / 1379 active / 67 ignored / 1216.3 pts | 14 suites / 1477 active / 70 ignored / 1255.5 pts | 13 suites / 1379 active / 67 ignored / 1216.3 pts |
| pipes | 1 suites / 462 active / 3 ignored / 323.4 pts | 1 suites / 462 active / 3 ignored / 323.4 pts | 1 suites / 462 active / 3 ignored / 323.4 pts |
-| privacy | 5 suites / 871 active / 36 ignored / 707.5 pts | 5 suites / 920 active / 16 ignored / 712.4 pts | 5 suites / 846 active / 14 ignored / 685.0 pts |
+| privacy | 5 suites / 874 active / 36 ignored / 710.5 pts | 5 suites / 923 active / 16 ignored / 715.4 pts | 5 suites / 849 active / 14 ignored / 688.0 pts |
| real-app | - | 1 suites / 98 active / 3 ignored / 39.2 pts | - |
| speaker | 2 suites / 348 active / 8 ignored / 348.0 pts | 2 suites / 348 active / 8 ignored / 348.0 pts | 2 suites / 348 active / 8 ignored / 348.0 pts |
| storage | 3 suites / 476 active / 29 ignored / 385.7 pts | 3 suites / 476 active / 29 ignored / 385.7 pts | 3 suites / 476 active / 29 ignored / 385.7 pts |
| sync | 1 suites / 462 active / 3 ignored / 323.4 pts | 1 suites / 462 active / 3 ignored / 323.4 pts | 1 suites / 462 active / 3 ignored / 323.4 pts |
-| timeline | 4 suites / 936 active / 33 ignored / 760.8 pts | 4 suites / 936 active / 33 ignored / 760.8 pts | 4 suites / 936 active / 33 ignored / 760.8 pts |
-| transcription | 5 suites / 700 active / 40 ignored / 552.6 pts | 5 suites / 700 active / 40 ignored / 552.6 pts | 5 suites / 700 active / 40 ignored / 552.6 pts |
+| timeline | 4 suites / 948 active / 33 ignored / 770.1 pts | 4 suites / 948 active / 33 ignored / 770.1 pts | 4 suites / 948 active / 33 ignored / 770.1 pts |
+| transcription | 5 suites / 709 active / 40 ignored / 558.9 pts | 5 suites / 709 active / 40 ignored / 558.9 pts | 5 suites / 709 active / 40 ignored / 558.9 pts |
| ui-events | 4 suites / 701 active / 28 ignored / 533.9 pts | 3 suites / 652 active / 5 ignored / 499.6 pts | 3 suites / 652 active / 5 ignored / 499.6 pts |
-| vision-capture | 5 suites / 495 active / 32 ignored / 392.0 pts | 5 suites / 499 active / 32 ignored / 397.5 pts | 4 suites / 490 active / 31 ignored / 388.5 pts |
+| vision-capture | 5 suites / 498 active / 32 ignored / 395.0 pts | 5 suites / 502 active / 32 ignored / 400.5 pts | 4 suites / 493 active / 31 ignored / 391.5 pts |
## Critical Flow Matrix
@@ -133,7 +133,7 @@ bun run coverage:core -- --llvm-cov-summary ../../docs/coverage/core-llvm-cov-su
| db-runtime-reliability | screenpipe-db | windows, macos, linux | database, performance | performance-liveness | high | partial | mixed | 13 | 30 | 6 | SQLite hard-fault classification, failpoint VFS injection, fresh-identity recovery verification with integrity/FK/write canaries, query cancellation, close-severs-connections regressions, multi-pool WAL parity, runtime version pinning, and WAL chaos plus memory-pressure probes, plus read-only quarantine self-heal verification for transient IOERR faults. |
| db-search-indexing | screenpipe-db | windows, macos, linux | db-search, ocr, accessibility, performance | local-api-search, capture-ocr-pipeline, accessibility-ui-events, performance-liveness | high | strong | mixed | 13 | 105 | 4 | FTS, tokenizer, OCR snapshot search, query planning, ordering, accessibility search, and contention coverage. |
| db-timeline-frames | screenpipe-db | windows, macos, linux | database, timeline, storage, performance | timeline-streaming, performance-liveness | high | strong | mixed | 18 | 175 | 3 | Frame/audio joins, timeline query shape, suggestions frames, write queue, DB primitives (src/db.rs split into src/db/ modules), feedback record upserts, media eviction anti-join regressions, SAF output registry, semantic storage, and timeline performance. |
-| engine-api-routes | screenpipe-engine | windows, macos, linux | local-api, timeline, meeting, transcription | local-api-search, timeline-streaming, meeting-live-notes, audio-record-transcribe | high | partial | mixed | 31 | 321 | 4 | Route/unit coverage for search, health, streaming, meetings, time/timezone, and transcription. Legacy endpoint/websocket tests require local data and remain ignored. |
+| engine-api-routes | screenpipe-engine | windows, macos, linux | local-api, timeline, meeting, transcription | local-api-search, timeline-streaming, meeting-live-notes, audio-record-transcribe | high | partial | mixed | 31 | 330 | 4 | Route/unit coverage for search, health, streaming, meetings, time/timezone, and transcription. Legacy endpoint/websocket tests require local data and remain ignored. |
| engine-capture-timeline | screenpipe-engine | windows, macos, linux | vision-capture, timeline, storage, performance | capture-ocr-pipeline, timeline-streaming, performance-liveness | high | partial | mixed | 23 | 263 | 26 | Covers capture trigger logic, frame/audio linking, hot cache, timeline refresh regressions, fragmented MP4 extraction, and HD-mode control. Several real-data tests are intentionally ignored by default. |
| engine-config-lifecycle | screenpipe-engine | windows, macos, linux | configuration, engine-lifecycle, performance | settings-to-engine-config, engine-health-lifecycle, performance-liveness | high | strong | mixed | 11 | 111 | 1 | Fast logic coverage for the config bridge, tray health debounce, sleep/power policies, and queue backpressure. |
| engine-db-recovery-cli | screenpipe-engine | windows, macos, linux | database, engine-lifecycle | engine-health-lifecycle, performance-liveness | high | strong | unit | 1 | 8 | 0 | Exact DB/WAL/SHM working-copy preservation, rollback on archive failure, and restart repair for crashes during the multi-file generation swap. |
@@ -144,7 +144,7 @@ bun run coverage:core -- --llvm-cov-summary ../../docs/coverage/core-llvm-cov-su
| engine-retention-storage | screenpipe-engine | windows, macos, linux | storage, engine-lifecycle, performance | engine-health-lifecycle, performance-liveness | medium | strong | mixed | 5 | 38 | 0 | Local retention deletion (including lean-mode heavy-text stripping), cloud archive watermarking, atomic state-file replacement, and the low-disk capture monitor. |
| engine-telemetry-observability | screenpipe-engine | windows, macos, linux | engine-lifecycle, performance | engine-health-lifecycle, performance-liveness | medium | strong | unit | 6 | 29 | 0 | PostHog capture gating, telemetry context shaping, piggyback telemetry forwarding, crash-log helpers, resource monitoring, and the recording-coverage reliability metric. |
| screen-capture-ocr-contract | screenpipe-screen | windows, macos, linux | vision-capture, ocr | capture-ocr-pipeline | high | partial | unit | 3 | 14 | 0 | Cross-platform cached-OCR unit coverage for RawCaptureResult to CaptureResult metadata, browser URL, focus state, window-to-screen OCR coordinate transformation, Tesseract output parsing, and contour-based text-region detection for the meeting OCR gate. |
-| screen-capture-windowing | screenpipe-screen | windows, macos, linux | vision-capture, timeline, performance, privacy | capture-ocr-pipeline, timeline-streaming, privacy-and-redaction, performance-liveness | high | strong | mixed | 14 | 177 | 0 | Window filtering, empty-window regressions, retry policy, URL timing, monitor cache, OCR cache, snapshots, and image comparison. |
+| screen-capture-windowing | screenpipe-screen | windows, macos, linux | vision-capture, timeline, performance, privacy | capture-ocr-pipeline, timeline-streaming, privacy-and-redaction, performance-liveness | high | strong | mixed | 14 | 180 | 0 | Window filtering, empty-window regressions, retry policy, URL timing, monitor cache, OCR cache, snapshots, and image comparison. |
| screen-custom-ocr | screenpipe-screen | windows, macos, linux | ocr | capture-ocr-pipeline | medium | conditional | manual | 1 | 0 | 2 | Custom OCR tests are ignored by default and only contribute when explicitly run. |
| screen-macos-ocr | screenpipe-screen | macos | ocr, vision-capture | capture-ocr-pipeline | high | strong | mixed | 2 | 9 | 1 | Apple Vision OCR source/unit coverage and fixture OCR assertions. |
| screen-monitor-platform | screenpipe-screen | windows, macos, linux | vision-capture | capture-ocr-pipeline | medium | partial | unit | 5 | 36 | 5 | Per-OS monitor enumeration (Windows, macOS, Wayland/portal on Linux) and the persistent Windows.Graphics.Capture session. Each file is cfg-gated and only executes on its target OS. |
@@ -398,7 +398,7 @@ bun run coverage:core -- --llvm-cov-summary ../../docs/coverage/core-llvm-cov-su
| engine-api-routes | screenpipe-engine | src/routes/data.rs | source | 2 | 0 | 2 |
| engine-api-routes | screenpipe-engine | src/routes/elements.rs | source | 25 | 1 | 26 |
| engine-api-routes | screenpipe-engine | src/routes/frames.rs | source | 7 | 1 | 8 |
-| engine-api-routes | screenpipe-engine | src/routes/health.rs | source | 34 | 0 | 34 |
+| engine-api-routes | screenpipe-engine | src/routes/health.rs | source | 43 | 0 | 43 |
| engine-api-routes | screenpipe-engine | src/routes/live_views.rs | source | 1 | 0 | 1 |
| engine-api-routes | screenpipe-engine | src/routes/meeting_summary_status.rs | source | 9 | 0 | 9 |
| engine-api-routes | screenpipe-engine | src/routes/meetings.rs | source | 6 | 0 | 6 |
@@ -452,7 +452,7 @@ bun run coverage:core -- --llvm-cov-summary ../../docs/coverage/core-llvm-cov-su
| screen-capture-windowing | screenpipe-screen | src/capture_screenshot_by_window.rs | source | 63 | 0 | 63 |
| screen-capture-ocr-contract | screenpipe-screen | src/core.rs | source | 1 | 0 | 1 |
| screen-capture-windowing | screenpipe-screen | src/frame_comparison.rs | source | 16 | 0 | 16 |
-| screen-capture-windowing | screenpipe-screen | src/metrics.rs | source | 10 | 0 | 10 |
+| screen-capture-windowing | screenpipe-screen | src/metrics.rs | source | 13 | 0 | 13 |
| screen-windows-ocr | screenpipe-screen | src/microsoft.rs | source | 4 | 0 | 4 |
| screen-capture-windowing | screenpipe-screen | src/monitor.rs | source | 5 | 0 | 5 |
| screen-monitor-platform | screenpipe-screen | src/monitor/linux_portal.rs | source | 5 | 0 | 5 |