gflow-cli 0.61.0__tar.gz → 0.62.0__tar.gz

{gflow_cli-0.61.0 → gflow_cli-0.62.0}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gflow",
-  "version": "0.61.0",
+  "version": "0.62.0",
   "description": "Reusable development and operations workflows for gflow-cli",
   "author": {
     "name": "Flavio Oliva",

{gflow_cli-0.61.0 → gflow_cli-0.62.0}/.env.template

@@ -173,7 +173,8 @@
 # `patchright install chromium`. Unset to revert to the default playwright engine.
 # GFLOW_CLI_BROWSER_ENGINE=playwright
 
-# Which Flow UI arm a command needs: auto (bind whatever renders) | classic
+# Which Flow UI arm a command needs: auto (default — no arm asked for, so it
+# resolves to classic, the arm that can satisfy a generation request) | classic
 # (require the hard aspect controls) | agentic (require the chat surface; needed
 # for -i instructions). gflow switches to the required arm, verifies via re-probe,
 # and aborts with exit 28 (retryable — the cohort flaps per load) if it can't be

{gflow_cli-0.61.0 → gflow_cli-0.62.0}/.github/workflows/ci.yml

@@ -205,6 +205,16 @@ jobs:
       - name: Type check
         run: uv run pyright src
 
+      # The overlay-precondition tests (#593) drive the captured changelog markup in
+      # a real headless Chromium — a mock cannot tell you whether
+      # `[role='dialog']:has(a[href*='changelog']) button` resolves against Flow's
+      # actual DOM, only a real CSS engine can. They skip cleanly when the browser is
+      # absent, which would make them silently decorative in CI, so one job in the
+      # matrix installs it. No account, no network, no credits.
+      - name: Install Chromium (real-DOM fixture tests)
+        if: matrix.python-version == '3.13'
+        run: uv run playwright install chromium --with-deps
+
       - name: Test (smoke only) + coverage
         # e2e/live tests require a logged-in Chromium profile and may spend
         # Flow credits. pyproject.toml excludes both markers by default; CI

{gflow_cli-0.61.0 → gflow_cli-0.62.0}/.gitignore

@@ -66,6 +66,11 @@ test_assets/debug_*/
 # Phase-2 live-spike capture outputs — NEVER commit (may contain real API payloads)
 scripts/dev/_spike_out/
 
+# HAR captures (GFLOW_CLI_HAR_PATH) — full request/response bodies, headers and
+# auth cookies. The _spike_out rule only covers the default location; a HAR
+# written anywhere else must not be committable either.
+*.har
+
 # Agent session marker — machine/session-local handoff state, regenerated per run
 .continue-here.md
 

{gflow_cli-0.61.0 → gflow_cli-0.62.0}/CHANGELOG.md

@@ -7,6 +7,161 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.62.0] — 2026-08-28
+
+### Changed
+
+- **`--ui-mode auto` (the default) now requires the *classic* Flow arm for image
+  generation ([#595](https://github.com/ffroliva/gflow-cli/issues/595)).** `auto`
+  used to bind whatever the composer rendered, so an account that Flow moved into
+  its **agentic** cohort — observed live on two accounts on 2026-08-27 — took a
+  path that cannot satisfy an image request and failed with either
+  `image_mode_tab` selector drift (exit 23) or a `WireFormatError` about video
+  bytes. Neither error named the cause, and the workaround
+  (`GFLOW_CLI_PREFER_CLASSIC=1`) had to be discovered from an error message.
+  `auto` now means "no arm was asked for" and resolves to `classic`, matching the
+  rule video has followed since [#299](https://github.com/ffroliva/gflow-cli/issues/299).
+  The bind still attempts classic recovery first and the cohort flaps per page
+  load, so a run only aborts (`UiModeUnavailableError`, **exit 28**, pre-submit,
+  zero credits) when the arm is genuinely pinned — and that abort is retryable.
+  The agentic arm stays reachable, but only when asked for by name
+  (`--ui-mode agentic` / `GFLOW_CLI_UI_MODE=agentic`) or by need (`-i` agent
+  instructions, which are agentic-only and still force it). The image **batch**
+  path carried its own inline mode resolution and so kept binding `auto`; it now
+  routes through the same policy as the single-prompt path.
+
+### Fixed
+
+- **An announcement modal that mounts *during* a batch generation no longer
+  silently changes the next prompt's settings**
+  ([#593](https://github.com/ffroliva/gflow-cli/issues/593) follow-up). #593 left a
+  stated gap: call sites that neither route through `_probe_selector_cascade` nor
+  sit behind a navigation gate were still unguarded, and the set had not been
+  enumerated. Auditing all 73 click/fill/press sites in the UI transports found
+  exactly one that survives the "can a modal actually land here?" test — the image
+  **batch** loop's per-prompt boundary. A batch dismisses overlays once, during
+  setup; from prompt 2 on, the settings clicks are the first act after a
+  multi-second generation wait on a page that never navigates. This one is worse
+  than a timeout: `_open_gen_settings_panel` returns `False` when no selector
+  matches and the caller falls back to Flow's current defaults, so a modal that
+  mounted during prompt 1 did not fail prompt 2 — it generated it at the wrong
+  aspect/count. The boundary now runs the same `_require_unblocked` check the
+  navigation epochs use (one probe on the happy path), so the run aborts with
+  exit 23 and a screenshot instead of producing a quietly wrong image.
+
+- **A Flow announcement modal no longer wedges a run with an unexplained timeout
+  ([#593](https://github.com/ffroliva/gflow-cli/issues/593)).** When Google ships a
+  feature, Flow puts a full changelog dialog over the editor and sets
+  `body { pointer-events: none }` while leaving the app neither `aria-hidden` nor
+  `inert` — so every control reads visible and enabled yet never receives a click,
+  and Playwright's actionability wait runs to timeout with no message. Measured live
+  on two accounts (2026-08-27, pt and en), which is also how the four failure paths
+  below were found:
+  - The gallery "+ New project" sweep ran with **no overlay check at all** — the one
+    navigation epoch that had none. A modal there cost 18 selectors x Playwright's
+    30 s default click timeout and then reported `Could not find 'New project' CTA`,
+    which is the wrong error about the wrong thing. It now dismisses first and the
+    click carries an explicit 5 s timeout.
+  - Dismissal **verifies itself**. It previously returned success the moment a click
+    landed, so a dismissal that changed nothing still logged `overlay_dismissed` and
+    the run timed out somewhere unrelated — the success event lied. It now re-probes
+    and reports honestly, with a new `ui_automation.overlay_postmortem` warning.
+  - A persistent block now **aborts pre-submit at $0** with exit 23 and a screenshot
+    (probe `overlay_close_button`) instead of hanging. A transient is not enough to
+    trigger it: Flow's own menus set the same property while open, so the guard
+    re-probes after a settle.
+  - **The modal can mount *after* the navigation gate**, which is how it kept winning.
+    Flow hydrates on its own schedule, well past `domcontentloaded`, so dismissal at
+    the navigation boundary can run before the dialog exists — then the dialog appears
+    and covers a control that is present and enabled, and the selector cascade reports
+    drift for an element that is perfectly fine. A failed probe now checks the overlay
+    state before believing itself, and dismisses and re-probes once. The guard lives in
+    the one cascade every probe routes through, so all ten call sites are covered.
+    Verified live on a third account (2026-08-27): before the fix, `image_mode_tab`
+    raised `UiSelectorDriftError` with the announcement on screen and **no
+    `overlay_detected` in the log at all**; after it, the same command on the same
+    account cleared the modal (`setLastAcknowledgedChangeLogId` → 200, 23 s in, i.e.
+    from the probe guard rather than the navigation gate) and left the editor
+    reachable.
+  - The destructive Escape fallback is now **gated on the page actually being
+    blocked**, which retires the [#395](https://github.com/ffroliva/gflow-cli/issues/395)
+    hazard structurally rather than by comment. That regression pressed Escape on the
+    character composer and sent a generation out without `entityContext` — billed,
+    silently wrong. A page we can positively see is clickable is never touched.
+
+  Two raw-`goto` e2e tests (`test_sidebar_recovery_e2e`, `e2e_auth` — the nightly
+  canary's default tier — and `test_agentic_count_enforcement_e2e`) bypass every
+  transport boundary and were unprotected; both now dismiss explicitly, and both stop
+  hardcoding `"en"` in favour of the account's own locale (#587).
+
+  **One deliberate behaviour change.** The close-button cascade is now split: the
+  changelog-scoped anchor (`[role='dialog']:has(a[href*='changelog']) button`) runs on
+  any page because it cannot match one of Flow's own surfaces, while the generic
+  selectors (`button:has(i:text('close'))` and friends) and the Escape fallback run
+  only once the body is known to be blocked. The cost is that a non-modal banner —
+  one that covers a control without blocking the body — is no longer auto-closed by
+  the generic selectors. That is the right side of the trade: those same generic
+  selectors match the character composer's own close button, #395 spent real credits
+  through exactly that door, and `KNOWN_ISSUES` rates the banner case Low and
+  transient.
+
+### Added
+
+- **`gflow project list` / `project show` and the MCP `gflow_list_projects` tool now
+  emit an account-correct editor URL
+  ([#587](https://github.com/ffroliva/gflow-cli/issues/587)).** They previously
+  emitted no URL at all: they are network-free catalog reads, so they had no way to
+  resolve a locale and correctly declined to guess one. With the locale now cached
+  per profile the link is readable offline. An unknown locale still yields the bare
+  URL — never a guessed `/fx/en/...`, which is the shape that started this thread by
+  being handed to a pt-BR account owner. In the terminal the project id renders as a
+  hyperlink, costing no column width.
+
+### Changed
+
+- **The account-locale probe no longer costs ~4 s on every command
+  ([#587](https://github.com/ffroliva/gflow-cli/issues/587)).** The probe added in
+  v0.61.0 settles the bootstrap navigation to learn where Flow lands. On an account
+  Flow does *not* redirect there is nothing to settle, so `wait_for_url` ran to the
+  full `URL_SETTLE_TIMEOUT_MS` every single invocation. Measured live 2026-08-27,
+  best-of-N per arm: **~6.2 s -> ~2.0 s** setup on the non-redirecting account,
+  against an unchanged ~2.8 s -> ~2.9 s on a redirecting one (the control, which
+  shows the cold-then-warm ordering is worth nothing on its own). Run-to-run
+  variance is over a second, so read the delta as "the 4 s settle timeout", not to
+  two decimals.
+  The outcome is cached in the profile dir (`.gflow_locale`, a sibling of the
+  existing `.gflow_account`). The same guard covers all four `await_url_settled`
+  call sites **in the UI transport**; guarding only the editor entry left three
+  navigations still paying the timeout. (The three sites in the experimental REST
+  transports have no resolved locale to gate on and are unchanged.)
+
+  The cache decides only *whether to wait*, never *where to navigate*. Sending the
+  browser to a cached `/fx/{seg}/...` was built, measured, and rejected: Flow
+  serves whatever segment it is asked for, so a pt-BR account handed `/fx/de/`
+  stayed there and rendered `html lang=de` with no redirect — no correction signal,
+  and a wrong-language UI for as long as the stale value lived. That is #580's
+  defect in a new hat. The navigation therefore stays bare, which is what lets Flow
+  state the account's own answer. Reproducer: `scripts/dev/spike_locale_poison.py`.
+
+  The cache holds **four** states, and the fourth is what keeps it honest.
+  `await_url_settled` returns `None` for both "Flow does not redirect this account"
+  and "the settle timed out this once", so one slow network could otherwise commit
+  to "not redirected" permanently and silently restore #580's post-`goto` race. A
+  no-redirect observation is therefore **provisional** until a second run agrees;
+  a transient timeout costs one extra probe instead of a lasting defect.
+
+### Fixed
+
+- **A NULL `model` / `aspect` / `project_id` no longer reads back as the string
+  `"None"` in `gflow data list images|videos`.** All three columns are nullable in
+  the schema (`assets.model`, `assets.aspect_ratio`, `assets.flow_project_id`), but
+  both listing constructors wrapped them in a bare `str(...)`, so a NULL became the
+  four-character string `"None"` — emitted verbatim into `--json` and
+  indistinguishable from a real value. `_row_to_operation_error` in the same module
+  already guarded `model` correctly; the two listing paths never got the same
+  treatment. `ImageRow` / `VideoRow` now type these fields `str | None` and the JSON
+  output carries `null`.
+
 ## [0.61.0] — 2026-08-27
 
 ### Fixed
@@ -3247,7 +3402,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.61.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.62.0...HEAD
+[0.62.0]: https://github.com/ffroliva/gflow-cli/compare/v0.61.0...v0.62.0
 [0.61.0]: https://github.com/ffroliva/gflow-cli/compare/v0.60.0...v0.61.0
 [0.60.0]: https://github.com/ffroliva/gflow-cli/compare/v0.59.0...v0.60.0
 [0.59.0]: https://github.com/ffroliva/gflow-cli/compare/v0.58.0...v0.59.0

{gflow_cli-0.61.0 → gflow_cli-0.62.0}/KNOWN_ISSUES.md

@@ -503,6 +503,16 @@ playwright._impl._errors.TimeoutError: Locator.click: Timeout 30000ms exceeded.
 
 **Legacy workaround (no longer required):** open Flow in Chrome with the same profile once, click the `X` on the "What's new" popup, then close Chrome cleanly.
 
+**Update 2026-08-27 ([#593](https://github.com/ffroliva/gflow-cli/issues/593)) — the modal wedges more than the first run.** Captured live on two accounts (pt and en): the announcement sets `body { pointer-events: none }` while leaving the app neither `aria-hidden` nor `inert`, so controls read visible **and enabled** yet never receive a click. That is why the symptom is a bare `TimeoutError` naming nothing rather than the "intercepts pointer events" message above. Three gaps were closed:
+
+- The gallery "+ New project" sweep had no overlay check at all, so a modal there burned 18 selectors x Playwright's 30 s default click timeout before reporting the wrong error.
+- Dismissal reported success on click without verifying anything cleared — `overlay_dismissed` was logged on runs that then timed out elsewhere.
+- The Escape fallback is now gated on the page being provably blocked, which retires the [#395](https://github.com/ffroliva/gflow-cli/issues/395) hazard structurally.
+
+A block that survives dismissal now aborts pre-submit with exit 23 (probe `overlay_close_button`) and a screenshot, at zero credits, instead of hanging. Dismissal persists server-side — Flow records it as `videoFx.setLastAcknowledgedChangeLogId`, so one dismissal per announcement per account is the whole cost.
+
+**Follow-up 2026-08-28 — the one remaining epoch, found by audit.** #593 left a stated gap: call sites that neither route through `_probe_selector_cascade` nor sit behind a navigation gate. All 73 click/fill/press sites in the UI transports were then enumerated and classified, and exactly one survives the "can a modal actually land here?" test: the **image batch** loop's per-prompt boundary. A batch dismisses overlays once during setup, so from prompt 2 on the settings clicks are the first act after a multi-second generation wait on a page that never navigates. That one failed *silently* rather than loudly — `_open_gen_settings_panel` returns `False` when nothing matches and the caller falls back to Flow's current defaults, so a modal that mounted during prompt 1 generated prompt 2 at the wrong aspect/count. It now runs the same `_require_unblocked` check the navigation epochs use. Every other unguarded site fails loudly (exit 23 with a probe name and a screenshot, or an `overlay_postmortem` warning), which is why they are deliberately left unguarded rather than pre-guarded on a hunch.
+
 ---
 
 ### No in-CLI quota visibility
@@ -901,6 +911,15 @@ names the pinning case. Retrying *immediately* during a pin is futile — wait a
 while or switch `--profile`. Recorded as the #299 PR-B predict-gate evidence:
 retry loops must never key off the pinned signature.
 
+**Update 2026-08-28 ([#595](https://github.com/ffroliva/gflow-cli/issues/595)) — images
+now reach this fail-fast by default.** Two accounts flipped agentic on 2026-08-27 and a
+plain `gflow image t2i` failed on both, because `auto` bound whatever rendered and the
+agentic driver cannot satisfy an image request (either `image_mode_tab` selector drift or
+a `WireFormatError` about video bytes — neither naming the cause). `auto` now resolves to
+`classic` for images too, so a pinned account gets the exit-28 abort described above
+instead of a mid-run failure, and `GFLOW_CLI_PREFER_CLASSIC=1` is no longer the
+workaround anyone needs to discover.
+
 ### Auth verification depends on Google's NextAuth session endpoint
 
 - **Status:** Mitigated · **Severity:** Low (degrades fail-closed) · **Affects:** issue #15 fix onward · **Tracked:** issue #15

{gflow_cli-0.61.0 → gflow_cli-0.62.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gflow-cli
-Version: 0.61.0
+Version: 0.62.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.61.0/website → gflow_cli-0.62.0}/docs/CONFIGURATION.md

@@ -345,7 +345,7 @@ GFLOW_CLI_HISTORY_PROMPTS=redacted gflow image t2i "confidential brief"
 
 **What:** Which Flow UI arm to use for generation. Flow serves a **classic** composer (hard crop/aspect controls) or an **agentic** chat cohort, server-assigned and flapping per page load ([#299](https://github.com/ffroliva/gflow-cli/issues/299)).
 **Values:**
-- `auto` (default) — bind whatever the composer renders.
+- `auto` (default) — no arm was asked for, so gflow **requires `classic`** ([#595](https://github.com/ffroliva/gflow-cli/issues/595)): classic is the arm that can satisfy a generation request, and it is recovered first, so this only aborts when the arm is genuinely pinned. Before v0.62.0 `auto` bound whatever rendered, which put an account in Flow's agentic cohort on a driver that cannot produce an image — failing mid-run as `image_mode_tab` selector drift or a `WireFormatError` about video bytes. Agentic is still reachable, but only by name (`--ui-mode agentic`) or by need (`-i`).
 - `classic` — require the classic composer (hard aspect controls). gflow switches to it, re-probes to verify, and if the arm is still agentic **aborts before submitting** with `UiModeUnavailableError` (**exit 28**) — no credits spent.
 - `agentic` — require the agentic chat surface (needed for `-i` agent instructions). gflow switches to it, verifies, and aborts (exit 28) if it can't be reached.
 **Default:** `auto`

{gflow_cli-0.61.0 → gflow_cli-0.62.0}/docs/INDEX.md

@@ -145,12 +145,12 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"Two gflow runs on the same profile — can the second one wait instead of failing (exit 11)?"** → [CONFIGURATION § GFLOW_CLI_LEASE_WAIT_SECONDS](CONFIGURATION.md#gflow_cli_lease_wait_seconds) (v0.56.0 opt-in bounded wait)
 **"How do I silence the 'newer version on PyPI' stderr notice?"** → [CONFIGURATION § GFLOW_CLI_UPDATE_CHECK](CONFIGURATION.md#gflow_cli_update_check) (`0` disables; auto-skipped in CI and for editable installs)
 **"How do I run the MCP server so an agent can't spend credits?"** → [CONFIGURATION § GFLOW_MCP_NO_SPEND](CONFIGURATION.md#gflow_mcp_no_spend) + [MCP § Option A2](MCP.md#option-a2-read-only-server) (`gflow mcp run --no-spend` / `GFLOW_MCP_NO_SPEND=1`; v0.57.0 — both generate tools go unregistered, not merely refused)
-**"Which Flow UI arm does a video run require, and why did it exit 2 or 28?"** → [CONFIGURATION § GFLOW_CLI_UI_MODE](CONFIGURATION.md#gflow_cli_ui_mode) (v0.57.0 — video is classic-only: `auto` ≡ `classic`, explicit `agentic` exits 2, unreachable classic aborts pre-submit with exit 28, $0)
+**"Which Flow UI arm does a run require, and why did it exit 2 or 28?"** → [CONFIGURATION § GFLOW_CLI_UI_MODE](CONFIGURATION.md#gflow_cli_ui_mode) (`auto` ≡ `classic` for **both** images and video — video since v0.57.0/#299, images since #595; unreachable classic aborts pre-submit with exit 28, $0; explicit `agentic` on video exits 2)
 **"A gflow command hangs / fails — where do I start?"** → [DEBUGGING § Quick reference](DEBUGGING.md#quick-reference)
 **"A command failed — where is the incident bundle and what's in it?"** → [DEBUGGING § Automatic incident bundles](DEBUGGING.md#automatic-incident-bundles) (layout, triggers, review-before-sharing); privacy boundaries: [SECURITY § Automatic incident bundles](SECURITY.md#automatic-incident-bundles-gflow_cli_incident_capture-default-on); disable via [CONFIGURATION § GFLOW_CLI_INCIDENT_CAPTURE](CONFIGURATION.md#gflow_cli_incident_capture)
 **"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.61.0](LIVE_VERIFICATION_v0.61.0.md) (**#539 video-model refusal + #586 image-model refusal and server-side attribution, verified 2026-08-26/27 on profile `denon82`, ONE Veo generation total** — the video fix was proven by a **zero-credit A/B against the stashed pre-fix source running on live Flow**: the old code returned SELECTED for `veo-lite-lp`, a model Flow does not offer to this account, and for a deliberately ambiguous selector matching 3 entries; the new code refuses both with exit 18 naming what Flow offered. Model selection happens before submit, so refusals cost nothing and the A/B was free. The happy path still generates: `--model omni-flash` → exit 0, a real 2.2 MB `ftypisom` mp4, catalog recording `omni_flash`. Two items are recorded as NOT verified rather than omitted: three of #584's four navigation-settle sites were never exercised [no bearer refresh occurred in these runs], and #582's canary self-re-exec has its first real exercise tonight. Also falsified: #539's recorded note that the video picker uses a different trigger — the two constants are byte-identical strings, and the repeated empty menu captures were the capture's own fault.) · previous: [LIVE_VERIFICATION_v0.60.0](LIVE_VERIFICATION_v0.60.0.md)
+**What was actually live-verified for the latest release?** → latest: [LIVE_VERIFICATION_v0.62.0](LIVE_VERIFICATION_v0.62.0.md) (**#595 `auto` ≡ `classic` for images, verified 2026-08-28 on profile `ci-probe` — an account Flow had moved to the agentic cohort the day before — at ZERO Veo credits.** With no flags and no env vars the run logged `ui_driver.ui_mode.attempt_exit_agent` → `ui_driver.bound mode=classic ui_mode=classic` and generated a real 768x1376 JPEG (exit 0); the day before, the identical command on the same account bound `auto`→`agentic` and failed. The same log independently closed **#183**: `mode_switch_trigger` and `image_mode_tab`, the selectors it reported as unfindable, both matched. #591 was proven against the real 500-row catalog — **0** occurrences of the string `"None"`, 31 proper JSON `null`s, over a catalog holding 119 NULL-bearing rows. #592 shows exactly one `client.account_locale_cached` per command. Three items are recorded as NOT verified rather than omitted: the exit-28 abort on a *pinned* agentic account, the #597 batch inter-prompt guard, and any fresh announcement modal — the last two because all three accounts have already acked the current changelog, so no modal can be raised until Google ships the next one.) · previous: [LIVE_VERIFICATION_v0.61.0](LIVE_VERIFICATION_v0.61.0.md) (**#539 video-model refusal + #586 image-model refusal and server-side attribution, verified 2026-08-26/27 on profile `denon82`, ONE Veo generation total** — the video fix was proven by a **zero-credit A/B against the stashed pre-fix source running on live Flow**: the old code returned SELECTED for `veo-lite-lp`, a model Flow does not offer to this account, and for a deliberately ambiguous selector matching 3 entries; the new code refuses both with exit 18 naming what Flow offered. Model selection happens before submit, so refusals cost nothing and the A/B was free. The happy path still generates: `--model omni-flash` → exit 0, a real 2.2 MB `ftypisom` mp4, catalog recording `omni_flash`. Two items are recorded as NOT verified rather than omitted: three of #584's four navigation-settle sites were never exercised [no bearer refresh occurred in these runs], and #582's canary self-re-exec has its first real exercise tonight. Also falsified: #539's recorded note that the video picker uses a different trigger — the two constants are byte-identical strings, and the repeated empty menu captures were the capture's own fault.) · previous: [LIVE_VERIFICATION_v0.60.0](LIVE_VERIFICATION_v0.60.0.md)
 **"Was the playwright upper bound raised, and on what evidence?"** → [LIVE_VERIFICATION_playwright_1.61](LIVE_VERIFICATION_playwright_1.61.md) (**`>=1.59.0,<1.60.0` → `>=1.61.0,<1.62.0` verified 2026-08-05, 1 Imagen + 1 Veo credit** — the 2026-08-03 regression that motivated the bound does NOT reproduce on 1.61.0: a live `i2v` drove the full chain with `image_uploaded status=200` → `frame_attached` → `generate_captured status=200` with `startImage` parsed, where **1.62.0 hung silently at exactly that upload step**; live `i2i` local-ref attach passed outright [96.7s]. **1.62.0 stays excluded** — never root-caused. Also found, A/B-proven pre-existing on BOTH 1.59.0 and 1.61.0: Flow dropped the duration-tab UI, so **`--duration` is currently broken for i2v** — `UiSelectorDriftError` fires correctly [refusing rather than silently accepting Flow's default, #288] but the selector needs re-deriving; that is why the i2v proof was driven via the CLI without `--duration`, and Flow's own server-side `PUBLIC_ERROR_VIDEO_GENERATION_TIMED_OUT` means no finished mp4 is claimed).
 **"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. Pre-capture research recons: [ASSET_TAGGING_RECON](ASSET_TAGGING_RECON.md) (`@`-mention asset tagging — shipped in v0.40.0, see [LIVE_VERIFICATION_v0.40.0](LIVE_VERIFICATION_v0.40.0.md)).
 **"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)

gflow_cli-0.62.0/docs/LIVE_VERIFICATION_v0.62.0.md

@@ -0,0 +1,115 @@
+# Live verification — v0.62.0
+
+Every claim below was **observed**. Claims that could not be observed are stated
+as such in §6, not omitted.
+
+## Environment
+
+| | |
+|---|---|
+| Date | 2026-08-28 |
+| Profile | `ci-probe` (one of the two accounts Flow moved to the **agentic** cohort on 2026-08-27) |
+| Code under test | `develop` @ `fb8b346` (all five release commits merged; the version bump itself came after, so log lines read `cli_version 0.61.0`) |
+| Veo credits spent | **0** — this release's user-facing changes are image-path and read-only surfaces |
+
+## 1. #595 — `--ui-mode auto` requires the classic arm (the headline change)
+
+The whole point of the fix is what happens with **no flags and no env vars**, which
+is what a new user gets:
+
+```bash
+gflow --verbose image t2i "a single red cube on a white studio table, soft light" --profile ci-probe
+```
+
+The decisive pair of events:
+
+```json
+{"event": "ui_driver.ui_mode.attempt_exit_agent"}
+{"mode": "classic", "ui_mode": "classic", "event": "ui_driver.bound"}
+```
+
+`ui_mode` is **`classic`** with nothing on the command line. The day before, the same
+command on this same account logged `ui_mode=auto` → `mode=agentic` and failed.
+
+Five-layer ledger for the generation that followed:
+
+| Layer | Observed |
+|---|---|
+| File count | 1 file in `~/Downloads/gflow-cli/images/2026-08-28/` |
+| Magic bytes | `ff d8 ff e0` + `JFIF` at offset 6 — a real JPEG, not an HTML error page |
+| Size / dimensions | 418 079 bytes, **768x1376** (the requested portrait 9:16) |
+| Structlog invariants | `mode_switch_trigger` matched → `image_mode_tab` matched → `image_mode_entered` → `image_model_selected NARWHAL` → `aspect_ratio_set 9:16` → `count_setter_completed 1` → `prompt_submitted` → `batch_response_captured status=200` |
+| User-confirmable artifact | `f0f5ef51-6a45-4c0c-a146-103f18ce9fba_1.jpg`, seed 294067, exit **0** |
+
+`mode_switch_trigger` and `image_mode_tab` both matching is independently the
+evidence that closed **#183**, which reported those exact selectors as unfindable.
+
+## 2. #591 — a NULL column no longer reads back as the string `"None"`
+
+Run against the **real catalog** (not a fixture), 500 rows:
+
+```bash
+gflow data list images --limit 500 --json
+```
+
+| | count |
+|---|---|
+| rows returned | 500 |
+| occurrences of the literal string `"None"` | **0** |
+| occurrences of JSON `null` | 31 |
+
+The catalog holds 119 image rows with a NULL in `model` / `aspect_ratio` /
+`flow_project_id`, so the null path is genuinely exercised: before the fix those
+rows emitted the four-character string `"None"`, indistinguishable from a real value.
+
+## 3. #592 — the account-locale probe runs once per profile
+
+From the same run's log:
+
+```json
+{"locale": null, "settle_skipped": true, "event": "client.account_locale_cached"}
+```
+
+Exactly **one** `client.account_locale_cached` event for the whole command, and both
+navigation settles report `settle_skipped: true` — the per-command ~4 s probe is gone.
+
+## 4. `gflow project list` / `project show` (the release's new feature)
+
+Both are read-only and credit-free. `project list --limit 3` returned the project
+created by §1 with a correct rollup (`IMG 1`, `VID 0`), and `project show` on that id
+returned title, profile, source `generated`, creation timestamp, and a working Flow URL:
+
+```
+Project ID: fdb68253-21a5-4d99-a5f5-091aa2a1de17
+Title:      a-single-red-cube-on-a-white-studio-tabl
+Profile:    ci-probe
+Source:     generated
+URL:        https://labs.google/fx/tools/flow/project/fdb68253-21a5-4d99-a5f5-091aa2a1de17
+```
+
+Cross-checked against §1: the id, the profile and the image count all agree with the
+generation that produced them.
+
+## 5. #593 — the announcement-modal fix
+
+Verified live in the previous cycle (2026-08-27, recorded on PR #594): the ack POST
+`videoFx.setLastAcknowledgedChangeLogId` → 200 fired at **+23 s**, well after the
+~3 s navigation gate, which is the attribution proving the probe-level guard — not the
+boundary dismissal — cleared it. In **this** release's runs the overlay path is
+silent (`0` overlay events in the §1 log), which is the correct outcome: all three
+accounts have already acknowledged the current announcement.
+
+## 6. NOT verified this cycle — stated, not omitted
+
+- **The exit-28 abort on a genuinely pinned agentic account (#595).** `ci-probe`
+  rendered classic on this load. The cohort is server-assigned and flaps, so a pin
+  cannot be provoked on demand. The abort path is the same `get_ui_driver` code #299
+  shipped for video and is covered offline, but it has not been observed live for
+  images.
+- **The #597 batch inter-prompt guard.** Reproducing it needs an announcement modal
+  to mount *during* a multi-prompt batch generation. All three accounts have acked
+  the current announcement, so no modal can be raised at all until Google ships the
+  next one. Covered offline against the captured markup
+  (`tests/fixtures/changelog_modal_page.html`, real headless Chromium) plus mocks.
+- **A fresh announcement modal end-to-end.** Same reason: nothing to dismiss until
+  Google ships the next changelog.

{gflow_cli-0.61.0/website → gflow_cli-0.62.0}/docs/MCP.md

@@ -82,7 +82,7 @@ Both Click CLI (`src/gflow_cli/cli.py`) and MCP Server (`src/gflow_cli/mcp/`) ar
 The server registers three protocol surfaces:
 
 ### Tools (Executable actions)
-* `gflow_generate_image(prompt, model, aspect, count, seed, reference_images, tools, profile, project, project_name, instructions, ui_mode, output, wait)`: 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. `ui_mode` selects the Flow UI arm (`auto`/`classic`/`agentic`, mirroring CLI `--ui-mode`, matched case-insensitively); passing `instructions` forces `agentic` automatically, so `ui_mode="classic"` + `instructions` is a hard conflict rather than a silent drop. An unknown value returns a 400 problem-details envelope. See [CONFIGURATION § GFLOW_CLI_UI_MODE](CONFIGURATION.md#gflow_cli_ui_mode).
+* `gflow_generate_image(prompt, model, aspect, count, seed, reference_images, tools, profile, project, project_name, instructions, ui_mode, output, wait)`: 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. `ui_mode` selects the Flow UI arm (`auto`/`classic`/`agentic`, mirroring CLI `--ui-mode`, matched case-insensitively). Since [#595](https://github.com/ffroliva/gflow-cli/issues/595) `auto` means "no arm was asked for" and **resolves to `classic`** — the arm that can satisfy an image request — so an account in Flow's agentic cohort aborts pre-submit (exit-28 equivalent envelope, zero credits) instead of failing mid-run with selector drift or video bytes; the agentic arm is bound only when named. Passing `instructions` forces `agentic` automatically, so `ui_mode="classic"` + `instructions` is a hard conflict rather than a silent drop. An unknown value returns a 400 problem-details envelope. See [CONFIGURATION § GFLOW_CLI_UI_MODE](CONFIGURATION.md#gflow_cli_ui_mode).
 * `gflow_generate_video(prompt, mode, aspect, initial_frame, end_frame, reference_images, model, duration, count, tools, profile, project, project_name, ui_mode, output, wait)`: 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. Since v0.58.0 (#529) the CLI and MCP surfaces are unified for i2v frames: the UUID keeps its identity and is enriched with the catalog's recorded display name plus an integrity-verified local fallback, so the transport prefers **selecting the exact asset in the project's media picker** (no duplicate upload) and re-uploads the recorded local file only when the tile is unreachable — and only if its byte count/SHA-256 still match. A UUID that isn't in your local asset catalog is rejected up front with a clear "Reference Not Found" error; a catalogued asset with neither a display name nor a verified local file gives a "Reference Not Usable" error (re-generate it or pass a local path). `r2v` UUID refs are resolved to the recorded local file for upload. `ui_mode` selects the Flow UI arm (#299 PR-A, mirroring CLI `--ui-mode`) and **applies to every mode of this tool, including `r2v`** — unlike the CLI, where `video r2v`/`chain` have no flag and follow the env-only path. Video generation has **only a classic driver**, so `auto` ≡ `classic`: both verify the classic editor pre-submit and abort before spending credits if it is unreachable. `ui_mode="agentic"` is rejected with a 400 problem-details envelope, because no agentic video driver exists yet. Values are matched case-insensitively. (MCP tools return envelopes, never process exit codes — the CLI equivalents of these aborts are exit 28 and exit 2 respectively.) See [CONFIGURATION § GFLOW_CLI_UI_MODE](CONFIGURATION.md#gflow_cli_ui_mode).
 * `gflow_auth_status(profile)`: Credit-free, non-interactive Flow session probe (#497) — wraps the same fail-closed `verify_flow_profile` check as `gflow auth status`. Returns `{"status": "authenticated", "profile", "user_email"}` or a problem-details error with a `remediation_hint`; a `verification_error` outcome means a network/endpoint problem, which re-login does not fix. Call it before a generation tool to fail fast on dead auth (the queue is async — without it, an auth failure surfaces only later from the daemon). Login/logout remain CLI-only (genuinely interactive).
 * `gflow_list_projects(profile, limit, offset)`: Queries the SQLite catalog for recent generation folders, paginated — the response carries `count` (rows in this page), `offset`, `has_more`, and `next_offset` (pass it back as `offset` for the next page; `null` on the last page).

{gflow_cli-0.61.0 → gflow_cli-0.62.0}/docs/USAGE.md

@@ -196,7 +196,9 @@ Options:
   --ui-mode [auto|classic|agentic]
                             Require a Flow UI arm: classic (hard aspect
                             controls) / agentic (chat surface; forced by -i) /
-                            auto (default). Aborts exit 28 if unreachable.
+                            auto (default) — auto resolves to classic, the only
+                            arm that can satisfy an image request (#595).
+                            Aborts exit 28 if unreachable.
                             Single-prompt only; batch uses GFLOW_CLI_UI_MODE.
   --profile NAME            Profile name (overrides default).
 ```
@@ -1508,7 +1510,7 @@ shell scripts can branch on the failure mode without parsing stderr.
 | `20` | `FrameExtractionError` | Could not extract the last frame for a video chain link | Check the source video downloaded intact; retry the link  |
 | `21` | `ChainPartialError`   | A video chain stopped mid-way; earlier links completed | Resume from the last completed link shown in the error     |
 | `22` | `UpscaleUnavailableError` | 4K upscale is gated to Flow **Ultra** accounts (HTTP 403) | Use `--scale 2k`, or upgrade the Flow plan                |
-| `23` | `UiSelectorDriftError` | A Flow editor control could not be located — Google changed the frontend (issues #183, #493) | Update gflow-cli; file a bug with the probe name + the diagnostics JSON / debug screenshot referenced in the error message, plus the incident bundle's `report.md` when one was written |
+| `23` | `UiSelectorDriftError` | A Flow editor control could not be located — Google changed the frontend (issues #183, #493) — **or** a blocking announcement overlay survived dismissal, so no control below it can be clicked (probe `overlay_close_button`, #593) | Update gflow-cli; file a bug with the probe name + the diagnostics JSON / debug screenshot referenced in the error message, plus the incident bundle's `report.md` when one was written. For `overlay_close_button`: open the project once in Chrome and dismiss the announcement — the dismissal persists on your account |
 | `24` | `BrowserEngineUnavailableError` | `GFLOW_CLI_BROWSER_ENGINE=patchright` but the engine is not installed | `pip install 'gflow-cli[patchright]'`, or unset `GFLOW_CLI_BROWSER_ENGINE` |
 | `25` | `FlowAgentUiError`    | The profile is on Flow's Agentic UI cohort and the classic media panel is unrecoverable for this operation | Rare since v0.38.0 (#332): the mode controller reliably recovers agentic→classic, so first retry with `--ui-mode classic`; if it persists, see KNOWN_ISSUES on the agentic cohort |
 | `26` | `MediaAttributionError` | Generated media could not be reliably attributed to this request (issue #281) | Re-run; a dedicated project with fewer pre-existing assets avoids the ambiguity |

{gflow_cli-0.61.0 → gflow_cli-0.62.0}/docs/superpowers/specs/2026-08-21-selector-registry-design.md

@@ -102,6 +102,16 @@ established, not merely plausible.**
 
 ### 2.4 Locale is account-driven
 
+> **Superseded 2026-08-27 (#587).** The sentence below — *"Passing `locale="en"` to
+> `project_editor_url()` still served `/fx/pt/` in Portuguese"* — is the **inverse** of
+> what `scripts/dev/spike_locale_poison.py` measures: Flow serves whatever segment it
+> is asked for and never corrects a wrong-but-valid one. The original observation was
+> almost certainly the ineffective launch-context `locale="en-US"` noted in the
+> corollary below — a Chrome kwarg, never a URL segment — rather than the URL
+> builder, which does reduce `en-US` to `/fx/en/`. §2.4's *conclusion* (account-driven) stands on the
+> authed/unauthed contrast; the mechanism sentence does not. Do not use it to argue
+> that navigating to a cached segment is safe — that design was built and rejected.
+
 Passing `locale="en"` to `project_editor_url()` still served `/fx/pt/` in Portuguese.
 The *evidence* for account-attribution is the authed/unauthed contrast at identical
 `Accept-Language` and IP: **authed → `pt`, unauthed → `en`, cookie the only variable**