gflow-cli 0.18.0__tar.gz → 0.20.0__tar.gz

{gflow_cli-0.18.0 → gflow_cli-0.20.0}/.env.template

@@ -106,6 +106,15 @@
 # visible window). The session is still reused from the persistent profile.
 # GFLOW_CLI_HEADLESS=true
 
+# Browser automation engine — playwright (default) | patchright
+# patchright is an OPT-IN, drop-in patched Playwright (Chromium) that avoids the
+# Runtime.enable CDP leak for stronger reCAPTCHA-Enterprise evasion on the HEADED
+# path. It is NOT a headless unlock. Requires a separate install:
+#   pip install patchright        (or: pip install 'gflow-cli[patchright]')
+# When using system Chrome (channel=chrome, the gflow default) you do NOT need
+# `patchright install chromium`. Unset to revert to the default playwright engine.
+# GFLOW_CLI_BROWSER_ENGINE=playwright
+
 # BCP-47 locale tag passed to Playwright's launch `locale=` parameter
 # (controls Accept-Language only — Chrome's UI language is forced to
 # en-US via the `--lang=en-US` launch arg regardless of this setting, so

{gflow_cli-0.18.0 → gflow_cli-0.20.0}/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.20.0] — 2026-06-15
+
+### Added
+
+- **Forced Agentic UI detection** (exit code 25): dynamically detects if the account's Flow editor page has been placed in Google Flow's new Agentic UI A/B cohort. Raises `FlowAgentUiError` and captures a diagnostic viewport screenshot (`debug_forced_agent_ui.png`) to exit cleanly and prevent CLI hangs.
+- **Pluggable Flow UI driver strategy** (`FlowUiDriver`): the UI-automation transport now probes the editor DOM **per generation** (the cohort flaps per page load) and binds a `ClassicFlowUiDriver` or `AgenticFlowUiDriver`, so the two cohorts' selectors never share code. Classic generation is unchanged.
+- **Agentic-cohort image generation** (validated live): when the editor is served the Agentic UI, `gflow image` drives it by encoding settings (count / aspect) into the conversational prompt directive and scraping generated assets directly from the DOM — **deduplicated by media UUID** — because the Agentic UI routes generation through a background Web Worker that defeats page-level network capture. Content-policy blocks (detected in alert/dialog regions) fail fast with `ContentPolicyError` (exit 5). Agentic **video** still raises `FlowAgentUiError` (exit 25) pending a validated scraping path.
+- **`GFLOW_CLI_FORCE_AGENT_UI`** (testing/diagnostic opt-in): forces the agentic composer by clicking the in-input "Agent" toggle after entering the editor, so the agentic path can be exercised deterministically regardless of the server-assigned A/B cohort (which has no client-readable flag). Unset by default — the cohort is auto-detected per generation. See `docs/AGENT_UI_E2E.md`.
+
+## [0.19.0] — 2026-06-12
+
+### Added
+
+- **Opt-in Patchright browser engine** via `GFLOW_CLI_BROWSER_ENGINE=patchright`
+  (default `playwright`, unchanged). Patchright is a drop-in patched Playwright
+  (Chromium) that runs page evaluations in an isolated execution context to
+  avoid the `Runtime.enable` CDP leak, for stronger reCAPTCHA-Enterprise evasion
+  on the **headed** path. It is **not** a headless unlock and must be installed
+  separately: `pip install 'gflow-cli[patchright]'`. The default engine is
+  byte-identical to before. `gflow auth status` now reports the active engine.
+- `BrowserEngineUnavailableError` (exit code 24): selecting `patchright` without
+  the package installed now fails with a clear `pip install patchright`
+  remediation hint instead of a raw `ImportError` hashed to a generic exit 1.
+
+### Fixed
+
+- An invalid `GFLOW_CLI_*` enum value (e.g. a typo'd `GFLOW_CLI_BROWSER_ENGINE`,
+  `GFLOW_CLI_PROVIDER`, or `GFLOW_CLI_LOG_LEVEL`) now fails with a clean
+  configuration error and **exit code 11** naming the offending variable, instead
+  of leaking a raw pydantic `ValidationError` traceback and exiting 1.
+
 ## [0.18.0] — 2026-06-12
 
 ### Added
@@ -1527,7 +1558,9 @@ 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.18.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.20.0...HEAD
+[0.20.0]: https://github.com/ffroliva/gflow-cli/compare/v0.19.0...v0.20.0
+[0.19.0]: https://github.com/ffroliva/gflow-cli/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/ffroliva/gflow-cli/compare/v0.17.0...v0.18.0
 [0.17.0]: https://github.com/ffroliva/gflow-cli/compare/v0.16.0...v0.17.0
 [0.16.0]: https://github.com/ffroliva/gflow-cli/compare/v0.15.1...v0.16.0

