gflow-cli 0.79.1__tar.gz → 0.81.0__tar.gz

{gflow_cli-0.79.1 → gflow_cli-0.81.0}/.codex-plugin/plugin.json

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

{gflow_cli-0.79.1 → gflow_cli-0.81.0}/.env.template

@@ -165,6 +165,13 @@
 # GFLOW_CLI_HEADLESS=false explicitly rather than relying on the default.
 # GFLOW_CLI_HEADLESS=false
 
+# Screen position X,Y of the headed generation browser. Default -30000,-30000 opens it
+# off-screen: still real headed Chrome (reCAPTCHA unaffected), just not over your
+# desktop. Set 0,0 (or a second monitor's origin) to watch a run or clear a consent /
+# account-chooser screen by hand; set empty for Chrome's own placement. It does NOT
+# stop Chrome taking keyboard focus at launch. Login windows are always visible.
+# GFLOW_CLI_BROWSER_WINDOW_POSITION=-30000,-30000
+
 # 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

{gflow_cli-0.79.1 → gflow_cli-0.81.0}/.github/workflows/ci.yml

@@ -43,7 +43,7 @@ jobs:
         with:
           persist-credentials: false
       - name: Install uv
-        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
       - name: Audit locked dependencies for known CVEs
         # Fails the build on any known advisory. Accept later via: pip-audit --ignore-vuln <GHSA-id>
         #
@@ -80,7 +80,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
 
       - name: Audit workflows (zizmor)
         # --offline: the online audits need a GH token and reach the network, so
@@ -116,7 +116,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
 
       - name: Set up Python
         run: uv python install 3.13
@@ -172,7 +172,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
 
       - name: Set up Python
         run: uv python install ${{ matrix.python-version }}
@@ -225,7 +225,9 @@ jobs:
         # e2e/live tests require a logged-in Chromium profile and may spend
         # Flow credits. pyproject.toml excludes both markers by default; CI
         # intentionally relies on that default smoke set.
-        run: uv run python -m pytest -q --cov=gflow_cli --cov-report=xml --junitxml=pytest-report.xml
+        # -n auto: pytest-xdist, one worker per runner vCPU (~2x on the full suite;
+        # 198 s vs ~390 s measured locally at -n 8).
+        run: uv run python -m pytest -q -n auto --cov=gflow_cli --cov-report=xml --junitxml=pytest-report.xml
 
       # Five files under tests/e2e/ are hermetic: every Flow origin is served by
       # `page.route(...).fulfill(...)`, so they need no account, no profile, no
@@ -285,7 +287,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
 
       - name: Set up Python
         run: uv python install 3.13
@@ -357,7 +359,7 @@ jobs:
         # archived actions, so its pin would rot silently); sonarqube-scan-action
         # is SonarSource's maintained successor and serves SonarCloud when
         # SONAR_HOST_URL points at it.
-        uses: SonarSource/sonarqube-scan-action@22918119ff8e1ca75a623e15c8296b6ea4fbe28f # v8.2.1
+        uses: SonarSource/sonarqube-scan-action@ba9859eae8dd6bd29e412f25ddbbef3d032000f4 # v8.2.2
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # PR decoration
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}    # set in repo → Settings → Secrets

{gflow_cli-0.79.1 → gflow_cli-0.81.0}/.github/workflows/deps-watch.yml

@@ -33,7 +33,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
 
       - name: Set up Python
         run: uv python install 3.13

{gflow_cli-0.79.1 → gflow_cli-0.81.0}/.github/workflows/governance-advisory.yml

@@ -25,7 +25,7 @@ jobs:
           fetch-depth: 0 # full history so `git diff origin/<base>..HEAD` resolves
 
       - name: Install uv
-        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
 
       - name: Classify touched paths (advisory, never blocks)
         # BASE_REF arrives through `env:`, never interpolated into the script

{gflow_cli-0.79.1 → gflow_cli-0.81.0}/.github/workflows/governance-benchmark.yml

@@ -24,7 +24,7 @@ jobs:
           fetch-depth: 0 # full history — the backtest replays every commit
 
       - name: Install uv
-        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
 
       - name: Run backtest (advisory; writes to job summary)
         run: uv run python scripts/dev/materiality_backtest.py >> "$GITHUB_STEP_SUMMARY"

{gflow_cli-0.79.1 → gflow_cli-0.81.0}/.github/workflows/release.yml

@@ -31,7 +31,7 @@ jobs:
           fetch-depth: 0
 
       - name: Install uv
-        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           # This is the one workflow that publishes artefacts (PyPI + GitHub
           # Release), so it must not restore a cache any other workflow can

{gflow_cli-0.79.1 → gflow_cli-0.81.0}/.github/workflows/scorecard.yml

@@ -47,6 +47,6 @@ jobs:
           retention-days: 5
 
       - name: Upload to code-scanning
-        uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4
+        uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4
         with:
           sarif_file: results.sarif

{gflow_cli-0.79.1 → gflow_cli-0.81.0}/.github/workflows/selector-probe.yml

@@ -16,7 +16,7 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with: { persist-credentials: false }
-      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
       - run: uv sync --frozen
       - run: uv run playwright install chromium --with-deps
       - name: Probe

{gflow_cli-0.79.1 → gflow_cli-0.81.0}/AGENTS.md

