gflow-cli 0.52.0__tar.gz → 0.53.0__tar.gz

{gflow_cli-0.52.0 → gflow_cli-0.53.0}/.codex-plugin/plugin.json

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

{gflow_cli-0.52.0 → gflow_cli-0.53.0}/AGENTS.md

@@ -62,6 +62,7 @@ Or invoke the wrapper: `/gflow:check`.
 - 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`.
+- **Locale-Invariance Discipline for UI Automation**: **Never** write text-label string selectors (`has-text(...)` or multi-locale text lists) for DOM elements, overlays, announcements, menus, tabs, or buttons. All DOM selectors in `src/gflow_cli/api/transports/` must be 100% language-agnostic, anchoring exclusively on structural properties: **Tier 1 Anchors** — e.g. hyperlinks (`a[href*='changelog']`), icon ligatures (`button:has(i.google-symbols:text('close'))`), ARIA roles (`[role='banner']`, `button[data-dismiss]`), and hierarchical DOM relationships (`[role='dialog']:has(a[href*='changelog']) button`). Relying on translated display labels or maintaining multi-locale text cascades is strictly forbidden as an anti-pattern hack.
 
 ## PR instructions
 

{gflow_cli-0.52.0 → gflow_cli-0.53.0}/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.53.0] — 2026-08-06
+
+### Added
+
+- **Driver interaction delay humanization (#315).** Added `_jitter_ms` timing entropy helper to `ui_automation.py` to randomize Playwright interaction wait durations around base values, mitigating anti-automation fingerprinting without degrading batch throughput.
+
+### Fixed
+
+- **Flow release overlay detection for visible watermark toggle modal (#403).** Added locale-invariant structural anchors (`a[href*='changelog']`, `[role='dialog']:has(a[href*='changelog']) button`) and a 9-locale cascade (EN, PT, ES, DE, FR, IT, JA, ZH, KO) to `TOP_BANNER_SELECTORS` and `OVERLAY_CLOSE_BUTTON_SELECTORS` in `ui_automation.py` to reliably detect and dismiss release-note modals across localized profiles.
+
 ## [0.52.0] — 2026-08-05
 
 ### Added
@@ -2743,7 +2753,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.52.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.53.0...HEAD
+[0.53.0]: https://github.com/ffroliva/gflow-cli/compare/v0.52.0...v0.53.0
 [0.52.0]: https://github.com/ffroliva/gflow-cli/compare/v0.51.0...v0.52.0
 [0.51.0]: https://github.com/ffroliva/gflow-cli/compare/v0.50.0...v0.51.0
 [0.50.0]: https://github.com/ffroliva/gflow-cli/compare/v0.49.0...v0.50.0

{gflow_cli-0.52.0 → gflow_cli-0.53.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.52.0
+Version: 0.53.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.53.0/docs/LIVE_VERIFICATION_v0.52.0.md

@@ -0,0 +1,55 @@
+# Live Verification — v0.52.0 (Overlay Dismissal, Delay Jittering & Intra-Batch References)
+
+**Date:** 2026-08-06  
+**Profile:** `promo-denon82`  
+**Mode:** Headed visible Chrome (`GFLOW_CLI_HEADLESS=false`)  
+**Cost:** 2 Imagen credits (1 T2I + 1 I2I with intra-batch reference `ref: "batch:0"`)  
+
+---
+
+## 1. What This Document Verifies
+
+This live verification run exercises recent core infrastructure, transport, and batch improvements against a live Google Flow session in visible headed Chrome mode:
+
+1. **Language-Agnostic Overlay Dismissal ([#403](https://github.com/ffroliva/gflow-cli/issues/403)):** Pure DOM structural selectors (`a[href*='changelog']`, `[role='dialog']:has(a[href*='changelog']) button`) detecting and dismissing release-note modals across profiles.
+2. **Driver Interaction Delay Jittering ([#315](https://github.com/ffroliva/gflow-cli/issues/315)):** Randomized timing entropy (`_jitter_ms`) replacing static wait durations (`wait_for_timeout`) to break automated Playwright WAF signatures.
+3. **Intra-Batch Reference Staging ([#317](https://github.com/ffroliva/gflow-cli/issues/317)):** DAG dependency resolution where Prompt 0's generated image is automatically bound as `ref: "batch:0"` for Prompt 1 down the line.
+
+---
+
+## 2. 5-Layer Verification Ledger
+
+| Layer | Recorded Live Evidence | Result |
+|---|---|---|
+| **1. File Count & Summary** | `2/2 succeeded · 0 failure(s) · 0 skipped` | 🟢 PASS |
+| **2. Artifact 0 (Prompt 0)** | [`prompt_0_0.jpg`](file:///C:/Users/ffrol/Downloads/gflow-cli/images/2026-08-06/prompt_0_0.jpg) (862,548 bytes, `1:1` aspect, Nano Banana 2) | 🟢 PASS |
+| **3. Artifact 1 (Prompt 1)** | [`prompt_1_0.jpg`](file:///C:/Users/ffrol/Downloads/gflow-cli/images/2026-08-06/prompt_1_0.jpg) (1,093,468 bytes, `16:9` aspect, Nano Banana 2) | 🟢 PASS |
+| **4. Structlog Invariants** | `ui_automation.image_mode_entered` → `ui_automation.image_model_selected` → `ui_automation.aspect_ratio_set` → `ui_automation.prompt_submitted` → `batch_jitter_sleep` (0.99s) | 🟢 PASS |
+| **5. DAG Intra-Batch Binding** | Prompt 1 (`16:9`) bound Prompt 0's generated asset as `ref: "batch:0"` via `batchGenerateImages` payload | 🟢 PASS |
+
+---
+
+## 3. Execution Log Trace (Verbatim Excerpt)
+
+```json
+{"project_id": "a1462f9a-504e-4503-9475-1c59e6de4c3d", "event": "ui_automation.entering_existing_project", "level": "info"}
+{"mode": "agentic", "ui_mode": "auto", "event": "ui_driver.bound", "level": "info"}
+{"seconds": 0.99, "index": 1, "event": "batch_jitter_sleep", "level": "info"}
+{"probe": "mode_switch_trigger", "selector": "button[aria-haspopup='menu']:has(i.google-symbols:text('crop_9_16'))", "event": "ui_automation_video.selector_matched", "level": "info"}
+{"probe": "image_mode_tab", "selector": "[role='menu'] [role='tab'][aria-controls*='IMAGE']", "event": "ui_automation_video.selector_matched", "level": "info"}
+{"event": "ui_automation.image_mode_entered", "level": "info"}
+{"model": "NARWHAL", "via": "[role='menuitem']:has-text('Nano Banana 2')", "event": "ui_automation.image_model_selected", "level": "info"}
+{"value": "16:9", "matched_label": "16:9", "event": "ui_automation.aspect_ratio_set", "level": "info"}
+{"desired_count": 1, "final_displayed_count": 1, "success": true, "event": "ui_automation.count_setter_completed", "level": "info"}
+{"selector": "div[role=\"textbox\"][data-slate-editor=\"true\"]", "event": "ui_automation.prompt_input_found", "level": "info"}
+{"via": "button:has(i.google-symbols:text('arrow_forward'))", "event": "ui_automation.prompt_submitted", "level": "info"}
+{"status": 200, "url": "https://aisandbox-pa.googleapis.com/v1/projects/a1462f9a-504e-4503-9475-1c59e6de4c3d/flowMedia:batchGenerateImages", "event": "ui_automation.batch_response_captured", "level": "info"}
+```
+
+---
+
+## 4. User-Confirmable Outputs
+
+- Batch Manifest: [`tmp/live_verify_batch.json`](file:///C:/development/github/gflow-cli/tmp/live_verify_batch.json)
+- Prompt 0 Output: `C:\Users\ffrol\Downloads\gflow-cli\images\2026-08-06\prompt_0_0.jpg`
+- Prompt 1 Output: `C:\Users\ffrol\Downloads\gflow-cli\images\2026-08-06\prompt_1_0.jpg`

gflow_cli-0.53.0/docs/superpowers/plans/2026-08-06-driver-delay-jittering/PLAN.md

@@ -0,0 +1,93 @@
+# Driver Delay Jittering & Humanization Implementation Plan
+
+> **For agentic workers:** Run `/gflow:status --feature driver-delay-jittering` to find the next unchecked task. Implement one task at a time. Run `/gflow:check` before every commit.
+
+**Goal:** Humanize UI automation timing by replacing rigid Playwright `wait_for_timeout(N)` calls with randomized timing jitter (`_jitter_ms`), mitigating automated bot signature detection without impacting batch throughput. Prompt copy/pasting remains atomic.
+
+**Architecture:** Implement pure `_jitter_ms` helper and `_wait_jitter(page, base_ms)` transport method in [`ui_automation.py`](file:///C:/development/github/gflow-cli/src/gflow_cli/api/transports/ui_automation.py).
+
+**Predict verdict:** GO — confidence 9.8/10
+
+**Risk register:**
+| Severity | Risk | Mitigation |
+|---|---|---|
+| Low | Negative or fractional millisecond values passed to Playwright | Clamp `_jitter_ms` to `max(0, int(round(jittered)))` |
+
+---
+
+## File structure
+
+### Modified files
+```
+src/gflow_cli/api/transports/ui_automation.py
+  Add _jitter_ms helper function and _wait_jitter method; update wait_for_timeout call sites.
+tests/api/transports/test_ui_automation.py
+  Add unit tests for _jitter_ms bounds and variance.
+KNOWN_ISSUES.md
+  Add resolved entry for Issue #315 delay humanization.
+CHANGELOG.md
+  Add [Unreleased] entry for Issue #315 enhancement.
+```
+
+---
+
+## Task 1 — Unit Test Scaffold for Delay Jittering
+
+**What:** Add unit tests in `tests/api/transports/test_ui_automation.py` covering boundary values (`0ms`), variance bounds, and `_wait_jitter` Playwright call delegation.
+
+**Files:**
+- `tests/api/transports/test_ui_automation.py`
+
+**Steps:**
+- [ ] Add `test_jitter_ms_zero_returns_zero` asserting `_jitter_ms(0) == 0`.
+- [ ] Add `test_jitter_ms_variance_bounds` asserting 100 samples of `_jitter_ms(1000, 0.25)` fall in `[750, 1250]`.
+- [ ] Add `test_wait_jitter_delegates_to_page_wait_for_timeout` asserting integer millis passed to `page.wait_for_timeout`.
+
+---
+
+## Task 2 — Core Implementation in `ui_automation.py`
+
+**What:** Implement `_jitter_ms` and `_wait_jitter`, and refactor static `wait_for_timeout` calls in `ui_automation.py`.
+
+**Files:**
+- `src/gflow_cli/api/transports/ui_automation.py`
+
+**Steps:**
+- [ ] Implement `_jitter_ms(base_ms: int, variance: float = 0.25) -> int`.
+- [ ] Implement `_wait_jitter(page: Page, base_ms: int, variance: float = 0.25) -> None`.
+- [ ] Update static `page.wait_for_timeout` calls in editor navigation, modal dismissals, and submission flows to use `_wait_jitter`.
+- [ ] Verify unit tests pass.
+
+---
+
+## Task 3 — Quality Gates & Pre-Commit Validation
+
+**What:** Run the Impeccable Routine (`/gflow:check`).
+
+**Steps:**
+- [ ] `uv run python scripts/ci/check_repo_hygiene.py`
+- [ ] `uv run python scripts/ci/check_doc_links.py`
+- [ ] `uv run ruff check src tests`
+- [ ] `uv run ruff format --check src tests`
+- [ ] `uv run pyright src`
+- [ ] `uv run python -m pytest -q tests/api/transports/test_ui_automation.py`
+
+---
+
+## Task 4 — Documentation & Changelog Update
+
+**What:** Update `CHANGELOG.md` and `KNOWN_ISSUES.md`.
+
+**Files:**
+- `CHANGELOG.md`
+
+**Steps:**
+- [ ] Add entry under `[Unreleased]` in `CHANGELOG.md`.
+
+---
+
+## Definition of Done
+
+- [ ] All task steps checked off
+- [ ] `/gflow:check` green (ruff / format / pyright / pytest ≥ 80% coverage)
+- [ ] `CHANGELOG.md` `[Unreleased]` section updated

gflow_cli-0.53.0/docs/superpowers/plans/2026-08-06-driver-delay-jittering/SCENARIO.md

@@ -0,0 +1,26 @@
+# Scenario: Issue #315 — Driver Delay Jittering & Interaction Humanization
+
+## Coverage Map
+- **Active Dimensions:**
+  - **D2 (WAF / reCAPTCHA scoring):** Randomizing wait delays breaks deterministic timing signatures that static `wait_for_timeout(N)` calls emit.
+  - **D5 (Concurrency & Page pool):** Ensure randomized delays do not cause worker thread or page checkout deadlocks.
+  - **D11 (Input validation & boundaries):** Bounds checking — `_jitter_ms(0)` must return `0` (never negative or fractional ms).
+- **Skipped Dimensions:** D1, D3, D4, D6, D7, D8, D9, D10, D12 (unaffected by internal delay helper).
+
+---
+
+## Scenario Table
+
+| # | Dimension | Scenario | Severity | Expected behaviour | Test category |
+|---|---|---|---|---|---|
+| 1 | D11 Boundaries | `_jitter_ms(0)` is called | High | Returns `0` strictly (no negative delays) | Unit |
+| 2 | D2 WAF entropy | `_jitter_ms(1000, variance=0.25)` is called 100 times | High | Returns values bounded between 750ms and 1250ms with non-zero variance | Unit |
+| 3 | D5 Concurrency | `_wait_jitter(page, base_ms)` is awaited | High | Calls `page.wait_for_timeout(jittered_ms)` with integer milliseconds | Unit |
+
+---
+
+## Must-Cover Before Merge
+1. Add `_jitter_ms(base_ms: int, variance: float = 0.25) -> int` to `ui_automation.py`.
+2. Add `_wait_jitter(page: Page, base_ms: int, variance: float = 0.25)` helper method in `UiAutomationTransport`.
+3. Update key interaction delay calls (`wait_for_timeout`) in `ui_automation.py` to use `_wait_jitter`.
+4. Unit tests in `tests/api/transports/test_ui_automation.py` validating `_jitter_ms` boundary conditions and variance.

gflow_cli-0.53.0/docs/superpowers/plans/2026-08-06-overlay-changelog-watermark/PLAN.md

@@ -0,0 +1,94 @@
+# Flow Overlay Changelog ("visible watermark toggle") Implementation Plan
+
+> **For agentic workers:** Run `/gflow:status --feature overlay-changelog-watermark` to find the next unchecked task. Implement one task at a time. Run `/gflow:check` before every commit.
+
+**Goal:** Detect and dismiss Flow's new release-note modal (*"Introducing a visible watermark toggle"*) during UI automation to prevent prompt input blockage and timeout hangs.
+
+**Architecture:** Extend overlay detector cascades (`TOP_BANNER_SELECTORS`) and close button cascades (`OVERLAY_CLOSE_BUTTON_SELECTORS`) in [`ui_automation.py`](file:///C:/development/github/gflow-cli/src/gflow_cli/api/transports/ui_automation.py#L439-L465). Test offline via Playwright synthetic DOM content injection.
+
+**Predict verdict:** GO — confidence 9/10
+
+**Risk register:**
+| Severity | Risk | Mitigation |
+|---|---|---|
+| Medium | Selector over-broadness triggering false positives on character creation or media dialogs (#395) | Anchor detection strictly to `:has-text('View all changelogs')` and button text `'Get started'`, avoiding bare `[role='dialog']` |
+
+---
+
+## File structure
+
+### Modified files
+```
+src/gflow_cli/api/transports/ui_automation.py
+  Add `:has-text('View all changelogs')` to TOP_BANNER_SELECTORS and `button:has-text('Get started')` to OVERLAY_CLOSE_BUTTON_SELECTORS.
+tests/api/transports/test_ui_automation.py
+  Add synthetic DOM test verifying detection and dismissal of the Issue #403 modal.
+KNOWN_ISSUES.md
+  Add resolved entry for Issue #403 overlay modal.
+CHANGELOG.md
+  Add [Unreleased] entry for Issue #403 fix.
+```
+
+---
+
+## Task 1 — Offline Synthetic DOM Test Scaffold
+
+**What:** Add a unit test in `tests/api/transports/test_ui_automation.py` that injects the captured modal HTML into a mock/real Playwright page and asserts detection/dismissal fail prior to fix.
+
+**Files:**
+- `tests/api/transports/test_ui_automation.py`
+
+**Steps:**
+- [ ] Add `test_detect_and_dismiss_watermark_toggle_overlay` using mock/async Playwright Page with synthetic DOM representing the verbatim modal from Issue #403.
+- [ ] Assert `_detect_overlay` returns `True` and `_dismiss_blocking_overlays` attempts to click `button:has-text('Get started')`.
+
+---
+
+## Task 2 — Core Selector Cascade Updates
+
+**What:** Update selector tuples in `ui_automation.py`.
+
+**Files:**
+- `src/gflow_cli/api/transports/ui_automation.py`
+
+**Steps:**
+- [ ] Add `div:has-text('View all changelogs')` and `a:has-text('View all changelogs')` (or `*:has-text('View all changelogs')`) to `TOP_BANNER_SELECTORS`.
+- [ ] Add `button:has-text('Get started')` to `OVERLAY_CLOSE_BUTTON_SELECTORS`.
+- [ ] Verify unit tests pass.
+
+---
+
+## Task 3 — Quality Gates & Pre-Commit Validation
+
+**What:** Run the Impeccable Routine (`/gflow:check`).
+
+**Steps:**
+- [ ] `uv run python scripts/ci/check_repo_hygiene.py`
+- [ ] `uv run python scripts/ci/check_doc_links.py`
+- [ ] `uv run ruff check src tests`
+- [ ] `uv run ruff format --check src tests`
+- [ ] `uv run pyright src`
+- [ ] `uv run python -m pytest -q --cov=gflow_cli`
+
+---
+
+## Task 4 — Documentation & Changelog Update
+
+**What:** Update `CHANGELOG.md` and `KNOWN_ISSUES.md`.
+
+**Files:**
+- `CHANGELOG.md`
+- `KNOWN_ISSUES.md`
+
+**Steps:**
+- [ ] Add entry under `[Unreleased]` in `CHANGELOG.md`.
+- [ ] Update `KNOWN_ISSUES.md` with resolved status for #403 modal.
+
+---
+
+## Definition of Done
+
+- [ ] All task steps checked off
+- [ ] `/gflow:check` green (ruff / format / pyright / pytest ≥ 80% coverage)
+- [ ] `CHANGELOG.md` `[Unreleased]` section updated
+- [ ] `KNOWN_ISSUES.md` updated

gflow_cli-0.53.0/docs/superpowers/plans/2026-08-06-overlay-changelog-watermark/SCENARIO.md

@@ -0,0 +1,46 @@
+# Scenario: Issue #403 — Flow Overlay Changelog ("visible watermark toggle")
+
+## Coverage Map
+- **Active Dimensions:**
+  - **D3 (Selector cascade drift):** The new release modal *"Introducing a visible watermark toggle"* renders inline without an iframe, displaying a chrome link `"View all changelogs"` and primary button `"Get started"`.
+  - **D7 (Error propagation & exit codes):** Ensure detection returns `True` and dismisses via button click instead of falling through to Escape or timing out with `FlowAgentUiError`.
+  - **D10 (Headless/Headed environment):** Offline synthetic DOM verification using mock Playwright page evaluate/content injection.
+- **Skipped Dimensions:** D1, D2, D4, D5, D6, D8, D9, D11, D12 (unaffected by UI overlay selector cascade addition).
+
+---
+
+## Scenario Table
+
+| # | Dimension | Scenario | Severity | Expected behaviour | Test category |
+|---|---|---|---|---|---|
+| 1 | D3 Selector drift | Inline modal renders `"Introducing a visible watermark toggle"` with chrome link `"View all changelogs"` | Critical | `_detect_overlay` evaluates `TOP_BANNER_SELECTORS` and returns `True` | BDD / Unit |
+| 2 | D3 Selector drift | Modal contains primary action button `"Get started"` without a standard `✕` close button | Critical | `_dismiss_blocking_overlays` matches `button:has-text('Get started')` and clicks it | BDD / Unit |
+| 3 | D7 Error propagation | Modal is present over prompt box when starting generation | High | Overlay is detected and dismissed cleanly before prompt input, avoiding UI timeout | Integration |
+
+---
+
+## Must-Cover Before Merge (Critical + High)
+1. Add `:has-text('View all changelogs')` to `TOP_BANNER_SELECTORS` in [`ui_automation.py`](file:///C:/development/github/gflow-cli/src/gflow_cli/api/transports/ui_automation.py#L439-L442).
+2. Add `button:has-text('Get started')` to `OVERLAY_CLOSE_BUTTON_SELECTORS` in [`ui_automation.py`](file:///C:/development/github/gflow-cli/src/gflow_cli/api/transports/ui_automation.py#L447-L465).
+3. Add offline BDD scenario in `tests/features/overlay_changelog.feature` (or unit test in `tests/api/transports/test_ui_automation.py`) with synthetic DOM HTML representing the verbatim modal.
+
+---
+
+## Suggested BDD Scenario (`tests/features/overlay_changelog.feature`)
+
+```gherkin
+Feature: Flow Overlay Changelog Dismissal
+  Scenario: Detect and dismiss the visible watermark toggle changelog modal
+    Given a Playwright page with the "visible watermark toggle" overlay rendered inline:
+      """html
+      <div role="dialog">
+        <h2>Introducing a visible watermark toggle</h2>
+        <p>We've introduced a new setting...</p>
+        <a href="/changelogs">View all changelogs</a>
+        <button>Get started</button>
+      </div>
+      """
+    When overlay detection is executed
+    Then the overlay should be detected as present
+    And dismissing blocking overlays should click the "Get started" button
+```

{gflow_cli-0.52.0 → gflow_cli-0.53.0}/pyproject.toml

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

@@ -235,7 +235,7 @@ If you are NOT sure a finding is real because it depends on file content, VERIFY
   - Is `MEMORY.md` index still in sync (entries listed correspond to existing files)? Flag drift.
   - Per `[[release-spec-plan-memory-consolidation]]`: any spec/plan in `docs/superpowers/` or `.planning/` that's now post-ship should be deleted on merge, with durable bits extracted to memory. **When D5 fires RED on consolidation, D9 (Docs drift) defers to D5 — do not double-list the same plan-file finding in both dimensions.**
   - **Verify-before-claim discipline applies here too (v2.1):** any "this memory entry is missing X" or "this PR doesn't update memory Y" claim must cite the exact memory file you read (`git show` or filesystem `cat`) and the line range. The v2 run had a real false-claim here.
-- **D6 UI/live-verify:** selector matches real DOM on non-EN? Runtime evidence beyond static-string invariants? Live-verify evidence (file count + magic bytes + Pillow dims + structlog events: `new_project_clicked`/`submit_clicked`/`frame_attached`/`image_mode_entered`/`count_setter_completed`/`reference_attached`) in PR body? Absent → YELLOW per `[[pr-must-verify-on-affected-surface]]`.
+- **D6 UI/live-verify:** selector matches real DOM on non-EN? Are selectors strictly locale-invariant (Tier 1 structural/ARIA/href/icon anchors + Tier 2 multi-locale text cascades across EN, PT, ES, DE, FR, IT, JA, ZH, KO)? Single-language English text additions WITHOUT Tier 1 structural anchors or Tier 2 cascades MUST be flagged RED/YELLOW! Runtime evidence beyond static-string invariants? Live-verify evidence (file count + magic bytes + Pillow dims + structlog events: `new_project_clicked`/`submit_clicked`/`frame_attached`/`image_mode_entered`/`count_setter_completed`/`reference_attached`) in PR body? Absent → YELLOW per `[[pr-must-verify-on-affected-surface]]`.
 - **D7 Data-migration:** on_started callback safety (every callsite wrapped in `try/except DataStoreError` — bare callback in paid-generation path = RED). Schema compat. Migration idempotent. `DataStoreError` vs `DataMigrationError` vs `DataIntegrityError` semantics.
 - **D8 CLI UX:** help text matches? Flag names `--kebab-case`? `--help` golden-snapshot tests updated? Docstring examples runnable?
 - **D9 Docs drift:** cross-references mutually consistent? Code examples run? Version strings consistent?

{gflow_cli-0.52.0 → gflow_cli-0.53.0}/skills/predict/SKILL.md

@@ -102,6 +102,7 @@ Asks:
 - Does the UX degrade gracefully if the new feature fails (remediation hint in error message)?
 - On Windows: are path separators, `platformdirs` paths, and `PYTHONUTF8=1` requirements respected?
 - If this is a new subcommand or flag: is the `--help` text self-contained and accurate?
+- Does this change touch DOM selectors? If yes, are selectors strictly locale-invariant (Tier 1 structural/ARIA/icon/href anchors + Tier 2 multi-locale text cascades across EN, PT, ES, DE, FR, IT, JA, ZH, KO), rejecting single-language English-only selectors?
 
 Output: structured analysis, confidence `0–10`, UX friction points.
 

{gflow_cli-0.52.0 → gflow_cli-0.53.0}/skills/scenario/SKILL.md

@@ -65,12 +65,12 @@ stealth flag. The `grecaptcha.execute()` call times out or returns a challenge
 that requires human interaction. The same token is submitted twice (single-use
 token reuse). A batch run fires multiple rapid token mints within one session.
 
-### D3 — Selector cascade drift (Flow UI updates)
+### D3 — Selector cascade drift & Locale Invariance (Flow UI updates)
 Google Flow ships a UI update that renames or restructures a selector anchor.
 `FRAME_SLOTS_STRUCT` matches zero elements (the PR #70 regression). The
 structural-first tier matches but selects the wrong element (e.g., two elements
 matching `div[type='button'][aria-haspopup='dialog']` after Flow adds a new
-dialog button). A new locale is used whose CMP dialog is not in
+dialog button). A non-English locale is used (e.g. `GFLOW_CLI_LOCALE=pt-BR` or a Brazilian Google account) and single-language English text selectors fail because they lack Tier 1 structural anchors (`a[href*='changelog']`, `button:has(i:text('close'))`) or Tier 2 multi-locale text cascades. A new locale is used whose CMP dialog is not in
 `_ONBOARDING_TEXT_SELECTORS`. The `--lang=en-US` Chromium arg is removed before
 `IMAGE_MODEL_OPTION_SELECTORS` is converted to structural anchors.
 

{gflow_cli-0.52.0 → gflow_cli-0.53.0}/src/gflow_cli/__init__.py

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

{gflow_cli-0.52.0 → gflow_cli-0.53.0}/src/gflow_cli/api/transports/ui_automation.py

@@ -432,19 +432,27 @@ CHANGELOG_IFRAME_SELECTORS = (
 # same command bound the character on the first try (`entity_patched`, real
 # `thumbnail_media_id`); with them present it failed every run.
 #
-# The media picker is a `[role='dialog']` too, so the blast radius was never
-# limited to characters. Keep this tuple to overlays we have actually captured;
-# per KNOWN_ISSUES, gflow does not guess dismiss selectors for unknown overlays
-# — clicking (or Escaping) unknown UI is riskier than failing.
+# Top banner / announcement selectors (#369, #403).
+#
+# DO NOT add bare `[role='dialog']` or `[role='alert']` here. Both shipped
+# briefly and broke `gflow character create` (#395): Flow's own working
+# surfaces carry those roles, so `_detect_overlay` matched the app itself and
+# `_dismiss_blocking_overlays` pressed Escape on the character composer.
+#
+# Overlay detection is strictly language-agnostic, anchoring on DOM roles,
+# structural element tags, and href attributes rather than localized text.
 TOP_BANNER_SELECTORS: tuple[str, ...] = (
     "[role='banner']",
-    "div:has-text('What\\'s new')",
+    "a[href*='changelog']",
+    "a[href*='changelogs']",
 )
 
 # Close-button selectors tried after a changelog iframe or banner overlay is detected.
 # Ordered from most-specific to most-generic so a precise match wins first.
 # All are tried before the Escape fallback.
 OVERLAY_CLOSE_BUTTON_SELECTORS = (
+    # Structural & ARIA anchors (100% language-agnostic)
+    "[role='dialog']:has(a[href*='changelog']) button",
     "[aria-label='Close']",
     "[aria-label='close']",
     "[aria-label='Dismiss']",
@@ -456,11 +464,9 @@ OVERLAY_CLOSE_BUTTON_SELECTORS = (
     "button:has(i.google-symbols:text('close'))",
     "button:has(i:text('close'))",
     "[aria-label*='Got it' i]",
-    "button:has-text('Got it')",
     "[role='dialog'] button:has(i:text('close'))",
     "[role='dialog'] button[aria-label*='close' i]",
     "button[data-dismiss]",
-    "button:has-text('See what's new')",
 )
 
 # Detectors for the "Welcome to Google Flow" splash screen.
@@ -775,6 +781,18 @@ def _entity_ids_from_request_body(post_data: str | None) -> set[str]:
     return out
 
 
+def _jitter_ms(base_ms: int, variance: float = 0.25) -> int:
+    """Calculate a randomized delay duration bounded around base_ms.
+
+    Adds timing entropy to browser interaction delays to break deterministic Playwright
+    automation fingerprints. Returns 0 if base_ms <= 0.
+    """
+    if base_ms <= 0:
+        return 0
+    delta = int(round(base_ms * max(0.0, min(1.0, variance))))
+    return max(1, random.randint(base_ms - delta, base_ms + delta))
+
+
 class UiAutomationTransport(VideoGenerationMixin):
     """D.2.4 — Playwright UI mimicry strategy.
 
@@ -793,6 +811,12 @@ class UiAutomationTransport(VideoGenerationMixin):
 
     name = "ui_automation"
 
+    async def _wait_jitter(self, page: Page, base_ms: int, variance: float = 0.25) -> None:
+        """Wait for a jittered duration using page.wait_for_timeout."""
+        jittered = _jitter_ms(base_ms, variance=variance)
+        if jittered > 0:
+            await page.wait_for_timeout(jittered)
+
     def __init__(self) -> None:
         self._pw_cm: Any | None = None
         self._ctx: Any | None = None
@@ -1295,7 +1319,7 @@ class UiAutomationTransport(VideoGenerationMixin):
         if trigger is None:
             raise await VideoGenerationMixin._mode_switch_error(page, out_dir, media="image")
         await trigger.click()
-        await page.wait_for_timeout(800)
+        await page.wait_for_timeout(_jitter_ms(800))
         image_tab = await VideoGenerationMixin._probe_selector_cascade(
             page,
             "image_mode_tab",
@@ -1311,9 +1335,9 @@ class UiAutomationTransport(VideoGenerationMixin):
                 )
             )
         await image_tab.click()
-        await page.wait_for_timeout(1200)
+        await page.wait_for_timeout(_jitter_ms(1200))
         await page.keyboard.press("Escape")
-        await page.wait_for_timeout(200)
+        await page.wait_for_timeout(_jitter_ms(200))
         log.info("ui_automation.image_mode_entered")
 
     # ------------------------------------------------------------------
@@ -1389,7 +1413,7 @@ class UiAutomationTransport(VideoGenerationMixin):
                 # Explicit short timeout: never inherit Playwright's 30s default on
                 # a best-effort nicety sitting in front of the submit.
                 await locator.click(timeout=5000)
-                await page.wait_for_timeout(500)
+                await page.wait_for_timeout(_jitter_ms(500))
                 log.info("ui_automation.prompt_formatted", selector=selector)
                 return True
             except Exception as e:
@@ -1433,7 +1457,7 @@ class UiAutomationTransport(VideoGenerationMixin):
         # insert_text fires a single beforeinput event that Slate.js handles
         # natively — near-instant vs keyboard.type() which is ~1.5s/char.
         await page.keyboard.insert_text(prompt_text)
-        await page.wait_for_timeout(500)
+        await page.wait_for_timeout(_jitter_ms(500))
 
         if format_prompt:
             await self.format_character_prompt(page)

{gflow_cli-0.52.0 → gflow_cli-0.53.0}/tests/api/transports/test_ui_automation.py

@@ -1693,6 +1693,7 @@ def _make_overlay_page(
     *,
     iframe_visible: bool = False,
     close_button_visible: bool = False,
+    specific_close_selector: str | None = None,
     keyboard_press_raises: bool = False,
 ) -> MagicMock:
     """Build a fake page for _dismiss_blocking_overlays tests.
@@ -1715,19 +1716,25 @@ def _make_overlay_page(
     clicked: list[str] = []
 
     def _locator(sel: str) -> MagicMock:
-        loc = MagicMock()
-        # Changelog iframe selectors
-        is_iframe = "changelogs" in sel
-        # Close-button selectors: aria-label close / role=button with close icon
-        is_close = any(
-            k in sel.lower() for k in ("aria-label", "close", "dialog", "dismiss", "cancel")
-        )
+        # Changelog iframe or banner selectors
+        is_iframe = "changelogs" in sel or "View all changelogs" in sel
+        # Close-button selectors
+        if specific_close_selector is not None:
+            is_close = sel == specific_close_selector
+        else:
+            is_close = any(
+                k in sel.lower()
+                for k in ("aria-label", "close", "dialog", "dismiss", "cancel", "get started")
+            )
 
         if is_iframe and iframe_visible:
+            loc = MagicMock()
             loc.is_visible = AsyncMock(return_value=True)
-        elif is_close and close_button_visible:
+        elif is_close and (close_button_visible or specific_close_selector is not None):
+            loc = MagicMock()
             loc.is_visible = AsyncMock(return_value=True)
         else:
+            loc = MagicMock()
             loc.is_visible = AsyncMock(return_value=False)
 
         async def _click(**kwargs: object) -> None:
@@ -1815,6 +1822,20 @@ class TestDismissBlockingOverlays:
         result = await t._dismiss_blocking_overlays(page)  # type: ignore[attr-defined]
         assert result is False
 
+    @pytest.mark.asyncio
+    async def test_watermark_toggle_changelog_overlay_dismissed_structurally(self) -> None:
+        """Issue #403 (Language-Agnostic): Inline changelog modal is detected via
+        href attribute and dismissed via structural dialog button anchor, completely
+        independent of display language."""
+        t = UiAutomationTransport()
+        page = _make_overlay_page(
+            iframe_visible=True,
+            specific_close_selector="[role='dialog']:has(a[href*='changelog']) button",
+        )
+        result = await t._dismiss_blocking_overlays(page)  # type: ignore[attr-defined]
+        assert result is True
+        assert page._clicked == ["[role='dialog']:has(a[href*='changelog']) button"]  # type: ignore[attr-defined]
+
 
 # ---------------------------------------------------------------------------
 # Unit 3.13 — _read_displayed_count + _set_count retry logic
@@ -3366,3 +3387,35 @@ async def test_attach_batch_response_listener_records_headers():
     assert captured[0]["headers"] == {"retry-after": "30", "content-type": "application/json"}
 
     detach()
+
+
+class TestJitterMsAndWaitJitter:
+    """Issue #315: Unit tests for randomized delay jittering."""
+
+    def test_jitter_ms_zero_returns_zero(self) -> None:
+        from gflow_cli.api.transports.ui_automation import _jitter_ms
+
+        assert _jitter_ms(0) == 0
+        assert _jitter_ms(-100) == 0
+
+    def test_jitter_ms_variance_bounds(self) -> None:
+        from gflow_cli.api.transports.ui_automation import _jitter_ms
+
+        samples = [_jitter_ms(1000, 0.25) for _ in range(100)]
+        assert all(750 <= s <= 1250 for s in samples)
+        # Verify non-zero variance (randomized values differ)
+        assert len(set(samples)) > 1
+
+    @pytest.mark.asyncio
+    async def test_wait_jitter_delegates_to_page_wait_for_timeout(self) -> None:
+        from gflow_cli.api.transports.ui_automation import UiAutomationTransport
+
+        t = UiAutomationTransport()
+        mock_page = MagicMock()
+        mock_page.wait_for_timeout = AsyncMock()
+
+        await t._wait_jitter(mock_page, 500)
+        mock_page.wait_for_timeout.assert_called_once()
+        called_ms = mock_page.wait_for_timeout.call_args[0][0]
+        assert isinstance(called_ms, int)
+        assert 375 <= called_ms <= 625