gflow-cli 0.13.0__tar.gz → 0.14.0__tar.gz

{gflow_cli-0.13.0 → gflow_cli-0.14.0}/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0] — 2026-06-07
+
+### Added
+
+- **`gflow movie` — multi-scene, character-consistent video generation.** A TOML
+  manifest (`gflow movie template` / `gflow movie run`) drives a sequence of clips
+  that reuse a single Flow CHARACTER entity (reference-to-video) so the same face
+  and voice carry across every scene. Generate-only by default; `--stitch`
+  produces an ffmpeg preview concat; runs are crash-resumable via the sibling
+  `<manifest>-state.json`; a versioned handoff manifest is written for downstream
+  composition (e.g. Remotion). Deterministic prompt assembly (`composition.py`),
+  scene = clip.
+- **`docs/MOVIE.md`** — manifest format, the run lifecycle (the headed browser is
+  required through generate → poll → download), the character-entity attach
+  mechanism, and the best-effort consistency model.
+- Dev utilities: `scripts/dev/make_project.py` (create a Flow project) and
+  `scripts/dev/patch_character.py` (rename / set voice + personality on an entity).
+
+### Fixed
+
+- **R2V character reuse now actually rides the wire.** The entity is attached via
+  the resource picker's **Personagens tab → right-click → "Incluir no comando"**
+  (which stages `referenceEntities`; a left-click on the Tudo tile only stages the
+  thumbnail as a `referenceImage`). The submit backstop now reads the response's
+  real `media[].mediaMetadata.requestData.videoGenerationRequestData.videoGenerationEntityInputs`
+  path instead of the request-shape `requests[].referenceEntities` — which had
+  false-rejected every successful entity generation. `omni-flash` R2V verified to
+  carry the entity.
+- Cleared pre-existing type/test debt: `pyright src` is clean again (the missing
+  `project_id` parameter was added to the `VideoCapableTransport` protocol and the
+  `_enter_editor` type stub); regenerated `uv.lock` (jsonschema dev dependency).
+
 ## [0.13.0] — 2026-06-04
 
 ### Added
@@ -1402,7 +1434,8 @@ shell-script template that branches on these codes.
 
 First skeleton. Not functional end-to-end yet.
 
