Three things that were quietly not true

None of these changes a frame. All three were claims -- in a check, in an
error path, in a docstring -- that did not hold.

**A tripwire that asserted nothing.** `check_latent_sidecar` guards that the
retired pickle sidecar is never read back, by searching `store.py`'s latent
reader for `LEGACY_LATENT_EXT`. It searched for `def get_latent(`; the
reader is `_get_latent`. The substring never matched, the ternary always
took its `else True`, and the check had been passing on nothing since it was
written. Now it matches the real name, with an `assert` above it so a rename
fails loudly instead of going quiet again.

**An error path that blamed the wrong thing.** `routes.py`'s SWAP encoder
returned the `for` loop's variable. `video_frame_data_urls` documents `[]`
as its failure mode, and on an empty list that name is unbound -- so a clip
whose frames could not be decoded raised `UnboundLocalError` into the
handler, which logged "could not attach stills" (naming the identity
pictures, which were fine) and threw away the ones already encoded. It now
returns the first frame it actually got, or None.

**A docstring that claimed a refactor that did not land.** `_repair_loop`
said WRITE and SWAP each pass their own consume. Only SWAP does.
`write_plan` still runs its own copy, because it rewrites the conversation
between attempts -- remapping rail tags by filename, merging the register,
restoring pinned `mp` and `file` -- before anything validates, which is not
a shape `consume` can express. That is a real constraint, not an oversight,
so the prose now says there are two loops and that the repair protocol has
to be changed in both. CLAUDE.md section 6c said the same thing and is
corrected the same way.

Also drops `media.video_first_frame_data_url`, dead since SWAP started
sending three frames instead of one. Two frame extractors to keep in step,
one of them called by nothing.

Found by an ultrareview of the v2 branch.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RVz8qNGn2NhrP3KG2Lh5yT

CLAUDE.md

@@ -255,9 +255,15 @@ generate/validate/repair loop, and must not Accept over a multi-shot plan
 without an explicit replace. A change that is about hops 2+, the pin, the
 tone anchor, the audio lock, or the hop cache is not a SWAP change.
 
-The generate/validate/repair *loop* (`planner._repair_loop`) is shared
-mechanism; SWAP's instruct (`prompt_pack/SWAP_PROMPT.md`) and validator
-(`validate_swap`) are separate policy. WRITE's `validate()` and
+The generate/validate/repair *loop* (`planner._repair_loop`) is
+mechanism, extracted so SWAP did not fork WRITE's policy loop to get one.
+**Only SWAP calls it.** `write_plan` still runs its own copy, because it
+rewrites the conversation between attempts -- remapping rail tags by
+filename, merging the register, restoring pinned `mp` and `file` -- before
+anything validates, which `consume` cannot express. Two loops, and a change
+to the repair protocol has to land in both. SWAP's instruct
+(`prompt_pack/SWAP_PROMPT.md`) and validator (`validate_swap`) are separate
+policy. WRITE's `validate()` and
 `system_prompt()` are not on this path. `tools/check_swap_boundary.py`
 enforces the clauses that can be checked without a browser. Gaps it cannot
 cover are named in that file's docstring.

media.py

@@ -139,10 +139,9 @@ def video_frame_data_urls(name, start=0.0, end=0.0, count=3,
     differ by almost nothing, so they would cost three times the tokens to say
     the same thing once.
 
-    Frames are counted rather than sought, matching `load_video` and
-    `video_first_frame_data_url`: a keyframe seek can land a second off, and a
-    caption of the wrong moment is worse than a caption of one moment. Failure
-    is an empty list, never a raise.
+    Frames are counted rather than sought, matching `load_video`: a keyframe
+    seek can land a second off, and a caption of the wrong moment is worse
+    than a caption of one moment. Failure is an empty list, never a raise.
     """
     path = resolve(name, kinds={"video"})
     if path is None:
@@ -183,37 +182,6 @@ def video_frame_data_urls(name, start=0.0, end=0.0, count=3,
         return []
 
 
-def video_first_frame_data_url(name, start=0.0, max_side=VISION_SIDE):
-    """JPEG data-URL of one frame at `start` seconds. -> str or None.
-
-    Prefix-checked through `resolve`. Frames are counted rather than sought,
-    matching `load_video`: a keyframe seek can land a second off, and a
-    caption of the wrong frame is worse than no caption. Failure is None,
-    never a raise.
-    """
-    path = resolve(name, kinds={"video"})
-    if path is None:
-        return None
-    try:
-        import av  # noqa: PLC0415
-        from PIL import Image  # noqa: PLC0415
-
-        with av.open(path) as container:
-            vs = container.streams.video[0]
-            fps = float(vs.average_rate or 0) or 24.0
-            first = max(0, int(round(float(start or 0.0) * fps)))
-            for i, frame in enumerate(container.decode(video=0)):
-                if i < first:
-                    continue
-                arr = frame.to_ndarray(format="rgb24")
-                im = Image.fromarray(arr)
-                return _pil_jpeg_data_url(im, max_side=max_side)
-        return None
-    except Exception as exc:
-        print(f"[{TAG}] could not attach a frame of {name!r}: {exc!r}",
-              flush=True)
-        return None
-
 
 def resolve(name, kinds=None):
     """Absolute path for a reference basename, or None.

routes.py

@@ -650,6 +650,11 @@ def register():
             # order out loud is what turns three pictures into a movement.
             frames = _media.video_frame_data_urls(
                 video, start=start, end=end, count=3)
+            # Not the loop variable: `video_frame_data_urls` documents [] as
+            # its failure mode, and returning `frame` from an empty loop raised
+            # UnboundLocalError into the handler below -- which then blamed the
+            # identity stills and threw away the ones it had already encoded.
+            first = frames[0] if frames else None
             for k, frame in enumerate(frames, 1):
                 images.append({
                     "caption": (
@@ -661,7 +666,7 @@ def register():
                     ),
                     "data_url": frame,
                 })
-            return images, frame
+            return images, first
 
         try:
             images, frame = await asyncio.get_running_loop().run_in_executor(

tools/check_latent_sidecar.py

@@ -155,10 +155,13 @@ def main():
            "or the cache silently exceeds its own budget")
         ck("eviction removes it", "LEGACY_LATENT_EXT" in sweep,
            "or it outlives the entry it belongs to")
+        # `def _get_latent(` -- store.py's reader is private, and the
+        # public spelling never matched, so the ternary always took `else True`
+        # and this tripwire asserted nothing at all.
+        assert "def _get_latent(" in src, "store.py's latent reader was renamed"
         ck("nothing ever reads it",
-           "LEGACY_LATENT_EXT" not in src[src.index("def get_latent("):
-                                          src.index("def entries(")]
-           if "def get_latent(" in src else True,
+           "LEGACY_LATENT_EXT" not in src[src.index("def _get_latent("):
+                                          src.index("def entries(")],
            "reading it back would need weights_only=False")
 
         print("refusals -- None means cache the frames, skip the latent")