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(overlay): name the failing subsystem on the capture-health pill (#6222)

Louis Beaumont508575b3d2d9
diff --git a/apps/screenpipe-app-tauri/app/shortcut-reminder/page.test.tsx b/apps/screenpipe-app-tauri/app/shortcut-reminder/page.test.tsx
index 25ab540b3..79d31dbd8 100644
--- a/apps/screenpipe-app-tauri/app/shortcut-reminder/page.test.tsx
+++ b/apps/screenpipe-app-tauri/app/shortcut-reminder/page.test.tsx
@@ -177,6 +177,91 @@ describe("recording health hover detail", () => {
);
});
+ // #6126: the pill read as a total product failure whatever broke, so routine
+ // audio churn and a wedged capture backend looked identical to the user.
+ it("names audio when only audio failed", async () => {
+ mocks.getRecordingHealthState.mockResolvedValue(
+ "failure|audio capture is not updating|audio",
+ );
+
+ render(<ShortcutReminderPage />);
+
+ expect(await screen.findByText("audio needs help")).toBeVisible();
+ expect(screen.queryByText("recording needs help")).toBeNull();
+ // The reason stays available where it always was.
+ expect(
+ screen.getByRole("button", {
+ name: "Audio needs help: audio capture is not updating. Restart recording",
+ }),
+ ).toHaveAttribute("title", "audio capture is not updating");
+ });
+
+ it("names screen capture when only vision failed", async () => {
+ mocks.getRecordingHealthState.mockResolvedValue(
+ "failure|screen capture is not updating|screen",
+ );
+
+ render(<ShortcutReminderPage />);
+
+ expect(await screen.findByText("screen capture needs help")).toBeVisible();
+ expect(screen.queryByText("recording needs help")).toBeNull();
+ });
+
+ it("stays generic when both subsystems failed or the cause is unknown", async () => {
+ for (const payload of [
+ // Both broken: the engine sends no subsystem, so the pill must not pick one.
+ "failure|audio and screen capture are not updating",
+ "failure|multiple recording errors detected",
+ "failure|recording data cannot be saved",
+ // Bare state, and an engine predating the subsystem field.
+ "failure",
+ "failure|recording stopped unexpectedly",
+ ]) {
+ cleanup();
+ mocks.getRecordingHealthState.mockResolvedValue(payload);
+
+ render(<ShortcutReminderPage />);
+
+ expect(await screen.findByText("recording needs help")).toBeVisible();
+ expect(screen.queryByText("audio needs help")).toBeNull();
+ expect(screen.queryByText("screen capture needs help")).toBeNull();
+ }
+ });
+
+ it("names the subsystem from a live pushed event, not just the mount pull", async () => {
+ mocks.getRecordingHealthState.mockResolvedValue("normal");
+ let pushHealth: ((event: { payload: string }) => void) | undefined;
+ mocks.listen.mockImplementation(async (event: string, handler: unknown) => {
+ if (event === "recording-health-state") {
+ pushHealth = handler as (event: { payload: string }) => void;
+ }
+ return vi.fn();
+ });
+
+ render(<ShortcutReminderPage />);
+ await waitFor(() => expect(pushHealth).toBeDefined());
+
+ act(() => {
+ pushHealth!({ payload: "failure|audio capture is not updating|audio" });
+ });
+
+ expect(await screen.findByText("audio needs help")).toBeVisible();
+ });
+
+ // #5553 fixed overflow in this pill; "screen capture needs help" is the
+ // longest label it can now show, so it has to stay inside the same budget.
+ it("keeps the longest label on one truncating line", async () => {
+ mocks.getRecordingHealthState.mockResolvedValue(
+ "failure|screen capture is not updating|screen",
+ );
+
+ render(<ShortcutReminderPage />);
+
+ const label = await screen.findByText("screen capture needs help");
+ expect(label.className).toContain("whitespace-nowrap");
+ expect(label.className).toContain("truncate");
+ });
+
it("shows a live meeting dot and reveals transcript plus explicit stop on hover", async () => {
mocks.getRecordingHealthState.mockResolvedValue("normal");
mocks.meetingOverlayState.active = true;
diff --git a/apps/screenpipe-app-tauri/app/shortcut-reminder/page.tsx b/apps/screenpipe-app-tauri/app/shortcut-reminder/page.tsx
index 03fa13926..8a281843b 100644
--- a/apps/screenpipe-app-tauri/app/shortcut-reminder/page.tsx
+++ b/apps/screenpipe-app-tauri/app/shortcut-reminder/page.tsx
@@ -70,6 +70,9 @@ export default function ShortcutReminderPage() {
const { isMac, isLoading } = usePlatform();
const [healthState, setHealthState] = useState<RecordingHealthState>("normal");
const [healthDetail, setHealthDetail] = useState("");
+ // "audio" | "screen" | "" — empty when the cause spans subsystems or could
+ // not be attributed, which keeps the pill on its generic wording (#6126).
+ const [healthSubsystem, setHealthSubsystem] = useState("");
const [overlayShortcut, setOverlayShortcut] = useState<string | null>(null);
const [chatShortcut, setChatShortcut] = useState<string | null>(null);
const [searchShortcut, setSearchShortcut] = useState<string | null>(null);
@@ -235,12 +238,14 @@ export default function ShortcutReminderPage() {
// current via the event.
useEffect(() => {
let mounted = true;
- // Payload is "state" or "state|detail" (a failure reason, or the boot
- // phase label while fixing).
+ // Payload is "state", "state|detail", or "state|detail|subsystem" —
+ // detail is a failure reason (or the boot phase label while fixing), and
+ // subsystem names what failed when the engine could attribute it to one.
const apply = (payload: string) => {
- const [state, detail = ""] = payload.split("|", 2);
+ const [state, detail = "", subsystem = ""] = payload.split("|");
setHealthState(state as RecordingHealthState);
setHealthDetail(detail);
+ setHealthSubsystem(subsystem);
};
commands
.getRecordingHealthState()
@@ -419,6 +424,19 @@ export default function ShortcutReminderPage() {
const smIconPx = 10 * overlayScale;
const dotPx = Math.max(5 * overlayScale, 5);
const failureReason = healthDetail || "recording stopped unexpectedly";
+ // Name the subsystem the engine identified. Anything else — both failed, a
+ // persistence error, an unattributable stop — keeps the generic wording.
+ // Must stay in sync with `healthHeadline` in
+ // src-tauri/swift/shortcut_reminder.swift; both read the same payload field.
+ const failureHeadline =
+ healthSubsystem === "audio"
+ ? "audio needs help"
+ : healthSubsystem === "screen"
+ ? "screen capture needs help"
+ : "recording needs help";
+ // The pill is lowercase by design; the accessible name is a sentence.
+ const failureHeadlineSentence =
+ failureHeadline.charAt(0).toUpperCase() + failureHeadline.slice(1);
const latestTranscript = meetingOverlay.items.at(-1);
const latestSpeaker = latestTranscript
? latestTranscript.speakerName ||
@@ -462,7 +480,7 @@ export default function ShortcutReminderPage() {
className="flex items-center justify-center flex-1 min-h-0 hover:bg-white/10 transition-colors cursor-pointer"
style={{ gap: `${gap * 2}px`, padding: `${padY}px ${padX}px`, WebkitAppRegion: 'no-drag' } as React.CSSProperties}
title={failureReason}
- aria-label={`Recording needs help: ${failureReason}. Restart recording`}
+ aria-label={`${failureHeadlineSentence}: ${failureReason}. Restart recording`}
>
<div
className="rounded-full bg-red-500 animate-pulse shrink-0"
@@ -472,7 +490,7 @@ export default function ShortcutReminderPage() {
className="font-mono text-white/90 whitespace-nowrap truncate"
style={{ fontSize: `${fontPx}px` }}
>
- recording needs help
+ {failureHeadline}
</span>
</button>
<div className="bg-white/15" style={{ height: "1px" }} />
diff --git a/apps/screenpipe-app-tauri/src-tauri/src/health.rs b/apps/screenpipe-app-tauri/src-tauri/src/health.rs
index b5140056c..c8a3094ce 100644
--- a/apps/screenpipe-app-tauri/src-tauri/src/health.rs
+++ b/apps/screenpipe-app-tauri/src-tauri/src/health.rs
@@ -697,6 +697,27 @@ fn overlay_failure_detail(
}
}
+/// Which subsystem the overlay pill should name, derived from the reason
+/// [`overlay_failure_detail`] already produced.
+///
+/// The pill said "recording needs help" for everything, so routine Bluetooth
+/// audio churn read as a total product failure while screen capture was
+/// writing a frame every second (#6126). The engine already knew which
+/// subsystem failed; only the visible label threw it away.
+///
+/// Returns `""` whenever the cause is more than one subsystem or cannot be
+/// attributed — the pill then keeps its generic wording rather than guessing.
+pub(crate) fn overlay_failure_subsystem(detail: &str) -> &'static str {
+ match detail {
+ "audio capture is not updating" => "audio",
+ "screen capture is not updating" => "screen",
+ // "audio and screen capture are not updating", "multiple recording
+ // errors detected", persistence, engine start/stop, simulated breaks,
+ // and anything unrecognized stay generic on purpose.
+ _ => "",
+ }
+}
+
#[allow(clippy::too_many_arguments)]
fn overlay_tick_decision(
status: RecordingStatus,
@@ -2840,6 +2861,94 @@ mod tests {
}
}
+ /// #6126: the pill said "recording needs help" for everything, so routine
+ /// audio churn read as a total product failure while screen capture was
+ /// writing a frame every second.
+ #[test]
+ fn overlay_names_a_single_failing_subsystem_and_never_guesses() {
+ assert_eq!(
+ overlay_failure_subsystem("audio capture is not updating"),
+ "audio",
+ );
+ assert_eq!(
+ overlay_failure_subsystem("screen capture is not updating"),
+ "screen",
+ );
+
+ // Anything spanning subsystems, or that the engine could not attribute,
+ // must stay generic rather than pick a side.
+ for generic in [
+ "audio and screen capture are not updating",
+ "multiple recording errors detected",
+ "recording data cannot be saved",
+ "recording engine could not start",
+ "recording engine stopped",
+ "recording stopped unexpectedly",
+ "recording did not restart",
+ "simulated recording failure",
+ "",
+ ] {
+ assert_eq!(
+ overlay_failure_subsystem(generic),
+ "",
+ "{generic:?} must keep the generic pill wording",
+ );
+ }
+ }
+
+ /// Every reason the engine can produce has to route through the mapping
+ /// above, so a new detail string cannot silently land in the wrong bucket.
+ #[test]
+ fn every_producible_failure_detail_maps_to_a_known_subsystem() {
+ let mut saw_audio = false;
+ let mut saw_screen = false;
+
+ for audio in [false, true] {
+ for vision in [false, true] {
+ for persistence in [false, true] {
+ for simulated in [false, true] {
+ for status in [
+ RecordingStatus::Recording,
+ RecordingStatus::Error,
+ RecordingStatus::Stopped,
+ RecordingStatus::Starting,
+ ] {
+ let detail = overlay_failure_detail(
+ status,
+ CaptureFailureSignals {
+ audio,
+ vision,
+ persistence,
+ },
+ simulated,
+ );
+ let subsystem = overlay_failure_subsystem(detail);
+ assert!(
+ matches!(subsystem, "" | "audio" | "screen"),
+ "{detail:?} produced unknown subsystem {subsystem:?}",
+ );
+ // Only a lone audio or lone vision failure may be
+ // attributed, and only when nothing else failed.
+ if subsystem == "audio" {
+ saw_audio = true;
+ assert!(audio && !vision && !persistence && !simulated);
+ }
+ if subsystem == "screen" {
+ saw_screen = true;
+ assert!(vision && !audio && !persistence && !simulated);
+ }
+ }
+ }
+ }
+ }
+ }
+
+ assert!(
+ saw_audio && saw_screen,
+ "both attributions must be reachable"
+ );
+ }
+
#[test]
fn overlay_decision_exhaustively_checks_12288_state_combinations() {
let statuses = [
diff --git a/apps/screenpipe-app-tauri/src-tauri/src/overlay_health.rs b/apps/screenpipe-app-tauri/src-tauri/src/overlay_health.rs
index eca9eb252..f084d1479 100644
--- a/apps/screenpipe-app-tauri/src-tauri/src/overlay_health.rs
+++ b/apps/screenpipe-app-tauri/src-tauri/src/overlay_health.rs
@@ -400,13 +400,9 @@ fn transition_tick(
pub fn current_state_payload() -> String {
INNER
.lock()
- .map(|i| {
- if i.last_detail.is_empty() {
- i.state.as_str().to_string()
- } else {
- format!("{}|{}", i.state.as_str(), i.last_detail)
- }
- })
+ // Same builder as the pushed event, so the mount-time pull and the
+ // live event can never disagree about which subsystem failed.
+ .map(|i| build_health_payload(i.state, Some(i.last_detail.as_str())))
.unwrap_or_else(|_| "normal".to_string())
}
@@ -436,14 +432,30 @@ fn mark_capture_recovery_e2e() {
#[cfg(not(all(debug_assertions, feature = "e2e")))]
fn mark_capture_recovery_e2e() {}
+/// Wire format for both overlay surfaces: `state`, `state|detail`, or
+/// `state|detail|subsystem`.
+///
+/// The subsystem is appended rather than inlined so the pill can name what
+/// actually failed (#6126) while `detail` keeps its existing meaning and
+/// position. It is only present for a failure the engine could attribute to a
+/// single subsystem; both renderers fall back to the generic wording without
+/// it. Neither field ever contains a `|`, so a fixed 3-way split is exact.
+pub(crate) fn build_health_payload(state: OverlayHealthState, detail: Option<&str>) -> String {
+ let detail = detail.unwrap_or("");
+ if detail.is_empty() {
+ return state.as_str().to_string();
+ }
+ match crate::health::overlay_failure_subsystem(detail) {
+ "" => format!("{}|{}", state.as_str(), detail),
+ subsystem => format!("{}|{}|{}", state.as_str(), detail, subsystem),
+ }
+}
+
/// Push a state to both overlay surfaces. The Swift panel keeps the state
/// even while hidden; the webview additionally pulls it on mount via the
/// `get_recording_health_state` command, so a lost emit is harmless.
fn push_state(app: &tauri::AppHandle, state: OverlayHealthState, detail: Option<&str>) {
- let payload = match detail {
- Some(d) if !d.is_empty() => format!("{}|{}", state.as_str(), d),
- _ => state.as_str().to_string(),
- };
+ let payload = build_health_payload(state, detail);
#[cfg(any(target_os = "macos", target_os = "windows"))]
{
crate::native_shortcut_reminder::set_health_state(&payload);
@@ -717,6 +729,85 @@ mod tests {
use super::*;
use crate::recording::TeardownOutcome;
+ /// #6126: both overlay surfaces read the subsystem out of this payload, so
+ /// the wire format is the contract that keeps them in sync.
+ #[test]
+ fn health_payload_carries_the_failing_subsystem() {
+ assert_eq!(
+ build_health_payload(
+ OverlayHealthState::Failure,
+ Some("audio capture is not updating"),
+ ),
+ "failure|audio capture is not updating|audio",
+ );
+ assert_eq!(
+ build_health_payload(
+ OverlayHealthState::Failure,
+ Some("screen capture is not updating"),
+ ),
+ "failure|screen capture is not updating|screen",
+ );
+ }
+
+ /// An unattributable failure keeps the two-field shape, so the renderers
+ /// fall back to the generic wording rather than inventing a subsystem.
+ #[test]
+ fn health_payload_omits_the_subsystem_when_the_cause_is_not_attributable() {
+ assert_eq!(
+ build_health_payload(
+ OverlayHealthState::Failure,
+ Some("audio and screen capture are not updating"),
+ ),
+ "failure|audio and screen capture are not updating",
+ );
+ assert_eq!(
+ build_health_payload(OverlayHealthState::Fixing, Some("updating database")),
+ "fixing|updating database",
+ );
+ }
+
+ /// No detail at all stays a bare state — the shape every existing consumer
+ /// already handles.
+ #[test]
+ fn health_payload_stays_bare_without_a_detail() {
+ for state in [
+ OverlayHealthState::Normal,
+ OverlayHealthState::Failure,
+ OverlayHealthState::Fixing,
+ OverlayHealthState::Recovered,
+ ] {
+ assert_eq!(build_health_payload(state, None), state.as_str());
+ assert_eq!(build_health_payload(state, Some("")), state.as_str());
+ }
+ }
+
+ /// The renderers split on `|` into at most three parts, so no field may
+ /// contain one — otherwise the subsystem would absorb part of the reason.
+ #[test]
+ fn no_payload_field_contains_the_separator() {
+ for detail in [
+ "audio capture is not updating",
+ "screen capture is not updating",
+ "audio and screen capture are not updating",
+ "multiple recording errors detected",
+ "recording data cannot be saved",
+ "recording engine could not start",
+ "recording engine stopped",
+ "recording stopped unexpectedly",
+ "recording did not restart",
+ "simulated recording failure",
+ "updating database",
+ ] {
+ let payload = build_health_payload(OverlayHealthState::Failure, Some(detail));
+ assert!(
+ payload.matches('|').count() <= 2,
+ "{payload:?} would not parse into state/detail/subsystem",
+ );
+ let parts: Vec<&str> = payload.splitn(3, '|').collect();
+ assert_eq!(parts[1], detail, "detail must survive the round trip");
+ }
+ }
+
fn test_inner(state: OverlayHealthState) -> Inner {
Inner {
state,
diff --git a/apps/screenpipe-app-tauri/src-tauri/swift/shortcut_reminder.swift b/apps/screenpipe-app-tauri/src-tauri/swift/shortcut_reminder.swift
index 4fc8945f6..1c7fa44e5 100644
--- a/apps/screenpipe-app-tauri/src-tauri/swift/shortcut_reminder.swift
+++ b/apps/screenpipe-app-tauri/src-tauri/swift/shortcut_reminder.swift
@@ -74,17 +74,21 @@ public func shortcutSetMeetingStopResult(_ succeeded: Int32) {
/// Recording-health state pushed from the Rust health loop (issue #5127):
/// "normal" | "failure" | "fixing" | "recovered", optionally "state|detail"
-/// where detail is a concise failure reason or a boot-phase label while fixing.
+/// or "state|detail|subsystem" where detail is a concise failure reason (or a
+/// boot-phase label while fixing) and subsystem is "audio" or "screen" when
+/// the engine could attribute the failure to one (#6126).
/// Swift only renders it — all detection/debounce/recovery logic lives in Rust.
@_cdecl("shortcut_set_health_state")
public func shortcutSetHealthState(_ statePtr: UnsafePointer<CChar>?) -> Int32 {
guard let statePtr = statePtr else { return -1 }
let payload = String(cString: statePtr)
- let parts = payload.split(separator: "|", maxSplits: 1).map(String.init)
+ let parts = payload.split(separator: "|", maxSplits: 2).map(String.init)
let state = parts.first ?? "normal"
let detail = parts.count > 1 ? parts[1] : ""
+ let subsystem = parts.count > 2 ? parts[2] : ""
if #available(macOS 13.0, *) {
- ShortcutReminderController.shared.setHealthState(state, detail: detail)
+ ShortcutReminderController.shared.setHealthState(
+ state, detail: detail, subsystem: subsystem)
return 0
}
return -2
@@ -110,6 +114,20 @@ final class OverlayMetrics: ObservableObject {
@Published var healthState: String = "normal"
/// Concise failure reason, or boot-phase label while fixing.
@Published var healthDetail: String = ""
+ /// "audio" | "screen" | "" — which subsystem failed, when the engine could
+ /// attribute it to one. Empty keeps the pill's generic wording (#6126).
+ @Published var healthSubsystem: String = ""
+
+ /// Collapsed failure-pill label. Must stay in sync with the webview's
+ /// `failureHeadline` in app/shortcut-reminder/page.tsx — both render the
+ /// same `healthSubsystem` from the same payload.
+ var healthHeadline: String {
+ switch healthSubsystem {
+ case "audio": return "audio needs help"
+ case "screen": return "screen capture needs help"
+ default: return "recording needs help"
+ }
+ }
/// True when the cursor is inside the panel area — drives expand/collapse
/// since SwiftUI's .onHover tracking areas use .activeInActiveApp which
/// does not fire when the app is not frontmost (the overlay stays visible
@@ -834,7 +852,9 @@ struct ShortcutReminderView: View {
// fits the fixed 200pt panel — the panel frame is never
// resized (setFrame on this nonactivating panel breaks
// its mouse routing; observed as a dead-click pill).
- Text(isExpanded ? "needs help" : "recording needs help")
+ // Collapsed names the failing subsystem (#6126); expanded
+ // stays generic because the action row owns that width.
+ Text(isExpanded ? "needs help" : metrics.healthHeadline)
.font(Brand.swiftUIMonoFont(size: 8 * scale, weight: .regular))
.foregroundColor(.white.opacity(0.85))
.padding(.trailing, isExpanded ? s(8) : s(2))
@@ -1787,11 +1807,14 @@ class ShortcutReminderController: NSObject, NSWindowDelegate {
/// frame is deliberately NOT resized — all health content is sized to fit
/// the fixed expanded panel, because setFrame on this nonactivating panel
/// breaks its mouse routing (dead-click pill).
- func setHealthState(_ state: String, detail: String = "") {
+ func setHealthState(_ state: String, detail: String = "", subsystem: String = "") {
DispatchQueue.main.async { [self] in
if self.metrics.healthDetail != detail {
self.metrics.healthDetail = detail
}
+ if self.metrics.healthSubsystem != subsystem {
+ self.metrics.healthSubsystem = subsystem
+ }
if self.metrics.healthState != state {
let normalityChanged = (self.metrics.healthState == "normal") != (state == "normal")
self.metrics.healthState = state