gflow-cli 0.32.1__tar.gz → 0.33.0__tar.gz

{gflow_cli-0.32.1 → gflow_cli-0.33.0}/.env.template

@@ -26,6 +26,13 @@
 # Useful for agent pipelines — set low to surface hung logins as exit 12 fast.
 # GFLOW_CLI_AUTH_LOGIN_TIMEOUT=600
 
+# Anti-bot pause between prompt submissions in multi-prompt image runs
+# (image batch, t2i --prompts-file/--stdin, gflow run). 'MIN-MAX' seconds, a
+# single number for 0-N, or 0 to disable. Default 0.5-1.5 (small on purpose);
+# widen (e.g. 10-30) if runs hit WAF 403s. The --jitter flag beats this.
+# See docs/CONFIGURATION.md § GFLOW_CLI_JITTER_RANGE.
+# GFLOW_CLI_JITTER_RANGE=0.5-1.5
+
 # -----------------------------------------------------------------------------
 # Output paths
 # -----------------------------------------------------------------------------
@@ -131,6 +138,14 @@
 # language end-to-end (see KNOWN_ISSUES § issue #24).
 # GFLOW_CLI_LOCALE=en-US
 
+# Display name of the --project project, used by `gflow video i2v` to select
+# the target project in the media picker's project menu when attaching a
+# media-UUID frame (#287 — the menu lists projects by NAME; unnamed projects
+# show only creation timestamps). Same as the `--project-name` flag, which
+# takes precedence when both are set. Escape hatch when automatic name
+# derivation (tab title / page hints) fails.
+# GFLOW_CLI_PROJECT_NAME=
+
 # -----------------------------------------------------------------------------
 # Headless Daemon (gflow serve)
 # -----------------------------------------------------------------------------

