[ffroliva]

Summary

Flow's video settings popover is model-conditional. Verified live on two accounts and two locales: only omni_flash renders a 4s/6s/8s/10s duration row; the Veo 3.1 models render no duration control at all.

api/video.py claimed "the four VEO_3_1_* models cap at 8s", which presumed a control that is never drawn. _select_video_duration therefore hunted a missing element and died with UiSelectorDriftError (exit 23) after ~30 s.

That explains every confusing symptom on #451/#288: it looked like drift, it reproduced identically on playwright 1.59 and 1.61 (so the version bound was correctly exonerated), and the locale hypothesis was correctly refuted. It was never either.

Changes

• VideoModel.supports_duration() — true only for OMNI_FLASH.
• --duration on a Veo model now exits 2 before any browser work, naming the model and the remedy. Guarded at the CLI edge (UsageError, like --ui-mode agentic) because a bare DTO ValueError surfaces as "Unexpected error." exit 1 and the explanation is lost. The DTO guards it too, as defence in depth for API/MCP callers.
• --reference-entity removed from video i2v, where _validate_i2v_symmetry rejects reference entities — the flag was advertised but raised for every caller who believed it. Still on t2v/r2v.
• Docs had the mirror-image error: REFERENCE_STRATEGIES.md, USAGE.md and the t2v help text all denied a flag that cli_video.py registered. Corrected in all four places, plus a --duration model-constraint note.
• ReferenceNotFoundError (exit 32) — --ref-name searches Flow's picker, which indexes Flow's short auto-caption, not the generation prompt. A miss was a bare Playwright TimeoutError after 8 s; it now lists what the picker actually offered.
• reference_cap_for documents the live-verified ingredient rule it already encoded.

Verified end to end (not just unit-green)

Command	Result
t2v --model veo-lite --duration 8	exit 2 + reason (was exit 1 "Unexpected error")
i2v --model veo-fast --duration 6	exit 2 + reason
i2v --model omni-flash --duration 6	passes — negative control, no over-reject
i2v --reference-entity X	exit 2 "No such option"
flags	t2v ✓ · i2v ✗ · r2v ✓

1689 passed / 3 skipped (cli+api+features) · 162 passed (mcp) · pyright 78 = exact baseline · ruff, hygiene, doc-links, PII, website mirror all green.

e2e caught two defects in this very fix that unit tests and --help both missed: the ValueError surfacing as exit 1, and i2v() crashing with a TypeError because the Click options were removed but the function parameters weren't.

Self-review

/ponytail:ponytail-review on my own diff found supports_image_ingredients() had zero production callers — orphaned when the redundant guard was correctly deleted, since reference_cap_for already encodes the rule. Deleted; evidence folded into reference_cap_for. (351ae6c)

Also included — two #493 negative results

Committed so they are not re-derived, since both hypotheses are compelling:

1. crop_free trigger — REFUTED. CROP_SELECTORS omits crop_free (the Frames tab icon), and video r2v: UiSelectorDriftError probe=mode_switch_trigger — new Flow editor variant (composer frame slots + Agente toggle) not recognized (v0.55.0) #493's reporter sees Frames-mode slots. Tested on pt-BR: the trigger renders crop_16_9 in both Frames and Ingredients modes. The trigger reflects the aspect, not the sub-mode.
2. Hydration race — REFUTED by live A/B. A cold editor genuinely has 0 [aria-pressed] nodes and 0 crop_* triggers on load, which appeared to explain both symptoms at once. But with the hydration wait neutered, 3/3 cold loads still succeed: _probe_selector_cascade already waits 4 s per selector for visible. The fix was a no-op, so it was reverted rather than shipped.

Net: #493's editor renders no crop_* across the cascade's full ~24 s budget, so it is a real DOM difference, not timing. Its diag_mode_switch_miss.json remains the gating artifact.

Refs #451, Refs #288, Refs #493

[ffroliva]

/code-review xhigh findings addressed (eefe2d0)

