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

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

@@ -7,6 +7,16 @@ 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

{gflow_cli-0.30.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.30.0 → gflow_cli-0.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.30.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.30.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.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)
+**"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.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.30.0 → gflow_cli-0.31.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gflow-cli"
-version = "0.30.0"
+version = "0.31.0"
 description = "Unofficial CLI for Google Flow — drive Veo image-to-video generations from the terminal."
 readme = "README.md"
 license = { file = "LICENSE" }

{gflow_cli-0.30.0 → gflow_cli-0.31.0}/src/gflow_cli/__init__.py

@@ -1,3 +1,3 @@
 """gflow-cli — unofficial CLI for Google Flow."""
 
-__version__ = "0.30.0"
+__version__ = "0.31.0"

{gflow_cli-0.30.0 → gflow_cli-0.31.0}/src/gflow_cli/api/transports/drivers/agentic.py

@@ -27,7 +27,12 @@ from typing import TYPE_CHECKING, Any, cast
 
 import structlog
 
-from gflow_cli.errors import ContentPolicyError, FlowAgentUiError, TransportTimeoutError
+from gflow_cli.errors import (
+    ContentPolicyError,
+    FlowAgentUiError,
+    MediaAttributionError,
+    TransportTimeoutError,
+)
 
 if TYPE_CHECKING:
     from pathlib import Path
@@ -462,6 +467,25 @@ class AgenticFlowUiDriver:
         default). On partial completion the error detail includes the
         produced-vs-requested mismatch count.
 