{gflow_cli-0.32.1 → gflow_cli-0.33.0}/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.33.0] — 2026-07-12
+
+### Added
+
+- **Configurable anti-bot jitter (#241).** The pause between multi-prompt image submissions is now tunable via `--jitter MIN-MAX` on `gflow image t2i` / `gflow image batch` or the `GFLOW_CLI_JITTER_RANGE` setting (env var or `.env`; flag beats env; a single number `N` means uniform 0–N like `video chain --jitter`; `0` disables; bounds must be finite and ≤ 3600 s). The previously **unpaced** paths — `t2i --prompts-file` / `--stdin` / multi-positional and `gflow run` image batches — now pace by default too; field data showed unpaced bursts tripping Flow's WAF (403 `PUBLIC_ERROR_UNUSUAL_ACTIVITY`). WAF cadence behavior and cooldown guidance documented in [DEBUGGING § WAF cadence](docs/DEBUGGING.md#waf-cadence).
+- **`--project-name TEXT` on `gflow video i2v` (env: `GFLOW_CLI_PROJECT_NAME`).** The media picker's project menu lists projects by display NAME only — no ids anywhere in its markup, and unnamed projects show nothing but creation timestamps (live round-4 dump: 80 recency-ordered `menuitem`s). When gflow attaches an in-project asset by media UUID it must first select the right project in that menu, so it needs the project's display name. Automatic derivation is best-effort but live-validated (round 5 confirmed the editor tab title carries the name: `Google Flow - <project name>`); `--project-name` is the explicit, highest-precedence override for when derivation fails on other cohorts/locales — a permanent escape hatch, not a workaround. Threads `GenerateVideoRequest.project_name` through to the picker project-menu match; documented in `.env.template`. CLI-only for now: the MCP `gflow_generate_video` tool has no media-UUID frame inputs yet, so the override has no consumer there (command-level parity unaffected; the field rides along when ref-id support lands) (#287).
+
+### Changed
+
+- **Default image-batch jitter lowered from 3–7 s to 0.5–1.5 s (#241).** The default is deliberately minimal — enough to break a perfectly uniform burst signature without wasting wall-clock. Widen (`--jitter 10-30` / `GFLOW_CLI_JITTER_RANGE=10-30`) when runs start hitting WAF 403s, then dial back once the score decays.
+
+### Fixed
+
+- **`gflow video i2v <media-uuid>` now reaches assets deep in a crowded project's virtualised media grid (#287 — primary fix, part 1: scroll on the RIGHT node, progress-bounded).** The live repro: `TransportTimeoutError` ("Start frame asset ... could not be located in the media picker") on a ~100+-asset project for an asset that WAS in the project and in the local catalog, while the same command worked from a small scratch project. `_select_existing_asset`'s scroll fallback had a fixed budget (12 scrolls x 500 px), capping the reachable depth of the react-virtuoso grid regardless of grid size — and the round-6 audit exposed a second layer: the scroll was a blind hover+wheel over the dialog, but react-virtuoso scrolls its OWN container, so a wheel over the wrong node is a silent no-op that looks exactly like "end of grid". The scroll (shared with `_find_picker_entity_tile` via `_scroll_picker_grid_until_rendered`) now drives the dialog's ACTUAL scrollable element via JS (`[data-virtuoso-scroller]` preferred, then the first overflow container; hover+wheel kept as fallback when the probe fails), and is bounded by evidence of progress: it keeps scrolling while the set of rendered tile identifiers still changes between scrolls — depth proportional to grid size — stops after 3 consecutive no-progress scrolls, retains the legacy 12-scroll budget when the DOM probe yields no evidence, and caps at a 200-scroll hard ceiling. Every scroll probe event reports WHICH node moved (tag + class) and its scrollTop before/after, so a wrong-node no-op (frozen scrollTop) is visible in telemetry. The not-found contract is unchanged: same `TransportTimeoutError` naming the slot and UUID (#287).
+- **CLI-resolved PROMPT search hints surface UUID frame refs via Flow's media search (#287 — primary fix, part 2).** Live rounds proved Flow's picker search does NOT index media UUIDs (both the full-UUID and UUID-stem tiers found nothing), but each picker tile's `alt` text carries the asset's generation PROMPT — which the search does index. New `get_asset_prompt(db_path, media_id)` catalog query (latest output-operation prompt by `flow_media_id`); `gflow video i2v` resolves each UUID frame ref's recorded prompt and passes its first 6 words as `GenerateVideoRequest.search_hints` (best-effort — no catalog, no hints; layering respected: the CLI resolves because it owns catalog access, the transport only consumes). `_select_existing_asset` types each hint into the picker search box after the UUID tiers and still matches tiles by UUID-in-`src` among the results, so an imprecise hint can only surface extra tiles, never select a wrong one; a hint hit skips the scroll fallback entirely. The pre-existing tiers (display name, media UUID, UUID stem) are kept as cheap first attempts (#287).
+- **Hardening: the media picker's library view is verified/aligned to the target project before any UUID asset lookup (#287 — demoted from root cause after round 5).** Round-2's DOM dump appeared to show the picker's library open on a DIFFERENT project ("gflow-cli t2i", 16 tiles, target id nowhere in the dialog), and rounds 2-5 built project-alignment machinery on that reading. The round-5 title telemetry then inverted it: the raw tab title on `/project/f6caf027` was "Google Flow - gflow-cli t2i" — the trigger's "gflow-cli t2i" WAS the target project's actual display name, so the picker had been on the correct project all along and the round-2 evidence was a mirage. The machinery stays as hardening (the picker's library IS per-project with its own selector, so it CAN open on the wrong project — now that state is detected and corrected, and the round-5/6 name derivation gives the match a working source): `_sync_picker_project` runs each time the frame-slot / Add-Media dialog opens: it derives the target project id from the editor URL, resolves the project's display NAME (the menu renders names, not ids; live round-3 run confirmed the previous href/class-only page probes find nothing) — precedence: the `--project-name` / `GFLOW_CLI_PROJECT_NAME` override, then the editor tab title (`document.title` — the editor was navigated to `/project/<id>` before the picker opened; "Flow" AND "Google Flow" branding is stripped tolerantly across separator variants — the live-observed pattern is `Google Flow - <project name>` — branding-only titles are rejected so 'flow' can never contains-match a project like 'gflow-cli i2i', and the raw title is logged on every resolution so the real live pattern stays learnable), then an element whose `href` references the project id, then a project-title-classed element (the local catalog's `projects.title` was considered but the transport layer has no catalog access, and the live page also covers renames and non-gflow projects) — probes the trigger cascade with the live-observed Radix `ProjectDropdownSubTrigger` class first (the generic `aria-haspopup='menu'` fallback tier explicitly excludes the sibling `SortDropdownSubTrigger` — "Recentes" on the observed pt-BR profile — and no tier matches on locale-dependent labels), no-ops when the trigger already shows the target project (by id, or by resolved name — exact OR contains, since the trigger text carries icon-ligature noise; round 5 wasted ~30 menu probes hunting for a project it was already in because the probe demanded exact equality) or when no selector exists (older cohort), and otherwise opens the Radix submenu (click, then hover, then focus+ArrowRight — SubTriggers may ignore plain click — each step verified against the portal-rendered `[role='menu'][data-state='open']`), polls up to ~3s for the portal to POPULATE (live round 3: the open-state flips before the project list renders — matching an empty portal was a guaranteed miss), and clicks the innermost candidate matching the target — anchors whose `href` carries the project id first (round 3 also showed the portal holds ZERO classic menu-item ARIA roles, so the sweep covers generic clickables: `a`, `button`, `li`, `div[role]`, plus the ARIA roles), then the id anywhere in markup, then the normalized name (exact match before contains, so timestamp-labeled scratch entries like "Jul 11, 11:00 PM" can't collide). When the in-view match misses, the open portal itself is scrolled with the same progress-bounded pattern (scroll one step, re-match, stall-terminate when the rendered item set stops changing, hard ceiling) — the recency-ordered menu holds EVERY project and the target's entry can sit below the visible fold. A miss closes the menu (Escape) and proceeds, leaving the asset lookup as the authority.
+- **Every picker-lookup decision point now emits structured telemetry, and each failure mode leaves a bounded DOM dump (#287 diagnosis).** The first live verification failed with zero events from the new code paths, making the failing layer indistinguishable (search tiers vs progress probe vs tile matcher vs wrong library project) — this telemetry is what confirmed the root cause in round 2. New `ui_automation_video.*` events: `picker_project_selector_absent` / `picker_project_already_active` / `picker_project_menu_opened` (opened + method: click/hover/keyboard) / `picker_project_menu_populated` (element count after the population poll) / `picker_project_switched` (matched_by: href/id/name) / `picker_project_switch_miss` (menu_opened, menu_elements, candidate count, dump path) / `picker_project_sync_skipped` / `picker_project_name_override` / `picker_project_name_resolved` / `picker_project_name_unresolved` (both name events carry the raw tab title) / `picker_project_menu_scroll_probe` (per menu scroll: rendered item count + new-item delta) / `picker_project_menu_scroll_done` (reason: found / stall / no_menu / ceiling) (project alignment), `picker_search_tier` (term, found, rendered-tile count) and `picker_search_unavailable`, `picker_scroll_probe` (per scroll: rendered-tile count + new-tile delta, plus WHICH node was scrolled — tag + class — and its scrollTop before/after, so a wrong-node no-op scroll with a frozen scrollTop is visible) and `picker_scroll_done` (termination reason: found / stall / legacy_budget / ceiling, total attempts), and `existing_asset_not_found` (media id, project id, screenshot + dump paths). On a final not-found, `_capture_picker_dom_dump` writes `debug_picker_dom_<uuid8>.json` to the out-dir — tile count, the first 3 tiles' outerHTML truncated to 500 chars (enough to see which attribute carries the media identity in a given cohort), the dialog's aria/role/data attributes, the project-selector candidates' outerHTML, and whether the target project id appears in the dialog at all — plus a `debug_picker_miss_<uuid8>.png` screenshot. On a project-switch miss, the OPEN portal's raw innerHTML (bounded to 4000 chars) plus its child-element count and tag histogram are written to `debug_picker_project_menu_<uuid8>.json` and summarized on the event — round 2's closed-trigger dump and round 3's role-filtered item list both left the menu structure invisible; raw markup can't be blinded by role assumptions. All dumps follow the 0.32.1 None-on-capture-failure contract (never report a file that was not written) (#287).
+
 ## [0.32.1] — 2026-07-11
 
 ### Fixed
@@ -1933,7 +1951,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.32.1...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.33.0...HEAD
+[0.33.0]: https://github.com/ffroliva/gflow-cli/compare/v0.32.1...v0.33.0
 [0.32.1]: https://github.com/ffroliva/gflow-cli/compare/v0.32.0...v0.32.1
 [0.32.0]: https://github.com/ffroliva/gflow-cli/compare/v0.31.0...v0.32.0
 [0.31.0]: https://github.com/ffroliva/gflow-cli/compare/v0.30.0...v0.31.0

{gflow_cli-0.32.1 → gflow_cli-0.33.0}/KNOWN_ISSUES.md

@@ -450,6 +450,9 @@ batch — so it is not a global incompatibility but a per-profile WAF state.
    the score).
 3. **Avoid same-day repeated batch runs** on a profile after a 403 — each
    rejected request can raise the score further.
+4. **Widen the submission jitter** when composing multiple runs — `--jitter 10-30`
+   or `GFLOW_CLI_JITTER_RANGE` (#241); cadence guidance in
+   [DEBUGGING § WAF cadence](docs/DEBUGGING.md#waf-cadence).
 
 **Tracked separately from** the architectural ["first-attempt listener-miss
 flake"](https://github.com/ffroliva/gflow-cli/pull/40) — that one was caused

{gflow_cli-0.32.1 → gflow_cli-0.33.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.32.1
+Version: 0.33.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.32.1 → gflow_cli-0.33.0}/docs/CONFIGURATION.md

@@ -153,6 +153,14 @@ GFLOW_CLI_AUTH_LOGIN_TIMEOUT=120 gflow auth login   # abort after 2 minutes
 **Default:** `600`
 **Note:** This is a single-request ceiling; the *batch* timeout you experience is sum of all per-clip waits.
 
+### `GFLOW_CLI_JITTER_RANGE`
+
+**What:** Anti-bot pause between prompt submissions in multi-prompt image runs (`gflow image batch`, `gflow image t2i --prompts-file` / `--stdin` / multiple positional prompts, and `gflow run` image batches). Spaces out the *submission clicks* only — generations still run in parallel inside Flow.
+**Values:** `MIN-MAX` seconds (e.g. `10-30`), a single number `N` (uniform `0`–`N`, mirrors `video chain --jitter`), or `0` to disable.
+**Default:** `0.5-1.5` — deliberately small so runs don't waste wall-clock. **Widen (e.g. `10-30`) when runs start hitting WAF 403s**, then dial back once the score decays.
+**CLI override:** `--jitter` on `image t2i` and `image batch` (flag beats env).
+**Why:** Flow's WAF reacts to cumulative submission cadence — see [DEBUGGING § WAF cadence](DEBUGGING.md#waf-cadence).
+
 ### `GFLOW_CLI_LOG_LEVEL`
 
 **What:** Logging verbosity.

{gflow_cli-0.32.1 → gflow_cli-0.33.0}/docs/DEBUGGING.md

@@ -173,6 +173,38 @@ $env:PYTHONUTF8 = "1"
 
 Bash users on Git Bash / WSL inherit a UTF-8 locale and don't need this.
 
+## WAF cadence
+
+Flow's WAF reacts to **cumulative submission cadence**, not individual
+requests. Field data (issue [#241](https://github.com/ffroliva/gflow-cli/issues/241),
+2026-07-05, real account):
+
+- 3-prompt multi-prompt runs spread 30–60 min apart all passed.
+- A burst of ~14 image submissions in ~10 min ended in a **403**
+  (`Flow returned 403; blocked by WAF or fingerprint check`,
+  `PUBLIC_ERROR_UNUSUAL_ACTIVITY` — see
+  [KNOWN_ISSUES § batchGenerateImages HTTP 403](../KNOWN_ISSUES.md)).
+- After ~30 min of cooldown, individually-paced calls (45–120 s apart) on the
+  same profile and project passed 4/4.
+
+Practical guidance:
+
+- **Pace multi-prompt runs — escalate only when needed.** All multi-prompt
+  image paths (`image batch`, `image t2i --prompts-file` / `--stdin` /
+  multiple prompts, `gflow run` image batches) apply a small random
+  0.5–1.5 s pause between submissions by default — enough to break a
+  perfectly uniform burst signature without wasting wall-clock. If runs
+  start returning 403s, widen with `--jitter 10-30` or
+  `GFLOW_CLI_JITTER_RANGE` ([CONFIGURATION § GFLOW_CLI_JITTER_RANGE](CONFIGURATION.md#gflow_cli_jitter_range)),
+  then dial back once the score decays. `--jitter 0` disables pacing.
+- **Cool down after a 403.** Wait 30–60 min, then probe with a single small
+  generation before batching again.
+- **Reuse a project.** Repeated project churn (`project.createProject` calls
+  between generations) adds to the bot-like signature. For repeated
+  single-prompt runs (`t2i`, `i2i`), pass `--project` to reuse a standing
+  project. Multi-prompt runs already create only **one** shared project per
+  run (never one per prompt).
+
 ## Common failure modes
 
 See [`KNOWN_ISSUES.md`](../KNOWN_ISSUES.md) for the canonical list and

{gflow_cli-0.32.1 → gflow_cli-0.33.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.32.1](LIVE_VERIFICATION_v0.32.1.md) (**#293 teardown fix live-verified credit-free** — error-path aborts leave ZERO chrome.exe holding the profile [3× leak reproduced pre-fix same day]; force-close fallback + ProfileLockedError translation unit-pinned; #283 wave logic fixes mock-verified to exact call counts). Prior: [v0.32.0](LIVE_VERIFICATION_v0.32.0.md) (**#287 UUID i2v frames proven live e2e** — an in-project asset selected by media UUID in the frame-slot dialog [frame_ref_attached, startImage bound on the wire, ZERO upload events] produced a real 720×1280 interpolation, resolving the #237 negative prior; foreign UUID → exit 9 pre-generation with screenshot; **#288 duration fail-fast proven live** — exit 23 pre-submit saved a 10-credit generation, and the debug screenshot confirmed the duration control is ABSENT from the cohort's settings popover [locale hypothesis refuted]; upload-400 exit-27 repro deferred-with-reason — the original rejected JPEG no longer exists). Prior: [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)
+**"What was actually live-verified for the latest release?"** → latest: [LIVE_VERIFICATION_v0.33.0](LIVE_VERIFICATION_v0.33.0.md) (**#287-follow-up picker fix proven live on the original repro** — the v0.32.1-failing `i2v <uuid> --project <crowded>` command now exits 0 with a real 3.0 MB `ftyp` mp4, `frame_ref_attached` + `video_saved`, zero uploads; **#241 jitter live-verified on both paths** — flag `--jitter 4-6` → `batch_jitter_sleep seconds=4.98`, and the new 0.5–1.5 s default → `seconds=1.47`, each firing exactly once between two t2i submissions; environment note: the denon82 cohort is now natively agentic and round-2 generations hit the pre-existing #281 `MediaAttributionError`, not a regression). Prior: [v0.32.1](LIVE_VERIFICATION_v0.32.1.md) (**#293 teardown fix live-verified credit-free** — error-path aborts leave ZERO chrome.exe holding the profile [3× leak reproduced pre-fix same day]; force-close fallback + ProfileLockedError translation unit-pinned; #283 wave logic fixes mock-verified to exact call counts). Prior: [v0.32.0](LIVE_VERIFICATION_v0.32.0.md) (**#287 UUID i2v frames proven live e2e** — an in-project asset selected by media UUID in the frame-slot dialog [frame_ref_attached, startImage bound on the wire, ZERO upload events] produced a real 720×1280 interpolation, resolving the #237 negative prior; foreign UUID → exit 9 pre-generation with screenshot; **#288 duration fail-fast proven live** — exit 23 pre-submit saved a 10-credit generation, and the debug screenshot confirmed the duration control is ABSENT from the cohort's settings popover [locale hypothesis refuted]; upload-400 exit-27 repro deferred-with-reason — the original rejected JPEG no longer exists). Prior: [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.33.0/docs/LIVE_VERIFICATION_v0.33.0.md

@@ -0,0 +1,53 @@
+# Live verification — v0.33.0 (2026-07-12)
+
+Both user-facing changes exercised against live Flow on the merged `develop`
+tip (`669884c`), profile `denon82`, before tagging. Evidence follows the
+5-layer ledger (file count · magic bytes · dimensions/shape · structlog
+invariants · user-confirmable artifact).
+
+## 1. #287 follow-up (PR #296) — picker reaches assets deep in a crowded project
+
+**Command (the original repro, verbatim surface):**
+
+```
+gflow video i2v 2f72aa2a-5081-4df8-a3b1-64b6a859274c "slow dolly-in, soft light shifting across the scene" \
+  --project f6caf027-ad68-49e3-aac9-ee32f1582bf3 --profile denon82 --out-dir <scratch>/330-e2e-i2v
+```
+
+- **Exit code:** `0` (v0.32.1 failed this exact command with `TransportTimeoutError`, exit 9).
+- **File count:** 1 mp4 produced.
+- **Magic bytes:** `ftyp` at offset 4 — real ISO-BMFF video.
+- **Size:** 3.0 MB.
+- **Structlog invariants:** `picker_project_name_resolved` → `picker_project_already_active`
+  (alignment machinery confirms the picker was on the target project; no switch needed)
+  → `frame_ref_attached` → `video_saved`. Zero upload events — the in-project asset
+  was referenced, not re-uploaded.
+- **Artifact:** `497d687d-86cc-4bcc-aeab-878a1d1c4fae.mp4` (scratch dir; user-inspectable).
+
+## 2. #241 (PR #297) — anti-bot jitter: configurable, small default, t2i path paced
+
+**Round 1 (pre-merge, flag path):** `gflow image t2i "<p1>" "<p2>" --jitter 4-6` →
+`batch_jitter_sleep {"seconds": 4.98, "index": 1}` — exactly one pause, between the
+two submissions (never before the first), within the requested 4–6 s. Prompt 1
+saved a real jpg.
+
+**Round 2 (post-merge, default path):** same 2-prompt t2i with NO `--jitter` flag →
+`batch_jitter_sleep {"seconds": 1.47, "index": 1}` — within the new 0.5–1.5 s
+default, fired once. This is the release-defining behavior: the previously
+unpaced t2i multi-prompt path now paces, at the minimal default.
+
+**Environment finding (pre-existing, NOT a regression):** both round-2 generations
+failed post-submission with the #281 `MediaAttributionError` (exit 26), and
+`prefer_classic.cohort_natively_agentic` fired — the `denon82` cohort now mounts
+Flow's agentic UI unconditionally and `GFLOW_CLI_PREFER_CLASSIC=1` cannot exit it.
+The identical failure mode exists on released v0.32.1 (same cohort); the jitter
+feature under verification is upstream of generation and verified by the sleep
+event + the round-1 saved jpg. Tracked in KNOWN_ISSUES (agentic attribution) —
+candidate for the next issue wave.
+
+## Not verified this cycle
+
+- `GFLOW_CLI_JITTER_RANGE` via a real `.env` file on a live run (covered by unit
+  tests through pydantic-settings; env-var form is equivalent at the Settings layer).
+- `gflow run --config` image-batch pacing (same `run_sequential_batch` code path
+  as t2i, verified live above; `gflow run` adds only config parsing on top).

{gflow_cli-0.32.1 → gflow_cli-0.33.0}/docs/USAGE.md

@@ -163,6 +163,11 @@ Options:
   --continue-on-error /
   --fail-fast               Continue after per-prompt failures or stop at the
                             first failed prompt. [default: continue-on-error]
+  --jitter SPEC             Anti-bot pause between multi-prompt submissions:
+                            'MIN-MAX' seconds, a single number for 0-N, or 0
+                            to disable. Widen (e.g. 10-30) if runs hit WAF
+                            403s. [default: 0.5-1.5; GFLOW_CLI_JITTER_RANGE
+                            overrides the default]
   --model [nano2|nano-pro|image4]
                             Image model alias.                [default: nano2]
   --aspect [9:16|16:9|1:1|4:3|3:4]
@@ -394,11 +399,12 @@ Example: [`test_assets/sample_batch.json`](../test_assets/sample_batch.json).
 
 ### Session behaviour
 
-All prompts in a batch share one Flow project. The editor is opened once; each prompt is submitted in turn with a random 3–7 second pause between submissions. This jitter is a **submission-cadence anti-bot-detection measure** — it spaces out the submission clicks, not the generation wait. All generations run in parallel inside Flow; only the click timing is jittered. The command returns once every submitted generation has resolved (success or failure), not after the last click.
+All prompts in a batch share one Flow project. The editor is opened once; each prompt is submitted in turn with a small random pause between submissions (default 0.5–1.5 seconds; tune with `--jitter` or `GFLOW_CLI_JITTER_RANGE`). This jitter is a **submission-cadence anti-bot-detection measure** — it spaces out the submission clicks, not the generation wait. All generations run in parallel inside Flow; only the click timing is jittered. The command returns once every submitted generation has resolved (success or failure), not after the last click. See [DEBUGGING § WAF cadence](DEBUGGING.md#waf-cadence) for when to widen the range.
 
 ### Flags
 
 - `--continue-on-error` / `--fail-fast` — keep going past row failures or stop at the first one (default: `--fail-fast`). On fail-fast, already-completed images are downloaded before the error is surfaced.
+- `--jitter SPEC` — anti-bot pause between submissions: `MIN-MAX` seconds (e.g. `10-30`), a single number for `0`–`N`, or `0` to disable. Default `0.5-1.5`; widen if runs hit WAF 403s. `GFLOW_CLI_JITTER_RANGE` overrides the default, the flag beats both.
 
 ### Limits
 

{gflow_cli-0.32.1 → gflow_cli-0.33.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gflow-cli"
-version = "0.32.1"
+version = "0.33.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.32.1 → gflow_cli-0.33.0}/src/gflow_cli/__init__.py

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