gflow-cli 0.29.0__tar.gz → 0.31.0__tar.gz

{gflow_cli-0.29.0 → gflow_cli-0.31.0}/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.31.0] — 2026-07-10
+
+### Fixed
+
+- **Agentic image generation no longer risks attributing a pre-existing project asset to the current request.** `await_images` settled its new-media baseline with a single DOM scrape, which could miss a lazily-rendered pre-existing tile and let `_build_generated_images` slice an arbitrary UUID out of an unordered set as "the" generated image — the 2026-07-10 production incident: an old project logo was silently downloaded and reported as a fresh generation. The baseline is now the **union of two `_scrape_img_srcs` passes** one poll interval apart, absorbing lazy-render stragglers before they're mistaken for new media, and if more new UUIDs still appear than were requested, `await_images` now fails fast with the new `MediaAttributionError` (**exit code 26**, RFC 9457 type `media-attribution`) naming every candidate UUID and the expected count instead of guessing (#281).
+- **A pre-download attribution guard now runs ahead of every image download, with `DataIntegrityError` escalated instead of warned.** Even a driver that never hits the agentic ambiguity check above can still hand back a `flow_media_id` already recorded for the profile. `OperationRecorder.verify_media_attribution()` (called from `cli_image.py`, `image_batch.py`'s manifest batch path, and `FlowWorker.process_task`) checks `is_media_recorded()` before `_download_images` and raises `MediaAttributionError` rather than downloading — it also now rejects an intra-batch duplicate `flow_media_id` (the classic transport can return the same media twice in one submission) with no DB lookup needed. Separately, a `DataIntegrityError` from the recorder's `UNIQUE(profile_name, flow_media_id)` constraint — previously caught by the generic `DataStoreError` path and reported as a warn-only "Generated media was saved, but local history was not updated." — now escalates to the same `MediaAttributionError` when (and only when) the failing write is that exact constraint (`route == "data.upsert_asset"`); any other `DataIntegrityError` (e.g. an unrelated `insert_operation`/`link_operation_asset` failure) falls through to the ordinary warn-and-continue path instead of being mislabeled as a media collision. The escalation message now names the full candidate set of `flow_media_id`s / saved paths ("one of ...") rather than always fingering the first image, since the colliding index can't be recovered from sqlite's bare constraint violation (#281).
+- **The pre-download attribution guard and the collision-escalation logic are each now a single shared implementation instead of three near-identical copies.** Both originally shipped duplicated across `cli_image.py`, `image_batch.py`, and `worker/daemon.py` (each call site already held a recorder instance), which tripped SonarCloud's duplicated-lines gate. The guard is consolidated onto `OperationRecorder.verify_media_attribution()`; the escalation is consolidated onto the new `gflow_cli.data.recorder.escalate_asset_collision()` — both with no behavior change beyond the route-scoping and intra-batch-duplicate fixes above (#281, #282, #283).
+- **`gflow image batch` (the manifest path) now honors `--continue-on-error` for a media-attribution collision.** A collision on one row — from either the pre-download guard or the post-download collision escalation — used to propagate out of the whole batch run regardless of `--continue-on-error`, discarding every other row's already-completed outcome. With `--continue-on-error` the colliding row is now marked as a normal "fail" outcome (nothing was downloaded/recorded for that row) and the batch continues; without it, the collision still aborts the run as before (#281, #282).
+- **`--ref <uuid>` picker selection now resolves every ref, not just the first.** `_select_existing_asset` gave up as soon as a tile wasn't in the initial viewport or surfaced by the display-name search, so any `--ref` after the first raised `TransportTimeoutError` once the virtualised (react-virtuoso) media grid hadn't rendered it yet. It now falls back to scrolling and re-checking between scrolls, mirroring the entity picker's `_find_picker_entity_tile` strategy, and `_attach_image_uuid_refs` clears the picker search input at the start of every ref iteration so a search typed while resolving one ref can't shadow the next ref's tile lookup. `_select_existing_asset` itself now also clears a failed display-name search before falling back to scrolling, so it doesn't scroll a grid still filtered by the failed term (#282).
+
+## [0.30.0] — 2026-07-09
+
+### Added
+
+- **MCP `gflow_generate_video` model/duration/count parameters (CLI↔MCP parity):** agents can now select the Veo model (`veo_lite`/`veo_fast`/`veo_quality`/`omni_flash`, aliases accepted), clip duration, and batch count through MCP, matching the CLI `gflow video` flags. An unknown model is rejected up front with a 400 instead of failing deep in the worker; an omitted model still lets the transport apply its i2v veo-lite default (issue #125). Co-authored-by C1ph3r404 (from the closed PR #258). Note: the pre-existing transport-level i2v veo-lite default already protected the MCP path, so this is parity + agent control, not a new credit guard.
+
+### Fixed
+
+- **Character-create recorder no longer crashes on a duplicated `flow_media_id`.** Under the agentic cohort the classic character-editor slot-add control is absent, so the body prompt lands in the still-active face slot and both slots report the same `flow_media_id`; `_record_character_local_files` minted a fresh asset `id` per slot and the second slot violated `UNIQUE(profile_name, flow_media_id)` → `DataIntegrityError`. The recorder now reuses the existing asset id (mirroring `record_completed_video`), making character local-file recording idempotent on the business key. Regression test in `tests/data/test_recorder_character.py`.
+- **`prefer_classic` no longer logs a misleading `WARNING` on the agentic cohort.** The server-gated agentic (`tune`) cohort cannot be exited client-side, and `prefer_classic` is best-effort by contract, so `get_ui_driver` now logs that expected fall-through at `INFO` (`ui_driver.prefer_classic.cohort_natively_agentic`) and reserves `WARNING` for genuinely unexpected exit failures.
+
 ## [0.29.0] — 2026-07-09
 
 ### Added
@@ -1887,7 +1908,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.29.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.30.0...HEAD
+[0.30.0]: https://github.com/ffroliva/gflow-cli/compare/v0.29.0...v0.30.0
 [0.29.0]: https://github.com/ffroliva/gflow-cli/compare/v0.28.0...v0.29.0
 [0.28.0]: https://github.com/ffroliva/gflow-cli/compare/v0.27.1...v0.28.0
 [0.27.1]: https://github.com/ffroliva/gflow-cli/compare/v0.27.0...v0.27.1

gflow_cli-0.31.0/GEMINI.md

@@ -0,0 +1,37 @@
+# GEMINI.md
+
+> Project memory hub for **Gemini CLI**. The universal coding-agent rules for any tool (Cursor, Codex, Aider, Gemini CLI, etc.) live in [AGENTS.md](AGENTS.md) — this file carries Gemini-specific session protocol only.
+
+## What this project is
+
+`gflow-cli` is an unofficial Python CLI that drives [Google Flow](https://labs.google/fx/tools/flow) (Veo image-to-video, Imagen text-to-image) from the terminal by reverse-engineering Flow's private REST API. See [README.md](README.md) for the user-facing overview.
+
+## On every session start
+
+1. Read **[AGENTS.md](AGENTS.md)** — universal rules every agent must follow.
+2. Read **[docs/INDEX.md](docs/INDEX.md)** — routing layer for all project docs and commands.
+3. Pull deeper context on demand (type as plain text in the `agy` TUI prompt):
+   - Current task / where we left off → `gflow:status`
+   - Starting a new feature → `gflow:predict` → `gflow:scenario` → `gflow:plan <feature>`
+   - Touching auth or reCAPTCHA → `gflow:known-issues`
+   - Cutting a release → `gflow:release`
+   - Before any commit → `gflow:check`
+
+## Gemini-specific
+
+- Use specialized skills when relevant (e.g., `find-docs` for library research, `pr-council-review` for PR audits).
+- Maintain memory via the `mcp-mempalace` tool if available.
+- Prioritize **turn efficiency** and **high-signal output**.
+
+## Active phase
+
+- **v0.29.0 shipped (2026-07-09):** persistent `gflow instructions` CRUD + movie-manifest instructions brief-sync + six `gflow_instructions_*` MCP tools, with a CI-enforced MCP↔CLI parity contract (`tests/mcp/test_cli_parity.py`) and the agentic-indicator selectors consolidated onto `drivers/factory.py`. Released to PyPI; issue #192 closed.
+- **PR #258 (Camoufox stealth engine, external contribution) — taken over and CLOSED-OUT (2026-07-09).** A 5-persona `/gflow:predict` rejected a rebase in favour of a decomposed, evidence-gated series: Phase 1 landed the MCP video param parity (#273, contributor-credited); a WAF-evidence harness (#274/#275) measured a **0.0% WAF 403 rate over 20 live generations**, so per ADR-13 the Camoufox engine was **NOT built** (#276). The i2i "UUID-ref bug" was investigated and found not-a-bug (#277, stale comment fixed). Contributor thanked + credited on the closed PR. Evidence: `docs/superpowers/spikes/2026-07-09-camoufox-waf-403.md`.
+- **Decoupled Daemon/Worker Plan:** The MCP→FlowWorker wiring shipped in v0.23.0 (PR #228). The remaining headless SSE Daemon + Tauri/React editor blueprint is scheduled in [gflow-studio-scaffold/PLAN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-24-gflow-studio-scaffold/PLAN.md) and [rest-api-layer/PLAN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-24-rest-api-layer/PLAN.md).
+- **Core Lesson (Retrospective):** 
+  - **Verify before adopting — measure, don't assume.** The PR #258 takeover's value was checking every claim against the real code and real data instead of adopting on assertion: a stealth engine we didn't build (0% WAF baseline), a "credit guard" already enforced one layer down, a `display_name` already shipped in v0.26.0, an i2i "bug" that wasn't one, and a concurrency bug that never merged. Five claims, five dismissals — the cheapest correct outcome came from investigation, not implementation.
+  - **ADR gates pay for themselves.** ADR-13 ("confirm the current stealth fix insufficient before implementing an alternative") turned a "build Camoufox" epic into a one-afternoon 20-generation spike that said "don't." Encode the gate as a runnable measurement (`scripts/spike_waf_camoufox.py`), not a debate.
+  - **Decompose contested external PRs; never rebase a branch that's 60+ commits behind.** Cherry-pick/re-express the genuinely-valuable pieces onto fresh branches with `Co-authored-by` credit, evidence-gate the risky parts, and split by concern — one PR per slice.
+  - Kept `gflow-cli` strictly headless (Uvicorn + FastMCP over localhost HTTP/SSE); browser-context locks bypassed by serializing task writes in the SQLite queue with WAL-mode parallel reads. Relational instruction cards must be phrased conversationally (imperative prompts bypass the brief); multi-scene movie sync is read-modify-write to preserve server-assigned card IDs.
+
+See [PLAN.md](PLAN.md) or type `gflow:status` for the current task. Type `gflow:plan <feature>` to create a new feature plan.

{gflow_cli-0.29.0 → gflow_cli-0.31.0}/KNOWN_ISSUES.md

@@ -663,6 +663,108 @@ key — surfaces as a `RuntimeError` that `auth/cookies.py` normalizes to
 
 ## Resolved
 
+### Agentic image generation could silently attribute a pre-existing project asset as the "generated" image
+
+- **Status:** Resolved · **Severity:** Was-High (wrong file downloaded and reported as success, silently) · **Was-affecting:** the agentic driver through v0.30.0 (and, for the pre-download guard below, every transport) · **Fixed in:** unreleased (0.31.0) · **Tracked:** [#281](https://github.com/ffroliva/gflow-cli/issues/281); related picker fix [#282](https://github.com/ffroliva/gflow-cli/issues/282)
+
+Discovered 2026-07-10 in a live production run: `gflow image t2i` under the
+agentic driver downloaded an **old project logo** and reported it as a freshly
+generated "portrait" — no error, just the pre-existing warn-only line
+`"Generated media was saved, but local history was not updated."` — and 11
+downstream `i2i` scenes were then anchored to the wrong file.
+
+**Root cause — two defects in `await_images` (agentic driver):**
+1. The new-media baseline was a **single** DOM scrape (`_scrape_img_srcs`); a
+   pre-existing tile that rendered lazily (after generation had already
+   started) was missed by that scrape and then counted as "new" once it
+   appeared.
+2. `_build_generated_images` sliced an **unordered** UUID set down to
+   `expected_count` — an arbitrary pick when more "new" UUIDs were present
+   than were actually requested, with no signal for which UUID(s) belonged to
+   this generation.
+
+**A third, independent gap** existed downstream of the driver: even a transport
+that never hits the agentic DOM-scrape path above could still hand back a
+`flow_media_id` already present in local history for the profile. That case
+was caught by the generic `DataStoreError` path, which only warned and
+continued — a silently duplicated/misattributed history row, not a hard
+failure.
+
+**Fix — three defense layers, all raising the new `MediaAttributionError`
+(exit code 26, RFC 9457 type `media-attribution`) instead of a silent or
+warn-only outcome:**
+1. **Baseline settle.** The baseline is now the **union of two
+   `_scrape_img_srcs` passes** one poll interval apart, absorbing lazy-render
+   stragglers before they can be mistaken for new media.
+2. **Ambiguity fail-fast.** If more new UUIDs still appear than were
+   requested, `await_images` raises `MediaAttributionError` naming every
+   candidate UUID and the expected count, rather than guessing via
+   `_build_generated_images`'s old arbitrary slice.
+3. **Pre-download attribution guard + collision escalation.**
+   `OperationRecorder.verify_media_attribution()` (called from `cli_image.py`,
+   `image_batch.py`'s manifest batch path, and the worker daemon's
+   `FlowWorker.process_task`; consolidated onto the recorder in #283 after
+   shipping as three near-identical module-level copies) checks
+   `is_media_recorded()` and raises before any download if the driver
+   returned a `flow_media_id` already recorded for the profile.
+   Separately, a `DataIntegrityError` from the recorder's
+   `UNIQUE(profile_name, flow_media_id)` constraint now escalates to
+   `MediaAttributionError` (naming the suspect file) instead of being caught
+   by the generic `DataStoreError` warn-only path.
+
+Precedent for this class of fix: the `--model` silent no-op entry below (same
+section) — an error the user sees beats a wrong artifact reported as success.
+
+**Related, but distinct.** [#282](https://github.com/ffroliva/gflow-cli/issues/282)
+fixed a separate defect in the same media-picker surface (`--ref <uuid>`
+selection failing on any ref after the first once the virtualised
+(react-virtuoso) grid needed to scroll to render it) — a picker-navigation
+bug, not a data-integrity one. [#174](https://github.com/ffroliva/gflow-cli/issues/174)
+(open, in the "Open" section above) is a Flow-side full-page media-library
+UI rollout that breaks entity attach on affected accounts — a different
+code path, but the same general theme that the media-picker surface needs
+ongoing hardening.
+
+**Residual risk (post-fix, not fully closed).** The two-pass baseline settle
+narrows the window, it doesn't remove it: the agentic poll loop still stops
+scraping the moment the new-UUID count on a single scrape equals the
+requested count. A pre-existing tile that lazy-renders *after* the 0.5s
+baseline settle but *before* the real generation actually completes
+(generations take 30–60s) lands inside that window at exactly the expected
+count — the ambiguity fail-fast in layer 2 only triggers on an *excess* of
+new UUIDs, so it never sees this case. Layer 3's pre-download guard and
+collision escalation then only catch it if the misattributed asset happens
+to already be in **local** history for the profile — an asset created in the
+Flow web UI, generated on another machine, or recorded under a different
+profile DB has no local history row to collide with, so it can still slip
+through all three layers: wrong file on disk, exit 0. Mitigations until this
+is closed: run generations in a dedicated, low-asset project (fewer
+pre-existing tiles means a smaller lazy-render population to collide with),
+and visually verify anchor/canonical images before referencing them
+downstream in `i2i`. Follow-up hardening (a break condition stable across
+two consecutive scrapes, not one) is tracked upstream against this issue.
+
+**Known gap: the shell multi-prompt path records no history at all.**
+`gflow run --config <file>` and `gflow image t2i` with multiple prompts
+(positional, `--prompts-file`, or `--stdin`) both go through
+`image_batch.run_image_batch` / `run_one_image_prompt`, which never opens an
+`OperationRecorder` or calls `record_generated_images` — no local history row
+is written for these runs at all. Layer 1 (the agentic driver's two-pass
+baseline settle + ambiguity fail-fast in `await_images`) still applies since
+it lives in the transport, independent of recording. Layers 2 and 3
+(`verify_media_attribution`'s pre-download guard and the post-download
+collision escalation) both depend on local history via
+`OperationRecorder.is_media_recorded()` / `record_generated_images()`, so
+neither guard exists on this path — this is a pre-existing gap, not a
+regression from this fix. `gflow image batch` (the manifest path, via
+`run_manifest_image_batch`) already threads a recorder through and is covered
+by all three layers. Follow-up tracked in #283.
+
+**Workaround (pre-fix):** none — on an affected version, manually verify the
+downloaded file matches the prompt before trusting a `t2i`/`i2i` result.
+
+---
+
 ### Profile named `default` is opaque — no Google account identity
 
 - **Status:** Resolved · **Severity:** Was-Low (UX confusion, no data loss) · **Was-affecting:** all versions through v0.9.x · **Fixed in:** v0.10.0 via PR #110 (2026-05-28) · **Tracked:** issue #92

{gflow_cli-0.29.0 → gflow_cli-0.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.29.0
+Version: 0.31.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.29.0 → gflow_cli-0.31.0}/PLAN.md

@@ -653,6 +653,8 @@ Records image, batch, T2V, I2V, and R2V provenance in a local SQLite catalog. Re
 
 **Status:** NOT implemented. Parked until the stealth-flag fix (`--disable-blink-features=AutomationControlled` + init script) is confirmed insufficient, or until a contributor picks it up.
 
+**2026-07-09 verification — the current stealth fix is CONFIRMED SUFFICIENT (so this stays parked).** A 20-generation baseline on a live authed profile through the default stealth stack produced a **0.0% WAF 403 rate** (19/20 success; the one miss was a UI-scrape timeout, not a WAF block). This met ADR-13's "must verify before implementing" gate and closed the [Camoufox adoption roadmap](superpowers/plans/2026-07-09-camoufox-adoption/PLAN.md) at Phase 2 — the Camoufox engine was NOT built. Evidence: [superpowers/spikes/2026-07-09-camoufox-waf-403.md](superpowers/spikes/2026-07-09-camoufox-waf-403.md). Re-run `scripts/spike_waf_camoufox.py` if a repeatable WAF-403 is later observed; a materially non-zero rate would reopen CDP-Attach / Camoufox.
+
 ---
 
 ### Phase 8 — Pluggable storage backend — BACKLOG
@@ -699,7 +701,7 @@ Today the CLI writes media to `$GFLOW_CLI_OUTPUT_DIR` on the local filesystem. P
 | 10 | Both `gflow` and `flow` binary names installed | `flow` is friendlier; `gflow` avoids conflicts with Facebook Flow / MS Power Automate |
 | 11 | LF-only line endings via `.gitattributes` | Single repo source of truth; cross-platform contributors don't think about it |
 | 12 | `Provider` indirection (legacy `providers/`) removed | Superseded by `api.FlowApiClient`. Re-introduce when we add `OfficialVeoProvider` (planned v0.5+) |
-| 13 | CDP attach transport deferred | Must first confirm whether CDP-attached Chrome still sets `navigator.webdriver=true` (which would negate any reCAPTCHA advantage over the current stealth fix). See CDP Attach backlog entry. |
+| 13 | CDP attach / stealth-engine alternatives deferred; **current stealth fix confirmed sufficient 2026-07-09** | Gate met: a 20-gen live baseline through the default stealth stack showed a **0.0% WAF 403 rate**, so the "confirm insufficient before implementing" bar is unmet — CDP-Attach and the Camoufox engine stay parked (Camoufox roadmap closed at Phase 2). Evidence: [superpowers/spikes/2026-07-09-camoufox-waf-403.md](superpowers/spikes/2026-07-09-camoufox-waf-403.md). |
 | 14 | HTTP status path (`get_video_status`) retired alongside `generate_video` | It is the same 401-dead path and would collide with the new `api/video.py:VideoStatus` value object — retiring both together keeps the domain clean. |
 
 ---

{gflow_cli-0.29.0 → gflow_cli-0.31.0}/docs/INDEX.md

@@ -122,7 +122,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"A gflow command hangs / fails — where do I start?"** → [DEBUGGING § Quick reference](DEBUGGING.md#quick-reference)
 **"Flow's UI broke a selector — how do I diagnose it?"** → [DEBUGGING § Inspecting Flow's live UI](DEBUGGING.md#inspecting-flows-live-ui)
 **"What does each `ui_automation.*` log event mean?"** → [DEBUGGING § Listener & HTTP-layer debugging](DEBUGGING.md#listener--http-layer-debugging)
-**"What was actually live-verified for the latest release?"** → latest: [LIVE_VERIFICATION_v0.29.0](LIVE_VERIFICATION_v0.29.0.md) (**persistent `gflow instructions` CRUD proven live e2e GREEN, credit-free** — 11-command sequence on a fresh project: add incl. `--ref <image-UUID>` attach, list/enable/disable, master toggle both ways, TOML `apply` destructive full-sync with `enabled=false` honored, `rm` with server card-id preserved across mutations; movie brief-sync code-path-verified via the same primitives, deferred-with-reason on credits; MCP `gflow_instructions_*` tools are thin adapters over the live-verified primitives). Prior: [v0.28.0](LIVE_VERIFICATION_v0.28.0.md) (**agent instructions `-i` now steer agentic generation — crayon e2e GREEN**: a style-neutral prompt + an enabled "crayon" card produced an unmistakable crayon drawing through the real transport; root causes were conversational phrasing + the `project_brief.enabled` master switch). Prior: [v0.27.1](LIVE_VERIFICATION_v0.27.1.md) (**v0.27.0 release follow-up fixes and documentation sync**). Prior: [v0.27.0](LIVE_VERIFICATION_v0.27.0.md) (**`[style]` block with named variants + prompt-aware resume — credit-free CLI verification**: real `movie run --dry-run` 3-way ledger proving resolved-style display, `skip (done)` on matching `style_hash`, and `re-run (style changed)` after a style edit; composition is local, wire path untouched, so no Veo credits spent — first credited styled run will confirm visually). Prior: [v0.26.0](LIVE_VERIFICATION_v0.26.0.md) (**image i2i by generated-image UUID proven live e2e GREEN** — the existing asset is *selected in place* by its media UUID, no duplicate upload, producing an i2i output that references it; plus generated-image `display_name` capture, credited @C1ph3r404). Prior: [v0.25.0](LIVE_VERIFICATION_v0.25.0.md) (**#237 remote-UUID i2v proven live e2e GREEN** — a real 8s 720×1280 interpolation from a generated image's UUID, after the picker-search attach was reworked to local upload; #240 home-`.env` matrix live; plus two silent-failure guards root-caused live: video-as-image download rejection and rejected-upload fail-loud). Prior: [v0.24.0](LIVE_VERIFICATION_v0.24.0.md) (--project parity across CLI + MCP — automated coverage; live gen auth-gated). Prior: [v0.23.0](LIVE_VERIFICATION_v0.23.0.md) (MCP generation wiring proven live end-to-end — tool→worker→real Flow REST→structured-error translation; final image-write blocked by an expired session, environmental. #222 macOS fix reporter-verified e2e on Apple Silicon). Prior: [v0.22.0](LIVE_VERIFICATION_v0.22.0.md) (Tools framework — automated/CI coverage complete; credit/key-gated live feature run is a pending owner gate, see the doc) · [v0.21.0](LIVE_VERIFICATION_v0.21.0.md) (MCP server over stdio + HTTP/SSE — credit-free protocol handshake; 4 tools / 2 prompts / 3 resources confirmed on stdout) · [v0.20.1](LIVE_VERIFICATION_v0.20.1.md) · [v0.20.0](LIVE_VERIFICATION_v0.20.0.md) · [v0.19.0](LIVE_VERIFICATION_v0.19.0.md) · [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
+**"What was actually live-verified for the latest release?"** → latest: [LIVE_VERIFICATION_v0.31.0](LIVE_VERIFICATION_v0.31.0.md) (**#281 wrong-media defenses live-verified in BOTH directions, credit-free** — correct attribution downloads with real wire metadata [seed, 768×1376]; the incident-class lazy-render ambiguity reproduced live and hard-stopped with `MediaAttributionError` exit 26 naming every candidate UUID, no file written; **#282 two-UUID-ref i2i proven e2e** — both freshly generated portrait UUIDs picker-selected into one scene with both canonical identities visually transferred). Prior: [v0.30.0](LIVE_VERIFICATION_v0.30.0.md) (**agentic-cohort image path + both fixes live-verified credit-free** — native 768×1376 stills, i2i-chain + canonical-ref identity hold; the character-create `DataIntegrityError` and the `prefer_classic` WARNING were observed live then fixed [recorder idempotent + INFO log]; MCP video-param feature deferred-with-reason on Veo credits, per the stills-only goal). Prior: [v0.29.0](LIVE_VERIFICATION_v0.29.0.md) (**persistent `gflow instructions` CRUD proven live e2e GREEN, credit-free** — 11-command sequence on a fresh project: add incl. `--ref <image-UUID>` attach, list/enable/disable, master toggle both ways, TOML `apply` destructive full-sync with `enabled=false` honored, `rm` with server card-id preserved across mutations; movie brief-sync code-path-verified via the same primitives, deferred-with-reason on credits; MCP `gflow_instructions_*` tools are thin adapters over the live-verified primitives). Prior: [v0.28.0](LIVE_VERIFICATION_v0.28.0.md) (**agent instructions `-i` now steer agentic generation — crayon e2e GREEN**: a style-neutral prompt + an enabled "crayon" card produced an unmistakable crayon drawing through the real transport; root causes were conversational phrasing + the `project_brief.enabled` master switch). Prior: [v0.27.1](LIVE_VERIFICATION_v0.27.1.md) (**v0.27.0 release follow-up fixes and documentation sync**). Prior: [v0.27.0](LIVE_VERIFICATION_v0.27.0.md) (**`[style]` block with named variants + prompt-aware resume — credit-free CLI verification**: real `movie run --dry-run` 3-way ledger proving resolved-style display, `skip (done)` on matching `style_hash`, and `re-run (style changed)` after a style edit; composition is local, wire path untouched, so no Veo credits spent — first credited styled run will confirm visually). Prior: [v0.26.0](LIVE_VERIFICATION_v0.26.0.md) (**image i2i by generated-image UUID proven live e2e GREEN** — the existing asset is *selected in place* by its media UUID, no duplicate upload, producing an i2i output that references it; plus generated-image `display_name` capture, credited @C1ph3r404). Prior: [v0.25.0](LIVE_VERIFICATION_v0.25.0.md) (**#237 remote-UUID i2v proven live e2e GREEN** — a real 8s 720×1280 interpolation from a generated image's UUID, after the picker-search attach was reworked to local upload; #240 home-`.env` matrix live; plus two silent-failure guards root-caused live: video-as-image download rejection and rejected-upload fail-loud). Prior: [v0.24.0](LIVE_VERIFICATION_v0.24.0.md) (--project parity across CLI + MCP — automated coverage; live gen auth-gated). Prior: [v0.23.0](LIVE_VERIFICATION_v0.23.0.md) (MCP generation wiring proven live end-to-end — tool→worker→real Flow REST→structured-error translation; final image-write blocked by an expired session, environmental. #222 macOS fix reporter-verified e2e on Apple Silicon). Prior: [v0.22.0](LIVE_VERIFICATION_v0.22.0.md) (Tools framework — automated/CI coverage complete; credit/key-gated live feature run is a pending owner gate, see the doc) · [v0.21.0](LIVE_VERIFICATION_v0.21.0.md) (MCP server over stdio + HTTP/SSE — credit-free protocol handshake; 4 tools / 2 prompts / 3 resources confirmed on stdout) · [v0.20.1](LIVE_VERIFICATION_v0.20.1.md) · [v0.20.0](LIVE_VERIFICATION_v0.20.0.md) · [v0.19.0](LIVE_VERIFICATION_v0.19.0.md) · [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
 **"Where is the reverse-engineered wire protocol for a feature?"** → the `*_RECON.md` design docs: [CHARACTER_RECON](CHARACTER_RECON.md) (Flow character entity protocol), [IMAGE_UPSCALE_RECON](IMAGE_UPSCALE_RECON.md) (`/v1/flow/upsampleImage` wire). Naming convention: one `<FEATURE>_RECON.md` per reverse-engineered surface, kept as the durable spec after the feature ships.
 **"What was live-verified for the data layer (PR #58)?"** → [LIVE_VERIFICATION_data_layer](LIVE_VERIFICATION_data_layer.md) — 1 Imagen + 1 Veo credit on denon82, 6-layer ledger (file + magic + Pillow + DB rows + CLI round-trip + structlog)
 **"What was live-verified for the video-download feature (#29)?"** → [LIVE_VERIFICATION_video_download](LIVE_VERIFICATION_video_download.md)

gflow_cli-0.31.0/docs/LIVE_VERIFICATION_v0.30.0.md

@@ -0,0 +1,53 @@
+# Live Verification — v0.30.0
+
+Release gate evidence for the user-facing changes in v0.30.0, using the 5-layer
+ledger (file count · magic bytes · dimensions/shape · structlog invariants ·
+user-confirmable artifact). Credit-free wherever possible.
+
+## Scope of v0.30.0
+
+- **Added:** MCP `gflow_generate_video` model/duration/count parameters (CLI↔MCP parity, #125).
+- **Fixed:** agentic character-recorder idempotency (DataIntegrityError); `prefer_classic`
+  WARNING→INFO on the server-gated agentic cohort.
+
+---
+
+## 1. Agentic-cohort image path + both Fixed items — LIVE, credit-free ✅
+
+Exercised end-to-end on **2026-07-09** against live Flow (account `denon82`, **agentic**
+cohort) as part of the parable image-consistency spike. Image generation is **credit-free**
+(no Veo credits).
+
+- **File count:** multiple stills downloaded per run (t2i baseline, i2i chain, canonical-ref,
+  multi-ref) — 1 file per generation, all present on disk.
+- **Magic bytes:** JPEG (`ffprobe`-decodable) for every downloaded still.
+- **Dimensions/shape:** **768×1376** (native 9:16) on every generation — the no-crop invariant
+  held under the agentic cohort.
+- **Structlog invariants:** the two Fixed conditions were **observed live** before the fix and
+  are now handled:
+  - `ui_driver.prefer_classic.exit_agent_failed` (WARNING) fired on the agentic (`tune`) cohort —
+    now logged at INFO (`ui_driver.prefer_classic.cohort_natively_agentic`); best-effort by contract.
+  - `character create` on the agentic cohort raised `DataIntegrityError`
+    (`UNIQUE constraint failed: assets.profile_name, assets.flow_media_id`) — now idempotent
+    (recorder reuses the existing asset id). Covered by regression test
+    `tests/data/test_recorder_character.py::test_record_character_completed_duplicate_media_id_is_idempotent`.
+- **User-confirmable artifact:** the side-by-side still gallery + scorecard recorded in the
+  consuming project's spike results (`out/spike/…` + `docs/superpowers/specs/2026-07-09-parable-image-consistency-spike-results.md`).
+
+## 2. MCP `gflow_generate_video` params (#125) — deferred this cycle, unit-test-covered ⚠️
+
+This feature is exercised only by **video generation**, which **costs Veo credits**, and the
+consuming pipeline's explicit goal this cycle is **stills-only (skip video generation)**. Per the
+release gate's escape hatch, it is **not live-verified this cycle** for that reason — it is **not
+silently omitted**. Coverage:
+
+- Unit/contract tests: `tests/mcp/` (including the MCP↔CLI parity contract
+  `tests/mcp/test_cli_parity.py`) — model/duration/count validation and the 400-on-unknown-model
+  path are covered without spending credits.
+- Recommended follow-up: a credit-spending i2v smoke on the next cycle that budgets Veo credits.
+
+---
+
+**Gate summary:** ruff ✓ · format ✓ · pyright 0 errors ✓ · pytest 2145 passed / 7 skipped ✓ ·
+repo-hygiene exit 0 ✓. Agentic image path + both fixes live-verified credit-free; MCP video
+feature deferred with documented reason.

gflow_cli-0.31.0/docs/LIVE_VERIFICATION_v0.31.0.md

@@ -0,0 +1,83 @@
+# Live Verification — v0.31.0
+
+**Date:** 2026-07-10 · **Profile:** `denon82` · **Project:** `f6caf027-ad68-49e3-aac9-ee32f1582bf3`
+(the standing production project — deliberately asset-heavy, i.e. the exact environment of the
+2026-07-10 wrong-media incident this release fixes) · **Build:** develop @ `ecfb5ed`
+(merge of PR #285) run via `uv run gflow` · **Model:** nano-pro · **Aspect:** 9:16 ·
+**Credit cost:** 0 Veo credits (image generation only).
+
+Features under verification (CHANGELOG `[Unreleased]` → 0.31.0):
+1. **#281 layer 1** — agentic ambiguity fail-fast + two-pass baseline settle (`MediaAttributionError`, exit 26)
+2. **#281 layers 2/3** — pre-download attribution guard + route-scoped collision escalation
+3. **#282** — UUID `--ref` picker: virtualised-grid scroll + search-state hygiene
+
+## Run 1 — t2i portrait (musician): correct attribution end-to-end ✅
+
+`gflow image t2i "<musician portrait prompt>" --model nano-pro --aspect 9:16 --project f6caf027-… --out <dir>`
+
+5-layer ledger:
+1. **File count:** exactly 1 file produced: `98a404e7-766d-443c-9385-a16fdb37c799_1.jpg` (886,886 bytes; sha256 `e25e96be454f0215…`).
+2. **Magic bytes:** `ff d8 ff` (JPEG).
+3. **Dimensions:** 768×1376 (native 9:16, no crop).
+4. **Structlog invariants:** real wire metadata surfaced — `seed=648895`, `dimensions=768x1376`
+   (not the agentic scrape sentinels seed=0/0x0); **no** `data.persistence_failed_after_success`
+   warning (the 0.30.0 incident's tell); recorder wrote history cleanly.
+5. **User-confirmable artifact:** image visually inspected — weathered street musician, late 50s,
+   grey beard, black beanie, worn dark jacket, guitar, plain neutral background, front view.
+   Exactly the prompt; NOT a pre-existing project asset. (Under 0.30.0 in this same project, this
+   exact call once returned an old brand logo.)
+
+## Run 2 — t2i portrait (mentor), attempt 1: ambiguity fail-fast fires ✅ (negative-path proof)
+
+Same command shape, mentor prompt. The generation hit the incident-class condition live: the
+asset-heavy project lazy-rendered multiple prior assets after the baseline settle, and the run
+**failed loudly instead of guessing**:
+
+- `MediaAttributionError` raised naming **every** candidate UUID (the list included
+  `6a0b44d5-…` and `64fc2c31-…` — assets generated earlier that day, i.e. genuinely pre-existing
+  media that 0.30.0 would have been free to silently download) plus the remediation text
+  ("Re-run the generation; a dedicated project with fewer pre-existing assets avoids lazy-render
+  ambiguity (issue #281)").
+- **No file was written** for this attempt (output dir unchanged).
+
+This is the strongest possible live evidence for #281: the exact failure environment reproduced,
+and the new behavior is a actionable hard stop, not a wrong artifact with exit 0.
+
+## Run 2 — t2i portrait (mentor), attempt 2: clean ✅
+
+Retry of the same command: 1 file `dacdc6ee-2725-4e5c-b08f-c7143c36d9b6_1.jpg` (591,180 bytes;
+sha256 `e82cc96b3bba60cf…`; JPEG magic `ff d8 ff`; 768×1376; real `seed=744814`; no persistence
+warning). Visually inspected: elegant silver-haired man, 60s, tailored black suit, pocket square,
+neutral background — exactly the prompt.
+
+## Run 3 — i2i with two UUID `--ref`s (#282 picker) ✅
+
+`gflow image i2i "<street scene prompt>" --ref dacdc6ee-… --ref 98a404e7-… --model nano-pro
+--aspect 9:16 --project f6caf027-… --out <dir>` — both refs are the freshly generated portrait
+UUIDs from Runs 1–2, attached by picker selection (no local file passed). Under v0.30.0 this exact
+call failed structurally: only the first UUID was picker-selectable (#282).
+
+Two attempts noted for completeness: attempt 1 failed pre-submission with
+`UiSelectorDriftError probe=mode_switch_trigger` whose debug screenshot was an entirely black
+viewport — a page-that-never-rendered transient, not selector drift; zero generations spent.
+Attempt 2 succeeded.
+
+5-layer ledger:
+1. **File count:** exactly 1 file: `d6f1927a-3eae-4626-bc90-9a6ea7637bab_1.jpg` (670,708 bytes;
+   sha256 `fd828df1a33e37c0…`).
+2. **Magic bytes:** `ff d8 ff` (JPEG).
+3. **Dimensions:** 768×1376 (native 9:16).
+4. **Structlog invariants:** real `seed=244712`; both refs attached (no
+   "could not be selected in the picker" error, no upload fallback); no persistence warning.
+5. **User-confirmable artifact:** visually inspected — BOTH canonical identities transferred:
+   the mentor is the same silver-haired man from Run 2's portrait (same face, suit, and paisley
+   pocket square), the musician the same man from Run 1's (same beanie, beard, work jacket).
+   Monochrome street scene with the iridescent coin accent confined to the guitar case. No
+   pre-existing project asset leaked into the frame.
+
+## Verdict
+
+All three release features live-verified: #281's defense layers in both directions (correct
+attribution succeeds with ground-truth metadata; incident-class ambiguity hard-stops with
+actionable output and no file written), and #282's multi-UUID-ref picker selection end-to-end —
+which simultaneously validates the canonical-reference identity workflow the fixes exist to serve.

{gflow_cli-0.29.0 → gflow_cli-0.31.0}/docs/MCP.md

@@ -46,7 +46,7 @@ The server registers three protocol surfaces:
 
 ### Tools (Executable actions)
 * `gflow_generate_image(prompt, model, aspect, count, seed, reference_images, tools, profile, project, instructions)`: Triggers text-to-image / image-to-image (Imagen / Nano Banana). `instructions` is an optional list of ephemeral agent-instruction strings (agentic cohort only). `reference_images` switches to i2i and accepts **either a local file path or a generated image's Flow media UUID**. A UUID reference is attached by **selecting the already-existing asset in Flow's reference picker — no duplicate copy is uploaded** (locating the tile by the media id in its thumbnail URL, and searching the recorded display name to surface it when needed); gflow falls back to uploading the asset's on-disk local file only when it can't be located in place (e.g. it lives in a different project's picker). `project` generates into an existing Flow project id (mirrors CLI `--project`) — pass the reference's project to keep it selectable in place.
-* `gflow_generate_video(prompt, mode, aspect, initial_frame, end_frame, reference_images, tools, profile, project)`: Triggers vertical or landscape video generation (Veo). `mode` is `t2v`/`i2v`/`r2v`; `i2v` requires `initial_frame`, `r2v` requires `reference_images`; `project` generates into an existing Flow project id (mirrors CLI `--project`). `initial_frame`, `end_frame`, and `reference_images` each accept **either a local file path or the Flow image UUID of a generated asset** — pass a generated image's id straight in to chain image→video, and gflow attaches it for you (the UUID is resolved to the asset's already-on-disk local file and uploaded as the frame; no manual download/re-upload step). A UUID that isn't in your local asset catalog is rejected up front with a clear "Reference Not Found" error; a catalogued asset whose local file is no longer on disk gives a "Reference Not On Disk" error (re-generate it or pass a local path).
+* `gflow_generate_video(prompt, mode, aspect, initial_frame, end_frame, reference_images, model, duration, count, tools, profile, project)`: Triggers vertical or landscape video generation (Veo). `mode` is `t2v`/`i2v`/`r2v`; `model` (`veo_lite`/`veo_fast`/`veo_quality`/`omni_flash`, aliases accepted), `duration` (seconds), and `count` mirror the CLI `gflow video` flags — an omitted `model` lets the transport apply its i2v veo-lite default (issue #125), and `omni_flash` is rejected for i2v-with-frames; `i2v` requires `initial_frame`, `r2v` requires `reference_images`; `project` generates into an existing Flow project id (mirrors CLI `--project`). `initial_frame`, `end_frame`, and `reference_images` each accept **either a local file path or the Flow image UUID of a generated asset** — pass a generated image's id straight in to chain image→video, and gflow attaches it for you (the UUID is resolved to the asset's already-on-disk local file and uploaded as the frame; no manual download/re-upload step). A UUID that isn't in your local asset catalog is rejected up front with a clear "Reference Not Found" error; a catalogued asset whose local file is no longer on disk gives a "Reference Not On Disk" error (re-generate it or pass a local path).
 * `gflow_list_projects(profile, limit)`: Queries SQLite catalog for recent generation folders.
 * `gflow_list_characters(profile)`: Lists Flow Character entities (requires an active browser session).
 * `gflow_list_tools()`: Lists the prompt tools (name/title/description/category) accepted by the generate tools' `tools` param.