+        **Baseline settle (issue #281):** a single baseline scrape can miss
+        pre-existing project tiles that lazily render a moment later — those
+        would then be miscounted as "new" media and silently attributed to
+        this generation (the 2026-07-10 production incident: a pre-existing
+        logo was downloaded and reported as a fresh portrait). The baseline is
+        therefore the UNION of two scrapes separated by one
+        ``_POLL_INTERVAL_S`` sleep, so a lazy tile rendering between the two
+        passes still counts as pre-existing, not new. This adds one poll
+        interval of wall time up front; the total poll timeout budget
+        (``_AWAIT_TIMEOUT_S``) is unchanged.
+
+        **Ambiguity fail-fast (issue #281):** if more new UUIDs appear than
+        were requested, there is no reliable way to tell which ones belong to
+        this generation. Rather than arbitrarily slice the unordered set (the
+        prior, buggy behaviour), this raises ``MediaAttributionError`` naming
+        every candidate UUID and the expected count. The caller should re-run
+        the generation — ideally in a dedicated project with fewer
+        pre-existing assets, which avoids the ambiguity entirely.
+
         **Content-policy fail-fast (conservative):** scans for explicit text
         (``"content policy"`` / ``"can't create"`` / ``"violat"`` / ``"not able
         to generate"``) and the ``warning``/``error``/``block`` Material Symbol
@@ -469,10 +493,13 @@ class AgenticFlowUiDriver:
         Because no positive block-refusal sample was captured, we prefer a false
         *miss* (timeout) over a false *positive* (spurious ContentPolicyError).
         """
-        # Snapshot existing UUIDs before any new images appear so we can
-        # compute the delta against what was already rendered in the page.
-        baseline_srcs = await _scrape_img_srcs(page)
-        baseline_uuids = _extract_uuids(baseline_srcs)
+        # Baseline settle (issue #281): union two scrapes separated by one
+        # poll interval so a lazily-rendered pre-existing tile is captured as
+        # baseline, not miscounted as "new" media.
+        first_baseline_srcs = await _scrape_img_srcs(page)
+        await asyncio.sleep(_POLL_INTERVAL_S)
+        second_baseline_srcs = await _scrape_img_srcs(page)
+        baseline_uuids = _extract_uuids(first_baseline_srcs) | _extract_uuids(second_baseline_srcs)
 
         deadline = asyncio.get_event_loop().time() + _AWAIT_TIMEOUT_S
         new_uuids: set[str] = set()
@@ -511,6 +538,18 @@ class AgenticFlowUiDriver:
                 )
             raise TransportTimeoutError(detail=detail, route="agentic:await_images")
 
+        if len(new_uuids) > expected_count:
+            candidates = sorted(new_uuids)
+            raise MediaAttributionError(
+                detail=(
+                    f"Cannot attribute the generation among {len(candidates)} candidate "
+                    f"media UUIDs (expected {expected_count}): {candidates}. Re-run the "
+                    "generation; a dedicated project with fewer pre-existing assets "
+                    "avoids lazy-render ambiguity."
+                ),
+                route="agentic:await_images",
+            )
+
         return _build_generated_images(
             uuids=new_uuids,
             expected_count=expected_count,
@@ -544,7 +583,23 @@ def _build_generated_images(
     - ``dimensions``          — ``(0, 0)`` placeholder (naturalWidth/Height
                                  are unreliable for tRPC redirect URLs until
                                  the image has fully decoded; scraping deferred)
+
+    ``uuids`` MUST contain exactly ``expected_count`` entries — the caller
+    (``await_images``) raises ``TransportTimeoutError`` for fewer and
+    ``MediaAttributionError`` for more, so this is only ever reached with an
+    unambiguous, exact match (issue #281: a set is unordered and previously
+    was silently truncated to ``expected_count``, which could attribute the
+    wrong media to the request).
     """
+    if len(uuids) != expected_count:
+        msg = (
+            f"_build_generated_images invariant violated: got {len(uuids)} uuids, "
+            f"expected exactly {expected_count}. Callers must raise "
+            "TransportTimeoutError (too few) or MediaAttributionError (too many) "
+            "before reaching this helper."
+        )
+        raise AssertionError(msg)
+
     # Late import — avoid module-load-time import of dto.
     from gflow_cli.api.dto import GeneratedImage  # noqa: PLC0415
 
@@ -555,9 +610,7 @@ def _build_generated_images(
         aspect_wire = _label_to_wire.get(pending_aspect, aspect_wire)
 
     images: list[GeneratedImage] = []
-    # Take only the first ``expected_count`` UUIDs (set is unordered; the
-    # caller verified len >= expected_count before calling this helper).
-    for uuid in list(uuids)[:expected_count]:
+    for uuid in uuids:
         fife_url = _MEDIA_REDIRECT_BASE.format(uuid=uuid)
         images.append(
             GeneratedImage(

{gflow_cli-0.30.0 → gflow_cli-0.31.0}/src/gflow_cli/api/transports/ui_automation_video.py

@@ -1502,25 +1502,63 @@ class VideoGenerationMixin:
         """In the OPEN reference picker, select the already-existing Flow asset
         identified by ``media_id`` (preferred over uploading a duplicate).
 
-        Locates the tile by the media UUID in its thumbnail URL; if it isn't
-        already visible, searches ``display_name`` to surface it, then re-locates
-        by UUID. Returns ``True`` once attached, ``False`` when the asset can't be
-        located (the caller then falls back to a local upload).
+        Locates the tile by the media UUID in its thumbnail URL. If it isn't
+        already visible, searches ``display_name`` to surface it (when given);
+        if it's STILL not visible, scrolls the virtualised picker grid
+        (react-virtuoso renders off-viewport tiles lazily — #282) and
+        re-checks between scrolls, the same strategy `_find_picker_entity_tile`
+        uses for the entity picker. Returns ``True`` once attached, ``False``
+        when the asset can't be located by any of the above (the caller then
+        falls back to a local upload).
         """
         tile = VideoGenerationMixin._existing_asset_tile(page, media_id)
+        visible = True
         try:
             await tile.wait_for(state="visible", timeout=4000)
         except Exception:  # noqa: BLE001 - not-visible is an expected branch
-            if not display_name:
-                return False
+            visible = False
+
+        attempted_search = False
+        if not visible and display_name:
             search = page.locator(PICKER_SEARCH_INPUT)
             # Human-like typing jitter to dodge WAF heuristics — not security.
             await search.press_sequentially(display_name, delay=random.randint(10, 50))  # NOSONAR
             await page.wait_for_timeout(800)
+            attempted_search = True
             try:
                 await tile.wait_for(state="visible", timeout=6000)
-            except Exception:  # noqa: BLE001 - still not found -> caller uploads
-                return False
+                visible = True
+            except Exception:  # noqa: BLE001 - still not found -> try scrolling
+                pass
+
+        if not visible:
+            # A failed display-name search leaves the grid filtered on that
+            # term — scrolling a still-filtered grid would only shuffle
+            # through the (possibly empty) filtered results rather than the
+            # full asset list, so the search box must be cleared first.
+            # Presence-guarded like `_attach_image_uuid_refs`'s per-ref clear.
+            if attempted_search:
+                clear_search = page.locator(PICKER_SEARCH_INPUT).first
+                if await clear_search.count():
+                    await clear_search.fill("")
+                    await page.wait_for_timeout(400)
+            # Neither the initial viewport nor the display-name search
+            # surfaced the tile — the Tudo grid is virtualised, so an
+            # off-screen (but existing) asset is simply absent from the DOM
+            # until scrolled into range. Scroll and re-check before giving up.
+            for _ in range(PICKER_GRID_SCROLL_ATTEMPTS):
+                if await tile.count():
+                    visible = True
+                    break
+                await VideoGenerationMixin._scroll_picker_grid(page)
+            if visible:
+                try:
+                    await tile.wait_for(state="visible", timeout=4000)
+                except Exception:  # noqa: BLE001 - rendered but never became visible
+                    visible = False
+
+        if not visible:
+            return False
 
         await tile.click()
         await page.wait_for_timeout(400)
@@ -1577,6 +1615,23 @@ class VideoGenerationMixin:
             await add.click()
             await page.wait_for_timeout(800)
 
+            # Fresh per-ref state (#282): a display-name search typed while
+            # locating a previous ref must not leak into this ref's lookup —
+            # every ref after the first was failing because the picker was
+            # still filtered on the prior ref's search term. (The dialog and
+            # tile locators are already re-resolved fresh each iteration below,
+            # since each is a brand new `page.locator(...)` call rather than a
+            # handle carried over from a prior loop pass.)
+            #
+            # Presence-guarded (#281 final review): a picker variant with no
+            # search box at all (#174's full-page media-library drift) must
+            # not become a hard dependency for every ref — an unconditional
+            # `.fill("")` would wait out a full actionability timeout against
+            # an element that's simply absent from the DOM.
+            search = page.locator(PICKER_SEARCH_INPUT).first
+            if await search.count():
+                await search.fill("")
+
             if await VideoGenerationMixin._select_existing_asset(
                 page, media_id, display_name, out_dir=out_dir
             ):

{gflow_cli-0.30.0 → gflow_cli-0.31.0}/src/gflow_cli/cli_image.py

@@ -51,10 +51,14 @@ from gflow_cli.api.image import (
 from gflow_cli.api.image_upscale import TargetResolution, UpsampleImageRequest
 from gflow_cli.api.transports import transport_choices
 from gflow_cli.config import get_settings
-from gflow_cli.data.recorder import OperationRecorder
+from gflow_cli.data.recorder import OperationRecorder, escalate_asset_collision
 from gflow_cli.data.repository import DataRepository
 from gflow_cli.data.store import DataStore
-from gflow_cli.errors import ConfigurationError, DataStoreError
+from gflow_cli.errors import (
+    ConfigurationError,
+    DataIntegrityError,
+    DataStoreError,
+)
 from gflow_cli.image_batch import (
     ALLOWED_ASPECT_RATIOS as _ALLOWED_ASPECT_RATIOS,
 )
@@ -939,6 +943,16 @@ def _record_generated_images_safe(
 
     Tool provenance (``original_prompt`` / ``tool``) travels on ``request``, so
     the recorder reads it directly — no separate kwarg to drift out of sync.
+
+    Collision escalation (issue #281, #282 review): a ``DataIntegrityError``
+    whose ``route`` is the asset-collision constraint means the write itself
+    violated a local DB constraint — most likely the per-profile uniqueness of
+    ``flow_media_id`` — i.e. the just-downloaded file may be a pre-existing
+    asset rather than genuinely new media. That is NOT a warn-and-continue
+    case like a generic ``DataStoreError``; ``escalate_asset_collision``
+    raises ``MediaAttributionError`` for that route and returns normally for
+    any other (unrelated) ``DataIntegrityError``, in which case this falls
+    through to the same warn-and-continue path as a plain ``DataStoreError``.
     """
     try:
         recorder.record_generated_images(
@@ -954,6 +968,8 @@ def _record_generated_images_safe(
             operation_kind=operation_kind,
         )
     except DataStoreError as exc:
+        if isinstance(exc, DataIntegrityError):
+            escalate_asset_collision(exc, images=images, saved_paths=saved_paths)
         first_image = images[0] if images else None
         first_path = saved_paths[0] if saved_paths else None
         _warn_persistence_failed_after_success(
@@ -1004,6 +1020,7 @@ async def _run_t2i(
                     count=count,
                 )
 
+            recorder.verify_media_attribution(profile_name=profile_name, images=images)
             saved_paths = await _download_images(client, images, out, output_root)
 
             if as_json:
@@ -1450,6 +1467,7 @@ async def _run_i2i(
                     count=count,
                 )
 
+            recorder.verify_media_attribution(profile_name=profile_name, images=images)
             saved_paths = await _download_images(client, images, out, output_root)
 
             if as_json: