venice-video-harness 2.18.0 → 2.20.0

package/.agents/skills/venice-agent-guide/SKILL.md

@@ -38,6 +38,14 @@ in the other.
 - State placement explicitly in every prompt: lock each location's landmark geography (`spatialAnchors`) and give every character shot a `blocking` field (position vs named anchors, screen side, depth, facing/eyeline). Keep screen sides and eyelines constant across a scene unless a movement is scripted.
 - Prefer native model dialogue (Seedance 2.0, HappyHorse 1.1 with voice-donor references) over exact TTS lip-sync.
 
+## Modes of operation — the linear pipeline is not the only path
+- Default path: the gated pipeline (`venice-video pipeline`) — aesthetic → cast → episode → script → approve → storyboard → QA → render → assemble. Use it for a finished, identity-locked cut.
+- Loop mode (`venice-video loop -p <project> -e <n> --mode <looping|production>`): once a shot script exists, render the whole plan continuously and watch it as a live browser loop that hot-swaps fresh takes. It SKIPS the storyboard/QA gates and writes only under `episodes/episode-NNN/loop/`, so it never touches the canonical cut. `looping` = creative flow, lower quality (Turbo 480P, disposable); `production` = gather usable, identity-locked takes (Max R2V @768P). `--mode` is REQUIRED non-interactively; `--budget` caps spend (default $2). This is NOT in the `pipeline` stage list — it is under `branches` in `pipeline --json`.
+- **Loop mode plays AND renders at the same time — it does NOT pre-generate everything.** The browser loops the takes that already exist while the worker keeps generating new ones, swapping each shot's newer take in on the loop's **next pass** (never mid-clip). Two things make a running loop *look* pre-generated when it isn't: (a) it **pauses** when it hits `--budget` or you click Pause, then just replays what's on disk — raise `--budget` or pass `--unbounded` to keep it generating; (b) `--max-takes` is a per-shot ring buffer (default 3, older takes pruned), not a total.
+- **Which mode evolves while you watch:** `looping` (Turbo, 480P) renders faster than it plays, so it visibly changes as you watch. `production`/create renders each shot slowly on Max R2V — it's for **gathering keeper takes**, not a continuously-evolving watch, and on a short/few-shot plan it can look static even while running (one take takes longer to render than a full loop cycle takes to play). Want "watch it keep changing"? Use `looping` with a higher/unbounded budget.
+- Three video lanes, chosen per shot by the router (see the `venice-video-model-routing` skill): **t2v** (prompt only), **i2v** (animate a supplied START image via `image_url` — establishing/atmosphere shots, or chaining off a previous last frame), **R2V** (identity anchored to a reference stack — the default for character shots). "i2v" means a supplied first frame; "R2V" means `reference_image_urls`, not a start frame — do not conflate them.
+- To animate a single image you already have (plain i2v, no project), the routing skill's bundled `scripts/venice-video.py --image <file> --model <...-image-to-video>` is the standalone path; the project pipeline is for multi-shot, consistency-first work.
+
 ## Where the full knowledge lives
 - `AGENTS.md` — 49 rules and 28 production anti-patterns, shipped in the package.
 - `.agents/skills/` — `venice-api`, `venice-video-model-routing`, `character-consistency`, `shot-composition`, `burn-in-subtitles`, `video-editing`, and more.

package/.agents/skills/venice-video-model-routing/SKILL.md

@@ -318,6 +318,73 @@ Generate consistent storyboard panels using two Venice models in sequence:
 
 Construct prompts differently depending on the resolved model's capabilities:
 