@@ -46,7 +46,7 @@ by construction, so Codex / Cursor / Aider / `agy` read exactly what Claude Code
 
 - Python CLI and MCP server for [Google Flow](https://labs.google/fx/tools/flow) — drives Veo (image-to-video, text-to-video) and Imagen (text-to-image) generations from the terminal by reverse-engineering Flow's private REST API at `aisandbox-pa.googleapis.com` — and, for accounts Google has moved to `flow.google.com`, that frontend's `batchexecute` wire (text-to-video, image-to-video from a local `--initial-frame`, reference-to-video from local `--ref` files, and text-to-image/local-file image-to-image, today; `GFLOW_CLI_FLOW_HOST`).
 - Python 3.11+ · `uv`-managed · `hatchling` builds · Playwright Chromium transport · `pyright` strict · `ruff` · `pytest`.
-- Single-package modular monolith. Top-level modules under `src/gflow_cli/`: `api/`, `auth/`, `data/`, `mcp/`, `services/`, `tools/`, `ui/`, `worker/`, `browser_manager.py`, `cli.py`, `_cli_helpers.py`, `diagnostics.py`, `json_output.py`, `media.py`, `profile_lease.py`, `redaction.py`, `storage.py`, `winsec.py`, `cli_project.py`, `cli_character.py`, `cli_credits.py`, `cli_data.py`, `cli_image.py`, `cli_instructions.py`, `cli_models.py`, `cli_movie.py`, `cli_run.py`, `cli_scene.py`, `cli_tools.py`, `cli_video.py`, `chain.py`, `chain_manifest.py`, `cli_doctor.py`, `cli_update.py`, `composition.py`, `config.py`, `errors.py`, `file_integrity.py`, `flow_selectors/`, `update_check.py`, `exceptions.py`, `image_batch.py`, `movie_manifest.py`, `observability.py`, `paths.py`, `profile_store.py`.
+- Single-package modular monolith. Top-level modules under `src/gflow_cli/`: `api/`, `auth/`, `data/`, `mcp/`, `services/`, `tools/`, `ui/`, `worker/`, `browser_manager.py`, `cli.py`, `_cli_helpers.py`, `diagnostics.py`, `json_output.py`, `media.py`, `profile_lease.py`, `redaction.py`, `storage.py`, `winsec.py`, `cli_project.py`, `cli_character.py`, `cli_credits.py`, `cli_data.py`, `cli_image.py`, `cli_instructions.py`, `cli_models.py`, `cli_movie.py`, `cli_run.py`, `cli_scene.py`, `cli_tools.py`, `cli_video.py`, `chain.py`, `chain_manifest.py`, `cli_doctor.py`, `cli_docs.py`, `docs_catalog.py`, `cli_update.py`, `composition.py`, `config.py`, `errors.py`, `file_integrity.py`, `flow_selectors/`, `update_check.py`, `exceptions.py`, `image_batch.py`, `movie_manifest.py`, `observability.py`, `paths.py`, `profile_store.py`.
 - Command surface: `gflow auth`, `gflow credits` (user/list — read-only Veo balance), `gflow image` (t2i/i2i/batch/upload/upscale), `gflow video` (t2v/i2v/r2v/chain/extend — `extend` continues an existing clip past Flow's 8s ceiling, server-seeded from the source so the join is continuous; no `batch` subcommand; the nonfunctional stub was removed, loop `gflow video t2v`/`i2v` from the shell for multi-clip runs), `gflow character` (create/list/show/rm/voices — reusable project-scoped Flow Character entities), `gflow scene` (create/show — Add Clip / Scenes, with `create --output` for credit-free server-side extended video), `gflow instructions` (persistent Agent-Mode brief cards — add/list/enable/disable/rm/apply/toggle-mode, credits-free, `--project` required), `gflow movie` (run/template — multi-scene manifest pipeline), `gflow tools` (list/show/run — prompt-rewriting tools, also `--tool` on generation commands), `gflow data` (catalog queries), `gflow docs` (browse the bundled documentation — bare lists every topic, `gflow docs <topic>` prints one as Markdown, `gflow docs --search TERM` searches all of them; there are **no** `list`/`print`/`search` subcommands — read-only, offline, deliberately no MCP twin), `gflow doctor` (read-only pre-flight diagnostic, exit 33 = findings present), `gflow update` (self-update through the installer that put it here — uv tool / pipx / pip; `--check` only reports; source installs refused, exit 11; deliberately no MCP twin), `gflow project`, `gflow models`, `gflow run`, `gflow mcp` (run/setup — stdio MCP server), and `gflow serve` (Streamable HTTP at `/mcp`; `--transport sse` is deprecated).
 - Works with any Google account that has Flow access. All generations bill against the user's own Google account.
 
@@ -97,11 +97,12 @@ the five other mirror axes), which no command here can check and no CI gate can
 > 2026-09-02). Two lists that disagree means the shorter one is silently wrong.
 
 - Use `pytest -m "not live and not e2e and not smoke"` locally; full suite OOMs on small dev machines. Scope to changed dirs; trust CI for the full sweep.
+- **Parallel runs (`pytest-xdist`):** add `-n 8` (or `-n auto`) to cut the offline suite from ~390 s to ~200 s. Every worker is a full process, so cap `-n` on a small machine. CI runs `-n auto`. A test that passes alone but fails under `-n` shares state with another test: **fix the shared state** (two measured cases: `tests/mcp/conftest.py` and `test_every_shipped_skill_is_byte_identical_to_its_source`). If two tests genuinely need the same exclusive resource (a fixed port, a file lock), mark both `@pytest.mark.xdist_group("<resource>")` so they run on one worker, one after another, while the rest stays parallel.
 - TDD is non-negotiable. Coverage floor: 80% overall.
 - Documentation is a first-class deliverable. Every behavior, workflow, config, or operator-facing change must update the relevant docs or state why no docs changed in the PR/checklist. `scripts/ci/check_doc_links.py` is a merge gate.
 - **A PR is not done until its SonarCloud gate is green (zero new issues).** The nine gates above are local/pre-commit; SonarCloud is server-side and runs in CI (`sonar.qualitygate.wait=true` → a red gate turns the `SonarCloud analysis` check red). Before calling a PR merge-ready, verify it with `/gflow:sonar <N>` (it is skipped on fork PRs — maintainer-checked there).
 - **E2E is the decisive layer, and it is required for every behavior change that touches a Flow surface.** Run the `tests/e2e/` test that covers the change, or write one — offline-green proves only that *our* code does what we think, never that Flow still behaves as captured. `/gflow:live-verify` does **not** satisfy this: it drives CLI commands by hand into a gitignored note and never runs `pytest -m e2e`. The two are complementary — an e2e test is a re-runnable regression, a live-verify ledger is a narrative record. A change touching no Flow surface at all (docs, help text, exit-code plumbing) is out of scope — say so explicitly rather than leaving it blank. Anything else follows the **Iron Law** above: run it, or name the external blocker that stops you. "A maintainer will run it" is a handoff, not a verification, and is only available once the blocker is named.