-[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.13.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.14.0...HEAD
+[0.14.0]: https://github.com/ffroliva/gflow-cli/compare/v0.13.0...v0.14.0
 [0.13.0]: https://github.com/ffroliva/gflow-cli/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/ffroliva/gflow-cli/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/ffroliva/gflow-cli/compare/v0.10.0...v0.11.0

{gflow_cli-0.13.0 → gflow_cli-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.13.0
+Version: 0.14.0
 Summary: Unofficial CLI for Google Flow — drive Veo image-to-video generations from the terminal.
 Project-URL: Homepage, https://github.com/ffroliva/gflow-cli
 Project-URL: Issues, https://github.com/ffroliva/gflow-cli/issues

gflow_cli-0.14.0/PR162_MOVIE_CHARACTER_REVIEW.md

@@ -0,0 +1,137 @@
+# PR #162 Review — Movie Orchestration Character Consistency
+
+**Branch:** `pr162` · **Scope:** `gflow movie` orchestrator (`cli_movie.py`, `movie_manifest.py`) + video transport
+**Verdict:** Sound foundation, correct project consolidation, but the headline goal (consistent character) is **not achievable with the current r2v-by-uploaded-image approach** — and there is a **release-blocking `NameError` that aborts every multi-scene run after scene 1.**
+
+---
+
+## TL;DR
+
+| # | Objective | Finding |
+|---|-----------|---------|
+| 0 | *(not in brief)* | 🔴 **CRITICAL** — `asyncio.sleep(5)` at `cli_movie.py:344` with **no `import asyncio`** → `NameError` on the 2nd scene of every movie, outside the try/except → whole run aborts after 1 scene. |
+| 1 | Native character integration | ✅ **Feasible & protocol-ready.** Flow's wire has a native field `referenceEntities:[{entityId}]` on `video:batchAsyncGenerateVideoReferenceImages` (live-verified, `docs/CHARACTER.md §6.6/§8`). The entity_id is *already saved* in state but never used. Needs a new transport path (composer resource-picker → "Personagens") + DTO field. |
+| 2 | r2v vs i2v / chain | ✅ The chaining engine **already exists** (`chain.py`, `media.extract_last_frame`, `gflow video chain`). It's just not wired into `movie.toml`. r2v+entity = identity; i2v-chain = motion continuity; **mutually exclusive per generation** (DTO enforces frames XOR references). |
+| 3 | Project consolidation | ✅ **Correct and it's the enabler.** `manifest.project` is threaded to character-create *and* every scene; `_enter_editor` deep-links to that project. This is exactly the precondition that makes native `referenceEntities` selection possible. |
+| 4 | Error handling (`generate_resp`/403) | ✅ **Already fixed.** `generate_resp={}` bound before `try` (`:1421`); 403→`WafRejectionError`, silent→`TimeoutError`; listeners freed in `finally`. No UnboundLocal remains. |
+
+---
+
+## 0. 🔴 CRITICAL — `asyncio` is not imported (multi-scene runs crash)
+
+`cli_movie.py:342-345`:
+
+```python
+# reCAPTCHA cooldown
+if completed_scene_ids:
+    await asyncio.sleep(5)      # NameError: name 'asyncio' is not defined
+```
+
+- `asyncio` appears **exactly once** in the file (the usage); it is **not** in the import block (`:17-44`).
+- `completed_scene_ids` is non-empty from the 2nd scene onward (appended at `:373`, and on resume at `:332`).
+- The call sits **outside** the per-scene `try/except` (`try` starts at `:346`), so the `NameError` propagates out of `_run_movie` → caught by `run_with_handlers` → **the entire movie aborts after exactly one scene**, regardless of `--continue-on-error`.
+- On *resume* it's worse: the first already-completed scene appends to `completed_scene_ids`, so the very first new scene hits the cooldown and crashes → **resume can make zero forward progress.**
+
+**Why it escaped CI:** the only async-orchestrator test (`tests/cli/test_cli_movie.py:368 test_happy_path_no_characters`) uses a **single** scene. No test drives `_run_movie` with ≥2 scenes, so the cooldown branch is never executed. (The `out/stickman-v3/` artifacts predate this regression — file mtime is later than the renders.)
+
+**Fix (one line):** add `import asyncio` to the import block. **Then add a 2-scene orchestrator test** so this can't regress (see §6).
+
+---
+
+## 1. Native character integration — the real fix for divergence
+
+### Current behaviour (confirms the brief)
+- `character_create` downloads face/body to **local disk**; `CharacterState` stores both `entity_id` *and* `image_paths` (`cli_movie.py:454-457`).
+- `_collect_refs` (`cli_movie.py:470-483`) returns **only `image_paths`** for r2v. `entity_id` is captured and then ignored.
+- `_generate_scene` passes those local paths as `reference_images`; the transport's `_attach_references` (`ui_automation_video.py:1092`) **re-uploads each file** via the "Add Media" dialog → fresh media IDs every scene → Flow sees unrelated assets → the Stickman drifts. **Exactly the diagnosed flaw.**
+
+### The native path exists and is verified
+From `docs/CHARACTER.md §6.6` (live-verified 2026-06-02, `labs.google23.har`):
+
+```json
+"video:batchAsyncGenerateVideoReferenceImages" → {
+  "referenceImages":   [ { "mediaId", "imageUsageType":"IMAGE_USAGE_TYPE_ASSET" } ],
+  "referenceEntities": [ { "entityId" } ]      // ← native character identity
+}
+```
+
+- `referenceEntities` is a **list** → multi-character per scene (`VIDEO_MODEL_CAPABILITY_MULTI_REFERENCE`).
+- UI flow: composer → resource picker (*"Pesquisar recursos"*) → **Personagens** tab → select → **"Incluir no comando"** → injects `referenceEntities`.
+- CLI `gflow video … --character <id>` is documented **backlog Phase 3 — unimplemented** (`docs/CHARACTER.md §8`). So this is *new automation*, not a refactor of existing code.
+
+### Proposed refactor
+
+**(a) DTO** — `api/video.py`, `GenerateVideoRequest`:
+```python
+reference_entities: tuple[str, ...] = ()   # R2V — Flow CHARACTER entity ids
+```
+⚠️ Relax `__post_init__`: today R2V **requires** `reference_images` (`video.py:249-252`). Change to *require `reference_images` **or** `reference_entities`* (either anchors the clip). Keep frames XOR references.
+
+**(b) Transport** — new `_attach_character_entities(page, names, out_dir)` that, in `references` sub-mode, opens the resource picker, switches to the Characters/"Personagens" tab, selects each character **by display name**, clicks "Include in prompt". In `_generate_video_locked` R2V branch (`:1406`): if `request.reference_entities` → use entity attach; else fall back to `_attach_references`. (Both *may* coexist per the wire.)
+- **Defense-in-depth (mirror the #125 backstop):** after submit, assert the captured generate payload's `referenceEntities` contains the expected `entityId`; if it's missing, raise rather than report a false success — otherwise an entity that silently failed to attach degrades to a plain text-only clip with no warning.
+
+**(c) Orchestrator** — `_collect_refs` → return entity refs when `CharacterState.entity_id` is present, image paths only as fallback. Pass `reference_entities=(...entity_ids...)` into `GenerateVideoRequest`. Selection is **by name** (what the picker shows); `entity_id` is the verification key. No `movie.toml` change needed — `characters = ["Stickman"]` already names them; the orchestrator maps name→entity_id from state.
+
+**(d) Pre-flight guard** — before the scene loop, verify each named entity actually exists in the project (`client.get_character(entity_id=...)`). Currently `_collect_refs` silently **drops** a missing character (`log.warning` + `continue`, `:478`) → the scene generates with **no refs at all** → guaranteed divergence with no hard failure. Fail loud instead.
+
+---
+
+## 2. r2v vs i2v for journey continuity — the chain engine already exists
+
+**Key constraint:** R2V "references" and I2V "frames" are **separate, mutually-exclusive composer sub-modes** (`_switch_video_sub_mode`, `:903`) and the DTO enforces it (`video.py:245-252`). You **cannot** have character-entity identity *and* a seeded start-frame in the *same* generation.
+
+What each buys you:
+- **r2v + `referenceEntities`** → strong **identity** consistency per clip; hard cuts between scenes.
+- **i2v chain** (scene N+1 start = scene N's last frame) → **motion/visual continuity**; but link 0 has no identity anchor and identity drifts frame-to-frame.
+
+**You already have the chain machinery** — it's just not exposed in `movie.toml`:
+- `media.extract_last_frame(src, dst, *, offset_ms=0)` (`media.py:31`)
+- `chain.run_chain(...)` + `ChainLinkSpec`/`ChainLinkResult`/`FrameExtractor` protocols (`chain.py:74-185`) — record-before-extract, crash-resumable.
+- `chain_repo.ChainLinkRecorder` + migration `0005_add_chain_links.sql`.
+- `gflow video chain` (`cli_video.py:324 _run_chain`): "link 0 as T2V, every later link as I2V seeded by the previous clip's last frame."
+
+**Recommendation:** add an opt-in chain mode to `movie.toml` that routes through the existing `chain.run_chain()` rather than reimplementing it (e.g. top-level `mode = "chain"`, or scene-level `chain_from = "<previous scene title>"`). Then give honest guidance in docs:
+
+> For a **journey where the character must stay the same**, prefer **r2v + native character** on *every* scene (each clip independently anchored to the entity → best identity, accepts cuts). Use **chain** when smooth motion handoff matters more than identity, accepting drift. They can be mixed per-scene but never combined within one clip.
+
+The strongest practical journey today = r2v+entity on each scene; chaining is complementary, not a substitute, for the *consistency* goal specifically.
+
+---
+
+## 3. Project consolidation — verified, and it's load-bearing
+
+`manifest.project` (single value) is passed to `_create_character(project_id=…)` (`:309`) **and** `_generate_scene(project_id=…)` (`:356`); `_enter_editor` deep-links via `routes.project_editor_url(locale, project_id)` → `page.goto` (`ui_automation.py:815-818`); characters are created at the project's character-editor URL (`:2275`). So every character and every scene live in **one** project. ✅
+
+This is precisely why the native-character refactor (§1) works: the entity must be in the **active** project to appear in the composer's "Personagens" picker. The consolidation you added is the enabler — keep it, and add the §1(d) guard so a missing entity fails loudly instead of silently degrading.
+
+---
+
+## 4. Error handling (`generate_resp` / `responses` / 403) — already correct
+
+- `generate_resp: dict[str, Any] = {}` is bound **before** the `try` (`ui_automation_video.py:1421`) → no access-before-assignment on any failure path.
+- `_await_generate_response` raises a clear `TimeoutError` when reCAPTCHA fails *silently* (no response captured, `:1172-1179`).
+- `_parse_generate_response` maps **401→`AuthExpiredError`**, **403→`WafRejectionError`**, other non-200→`WireFormatError` (`:1245-1262`).
+- Both response listeners are removed in `finally` (`:1484-1488`); `generate_handler`/`status_handler` are bound before the `try`.
+- `responses` only appears in comments — no live variable by that name. **No remaining UnboundLocal/TypeError on the 403 path.** Nothing to fix here.
+
+---
+
+## 5. Other observations (non-blocking)
+
+- **Dry-run vs reality mismatch:** the plan prints `refs=[<names>]` (`:260`) but r2v actually consumes image *paths*; after §1 this becomes accurate again (names = entities). Minor.
+- `CharacterState`/`SceneState` are non-frozen dataclasses — intentional (mutated in place); fine.
+- Summary stitch hint uses `flow_operation_id or media_id` (`:371`) — good.
+
+## 6. Testing gap (ties to the DoD: "full e2e covering all scenarios")
+
+- No test drives `_run_movie` with **≥2 scenes** → the cooldown/`asyncio` path and the resume-append path are unexercised. Add: a 2-scene happy path (mock `_generate_scene`) that would have caught §0, and a resume test (one scene pre-completed in state).
+- Add a unit test asserting `_collect_refs` (post-refactor) returns entity ids when present, and a transport test asserting `referenceEntities` lands in the captured payload.
+- Per project DoD memory, a movie feature isn't done until a live e2e covers happy + all error/exit paths on a real project.
+
+---
+
+## Suggested sequencing
+
+1. **Hotfix now:** `import asyncio` + 2-scene orchestrator test. (Unblocks the feature as-is, even with uploaded-image refs.)
+2. **Identity fix:** DTO `reference_entities` + validation relax + transport entity-attach + payload backstop + orchestrator wiring + missing-entity guard.
+3. **Journey mode (opt-in):** wire `movie.toml` → existing `chain.run_chain()`; document the identity-vs-continuity tradeoff.

{gflow_cli-0.13.0 → gflow_cli-0.14.0}/docs/INDEX.md

@@ -33,6 +33,7 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 | **[docs/SECURITY.md](SECURITY.md)** | What secrets are stored where, threat model, hardening | Audit, code review, multi-user machines |
 | **[docs/DATA_LAYER.md](DATA_LAYER.md)** | Local SQLite catalog: goals, schema, recording flow, redaction, `gflow data` CLI, migrations, extension guide | Anything touching `gflow_cli.data`, debugging missing rows, building I2V/repair tooling, auditing what is stored |
 | **[docs/CHARACTER.md](CHARACTER.md)** | Characters feature spec & system design: domain model, endpoint/cost matrix, sequence diagrams, JSON payloads (I/O), CLI surface, reuse via `referenceEntities` (#145) | Working on `gflow character`, reusing a character in generations, or understanding Flow's character wire protocol |
+| **[docs/MOVIE.md](MOVIE.md)** | `gflow movie` — multi-scene character-consistent films: manifest format, run lifecycle (browser stays open through generate→poll→download), entity-attach mechanism (Personagens right-click), resume/handoff, credits | Working on `gflow movie`, debugging scene generation, or understanding the character-entity attach + consistency model |
 | **[tasks/lessons.md](../tasks/lessons.md)** | Running notebook of patterns + reviewer findings, dated and traced to commits | Starting a new phase; debugging "why did the council flag this?" |
 | **[skills/README.md](../skills/README.md)** | Installable agent skill docs (gflow-cli, predict, pr-council-review, scenario) — cross-tool portable Markdown consumed by Claude Code, Cursor, Codex, Gemini CLI, Aider, etc. | Any agent wanting to use gflow-cli correctly |
 | **[scripts/dev/skillopt/README.md](../scripts/dev/skillopt/README.md)** | SkillOpt mock harness — rollout→score loop for measuring and improving skill doc accuracy across multiple LLM providers | Measuring a skill edit's impact; comparing Claude vs GPT-4o vs Gemini on gflow tasks |

gflow_cli-0.14.0/docs/MOVIE.md

@@ -0,0 +1,141 @@
+# Movie — multi-scene, character-consistent films
+
+`gflow movie` turns a single TOML manifest into a sequence of generated video
+clips that share the **same characters** (face + voice) across every scene. It
+is the orchestration layer on top of `gflow character` (entity creation) and
+`gflow video` (R2V generation).
+
+> Status: under active development on the movie feature branch. The wire
+> protocol and CLI surface below are live-verified but may still change before
+> release.
+
+## Quick start
+
+```bash
+# 1. Scaffold a manifest
+gflow movie template movie.toml
+
+# 2. Edit movie.toml (characters + scenes), then run
+gflow movie run movie.toml --profile <chrome-profile>
+```
+
+`movie run` is **generate-only** by default: each scene becomes its own clip in
+the output directory. Pass `--stitch` for an optional ffmpeg hard-concat preview
+(no transitions — not a deliverable).
+
+## Manifest (`movie.toml`)
+
+```toml
+schema_version = 1
+title = "E2E Stickman"
+project = "6ba50219-…"            # reusable Flow project id
+output_dir = "./out"
+
+[[characters]]
+name = "Stickman"
+identity = "entity"               # reuse a Flow CHARACTER entity across scenes
+face_prompt = "Simple round stickman, black ink lines, smiley face"
+voice = "alnilam"                 # voice baked into the entity at creation
+
+[[scenes]]
+id = "summit"                     # stable key — used for resume
+action = "stands on a clifftop at sunset, waves at the camera"
+framing = "wide"
+characters = ["Stickman"]         # which characters appear (drives R2V reuse)
+speaker = "Stickman"
+line = "We finally made it to the top!"
+aspect = "9:16"
+model = "veo-lite"
+duration = 8
+```
+
+On first run, characters with `identity = "entity"` are created once (image
+generation — **free**, no credits) and cached. Each scene then generates a clip
+that **reuses the same Flow CHARACTER entity** so the character drives every
+scene from one identity.
+
+> **Consistency is best-effort, not pixel-exact.** gflow guarantees the *right
+> entity rides the wire* (`consistency_method = entity`); the final on-screen
+> fidelity is Flow's Veo R2V model, which may reinterpret minimalist or
+> hand-drawn references (e.g. a single round body can render as stacked
+> circles). For tighter results, use clearer/richer reference images and a
+> higher-tier model (`veo-quality`/`veo-fast` rather than `veo-lite`) — the same
+> trade-offs you would hit driving Flow's UI by hand.
+
+## Run lifecycle — keep the browser open
+
+`gflow movie run` drives the **real Flow web UI** in a headed Chrome window
+(your `--browser chrome` profile). For **each scene** the same browser window
+is used end-to-end:
+
+1. **Attach** the character entity to the generation (see below).
+2. **Submit** the prompt — this passes reCAPTCHA and **spends 1 video credit**.
+3. **Poll** Flow for completion (the clip renders server-side, ~30–90s).
+4. **Download** the finished mp4 into `output_dir`.
+
+> **Do not close the browser window while a run is in progress.** Steps 3 and 4
+> still use the browser page (polling even brings it to the foreground). If the
+> window is closed before a scene finishes downloading, the in-flight scene
+> **aborts** — you will see a "Target/page/context closed" or `scene_failed`
+> error. **This is expected, not a bug.**
+
+If a run is interrupted (closed window, crash, network drop), it is **safe to
+re-run**: the sibling `<manifest>-state.json` records completed scenes (keyed on
+`scene.id`) and they are skipped, so the command resumes where it left off. A
+versioned handoff manifest (`<manifest>-handoff.json`) is always written at the
+end.
+
+> **Future — fire-and-forget.** Flow's status-poll and download endpoints are
+> non-generative and *could* be driven browser-free over Bearer REST (no
+> reCAPTCHA, no extra credits), letting the browser close right after submit
+> while gflow finishes over the API. That mode is **not implemented yet**; today
+> the browser is required for the full generate → poll → download cycle.
+
+## Character consistency (how the entity rides)
+
+A scene listing `characters = ["Stickman"]` is generated as **R2V**
+(reference-to-video) so the named Flow CHARACTER entity is reused. The entity is
+attached by driving Flow's resource picker:
+
+1. Click **Add Media** in the composer (references sub-mode).
+2. Switch to the **Personagens** (Characters) tab.
+3. **Right-click** the entity tile — addressed by entity id as
+   `data-tile-id="fe_id_<entityId>"` — and choose **"Incluir no comando"** from
+   the context menu. *(A plain left-click navigates into the character editor;
+   the inline "Incluir" button on the **Tudo** tab attaches the character's
+   thumbnail as a plain image, not the entity.)*
+
+This puts `referenceEntities:[{entityId}]` on the
+`video:batchAsyncGenerateVideoReferenceImages` **request**. Flow's **response**
+echoes the accepted entity at:
+
+```
+media[].mediaMetadata.requestData.videoGenerationRequestData
+      .videoGenerationEntityInputs[].entityId
+```
+
+gflow asserts this on every entity scene (`_assert_entities_attached`) and
+**refuses to report success** if the entity did not ride — a text/image-only
+clip is never silently passed off as character-consistent. The recorded
+`consistency_method` in the run state is `entity` when the entity rode (vs
+`text`).
+
+See [CHARACTER.md](CHARACTER.md) for the underlying entity model and
+[CHARACTER_RECON.md](CHARACTER_RECON.md) for the reverse-engineered wire
+protocol.
+
+## `movie run` options
+
+| Flag | Default | Effect |
+|------|---------|--------|
+| `--profile <name>` | default profile | Chrome profile to drive (must be a `chrome`-strategy profile). |
+| `--out-dir <dir>` | manifest `output_dir` | Override the output directory. |
+| `--dry-run` | off | Print the plan + credit estimate; make **no** API calls. |
+| `--fail-fast` / `--continue-on-error` | continue | Stop on the first scene failure, or attempt the rest (default). |
+| `--stitch` | off | After generating, hard-concat all clips into one preview mp4 (ffmpeg, no transitions). |
+
+## Credits
+
+- Character creation (image generation) is **free** — no credits, no reCAPTCHA.
+- Each **scene** is one video generation = **1 credit**, spent at submit (step 2
+  above). A `--dry-run` shows the estimate without spending anything.

gflow_cli-0.14.0/docs/schemas/movie-handoff.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gflow movie handoff manifest",
+  "type": "object",
+  "required": ["schema_version", "generator", "movie", "clips"],
+  "additionalProperties": true,
+  "properties": {
+    "schema_version": { "const": 1 },
+    "generator": {
+      "type": "object",
+      "required": ["name", "version"],
+      "properties": { "name": { "type": "string" }, "version": { "type": "string" } }
+    },
+    "movie": {
+      "type": "object",
+      "required": ["title"],
+      "properties": {
+        "title": { "type": "string" },
+        "output_dir": { "type": "string" },
+        "total_duration_seconds": { "type": "number" }
+      }
+    },
+    "style": { "type": "object" },
+    "characters": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "identity"],
+        "properties": {
+          "name": { "type": "string" },
+          "identity": { "enum": ["text", "entity"] },
+          "voice": { "type": ["string", "null"] },
+          "x_gflow": { "type": "object" }
+        }
+      }
+    },
+    "clips": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "index", "file", "status"],
+        "properties": {
+          "id": { "type": "string" },
+          "index": { "type": "integer", "minimum": 0 },
+          "file": { "type": ["string", "null"], "pattern": "^[^\\\\]*$" },
+          "duration_seconds": { "type": ["number", "null"] },
+          "framing": { "type": ["string", "null"] },
+          "characters": { "type": "array", "items": { "type": "string" } },
+          "consistency_method": { "enum": ["text", "entity", "degraded"] },
+          "dialogue": { "type": "array" },
+          "prompt": { "type": ["string", "null"] },
+          "status": { "enum": ["completed", "failed"] },
+          "x_gflow": { "type": "object" }
+        }
+      }
+    },
+    "stitch": { "type": "object" }
+  }
+}

