fix(task): raise CaptureException when frame capture stalls

[nagameTW]

Problem

ok-oldking/ok-wuthering-waves#1466 — a farming task dies with AttributeError: 'NoneType' object has no attribute 'shape' in FeatureSet.check_size after the user locks the screen / turns off the monitor.

From the log attached to that issue: right before the crash the capture layer logs no frame for 10 sec, try to restart twice — a transient stall during the lock-screen transition. next_frame(time_out=6) returns None after its timeout, the frame property passes that None through, and the recognition path crashes. All three tracebacks in the log funnel through FeatureSet.check_size, so a stall of ~10-20 seconds permanently kills the running task.

Fix

• TaskExecutor.frame now keeps retrying next_frame(), so transient capture stalls no longer kill the task — it resumes once frames come back.
• If no frame arrives for frame_stall_timeout seconds (new constructor param, default 60), it raises the existing CaptureException, which the executor main loop already handles (capture_error signal + task stopped with a clear message) — instead of the raw AttributeError.
• The error-handler screenshot path now uses the cached _frame instead of the frame property, so error handling itself can never raise CaptureException.

Callers that want a nullable frame still have nullable_frame(); no caller relies on the frame property returning None (they would all crash on it).

Tests

tests/test_task_executor_frame.py, following the TaskExecutor.__new__ pattern of test_task_executor_queue.py:

• capture stalled → raises CaptureException
• capture recovers mid-stall → returns the frame
• frame already present → returned directly, no capture call

Note: developed on Linux where the package cannot be imported (win32 deps), so the tests are written but were not executed here — verified via py_compile and review. Please run them on Windows before merging.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud