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(capture): recover precisely from locked starts and idle waits (#6369)

Ezra Ellettee8c22a2b4054
diff --git a/apps/screenpipe-app-tauri/src-tauri/src/capture_session.rs b/apps/screenpipe-app-tauri/src-tauri/src/capture_session.rs
index 8159dffd6..26c4eadf9 100644
--- a/apps/screenpipe-app-tauri/src-tauri/src/capture_session.rs
+++ b/apps/screenpipe-app-tauri/src-tauri/src/capture_session.rs
@@ -8,9 +8,9 @@
//! Borrows shared `Arc`s from `ServerCore` (DB, AudioManager, etc.)
//! without taking ownership — the server stays alive across capture cycles.
+use std::path::PathBuf;
use std::sync::Arc;
use std::time::Duration;
-use std::path::PathBuf;
use screenpipe_audio::audio_manager::builder::AudioManagerOptions;
use screenpipe_audio::core::device::resolve_audio_devices_for_capture;
@@ -155,14 +155,34 @@ impl CaptureSession {
None
};
- // A failed initial start() (e.g. 0 monitors while screen is locked at boot)
- // is recoverable — the monitor watcher below retries on unlock/topology change.
- // Don't propagate the error; keep the session alive so the watcher can run.
- match vision_manager.start().await {
- Ok(()) => info!("VisionManager started successfully"),
- Err(e) => {
- warn!("VisionManager initial start failed ({e}); monitor watcher will retry");
- crate::health::set_recording_status(crate::health::RecordingStatus::Starting);
+ // Do not initialize ScreenCaptureKit while the login session is
+ // locked. A replacement process can launch while the lid is shut
+ // (for example after an auto-update); asking SCShareableContent for
+ // displays then can leave that process returning an empty display
+ // list even after the authoritative unlock notification arrives.
+ // The monitor watcher below waits on that notification and performs
+ // the first SCK call only after the session is unlocked.
+ #[cfg(target_os = "macos")]
+ let defer_vision_start = screenpipe_engine::sleep_monitor::screen_is_locked();
+ #[cfg(not(target_os = "macos"))]
+ let defer_vision_start = false;
+
+ if defer_vision_start {
+ info!("Screen locked at capture startup — deferring VisionManager until unlock");
+ crate::health::set_recording_status(crate::health::RecordingStatus::Starting);
+ } else {
+ // Other initial failures remain recoverable through the monitor
+ // watcher; keep the session alive so it can reconcile them.
+ match vision_manager.start().await {
+ Ok(()) => info!("VisionManager started successfully"),
+ Err(e) => {
+ warn!(
+ "VisionManager initial start failed ({e}); monitor watcher will retry"
+ );
+ crate::health::set_recording_status(
+ crate::health::RecordingStatus::Starting,
+ );
+ }
}
}
diff --git a/crates/screenpipe-engine/src/event_driven_capture.rs b/crates/screenpipe-engine/src/event_driven_capture.rs
index b7b83e3fb..b1eecc2ed 100644
--- a/crates/screenpipe-engine/src/event_driven_capture.rs
+++ b/crates/screenpipe-engine/src/event_driven_capture.rs
@@ -1582,65 +1582,64 @@ pub(crate) async fn event_driven_capture_loop(
tokio::time::sleep(poll_interval).await;
}
} else {
- // Block on `recv()` for the FIRST trigger so an idle channel
- // doesn't burn CPU (matches the upstream "reduce idle
- // wakeups" change). Once a message arrives, drain the rest
- // via `try_recv` so that bursts of triggers coalesce into
- // one capture, with every correlation_id reaching the
- // linker. The reducer then collapses (kind, corr_ids) and
- // filters out skipped kinds (Clipboard/KeyPress with their
- // respective gates off).
+ // Drain without parking this long-lived capture task inside
+ // `broadcast::Receiver::recv()`. Production traces showed this
+ // task repeatedly failing to resume from that receiver wait even
+ // though its 250ms timeout had elapsed; the heartbeat then froze
+ // for minutes while the rest of the runtime stayed healthy.
+ //
+ // Preserve the same 250ms idle cadence and CPU cost with a plain
+ // timer sleep. Triggers remain buffered by the broadcast channel
+ // and are drained on wake, adding at most the same poll interval
+ // already budgeted for checkpoint promotion and idle capture.
+ // This removes the receiver-waker/cancellation path without adding
+ // a retry threshold, watchdog timer, or other recovery heuristic.
let mut drained: Vec<CaptureTriggerMsg> = Vec::new();
let mut lagged_force_manual = false;
let mut closed_now = false;
+ // Preserve immediate handling for an already-buffered trigger.
+ // Sleep only when the channel is empty; anything arriving during
+ // that sleep remains buffered for the drain below.
record_loop_stage(
&vision_metrics,
&monitor_liveness,
- screenpipe_screen::CaptureLoopStage::TriggerWait,
+ screenpipe_screen::CaptureLoopStage::TriggerDrain,
);
- match tokio::time::timeout(poll_interval, trigger_rx.recv()).await {
- Ok(Ok(msg)) => drained.push(msg),
- Ok(Err(broadcast::error::RecvError::Lagged(n))) => {
+ match trigger_rx.try_recv() {
+ Ok(msg) => drained.push(msg),
+ Err(broadcast::error::TryRecvError::Empty) => {
+ record_loop_stage(
+ &vision_metrics,
+ &monitor_liveness,
+ screenpipe_screen::CaptureLoopStage::TriggerWait,
+ );
+ tokio::time::sleep(poll_interval).await;
+ }
+ Err(broadcast::error::TryRecvError::Lagged(n)) => {
debug!(
"trigger channel lagged by {} messages on monitor {}",
n, monitor_id
);
- // Missed broadcast msgs — their correlation_ids are
- // gone forever and those ui_events rows will stay
- // frame_id=NULL. Bump the lagged counter so the
- // periodic linker WARN shows this slice of loss.
report_triggers_dropped(
linker_tx.as_ref(),
Vec::new(),
crate::frame_linker::DropReason::Lagged,
);
- let _ = n;
- // Fall back to Manual below if nothing else wins.
lagged_force_manual = true;
}
- Ok(Err(broadcast::error::RecvError::Closed)) => {
+ Err(broadcast::error::TryRecvError::Closed) => {
warn!(
"trigger channel closed for monitor {}, continuing with polling-only mode",
monitor_id
);
closed_now = true;
}
- Err(_elapsed) => {
- // No trigger this poll_interval — fall through to
- // poll_activity below.
- }
}
- // The bounded wait above returned, so anything past this point is
- // synchronous gate work, not the timer. Re-marking here keeps the
- // watchdog's "frozen in <stage>" message honest: `trigger-wait`
- // now accuses only the 250ms-bounded await (a freeze there means
- // the task was never resumed), while `trigger-drain` accuses the
- // synchronous gates below (a freeze there means a lock is held by
- // another thread). Previously both shared one marker, so a
- // multi-minute #3939 freeze reported `trigger-wait` even though a
- // 250ms timeout cannot account for it.
+ // Anything past this point is synchronous channel/gate work.
+ // Re-marking here keeps the watchdog's "frozen in <stage>"
+ // message honest.
record_loop_stage(
&vision_metrics,
&monitor_liveness,
diff --git a/crates/screenpipe-engine/src/vision_manager/monitor_watcher.rs b/crates/screenpipe-engine/src/vision_manager/monitor_watcher.rs
index 5d0520cdf..1afa1a61c 100644
--- a/crates/screenpipe-engine/src/vision_manager/monitor_watcher.rs
+++ b/crates/screenpipe-engine/src/vision_manager/monitor_watcher.rs
@@ -411,6 +411,28 @@ fn restart_cooldown_elapsed(
.unwrap_or(true)
}
+#[cfg(target_os = "macos")]
+async fn wait_for_stopped_vision_retry(
+ unlock: &tokio::sync::Notify,
+ screen_locked: bool,
+ unlocked_backstop: Duration,
+) -> bool {
+ if screen_locked {
+ // A locked session is authoritative. Do not probe SCK on a cadence;
+ // wait until macOS reports the exact transition that makes capture
+ // possible again.
+ unlock.notified().await;
+ return true;
+ }
+
+ // Clear a notification left from an earlier Running state, then retain the
+ // existing backstop for non-lock failures such as an enumeration timeout.
+ let _ = tokio::time::timeout(Duration::from_millis(0), unlock.notified()).await;
+ tokio::time::timeout(unlocked_backstop, unlock.notified())
+ .await
+ .is_ok()
+}
+
/// Pure step function for the anomalous-empty-enumeration counter — how many
/// consecutive passes SCK returned zero displays while CG topology said
/// capture should be possible. Clock- and FFI-free for unit testing.
@@ -628,43 +650,60 @@ pub async fn start_monitor_watcher(
_ => None,
};
- // Initialize with current monitors
- match list_monitors_detailed().await {
- Ok(monitors) => {
- for monitor in &monitors {
- known_monitors.insert(monitor.id(), monitor.name().to_string());
+ // Never make the watcher's first ScreenCaptureKit call from a locked
+ // login session. A process launched while the lid is shut can otherwise
+ // retain the empty SCShareableContent state after unlock. The normal
+ // not-Running branch below waits for the authoritative unlock event.
+ #[cfg(target_os = "macos")]
+ let defer_startup_enumeration = crate::sleep_monitor::screen_is_locked();
+ #[cfg(not(target_os = "macos"))]
+ let defer_startup_enumeration = false;
+
+ // Initialize with current monitors when capture is currently possible.
+ let startup_monitors = if defer_startup_enumeration {
+ info!("Screen locked at monitor-watcher startup — deferring monitor enumeration until unlock");
+ None
+ } else {
+ Some(list_monitors_detailed().await)
+ };
+ if let Some(startup_monitors) = startup_monitors {
+ match startup_monitors {
+ Ok(monitors) => {
+ for monitor in &monitors {
+ known_monitors.insert(monitor.id(), monitor.name().to_string());
+ }
+ permission_denied_logged = false;
+ // A successful enumeration is the only thing that can lift a
+ // stale verdict left by an earlier watcher in this process, so
+ // it must be reported from here too — not just from the loop.
+ if permission_monitor::screen_enumeration_denied() {
+ info!("Screen recording enumeration recovered at watcher startup");
+ permission_monitor::report_screen_enumeration(true, None);
+ }
}
- permission_denied_logged = false;
- // A successful enumeration is the only thing that can lift a
- // stale verdict left by an earlier watcher in this process, so
- // it must be reported from here too — not just from the loop.
- if permission_monitor::screen_enumeration_denied() {
- info!("Screen recording enumeration recovered at watcher startup");
- permission_monitor::report_screen_enumeration(true, None);
+ Err(MonitorListError::PermissionDenied) => {
+ warn!("Screen recording permission denied. Vision capture is disabled. Grant access in System Settings > Privacy & Security > Screen Recording");
+ permission_denied_logged = true;
+ permission_monitor::report_screen_enumeration(
+ false,
+ Some("list_monitors PermissionDenied (startup)"),
+ );
+ }
+ Err(MonitorListError::NoMonitorsFound) => {
+ // Classify it here too: in the lapsed-grant state SCK succeeds
+ // with an empty list, which surfaces as NoMonitorsFound (not
+ // PermissionDenied). Falling through to the generic arm below
+ // meant a process that launched with the grant already lapsed
+ // never classified the signal at all.
+ classify_empty_enumeration(
+ &mut consecutive_anomalous_empty,
+ &mut permission_denied_logged,
+ "startup",
+ );
+ }
+ Err(e) => {
+ warn!("Failed to list monitors on startup: {}", e);
}
- }
- Err(MonitorListError::PermissionDenied) => {
- warn!("Screen recording permission denied. Vision capture is disabled. Grant access in System Settings > Privacy & Security > Screen Recording");
- permission_denied_logged = true;
- permission_monitor::report_screen_enumeration(
- false,
- Some("list_monitors PermissionDenied (startup)"),
- );
- }
- Err(MonitorListError::NoMonitorsFound) => {
- // Classify it here too: in the lapsed-grant state SCK succeeds
- // with an empty list, which surfaces as NoMonitorsFound (not
- // PermissionDenied). Falling through to the generic arm below
- // meant a process that launched with the grant already lapsed
- // never classified the signal at all.
- classify_empty_enumeration(
- &mut consecutive_anomalous_empty,
- &mut permission_denied_logged,
- "startup",
- );
- }
- Err(e) => {
- warn!("Failed to list monitors on startup: {}", e);
}
}
@@ -777,13 +816,12 @@ pub async fn start_monitor_watcher(
#[cfg(target_os = "macos")]
{
let unlock = crate::sleep_monitor::screen_unlock_notify();
- // Drain any permit buffered while we were Running so we don't
- // wake instantly on a stale signal.
- let _ = tokio::time::timeout(Duration::from_millis(0), unlock.notified()).await;
- // Race unlock against the 5s backstop.
- if tokio::time::timeout(Duration::from_secs(5), unlock.notified())
- .await
- .is_ok()
+ if wait_for_stopped_vision_retry(
+ unlock,
+ crate::sleep_monitor::screen_is_locked(),
+ Duration::from_secs(5),
+ )
+ .await
{
info!("screen unlocked — retrying VisionManager start immediately");
}
@@ -1214,6 +1252,26 @@ mod tests {
// Fixed "now" so deltas are exact and the tests never depend on wall clock.
const NOW: u64 = 2_000_000_000;
+ #[cfg(target_os = "macos")]
+ #[tokio::test]
+ async fn locked_vision_retry_waits_for_the_unlock_event() {
+ let unlock = tokio::sync::Notify::new();
+ let wait = wait_for_stopped_vision_retry(&unlock, true, Duration::from_millis(1));
+ tokio::pin!(wait);
+
+ assert!(
+ tokio::time::timeout(Duration::from_millis(20), &mut wait)
+ .await
+ .is_err(),
+ "the unlocked-failure backstop must not probe SCK while macOS still reports locked"
+ );
+
+ unlock.notify_one();
+ assert!(tokio::time::timeout(Duration::from_millis(100), &mut wait)
+ .await
+ .expect("unlock should release the retry immediately"));
+ }
+
#[test]
fn anomalous_empty_counter_only_advances_with_awake_unlocked_displays() {
use std::collections::BTreeSet;