The review found 15 issues, including a hole in this PR's own headline claim and a regression in a shipped scaffold. Each fix verified:

Hole in the core claim. Both guards returned early when model is None, but the transport substitutes I2V_DEFAULT_MODEL — so i2v's default path still hit the exact #451/#288 failure. The DTO now resolves the model the transport will actually use:

i2v + frames + --duration, no --model  ->  REJECT naming 'veo_3_1_lite'   (was ACCEPT)

t2v/r2v with no --model stay unguarded by design — Flow's sticky UI default is genuinely unknowable at DTO time.

Regression in a shipped scaffold. gflow movie template paired duration with veo-lite and veo-quality, so the generated starter file raised at request construction. Fixed — 3/3 template scenes now construct valid requests (two were raising).

r2v was never wired to the CLI-edge guard, so it fell through to the DTO's bare ValueError → "Unexpected error." exit 1. Now exit 2 with the reason, like t2v/i2v.

max_duration_for() still returned 8 for the Veo models — contradicting supports_duration() twelve lines below, and making gflow models advertise a duration users cannot set. Now 0, test updated to the verified contract.

All three --help strings still said "10 requires --model omni-flash", implying 4/6/8 work on Veo models. That's the first surface users read, and it walked them straight into the failure. Swept.

ReferenceNotFoundError named a --ref-name flag that doesn't exist (ref_names is DTO/MCP-only), was missing from __all__ and the USAGE exit-code table, and had no test. All fixed; the inline screenshot clause now reuses screenshot_clause().

A dead is not None branch was masking an escaping ValueError from from_cli on an unknown alias. Handled.

The #493 spike docstring still asserted a mode_control.await_composer_hydrated fix that was reverted in the very commit that refuted it — corrected, so no future reader concludes a rescue landed that never did.

Tests added

• exit-32 contract + problem-details, matching the per-error convention in tests/test_errors.py
• CLI matrix: t2v/i2v/r2v × veo-lite/veo-fast/veo-quality → exit 2 + reason, plus an omni-flash negative control proving no over-reject

Verification

1684 passed / 3 skipped (api+cli+errors) · 10 passed new CLI matrix · 56 passed errors · pyright 78 = exact baseline · ruff, format, hygiene (755), doc-links (29), PII, website mirror — all green.

Still open (not in this PR)

Three review findings deliberately deferred rather than rushed, all pre-existing in shape:

1. chain.py — a per-link duration aborts mid-run after earlier links are billed, and _resolve_chain_model forces a Veo model, so chain durations are invalid by construction. Needs manifest-level pre-validation before the run starts, which is its own change.
2. The except PlaywrightTimeoutError around _pick_option_and_include is broader than the name-miss it reports, so an unrelated timeout inside it would be relabelled.
3. The typed error is at one call site rather than in the shared helper, so _attach_remote_frame's identical i2v miss still raises untyped.

[ffroliva]

Correction to this PR's description. It says "Also included — two #493 negative results". That is wrong for the crop_free one: f2f05e6 lives on #536, not here. This branch was cut from develop before #536 landed.

Accurate split:

• fix(video): model-capability guards — root-cause fix for #451/#288 #537 (this PR) — the i2v: Flow dropped the duration-tab UI — --duration fails closed on every playwright version #451/video i2v: --duration is silently ignored when the duration tab probe fails (requested 4s, got 8s) #288 capability guards, the video r2v: UiSelectorDriftError probe=mode_switch_trigger — new Flow editor variant (composer frame slots + Agente toggle) not recognized (v0.55.0) #493 sidebar-close fallback and its live e2e, and the hydration-race negative result (10498f2).
• spike(493): refute the crop_free trigger hypothesis (negative result) #536 — the crop_free negative result (f2f05e6) and the r2v Ingredients probe (a14dec2, which had been committed locally but never pushed — now recovered).

Both are green. #536 is evidence-only (scripts/dev/ + spike doc); this PR carries the product changes. They touch different files, so either merge order works.