+### Simple-Prompt Models (MiniMax H3 Max, H3 Max Turbo)
+
+Read this before anything else in this section: everything below assumes a model that
+renders what it is told and drifts when it is not. The H3 Max pair is the opposite, and
+the registry marks it with `promptStyle: 'simple'` (`modelWantsSimplePrompt(modelId)`).
+These models compose their own coverage — framing, cutting, beat rhythm — from one plain
+statement of intent, and the directorial stack fights the shot the model would otherwise
+have chosen.
+
+`buildVideoPrompt()` and `buildMontagePrompt()` already drop the heavy blocks for them, so
+the adaptation is mostly a matter of not writing them back in by hand:
+
+- **Dropped:** the authored `Blocking:` restatement, the location description and
+  `spatialAnchors` "Fixed layout (never rearrange)" line, the geography-hold /
+  no-mirroring lecture, and the full aesthetic string (the compact one is used instead).
+- **Kept:** `@ImageN` identity declarations and role clauses on the R2V lane, the beat
+  description, dialogue with delivery, and the audio-exclusion suffix. Identity and look
+  still have to be bound; only the staging instructions go.
+- **Dialogue is IMPROVISED, not scripted.** These models carry natural, continuous speech
+  across a whole generation and degrade when handed an exact line to recite. So in
+  native-dialogue mode the prompt gives the scripted line as INTENT — `[@Image1, voice,
+  delivery] conveys: "…"` plus a one-line "improvise naturally in character, keep the intent
+  and tone, don't recite word for word" note — instead of the directorial `[…]: "exact line"`
+  quote. `buildVideoPrompt` / `buildMontagePrompt` do this automatically via
+  `shouldImproviseDialogue(modelId, series)` (gated on `modelWantsSimplePrompt` +
+  `audioStrategy !== 'lip-sync'`). Do NOT hand-write exact quotes for these models expecting
+  them verbatim. The exception is **exact-lip-sync**, where the `audio_url` drives the exact
+  words, so the line stays verbatim. One consequence: captions must come from transcribing
+  the rendered audio, not from `script.json` (the model won't say it word for word).
+- **Don't** add camera terms, shot lists, or `Lens switch.` lines per beat. State the
+  sequence in a sentence or two and let the model cut it — that instinct is why this is
+  the montage family.
+- Resolution is pinned to **768P** by default (2K is a hard 400 — the inverse of plain
+  MiniMax H3, which is 2K-only). **480P is the draft tier** and is only selected via an
+  explicit `resolution` override on `renderVideoFile`. Durations run the 5-15s ladder.
+  `audio` is not configurable, so the field is omitted from the body entirely.
+- Turbo ships **no R2V lane**; identity and lip-sync shots cross to
+  `minimax-h3-max-reference-to-video`.
+
+**Loop mode uses this family, with two modes.** `venice-video loop` renders the whole shot
+script continuously and plays it as a live browser loop that hot-swaps in fresh takes:
+
+- `--mode watch` (default) — `minimax-h3-max-turbo-text-to-video` (or `-image-to-video` off
+  an existing panel) at 480P, ~$0.012/s. The cheapest lane; a disposable draft that does NOT
+  lock identity (Turbo has no R2V lane).
+- `--mode create` — the real reference-first routing on the **non-Turbo** H3 Max family at
+  768P (~$0.024/s): character shots on `minimax-h3-max-reference-to-video` with the full
+  `@Image` reference stack + voice-donor audio (identity locked, takes usable), atmosphere on
+  Max i2v/t2v. Shots with missing references degrade to i2v/t2v.
+
+Both skip the storyboard/QA gates and write only under `loop/`. See `LoopEngine`
+(`src/mini-drama/loop-engine.ts`) and AGENTS.md rule 58. Watch is a preview, not a production
+path; create is the "keep the good takes" path.
+
+**The loop plays AND renders concurrently — it does not pre-generate.** The browser loops the
+takes that already exist while the worker keeps generating new ones, swapping each shot's newer
+take in on the loop's NEXT pass (never mid-clip). It only *looks* pre-generated when (a) it is
+PAUSED — budget hit or Pause clicked — and just replays what is on disk (raise `--budget` or
+pass `--unbounded` to keep it going), or (b) it is in `create` mode, whose slow Max R2V renders
+can't keep up with a short loop cycle, so evolution lags. `watch` (looping/Turbo) renders faster
+than it plays and visibly evolves as you watch; `create` (production) is for gathering keeper
+takes, not a live-evolving watch. `--max-takes` is a per-shot ring buffer, not a total/stop.
+
+The Creator app mirrors this: `VideoModelCapabilities.wantsSimplePrompt(id:)` gates the
+same trimming in `ShotPromptBuilder`, and relaxes the `produce_shots` motion/length gate
+so a correctly short H3 Max prompt isn't rejected as thin.
+
 ### Image-Tag R2V Models (Seedance 2.0 R2V Enhanced — default for all lanes)
 
 - Replace character names in descriptions with `@Image1`, `@Image2` tokens via regex
@@ -454,6 +521,9 @@ Seedance 2.0 (now the default for both atmosphere and character shots) accepts *
 - **Omitting `aspect_ratio` from R2V models:** Both Seedance R2V and Kling O3 R2V require `aspect_ratio`. If omitted, it defaults to `16:9` in code. Always pass `aspect_ratio` explicitly.
 - **Sending `image_references`/`image_1` to `nano-banana-pro`:** Returns 400. The generation model does not accept reference payloads at all.
 - **Sending invalid durations:** Seedance 2.0 accepts 4s/5s/8s/10s/12s/15s. Veo 3.1 accepts 4s/6s/8s. Duration auto-snap corrects this.
+- **Sending `2K` to MiniMax H3 Max, or `768P` to plain MiniMax H3:** The two families share a name and invert on resolution. H3 is 2K-only; H3 Max and H3 Max Turbo top out at 768P and reject 2K. `video-generator.ts` pins each family, and the `-max` branch has to stay above the `minimax-h3` substring match or every H3 Max render 400s.
+- **Reaching for `minimax-h3-max-turbo-reference-to-video`:** It doesn't exist ("Specified model not found"). Turbo has no R2V lane; identity shots route to `minimax-h3-max-reference-to-video`.
+- **Sending `audio` to any MiniMax H3 family model:** `audioConfigurable: false` — audio is always generated and the field must be omitted from the body, not set to `true`.
 - **Reference images below 300x300:** R2V models reject `reference_image_urls` and `elements` images smaller than 300x300 pixels. Never downscale character references below this threshold.
 - **Seedance + non-seedream face images (no longer an issue, 2026-07):** Venice removed the restriction that Seedance 2.0 only accepts face-bearing input images from `seedream-v5-lite` / `seedream-v5-lite-edit`. Any image family now works for face-bearing inputs, so there's nothing to pair, reroute, or launder — the pre-flight gate is a no-op.
 
@@ -471,6 +541,11 @@ Seedance 2.0 (now the default for both atmosphere and character shots) accepts *
 - **Sequential action in image descriptions:** Causes comic-panel layouts instead of single frames. Separate the single-frame panel description from the full video action description.
 - **Vague body orientation:** Produces twisted poses. Always specify full-body direction explicitly (e.g., "seen entirely from behind", "facing camera directly").
 
+### Prompt-Style Mismatches
+
+- **Over-directing a simple-prompt model:** Hand-writing blocking, per-beat camera terms, `Lens switch.` lines, or geography-hold clauses into a MiniMax H3 Max prompt flattens the result — it stages its own coverage and the clauses fight it. The prompt builder strips these automatically; don't re-add them via authored shot fields expecting them to help.
+- **Padding an H3 Max prompt to clear the motion gate:** The Creator's `produce_shots` money gate normally demands 12+ words and motion vocabulary. For simple-prompt models it only asks for a stated subject and setting. Inflating a short, correct prompt to satisfy the old bar is the failure, not the fix.
+
 ### Style Consistency Failures
 
 - **Aesthetic description buried at end of prompt:** The model commits to a rendering style before reaching the style instructions, causing inconsistency between angles/shots. Always front-load style with a `STYLE:` prefix and add a `STYLE REMINDER:` suffix.

package/AGENTS.md

@@ -123,6 +123,44 @@ The full model registry lives in `src/venice/models.ts` with typed specs for eve
 - **R2V is pure-reference-only.** Sending `image_url` (or `end_image_url`) alongside `reference_image_urls` is a hard 400: *"image_url and end_image_url cannot be combined with reference media for this model."* `minimax-h3-reference-to-video` is therefore in `MODELS_USING_IMAGE_TAGS`, which is what puts the generator in pure reference mode. It honors `@ImageN` tags — verified by paid render, both tagged characters landed on their assigned `@Image1` / `@Image2` slots.
 - **Reference aspect influences output orientation, so keep a 16:9 plate in the stack.** With the harness's normal slot plan (1:1 character sheets + the 16:9 storyboard blocking plate) and `aspect_ratio: '16:9'`, a paid render returned a true 2560×1440. But a stack of uniformly portrait references returned 1440×1920 *despite* `aspect_ratio: '16:9'` — the requested ratio did not override them. Character-only H3 shots with no blocking plate are the orientation risk; check the first-frame contact sheet before assembling.
 
+**MiniMax H3 Max / H3 Max Turbo (added 2026-09-03):**
+- `minimax-h3-max-text-to-video` / `-image-to-video` / `-reference-to-video`, and
+  `minimax-h3-max-turbo-text-to-video` / `-image-to-video`.
+- **Related to MiniMax H3 in name only.** Four differences, each of which costs
+  a render if you assume H3 behavior:
+  - **768P, and 2K is a hard 400** (`Expected '480P' | '768P'`) — the exact
+    inverse of base H3. The generator's resolution pin matches
+    `minimax-h3-max` *before* `minimax-h3` for this reason; do not reorder
+    those branches. 480P is the draft tier, 768P the finish.
+  - **They want plain prompts** (`promptStyle: 'simple'` in the registry).
+    These models stage their own framing, coverage, and cutting from a stated
+    intent, and the directorial stack overrides that instinct. `buildVideoPrompt`
+    and `buildMontagePrompt` drop blocking, the locked location description, and
+    the geography-hold paragraphs for them; identity (`@ImageN`), the beat, the
+    line, the sound, and a compact look survive. Use `modelWantsSimplePrompt(id)`
+    rather than an id check when adding new behavior.
+  - **`private` tier** (H3 is `anonymized`), and uncensored. Prompt cap 10000
+    chars, though the useful prompt is a couple of sentences.
+  - **Price.** $0.024/s for H3 Max and $0.012/s for Turbo at 768P, against
+    $0.10/s for base H3 — Turbo is the cheapest lane in the registry, cheap
+    enough that a 15s take is disposable: render several and pick.
+- **Best used for montages and single-take storytelling.** This is where the
+  simple-prompt instinct pays: describe the sequence and let the model cut it.
+  Note the montage window now derives from the montage model's own ladder, so
+  H3 Max montages plan at 5-15s rather than Seedance's 30s.
+- Shared with H3: the 5-15s ladder (4s is a hard 400) and native audio that is
+  **not** toggleable, so the generator omits the `audio` field entirely.
+- **Turbo has no R2V lane.** `minimax-h3-max-turbo-reference-to-video` is
+  "Specified model not found", so the `minimax-h3-max-turbo` family routes
+  character-consistency and lip-sync shots to `minimax-h3-max-reference-to-video`.
+- R2V is treated as pure-reference (in `MODELS_USING_IMAGE_TAGS`) like H3 R2V.
+  Note the difference from H3: `/video/quote` *accepted* `image_url` alongside
+  `reference_image_urls` here, but quote validates less than queue, and
+  pure-reference is the right mode regardless — it keeps compositional
+  authority with the reference stack and is what makes `@ImageN` resolve.
+- i2v lanes inherit aspect from the start image and expose no `aspect_ratios`;
+  t2v and R2V accept `16:9 / 21:9 / 4:3 / 1:1 / 3:4 / 9:16`.
+
 **Long Duration:**
 - `longcat-image-to-video` / `longcat-distilled-image-to-video` (up to **30s**, no audio)
 - `ltx-2-fast-image-to-video` / `ltx-2-v2-3-fast-image-to-video` (up to **20s**, up to 4K)
@@ -440,6 +478,10 @@ Use `POST /video/quote` (via `quoteVideo()`) to estimate costs before committing
 
 57. **The browser UI is the built-in node web app — default to `venice-video web`.** When the operator asks for a browser UI, a dashboard, or to "open the harness in a browser," start the bundled local web app: `venice-video web` (browser dashboard + a whitelisted command runner over the workspace; binds localhost only, `http://127.0.0.1:3000` by default). Do NOT scaffold a separate/ad-hoc UI or point them at anything else. Per the workspace dev-server rule, kill existing node processes first and run on port 3000. The compiled front-end ships inside the npm package (`dist/web/ui/dist`); `npm run web:build` rebuilds it. Command lives in `src/mini-drama/cli.ts` (`web`), server in `src/web/server.ts`.
 
+58. **Loop mode has two modes — a disposable Turbo draft (watch) and an identity-locked Max R2V create — both gate-skipping and money-capped (2026-09-04).** `venice-video loop -p <project> -e <n> [--mode watch|create]` boots the web UI (Loop tab) plus an in-process `LoopEngine` (`src/mini-drama/loop-engine.ts`) that renders every shot into `episodes/episode-NNN/loop/` and keeps regenerating fresh takes so the browser can watch the whole plan on repeat while it evolves. Both modes **bypass the references(only for watch) / storyboard / QA gates** — the only hard precondition is a shot script with ≥1 shot — and write ONLY under `loop/` (`shot-NNN--takeK.mp4` + `loop-manifest.json`), never touching canonical `scene-001/` renders or `series.json`, so a loop can run alongside real production. **The mode is the session's first, REQUIRED decision** — the `loop` command asks "is this for LOOPING (creative flow, lower quality) or PRODUCTION (gather usable shots, higher quality)?" It is a deliberate quality-vs-flow tradeoff, never a silent default: interactive `promptChoice` in a TTY, and a **hard error** in a non-interactive run with no `--mode` (agents MUST pass it). `--mode` accepts natural words — `looping`/`loop`/`fun`/`creative` → watch, `production`/`prod`/`gather` → create (`normalizeLoopMode`). Internally the modes are still `watch`/`create`. **The two modes are the point:** (a) **watch** (enjoyment / creative flow) = MiniMax H3 Max **Turbo** at 480P (~$0.012/s): the first generation is **t2v**, every shot after it **chains i2v off the previous last frame**, and it **NEVER uses R2V** (R2V renders are too slow for a loop, and Turbo has none anyway). It ignores panels and the reference stack — identity is NOT locked; it is a fast fun loop, never production-fidelity. (b) **create** (gather good shots for a project) = the real reference-first routing on the **non-Turbo** H3 Max family at 768P (~$0.024/s): character shots render on `minimax-h3-max-reference-to-video` with the full `@Image` reference stack + voice-donor audio (identity **locked**, takes usable), atmosphere shots on Max i2v/t2v, **each shot rendered independently (chaining OFF by default** — R2V and a start frame can't combine on MiniMax). Create degrades a character shot to i2v/t2v only when its references are missing on disk — so for create, generate character/location references first (rule 54). Both share the render primitive: create mode reuses `resolveShotReferenceInputs` + `ensureVoiceReferenceForShot` (exported from `video-generator.ts`, the SAME resolution `renderSingleShotUnit` uses), so its reference stack can't drift from the real pipeline. Other invariants: (c) **chaining default follows the mode:** watch chains (shot 1 t2v, every later shot i2v off the previous shot's current-take LAST frame via `extractLastFrame`, so the loop plays as one piece); create does NOT chain (each shot is independent R2V — chaining and R2V are mutually exclusive on MiniMax). `--no-chain` forces it off. Chaining uses a lean prompt because the start frame, not a reference stack, drives the render. (d) **Every take renders the model's full length (15s default)** — not the shot's scripted duration — for maximum footage/playback per render; override with `--duration`. (e) **The loop regenerates continuously** and does NOT settle after a fixed number of takes: `--max-takes` is a **ring buffer** (candidate takes kept per shot; older non-current takes are pruned and their files deleted so an infinite run can't fill the disk), NOT a stop condition. It stops only on Pause, `--once` (one pass), or the budget. (f) **Money:** billed at queue time; `--budget` (default $2) pauses the loop, and the UI **Resume** button (or a per-shot regenerate) authorizes another budget's worth via `engine.start()` — so "Start/Resume" always does something. `--unbounded` removes the budget cap (spends until stopped) but keeps the ring buffer. (g) Resolution is reachable because `renderVideoFile` honors an optional `resolution` override validated against the model's `resolutions` (it otherwise force-pins `768P` for every `minimax-h3-max*` id); **watch defaults 480P (the infinite-loop tier), create 768P**. (h) The engine shares the web server's `EventHub` and broadcasts `loop-updated` for instant hot-swap; the manifest (with `mode` + `chain`) also feeds `collectEpisodeState` so a plain `venice-video web` shows the last loop state. (i) **A shot that fails `MAX_CONSECUTIVE_SHOT_ERRORS` (3) times in a row is given up on** — marked `failed`, dropped from `pickNext`, no longer re-queued/re-billed (a manual `regenerate` clears it). This caps the money leak where a server-side-doomed shot (a MiniMax i2v face start frame — billed at queue time, then `/video/retrieve` 500s) is otherwise re-selected fewest-takes-first and re-billed every cycle. (j) **Face-continuity prompting (`--face-continuity`, default on):** prompts each chained character shot to END on the character's face so the next i2v continuation is smoother — but it is **auto-suppressed** when the chain i2v model rejects face start frames (`i2vRejectsFaceStartFrame`, i.e. all MiniMax i2v lanes; a face-ending frame becomes the next start frame and would trip the death in anti-pattern 31). So it is dormant on both current loop lanes and activates on a face-accepting i2v lane; for face loops today use create/R2V. When changing loop behavior, keep `loop-engine.ts`, the `loop` command in `cli.ts`, the `/api/projects/:slug/loop/*` endpoints + `WebServerOptions.loop` in `src/web/server.ts`, `resolveShotReferenceInputs`/`extractLastFrame`/`i2vRejectsFaceStartFrame` in `video-generator.ts`/`models.ts`, and the `LoopView` UI in sync.
+
+59. **MiniMax H3 Max (simple-prompt) models IMPROVISE dialogue — the scripted line is intent, not a script (2026-09-04).** Unlike Seedance/Wan, which render the exact line you give them, the H3 Max family (`promptStyle: 'simple'`) performs markedly better carrying natural, continuous speech across a whole generation than reciting a verbatim quote — a fixed line fights the model the same way the directorial blocks do. So in **native-dialogue mode** the prompt builders render a speaker's line as INTENT — `[@ImageN, voice, delivery] conveys: "…"` plus a one-line "improvise naturally in character, keep the meaning and tone, don't recite word for word" note — instead of the directorial `[…]: "exact line"` quote. This is automatic via `shouldImproviseDialogue(modelId, series)` in `prompt-builder.ts` (`modelWantsSimplePrompt(modelId)` AND `videoDefaults.audioStrategy !== 'lip-sync'`), applied in both `buildVideoPrompt` (singles) and `buildMontagePrompt` (montage) — the two paths the H3 Max family renders through. Directorial models keep the exact quote; the legacy Seedance-native / Kling multi-shot builders (`buildMultiShotPrompt`) are untouched because those lanes are never simple-prompt. **The exception is exact-lip-sync**: there the `audio_url` drives the exact spoken words, so the line stays verbatim (the improv gate excludes `audioStrategy === 'lip-sync'`). **Consequence:** when a simple-prompt model improvises, burned/exported captions must be derived by transcribing the rendered audio (the editing pipeline's `silencedetect`/whisper path), NOT from `script.json` — the model will not say it word for word. When changing this, keep `shouldImproviseDialogue` / `formatDialogueLine` / `IMPROV_DIALOGUE_NOTE` in `prompt-builder.ts` and this rule in sync.
+
 ## Learned Anti-Patterns (Production Issues Log)
 
 Issues discovered during production and their fixes. The agent should internalize these to avoid repeating them.
@@ -632,6 +674,13 @@ Issues discovered during production and their fixes. The agent should internaliz
 **Root cause:** Seedance montage generations front-load transition frames so the beats can be cut apart; the per-beat cutter slices at the planned timestamps, so when the model's actual transition lands a few frames off the boundary, junk frames survive at a cut's head — most visibly on the first beat of unit 1, which becomes the film's opening frames.
 **Fix:** `qa-videos` detects it programmatically (per-frame luma scan over each unit's first second; a spike that reverts within 3 frames is a flash, not a scene change — ffmpeg `signalstats`, zero API cost). Fix by re-rendering the unit or trimming the flagged frames off the head of that beat's cut before assembly; for the film's first shot, always eyeball frames 0-10 of the final master before delivery.
 
+### 31. Loop Watch Mode: t2v Aspect 400, Chain Frame Past Stream End, Face Frames Die Server-Side (2026-09-04)
+**Symptom:** First watch-mode loop run failed at three successive layers. (a) Every t2v queue 400'd with `aspect_ratio: Required`. (b) After that was fixed, chained i2v takes 400'd with `image_url is required` because the extracted last-frame PNG did not exist — yet `extractLastFrame` had not thrown. (c) Once chaining produced real frames, every chained render whose start frame contained a recognizable human face queued successfully, then died server-side: `/video/retrieve` 500s ("An unknown error occurred") forever. The engine's give-up-after-6-polls path cleared the pending record and re-queued fresh, billing ~$0.18 per attempt (4 attempts on one shot).
+**Root cause:** (a) `renderVideoFile` set `aspect_ratio` only for `reference-to-video` and non-i2v Seedance; MiniMax H3 Max (Turbo) t2v REQUIRES it. (b) `extractLastFrame` probed the CONTAINER duration and sought to `duration - 0.05`; MiniMax writes an audio track slightly longer than the video stream, so the seek landed past the last decodable frame — and ffmpeg exits 0 having written no file. (c) MiniMax i2v accepts a face-bearing start frame at queue time (billed) but the render fails server-side, surfacing only as a retrieve 500. Faceless start frames (the robot) render fine; t2v (no input image) renders fine. There is no MiniMax equivalent of the Seedance 409 `needs_consent` handshake.
+**Fix:** (a) `video-generator.ts` now sets `body.aspect_ratio` for every `text-to-video` model as well. (b) `extractLastFrame` probes the `v:0` stream duration and steps back in widening offsets (0.1/0.3/0.6/1.0s) until the PNG actually exists on disk, throwing otherwise. (c) The face-death is Venice-side, but the fallout is now capped: `LoopEngine` counts consecutive render failures per shot and **gives up on a shot after `MAX_CONSECUTIVE_SHOT_ERRORS` (3)** — it is marked `failed`, dropped from `pickNext`, and no longer re-queued/re-billed (a manual `regenerate` revives it). This is the real fix for the money leak — note the re-queue was NOT `isQueueGoneError` (400/404/410, not 500): the loop force-requeues, so a doomed shot was re-selected fewest-takes-first by the *scheduler* every cycle. Watch mode with human faces still hits the death per chained take, so `--no-chain` remains the clean workaround; create mode routes character shots to R2V (face **references**, not a start frame) and, when refs are missing, now degrades to **t2v** instead of a face-bearing i2v (`i2vRejectsFaceStartFrame` in `models.ts`). **Verified 2026-09-04:** MiniMax **R2V** accepts face-bearing reference sheets — a 5s render off a character `front.png` succeeded in ~13s (`scripts/probe-minimax-r2v-face.ts`). So only i2v *start frames* die on a face, not R2V *references*: create-mode character loops are viable, and create/R2V is the working path for smooth character-face loops.
+**Related — face-continuity prompting:** the loop can prompt each chained shot to END on the character's face for smoother i2v continuations (`--face-continuity`, on by default), but it is **auto-suppressed on any i2v model that rejects face start frames** (all MiniMax i2v lanes), because a face-ending frame is the next shot's start frame and would trip exactly this death. So today it is dormant on both loop lanes; it activates on a non-MiniMax i2v lane or once Venice fixes MiniMax i2v. For face continuity now, use create mode (R2V locks the face from the sheets, no i2v chaining).
+**Files:** `src/mini-drama/video-generator.ts`, `src/mini-drama/loop-engine.ts`, `src/venice/models.ts`, `scripts/probe-minimax-r2v-face.ts`
+
 ## Output
 
 Generated project output belongs in:

package/CHANGELOG.md

@@ -1,5 +1,155 @@
 # Changelog
 
+## 2.20.0 — 2026-09-04
+
+### Fixed
+
+- **Loop watch mode: t2v `aspect_ratio` 400 + chain-frame past stream end (#25).**
+  `renderVideoFile` now sends `aspect_ratio` for every `text-to-video` model
+  (MiniMax H3 / H3 Max t2v **require** it — every opening watch take 400'd
+  without it). `extractLastFrame` now probes the `v:0` **stream** duration (not
+  the container, whose longer audio track pushed the seek past the last
+  decodable frame, making ffmpeg exit 0 with no file) and steps back in widening
+  offsets until the PNG lands, throwing otherwise so callers fall back to an
+  unchained render instead of queueing an `image_url`-less i2v.
+- **Loop money leak: a persistently-failing shot is now given up on.**
+  `LoopEngine` tracks consecutive render failures per shot and, after
+  `MAX_CONSECUTIVE_SHOT_ERRORS` (3), marks the shot `failed`, drops it from the
+  scheduler, and stops re-queueing it. Previously a server-side-doomed shot (a
+  MiniMax i2v start frame with a human face — billed at queue time, then
+  `/video/retrieve` 500s forever) was re-selected fewest-takes-first and
+  re-billed every cycle until the budget paused the loop. A manual `regenerate`
+  revives a given-up-on shot. `failed`/`lastError` are surfaced on the manifest
+  and `loop-updated` events.
+- **Create mode no longer degrades a character shot to a face-killing i2v.**
+  When a create-mode character shot has no R2V references on disk it now degrades
+  to **t2v** rather than i2v-off-a-panel on models that reject face start frames
+  (MiniMax) — a character panel almost always shows a face, which would 500.
+
+### Added
+
+- **`venice-video loop --face-continuity` (on by default).** Prompts each chained
+  character shot to end on the character's face so the next clip's i2v
+  continuation is smoother. **Auto-suppressed** on i2v models that reject face
+  start frames (all MiniMax i2v lanes — a face-ending frame is the next start
+  frame and would trip the server-side death), so it can't break the watch loop;
+  it activates on a face-accepting i2v lane. `--no-face-continuity` to disable.
+  New `i2vRejectsFaceStartFrame()` capability in `models.ts`.
+- **`scripts/probe-minimax-r2v-face.ts`** — one paid 5s probe to settle whether
+  MiniMax H3 Max **R2V** accepts face-bearing reference sheets (the open question
+  behind create-mode character loops). **Verified 2026-09-04: it does** (render
+  succeeded in ~13s) — only i2v *start frames* die on a face, so create-mode
+  character loops are viable.
+- Injectable `errorBackoffMs` on `LoopEngine` (test seam).
+
+See AGENTS.md rule 58 and anti-pattern 31.
+
+## 2.19.0 — 2026-09-04
+
+### Added
+
+- **`venice-video loop` — infinite loop mode (watch + create).** Boots the local
+  web UI (a new **Loop** tab) plus an in-process `LoopEngine`
+  (`src/mini-drama/loop-engine.ts`) that renders the approved shot script
+  continuously and plays the whole plan as a live browser loop, hot-swapping each
+  shot in as its take finishes and regenerating fresh takes while it plays. Two
+  modes, **chosen by a required decision at session start** — "is this for LOOPING
+  (creative flow, lower quality) or PRODUCTION (gather usable shots, higher
+  quality)?" — asked interactively in a terminal and a hard error in a
+  non-interactive run with no `--mode` (never a silent default). `--mode` accepts
+  natural words (`looping`/`loop`/`fun`, `production`/`prod`/`gather`). The modes:
+  **watch** (looping) renders
+  **MiniMax H3 Max Turbo at 480P** — the first generation is t2v, every later shot
+  chains i2v off the previous last frame, and it **never uses R2V** (too slow for
+  a loop); identity is NOT locked. **create** renders the **non-Turbo** H3 Max
+  family at 768P using the real reference-first routing — character shots on
+  `minimax-h3-max-reference-to-video` with the full `@Image` reference stack +
+  voice-donor audio (identity locked, takes usable), each shot rendered
+  independently, degrading to i2v/t2v when references are missing.
+  - **Continuous by default:** the loop regenerates forever (it does not stop
+    after N takes); `--max-takes` is a ring buffer (candidate takes kept per shot,
+    older ones pruned + deleted), not a stop condition. It stops only on Pause,
+    `--once`, or the budget.
+  - **Last-frame chaining** defaults to the mode (on for watch, off for create,
+    since R2V and a start frame can't combine on MiniMax); `--no-chain` forces it
+    off. Shot 1 renders normally, every later chained shot renders i2v off the
+    previous shot's last frame so the loop plays as one continuous piece.
+  - **Full-length takes:** every generation renders the model max (15s default),
+    override with `--duration`.
+  - **Budget as pause, not a hard stop:** `--budget` (default $2) pauses the loop;
+    the UI **Resume** button (and per-shot regenerate) authorizes another budget's
+    worth, so "Start/Resume" always does something. `--unbounded` removes the cap.
+  Both modes skip the storyboard/QA gates, write only under
+  `episodes/episode-NNN/loop/` (per-take mp4s + `loop-manifest.json`), and never
+  touch canonical renders or `series.json`. Resumable across restarts; pins and
+  per-shot regenerate from the UI. New
+  `/api/projects/:slug/loop/{state,start,stop,pin,regenerate}` endpoints, a shared
+  `EventHub` `loop-updated` event, and loop state surfaced through
+  `collectEpisodeState`. See AGENTS.md rule 58.
+- **MiniMax H3 Max (simple-prompt) models now improvise dialogue.** In
+  native-dialogue mode, `buildVideoPrompt` and `buildMontagePrompt` render a
+  speaker's scripted line as INTENT for these models — `[@ImageN, voice,
+  delivery] conveys: "…"` plus a "improvise naturally in character, keep the
+  meaning and tone, don't recite word for word" note — instead of the
+  directorial `[…]: "exact line"` quote. Gated on
+  `shouldImproviseDialogue(modelId, series)` (`modelWantsSimplePrompt` AND
+  `audioStrategy !== 'lip-sync'`). Seedance/Wan/Kling keep the exact quote, and
+  exact-lip-sync keeps the exact line (the `audio_url` drives the words). See
+  AGENTS.md rule 59. Note: captions for these shots should come from
+  transcribing the rendered audio, not `script.json`.
+- **`resolveShotReferenceInputs` / `ensureVoiceReferenceForShot` exported from
+  `video-generator.ts`.** The per-shot reference/scene/voice resolution block was
+  extracted from `renderSingleShotUnit` into a shared `resolveShotReferenceInputs`
+  helper (behavior-identical; `renderSingleShotUnit` now calls it) so loop create
+  mode resolves the exact same reference stack the real pipeline does instead of a
+  divergent copy.
+- **`resolution` override on `renderVideoFile`.** Honored only when the model
+  lists it (validated against the registry, else the family default applies), so
+  loop mode can pin H3 Max Turbo to its 480P draft tier without disturbing the
+  `768P`/`2K`/`720p` auto-pins every other path relies on.
+- **MiniMax H3 Max + H3 Max Turbo** (probe-verified 2026-09-03):
+  `minimax-h3-max-text-to-video` / `-image-to-video` / `-reference-to-video`
+  and `minimax-h3-max-turbo-text-to-video` / `-image-to-video`. 768P/480P,
+  5-15s, native non-toggleable audio, `private`, uncensored. $0.024/s and
+  $0.012/s at 768P (base H3 is $0.10/s). Turbo ships no R2V lane. Two new
+  video families — `minimax-h3-max` and `minimax-h3-max-turbo` — both routing
+  identity to `minimax-h3-max-reference-to-video`, which is the only lane in
+  the pair with `audio_input: true` and therefore also the family lip-sync model.
+- **`promptStyle` on `VideoModelSpec`, and a simple-prompt path in the prompt
+  builder.** H3 Max models are `promptStyle: 'simple'`: they stage their own
+  framing, coverage, and cutting from a plain statement of intent, and the
+  directorial stack flattens that. `buildVideoPrompt` and `buildMontagePrompt`
+  now drop spatial blocking, the locked location description, and the
+  geography-hold paragraphs for these models, and use the compact aesthetic
+  instead of the full one. Identity declarations, reference role clauses, the
+  beat, dialogue, sound, and the hard-cut instruction are kept — those are not
+  inferable. Gate new behavior on `modelWantsSimplePrompt(id)`, not id checks.
+  Every other family is unchanged (`'directorial'` is the default).
+
+### Fixed
+
+- **The resolution pin no longer sends H3 Max to 2K.** `renderVideoFile` matched
+  `minimax-h3` by substring, so every `minimax-h3-max-*` render would have been
+  pinned to `2K` — a hard 400 on those models. The `minimax-h3-max` branch now
+  precedes it and pins `768P`.
+- **Montage windows are bounded by the montage model, not a flat 30s.**
+  `resolveMontageMaxDurationSec` accepted a `montageModel` and ignored it,
+  always returning Seedance 2.5's 30s ceiling. Pointing `montageModel` at any
+  shorter-ladder model (H3 Max tops out at 15s) therefore planned 30s units
+  that all failed `assertShotDurationsValid` *after* the plan was written. The
+  ceiling now comes from the model's `maxDurationSec` and an explicit
+  `montageMaxDurationSec` is clamped to it. New `resolveMontageMinDurationSec`
+  does the same for the floor, so H3 Max montages respect its 5s ladder start
+  instead of Seedance's 4s.
+- **Registry resolution ORDER is now load-bearing, and the Creator app honors
+  it.** The app defaults to the first allowed resolution whenever a plan's own
+  value isn't offered, and Venice's live `/models` lists H3 Max as
+  `["480P", "768P"]` — so the app would have rendered every H3 Max shot at its
+  draft tier. H3 Max entries list `['768P', '480P']` deliberately, and the app
+  reorders the live list to follow the manifest
+  (`VideoModelCapabilities.preferredResolutionOrder`). When editing a
+  `resolutions` array, treat position 0 as the default, not as arbitrary.
+
 ## 2.18.0 — 2026-08-21
 
 ### Added

package/README.md

@@ -552,6 +552,8 @@ Live catalog (synced against `GET /api/v1/models?type=video` — 103 entries). F
 | **HappyHorse 1.1** | i2v, R2V (up to 9 refs) | t2v | 15s | Yes (joint single-pass, 7-lang phoneme lip-sync) | **#1 blind-preference T2V + I2V** (Alibaba 15B). 3-15s, 720p/1080p, nine aspect ratios. Best for talking characters + multilingual localization; SFW/commercial-leaning. The `happyhorse` video-family now routes here. |
 | **HappyHorse 1.0** | i2v, R2V | t2v | 15s | Yes | Prior line, kept for back-compat. Livelier hand-camera realism / cinematic grain vs Seedance. |
 | **MiniMax H3** | i2v, R2V (up to 9 refs) | t2v | 15s (**5s floor**) | Yes (native stereo, not toggleable) | Open-weight omni-modal model — one net covers T2V/I2V/reference. **2K is the only resolution** (no draft tier) at ~1/3 the per-second cost of other families; 24fps, 2500-char prompts. The `minimax-h3` video-family routes here. Sub-5s durations are a hard 400. |
+| **MiniMax H3 Max** | i2v, R2V (up to 9 refs) | t2v | 15s (**5s floor**) | Yes (native, not toggleable) | **Simple prompts — the model stages its own coverage.** Registry `promptStyle: 'simple'`, so the prompt builder strips blocking, locked location descriptions, and geography-hold clauses; say the intent in a sentence or two. Best for montages and beats where the model telling its own story is the point. **768P max — 2K is a hard 400**, the inverse of base H3 (480P is the draft tier). `private` tier, uncensored, 10000-char prompts. $0.024/s. The `minimax-h3-max` video-family routes here. |
+| **MiniMax H3 Max Turbo** | i2v | t2v | 15s (**5s floor**) | Yes (native, not toggleable) | Same model and constraints at **$0.012/s — the cheapest lane in the registry**, which makes 15s takes cheap enough to render several and pick. **No R2V lane** (`-turbo-reference-to-video` does not exist), so the `minimax-h3-max-turbo` family routes identity shots to `minimax-h3-max-reference-to-video`. |
 | **Wan 3.0** | i2v, R2V (up to 9 refs), Enhanced | t2v | **30s** | Yes (always on, not toggleable) | **Longest shots on Venice** — 5/10/15/20/25/30s at 480p/720p/1080p, five aspect ratios plus adaptive, 5000-char prompts. The `wan-3-0` video-family routes here. No audio input anywhere in the family, so it can't lip-sync to a supplied recording. `*-enhanced-*` variants are beta. |
 | **Wan 2.7** | i2v, R2V, V2V, Spicy | t2v | 15s | Wan i2v has no audio; lip-syncs via `audio_url` input | **The audio-driven fallback for exact lip-sync.** R2V exposes per-element `audio_url` for multi-speaker. Spicy = uncensored i2v variant. Seedance 2.x R2V and MiniMax H3 R2V also accept a top-level `audio_url`, so those families never route here. |
 | **Wan 2.6** | Standard, Flash, R2V | Standard | 15s | Yes (i2v/t2v); R2V capped at 10s | Now has R2V variant with `audio_url` input. 1080p. |
@@ -930,6 +932,115 @@ a persistent history file; `Ctrl-C` cancels the running command without killing
 the session (`Ctrl-D` or `/exit` leaves); `/help`, `/status`, `/jobs`, `/cd`, and
 `/pwd` are shell meta-commands; `!<cmd>` runs something in your system shell.
 
+### Loop mode — watch the whole plan while it renders, or iterate on real shots
+
+Once a plan exists (an approved shot script), you can play the entire film as a
+live browser loop while the harness renders it, instead of waiting for the full
+gated pipeline:
+
+```bash
+venice-video loop -p ~/VeniceVideos/my-film -e 1                   # asks the purpose
+venice-video loop -p ~/VeniceVideos/my-film -e 1 --mode looping    # or state it
+venice-video loop -p ~/VeniceVideos/my-film -e 1 --mode production
+```
+
+Loop mode starts with one **required, deliberate decision** — **is this for
+LOOPING or for PRODUCTION?** — because it is a real quality-vs-flow tradeoff, not
+a default to fall through. In a terminal it asks; non-interactively you must pass
+`--mode` (it errors otherwise). You can state it in plain words —
+`--mode looping` / `loop` / `fun` / `creative`, or `--mode production` / `prod` /
+`gather`:
+
+- **Looping — creative flow, lower quality.** The first generation is **t2v**,
+  every shot after it **chains i2v off the previous shot's last frame**, and it
+  **never uses R2V** (those renders are too slow for a loop). Turbo, 480P, fast.
+  Not final-quality; it's for watching and riffing.
+- **Production — gather usable shots, higher quality.** **Max R2V + references**
+  at 768P, identity locked, each shot rendered independently. Slower, but the
+  takes you pin are keepers.
+
+Either way it boots the local web UI, opens the browser to a **Loop** tab, and
+**auto-starts** a background engine that renders each shot into the episode's
+`loop/` directory and **keeps regenerating fresh takes continuously** (it does
+not stop after a fixed number of takes — only a Pause or the budget stops it).
+The plan plays on repeat and each shot hot-swaps in as its take finishes;
+because the render outruns playback, the video keeps evolving. Pin the keepers,
+regenerate the ones you don't, and watch a running spend meter. Both modes
+**skip the storyboard/QA gates** and write **only** under `loop/` — canonical
+`scene-001/shot-NNN.mp4` renders and `series.json` are never touched, so a loop
+can run alongside real production.
+
+Two behaviors make the loop play as one continuous piece:
+
+- **Last-frame chaining (default on).** Shot 1 renders normally; **every shot
+  after the first renders i2v using the previous shot's last frame as its first
+  frame**, so the clips flow into each other. Turn it off with `--no-chain` to
+  render each shot independently (in create mode that keeps per-shot R2V identity
+  locking).
+- **Full-length takes.** Every generation renders the model's full length
+  (**15s** by default — MiniMax H3 Max's max), for maximum footage and playback
+  per render. Override with `--duration`.
+
+Because the engine auto-starts, the **Loop** tab shows **Pause** while it's
+running. It regenerates until you Pause or the budget is reached; when the budget
+is reached it pauses and the button becomes **Resume**, which authorizes another
+budget's worth and continues. (`--max-takes` is a ring buffer — the number of
+candidate takes kept per shot — not a stop condition; older takes are pruned so
+an infinite run can't fill the disk.)
+
+The two modes differ in what they render:
+
+| Purpose (`--mode`) | Model | Resolution | Identity | Use it to… |
+|---|---|---|---|---|
+| **looping** | MiniMax H3 Max **Turbo** t2v/i2v (~$0.012/s) | 480P | **not** locked (Turbo has no R2V lane) | keep a fast, continuous loop going for creative flow |
+| **production** | MiniMax H3 Max **R2V** for character shots, i2v/t2v otherwise (~$0.024/s) | 768P | **locked** via the project's reference stack | gather real, usable shots and pin keepers |
+
+Production mode uses the same reference-first routing as the real pipeline:
+character shots render on `minimax-h3-max-reference-to-video` with the full
+`@Image` reference stack (character sheets, location angles, blocking plates)
+plus voice-donor audio, so identity holds. Shots with no references on disk
+degrade to i2v (off a panel) or t2v, so generate your character/location
+references first for the full effect.
+
+Continuous regeneration spends money, so it is capped by default:
+
+```bash
+venice-video loop -p <dir> -e 1 \
+  --mode production \      # looping | production (required; also accepts loop/fun, prod/gather)
+  --resolution 768P \      # defaults: 480P (looping) / 768P (production)
+  --duration 15s \         # per-take length, snapped to the 5-15s ladder (default 15s)
+  --budget 2 \             # pause after ~$2; Resume/regenerate authorizes another budget
+  --max-takes 3 \          # candidate takes kept per shot (ring buffer, not a stop)
+  --no-chain \             # render shots independently instead of i2v last-frame chaining
+  --no-face-continuity \   # don't prompt chained shots to end on the character's face (see below)
+  --once                   # or: render one take per shot, then stop
+# --unbounded              # remove the budget cap (spends until you Ctrl-C)
+```
+
+The loop is resumable: takes, pins, and spend are recorded in
+`loop/loop-manifest.json`, so re-running `loop` picks up where it left off.
+`Ctrl-C` stops the engine and the server.
+
+**A shot that keeps failing is given up on, not re-billed forever.** After 3
+consecutive render failures the engine marks the shot `failed`, stops scheduling
+it, and moves on — so a server-side-doomed shot (e.g. a MiniMax i2v start frame
+with a human face, which Venice bills at queue time then 500s on retrieve) can't
+burn the whole budget one failed take at a time. A manual **regenerate** in the
+UI revives it.
+
+**Face continuity (on by default, for smoother i2v transitions).** In a chained
+loop each shot's last frame becomes the next shot's i2v start frame, so
+`--face-continuity` (default on) prompts each character shot to **end on the
+character's face**, giving the next clip a clean anchor to continue from
+(`--no-face-continuity` turns it off). One important caveat: MiniMax i2v renders
+**die server-side when the start frame shows a face** (AGENTS.md anti-pattern
+31), so on the MiniMax loop lanes this prompting is **auto-suppressed** — a
+face-ending frame would kill the next chained render. It activates on any i2v
+model that accepts face start frames. For smooth character-face loops **today**,
+use **production** mode: R2V locks the face from the reference sheets across every
+shot, with no i2v chaining involved (verified — MiniMax R2V accepts face-bearing
+reference sheets; only i2v *start frames* die).
+
 ### Interrupted renders are resumable
 
 The harness records each Venice `queue_id` to disk *before* it starts polling, so
@@ -1018,7 +1129,7 @@ These defaults are overridable per-project via `series.json` → `videoDefaults`
 
 ### Picking a family at project creation
 
-`venice-video new` asks which family to use, and `venice-video new-series` asks too when it's run on a terminal without `--video-family`. Both write the answer to `series.json` → `videoDefaults.videoFamilyPreference` and swap the action / atmosphere / character-consistency models to match. The wizard orders the families as Automatic, Seedance, Wan 3.0, MiniMax H3, HappyHorse, Grok Imagine, then Kling O3.
+`venice-video new` asks which family to use, and `venice-video new-series` asks too when it's run on a terminal without `--video-family`. Both write the answer to `series.json` → `videoDefaults.videoFamilyPreference` and swap the action / atmosphere / character-consistency models to match. The wizard orders the families as Automatic, Seedance, Wan 3.0, MiniMax H3, MiniMax H3 Max, MiniMax H3 Max Turbo, HappyHorse, Grok Imagine, then Kling O3.
 
 ### Choosing dialogue audio