{gflow_cli-0.18.0 → gflow_cli-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.18.0
+Version: 0.20.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
@@ -58,6 +58,8 @@ Requires-Dist: ruff>=0.15.16; extra == 'dev'
 Provides-Extra: gcs
 Requires-Dist: gcsfs>=2024.2.0; extra == 'gcs'
 Requires-Dist: universal-pathlib>=0.2.5; extra == 'gcs'
+Provides-Extra: patchright
+Requires-Dist: patchright==1.60.1; extra == 'patchright'
 Provides-Extra: s3
 Requires-Dist: s3fs>=2024.2.0; extra == 's3'
 Requires-Dist: universal-pathlib>=0.2.5; extra == 's3'

gflow_cli-0.20.0/docs/AGENT_UI_E2E.md

@@ -0,0 +1,108 @@
+# Agentic UI — End-to-End Testing Runbook
+
+> How to **deterministically** drive and validate `gflow`'s **Agentic UI** image
+> path against live Google Flow. Companion to
+> [AGENT_UI_RECON.md](AGENT_UI_RECON.md) (the reverse-engineered wire/DOM spec)
+> and [LIVE_VERIFICATION_v0.20.0.md](LIVE_VERIFICATION_v0.20.0.md) (the shipped
+> evidence).
+
+## The problem, and the way in
+
+Google Flow serves the composer via a **server-assigned A/B cohort** that flaps
+per page load and has **no client-readable flag** — so the agentic UI cannot be
+*requested*. A naive "retry until the dice land agentic" e2e is unreliable (we
+observed 7 classic loads in a row).
+
+**The deterministic trigger:** the *classic* composer exposes an in-input
+**"Agent" toggle**. Clicking it switches the composer into the **same** agentic
+layout — confirmed live (`scripts/e2e/capture_agent_toggle.py`, 2026-06-14):
+
+| Signal | Before toggle | After toggle |
+|---|---|---|
+| `crop_*` media trigger | present | **gone** |
+| `tune` settings gear | absent | **present** |
+| Slate composer | present | present |
+
+So `tune` appears and `crop_*` disappears → `detect_ui_mode` then binds the
+agentic driver. An **`expand_content`** button opens the full agent side panel.
+
+## Repeatable procedure (deterministic)
+
+Set **`GFLOW_CLI_FORCE_AGENT_UI=1`** and the transport clicks the Agent toggle
+after entering the editor, forcing the agentic path on any load. The harness
+runs that and verifies the whole chain:
+
+```powershell
+# From repo root. Image generation is free — safe to run repeatedly.
+.\scripts\e2e\agentic_image_e2e.ps1 -Profile denon82 -Count 1
+.\scripts\e2e\agentic_image_e2e.ps1 -Profile denon82 -Count 3   # also exercises dedup
+```
+
+It PASSes only when all four hold (else it prints which stage failed):
+
+1. `agent_mode_forced activated=true` — the toggle flipped the composer to agentic;
+2. `ui_driver.bound mode=agentic` — the agentic driver was bound;
+3. exit 0;
+4. exactly `-Count` `.jpg` files written (scrape → dedup-by-UUID → download).
+
+Run it directly without the harness, too:
+
+```powershell
+$env:GFLOW_CLI_FORCE_AGENT_UI="1"
+uv run gflow image t2i "a ripe banana on a white plate" --profile denon82 --json
+```
+
+> `GFLOW_CLI_FORCE_AGENT_UI` is a **testing/diagnostic opt-in**, not a user
+> feature: it forces the agentic path even when the server served classic.
+> Leave it unset for normal use (the cohort is then auto-detected per
+> generation).
+
+## Validation result (2026-06-14, profile denon82)
+
+Forced-agentic runs validated the three assumptions that mocked tests cannot:
+
+- **`--count 1`** → exit 0, one **420 KB JPG**. Scrape found the asset, built the
+  full-res redirect URL, the `labs.google` download resolved with session
+  cookies, and the synthetic `GeneratedImage` fields (`workflow_id=""`, `seed=0`,
+  `dimensions=(0,0)`) flowed through the save path without error.
+- **`--count 3`** → exit 0, **3 distinct JPGs** for 3 distinct media UUIDs —
+  confirming dedup: the agentic UI's multiple `<img>` nodes per asset collapse to
+  the correct count.
+
+Classic remains unaffected: live `gflow image t2i` and `gflow video t2v` both
+succeed when the cohort/loads serve classic.
+
+## Knowledge extracted (this cost real e2e runs — keep it)
+
+Three render-timing / detection bugs were found **only** by live e2e (mocked
+tests passed throughout); each is now fixed with a regression test:
+
+1. **Cohort detection raced the render.** `get_ui_driver` probed instantly after
+   navigation and missed the agentic `tune` indicator (it appeared ~1.25 s
+   later), defaulting to classic → spurious `FlowAgentUiError` (exit 25). Fix:
+   `detect_ui_mode` polls (8 s window). Test: `test_detect_agentic_after_delayed_render`.
+2. **The force-toggle raced the render too.** `_force_agent_mode` probed for the
+   Agent toggle ~0.8 s after entering the editor, before the composer rendered →
+   `agent_toggle_not_found`, silently staying classic. Fix: `wait_for` the toggle
+   (8 s) before clicking.
+3. **Content-policy detection false-positived on static chrome.** Scanning the
+   whole `document.body` for "content policy" matched a benign page's footer/menu
+   link → every agentic generation died with a spurious `ContentPolicyError`
+   (exit 5) in ~6 s. Fix: scope the scan to `[role=alert]`/`[role=dialog]`/
+   `[aria-live=assertive]` regions only (a real block surfaces there; a
+   chat-message-only refusal is missed, which is the safe trade — a miss →
+   timeout beats a false positive that breaks every generation). Tests:
+   `test_await_images_raises_content_policy_on_explicit_text`,
+   `test_await_images_ignores_body_chrome_policy_text`.
+
+General lesson: **any agentic-composer probe must wait for the render** — instant
+DOM checks race Flow's deferred composer mount.
+
+## Still owed
+
+- A **captured positive content-policy refusal** in the agentic cohort, to widen
+  detection safely beyond alert/dialog regions (chat-message refusals are
+  currently missed → timeout). Trigger a disallowed prompt under
+  `GFLOW_CLI_FORCE_AGENT_UI=1` and capture how the refusal surfaces.
+- **Agentic video** — only the image path is validated; video stays on the
+  classic→`FlowAgentUiError` path pending a video scraping capture.

gflow_cli-0.20.0/docs/AGENT_UI_RECON.md

@@ -0,0 +1,192 @@
+# Agentic Flow UI — Recon Findings
+
+> Reverse-engineered 2026-06-14 via `gflow-agent-browser-spike` (CDP-attached
+> real Chrome, `agent-browser@0.27.0`) against the live Flow editor on two
+> Chrome profiles. Account-specific values (emails, project UUIDs) are redacted.
+> Relates to issues #183 (image `t2i` exit 23) and #174 (library-UI entity drop).
+
+## TL;DR
+
+- Flow runs a **server-side A/B cohort** that swaps the project composer between
+  the **classic** media UI and a new **agentic** UI (chat-style "Agent").
+- It is **volatile**: the *same* Chrome profile rendered the classic composer at
+  one point and the agentic composer later on the *same* project — confirming the
+  #174 flapping (denon82 reverting within 12h).
+- **gflow's own dedicated automation profiles DO land in the agentic cohort**
+  (not only the user's primary profile), so #183/#174 are reproducible through
+  gflow — the feature must handle it.
+- The cohort is **NOT discoverable from client-side state**: localStorage keys and
+  JS-visible cookies are byte-identical across both UIs, and the prime-suspect key
+  `FLOW_MAIN_PROMPT_BOX_STATE` holds only generation settings, not a mode flag.
+  → **Detection must be runtime DOM-based**; there is no pre-navigation cookie/flag
+  to read or flip.
+- `navigator.webdriver` is **`false`** under CDP-attached real Chrome.
+
+## How it was captured
+
+`gflow-agent-browser-spike` launches real Chrome with `--remote-debugging-port`
+on a chosen profile and drives `agent-browser` over CDP. JS is passed as
+**base64-wrapped `eval`** (`eval(atob('…'))`) — multi-line eval args get mangled
+through `npx`, so base64 is the reliable path (this also applies to
+`capture-agent-ui.ps1`, which must minify/encode its eval expressions). Capturing
+the user's **primary** profile required relaunching it with the debug flag (only
+applied on a fresh Chrome start, so all windows must be closed first), which
+triggered a one-time Google 2-Step Verification.
+
+## The two UIs — DOM signature
+
+| Signal | Classic | Agentic |
+|---|---|---|
+| `crop_*` inline aspect/mode trigger | **present** (`crop_9_16` etc.) | **absent** |
+| Agent pill (`/\bAgent\b/` + `div[role='textbox']`) | no | **yes** |
+| Chat ligatures `edit_square`, `thumb_up`, `thumb_down`, `flag` | no | **yes** |
+| Agentic ligatures `article_spark`, `apps_spark_2`, `tune` | no | **yes** |
+| "What do you want to create?" placeholder | no | **yes** |
+| Aspect / model / upscale controls | inline `crop_*` dropdown | moved into **"Agent settings"** (`tune`) |
+
+Agentic ligature inventory (captured): `accessibility_new, add, add_2,
+apps_spark_2, arrow_back, arrow_forward, arrow_forward_ios, article_spark, close,
+content_copy, dashboard, delete, edit_square, filter_list, flag, help, image,
+left_panel_close, menu, more_vert, movie, search, settings_2, thumb_down,
+thumb_up, tune, warning` — and **no `crop_*`**.
+
+## Gating mechanism (the cohort key)
+
+Captured on agentic profiles (both the user's primary and a gflow dedicated
+profile), the client-visible state is **identical**:
+
+- **localStorage keys**: `FLOW_MAIN_PROMPT_BOX_STATE`, `FLOW_QUICK_SEARCH_MODE`,
+  `_grecaptcha`, `glue.CookieNotificationBar`, `nextauth.message`.
+- **JS-visible cookies**: `EMAIL`, `_ga`, `_ga_X2GNH8R5NS` (any cohort cookie
+  would be `httpOnly`, i.e. invisible to JS — recoverable only from HAR request
+  headers, not yet captured).
+- **`FLOW_MAIN_PROMPT_BOX_STATE`** value (agentic):
+  `{"aspectRatio":"PORTRAIT","selectedImageModelFamily":"narwhal_display","selectedVideoModelFamily":"abra","imageOrVideoMode":"IMAGE","outputsPerPrompt":1,"selectedVideoDuration":4}`
+  — generation settings only, **no cohort/mode flag**.
+
+Because (a) the key set is identical across classic and agentic, (b) the one
+plausible key holds only settings, and (c) the same profile flaps between states,
+the cohort is concluded to be **server-assigned per page load**, not a readable
+client signal. Pre-navigation detection (read a cookie before driving) is **not
+viable**; runtime DOM classification is the only reliable detector.
+
+## Why the existing handling fails (#183)
+
+`_exit_agent_mode` (`ui_automation_video.py`) assumes the classic composer is
+recoverable and keys on `_media_panel_present` (the `crop_*` trigger). In the
+agentic cohort there is **no `crop_*`** at all (aspect moved into Agent settings),
+so the probe never recovers, the selector cascade exhausts, and the caller raises
+`UiSelectorDriftError` (exit 23). The recovery has nothing to recover *to*.
+
+## Recommendation for the feature plan
+
+1. **Detection = runtime DOM classification.** Agentic if *no `crop_*` mode
+   trigger* **and** (*Agent pill present* **or** *chat-panel ligatures present*).
+   This is what `classify_composer` / a refreshed `_exit_agent_mode` should key
+   on. Run it every generation — the cohort flaps, so no caching.
+2. **No pre-flight cookie/flag gate** — there is no client-readable cohort signal.
+3. **Response (decide in the feature plan, evidence now supports either):**
+   - **Detect + fail cleanly** with a typed `FlowAgentUiError` (own exit code) +
+     screenshot — low risk, immediately diagnosable. *Recommended first step.*
+   - **Drive the agentic surface** — type into the chat composer, set aspect/model
+     via the Agent-settings (`tune`) panel, handle the confirm-before-generating
+     gate. Larger; intermittently needed because the cohort flaps.
+
+## DOM scraping validation (2026-06-14, live capture)
+
+> Captured via `scripts/capture-media-scrape.ps1` (CDP-attached real Chrome,
+> profile `default`, agentic cohort confirmed: `crop=false, agentPill=true,
+> chatPanel=true`). One image generation, before/after media-DOM snapshot.
+> Artifact: `media-scrape-agentic-20260614-202739.json`.
+
+This resolves the open question blocking `AgenticFlowUiDriver.await_images`: **how do
+generated assets surface in the agentic DOM, and is count-delta scraping viable?**
+
+- **Assets render as plain remote `<img>` nodes.** After the generation: `blob=0`,
+  `data=0`, `canvas=0`, `background-image=0`. The full-res asset is a normal
+  `<img src="https://…">`. Count-delta DOM scraping **is viable** — network
+  interception is not (see HAR note below).
+- **The src is a same-origin tRPC redirect carrying a stable media id:**
+  ```
+  https://labs.google/fx/api/trpc/media.getMediaUrlRedirect?name=<uuid>[&mediaUrlType=MEDIA_URL_TYPE_THUMBNAIL]
+  ```
+  It 302-redirects to the CDN blob; same-origin (`labs.google`) means the session
+  cookies authorize the download. The `name=<uuid>` is the **stable backend media id**
+  — scraped assets correlate to media identity (usable for the batch ledger / dedup).
+- **Dedupe by `name=<uuid>`, NOT by `<img>` node count.** One generated asset surfaces
+  as **multiple** `<img>` nodes (canvas full-res + filmstrip thumbnail + chat preview,
+  each in bare and `&mediaUrlType=MEDIA_URL_TYPE_THUMBNAIL` variants). The single
+  capture produced **9 new `<img>` nodes for only 3 distinct assets** (~3× inflation).
+  `await_images` must extract the `name` query param and **count distinct UUIDs** — a
+  raw `initial_count + expected_count` node check would massively over-count.
+- **Page-level HAR captured 0 entries.** Confirms the Web-Worker delegation: the
+  `streamChat` + media requests bypass page-level network capture entirely. **DOM
+  scraping is the only viable capture path** in the agentic cohort.
+- **`flag` is NOT a content-policy signal.** The warn-symbol probe matched the `flag`
+  ligature 11× on a *successful* generation — `flag`/`thumb_up`/`thumb_down` are the
+  normal per-message chat affordances. Fail-fast detection must key on `warning` /
+  `error` / `block` or specific dialog/stream text, **never `flag`**. *(A deliberate
+  content-policy-refusal capture is still outstanding — no positive block sample yet.)*
+
+## Settings via prompt, not the `tune` popover (agentic acts MCP-like)
+
+The agentic composer behaves like a conversational agent: generation parameters that the
+classic UI exposes as discrete controls — **output count** (1 / 4 images), **video
+duration** (4/6/8/10 s), and likely **aspect ratio** and **model** — can be expressed in
+**natural language inside the prompt** (e.g. `Generate 4 images of <prompt> in 16:9`), and
+the agent resolves the selection itself.
+
+Implications for `AgenticFlowUiDriver`:
+- **`configure_settings` becomes optional.** Encoding settings as a directive prompt
+  avoids driving the fragile `tune` → Radix-popover dropdowns — the most drift-prone
+  surface on a volatile A/B UI. Prefer prompt-encoding; treat popover automation as a
+  fallback only if prompt-steering proves unreliable.
+- **The agent *interprets* the request → verify, don't trust.** It may produce a
+  different count or ignore a duration. This is precisely why scrape-and-dedup-by-UUID
+  is load-bearing: request N → poll until N distinct new media UUIDs → if the produced
+  count differs, raise a typed mismatch rather than silently returning the wrong set.
+- **Compose carefully** so settings directives aren't read as subject text (e.g. a
+  `Generate {n} image(s){aspect}: {prompt}` template).
+
+## Open follow-ups
+
+- **Content-policy block sample (outstanding):** capture a deliberate-refusal generation
+  in the agentic cohort to learn how a block surfaces (chat message vs. dialog vs.
+  symbol) — needed to design `await_images` fail-fast. The `flag` symbol is ruled out.
+
+## The Wire & API Endpoint (Resolved via Issue #183 Reporter)
+
+The network request logs from the agentic UI have been resolved. The new UX bypasses the direct media generation endpoints (such as `batchGenerateImages`) and routes all generation requests through Google's conversational flow creation agent.
+
+- **Endpoint**: `POST https://aisandbox-pa.googleapis.com/v1/flowCreationAgent:streamChat?alt=sse`
+- **Transport**: Server-Sent Events (SSE) stream, preceded by a CORS OPTIONS preflight.
+- **Request Payload Structure**:
+  ```json
+  {
+    "agentSessionId": "<uuid>",
+    "agentClientContext": {
+      "projectId": "projects/<projectUuid>",
+      "clientSessionId": ";<epochMillis>",
+      "recaptchaContext": {
+        "token": "<recaptcha_token>",
+        "applicationType": "RECAPTCHA_APPLICATION_TYPE_WEB"
+      },
+      "turnNumber": 2
+    },
+    "userMessage": {
+      "userPrompt": {
+        "parts": [
+          {
+            "text": "a red apple"
+          }
+        ]
+      }
+    }
+  }
+  ```
+
+### Why page-level CDP/Playwright instrumentation recorded 0 entries
+During local capture sessions, page-level request event listeners repeatedly recorded `0` API request entries. This occurred because the agentic UI delegates all `streamChat` network requests to a background **Web/Service Worker** target (`type: worker`). Worker-initiated requests completely bypass page-level network event registration in Playwright/CDP and require worker-level target attachments to capture.
+
+### Impact on issue #174 (referenceEntities)
+In the agentic UI, the prompt box is a conversational Slate.js editor. Because generation is driven by the conversation agent stream rather than direct REST inputs, staging library entities (e.g. characters) behaves differently. For the initial implementation phase, driving or injecting into `flowCreationAgent:streamChat` is out of scope. The recommended direction is **Runtime DOM detection + Fail Cleanly** with `FlowAgentUiError` (exit code 23) to prevent automation lockups while the cohort is active.

