feat(agent): store ffmpeg's actual failure reason in the job's error field

sample_frames_from_url now returns (frames, reason) — reason carries the
SPECIFIC cause on failure (ffmpeg's stderr tail, e.g. "moov atom not found",
or the timeout) instead of only logging it agent-side. The worker folds it
into the failure it reports, so curator's GpuJob.error reads e.g.

  no frames sampled from video — ffmpeg exit 183: moov atom not found ...

instead of the bare "(unprocessable)". The errored-jobs list becomes
self-describing: after a retry sweep, surviving errors name their real
defect without needing the agent log. Return-value plumbing (not shared
state) so concurrent downloaders stay isolated. Agent VERSION → 2026-07-02.2.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

agent/fc_agent/media.py

@@ -125,7 +125,7 @@ def _terminate(proc: subprocess.Popen) -> None:
 def sample_frames_from_url(
     url: str, interval_seconds: float, max_frames: int,
     *, headers: str = "", timeout: float = 1200.0, should_stop=None,
-) -> list[tuple[float, Image.Image]]:
+) -> tuple[list[tuple[float, Image.Image]], str | None]:
     """Sample frames by pointing ffmpeg STRAIGHT at the media URL — it Range-reads
     only the video index + up to max_frames worth of content, so the agent never
     downloads the whole file (VR/4K originals run 800MB+ and would buffer ~1GB in
@@ -133,7 +133,12 @@ def sample_frames_from_url(
     the timeout is the per-video ceiling (a slow/reconnecting stream can otherwise
     run for minutes). `should_stop` is polled while ffmpeg runs so a Stop KILLS the
     subprocess at once — otherwise a downloader stuck in a long decode keeps the
-    agent "working" long after Stop. Empty on failure / stop / timeout."""
+    agent "working" long after Stop.
+
+    Returns (frames, reason): frames is empty on failure/stop/timeout, and
+    `reason` then carries the SPECIFIC cause (ffmpeg's stderr tail / timeout) so
+    the caller can put it in the job's error — a bare "no frames" hid a filter
+    bug as "unprocessable" for weeks. None reason on success."""
     interval = max(0.5, float(interval_seconds or 4.0))
     cap = max(1, int(max_frames or 64))
     hdr = ["-headers", headers] if headers else []
@@ -174,17 +179,19 @@ def sample_frames_from_url(
                         stopped = should_stop and should_stop()
                         if stopped or (time.monotonic() - start > timeout):
                             _terminate(proc)
-                            if not stopped:
-                                log.warning("ffmpeg timed out after %.0fs: %s",
-                                            timeout, url)
-                            return []
-        except (OSError, ValueError):
-            return []
+                            if stopped:
+                                return [], "stopped"
+                            log.warning("ffmpeg timed out after %.0fs: %s",
+                                        timeout, url)
+                            return [], f"ffmpeg timed out after {timeout:.0f}s"
+        except (OSError, ValueError) as exc:
+            return [], f"ffmpeg not runnable: {exc}"
         frames = _collect_frames(tmp, interval, cap)
         if not frames:
-            log.warning("ffmpeg produced no frames (exit %s) for %s — stderr: %s",
-                        proc.returncode, url, _tail(errpath))
-        return frames
+            reason = f"ffmpeg exit {proc.returncode}: {_tail(errpath)}"
+            log.warning("ffmpeg produced no frames for %s — %s", url, reason)
+            return [], reason
+        return frames, None
 
 
 def _tail(path: str, limit: int = 300) -> str: