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

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

@@ -123,11 +123,20 @@
 # `patchright install chromium`. Unset to revert to the default playwright engine.
 # GFLOW_CLI_BROWSER_ENGINE=playwright
 
-# Try to force the Classic Flow UI mode for image generation by clicking the Agent toggle pill
-# if the page mounts in Agentic mode. This ensures deterministic aspect ratio controls.
-# If the page cannot be switched back to Classic, falls back to Agentic mode.
+# Which Flow UI arm a command needs: auto (bind whatever renders) | 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
+# reached. -i instructions force agentic automatically. See docs/CONFIGURATION.md.
+# GFLOW_CLI_UI_MODE=auto
+
+# DEPRECATED — use GFLOW_CLI_UI_MODE=classic. true maps to ui_mode=classic, but the
+# old silent agentic fallback is gone: a classic-required run now aborts (exit 28).
 # GFLOW_CLI_PREFER_CLASSIC=false
 
+# DEPRECATED — use GFLOW_CLI_UI_MODE=agentic. true maps to ui_mode=agentic.
+# GFLOW_CLI_FORCE_AGENT_UI=false
+
 
 # BCP-47 locale tag passed to Playwright's launch `locale=` parameter
 # (controls Accept-Language only — Chrome's UI language is forced to

{gflow_cli-0.33.0 → gflow_cli-0.34.0}/AGENTS.md

@@ -59,6 +59,7 @@ Or invoke the wrapper: `/gflow:check`.
 - Structured logging only (`structlog`) — **never** raw `print()` or `import logging` in `src/`.
 - Errors as RFC 9457 Problem Details with stable per-class exit codes (3–27, e.g. 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`, 22 `UpscaleUnavailableError`, 25 `FlowAgentUiError`). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping.
 - 100-char line length, `ruff` configured. Imports sorted by `ruff` (isort rules).
+- **YAGNI / least-code**: prefer the smallest change that works. No speculative abstractions (interface/factory with one implementation), no config or flags nobody sets, no dead constants/helpers, no reinventing the stdlib. Review carries this as its own lens — the **D14 over-engineering** dimension of [`pr-council-review`](skills/pr-council-review/SKILL.md) (baseline, always runs). Its rubric is portable; the `ponytail` plugin (see CONTRIBUTING) is an optional accelerant, not a dependency.
 - **MCP & CLI Schema Symmetry**: Any updates or additions to user-facing CLI command parameters (e.g., `gflow image t2i`, `gflow video`) must be mirrored in the corresponding MCP tool definitions. Never add option/argument fields to Click commands without updating the MCP server implementation. This symmetry is enforced programmatically in CI via `tests/mcp/test_cli_parity.py` (every CLI leaf command needs a mapped MCP tool or an explicit, reasoned exemption) plus the schema checks in `tests/mcp/test_server.py`.
 
 ## PR instructions

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

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.34.0] — 2026-07-12
+
+### Added
+
+- **`--ui-mode` / `GFLOW_CLI_UI_MODE` — the CLI can drive the Flow UI arm the command needs, both directions (#299).** Flow serves a **classic** composer or an **agentic** chat cohort, server-assigned and flapping per page load. Before generating, gflow now determines the **required** arm, switches to it as a prerequisite (classic↔agentic DOM toggle), **verifies** via a DOM re-probe, and — if the arm is unreachable — aborts *before* submitting with the new `UiModeUnavailableError` (**exit 28**, retryable), no credits spent. Values: `auto` (default; bind whatever renders), `classic` (require the hard aspect controls), `agentic` (require the chat surface). The required arm is also **inferred**: agent instructions (`-i`) are agentic-only, so they force agentic — closing the #267 gap where `-i` on a classic roll was *silently dropped* (now it either binds agentic or fails fast). Exposed as the **`--ui-mode` flag** on `gflow image t2i` / `i2i` (single-prompt; batch uses the env var) and the **`ui_mode` param** on the `gflow_generate_image` MCP tool; `--ui-mode classic` + `-i` is a fail-fast usage error. Grounded in the #299 spike (`docs/superpowers/spikes/2026-07-12-ui-cohort-backend-config.md`). Applies to every image generation via the shared driver seam. Honest ceiling: a server-side experiment can pin the arm, in which case the switch can't win — the abort still saves the credits.
+
+### Changed
+
+- **`GFLOW_CLI_PREFER_CLASSIC` and `GFLOW_CLI_FORCE_AGENT_UI` are deprecated (#299)** in favor of `GFLOW_CLI_UI_MODE=classic` / `=agentic` (both still work, mapping to the new modes with a `DeprecationWarning`). **Behavior change:** the old `prefer_classic` silent fallback to agentic when the classic toggle was unavailable is gone — a classic-required run now aborts with exit 28 instead. Pipelines that relied on "always yields a file" from `PREFER_CLASSIC=1` must handle exit 28 (retry / switch profile / `GFLOW_CLI_UI_MODE=agentic`).
+
 ## [0.33.0] — 2026-07-12
 
 ### Added
@@ -1951,7 +1961,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.33.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.34.0...HEAD
+[0.34.0]: https://github.com/ffroliva/gflow-cli/compare/v0.33.0...v0.34.0
 [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

{gflow_cli-0.33.0 → gflow_cli-0.34.0}/CONTRIBUTING.md

@@ -102,6 +102,19 @@ pip install pre-commit && pre-commit install
 
 The `.pre-commit-config.yaml` already ships ruff and the hygiene gate.
 
+### Review lenses (over-engineering matters)
+
+`gflow-cli` values **YAGNI / least-code** (see [AGENTS.md § Code style](AGENTS.md)):
+the smallest change that works, no speculative abstractions, no dead code. This is a
+first-class review dimension — **D14 over-engineering** in
+[`pr-council-review`](skills/pr-council-review/SKILL.md), which always runs and carries
+its own portable rubric.
+
+Optionally, the `ponytail` Claude Code plugin (from the plugin marketplace) encodes
+exactly this review taste — `/ponytail-review` audits a diff for over-engineering. It's a
+**recommended, not required** accelerant: the D14 rubric applies with or without it, so no
+contributor is blocked for lacking the plugin.
+
 ### SonarCloud quality gate
 
 On top of the six gates, CI runs a **SonarCloud** analysis whose quality gate must be

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

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

@@ -231,13 +231,26 @@ GFLOW_CLI_HISTORY_PROMPTS=redacted gflow image t2i "confidential brief"
 **Reverting:** unset the variable (or set `playwright`) — the default path is byte-identical to a build without this feature, with no profile migration.
 **Security note:** the `patchright` extra ships a *patched Chromium driver* that handles your live Google session cookies; it is exact-pinned and treated as a security-review-required dependency. See [SECURITY.md § Dependencies](SECURITY.md).
 
-### `GFLOW_CLI_PREFER_CLASSIC`
+### `GFLOW_CLI_UI_MODE`
 
-**What:** Try to force the Classic Flow UI mode for image generation by clicking the Agent toggle pill if the page mounts in Agentic mode.
-**Values:** `true` | `false`
-**Default:** `false`
-**Why use it:** The Agentic UI cohort (conversational chat) treats requested aspect ratios as a soft prompt hint, which can result in inconsistent aspect ratios (e.g. producing landscape when portrait 9:16 was requested). Exposing this setting allows callers to opt into switching the UI back to Classic mode where aspect ratios are enforced deterministically (via hard Flow crop controls).
-**Fallback:** If the page cannot be switched back to Classic (e.g., in a forced A/B cohort where the toggle is not available), the driver gracefully falls back to Agentic mode rather than blocking execution.
+**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.
+- `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`
+**How it works:** before each generation, gflow determines the required arm, clicks the classic↔agentic toggle as a **prerequisite**, **verifies** with a DOM re-probe, then binds — or fails fast. The required arm is also **inferred**: `-i` instructions are agentic-only, so they force `agentic` automatically (and `--ui-mode classic` + `-i` is a hard conflict, not a silent drop).
+**Why `classic`:** the agentic cohort treats aspect ratio as a soft prompt hint (portrait 9:16 can come back landscape). `classic` enforces it or fails fast instead of silently degrading.
+**Retry note:** the cohort flaps per load, so an exit-28 abort is **retryable** — a re-run often lands the wanted arm. A server experiment can pin the arm, in which case it's unreachable from the client (the abort still saves the credits).
+**Supersedes:** `GFLOW_CLI_PREFER_CLASSIC` and `GFLOW_CLI_FORCE_AGENT_UI` (below).
+
+### `GFLOW_CLI_PREFER_CLASSIC` *(deprecated — use `GFLOW_CLI_UI_MODE=classic`)*
+
+**Deprecated** in favor of [`GFLOW_CLI_UI_MODE`](#gflow_cli_ui_mode). `true` now maps to `ui_mode=classic` (emits a `DeprecationWarning`). **Behavior change:** the old silent fallback to agentic when the toggle was unavailable is gone — a classic-required run now **aborts with exit 28** instead of producing an agentic-cohort result. `GFLOW_CLI_UI_MODE` (and `--ui-mode`) take precedence when both are set.
+
+### `GFLOW_CLI_FORCE_AGENT_UI` *(deprecated — use `GFLOW_CLI_UI_MODE=agentic`)*
+
+**Deprecated** in favor of [`GFLOW_CLI_UI_MODE`](#gflow_cli_ui_mode). `true` maps to `ui_mode=agentic` (emits a `DeprecationWarning`). `-i` instructions already force agentic automatically, so this is rarely needed explicitly.
 
 ### `GFLOW_CLI_LOCALE`
 

{gflow_cli-0.33.0 → gflow_cli-0.34.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.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)
+**"What was actually live-verified for the latest release?"** → latest: [LIVE_VERIFICATION_v0.34.0](LIVE_VERIFICATION_v0.34.0.md) (**#299 `--ui-mode` gate proven live, ZERO credits** — drove `get_ui_driver` directly over 4 real editor loads, never generated: bidirectional switch works [classic→agentic via `_force_agent_mode`, agentic→classic via `_exit_agent_mode`, each DOM-reverified], `agentic`-when-already-agentic is idempotent, and a timed-out toggle → **exit-28 fail-fast before submission**; deprecation behavior-change [`prefer_classic`→exit 28] confirmed). Prior: [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.34.0/docs/LIVE_VERIFICATION_v0.34.0.md

@@ -0,0 +1,49 @@
+# Live verification — v0.34.0 (2026-07-12)
+
+The release's one user-facing feature — the `--ui-mode` / `GFLOW_CLI_UI_MODE`
+ensure-required-mode gate (#299) — exercised against live Flow on the merged
+`develop` tip, profile `denon82`. **Zero credits:** the production
+`get_ui_driver(page, ui_mode=…)` gate was driven directly over 4 real editor
+loads; generation was **never** called.
+
+Ledger adapted for a control-plane feature (no generated artifact): exit-code /
+raise outcome · structlog switch invariants · observed DOM arm transition
+(before → after) · a re-runnable probe. `scratchpad/ui_mode_gate_e2e.py`.
+
+## What was confirmed (all four gate behaviors)
+
+| Requested | Live mount | Switch attempt (structlog) | Outcome |
+|---|---|---|---|
+| `auto` | agentic | (none) | binds `agentic` (whatever renders) |
+| `agentic` | classic | `ui_driver.ui_mode.attempt_force_agent` → `ui_automation.agent_mode_forced activated=True` | arm before=classic → **after=agentic**, binds `agentic` |
+| `classic` | agentic | `ui_driver.ui_mode.attempt_exit_agent` → `ui_automation_video.exited_agent_mode` | arm before=agentic → **after=classic**, binds `classic` |
+| `agentic` | agentic | `ui_automation.agent_mode_already_active` | idempotent no-op, binds `agentic` |
+| `classic` | agentic (toggle click **timed out**: `agent_toggle_probe_failed`) | switch did not take | **`UiModeUnavailableError` — exit 28 fail-fast** (`requested=classic`), before any submission |
+
+- **Bidirectional switch proven live** — classic→agentic (`_force_agent_mode`)
+  and agentic→classic (`_exit_agent_mode`), each verified by a DOM re-probe.
+- **Fail-fast proven live** — when the toggle genuinely could not reach the
+  required arm, the gate raised exit 28 *before* submitting, spending no credits
+  (the money-shot: the honest terminal state fires on a real unreachable arm).
+- **Inference / flag / MCP surfaces** — covered by 1529 automated tests
+  (flag→request threading, both CLI guards, worker payload→request); the CLI
+  guards (`--ui-mode classic` + `-i`, `--ui-mode` single-prompt-only) were also
+  smoke-verified at exit 2.
+
+`denon82` rolled agentic on most loads (the current natively-agentic cohort
+behavior), which conveniently exercised both switch directions in one run.
+
+## Behavior-change note (carried from the CHANGELOG)
+
+`GFLOW_CLI_PREFER_CLASSIC` is deprecated → maps to `--ui-mode classic`, and the
+old silent agentic fallback is gone: a classic-required run now aborts with exit
+28 instead of producing an agentic-cohort result. Verified above (the timed-out
+case is exactly that abort).
+
+## Not verified this cycle
+
+- The exit-28 abort's *auto-reload-retry* is intentionally **not implemented**
+  (deferred; see the design note) — today the retry is the user re-running the
+  command. Nothing to verify.
+- Item 3a/3b (agentic driver parity) and item 2 (enforce-via-mutation) are not in
+  this release.

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

@@ -184,6 +184,11 @@ Options:
   -t, --tool NAME[:k=v]     Apply a prompt tool before generating, e.g.
                             `creative-director:style=cinema`. Repeatable; applied
                             per prompt on multi-prompt/batch. See "Prompt tools".
+  --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.
+                            Single-prompt only; batch uses GFLOW_CLI_UI_MODE.
   --profile NAME            Profile name (overrides default).
 ```
 
@@ -1249,6 +1254,7 @@ shell scripts can branch on the failure mode without parsing stderr.
 | `25` | `FlowAgentUiError`    | The profile is on Flow's Agentic UI cohort and the classic media panel is unrecoverable for this operation | Use a Classic-cohort profile; 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 |
 | `27` | `MediaUploadRejectedError` | Flow's upload endpoint refused the input file (`uploadImage` 4xx, issue #287) | Re-encode the image (`ffmpeg -q:v 2 -map_metadata -1`), or reference the asset by its media UUID |
+| `28` | `UiModeUnavailableError` | The Flow UI arm this command required (`GFLOW_CLI_UI_MODE`, or inferred — `-i` forces agentic) couldn't be reached after a switch attempt; aborted before submitting — no credits spent (issue #299) | Retry (the cohort flaps per load); try another `--profile`; or relax `GFLOW_CLI_UI_MODE` |
 | `130`| SIGINT                | User-interrupted (Ctrl-C)                        | —                                                          |
 
 **Exit code 16 — data store / migration error.** Fires when:

gflow_cli-0.34.0/docs/superpowers/spikes/2026-07-12-ui-cohort-backend-config.md

@@ -0,0 +1,87 @@
+# Spike evidence — UI-cohort backend config surface (issue #299 gate)
+
+**Date:** 2026-07-12 · **Verdict: GO (partial) — the UI arm IS a readable, persisted
+backend setting; enforcement is a captured mutation away.** This overturns the
+`AGENT_UI_RECON.md` § Gating conclusion that "there is no client-readable cohort
+signal."
+
+## Method
+
+Automatable half of the #299 spike (H1/H3), zero credits — navigation only, no
+Generate click. `scratchpad/ui_cohort_spike.py`: launched a headless persistent
+Chrome context on `profile_denon82`, cold-loaded the editor
+(`/project/f6caf027…`) **3×**, and per load captured (a) the UI arm via the
+production `detect_ui_mode` probe, (b) the client gating surface (`__NEXT_DATA__`
+pageProps, localStorage, sessionStorage, cookie names), and (c) every network
+response, with bounded JSON bodies for config/preference/RPC-looking URLs.
+
+The recon (2026-06-14) inspected localStorage / cookies / `__NEXT_DATA__` pageProp
+**keys** and correctly found no arm flag there. It did **not** read the **tRPC
+query response bodies** — which is where the arm actually lives.
+
+## Result
+
+- **Arm this session:** `classic` on all 3 headless loads — yet today's earlier
+  CLI e2e (also headless, same profile) hit `agentic`. So the cohort **flaps**;
+  denon82 is **not** permanently agentic.
+- **`GET /api/trpc/videoFx.getUserSettings`** →
+  `{"isAgentModeToggled": false, "isChatPanelOpen": false, "tilesDisplayMode":
+  "grid", "completedOnboardingIds":["AGENT","MODEL"], …}` — a **per-user persisted
+  setting**. `isAgentModeToggled:false` is consistent with the 3 classic loads.
+- **`GET /api/trpc/videoFx.getFlowAppConfig`** → `"agentModeDefaultState":
+  "agent_off"`, plus `"activeExperimentIds":[106077941, 105798603, …]` and a raft
+  of `isXEnabled` feature flags — the app-level default + server experiment list.
+- **`GET /api/trpc/general.fetchUserPreferences`** → history/product-improvement
+  only (no arm).
+- Endpoints seen on cold load are **all GET** (plus a `general.submitBatchLog`
+  telemetry POST). No mode-mutation fired — it only fires on the Agent-pill click.
+
+## Interpretation
+
+The effective arm is best modelled as:
+
+```
+effective_arm  =  experiment_override(activeExperimentIds)   # server, may force agentic
+              ??  user_setting(isAgentModeToggled)           # persisted, client-readable
+              ??  app_default(agentModeDefaultState)          # "agent_off" today
+```
+
+- **H1 — CONFIRMED.** The intended arm is **readable pre-generation** from
+  `getUserSettings.isAgentModeToggled` + `getFlowAppConfig.agentModeDefaultState`
+  / `activeExperimentIds`, via an authenticated in-page `fetch` on the editor we
+  already load. DOM `detect_ui_mode` stays the ground-truth post-render check;
+  the tRPC read gives a *pre-render prediction* + a diagnosable "why".
+- **H2 — STRONGLY INDICATED, not yet captured.** `isAgentModeToggled` is a
+  persisted tRPC-backed setting, so the Agent pill flips it through a mutation
+  (expected `videoFx.setUserSettings` / `updateUserSettings` shape). It does not
+  fire on load, so its exact name/payload needs one pill-click capture.
+- **H3 — residual.** If an entry in `activeExperimentIds` force-assigns agentic,
+  setting `isAgentModeToggled:false` will not override it. Reading still lets us
+  **fail fast** before spending; enforcement is then partial, not guaranteed.
+
+## Decision
+
+**GO into `/gflow:predict`** with this evidence. Recommended scope, in reliability
+order:
+
+1. **Read-and-fail-fast (no mutation needed, ships on H1 alone):** the `--ui-mode`
+   policy (#299 item 1) gains a pre-submission tRPC read of `isAgentModeToggled` /
+   `agentModeDefaultState`; a strict `classic` request aborts cleanly (typed
+   error, zero credits) when the predicted/probed arm is agentic. Deterministic,
+   low-risk.
+2. **Enforce (needs the H2 capture):** replace the best-effort pill-click in
+   `get_ui_driver(prefer_classic=True)` with the captured `setUserSettings`
+   mutation to persist `isAgentModeToggled:false`, then re-probe. Predict-gated
+   (transport change).
+3. **Driver parity (H3 fallback, from #299 item 2):** wire-response attribution +
+   content-type retry — the fix when an experiment pins agentic and enforcement
+   can't win.
+
+## Follow-up needed (manual, blocked on a human at the keyboard)
+
+`gflow-agent-browser-spike/scripts/capture-agent-ui.ps1` already automates the
+capture around a pill click + one generation. Run it on a **pill-rendering
+cohort** (try `promo-denon82` / `test_acc`; toggle the Agent pill) to record the
+mutation endpoint + payload (H2) and, ideally, an `agentic` load to confirm the
+arm correlates with `isAgentModeToggled:true`. That closes H2/H3 before predict
+finalizes item 2.

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

@@ -1,6 +1,6 @@
 [project]
 name = "gflow-cli"
-version = "0.33.0"
+version = "0.34.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.33.0 → gflow_cli-0.34.0}/skills/pr-council-review/SKILL.md

@@ -6,7 +6,7 @@ description: Multi-dimensional LLM council review of an open PR (default) or a l
 
 # `pr-council-review` — PR Council Review skill
 
-Council-driven PR review. Dispatches **5 baseline + N adaptive** parallel reviewers, each scoped to one dimension, each invoking the relevant Claude Code specialized skill (e.g. `security-review`, `code-review`, `verify`), then synthesizes a single consensus verdict.
+Council-driven PR review. Dispatches **6 baseline + N adaptive** parallel reviewers, each scoped to one dimension, each invoking the relevant Claude Code specialized skill (e.g. `security-review`, `code-review`, `verify`), then synthesizes a single consensus verdict.
 
 This skill is the canonical body. The Claude Code slash command at `.claude/commands/gflow/pr-council-review.md` is a thin wrapper that invokes this skill. Non-Claude tools (Gemini CLI / Codex / Cursor / Aider) can consume this SKILL.md directly via their own skill loaders.
 
@@ -117,8 +117,9 @@ Pull in parallel via `ctx_batch_execute`:
 | **D11 — Release-gate compliance** | adaptive | `pyproject.toml`, `src/gflow_cli/__init__.py`, `.github/workflows/`, `release/*` branch |
 | **D12 — BDD step-stub signatures** | adaptive | any path under `tests/features/` |
 | **D13 — Dev / release scripts** | adaptive | any path under `scripts/` |
+| **D14 — Over-engineering / YAGNI** | ✅ baseline (NEW v3) | always |
 
-**Baseline floor is non-negotiable.** D1–D5 ALWAYS run. **Docs-only PRs** (100% paths under `*.md`, `docs/**`, `CHANGELOG.md`, `README.md`, `LICENSE`, `AUTHORS`) → D4 reframes from "test code coverage" to "docs-verification"; D5 still runs unchanged.
+**Baseline floor is non-negotiable.** D1–D5 and D14 ALWAYS run. **Docs-only PRs** (100% paths under `*.md`, `docs/**`, `CHANGELOG.md`, `README.md`, `LICENSE`, `AUTHORS`) → D4 reframes from "test code coverage" to "docs-verification"; D5 still runs unchanged.
 
 ---
 
@@ -145,6 +146,9 @@ Each agent is a `general-purpose` agent (only subagent type that supports arbitr
 | D11 Release-gate | (none — direct config inspection) | |
 | D12 BDD | (none — direct stub-signature inspection) | |
 | D13 Scripts | (none — direct script inspection) | |
+| D14 Over-engineering | `ponytail:ponytail-review` *(soft dep — invoke if installed; else apply the inline YAGNI rubric in § Per-dimension specifics)* | "Should this code exist at all?" — the lens D1–D2 don't cover |
+
+**On the D14 soft dependency:** `ponytail:ponytail-review` is a user-local plugin, not shipped with this repo, so it is **optional** (same pattern as the `agy` extra reviewer in `issue-resolve`). The over-engineering **lens is owned by this skill** (the rubric below); the plugin only accelerates it. An agent without the plugin applies the rubric directly and still produces a D14 verdict — never skip D14 because the plugin is absent.
 
 ### Per-agent prompt skeleton (mandatory v2 changes in bold)
 
@@ -213,6 +217,7 @@ If you are NOT sure a finding is real because it depends on file content, VERIFY
 | D11 | `[[release-back-merge-gap-recovery]]`, `[[wheel-build-sanity-gate]]`, `[[pypi-rejected-filename-reusable]]`, `[[draft-pr-merge-trap]]` |
 | D12 | `[[bdd-stubs-mirror-runtime-signatures]]` |
 | D13 | `[[wheel-build-sanity-gate]]` |
+| D14 | (none mandatory; apply the YAGNI rubric below) |
 
 ### Per-dimension specifics
 
@@ -238,6 +243,13 @@ If you are NOT sure a finding is real because it depends on file content, VERIFY
 - **D11 Release-gate:** version match `pyproject.toml` ↔ `src/gflow_cli/__init__.py` (RED if drift). `[Unreleased]` emptied + new version added. Wheel build clean. Back-merge gap addressed.
 - **D12 BDD:** new `_run_*` kwarg → mirror in `tests/features/_fake_*` stubs (silent TypeError trap).
 - **D13 Scripts:** Windows-clean (memory `[[windows-dev-quirks]]`); release scripts include wheel-build sanity gate.
+- **D14 Over-engineering / YAGNI:** *should this code exist at all?* — the lens D1 (correctness) and D2 (quality) don't ask. If `ponytail:ponytail-review` is installed, invoke it; otherwise apply this rubric directly to the **added** lines:
+  - **Dead / orphaned:** a constant, helper, field, or branch with no live caller after the change (e.g. a module constant only its own definition + a docstring reference now use). Cut it.
+  - **Speculative flexibility:** an interface/factory/abstraction with one implementation, a config knob or flag nobody sets, a parameter only ever passed one value, a layer with one caller. Inline until a second caller exists.
+  - **Reinvented stdlib / platform:** a hand-rolled parser/validator/date-format the standard library or the platform already ships. Name the built-in.
+  - **One-caller indirection:** a wrapper function whose only value is a test seam, when the callee could be patched directly (match how sibling code does it).
+  - **Scaffolding "for later":** boilerplate, placeholder modules, or generality added for a use case not in this PR.
+  - Output the concrete cut per finding (`file:Lline: delete/inline/shrink — what replaces it`) and, when meaningful, `net: -N lines possible`. A single smoke test / `assert`-based self-check is the minimum, never flag it as bloat. RED only for genuinely dead/unreachable code; over-generality is Nice-to-have unless it's load-bearing.
 
 ---
 
@@ -303,7 +315,7 @@ Always end with an `AskUserQuestion`.
 
 > **Provenance:** v1 protocol validated on PR #93 (locale selectors, 2026-05-26). v2 evolved 2026-05-27 after running on PR #95 surfaced two real defects: (a) sub-agents read stale working-tree files producing 5+ false positives (memory `[[pr-council-review-stale-tree-reads]]`), (b) baseline missed memory-hygiene as a dimension. Both fixed in v2.
 
-- Council baseline = 5 dimensions (D1–D5). Adaptive ceiling = D6–D13. Going beyond ~13 adds noise faster than signal — split into two reviews instead.
+- Council baseline = 6 dimensions (D1–D5 + D14 over-engineering). Adaptive ceiling = D6–D13. Going beyond ~14 adds noise faster than signal — split into two reviews instead.
 - Sub-agents are `general-purpose` agents that invoke specialized skills (`security-review`, `code-review`, `verify`, `review`) inside their prompt for dimension-specific capability.
 - The command is **stateless** and **read-only** — concurrent invocations on different PRs don't share data. No `gh pr merge`, no `git push`, no `gh pr close`.
 - **Idempotence:** same PR SHA → comparable verdicts on different days. Drift usually means memory grew new precedents or the mandatory-slug table needs an update.

{gflow_cli-0.33.0 → gflow_cli-0.34.0}/src/gflow_cli/__init__.py

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

{gflow_cli-0.33.0 → gflow_cli-0.34.0}/src/gflow_cli/api/image.py

@@ -30,6 +30,7 @@ if TYPE_CHECKING:
     from collections.abc import Mapping
     from pathlib import Path
 
+    from gflow_cli.config import UiMode
     from gflow_cli.tools.invocation import AppliedTool
 
 __all__ = [
@@ -431,6 +432,9 @@ class GenerateImageRequest:
     # ignored by the body builders. (PR2 §8)
     original_prompt: str | None = None
     tool: AppliedTool | None = None
+    # Requested Flow UI arm (#299) from --ui-mode; None → resolve from
+    # GFLOW_CLI_UI_MODE / default at the transport. Not sent on the wire.
+    ui_mode: UiMode | None = None
 
     def __post_init__(self) -> None:
         if not self.prompt or not self.prompt.strip():

{gflow_cli-0.33.0 → gflow_cli-0.34.0}/src/gflow_cli/api/transports/drivers/factory.py

@@ -30,6 +30,7 @@ import structlog
 
 from gflow_cli.api.transports.drivers.agentic import AgenticFlowUiDriver
 from gflow_cli.api.transports.drivers.classic import ClassicFlowUiDriver
+from gflow_cli.config import UiMode
 
 if TYPE_CHECKING:
     from collections.abc import Iterable
@@ -128,32 +129,60 @@ async def get_ui_driver(
     *,
     timeout_s: float | None = None,
     poll_interval_s: float | None = None,
-    prefer_classic: bool = False,
+    ui_mode: UiMode = UiMode.AUTO,
 ) -> FlowUiDriver:
     """Probe the DOM and return the matching :class:`FlowUiDriver`.
 
+    ``ui_mode`` (issue #299) is the caller's policy:
+      * ``AUTO`` — bind whatever the composer renders.
+      * ``CLASSIC`` — attempt to recover the classic composer (best-effort exit
+        of the agentic chat), then, if the arm is STILL agentic, raise
+        ``UiModeUnavailableError`` (exit 28) **before** any generation — zero
+        credits. The DOM probe is the authority; the arm flaps per load, so a
+        re-run often lands classic.
+      * ``AGENTIC`` — switch the composer to agentic, verify, and raise
+        ``UiModeUnavailableError`` if the arm can't be reached.
+
     Call per generation — the cohort flaps per page load, so a cached driver
     goes stale on the next navigation / batch item.
     """
-    if prefer_classic:
+    # Prerequisite switch: when a specific arm is required and the current one
+    # differs, attempt the DOM toggle for that direction (best-effort — the
+    # server can pin the arm). The re-probe below VERIFIES whether it took.
+    if ui_mode is UiMode.CLASSIC:
         from gflow_cli.api.transports.ui_automation_video import (
             VideoGenerationMixin,
         )
         from gflow_cli.errors import FlowAgentUiError
 
         try:
-            log.info("ui_driver.prefer_classic.attempt_exit_agent")
+            log.info("ui_driver.ui_mode.attempt_exit_agent")
             await VideoGenerationMixin._exit_agent_mode(page)  # type: ignore[reportPrivateUsage]
         except FlowAgentUiError as exc:
-            # Expected: the server-gated agentic ("tune") cohort cannot be exited
-            # client-side. prefer_classic is best-effort (see config docstring), so
-            # falling through to the agentic driver is normal, not a fault.
-            log.info("ui_driver.prefer_classic.cohort_natively_agentic", detail=str(exc))
+            # Expected: a server-pinned agentic cohort cannot be exited
+            # client-side. The verify check below turns this into a clean abort.
+            log.info("ui_driver.ui_mode.cohort_natively_agentic", detail=str(exc))
         except Exception as exc:
-            log.warning("ui_driver.prefer_classic.exit_agent_failed", error=str(exc))
+            log.warning("ui_driver.ui_mode.exit_agent_failed", error=str(exc))
+    elif ui_mode is UiMode.AGENTIC:
+        from gflow_cli.api.transports.ui_automation import UiAutomationTransport
+
+        try:
+            log.info("ui_driver.ui_mode.attempt_force_agent")
+            await UiAutomationTransport._force_agent_mode(page)  # type: ignore[reportPrivateUsage]
+        except Exception as exc:  # noqa: BLE001 - best-effort switch, verified below
+            log.warning("ui_driver.ui_mode.force_agent_failed", error=str(exc))
+
+    # Verify: re-probe the DOM ground truth after any switch attempt.
+    from gflow_cli.errors import UiModeUnavailableError
 
     mode = await detect_ui_mode(page, timeout_s=timeout_s, poll_interval_s=poll_interval_s)
-    log.info("ui_driver.bound", mode=mode)
+    log.info("ui_driver.bound", mode=mode, ui_mode=ui_mode.value)
     if mode == "agentic":
+        if ui_mode is UiMode.CLASSIC:
+            raise UiModeUnavailableError(UiMode.CLASSIC)
         return AgenticFlowUiDriver()
+    # classic rendered
+    if ui_mode is UiMode.AGENTIC:
+        raise UiModeUnavailableError(UiMode.AGENTIC)
     return ClassicFlowUiDriver()

{gflow_cli-0.33.0 → gflow_cli-0.34.0}/src/gflow_cli/api/transports/ui_automation.py

@@ -16,7 +16,6 @@ from __future__ import annotations
 import asyncio
 import hashlib
 import json
-import os
 import random
 import re
 import time
@@ -208,10 +207,9 @@ SUBMIT_BUTTON_SELECTORS = (
 # agentic chat layout — the ``crop_*`` media trigger disappears and the ``tune``
 # settings gear + ``expand_content`` open button appear. Captured live
 # 2026-06-14 via ``scripts/e2e/capture_agent_toggle.py`` (cropPresent true→false,
-# tune false→true). Opt-in via ``GFLOW_CLI_FORCE_AGENT_UI`` to deterministically
-# drive the agentic path regardless of the server-assigned A/B cohort (which has
-# no client-readable flag and cannot otherwise be forced).
-AGENT_FORCE_ENV_VAR = "GFLOW_CLI_FORCE_AGENT_UI"
+# tune false→true). Reached via ``GFLOW_CLI_UI_MODE=agentic`` (or an inferred
+# agentic requirement) to drive the agentic path regardless of the
+# server-assigned A/B cohort (which has no client-readable flag).
 AGENT_EXPAND_BUTTON_SELECTOR = "button:has(i.google-symbols:text-is('expand_content'))"
 
 # _force_agent_mode: after clicking the Agent toggle, POLL for the ``tune``
@@ -1058,7 +1056,7 @@ class UiAutomationTransport(VideoGenerationMixin):
     async def _force_agent_mode(page: Page) -> bool:
         """Force the agentic composer by clicking the in-composer Agent toggle.
 
-        Opt-in helper (gated by :data:`AGENT_FORCE_ENV_VAR`) used to drive the
+        Opt-in helper (reached via ``GFLOW_CLI_UI_MODE=agentic``) used to drive the
         agentic path deterministically — the server-assigned A/B cohort has no
         client-readable flag, but the in-composer "Agent" toggle switches the
         classic composer into the same agentic layout (``crop_*`` → ``tune``).
@@ -2107,52 +2105,22 @@ class UiAutomationTransport(VideoGenerationMixin):
         # of the editor before we click into settings / submit (#26).
         await self._dismiss_blocking_overlays(page, out_dir)
 
-        # Force the agentic composer when it's needed or explicitly requested:
-        #  - ``request.instructions`` present → instruction cards are an
-        #    agentic-only surface, so a classic bind would silently drop them
-        #    (#267). Switching the composer to agentic first makes ``-i``
-        #    dependable instead of ~50/50.
-        #  - ``GFLOW_CLI_FORCE_AGENT_UI`` set → opt-in to exercise the agentic
-        #    path deterministically (the A/B cohort can't be forced server-side).
-        # ``_force_agent_mode`` is idempotent (no-op when already agentic) and
-        # polls for the render, so the probe below reliably binds agentic.
-        if os.getenv(AGENT_FORCE_ENV_VAR) or request.instructions:
-            forced = await self._force_agent_mode(page)
-            if not forced and request.instructions:
-                log.warning(
-                    "ui_automation.agent_force_failed_with_instructions",
-                    instruction_count=len(request.instructions),
-                    detail=(
-                        "Could not switch this session to the agentic composer; "
-                        "instruction cards (-i) may not be applied. This account "
-                        "may not offer Agent mode."
-                    ),
-                )
-
-        # Probe the DOM for the active UI cohort AFTER _enter_editor so the
-        # project page is fully rendered.  The cohort flaps per page load so
-        # we re-probe every generation — never cache across calls.
-        # Classic driver requires a transport reference for send_prompt.
-        from gflow_cli.config import get_settings
-
-        ui_driver = await get_ui_driver(page, prefer_classic=get_settings().prefer_classic)
+        # Determine the arm this command REQUIRES: explicit --ui-mode / env, or
+        # inferred — agent instructions (-i) are an agentic-only surface, so they
+        # force agentic. get_ui_driver switches to the required arm as a
+        # PREREQUISITE, VERIFIES via a DOM re-probe, and fails fast
+        # (UiModeUnavailableError, exit 28) if the arm is unreachable — so -i can
+        # never silently no-op on a classic bind, and no credits are spent. The
+        # cohort flaps per page load, so this runs every generation (no caching).
+        from gflow_cli.config import infer_required_ui_mode, resolve_ui_mode
+
+        base_mode = request.ui_mode if request.ui_mode is not None else resolve_ui_mode(None)
+        required_mode = infer_required_ui_mode(
+            base_mode, has_instructions=bool(request.instructions)
+        )
+        ui_driver = await get_ui_driver(page, ui_mode=required_mode)
         if ui_driver.name == "classic":
             ui_driver._transport = self  # type: ignore[union-attr]
-            # Agent instruction cards are an agentic-only surface — the classic
-            # driver has no brief to sync. Warn loudly (stderr) so ``-i`` never
-            # silently no-ops: the user asked for instructions but this session
-            # bound the classic cohort, so they will NOT be applied.
-            if request.instructions:
-                log.warning(
-                    "ui_automation.instructions_ignored_classic_cohort",
-                    instruction_count=len(request.instructions),
-                    detail=(
-                        "Custom agent instructions (-i) were provided but this Flow "
-                        "session is using the classic (non-agentic) UI, which has no "
-                        "instruction surface — they will be ignored for this generation. "
-                        "Instructions only apply on agentic-cohort sessions."
-                    ),
-                )
 
         # Select Image mode explicitly. If the account was last in Video mode,
         # an unguarded submission goes to the video endpoint and the image
@@ -2538,9 +2506,13 @@ class UiAutomationTransport(VideoGenerationMixin):
         # cohort flaps per page load; bind once per batch (the editor stays
         # mounted so the cohort is stable for this batch's lifetime).
         # Classic driver requires a transport reference for send_prompt.
-        from gflow_cli.config import get_settings
+        # No instruction inference here: the image-batch manifest carries no
+        # per-item -i instructions (single-prompt only), so the required arm is
+        # just the resolved --ui-mode / env. Route through infer_required_ui_mode
+        # if batch ever gains instruction support.
+        from gflow_cli.config import resolve_ui_mode
 
-        ui_driver = await get_ui_driver(page, prefer_classic=get_settings().prefer_classic)
+        ui_driver = await get_ui_driver(page, ui_mode=resolve_ui_mode(None))
         if ui_driver.name == "classic":
             ui_driver._transport = self  # type: ignore[union-attr]