{gflow_cli-0.18.0 → gflow_cli-0.20.0}/docs/CONFIGURATION.md

@@ -190,6 +190,16 @@ GFLOW_CLI_HISTORY_PROMPTS=redacted gflow image t2i "confidential brief"
 **Default:** `true`
 **When to flip to `false`:** if reCAPTCHA Enterprise refuses to mint tokens (Google's bot-detection sometimes refuses headless Chromium but accepts a visible window). Set to `false` and re-run; the browser will appear during generation but the session is still reused from the persistent profile.
 
+### `GFLOW_CLI_BROWSER_ENGINE`
+
+**What:** Selects the browser-automation engine backing the Playwright API.
+**Values:** `playwright` | `patchright`
+**Default:** `playwright`
+**What `patchright` is:** an opt-in, drop-in patched Playwright (Chromium) that runs page evaluations in an isolated execution context to avoid the `Runtime.enable` CDP leak, for stronger reCAPTCHA-Enterprise evasion on the **headed** path. It is **not** a headless unlock — Google still detects headless Chromium regardless of engine.
+**Install:** `pip install 'gflow-cli[patchright]'` (or `pip install patchright`). Selecting `patchright` without it installed fails fast with exit code 24 and a pip remediation hint. When using system Chrome (the gflow default, `channel=chrome`) you do **not** need `patchright install chromium`.
+**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_LOCALE`
 
 **What:** BCP-47 locale tag passed to Playwright's `launch_persistent_context(locale=...)` — controls the `Accept-Language` HTTP header only.

{gflow_cli-0.18.0 → gflow_cli-0.20.0}/docs/INDEX.md

@@ -35,6 +35,7 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 | **[docs/CHARACTER.md](CHARACTER.md)** | Characters feature spec & system design: domain model, endpoint/cost matrix, sequence diagrams, JSON payloads (I/O), CLI surface, reuse via `referenceEntities` (#145) | Working on `gflow character`, reusing a character in generations, or understanding Flow's character wire protocol |
 | **[docs/MOVIE.md](MOVIE.md)** | `gflow movie` — multi-scene character-consistent films: manifest format, run lifecycle (browser stays open through generate→poll→download), entity-attach mechanism (Personagens right-click), resume/handoff, credits | Working on `gflow movie`, debugging scene generation, or understanding the character-entity attach + consistency model |
 | **[docs/IMAGE_UPSCALE_RECON.md](IMAGE_UPSCALE_RECON.md)** | `gflow image upscale` wire protocol: `upsampleImage` endpoint, full clientContext (projectId/sessionId/tool/userPaygateTier), reCAPTCHA action `IMAGE_GENERATION`, inline base64 response, 4K Ultra-gating, REST-is-dead proof | Working on `gflow image upscale`, debugging the 403/reCAPTCHA path, or understanding Flow's image-upscale wire protocol (#171) |
+| **[docs/AGENT_UI_RECON.md](AGENT_UI_RECON.md)** | Agentic Flow UI cohort: classic-vs-agentic DOM signature, server-side + volatile (flapping) A/B gating (no client-readable flag), why `_exit_agent_mode` fails, runtime-DOM-detection recommendation | Touching `_exit_agent_mode` / composer mode-switch, diagnosing exit 23 selector drift, or understanding Flow's agentic-UI A/B (#183/#174) |
 | **[tasks/lessons.md](../tasks/lessons.md)** | Running notebook of patterns + reviewer findings, dated and traced to commits | Starting a new phase; debugging "why did the council flag this?" |
 | **[skills/README.md](../skills/README.md)** | Installable agent skill docs (gflow-cli, predict, pr-council-review, scenario) — cross-tool portable Markdown consumed by Claude Code, Cursor, Codex, Gemini CLI, Aider, etc. | Any agent wanting to use gflow-cli correctly |
 | **[scripts/dev/skillopt/README.md](../scripts/dev/skillopt/README.md)** | SkillOpt mock harness — rollout→score loop for measuring and improving skill doc accuracy across multiple LLM providers | Measuring a skill edit's impact; comparing Claude vs GPT-4o vs Gemini on gflow tasks |
@@ -111,7 +112,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.18.0](LIVE_VERIFICATION_v0.18.0.md) (#183 exit-23 selector-drift error: live drift simulation + happy path, credit-free). v0.14.0 / v0.15.0 / v0.15.1 shipped without a dedicated doc (CI + the v0.13.0 baseline). Prior: [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.20.0](LIVE_VERIFICATION_v0.20.0.md) (Agentic UI image generation on `denon82`: classic `image t2i` + `video t2v` unaffected, and forced-agentic `image t2i` count 1 & count 3 with **live dedup-by-UUID** under `GFLOW_CLI_FORCE_AGENT_UI=1`; 5-layer ledger; natural-cohort agentic load + content-policy refusal recorded as not-verified-this-cycle). v0.14.0 / v0.15.0 / v0.15.1 shipped without a dedicated doc (CI + the v0.13.0 baseline). Prior: [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.20.0/docs/LIVE_VERIFICATION_v0.19.0.md

@@ -0,0 +1,60 @@
+# Live Verification — v0.19.0
+
+Feature under test: **opt-in Patchright browser engine** (`GFLOW_CLI_BROWSER_ENGINE=patchright`).
+Verified 2026-06-12 against live Google Flow on a real authenticated profile. Image
+generation is credit-free, so the end-to-end run cost **$0**.
+
+## Layer 1 — file count
+
+One image produced by `gflow image t2i` through the integrated patchright path:
+
+```
+scripts/dev/_spike_out/patch_verify/images/2026-06-12/6cb21d9e-e4f9-40ba-897c-eb25c6333892_1.jpg
+```
+
+(written to a throwaway `GFLOW_CLI_OUTPUT_DIR`, since cleaned up).
+
+## Layer 2 — magic bytes
+
+`b[:3] == FF D8 FF` → **valid JPEG**. Size 723,911 bytes.
+
+## Layer 3 — dimensions / shape
+
+Pillow: `format=JPEG dims=(768, 1376)` → correct **9:16** portrait (the default aspect).
+
+## Layer 4 — structlog invariants
+
+From the live run (`correlation_id=40877345-0af4-472f-966a-94f88112f0d9`):
+
+- `browser.engine_selected engine=patchright` — the **settings resolver** selected
+  patchright (the real wired path, not a test monkeypatch).
+- `ui_automation.batch_request_body` — prompt submitted (`bytes=5054`).
+- `ui_automation.batch_response_seen status=200` and
+  `ui_automation.batch_response_captured status=200` — `batchGenerateImages`
+  returned 200 and the response body parsed under patchright.
+
+## Layer 5 — user-confirmable artifact
+
+A studio-lit image of "a small green cactus in a terracotta pot" — visually
+inspectable, matches the prompt.
+
+## Supporting checks (same release)
+
+| Check | Evidence | Result |
+|---|---|---|
+| Default path byte-identical | client-level `navigator.webdriver` read through real `FlowApiClient`: `playwright → None` (masked), `patchright → False` (both non-bot) | ✅ default still stealthed |
+| Missing-dependency UX | `GFLOW_CLI_BROWSER_ENGINE=patchright` with patchright uninstalled → `image t2i` | ✅ **exit 24**, `BrowserEngineUnavailableError` + `pip install patchright` hint, no traceback, no browser launched |
+| Invalid enum setting | `GFLOW_CLI_BROWSER_ENGINE=patchwright` (and `GFLOW_CLI_PROVIDER=bogus`) | ✅ **exit 11**, clean "Configuration error" naming the variable, no raw pydantic traceback |
+| reCAPTCHA mint under patchright | `TokenMinter.mint` with `isolated_context=False` | ✅ returns a real token (the predicted isolated-world break, fixed) |
+| Retry across engine boundary | patchright's distinct `TimeoutError` through the real retry policy | ✅ retried (unit test) |
+
+## Premise still pending (documented, not a blocker)
+
+The *value* premise — does patchright reduce real 403s vs Playwright — could **not**
+be measured this cycle: the documented hot profile (`denon82`) had cooled, so plain
+Playwright also returned 200 (no 403 to flip). A faithful 403 cannot be emulated
+locally (a route-injected 403 is engine-blind; inflating real WAF heat risks the
+account). The feature ships as a **proven non-breaking, opt-in escape-hatch** with
+the default unchanged. Re-fire trigger: the instant any profile actually 403s, run
+`scripts/dev/spike_patchright.py --profile <hot> --engines playwright,patchright`
+to capture the `WAF_403 → OK_200` differential.

gflow_cli-0.20.0/docs/LIVE_VERIFICATION_v0.20.0.md

@@ -0,0 +1,76 @@
+# Live verification — v0.20.0 (Agentic UI driver)
+
+> Hand-run against the real Google Flow editor on profile `denon82`. v0.20.0
+> ships the pluggable `FlowUiDriver` strategy and **Agentic-cohort image
+> generation**. The agentic cohort is server-assigned and cannot be forced from
+> the client, so the deterministic trigger `GFLOW_CLI_FORCE_AGENT_UI=1` (clicks
+> the in-input "Agent" toggle) is used to exercise the agentic path. Image
+> generation is credit-free.
+
+## Environment
+
+| | |
+|---|---|
+| Branch | `feature/agentic-ui-driver` → `develop` (PR [#189](https://github.com/ffroliva/gflow-cli/pull/189)) |
+| Version | `0.19.0` working tree (pre-v0.20.0 bump) |
+| Profile | `denon82` (real-browser Chrome) |
+| Profile dir | `C:\Users\ffrol\AppData\Local\ffroliva\gflow-cli\profile_denon82` |
+| Date | 2026-06-14 |
+| Transport | `ui_automation` |
+| Engine | `playwright` |
+
+## How to reproduce
+
+```pwsh
+$env:PYTHONUTF8=1
+# Classic cohort (auto-detected):
+uv run gflow image t2i "a red apple on a rustic wooden table" --profile denon82 --aspect 16:9 --json
+uv run gflow video t2v "a golden sunset over calm ocean waves" --profile denon82 --aspect 16:9 --duration 4 --json
+
+# Agentic cohort, forced deterministically (clicks the Agent toggle):
+$env:GFLOW_CLI_FORCE_AGENT_UI="1"
+uv run gflow image t2i "a single ripe banana on a white plate" --profile denon82 --aspect 16:9 --json
+uv run gflow image t2i "three colorful macarons on a marble surface" --profile denon82 --count 3 --json
+
+# Deterministic harness (verifies forced→agentic→scrape→download, asserts file count):
+.\scripts\e2e\agentic_image_e2e.ps1 -Profile denon82 -Count 3
+```
+
+## Evidence ledger (5-layer)
+
+Each run: **file written** + **magic bytes (JPEG/MP4)** + **dimensions/size** +
+**structlog invariants** + **user-confirmable artifact (media UUID + path)**.
+
+| # | Path | Cohort | Result | Media UUID(s) | Bytes | Key structlog invariants |
+|---|---|---|---|---|---|---|
+| 1 | image t2i (classic) | classic | exit 0, 1 JPG | `f3e529ca…` | 647 KB | `ui_driver.bound mode=classic`; `crop_16_9` matched; `batchGenerateImages` 200 captured |
+| 2 | video t2v (classic) | classic | exit 0, 1 MP4 | `433a92d5…` | 6.33 MB | `video_mode_entered`; `poll_terminal STATUS_SUCCESSFUL`; `video_saved` |
+| 3 | image t2i (forced agentic, count 1) | agentic | exit 0, 1 JPG | `3722b716…` | 420 KB | `agent_mode_forced activated=true`; `ui_driver.bound mode=agentic`; full-res `getMediaUrlRedirect` URL |
+| 4 | image t2i (forced agentic, count 3) | agentic | exit 0, **3 distinct** JPGs | `0bfb4127…`, `2f5c5f9e…`, `cd8f4781…` | 596 / 590 / 629 KB | `mode=agentic`; **dedup**: multiple `<img>` nodes → 3 distinct media UUIDs |
+
+## What this proves
+
+- **Classic path unaffected** by the driver refactor (rows 1–2): image + video
+  generate and download end-to-end through the new `ClassicFlowUiDriver`.
+- **Agentic image generation works end-to-end** (rows 3–4): the Agent toggle
+  flips the composer to agentic, the agentic driver encodes settings into the
+  prompt, types into the Slate composer, **scrapes** the generated assets from
+  the DOM (page-level network capture is dead in this cohort — Web-Worker
+  delegated), **deduplicates by media UUID**, and downloads via the same-origin
+  `labs.google/.../getMediaUrlRedirect` redirect (allow-listed for download).
+- **Synthetic `GeneratedImage` fields** (`seed=0`, `workflow_id=""`,
+  `dimensions=(0,0)`) flow through the save/report path without error.
+
+## Not verified this cycle (recorded honestly)
+
+- **A natural (non-forced) agentic load end-to-end:** the cohort flapped to
+  classic during the windows tested; the forced path exercises identical driver
+  code, but a naturally-served agentic load was not captured generating.
+- **A positive content-policy refusal in the agentic cohort:** detection is
+  scoped to alert/dialog regions pending a captured sample (a chat-message-only
+  refusal currently misses → timeout). See `docs/AGENT_UI_E2E.md`.
+- **Agentic video:** out of scope — raises `FlowAgentUiError` (exit 25) pending a
+  video scraping capture.
+
+See [docs/AGENT_UI_E2E.md](AGENT_UI_E2E.md) for the repeatable procedure and the
+three render-race / detection bugs this live testing surfaced and fixed.

{gflow_cli-0.18.0 → gflow_cli-0.20.0}/docs/SECURITY.md

@@ -201,6 +201,26 @@ Audited with `pip-audit` in CI on every push. Major dependency surface:
 
 No transitive dep with known CVEs at the time of v0.1.0 scaffold.
 
+### Optional `patchright` engine — elevated supply-chain trust
+
+The `gflow-cli[patchright]` extra (opt-in via `GFLOW_CLI_BROWSER_ENGINE=patchright`)
+installs **Patchright**, a single-maintainer package that ships a **patched
+Chromium driver**. Because that driver *is* the browser process that loads your
+real Google session — it has direct access to session cookies, the OAuth Bearer
+token, and SAPISID — it carries a higher blast radius than an ordinary Python
+dependency: a compromised release could exfiltrate the full Google session.
+
+Controls:
+
+- **Optional-only** — never in the base `dependencies`; the default install pulls
+  neither the package nor its driver.
+- **Exact-pinned** (`patchright==1.60.1`) so a release cannot silently move the
+  browser binary underneath you.
+- **Security-review-required on bump** — a Patchright version change is treated
+  like a browser-binary change, NOT a routine dependabot auto-merge.
+- Default engine is `playwright` (Microsoft, security-reviewed); patchright is an
+  experiment you opt into per the trade-off above.
+
 ## Reporting
 
 | Issue type | How |

{gflow_cli-0.18.0 → gflow_cli-0.20.0}/docs/USAGE.md

@@ -1031,6 +1031,7 @@ shell scripts can branch on the failure mode without parsing stderr.
 | `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 (issue #183) | Update gflow-cli; file a bug with the probe name + debug screenshot from the error message |
+| `24` | `BrowserEngineUnavailableError` | `GFLOW_CLI_BROWSER_ENGINE=patchright` but the engine is not installed | `pip install 'gflow-cli[patchright]'`, or unset `GFLOW_CLI_BROWSER_ENGINE` |
 | `130`| SIGINT                | User-interrupted (Ctrl-C)                        | —                                                          |
 
 **Exit code 16 — data store / migration error.** Fires when:

{gflow_cli-0.18.0 → gflow_cli-0.20.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gflow-cli"
-version = "0.18.0"
+version = "0.20.0"
 description = "Unofficial CLI for Google Flow — drive Veo image-to-video generations from the terminal."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -58,6 +58,15 @@ s3 = [
 chain = [
     "av>=12",
 ]
+# Patchright engine extra — opt-in, drop-in patched Playwright (Chromium) that
+# avoids the Runtime.enable CDP leak on the headed path. Selected via
+# GFLOW_CLI_BROWSER_ENGINE=patchright. Ships a PATCHED Chromium driver that
+# handles live Google session cookies/Bearer/SAPISID, so it is EXACT-pinned and
+# treated as a security-review-required bump (NOT a dependabot auto-merge) —
+# see SECURITY.md. Not a headless unlock.
+patchright = [
+    "patchright==1.60.1",
+]
 
 [project.scripts]
 gflow = "gflow_cli.cli:main"