-- E2E tests require `GFLOW_CLI_E2E_PROFILE` and `-m e2e` (excluded from the default `addopts`, so they never run by accident). Cost sub-markers: `e2e_auth` (zero credits, browser only), `e2e_image` (zero credits, daily cap), `e2e_scene`, `e2e_data`, `e2e_batch`, `e2e_character` (opt in with `GFLOW_CLI_E2E_RUN_CHARACTER=1`), `e2e_video` (spends Veo credits — opt in with `GFLOW_CLI_E2E_RUN_VIDEO=1`). Redact account identifiers and any token or cookie value before pasting output into a PR.
+- E2E tests require `GFLOW_CLI_E2E_PROFILE` and `-m e2e` (excluded from the default `addopts`, so they never run by accident). Cost sub-markers: `e2e_auth` (zero credits, browser only), `e2e_image` (zero credits, daily cap), `e2e_scene`, `e2e_data`, `e2e_batch`, `e2e_character` (opt in with `GFLOW_CLI_E2E_RUN_CHARACTER=1`), the migrated refusal e2e (`e2e_image`, opt in with `GFLOW_CLI_E2E_RUN_REFUSAL=1` — it sends one corrupted reCAPTCHA token, so run it on a probe profile), `e2e_video` (spends Veo credits — opt in with `GFLOW_CLI_E2E_RUN_VIDEO=1`). Redact account identifiers and any token or cookie value before pasting output into a PR.
 - Live tests (`@pytest.mark.live`) opt in via `GFLOW_LIVE=1`.
 
 ## Code style

{gflow_cli-0.79.1 → gflow_cli-0.81.0}/CHANGELOG.md