gflow_cli-0.14.0/docs/superpowers/plans/2026-06-06-movie-p0-asyncio-hotfix.md

@@ -0,0 +1,223 @@
+# Movie P0 — `asyncio` Multi-Scene Hotfix Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Fix the release-blocking `NameError` that aborts every multi-scene `gflow movie run` after the first scene, and add the regression tests that should have caught it.
+
+**Architecture:** `gflow_cli/cli_movie.py` calls `await asyncio.sleep(5)` as a reCAPTCHA cooldown between scenes, but never imports `asyncio`. The call sits *outside* the per-scene `try/except`, so on the 2nd scene it raises `NameError` and aborts the whole run (and on resume, the first already-completed scene makes the first *new* scene hit it → zero forward progress). Fix = add the import and relocate the cooldown inside the `try` so any failure there is handled per-scene. The existing async-orchestrator tests only ever use single-scene manifests, so the bug was invisible — we add a 2-scene run test and a resume test.
+
+**Tech Stack:** Python 3.13, pytest (`pytest-asyncio`), `unittest.mock`. Run tests with the worktree venv: `.venv/Scripts/python.exe -m pytest` (do **not** use `uv run pytest` on Windows — it's broken here).
+
+---
+
+### Task 1: Add the failing 2-scene regression test, then fix the import
+
+**Files:**
+- Test: `tests/cli/test_cli_movie.py` (add a method to `class TestRunMovieOrchestrator`, near line 400)
+- Modify: `src/gflow_cli/cli_movie.py` (imports ~line 19; cooldown block ~lines 341-346)
+
+- [ ] **Step 1: Write the failing test**
+
+Add this method inside `class TestRunMovieOrchestrator` in `tests/cli/test_cli_movie.py` (it reuses the file's existing helpers `_mock_client_cm`, `_make_video_result` and imports `MovieManifest`, `SceneDef`, `MovieState`, `AsyncMock`, `MagicMock`, `patch`, already imported at the top of that test module):
+
+```python
+    async def test_two_scene_run_does_not_crash_on_cooldown(self, tmp_path: Path) -> None:
+        """Regression: the reCAPTCHA cooldown on scene 2+ must not NameError.
+
+        Before the fix, `cli_movie` calls `asyncio.sleep` without importing
+        asyncio, so the 2nd scene aborts the whole run. `patch("asyncio.sleep")`
+        makes the (post-fix) cooldown instant; pre-fix it raises NameError.
+        """
+        from gflow_cli.cli_movie import _run_movie
+
+        manifest = MovieManifest(
+            title="T",
+            project="p",
+            characters=(),
+            scenes=(
+                SceneDef(title="S1", type="t2v", prompt="x"),
+                SceneDef(title="S2", type="t2v", prompt="y"),
+            ),
+        )
+        state = MovieState(title="T", project="p")
+        state_path = tmp_path / "state.json"
+
+        with (
+            patch("gflow_cli.cli_movie.get_settings"),
+            patch("gflow_cli.cli_movie.OperationRecorder") as mock_recorder_cls,
+            patch("gflow_cli.cli_movie.FlowApiClient", return_value=_mock_client_cm()),
+            patch(
+                "gflow_cli.cli_movie._generate_scene",
+                new=AsyncMock(return_value=_make_video_result()),
+            ),
+            patch("asyncio.sleep", new=AsyncMock()),
+        ):
+            mock_recorder_cls.open.return_value = MagicMock()
+            await _run_movie(
+                manifest=manifest,
+                state=state,
+                state_path=state_path,
+                profile_name="default",
+                profile_dir=tmp_path / "profile",
+                out_dir=tmp_path / "out",
+                continue_on_error=True,
+            )
+
+        assert state.scenes["S1"].status == "completed"
+        assert state.scenes["S2"].status == "completed"
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `.venv/Scripts/python.exe -m pytest tests/cli/test_cli_movie.py::TestRunMovieOrchestrator::test_two_scene_run_does_not_crash_on_cooldown -v`
+Expected: **FAIL** — `NameError: name 'asyncio' is not defined` (raised from the cooldown in `_run_movie`, so scene `S2` never completes).
+
+- [ ] **Step 3: Add the `import asyncio` and relocate the cooldown into the try**
+
+In `src/gflow_cli/cli_movie.py`, add the import (alphabetical, before `import sys`). Change:
+
+```python
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+```
+
+to:
+
+```python
+from __future__ import annotations
+
+import asyncio
+import sys
+from pathlib import Path
+```
+
+Then relocate the cooldown so a failure there is handled per-scene rather than aborting the run. Change this block (currently ~lines 340-346):
+
+```python
+                refs = _collect_refs(scene_def, state)
+
+                # reCAPTCHA cooldown
+                if completed_scene_ids:
+                    await asyncio.sleep(5)
+
+                try:
+
+                    video_result = await _generate_scene(
+```
+
+to:
+
+```python
+                refs = _collect_refs(scene_def, state)
+
+                try:
+                    # reCAPTCHA cooldown between scenes — inside the try so any
+                    # failure here is handled per-scene and never aborts the run.
+                    if completed_scene_ids:
+                        await asyncio.sleep(5)
+
+                    video_result = await _generate_scene(
+```
+
+(Leave the rest of the `try` body and the `except`/`state.save` unchanged.)
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run: `.venv/Scripts/python.exe -m pytest tests/cli/test_cli_movie.py::TestRunMovieOrchestrator::test_two_scene_run_does_not_crash_on_cooldown -v`
+Expected: **PASS** (both `S1` and `S2` complete; `asyncio.sleep` is patched so no real delay).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/gflow_cli/cli_movie.py tests/cli/test_cli_movie.py
+git commit -m "fix(movie): import asyncio so multi-scene runs don't crash after scene 1"
+```
+
+---
+
+### Task 2: Add the resume regression test
+
+**Files:**
+- Test: `tests/cli/test_cli_movie.py` (add a method to `class TestRunMovieOrchestrator`)
+
+This proves the *resume* path makes forward progress: with scene 1 already completed in state, scene 2 must still generate (pre-fix, the completed-scene append made the first new scene hit the un-imported cooldown and crash → zero progress).
+
+- [ ] **Step 1: Write the test**
+
+Add inside `class TestRunMovieOrchestrator`:
+
+```python
+    async def test_resume_generates_first_new_scene(self, tmp_path: Path) -> None:
+        """Regression: on resume, the first NEW scene must generate (not crash
+        on the cooldown triggered by the resumed completed scene)."""
+        from gflow_cli.cli_movie import _run_movie
+
+        manifest = MovieManifest(
+            title="T",
+            project="p",
+            characters=(),
+            scenes=(
+                SceneDef(title="S1", type="t2v", prompt="x"),
+                SceneDef(title="S2", type="t2v", prompt="y"),
+            ),
+        )
+        state = MovieState(title="T", project="p")
+        state.scenes["S1"] = SceneState(
+            media_id="m",
+            flow_operation_id="op-old",
+            local_path="/out/v.mp4",
+            status="completed",
+        )
+        state_path = tmp_path / "state.json"
+        gen = AsyncMock(return_value=_make_video_result())
+
+        with (
+            patch("gflow_cli.cli_movie.get_settings"),
+            patch("gflow_cli.cli_movie.OperationRecorder") as mock_recorder_cls,
+            patch("gflow_cli.cli_movie.FlowApiClient", return_value=_mock_client_cm()),
+            patch("gflow_cli.cli_movie._generate_scene", new=gen),
+            patch("asyncio.sleep", new=AsyncMock()),
+        ):
+            mock_recorder_cls.open.return_value = MagicMock()
+            await _run_movie(
+                manifest=manifest,
+                state=state,
+                state_path=state_path,
+                profile_name="default",
+                profile_dir=tmp_path / "profile",
+                out_dir=tmp_path / "out",
+                continue_on_error=True,
+            )
+
+        gen.assert_awaited_once()  # S1 skipped, S2 generated
+        assert state.scenes["S2"].status == "completed"
+```
+
+- [ ] **Step 2: Run the test to verify it passes**
+
+Run: `.venv/Scripts/python.exe -m pytest tests/cli/test_cli_movie.py::TestRunMovieOrchestrator::test_resume_generates_first_new_scene -v`
+Expected: **PASS** (with Task 1's fix in place). `_generate_scene` is awaited exactly once (for `S2`).
+
+- [ ] **Step 3: Run the full movie test module to confirm no regressions**
+
+Run: `.venv/Scripts/python.exe -m pytest tests/cli/test_cli_movie.py -q`
+Expected: all tests **PASS**.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add tests/cli/test_cli_movie.py
+git commit -m "test(movie): cover multi-scene run + resume (guards asyncio cooldown)"
+```
+
+---
+
+## Self-Review
+
+**Spec coverage:** Implements spec §11 P0 (`import asyncio`, relocate cooldown) and §14 (multi-scene run test that "catches P0" + resume test). No other spec section is in P0 scope.
+
+**Placeholder scan:** None — every step has exact paths, full test code, exact commands, and expected output.
+
+**Type consistency:** Reuses the test module's existing helpers verbatim (`_mock_client_cm`, `_make_video_result`) and `_run_movie`'s real keyword signature (`manifest`, `state`, `state_path`, `profile_name`, `profile_dir`, `out_dir`, `continue_on_error`), matching the surrounding tests (e.g. `test_happy_path_no_characters`). `SceneState` fields (`media_id`, `flow_operation_id`, `local_path`, `status`) match `movie_manifest.py`.