[Bug]: preview_snapshot fails with UnknownVizError while the Linux Wayland session is locked or monitors are off: capture retries last only ~240 ms

[Vantrongs]

Before submitting

• I searched existing issues and did not find a duplicate.
• I included enough detail to reproduce or investigate the problem.

Area

apps/desktop

Steps to reproduce

1. Run the desktop app on Linux Wayland (niri 26.04 here).
2. Lock the session with any ext-session-lock locker, or turn the monitors off (niri msg action power-off-monitors).
3. From an agent, open a background tab with preview_open {open: false, reuseExistingTab: false} and call preview_snapshot on it.
4. Repeat with a few new tabs.

Expected behavior

The snapshot succeeds, as it does in 4–11 ms while the session is unlocked.

Actual behavior

Some snapshots fail in about 240 ms. The agent sees only Preview snapshot failed: Preview automation snapshot failed on client preview-…. The desktop trace shows automationSnapshot.capturePage … [cause]: Error: UnknownVizError for each of the three attempts. The snapshots that succeed take 0.3–2.7 s.

From desktop.trace.ndjson (PreviewManager.capturePageWithRetry), 27–28 Sep:

Session	Captures	Failed	Successful capture time
Locked or monitors off	30	8: seven in ~241 ms with UnknownVizError, one in 1.24 s including a 1 s attempt timeout	8 under 11 ms, 14 in 0.27–2.7 s
Unlocked	9	0	all 6–11 ms, including 5 new tabs that were never shown

It is not just a hidden window. With the session unlocked and the T3 window left on another niri workspace for 70 s, a new background tab still captured in 6 ms.

This matters for anyone who locks the machine and keeps working with agents remotely: about one snapshot in four fails.

Cause and fix

• niri. While the session is locked or the monitors are off, windows are not drawn. niri then sends their wl_surface.frame callbacks only from a fallback timer: at least once a second, about 2 s at worst (FRAME_CALLBACK_THROTTLE and send_frame_callbacks_on_fallback_timer in src/niri.rs). Throttling invisible surfaces is normal Wayland compositor behavior, so the T3 window, and the guest inside it, can present a new frame only that often.
• T3. requireReadyTab (apps/web/src/components/preview/PreviewAutomationHosts.tsx) moves the guest into the viewport (acquireBrowserSurfaceActivity). capturePageWithRetry (apps/desktop/src/preview/Manager.ts) then makes three attempts 120 ms apart (CAPTURE_PAGE_RETRY_ATTEMPTS, CAPTURE_PAGE_RETRY_DELAY_MS). A guest without a fresh frame rejects each attempt at once with UnknownVizError, as the comment above those constants notes. So the capture gives up after about 240 ms, which is shorter than one frame interval of a locked session.
• Time is what's missing. Under lock, sending a 3 s preview_evaluate together with the snapshot keeps the guest active for 3 s before the capture, and the capture then succeeded. Tabs that failed also succeeded on a later attempt.

Suggested fix: keep retrying UnknownVizError until a time budget of about 2.5 s runs out, which is above niri's worst-case 2 s interval, instead of a fixed three attempts. Keep the 1 s per-attempt timeout for hangs. The tool error could also name the cause; today it says only Preview automation snapshot failed on client ….

Related: #11223 (macOS, intermittent snapshot failures), #13600 (keeps the main window unthrottled during a capture; not checked on Linux), #8981 (2500 ms snapshot deadline for background webviews, currently conflicting).

Impact

Minor bug or occasional failure

Version or commit

main @ de251fc; installed 0.0.43-nightly.20260926.2282

Environment

Desktop app on Linux (NixOS), niri 26.04 (Wayland), Noctalia lock screen (ext-session-lock), Electron 44.4.2; Claude Code in T3 Code

Logs or stack traces

Screenshots, recordings, or supporting files

No response

Workaround

Retry the snapshot, or send a 3 s preview_evaluate (new Promise(r => setTimeout(r, 3000))) together with it.

[juliusmarminge]

Triage

Confirmed on current main. This is a real desktop bug, and it is not covered by the related reports.

capturePageWithRetry in apps/desktop/src/preview/Manager.ts retries any capture failure twice, 120 ms apart, with a 1 s cap on each attempt (CAPTURE_PAGE_RETRY_ATTEMPTS, CAPTURE_PAGE_RETRY_DELAY_MS, CAPTURE_PAGE_ATTEMPT_TIMEOUT_MS). An immediate UnknownVizError therefore gives up after about 240 ms. One attempt that hangs until the 1 s cap, plus two 120 ms gaps, is about 1.24 s, which matches the slow failure in the trace. The comment and the test around that retry only account for a cold guest waiting on its first frame, not a compositor that delivers wl_surface.frame about once a second.

requireReadyTab does put the guest inside the window for the capture: acquireBrowserSurfaceActivity marks the tab active, and resolveHostedBrowserWebviewWrapperStyle then places it at the origin instead of offscreen, because Electron will not composite a guest that sits fully outside the window. That only helps if the compositor actually sends a frame callback. niri’s fallback is FRAME_CALLBACK_THROTTLE at 995 ms and a 1 s timer (send_frame_callbacks_on_fallback_timer), so the worst gap is about 2 s. The unlocked control (another niri workspace, still 6 ms) rules out “the T3 window is merely unfocused.”

The tool text is also as reported. The desktop cause is dropped before it reaches the agent: PreviewAutomationExecutionError only says Preview automation snapshot failed on client …, and preview_snapshot prefixes that with Preview snapshot failed:.

Not duplicates:

• Built-in browser snapshots fail even after the desktop snapshot handler reports success #11223 is the macOS failure where capturePage times out, or the desktop handler succeeds and the tool still times out.
• fix(desktop): preview snapshots no longer time out while the T3 window is hidden #13600 only disables Electron background throttling around the same three short attempts. It does not wait for a locked or powered-off output.
• fix(preview): stabilize background browser automation #8981 is open and not a fix for this. It replaces the automation-snapshot retry with a single capturePage whose 2500 ms deadline applies only when the call does not settle. An immediate UnknownVizError still fails at once, and landing that PR as written would remove the short retry.

A retry budget of about 2.5 s for UnknownVizError, while keeping the 1 s per-attempt cap, matches the niri worst case and still fits the 15 s snapshot timeout. It should be a budget, not more fixed attempts: a guest that will never paint should not wait forever. If #8981 lands first, that budget has to be added to its single-capture path rather than stacked on the old retry loop. Naming UnknownVizError in the tool error is worth doing in the same change.