@@ -6,6 +6,109 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+
+## [0.81.0] — 2026-09-30
+
+### Added
+
+- **The generation browser opens off-screen (#923).** Headed Chrome is required, so until
+  now every `image`/`video` run put a Chrome window over your desktop. It now opens at
+  `-30000,-30000`. It is still fully headed, so Flow and reCAPTCHA see the same browser.
+  Image and video generation were measured unchanged, and the page is not throttled.
+  `GFLOW_CLI_BROWSER_WINDOW_POSITION` takes any `X,Y` to place it where you want (to watch
+  a run or clear a consent screen by hand); empty restores Chrome's own placement. It
+  does not stop Chrome taking keyboard focus at launch. Login windows are unaffected. See
+  [docs/CONFIGURATION.md](docs/CONFIGURATION.md#gflow_cli_browser_window_position).
+  Thanks to @johngbl for the idea and the first implementation.
+
+### Security
+
+- **Locked `urllib3` 2.8.0 (CVE-2026-97687, CVE-2026-97688, CVE-2026-97689).**
+  Transitive only — via `requests` and, with the `s3` extra, `botocore`. No gflow
+  code imports it directly.
+
+### Fixed
+
+- **Windows profile write-denial is distinguished from browser contention.** When
+  the generation client's browser launch fails with a Chrome `ProcessSingleton`
+  error carrying Windows access-denied code 5, it now raises `ProfileAccessError`
+  (configuration exit code 11) instead of a misleading "another Chrome holds it"
+  `ProfileLockedError` or an unclassified error. The match is on the error code,
+  so it works in every Windows display language. The remediation points to
+  profile-directory write access, not to closing a competing Chrome. Not covered
+  yet: `gflow auth login` / auth verification, and the standalone and experimental
+  transport launches — those still surface Chrome's raw error.
+  Thanks @L1meSn0w for the diagnosis and the Windows reproduction (#919).
+
+## [0.80.0] — 2026-09-29
+
+### Security
+
+- **Locked `oauthlib` 4.0.0 (CVE-2026-49265) and `pyjwt` 2.15.1 (CVE-2026-102274).**
+  Both are transitive: `oauthlib` via the `gcs` extra (`gcsfs` → `google-auth-oauthlib`
+  → `requests-oauthlib`), `pyjwt` via `mcp[crypto]`. No gflow code imports either directly.
+
+### Added
+
+- **Explicit video resolution control (`--resolution [360p|720p]`, #787).** Added `--resolution`
+  to `gflow video t2v`, `i2v`, and `r2v`, as well as MCP tool `gflow_generate_video`.
+  Enables explicit selection of `360p` or `720p` on models providing resolution controls
+  (such as `omni-flash`), preventing unintended defaults.
+- **Support for Nano Banana 2 Lite (`--model nano2-lite`, #787).** Added `nano2-lite` alias mapped
+  to Google's internal `HARBOR_SEAL` wire model for `gflow image t2i`, `i2i`, and `batch`. Its I2I reference
+  cap starts at 3 because it has not been measured yet, and its daily quota is
+  unmeasured too ([spike](docs/superpowers/spikes/2026-09-11-nano2-lite-capability.md)).
+
+### Fixed
+
+- **An unported image form is refused by name, on a fresh or a reused client (#891).**
+  The browser transport no longer pre-mints a reCAPTCHA token for images: Flow's page
+  mints its own, and the client's token was never read. After a successful image the
+  pre-mint ran on the parked `about:blank` page and turned exit 36 into a misleading
+  `RecaptchaError`. The refusal now comes from the composer and names the form, e.g.
+  "the IMAGEN_3_5 model is not ported yet". Reachable from `gflow run --config` with a
+  per-prompt `imagen4` after a successful prompt: that run used to crash with exit 1 and
+  lose its results table; now the prompt fails by name and the run completes. This
+  corrects the 0.78.0 note that project-less image runs "keep the served host": the
+  client creates the project first, so they are served by the migrated composer. The HTTP
+  image transports still mint.
+- **A clip whose download connection dropped is no longer recorded as never generated
+  (#896, #898).** When Flow reports a video done but the signed-media connection drops
+  on every retry, the catalog now marks the asset `MEDIA_GENERATION_STATUS_SUCCESSFUL`
+  rather than leaving it `pending` forever. The operation's `error_type` is
+  `media-download` (still exit 6), so `gflow data list errors` tells a lost transfer from
+  a failed generation. `gflow data list videos` gains a `STATUS` column and a `status`
+  field in `--json`. An HTTP error answer on the signed URL still leaves the asset
+  `pending`. **Changed:** that failure's Problem Details `type` is now
+  `…/errors/media-download` (a subclass of the `network` error, same exit code).
+- **A generation flow.google.com refuses is now reported as that refusal, by name (#906, #873).**
+  Flow answers a refused submit with HTTP 200 and a `batchexecute` error envelope carrying
+  Google's reason (`PUBLIC_ERROR_UNUSUAL_ACTIVITY`), but gflow's parser discarded any frame
+  without a payload. So a refusal ended as a retryable 60 s video timeout (exit 9) or an image
+  "no ogiZ0b frame" wire fault (exit 7), whose remediation tells you to file a frontend bug.
+  It is now `WafRejectionError` (exit 10) — the class the labs path has always used for the same
+  reason — with a remediation that says the prompt is not the cause and nothing was charged. The
+  content-safety reasons map to `ContentPolicyError` (exit 5) as on the REST path. Read from the
+  wire, not from the grid's failure card, which looks identical for a refusal and an aborted
+  submit ([spike](docs/superpowers/spikes/2026-09-27-migrated-refusal-is-on-the-wire.md)).
+  The refusal was observed live on the image submit; the video submit reads the same framing
+  and is covered offline, but a live video refusal has not been captured yet.
+  Diagnosed by [@stgmt](https://github.com/stgmt) in #873 and #906; this change supersedes
+  #873 and the refusal-card half of #907.
+
+- **`gflow auth login` no longer reports success while Google is waiting for the account to
+  "Confirm it's you" (#902).** In that state the cookies stay valid, so the session probe
+  answered in 0.4 s and the login closed Chrome before Flow's client-side hop to
+  `flow.google.com/about` could land. It then printed `[OK] Flow session verified` on an
+  account where every command still exited 31. The login now watches a `flow.google.com`
+  landing for up to 3 s before it closes. If Flow routes the page to `/about`, Chrome stays open
+  and the user is told to press the page's main button and finish Google's check. Closing the
+  window or running out of time in that state exits 12 with the new
+  `IdentityRecheckPendingError`. The #849 on-disk check is skipped in that case, because it reads
+  the same healthy cookies. A labs-served login closes as fast as before. The failing state is
+  tested offline only: the one account measured in it (2026-09-23) had already been cleared by
+  hand, and none of the profiles here is in that state now.
+
 ## [0.79.1] — 2026-09-22
 
 ### Fixed
@@ -5638,7 +5741,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.79.1...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.81.0...HEAD
+[0.81.0]: https://github.com/ffroliva/gflow-cli/compare/v0.80.0...v0.81.0
+[0.80.0]: https://github.com/ffroliva/gflow-cli/compare/v0.79.1...v0.80.0
 [0.79.1]: https://github.com/ffroliva/gflow-cli/compare/v0.79.0...v0.79.1
 [0.79.0]: https://github.com/ffroliva/gflow-cli/compare/v0.78.0...v0.79.0
 [0.78.0]: https://github.com/ffroliva/gflow-cli/compare/v0.77.1...v0.78.0

{gflow_cli-0.79.1 → gflow_cli-0.81.0}/KNOWN_ISSUES.md

@@ -14,14 +14,46 @@ Living list of behaviour that's broken, surprising, or limited by design — alo
 
 ## Open
 
+### Every command lands on `flow.google.com/about` (exit 31) while `gflow auth status` says the session is fine
+
+- **Status:** Open · **Severity:** High for the affected account (nothing runs) · **Affected:** measured on one account (`denon82`, 2026-09-23). Other `/about` occurrences are not yet shown to share the cause.
+- **Tracked:** [#902](https://github.com/ffroliva/gflow-cli/issues/902) (`auth login` cannot clear it) · [#888](https://github.com/ffroliva/gflow-cli/issues/888) · [#756](https://github.com/ffroliva/gflow-cli/issues/756)
+- **Evidence:** [spike](docs/superpowers/spikes/2026-09-23-about-cta-leads-to-google-reauth.md)
+
+Flow sends every visit to its public landing page `/about`, while every Google and Flow cookie
+gflow checks is present and unexpired. On the measured account, the page's "Create with Google
+Flow" button led to Google's **"Confirm it's you — sign in again to continue"** page: Google was
+waiting for the account to re-verify its identity.
+
+**Through v0.79.1, `gflow auth login` does not fix it.** It sees the valid cookies, reports
+`Flow session verified` in about half a second, and closes Chrome before Google can ask (#902).
+From the next release, the login watches where the page lands. If Flow sends it to `/about`, the
+login keeps Chrome open and asks you to press the page's main button and finish "Confirm it's
+you". If you close the window or the time limit runs out first, it exits 12
+(`IdentityRecheckPendingError`) instead of reporting success. The failing state could not be
+reproduced live for this fix, because the one measured account was already cleared by hand. The
+detection is tested offline only.
+
+**Workaround (needs the account password):** with no gflow command running, open real Chrome on
+the profile directory yourself:
+
+```bash
+"<chrome.exe>" --user-data-dir="<GFLOW_CLI_HOME profile dir, e.g. …/profile_<name>>" --password-store=basic https://flow.google.com/
+```
+
+Click the landing page's main button, complete "Confirm it's you", wait for the Flow editor, then
+close Chrome yourself. On the measured account, `/about` was gone on the next run and
+`gflow project create` succeeded.
+
 ### Flow is migrating to `flow.google.com`; generation coverage is partial but includes images
 
-- **Status:** Open (partially resolved) · **Severity:** High for unported forms · **Affected:** on accounts the rollout has reached, `gflow video t2v`, local-file `video i2v` / `r2v`, `gflow image t2i`, and local-file `gflow image i2i` now run on the migrated host. Image mode supports Nano Banana 2 / Pro, all five aspect ratios its radiogroup renders (16:9, 4:3, 1:1, 3:4, 9:16 — 3:4 appeared by 2026-09-17, #864), and count 1–4. Image refs by UUID, `@Name` / `--reference-entity`, Agent instructions, Imagen 4, video frame refs by UUID/name, scenes, extend, instructions and tools are not ported yet and fail before submit. **`character create` is NOT in that list any more** — it works on the migrated host. `character list` does NOT: it reads the retired labs `projectInitialData` route and exits 7, measured 2026-09-20 both on `auto` and with `GFLOW_CLI_FLOW_HOST=flow.google.com` (#875). Of the remainder, only the i2v-by-UUID case rests on a positive observation of absence (the Frames picker tiles carry no media id); `scenes`, `extend`, `instructions` and `tools` remain *unported by gflow*, never proven impossible on the host.
+- **Status:** Open (partially resolved) · **Severity:** High for unported forms · **Affected:** on accounts the rollout has reached, `gflow video t2v`, local-file `video i2v` / `r2v`, `gflow image t2i`, and local-file `gflow image i2i` now run on the migrated host. Image mode supports Nano Banana 2 / 2 Lite / Pro, all five aspect ratios its radiogroup renders (16:9, 4:3, 1:1, 3:4, 9:16 — 3:4 appeared by 2026-09-17, #864), and count 1–4. Image refs by UUID, `@Name` / `--reference-entity`, Agent instructions, Imagen 4, video frame refs by UUID/name, scenes, extend, instructions and tools are not ported yet and fail before submit. **`character create` is NOT in that list any more** — it works on the migrated host. `character list` does NOT: it reads the retired labs `projectInitialData` route and exits 7, measured 2026-09-20 both on `auto` and with `GFLOW_CLI_FLOW_HOST=flow.google.com` (#875). Of the remainder, only the i2v-by-UUID case rests on a positive observation of absence (the Frames picker tiles carry no media id); `scenes`, `extend`, `instructions` and `tools` remain *unported by gflow*, never proven impossible on the host.
 - **Tracked:** [#639](https://github.com/ffroliva/gflow-cli/issues/639) · Reported 2026-09-02 against 0.59.0, 0.62.1, 0.63.0 and 0.65.0
 - **Confirmed live 2026-09-03 on a second, independent account** (`ffroliva`) — see [LIVE_VERIFICATION_v0.66.0](docs/LIVE_VERIFICATION_v0.66.0.md). A read-only probe of the migrated origin measured `i_total: 0`, reproducing the reporter's central measurement.
 - **`--reference-entity` was refused on `r2v` but not on `t2v`** ([#716](https://github.com/ffroliva/gflow-cli/issues/716), fixed in v0.71.0): the "not ported, exit 36" refusal above sat inside the r2v branch of the routing gate, so a `t2v` request carrying a character entity returned from that gate without its entities ever being inspected — and nothing downstream attaches one on this host. The generation was **submitted and billed** with the entity silently dropped, returning a plausible clip of the wrong person. The check is now mode-independent and ahead of every early return. If you ran `gflow video t2v @Name …` or `--reference-entity` on a moved account before this fix, the identity in those clips was never bound.
 - **The migrated composer image path is now driven** ([#692](https://github.com/ffroliva/gflow-cli/issues/692)): the first probe established a hit-testable Image mode; the 2026-09-08 follow-up captured real T2I and local-file I2I submissions on `ogiZ0b`, including page-owned reCAPTCHA, upload ids, response records and signed JPEG downloads. See [the submit-wire spike](docs/superpowers/spikes/2026-09-08-migrated-image-submit-wire.md).
-- **Image commands on a moved account** ([#673](https://github.com/ffroliva/gflow-cli/issues/673), fixed in v0.69.0): through v0.68.0 `image t2i` / `i2i` (and `upscale`, `extend`) died with exit 1 `RecaptchaError` within seconds, before any submit, instead of the exit 36 above, because the labs client minted the reCAPTCHA token on the `flow.google.com` project grid before any migration guard ran. The guard now runs at the mint. If you still see a `RecaptchaError` on a moved account right after `auth login`, that is the labs logged-out landing page from the [#644](https://github.com/ffroliva/gflow-cli/issues/644) cookie harvest, not this.
+- **Image commands on a moved account** ([#673](https://github.com/ffroliva/gflow-cli/issues/673), fixed in v0.69.0): through v0.68.0 `image t2i` / `i2i` (and `upscale`, `extend`) died with exit 1 `RecaptchaError` within seconds, before any submit, instead of the exit 36 above, because the labs client minted the reCAPTCHA token on the `flow.google.com` project grid before any migration guard ran. The guard now runs at the mint; since v0.80.0 the browser transport no longer mints for images at all, and the flow.google.com composer itself refuses unported forms (#891). If you still see a `RecaptchaError` on a moved account right after `auth login`, that is the labs logged-out landing page from the [#644](https://github.com/ffroliva/gflow-cli/issues/644) cookie harvest, not this.
+- **A second image request on one client hit the same `RecaptchaError`** ([#891](https://github.com/ffroliva/gflow-cli/issues/891), fixed in v0.80.0): after a successful image on an account served flow.google.com, the page is parked on `about:blank`, and the client's pre-mint ran there, so an unported form (e.g. `--model imagen4`) failed with "the Flow editor page may have failed to load" instead of exit 36. The browser transport never used that token, so it no longer mints; the composer refuses the form by name. Reachable from `gflow run --config` with a per-prompt `"model": "imagen4"` after a successful prompt, where it also crashed the whole run (exit 1, results table lost); it now reports that prompt as exit 36 and the run completes.
 
 Google is moving Flow off Labs onto its own origin. On a migrated page load,
 `https://labs.google/fx/tools/flow/project/<id>` redirects to
@@ -935,6 +967,11 @@ find "$HOME/Downloads/gflow-cli" -type f -mtime +30 -delete
 - **Status:** Open · **Severity:** High (blocks affected profile until WAF score decays or profile is replaced)
 - **First observed:** 2026-05-23 on profile `denon82` during `gflow image batch` runs
 - **Surfaces as:** `gflow_cli.errors.WafRejectionError: WAF rejection (HTTP 403): batchGenerateImages HTTP 403 — reCAPTCHA score too low or WAF fingerprint mismatch`
+- **On flow.google.com** (measured 2026-09-27): the same reason arrives as HTTP 200 with a
+  `batchexecute` error envelope (`[7,null,[["type.googleapis.com/google.rpc.ErrorInfo",["PUBLIC_ERROR_UNUSUAL_ACTIVITY"]]]]`)
+  and surfaces as `WafRejectionError: … Flow refused the submit: PUBLIC_ERROR_UNUSUAL_ACTIVITY`.
+  Flow's grid shows *"We noticed some unusual activity… You have not been charged"*
+  ([spike](docs/superpowers/spikes/2026-09-27-migrated-refusal-is-on-the-wire.md)).
 - **structlog signature:** `ui_automation.batch_response_seen` with `status=403` followed by `ui_automation.batch_403_body` containing `'message': 'reCAPTCHA evaluation failed', 'status': 'PERMISSION_DENIED', 'reason': 'PUBLIC_ERROR_UNUSUAL_ACTIVITY'`
 
 Distinct from the historical `aisandbox-pa` 401 (resolved in v0.7.0). The 403
@@ -1414,7 +1451,9 @@ failed assert left the profile unusable — it is usable, just possibly as the w
 
 Two further items on the same issue are unfixed and worth knowing about: a second chooser
 hop (chooser → consent → chooser) is not handled and degrades into the landing timeout, and
-that timeout is still an unmeasured number.
+that timeout is still an unmeasured number. The generation browser opens off-screen since
+v0.81.0; to clear such a screen by hand, re-run with
+`GFLOW_CLI_BROWSER_WINDOW_POSITION=0,0` (see [CONFIGURATION](docs/CONFIGURATION.md#gflow_cli_browser_window_position)).
 
 ### Auth verification depends on Google's NextAuth session endpoint
 
@@ -1448,6 +1487,8 @@ key — surfaces as a `RuntimeError` that `auth/cookies.py` normalizes to
 
 Chromium refuses to open two persistent contexts on the same `user-data-dir` simultaneously. Historically this surfaced as an unhelpful Chromium "ProcessSingleton: profile is locked" error partway through a run. As of the profile-lease hardening (production-readiness plan, slice D1/D3), gflow-cli enforces this itself: a cross-process advisory lock (`ProfileLease`, kernel `flock` on POSIX / `msvcrt.locking` on Windows) guards every profile directory. A second `gflow` invocation, `gflow serve` daemon task, or MCP call against an already-leased profile is rejected **immediately** by default — before any Chrome process starts — with a typed `ProfileLockedError` (**exit code 11**); it never silently corrupts the profile. Since #478, setting [`GFLOW_CLI_LEASE_WAIT_SECONDS`](docs/CONFIGURATION.md#gflow_cli_lease_wait_seconds) opts a waiter into a bounded wait that takes over as soon as the current holder finishes (holders always run to completion and are never asked to release early; same-process contention still fails fast — waiting on yourself would deadlock). Since #864 an MCP server waits 180 s by default, and queues its own calls on one profile rather than rejecting the second.
 
+**Not every `ProcessSingleton` failure is contention.** On Windows, a `ProcessSingleton` error carrying access-denied code `(0x5)` means Chrome cannot write the profile directory; at the generation client's launch gflow reports it as `ProfileAccessError` — see [CONFIGURATION § Profile-directory permissions at browser launch](docs/CONFIGURATION.md#profile-directory-permissions-at-browser-launch).
+
 **Workaround:** use different profiles for parallel work — different profiles acquire independent leases and run fully concurrently.
 
 ### gflow refuses to open my profile after a downgrade ("written by a newer Chromium", exit 11)

{gflow_cli-0.79.1 → gflow_cli-0.81.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gflow-cli
-Version: 0.79.1
+Version: 0.81.0
 Summary: CLI and MCP server for Google Flow — drive Veo text-to-video, image-to-video and Imagen image generation from the terminal.
 Project-URL: Homepage, https://github.com/ffroliva/gflow-cli
 Project-URL: Documentation, https://ffroliva.github.io/gflow-cli/
@@ -73,8 +73,9 @@ Requires-Dist: av>=12; extra == 'dev'
 Requires-Dist: numpy>=1.24; extra == 'dev'
 Requires-Dist: pyright>=1.1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
-Requires-Dist: ruff==0.16.7; extra == 'dev'
+Requires-Dist: ruff==0.16.9; extra == 'dev'
 Provides-Extra: gcs
 Requires-Dist: gcsfs>=2024.2.0; extra == 'gcs'
 Requires-Dist: universal-pathlib>=0.2.5; extra == 'gcs'

{gflow_cli-0.79.1 → gflow_cli-0.81.0}/docker/Dockerfile

@@ -45,7 +45,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 # Deliberately NOT pinned: google-chrome-stable. Chrome's apt repo keeps only the current
 # build, so a pinned version stops resolving within weeks. The trade-off is that this
 # layer caches indefinitely and a rebuild is what picks up a newer Chrome.
-ARG GFLOW_VERSION=0.79.1
+ARG GFLOW_VERSION=0.81.0
 RUN pip install --no-cache-dir "gflow-cli==${GFLOW_VERSION}"
 
 VOLUME ["/data"]

{gflow_cli-0.79.1 → gflow_cli-0.81.0}/docs/CONFIGURATION.md

@@ -31,6 +31,22 @@ See [AUTHENTICATION § Session storage](AUTHENTICATION.md#session-storage) for t
 create it — a `tools/` directory of user-authored "My Tools" TOMLs
 (`<GFLOW_CLI_HOME>/tools/*.toml`, auto-loaded; see [TOOLS.md § My Tools](TOOLS.md)).
 
+#### Profile-directory permissions at browser launch
+
+On Windows, when a generation run's browser launch fails with a Chrome
+`ProcessSingleton` error carrying access-denied code 5, gflow reports
+`ProfileAccessError`, a configuration error (exit code 11), rather than suggesting
+contention. Ensure the process can write the complete persistent profile directory,
+or use a profile inside a writable `GFLOW_CLI_HOME`. Relocating application-level
+lease locks alone does not relocate Chrome's `ProcessSingleton`, cookies, or crash
+reports.
+
+This classification covers the generation client's launch only. `gflow auth login`,
+auth verification, and the standalone and experimental transports still
+surface Chrome's raw error for the same cause; look for `ProcessSingleton` plus
+`(0x5)` in it. Launch failures without the access-denied code keep their existing
+classification; this is not general cross-platform permission-error detection.
+
 ### `GFLOW_CLI_PROFILE`
 
 **What:** Default profile name used when `--profile` isn't passed on the CLI.
@@ -333,6 +349,53 @@ GFLOW_CLI_HISTORY_PROMPTS=redacted gflow image t2i "confidential brief"
 **Default:** `false` — **headed real Chrome is the production default**, not an opt-in fallback. The `ui_automation` transport (gflow-cli's only production transport) requires a headed browser: reCAPTCHA Enterprise rejects headless Chromium with an immediate 403, so `headless=true` is not a WAF workaround — it only exists for CI/CD environments running a non-`ui_automation` transport (e.g. `bearer`/`sapisidhash`, experimental).
 **WAF-sensitive runs:** set `GFLOW_CLI_HEADLESS=false` explicitly (it is already the default, but pin it in CI/CD env files or scripts that also set `headless=true` for a different transport, so a transport switch back to `ui_automation` doesn't silently regress to a rejected headless launch).
 
+### `GFLOW_CLI_BROWSER_WINDOW_POSITION`
+
+**What:** Where on screen the headed generation browser opens, as `X,Y` in pixels.
+**Values:** `X,Y` (integers, may be negative) | empty
+**Default:** `-30000,-30000`: off-screen. Generation needs a real **headed** Chrome (see
+[`GFLOW_CLI_HEADLESS`](#gflow_cli_headless)), and without this setting that window
+opens over whatever you are working on during every run. Off-screen it is still fully
+headed, so Flow and reCAPTCHA see exactly the same browser.
+
+| Set it to | Result |
+|---|---|
+| unset | off-screen (default) |
+| `0,0`, `1920,0`, … | the window opens there: watch a run, or park it on a second monitor |
+| empty (`GFLOW_CLI_BROWSER_WINDOW_POSITION=`) | Chrome's own placement, the behaviour before this setting existed |
+
+**When to bring it back on-screen:** a run that waits on something only a person can
+clear, such as an account chooser that wants a click or a Google consent or
+verification screen. The error names where the session stopped. Set a visible
+position, re-run, and deal with it in the window. (Flow's one-time *rights to use this
+image* confirmation has its own remedy: see
+[KNOWN_ISSUES](../KNOWN_ISSUES.md).)
+
+**What it does not do:** it does not stop Chrome **taking keyboard focus** when it
+launches: the `--no-focus-on-init` switch we tried made no measurable difference. If you are typing when a run starts, the
+first keystrokes can land in the (invisible) browser. Login (`gflow auth login`) is
+unaffected and always opens where you can see it.
+
+**Measured (Windows 11, 2026-09-30):** off-screen and visible runs behaved the same.
+
+| | off-screen | visible |
+|---|---|---|
+| `gflow image t2i` | image saved, 34 s | image saved, 33 s |
+| `gflow video t2v` (`veo-lite`) | video saved, 53 s, no poll stalls | video saved, 65 s, no poll stalls |
+| page `visibilityState` | `visible` | `visible` |
+| animation frames / 100 ms timer ticks in 5 s | 300 / 50 | 295 / 50 |
+
+Chrome does not throttle an off-screen window: the page still counts as visible.
+Windows clamps very large offsets, so `-30000,-30000` lands at `-21845,-21845`, still
+past any monitor, on every launch measured. A visible position such as `100,100` opened
+exactly there on 8 of 10 launches. In the other two the window was found elsewhere, and
+once it was seen moving mid-run: a visible window can be moved like any other once it
+is open. Not yet measured on macOS or
+Linux, or for runs whose polling lasts longer than about five minutes.
+Measurement script: `scripts/dev/spike_offscreen_window.py`.
+
+**Malformed values** (`100`, `1,2,3`, `a,b`) fail at startup with a validation error.
+
 ### `GFLOW_CLI_BROWSER_ENGINE`
 
 **What:** Selects the browser-automation engine backing the Playwright API.
@@ -365,7 +428,7 @@ GFLOW_CLI_HISTORY_PROMPTS=redacted gflow image t2i "confidential brief"
 - `flow.google.com` — force the migrated composer for everything, including what it cannot serve yet (those requests then exit 36/11 instead of falling back).
 - `labs.google` — never use the migrated composer; where Flow serves `flow.google.com`, requests fail with exit 36 (kill switch).
 **Default:** `auto`
-**Scope today:** the migrated composer covers `gflow video t2v`, local-file `video i2v` / `r2v`, `gflow image t2i`, and local-file `gflow image i2i`. Images support Nano Banana 2 / Pro, all five aspect ratios (16:9, 4:3, 1:1, 3:4, 9:16 — `3:4` was added to that host's radiogroup by 2026-09-17, #864) and count 1–4; the page owns the `ogiZ0b` reCAPTCHA + submit and the response already contains completed signed image URLs. Local-file start+end frames (`--initial-frame` + `--end-frame`) are ported (#639). Frames or references given by UUID/`@Name`, character entities, Agent instructions, Imagen 4, scenes, extend, instructions and tools are not ported yet and fail before submit where Flow serves flow.google.com. MCP uses the same image service and queue payload, and inherits this setting from the server/daemon environment rather than per call.
+**Scope today:** the migrated composer covers `gflow video t2v`, local-file `video i2v` / `r2v`, `gflow image t2i`, and local-file `gflow image i2i`. Images support Nano Banana 2 / 2 Lite / Pro, all five aspect ratios (16:9, 4:3, 1:1, 3:4, 9:16 — `3:4` was added to that host's radiogroup by 2026-09-17, #864) and count 1–4; the page owns the `ogiZ0b` reCAPTCHA + submit and the response already contains completed signed image URLs. Local-file start+end frames (`--initial-frame` + `--end-frame`) are ported (#639). Frames or references given by UUID/`@Name`, character entities, Agent instructions, Imagen 4, scenes, extend, instructions and tools are not ported yet and fail before submit where Flow serves flow.google.com. MCP uses the same image service and queue payload, and inherits this setting from the server/daemon environment rather than per call.
 
 ### `GFLOW_CLI_PREFER_CLASSIC` *(deprecated — use `GFLOW_CLI_UI_MODE=classic`)*
 
@@ -557,5 +620,7 @@ gflow image t2i "test idea" --profile experiments
 | `ValidationError: GFLOW_CLI_TIMEOUT_SECONDS must be a positive integer` | Bad `.env` value | Set to a number ≥ 1 |
 | `FileNotFoundError: $GFLOW_CLI_HOME/profile_default not found` | First run, no auth yet | `gflow auth login` |
 | `AuthExpiredError` | Cookies expired or revoked | `gflow auth login --profile <name>` |
+| A run waits, then times out on an account chooser, consent or verification screen | The generation browser opens off-screen, so you cannot click it | Re-run with `GFLOW_CLI_BROWSER_WINDOW_POSITION=0,0` (or empty) and clear the screen in the window. See [`GFLOW_CLI_BROWSER_WINDOW_POSITION`](#gflow_cli_browser_window_position) |
+| `ProfileAccessError` (exit code 11) | Chrome cannot write the profile directory (Windows access denied) | Grant write access to the whole profile directory, or use a writable profile. See [Profile-directory permissions](#profile-directory-permissions-at-browser-launch) |
 | Output files don't appear where I expect | Flag > env > .env > default — check actual resolved path | `gflow image t2i ... --verbose` shows the resolved output path |
 | `ProfileLockedError` (exit code 11) | Two concurrent calls against the same profile — the cross-process `ProfileLease` fails fast (never waits) on same-profile contention, whether the second holder is another `gflow` process, the `gflow serve` daemon, or an MCP call | Wait for the first call to finish, or use `--profile other` — different profiles run fully in parallel, each with its own lease |

{gflow_cli-0.79.1 → gflow_cli-0.81.0}/docs/DATA_LAYER.md

@@ -206,6 +206,11 @@ async worker (which mirrors its `generation_queue.error_json` failure into
   `count>1` request fires the callback per output — no sibling row is
   stranded); failures before `on_started`, and all image failures, INSERT a
   fresh row with full request metadata.
+- A download whose connection drops on every retry AFTER Flow reported the clip done
+  (`MediaDownloadError`, exit 6, `error_type=media-download`, #896) also marks that
+  clip's asset `MEDIA_GENERATION_STATUS_SUCCESSFUL`: the operation failed, the
+  generation did not, and `gflow data download <media_id>` recovers it for free. An
+  HTTP error answer on the signed URL (e.g. an expired link) still leaves it `pending`.
 - A poll that COMPLETES with a Flow-reported failure (`succeeded=false`) is
   recorded as `failed` with `error_type=generation-failed` and the
   `failure_reasons` as detail — not as a success.
@@ -334,6 +339,10 @@ By default, `images` and `videos` aggregate rows by Flow media ID. If an asset
 has multiple local copies (e.g. re-downloaded to different paths), they appear
 as a single row with a `COPIES` count and the path of the latest copy.
 
+`videos` also shows the asset `STATUS` (`status` in `--json`): `pending` until Flow
+reports the clip done, then `MEDIA_GENERATION_STATUS_SUCCESSFUL` — including when only
+the download failed (#896). Images are recorded `ready`.
+
 TTY stdout → Rich table; pipe or `--json` → JSONL. Default sort: newest first. Exit code 16 on data-store errors (same `DataStoreError` family as `gflow data media`). A **missing or freshly-created** DB is NOT a data-store error — `data list` auto-creates the schema via `DataStore.open()` and returns exit 0 with an empty result (see [#88](https://github.com/ffroliva/gflow-cli/issues/88)).
 
 > **`data list profiles` vs `gflow auth list`:** `data list profiles` shows profiles that have **recorded generations** in the catalog; `gflow auth list` shows profiles that have ever **logged in** via `gflow auth login`. A profile that logged in but never generated anything will appear in `auth list` but not in `data list profiles`.
@@ -535,9 +544,10 @@ See [`errors.py::EXIT_CODE_MAP`](../src/gflow_cli/errors.py) for the complete ex
 Distinct from the above (which are errors OF the data layer), the
 `operations.error_type` column stores the taxonomy of RECORDED generation
 failures — the last segment of each exception's `problem_type` URI. Common
-values: `waf-rejection` (HTTP 403 / WAF), `content-policy`, `auth-expired`,
+values: `waf-rejection` (reCAPTCHA/WAF refusal — labs HTTP 403, or a flow.google.com `PUBLIC_ERROR_UNUSUAL_ACTIVITY` envelope), `content-policy`, `auth-expired`,
 `transport-timeout`, `wire-format`, `rate-limit`, `ui-mode-unavailable`
-(cohort pin), `media-attribution`. Query them with `gflow data list errors`.
+(cohort pin), `media-attribution`, `media-download` (the clip was generated; only
+the transfer failed — recover it with `gflow data download`). Query them with `gflow data list errors`.
 
 ---
 

{gflow_cli-0.79.1/website → gflow_cli-0.81.0}/docs/DEBUGGING.md

@@ -257,8 +257,9 @@ First visible-and-clickable wins. Log:
 | `AuthExpiredError` | 3 | Session cookies no longer valid | `gflow auth login --profile <name>` |
 | `AuthBrowserRejectedError` | 14 | Google's sign-in rejected the browser for advertising automation; only the `internal` strategy surfaces it | Re-run `gflow auth login` (default `auto` picks the `chrome` strategy, which retries on a no-automation path) |
 | `AuthLoginTimeoutError` | 12 | User did not finish the OAuth flow in time | Run `gflow auth login` again; raise `GFLOW_CLI_AUTH_LOGIN_TIMEOUT` |
+| `IdentityRecheckPendingError` | 12 | Login ended while Flow was still sending the account to `/about` because Google wants it to "Confirm it's you" (#902) | Run `gflow auth login` again, press the page's main button, and finish Google's check until the Flow app loads |
 | `TransportTimeoutError` | 9 | A single API call exceeded its timeout | Retry; check Flow status |
-| `WafRejectionError` | 10 | reCAPTCHA / WAF blocked the request | Wait + retry; verify session is healthy |
+| `WafRejectionError` | 10 | reCAPTCHA / WAF blocked the request (`PUBLIC_ERROR_UNUSUAL_ACTIVITY`) | Stop on that profile — each rejected request can raise its score. Wait hours or switch profile; see [ACCOUNT_SAFETY § When Google does push back](ACCOUNT_SAFETY.md#when-google-does-push-back) |
 
 For health probes from a worker process, use
 `FlowApiClient.health_check()` — it returns `bool` and never raises.

{gflow_cli-0.79.1 → gflow_cli-0.81.0}/docs/E2E_TESTING.md

@@ -155,6 +155,7 @@ test, not a mocked proxy — the Bug Lane's step 5.
 | `GFLOW_CLI_E2E_VIDEO_ASPECT` | `"landscape"` | Aspect ratio for video e2e: `landscape` or `portrait`. |
 | `GFLOW_CLI_E2E_VIDEO_MODEL` | `"omni-flash"` | Veo model for i2v tests: `omni-flash` or `veo-fast`. |
 | `GFLOW_CLI_E2E_VIDEO_DURATION` | `"4"` | Seconds of video to generate in i2v tests (minimum credit unit). |
+| `GFLOW_CLI_E2E_RUN_REFUSAL` | `"0"` | Set to `"1"` to run the migrated refusal e2e (`e2e_image`): one image submit goes out with its reCAPTCHA token corrupted so Flow refuses it, proving the refusal is reported as `WafRejectionError`. Zero credits, but a refused token can raise the profile's WAF score for hours, so run it **alone** and on a probe profile, never before other image tests in the same session. |
 | `GFLOW_CLI_E2E_RUN_ENTITY_PROV` | `"0"` | Set to `"1"` to run the entity-provenance e2e (#402) — asserts a generation Flow actually accepted records its `entity_ids` / `entity_names` in `operations.metadata_json`. Opt-in because it drives a real browser generation (no credit cost — images are free). |
 | `GFLOW_CLI_E2E_BATCH_MANIFEST` | `test_assets/sample_batch.tsv` | TSV manifest for the batch image e2e. |
 | `GFLOW_CLI_E2E_BATCH_JITTER` | `"1"` | Set to `"0"` to disable inter-request jitter in batch tests. |