FREEZE GUARD fires on first run because Manim has no timing data yet

[jmjava]

Context

Discovered during Course Builder demo video generation. The docgen generate-all pipeline fails at the compose stage on the first full run because Manim scenes are much shorter than the audio.

Problem

The pipeline stages execute in order: tts → timestamps → manim → vhs → compose. However, Manim scenes that use wait_until() for audio synchronization depend on timing.json data that is generated during the timestamps stage of the same run.

On the first run:

1. timestamps generates timing.json from the new TTS audio
2. manim renders scenes — but the scenes use timing data from timing.json for wait_until() calls, and if the scene was cached or the timing data format doesn't match expectations, the scenes render at their natural animation pace (~20-30s)
3. compose compares audio duration (259s) to video duration (22s) and raises FREEZE GUARD: 92% frozen

This creates a chicken-and-egg problem: scenes need timing data to render at the right length, but timing data comes from audio that was just generated.

What we had to do

1. Run generate-all once — TTS + timestamps succeed, Manim scenes render short, compose fails
2. Clear Manim cache: rm -rf animations/media/
3. Re-render Manim with docgen manim — now timing.json is populated, scenes render at correct duration
4. Run docgen compose — succeeds

Recommendations

• generate-all should detect this condition and automatically re-render Manim after timestamps are generated, if scene durations don't match audio durations
• Or: split Manim rendering into two passes — first pass generates timing-independent animations, second pass applies wait_until() pacing
• docgen manim should always clear the cache for scenes whose timing.json has changed since last render
• Add --retry-manim flag to generate-all that auto-retries Manim if compose fails with FREEZE GUARD
• Document the timing dependency clearly: "Scenes using wait_until() require timing.json — run docgen timestamps before docgen manim"

Severity

High — every first-time generate-all run will fail at compose if scenes use timing-based pacing. The error message ("Re-render the visual source to be longer") doesn't explain the root cause.