gflow-cli 0.29.0__tar.gz → 0.30.0__tar.gz

{gflow_cli-0.29.0 → gflow_cli-0.30.0}/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.30.0] — 2026-07-09
+
+### Added
+
+- **MCP `gflow_generate_video` model/duration/count parameters (CLI↔MCP parity):** agents can now select the Veo model (`veo_lite`/`veo_fast`/`veo_quality`/`omni_flash`, aliases accepted), clip duration, and batch count through MCP, matching the CLI `gflow video` flags. An unknown model is rejected up front with a 400 instead of failing deep in the worker; an omitted model still lets the transport apply its i2v veo-lite default (issue #125). Co-authored-by C1ph3r404 (from the closed PR #258). Note: the pre-existing transport-level i2v veo-lite default already protected the MCP path, so this is parity + agent control, not a new credit guard.
+
+### Fixed
+
+- **Character-create recorder no longer crashes on a duplicated `flow_media_id`.** Under the agentic cohort the classic character-editor slot-add control is absent, so the body prompt lands in the still-active face slot and both slots report the same `flow_media_id`; `_record_character_local_files` minted a fresh asset `id` per slot and the second slot violated `UNIQUE(profile_name, flow_media_id)` → `DataIntegrityError`. The recorder now reuses the existing asset id (mirroring `record_completed_video`), making character local-file recording idempotent on the business key. Regression test in `tests/data/test_recorder_character.py`.
+- **`prefer_classic` no longer logs a misleading `WARNING` on the agentic cohort.** The server-gated agentic (`tune`) cohort cannot be exited client-side, and `prefer_classic` is best-effort by contract, so `get_ui_driver` now logs that expected fall-through at `INFO` (`ui_driver.prefer_classic.cohort_natively_agentic`) and reserves `WARNING` for genuinely unexpected exit failures.
+
 ## [0.29.0] — 2026-07-09
 
 ### Added
@@ -1887,7 +1898,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.29.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.30.0...HEAD
+[0.30.0]: https://github.com/ffroliva/gflow-cli/compare/v0.29.0...v0.30.0
 [0.29.0]: https://github.com/ffroliva/gflow-cli/compare/v0.28.0...v0.29.0
 [0.28.0]: https://github.com/ffroliva/gflow-cli/compare/v0.27.1...v0.28.0
 [0.27.1]: https://github.com/ffroliva/gflow-cli/compare/v0.27.0...v0.27.1

gflow_cli-0.30.0/GEMINI.md

@@ -0,0 +1,37 @@
+# GEMINI.md
+
+> Project memory hub for **Gemini CLI**. The universal coding-agent rules for any tool (Cursor, Codex, Aider, Gemini CLI, etc.) live in [AGENTS.md](AGENTS.md) — this file carries Gemini-specific session protocol only.
+
+## What this project is
+
+`gflow-cli` is an unofficial Python CLI that drives [Google Flow](https://labs.google/fx/tools/flow) (Veo image-to-video, Imagen text-to-image) from the terminal by reverse-engineering Flow's private REST API. See [README.md](README.md) for the user-facing overview.
+
+## On every session start
+
+1. Read **[AGENTS.md](AGENTS.md)** — universal rules every agent must follow.
+2. Read **[docs/INDEX.md](docs/INDEX.md)** — routing layer for all project docs and commands.
+3. Pull deeper context on demand (type as plain text in the `agy` TUI prompt):
+   - Current task / where we left off → `gflow:status`
+   - Starting a new feature → `gflow:predict` → `gflow:scenario` → `gflow:plan <feature>`
+   - Touching auth or reCAPTCHA → `gflow:known-issues`
+   - Cutting a release → `gflow:release`
+   - Before any commit → `gflow:check`
+
+## Gemini-specific
+
+- Use specialized skills when relevant (e.g., `find-docs` for library research, `pr-council-review` for PR audits).
+- Maintain memory via the `mcp-mempalace` tool if available.
+- Prioritize **turn efficiency** and **high-signal output**.
+
+## Active phase
+
+- **v0.29.0 shipped (2026-07-09):** persistent `gflow instructions` CRUD + movie-manifest instructions brief-sync + six `gflow_instructions_*` MCP tools, with a CI-enforced MCP↔CLI parity contract (`tests/mcp/test_cli_parity.py`) and the agentic-indicator selectors consolidated onto `drivers/factory.py`. Released to PyPI; issue #192 closed.
+- **PR #258 (Camoufox stealth engine, external contribution) — taken over and CLOSED-OUT (2026-07-09).** A 5-persona `/gflow:predict` rejected a rebase in favour of a decomposed, evidence-gated series: Phase 1 landed the MCP video param parity (#273, contributor-credited); a WAF-evidence harness (#274/#275) measured a **0.0% WAF 403 rate over 20 live generations**, so per ADR-13 the Camoufox engine was **NOT built** (#276). The i2i "UUID-ref bug" was investigated and found not-a-bug (#277, stale comment fixed). Contributor thanked + credited on the closed PR. Evidence: `docs/superpowers/spikes/2026-07-09-camoufox-waf-403.md`.
+- **Decoupled Daemon/Worker Plan:** The MCP→FlowWorker wiring shipped in v0.23.0 (PR #228). The remaining headless SSE Daemon + Tauri/React editor blueprint is scheduled in [gflow-studio-scaffold/PLAN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-24-gflow-studio-scaffold/PLAN.md) and [rest-api-layer/PLAN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-24-rest-api-layer/PLAN.md).
+- **Core Lesson (Retrospective):** 
+  - **Verify before adopting — measure, don't assume.** The PR #258 takeover's value was checking every claim against the real code and real data instead of adopting on assertion: a stealth engine we didn't build (0% WAF baseline), a "credit guard" already enforced one layer down, a `display_name` already shipped in v0.26.0, an i2i "bug" that wasn't one, and a concurrency bug that never merged. Five claims, five dismissals — the cheapest correct outcome came from investigation, not implementation.
+  - **ADR gates pay for themselves.** ADR-13 ("confirm the current stealth fix insufficient before implementing an alternative") turned a "build Camoufox" epic into a one-afternoon 20-generation spike that said "don't." Encode the gate as a runnable measurement (`scripts/spike_waf_camoufox.py`), not a debate.
+  - **Decompose contested external PRs; never rebase a branch that's 60+ commits behind.** Cherry-pick/re-express the genuinely-valuable pieces onto fresh branches with `Co-authored-by` credit, evidence-gate the risky parts, and split by concern — one PR per slice.
+  - Kept `gflow-cli` strictly headless (Uvicorn + FastMCP over localhost HTTP/SSE); browser-context locks bypassed by serializing task writes in the SQLite queue with WAL-mode parallel reads. Relational instruction cards must be phrased conversationally (imperative prompts bypass the brief); multi-scene movie sync is read-modify-write to preserve server-assigned card IDs.
+
+See [PLAN.md](PLAN.md) or type `gflow:status` for the current task. Type `gflow:plan <feature>` to create a new feature plan.

{gflow_cli-0.29.0 → gflow_cli-0.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.29.0
+Version: 0.30.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.29.0 → gflow_cli-0.30.0}/PLAN.md

@@ -653,6 +653,8 @@ Records image, batch, T2V, I2V, and R2V provenance in a local SQLite catalog. Re
 
 **Status:** NOT implemented. Parked until the stealth-flag fix (`--disable-blink-features=AutomationControlled` + init script) is confirmed insufficient, or until a contributor picks it up.
 
+**2026-07-09 verification — the current stealth fix is CONFIRMED SUFFICIENT (so this stays parked).** A 20-generation baseline on a live authed profile through the default stealth stack produced a **0.0% WAF 403 rate** (19/20 success; the one miss was a UI-scrape timeout, not a WAF block). This met ADR-13's "must verify before implementing" gate and closed the [Camoufox adoption roadmap](superpowers/plans/2026-07-09-camoufox-adoption/PLAN.md) at Phase 2 — the Camoufox engine was NOT built. Evidence: [superpowers/spikes/2026-07-09-camoufox-waf-403.md](superpowers/spikes/2026-07-09-camoufox-waf-403.md). Re-run `scripts/spike_waf_camoufox.py` if a repeatable WAF-403 is later observed; a materially non-zero rate would reopen CDP-Attach / Camoufox.
+
 ---
 
 ### Phase 8 — Pluggable storage backend — BACKLOG
@@ -699,7 +701,7 @@ Today the CLI writes media to `$GFLOW_CLI_OUTPUT_DIR` on the local filesystem. P
 | 10 | Both `gflow` and `flow` binary names installed | `flow` is friendlier; `gflow` avoids conflicts with Facebook Flow / MS Power Automate |
 | 11 | LF-only line endings via `.gitattributes` | Single repo source of truth; cross-platform contributors don't think about it |
 | 12 | `Provider` indirection (legacy `providers/`) removed | Superseded by `api.FlowApiClient`. Re-introduce when we add `OfficialVeoProvider` (planned v0.5+) |
-| 13 | CDP attach transport deferred | Must first confirm whether CDP-attached Chrome still sets `navigator.webdriver=true` (which would negate any reCAPTCHA advantage over the current stealth fix). See CDP Attach backlog entry. |
+| 13 | CDP attach / stealth-engine alternatives deferred; **current stealth fix confirmed sufficient 2026-07-09** | Gate met: a 20-gen live baseline through the default stealth stack showed a **0.0% WAF 403 rate**, so the "confirm insufficient before implementing" bar is unmet — CDP-Attach and the Camoufox engine stay parked (Camoufox roadmap closed at Phase 2). Evidence: [superpowers/spikes/2026-07-09-camoufox-waf-403.md](superpowers/spikes/2026-07-09-camoufox-waf-403.md). |
 | 14 | HTTP status path (`get_video_status`) retired alongside `generate_video` | It is the same 401-dead path and would collide with the new `api/video.py:VideoStatus` value object — retiring both together keeps the domain clean. |
 
 ---

{gflow_cli-0.29.0 → gflow_cli-0.30.0}/docs/INDEX.md

@@ -122,7 +122,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"A gflow command hangs / fails — where do I start?"** → [DEBUGGING § Quick reference](DEBUGGING.md#quick-reference)
 **"Flow's UI broke a selector — how do I diagnose it?"** → [DEBUGGING § Inspecting Flow's live UI](DEBUGGING.md#inspecting-flows-live-ui)
 **"What does each `ui_automation.*` log event mean?"** → [DEBUGGING § Listener & HTTP-layer debugging](DEBUGGING.md#listener--http-layer-debugging)
-**"What was actually live-verified for the latest release?"** → latest: [LIVE_VERIFICATION_v0.29.0](LIVE_VERIFICATION_v0.29.0.md) (**persistent `gflow instructions` CRUD proven live e2e GREEN, credit-free** — 11-command sequence on a fresh project: add incl. `--ref <image-UUID>` attach, list/enable/disable, master toggle both ways, TOML `apply` destructive full-sync with `enabled=false` honored, `rm` with server card-id preserved across mutations; movie brief-sync code-path-verified via the same primitives, deferred-with-reason on credits; MCP `gflow_instructions_*` tools are thin adapters over the live-verified primitives). Prior: [v0.28.0](LIVE_VERIFICATION_v0.28.0.md) (**agent instructions `-i` now steer agentic generation — crayon e2e GREEN**: a style-neutral prompt + an enabled "crayon" card produced an unmistakable crayon drawing through the real transport; root causes were conversational phrasing + the `project_brief.enabled` master switch). Prior: [v0.27.1](LIVE_VERIFICATION_v0.27.1.md) (**v0.27.0 release follow-up fixes and documentation sync**). Prior: [v0.27.0](LIVE_VERIFICATION_v0.27.0.md) (**`[style]` block with named variants + prompt-aware resume — credit-free CLI verification**: real `movie run --dry-run` 3-way ledger proving resolved-style display, `skip (done)` on matching `style_hash`, and `re-run (style changed)` after a style edit; composition is local, wire path untouched, so no Veo credits spent — first credited styled run will confirm visually). Prior: [v0.26.0](LIVE_VERIFICATION_v0.26.0.md) (**image i2i by generated-image UUID proven live e2e GREEN** — the existing asset is *selected in place* by its media UUID, no duplicate upload, producing an i2i output that references it; plus generated-image `display_name` capture, credited @C1ph3r404). Prior: [v0.25.0](LIVE_VERIFICATION_v0.25.0.md) (**#237 remote-UUID i2v proven live e2e GREEN** — a real 8s 720×1280 interpolation from a generated image's UUID, after the picker-search attach was reworked to local upload; #240 home-`.env` matrix live; plus two silent-failure guards root-caused live: video-as-image download rejection and rejected-upload fail-loud). Prior: [v0.24.0](LIVE_VERIFICATION_v0.24.0.md) (--project parity across CLI + MCP — automated coverage; live gen auth-gated). Prior: [v0.23.0](LIVE_VERIFICATION_v0.23.0.md) (MCP generation wiring proven live end-to-end — tool→worker→real Flow REST→structured-error translation; final image-write blocked by an expired session, environmental. #222 macOS fix reporter-verified e2e on Apple Silicon). Prior: [v0.22.0](LIVE_VERIFICATION_v0.22.0.md) (Tools framework — automated/CI coverage complete; credit/key-gated live feature run is a pending owner gate, see the doc) · [v0.21.0](LIVE_VERIFICATION_v0.21.0.md) (MCP server over stdio + HTTP/SSE — credit-free protocol handshake; 4 tools / 2 prompts / 3 resources confirmed on stdout) · [v0.20.1](LIVE_VERIFICATION_v0.20.1.md) · [v0.20.0](LIVE_VERIFICATION_v0.20.0.md) · [v0.19.0](LIVE_VERIFICATION_v0.19.0.md) · [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
+**"What was actually live-verified for the latest release?"** → latest: [LIVE_VERIFICATION_v0.30.0](LIVE_VERIFICATION_v0.30.0.md) (**agentic-cohort image path + both fixes live-verified credit-free** — native 768×1376 stills, i2i-chain + canonical-ref identity hold; the character-create `DataIntegrityError` and the `prefer_classic` WARNING were observed live then fixed [recorder idempotent + INFO log]; MCP video-param feature deferred-with-reason on Veo credits, per the stills-only goal). Prior: [v0.29.0](LIVE_VERIFICATION_v0.29.0.md) (**persistent `gflow instructions` CRUD proven live e2e GREEN, credit-free** — 11-command sequence on a fresh project: add incl. `--ref <image-UUID>` attach, list/enable/disable, master toggle both ways, TOML `apply` destructive full-sync with `enabled=false` honored, `rm` with server card-id preserved across mutations; movie brief-sync code-path-verified via the same primitives, deferred-with-reason on credits; MCP `gflow_instructions_*` tools are thin adapters over the live-verified primitives). Prior: [v0.28.0](LIVE_VERIFICATION_v0.28.0.md) (**agent instructions `-i` now steer agentic generation — crayon e2e GREEN**: a style-neutral prompt + an enabled "crayon" card produced an unmistakable crayon drawing through the real transport; root causes were conversational phrasing + the `project_brief.enabled` master switch). Prior: [v0.27.1](LIVE_VERIFICATION_v0.27.1.md) (**v0.27.0 release follow-up fixes and documentation sync**). Prior: [v0.27.0](LIVE_VERIFICATION_v0.27.0.md) (**`[style]` block with named variants + prompt-aware resume — credit-free CLI verification**: real `movie run --dry-run` 3-way ledger proving resolved-style display, `skip (done)` on matching `style_hash`, and `re-run (style changed)` after a style edit; composition is local, wire path untouched, so no Veo credits spent — first credited styled run will confirm visually). Prior: [v0.26.0](LIVE_VERIFICATION_v0.26.0.md) (**image i2i by generated-image UUID proven live e2e GREEN** — the existing asset is *selected in place* by its media UUID, no duplicate upload, producing an i2i output that references it; plus generated-image `display_name` capture, credited @C1ph3r404). Prior: [v0.25.0](LIVE_VERIFICATION_v0.25.0.md) (**#237 remote-UUID i2v proven live e2e GREEN** — a real 8s 720×1280 interpolation from a generated image's UUID, after the picker-search attach was reworked to local upload; #240 home-`.env` matrix live; plus two silent-failure guards root-caused live: video-as-image download rejection and rejected-upload fail-loud). Prior: [v0.24.0](LIVE_VERIFICATION_v0.24.0.md) (--project parity across CLI + MCP — automated coverage; live gen auth-gated). Prior: [v0.23.0](LIVE_VERIFICATION_v0.23.0.md) (MCP generation wiring proven live end-to-end — tool→worker→real Flow REST→structured-error translation; final image-write blocked by an expired session, environmental. #222 macOS fix reporter-verified e2e on Apple Silicon). Prior: [v0.22.0](LIVE_VERIFICATION_v0.22.0.md) (Tools framework — automated/CI coverage complete; credit/key-gated live feature run is a pending owner gate, see the doc) · [v0.21.0](LIVE_VERIFICATION_v0.21.0.md) (MCP server over stdio + HTTP/SSE — credit-free protocol handshake; 4 tools / 2 prompts / 3 resources confirmed on stdout) · [v0.20.1](LIVE_VERIFICATION_v0.20.1.md) · [v0.20.0](LIVE_VERIFICATION_v0.20.0.md) · [v0.19.0](LIVE_VERIFICATION_v0.19.0.md) · [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
 **"Where is the reverse-engineered wire protocol for a feature?"** → the `*_RECON.md` design docs: [CHARACTER_RECON](CHARACTER_RECON.md) (Flow character entity protocol), [IMAGE_UPSCALE_RECON](IMAGE_UPSCALE_RECON.md) (`/v1/flow/upsampleImage` wire). Naming convention: one `<FEATURE>_RECON.md` per reverse-engineered surface, kept as the durable spec after the feature ships.
 **"What was live-verified for the data layer (PR #58)?"** → [LIVE_VERIFICATION_data_layer](LIVE_VERIFICATION_data_layer.md) — 1 Imagen + 1 Veo credit on denon82, 6-layer ledger (file + magic + Pillow + DB rows + CLI round-trip + structlog)
 **"What was live-verified for the video-download feature (#29)?"** → [LIVE_VERIFICATION_video_download](LIVE_VERIFICATION_video_download.md)

gflow_cli-0.30.0/docs/LIVE_VERIFICATION_v0.30.0.md

@@ -0,0 +1,53 @@
+# Live Verification — v0.30.0
+
+Release gate evidence for the user-facing changes in v0.30.0, using the 5-layer
+ledger (file count · magic bytes · dimensions/shape · structlog invariants ·
+user-confirmable artifact). Credit-free wherever possible.
+
+## Scope of v0.30.0
+
+- **Added:** MCP `gflow_generate_video` model/duration/count parameters (CLI↔MCP parity, #125).
+- **Fixed:** agentic character-recorder idempotency (DataIntegrityError); `prefer_classic`
+  WARNING→INFO on the server-gated agentic cohort.
+
+---
+
+## 1. Agentic-cohort image path + both Fixed items — LIVE, credit-free ✅
+
+Exercised end-to-end on **2026-07-09** against live Flow (account `denon82`, **agentic**
+cohort) as part of the parable image-consistency spike. Image generation is **credit-free**
+(no Veo credits).
+
+- **File count:** multiple stills downloaded per run (t2i baseline, i2i chain, canonical-ref,
+  multi-ref) — 1 file per generation, all present on disk.
+- **Magic bytes:** JPEG (`ffprobe`-decodable) for every downloaded still.
+- **Dimensions/shape:** **768×1376** (native 9:16) on every generation — the no-crop invariant
+  held under the agentic cohort.
+- **Structlog invariants:** the two Fixed conditions were **observed live** before the fix and
+  are now handled:
+  - `ui_driver.prefer_classic.exit_agent_failed` (WARNING) fired on the agentic (`tune`) cohort —
+    now logged at INFO (`ui_driver.prefer_classic.cohort_natively_agentic`); best-effort by contract.
+  - `character create` on the agentic cohort raised `DataIntegrityError`
+    (`UNIQUE constraint failed: assets.profile_name, assets.flow_media_id`) — now idempotent
+    (recorder reuses the existing asset id). Covered by regression test
+    `tests/data/test_recorder_character.py::test_record_character_completed_duplicate_media_id_is_idempotent`.
+- **User-confirmable artifact:** the side-by-side still gallery + scorecard recorded in the
+  consuming project's spike results (`out/spike/…` + `docs/superpowers/specs/2026-07-09-parable-image-consistency-spike-results.md`).
+
+## 2. MCP `gflow_generate_video` params (#125) — deferred this cycle, unit-test-covered ⚠️
+
+This feature is exercised only by **video generation**, which **costs Veo credits**, and the
+consuming pipeline's explicit goal this cycle is **stills-only (skip video generation)**. Per the
+release gate's escape hatch, it is **not live-verified this cycle** for that reason — it is **not
+silently omitted**. Coverage:
+
+- Unit/contract tests: `tests/mcp/` (including the MCP↔CLI parity contract
+  `tests/mcp/test_cli_parity.py`) — model/duration/count validation and the 400-on-unknown-model
+  path are covered without spending credits.
+- Recommended follow-up: a credit-spending i2v smoke on the next cycle that budgets Veo credits.
+
+---
+
+**Gate summary:** ruff ✓ · format ✓ · pyright 0 errors ✓ · pytest 2145 passed / 7 skipped ✓ ·
+repo-hygiene exit 0 ✓. Agentic image path + both fixes live-verified credit-free; MCP video
+feature deferred with documented reason.

{gflow_cli-0.29.0 → gflow_cli-0.30.0}/docs/MCP.md

@@ -46,7 +46,7 @@ The server registers three protocol surfaces:
 
 ### Tools (Executable actions)
 * `gflow_generate_image(prompt, model, aspect, count, seed, reference_images, tools, profile, project, instructions)`: Triggers text-to-image / image-to-image (Imagen / Nano Banana). `instructions` is an optional list of ephemeral agent-instruction strings (agentic cohort only). `reference_images` switches to i2i and accepts **either a local file path or a generated image's Flow media UUID**. A UUID reference is attached by **selecting the already-existing asset in Flow's reference picker — no duplicate copy is uploaded** (locating the tile by the media id in its thumbnail URL, and searching the recorded display name to surface it when needed); gflow falls back to uploading the asset's on-disk local file only when it can't be located in place (e.g. it lives in a different project's picker). `project` generates into an existing Flow project id (mirrors CLI `--project`) — pass the reference's project to keep it selectable in place.
-* `gflow_generate_video(prompt, mode, aspect, initial_frame, end_frame, reference_images, tools, profile, project)`: Triggers vertical or landscape video generation (Veo). `mode` is `t2v`/`i2v`/`r2v`; `i2v` requires `initial_frame`, `r2v` requires `reference_images`; `project` generates into an existing Flow project id (mirrors CLI `--project`). `initial_frame`, `end_frame`, and `reference_images` each accept **either a local file path or the Flow image UUID of a generated asset** — pass a generated image's id straight in to chain image→video, and gflow attaches it for you (the UUID is resolved to the asset's already-on-disk local file and uploaded as the frame; no manual download/re-upload step). A UUID that isn't in your local asset catalog is rejected up front with a clear "Reference Not Found" error; a catalogued asset whose local file is no longer on disk gives a "Reference Not On Disk" error (re-generate it or pass a local path).
+* `gflow_generate_video(prompt, mode, aspect, initial_frame, end_frame, reference_images, model, duration, count, tools, profile, project)`: Triggers vertical or landscape video generation (Veo). `mode` is `t2v`/`i2v`/`r2v`; `model` (`veo_lite`/`veo_fast`/`veo_quality`/`omni_flash`, aliases accepted), `duration` (seconds), and `count` mirror the CLI `gflow video` flags — an omitted `model` lets the transport apply its i2v veo-lite default (issue #125), and `omni_flash` is rejected for i2v-with-frames; `i2v` requires `initial_frame`, `r2v` requires `reference_images`; `project` generates into an existing Flow project id (mirrors CLI `--project`). `initial_frame`, `end_frame`, and `reference_images` each accept **either a local file path or the Flow image UUID of a generated asset** — pass a generated image's id straight in to chain image→video, and gflow attaches it for you (the UUID is resolved to the asset's already-on-disk local file and uploaded as the frame; no manual download/re-upload step). A UUID that isn't in your local asset catalog is rejected up front with a clear "Reference Not Found" error; a catalogued asset whose local file is no longer on disk gives a "Reference Not On Disk" error (re-generate it or pass a local path).
 * `gflow_list_projects(profile, limit)`: Queries SQLite catalog for recent generation folders.
 * `gflow_list_characters(profile)`: Lists Flow Character entities (requires an active browser session).
 * `gflow_list_tools()`: Lists the prompt tools (name/title/description/category) accepted by the generate tools' `tools` param.

gflow_cli-0.30.0/docs/superpowers/plans/2026-07-09-camoufox-adoption/PLAN.md

@@ -0,0 +1,342 @@
+# Camoufox Adoption Implementation Plan
+
+> **For agentic workers:** Run `/gflow:status --feature camoufox-adoption` to find the
+> next unchecked task. Implement one task at a time. Run `/gflow:check` before every commit.
+> This plan supersedes PR #258 (closed) — it re-expresses that contributor work as a
+> gated, decomposed series. Preserve `Co-authored-by: C1ph3r404 <C1ph3r404@users.noreply.github.com>`
+> on every commit that carries their code.
+>
+> **STATUS (2026-07-09): Phase 1 shipped (PR #273); Phase 2 verdict = STOP — the Camoufox
+> engine (Phase 3) is NOT built because the current stealth fix showed a 0.0% WAF 403 rate.
+> See Phase 2 below + `docs/superpowers/spikes/2026-07-09-camoufox-waf-403.md`. Phase 4 items
+> remain independent backlog.**
+
+**Goal:** Adopt Camoufox as an optional, evidence-justified stealth browser engine for
+WAF-blocked users — without regressing the default (playwright) path — landing the
+engine-independent fixes from PR #258 immediately and the engine itself only after it is
+proven to beat the incumbent stealth story.
+
+**Architecture:** Camoufox slots into the existing engine abstraction (`api/_engine.py` +
+`config.BrowserEngine`, the patchright precedent from v0.19.0). The current port
+(`resolve_async_playwright`) is too narrow for Camoufox (its own async CM yielding a Firefox
+`BrowserContext`, no Playwright driver), so Phase 3 **widens `_engine.py` into a single
+context-launching adapter + an `EngineQuirks` capabilities value**. All engine conditionals
+resolve once at setup and thread down as quirks — never inline `settings.browser_engine ==`
+checks in transports/drivers. The default and patchright paths stay byte-for-byte unchanged.
+
+**Predict verdict:** CAUTION — confidence 7/10 (Architect 8 · Security 8 · Performance 7 ·
+CLI-UX 8 · Devil's-Advocate 8). Five-persona review 2026-07-09. Full takeover-by-rebase
+was rejected unanimously in favour of cherry-pick/re-express, split by concern, gated by a
+WAF-evidence spike per ADR-13.
+
+**ADR gate (blocking for Phase 3):** PLAN.md Decision Log #13 + the CDP-Attach backlog park
+all stealth-engine alternatives "until the stealth-flag fix is **confirmed insufficient** —
+this must be verified before implementing anything." Phase 2 produces that verification.
+Camoufox engine code (Phase 3) MUST NOT merge until Phase 2 shows a real 403-rate win.
+
+**Risk register:**
+| Severity | Risk | Mitigation |
+|---|---|---|
+| High | `mcp_warmup` automates Google Search on a logged-in account → account-level flagging, larger blast radius than the Flow WAF | **Drop it** (Phase 4 re-evaluation only; not adopted). Replace with the direct `labs.google` navigation already present. |
+| High | Un-gated `create_project` REST→UI rewrite = 10–30× hot-path regression (5–12 s/call, 135 s worst case) on every engine; DOM selector leaks into the API-client layer | **Do not adopt as-is.** REST stays the default `FlowApiClient.create_project`. A UI-first variant, if ever needed, lands transport-side + camoufox-gated (Phase 4). |
+| High | MCP `_SessionManager` idle-reaper can `__aexit__` a client mid-generation (>5 min) — live concurrency bug | Deferred to Phase 4; needs in-use refcounting before any MCP session-caching lands. Not required for Phases 1–3. |
+| Medium | Camoufox unverified vs live reCAPTCHA-Enterprise; Firefox-on-Flow is population-anomalous; engine-switch on a Chrome-authed profile silently fails | Phase 2 spike + Phase 3 profile↔engine mismatch guard + clean fresh-profile live verification. |
+| Medium | Camoufox = third-party Firefox build with full live-session-cookie access (supply-chain trust); dep unpinned vs patchright exact-pin policy | Phase 3: pin exact version, document under SECURITY.md "elevated supply-chain trust", opt-in only. |
+| Medium | `ref_names` invariant reversal (PR #245 image-i2i guard) rides in un-gated on the default path | Deferred to Phase 4; evaluate on its own with tests. Phase 1's i2i fix is the *other*, safe change (remote-UUID ref resolution). |
+| Low | `image upscale` still mints via enterprise.js → likely broken under Camoufox | Phase 3: document the limitation or route the mint through the quirks gate. |
+| Low | reCAPTCHA token-skip changes the default-path request (empty token) | **Safe** (Security-confirmed: ui_automation discards the minted token; Flow's JS mints natively on submit). Lands in Phase 3 re-expressed as a transport capability, with A/B evidence. |
+
+---
+
+## Provenance — PR #258 commit map
+
+| SHA | Commit | Disposition |
+|---|---|---|
+| `ad1d041` | Extract & save `display_name` for generated images | **Phase 1** — cherry-pick |
+| `b94302c` | Resolve & attach remote-UUID refs in UI automation (i2i) | **Phase 1** — cherry-pick |
+| `5f9d97e` | MCP video tool param parity + veo-lite i2v guard | **Phase 1** — cherry-pick (params + guard only) |
+| `3a5a390` | Camoufox optional stealth engine | **Phase 3** — re-express through widened `_engine.py` |
+| `85e67d3` | Camoufox WAF-retry + display_name tests | **Phase 3** (retry) / Phase 1 (display_name tests) |
+| `c3254b4` | Re-attach refs during WAF retry | **Phase 3** — WAF retry hardening |
+| `c8b8690` | Resource-picker auto-close detection | **Phase 3** — verify it's a real bug, not a Camoufox artifact |
+| `741e44f` | `page.reload` → `goto(page.url)` (Camoufox timeout) | **Phase 4** — re-evaluate (default-path behavior change) |
+
+---
+
+## File structure
+
+### New files
+```
+scripts/spike_waf_camoufox.py
+  Phase 2: A/B 403-rate harness — N generations per engine on one profile, compares
+  PUBLIC_ERROR_UNUSUAL_ACTIVITY / 403 rates. No product code.
+docs/superpowers/spikes/2026-07-XX-camoufox-waf-403.md
+  Phase 2: the spike's recorded evidence (the ADR-13 gate artifact).
+src/gflow_cli/auth/camoufox_strategy.py
+  Phase 3: AuthStrategy for `gflow auth login --browser camoufox` (re-expressed).
+docs/LIVE_VERIFICATION_camoufox.md
+  Phase 3: 5-layer live ledger proving the Camoufox path evades the WAF end-to-end.
+```
+
+### Modified files
+```
+src/gflow_cli/api/dto.py                 Phase 1: display_name field on GeneratedImage.
+src/gflow_cli/api/transports/ui_automation.py   Phase 1: i2i remote-UUID ref resolution.
+src/gflow_cli/mcp/tools.py               Phase 1: gflow_generate_video model/duration/count + veo-lite i2v default.
+src/gflow_cli/api/_engine.py             Phase 3: widen to context-launcher adapter + EngineQuirks.
+src/gflow_cli/config.py                  Phase 3: BrowserEngine.CAMOUFOX enum value.
+src/gflow_cli/api/client.py              Phase 3: engine dispatch via adapter; recaptcha-skip as transport capability.
+src/gflow_cli/errors.py                  Phase 3: generalize BrowserEngineUnavailableError remediation.
+pyproject.toml / uv.lock                 Phase 3: pinned [camoufox] extra.
+.env.template / docs/CONFIGURATION.md / README.md / docs/KNOWN_ISSUES.md / SECURITY.md
+                                         Phase 3: engine docs, profile-mismatch caveat, supply-chain note.
+```
+
+---
+
+# PHASE 1 — Quick wins (land now, no engine, contributor-credited)
+
+> **Re-scoped 2026-07-09 after code investigation.** Two of the three planned cherry-picks
+> evaporated on contact with develop — see the findings below. Phase 1's real deliverable is
+> **one** genuine, safe, engine-independent improvement: MCP video param parity. Branch
+> `fix/pr258-quick-wins` off `origin/develop`, `Co-authored-by: C1ph3r404`, one PR to develop.
+
+## Task 1.1 — `display_name` — ALREADY SHIPPED (no work)
+
+**Finding:** `GeneratedImage.display_name` + the `_workflow_display_names` parse + the recorder
+`metadata_json` write are already on develop (commit `ec9377f`, shipped v0.26.0, credited to
+C1ph3r404). PR #258's `ad1d041` is a duplicate of already-merged work. **Nothing to do.**
+
+## Task 1.2 — i2i remote-UUID refs — MOVED TO PHASE 4 (not a safe quick win)
+
+**Finding:** PR #258's only i2i commit (`b94302c`) IS the contested `ref_names` invariant
+reversal, not a separable safe fix. It adds `ref_names` to `GenerateImageRequest` and **deletes
+the PR #245 guard comment in `daemon.py`** ("image tasks … must not receive ref_names"),
+routing image refs through the R2V `_attach_remote_references` mechanism. This is exactly the
+default-image-path behavior change the Architect flagged. It needs its own predict + tests —
+tracked as **Phase 4.3**, not Phase 1.
+
+## Task 1.3 — MCP video param parity (the one genuine Phase 1 win) — ✅ DONE
+
+**What:** Expose `model`/`duration`/`count` on `gflow_generate_video` (CLI↔MCP parity per the
+AGENTS.md symmetry rule). The worker's `_build_video_request` already reads these payload keys;
+the only gap was the MCP tool not accepting/forwarding them.
+
+**Finding on the "veo-lite guard":** redundant. The transport (`ui_automation_video.py`, issue
+#125) already defaults i2v-with-frames to `I2V_DEFAULT_MODEL` and raises
+`ModelModeIncompatibilityError` for an explicit incompatible model — the MCP path inherits both.
+So this task is parity + agent model-control, NOT a new credit guard.
+
+**Files:** `src/gflow_cli/mcp/tools.py`, `tests/mcp/test_tools_wired.py`, `docs/MCP.md`, `CHANGELOG.md`.
+
+**Steps:**
+- [x] Add `model`/`duration`/`count` to the signature + docstring + tool description.
+- [x] Validate the model alias up front → `_bad_param` 400 on unknown model (pre-spend, mirrors CLI).
+- [x] Forward to payload; omit `model`/`duration` when unset so the transport's i2v default stands.
+- [x] Echo the params in the result's `params` block.
+
+**Tests created (red→green):**
+- [x] `test_video_forwards_model_duration_count_to_payload`
+- [x] `test_video_omits_unset_model_and_duration_from_payload` (transport default preserved)
+- [x] `test_video_invalid_model_is_rejected_before_enqueue` — 400 before enqueue.
+
+## Task 1.4 — Phase 1 gates + PR
+
+**Steps:**
+- [x] `/gflow:check` green (ruff / format / pyright / mcp+worker suites).
+- [x] CHANGELOG `[Unreleased]` — Added entry crediting C1ph3r404.
+- [ ] Open PR `fix/pr258-quick-wins → develop`, reference #258, wait for green CI + SonarCloud, merge.
+
+---
+
+# PHASE 2 — WAF evidence spike (the ADR-13 gate)
+
+**Blocking gate for Phase 3.** No product code. The ADR-13 question is not first "does
+Camoufox win?" but "*is the current stealth stack actually insufficient?*" — so the spike's
+first job is the **baseline**: measure the 403 rate on the default (playwright) engine. A
+~0% baseline means ADR-13's premise is unmet → **STOP, Camoufox unjustified**, and no
+Camoufox arm is ever needed. Only a materially non-zero baseline escalates to a Camoufox A/B.
+
+**Sequencing note (why the arms are staged, not parallel):** `camoufox` is **not** a valid
+`BrowserEngine` on develop — it is Phase 3, gated on this spike. So the spike **cannot** drive
+a Camoufox arm through product code today (chicken-and-egg). This is correct: the baseline
+comes first and may end the roadmap before any Camoufox code exists. The Camoufox A/B arm is
+run *during Phase 3* (once the engine is wired) by re-running the same harness with
+`--engine camoufox`.
+
+## Task 2.1 — Spike harness — ✅ DONE
+
+**What:** `scripts/spike_waf_camoufox.py` — drives N real image generations on one authed
+profile through a chosen engine and classifies each outcome
+(`success`/`waf_403`/`auth_401`/`rate_limited_429`/`other_error`); emits structured JSON
+(per-attempt records + summary with `waf_403_rate`/`success_rate`).
+
+**Files:** `scripts/spike_waf_camoufox.py` (scripts/ — excluded from SonarCloud; not imported
+by the package).
+
+**Steps:**
+- [x] Engine-parameterized (`--engine playwright|patchright`); selects via `GFLOW_CLI_BROWSER_ENGINE`
+      + `reset_settings()`, exactly as a user would.
+- [x] `--engine camoufox` fails fast (exit 3) with the ADR-13 "measure the baseline first" pointer.
+- [x] Credit-safe by default: `--dry-run` (validate + estimate, spend nothing) and an explicit
+      `--yes`/interactive confirmation gate; non-interactive without `--yes` refuses to spend.
+- [x] Classifies `WafRejectionError`→403, `AuthExpiredError`→401 (aborts early — a dead session
+      dilutes the 403 rate), `RateLimitError`→429; `--delay` between attempts avoids self-inflicted 429s.
+- [x] Ruff clean; dry-run + both guard exit codes verified without spending.
+
+## Task 2.2 — Run the baseline + record the evidence — ✅ DONE (STOP verdict)
+
+**What:** Ran the baseline arm; wrote the ADR-13 evidence artifact.
+
+**Result (2026-07-09):** 20-gen baseline on `ffroliva` through the default stealth stack →
+**0.0% WAF 403 rate** (19/20 success; the one miss was a `TransportTimeoutError` UI-scrape
+flake, not a WAF block). Evidence: [../../spikes/2026-07-09-camoufox-waf-403.md](../../spikes/2026-07-09-camoufox-waf-403.md).
+
+**Verdict: STOP.** The current stealth fix is confirmed sufficient — ADR-13's "confirm
+insufficient before implementing" gate is unmet. ADR-13 (PLAN.md Decision Log #13) updated
+with the evidence. Phase 1 stays shipped; **Phase 3 is NOT built.**
+
+- [x] Baseline run (≈20 Imagen credits; a first attempt aborted at 0 credits on an expired
+      session, which validated the harness's clean expired-session handling).
+- [x] Recorded raw JSON + the 403 rate.
+- [x] Verdict applied: ~0% → STOP; ADR-13 updated; roadmap closed at Phase 2.
+
+---
+
+# PHASE 3 — Camoufox engine adoption — ❌ NOT PROCEEDING (Phase 2 = STOP)
+
+**Gate closed 2026-07-09.** The Phase 2 baseline showed a 0.0% WAF 403 rate, so per ADR-13 the
+Camoufox engine is **not built**. The tasks below are retained only as the design of record in
+case a future, repeatable WAF-403 reopens the gate (re-run `scripts/spike_waf_camoufox.py`;
+a materially non-zero rate would revive this phase). Until then, none of it is implemented.
+
+Re-expressed from PR #258 through the widened abstraction so engine logic lives in one place.
+Own branch `feature/camoufox-engine → develop`, contributor-credited.
+
+## Task 3.1 — Widen `_engine.py` + `EngineQuirks` (test scaffold)
+
+**What:** Red tests for a single `open_persistent_context(engine, *, user_data_dir, headless,
+chromium_kwargs) -> (BrowserContext, aclose)` adapter and an `EngineQuirks` value
+(`typing_strategy`, `supports_init_script`, `needs_webdriver_patch`, `mints_recaptcha_inline`,
+`mint_isolated_context`).
+
+**Files:** `tests/api/test_engine.py`.
+
+**Steps:**
+- [ ] Tests: each engine resolves the right quirks; playwright/patchright quirks unchanged.
+
+**Tests created (red):**
+- [ ] `test_quirks_for_playwright_default` · `test_quirks_for_camoufox` · `test_adapter_returns_context_and_aclose`.
+
+## Task 3.2 — Implement the adapter + quirks (green)
+
+**What:** Fold the three PR #258 camoufox launch/teardown copies (auth, client, transport)
+into one adapter; the CM-vs-driver asymmetry stays inside `_engine.py`. Add
+`BrowserEngine.CAMOUFOX`, the pinned `[camoufox]` extra, `retryable_engine_errors()` extension.
+
+**Files:** `src/gflow_cli/api/_engine.py`, `config.py`, `pyproject.toml`, `uv.lock`.
+
+**Steps:**
+- [ ] One adapter call at each site; delete inline `settings.browser_engine ==` checks in
+      `agentic.py` (~310) and `ui_automation.py` (~1277, ~1337) — replace with threaded quirks.
+- [ ] Pin `camoufox==<exact>`; regenerate `uv.lock`.
+- [ ] Partial-setup leak guard covers `AsyncCamoufox.__aenter__` failure (no orphaned firefox.exe,
+      no locked profile dir) — **must have a test** (Performance finding #4).
+
+**Tests:** 3.1 green + a leak-guard test.
+
+## Task 3.3 — Auth strategy + profile↔engine mismatch guard
+
+**What:** Re-express `camoufox_strategy.py`; raise `BrowserEngineUnavailableError` (exit 24,
+**not** the PR's `ConfigurationError`/exit 11) for a missing package **and** a missing
+`camoufox fetch` binary. Add the mismatch guard: a camoufox-authed profile opened under a
+chromium engine (or vice-versa) fails fast with a typed error, not the exit-8 login loop.
+
+**Files:** `src/gflow_cli/auth/camoufox_strategy.py`, `src/gflow_cli/errors.py`, engine-resolution site.
+
+**Steps:**
+- [ ] Unify the missing-package exit code to 24 across auth + client paths.
+- [ ] Catch missing-binary at `AsyncCamoufox` launch → exit 24 with a `camoufox fetch` hint
+      (verify camoufox-py's actual behavior first — CLI-UX must-test).
+- [ ] Mismatch guard: read `.gflow_browser_strategy` marker; typed error on engine mismatch.
+
+**Tests created (red):**
+- [ ] `test_camoufox_missing_package_is_exit_24` · `test_camoufox_missing_binary_is_typed` ·
+      `test_profile_engine_mismatch_fails_fast` — all Critical.
+
+## Task 3.4 — reCAPTCHA-skip + WAF-retry as transport capabilities
+
+**What:** Re-express the (safe) empty-token path as `transport.mints_recaptcha_inline` on the
+transport protocol (not a stringly `name == "ui_automation"` check); port the WAF-retry
+ref-re-attach (`c3254b4`) and the resource-picker auto-close (`c8b8690`, only if confirmed a
+real bug). Selectors follow the v0.29.0 canonical-source rule (`drivers/factory.py`), not new
+hardcoded ligatures.
+
+**Files:** `src/gflow_cli/api/transports/base.py`, `client.py`, `ui_automation.py`, `drivers/factory.py`.
+
+**Tests created (red):**
+- [ ] `test_ui_automation_mints_recaptcha_inline_capability` · WAF-retry ref-reattach test.
+
+## Task 3.5 — Docs + live verification
+
+**Files:** `.env.template`, `docs/CONFIGURATION.md`, `README.md`, `docs/KNOWN_ISSUES.md`,
+`SECURITY.md`, `docs/USAGE.md`, `docs/LIVE_VERIFICATION_camoufox.md`.
+
+**Steps:**
+- [ ] `.env.template` + CONFIGURATION: `GFLOW_CLI_BROWSER_ENGINE` → `playwright | patchright | camoufox`;
+      install + `camoufox fetch`; "must match the engine you logged in with"; Windows binary-cache location.
+- [ ] SECURITY.md: camoufox under "elevated supply-chain trust", exact-pinned.
+- [ ] KNOWN_ISSUES: profile↔engine mismatch symptom; `image upscale` enterprise.js limitation under camoufox.
+- [ ] README: engine mention + C1ph3r404 credit line.
+- [ ] `docs/LIVE_VERIFICATION_camoufox.md`: full fresh-profile `auth login → create_project →
+      t2i → batch` under camoufox (5-layer ledger), session persistence across restart, the
+      Phase 2 403-rate delta, and the DevTools native-token confirmation.
+
+## Task 3.6 — Phase 3 gates + PR
+
+**Steps:**
+- [ ] `/gflow:check` green; `/gflow:doc-review` clean.
+- [ ] CHANGELOG `[Unreleased]` — Camoufox engine (opt-in), crediting C1ph3r404.
+- [ ] PR `feature/camoufox-engine → develop`, reference #258, green CI + SonarCloud, merge.
+
+---
+
+# PHASE 4 — Deferred re-evaluations (each its own predict → plan)
+
+Not adopted from PR #258; each needs independent design + evidence. Tracked here so nothing is
+silently dropped. **Do not bundle these into Phases 1–3.**
+
+- **4.1 — Transport-side UI-first `create_project`.** ARCHITECTURE.md already sanctions UI-first
+  creation *in the transport*. If a WAF-fallback for create is ever justified: REST-first, UI
+  fallback only on a WAF-classified failure, selector via `drivers/factory.py`, camoufox-gated.
+  Never in the API-client layer. (Blocked on a real need — createProject returns 200 today.)
+- **4.2 — `mcp_warmup` redesign or removal.** As-is it automates Google Search on a logged-in
+  account (account-level risk). If any warmup is needed: direct `labs.google` navigation, own
+  env flag defaulted OFF, rate-limited, hard-stop (not swallow) on a Google captcha.
+- **4.3 — i2i remote-UUID refs / `ref_names` invariant reversal** (PR #258 `b94302c`) —
+  **INVESTIGATED 2026-07-09: NOT A BUG on develop. Closed, no change needed.** The contributor's
+  premise ("i2i with a bare UUID ref is ignored → plain t2i submitted") does not reproduce:
+  develop attaches UUID refs via the v0.26.0 select-in-place path (`ui_automation.py:2175`
+  `if request.refs → _attach_image_uuid_refs`), which selects the existing Flow asset in the
+  picker, falls back to local-file upload, and **fails loud** if neither works — never a silent
+  drop. The PR's `ref_names` change would have added a SECOND, parallel R2V attach path on top,
+  likely double-attaching — good that it wasn't merged. Root cause of the false premise: a stale
+  `cli_image.py` comment claiming UUID binding was "not wired yet" (fixed). The PR #245 invariant
+  stands.
+- **4.4 — MCP `_SessionManager` client caching + idle reaper.** The idle monitor can close a
+  client mid-generation. Needs in-use refcounting in the worker/service layer before any
+  session-caching lands.
+- **4.5 — `.type()` chunked-input follow-up** for long agentic prompts under camoufox
+  (10–60 s per prompt) — a perf polish once the engine is in.
+
+---
+
+## Definition of done (per phase)
+
+- [ ] All in-phase task steps checked off.
+- [ ] `/gflow:check` green (ruff / format / pyright / pytest ≥ 80% coverage).
+- [ ] `CHANGELOG.md` `[Unreleased]` updated; contributor credit preserved.
+- [ ] Docs updated (Phase 3: CONFIGURATION / SECURITY / KNOWN_ISSUES / README / live-verification).
+- [ ] Phase 2 evidence recorded before any Phase 3 code merges (ADR-13 gate).
+- [ ] No `# TODO` in diff without a tracked issue link.
+- [ ] Each phase merges as its own PR referencing #258 for provenance.

gflow_cli-0.30.0/docs/superpowers/spikes/2026-07-09-camoufox-waf-403.md

@@ -0,0 +1,75 @@
+# Spike evidence — Camoufox WAF 403 baseline (ADR-13 gate)
+
+**Date:** 2026-07-09 · **Verdict: STOP — do not build the Camoufox engine (roadmap Phase 3).**
+
+This is the ADR-13 evidence artifact for the
+[camoufox-adoption roadmap](../plans/2026-07-09-camoufox-adoption/PLAN.md). ADR-13
+(PLAN.md Decision Log #13 + the CDP-Attach backlog) parks every stealth-engine
+alternative "until the stealth-flag fix is **confirmed insufficient** — this must be
+verified before implementing anything." This spike ran that verification and the current
+stealth stack is **confirmed sufficient**: zero WAF rejections over a real 20-generation
+baseline. The premise for adopting Camoufox is therefore unmet.
+
+## Method
+
+`scripts/spike_waf_camoufox.py --engine playwright -n 20 --profile ffroliva` — 20 real
+Imagen image generations against live Flow on one authenticated profile, through the
+**default** stealth stack (Playwright + system Chrome `channel=chrome` +
+`--disable-blink-features=AutomationControlled` + the `navigator.webdriver` init script).
+Each attempt is classified: `success` / `waf_403` (`WafRejectionError`, the WAF/reCAPTCHA
+wall) / `auth_401` / `rate_limited_429` / `other_error`.
+
+- **Engine:** `playwright` (the baseline / default). Camoufox was **not** run — it is not a
+  drivable engine on develop (it *is* Phase 3, gated on this spike), and the baseline result
+  makes a Camoufox comparison moot.
+- **Profile:** `ffroliva` (re-authenticated immediately before the run — a first attempt
+  aborted cleanly at 0 credits on an expired session, which validated the harness's
+  expired-session handling).
+- **Model/aspect:** `narwhal` / `1:1`. **Window:** 2026-07-09 20:07–20:14 UTC (442.9s).
+- **Raw evidence:** `scripts/dev/_spike_out/waf_spike_20260709_211430.json` (gitignored;
+  per-attempt records + summary).
+
+## Result
+
+| Outcome | Count |
+|---|---|
+| success | 19 |
+| **WAF 403 (`WafRejectionError`)** | **0** |
+| auth 401 | 0 |
+| rate-limit 429 | 0 |
+| other error | 1 |
+| **WAF 403 rate** | **0.0%** |
+| success rate | 95.0% |
+
+Success latency: n=19, avg 10.5s (min 3.4s, max 34.6s).
+
+The single non-success (attempt #3) was a `TransportTimeoutError` — "Agentic DOM scraping
+timed out after 180s: 0/1 distinct media UUIDs appeared". That is a UI-cohort scraping
+flake (the session bound the agentic cohort on that attempt), **not** a WAF block. It is
+orthogonal to the stealth question and does not count toward the 403 rate.
+
+## Interpretation
+
+The historical 403 (`PUBLIC_ERROR_UNUSUAL_ACTIVITY`) that motivated the CDP-Attach / stealth
+backlog was observed before the current stealth flags landed, when `navigator.webdriver=true`
+let reCAPTCHA-Enterprise detect automation. This run — on the current stealth stack — produced
+**zero** WAF rejections in 20 consecutive real generations. The stealth fix works; the WAF is
+not a material problem for this configuration today.
+
+**Sample-size honesty:** 0/20 is strong evidence that the WAF is *not currently* a material
+blocker, not a proof of 0% under all conditions (WAF scoring varies with profile age, IP
+reputation, request volume, and time). But the ADR-13 gate does not ask for a universal
+guarantee — it asks whether the current fix is *insufficient*. This run decisively fails to
+reproduce insufficiency. If a real, repeatable WAF-403 problem is later observed on the
+default stack, re-run this spike to quantify it; a materially non-zero rate would reopen the
+Camoufox question with the A/B arm.
+
+## Decision
+
+- **STOP the Camoufox adoption roadmap at Phase 2.** Do not build the engine (Phase 3).
+- **Phase 1 stays shipped** (PR #273 — MCP video param parity; unrelated to the engine).
+- **ADR-13 updated** (PLAN.md Decision Log #13) with this evidence: the stealth-flag fix is
+  confirmed sufficient as of 2026-07-09; CDP-Attach and Camoufox remain parked.
+- **Phase 4 items** (transport-side UI-first create_project, `mcp_warmup`, the i2i `ref_names`
+  invariant, the MCP `_SessionManager` idle-reaper concurrency fix) were always independent of
+  the engine and remain as their own backlog — each needs its own predict if picked up.

{gflow_cli-0.29.0 → gflow_cli-0.30.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gflow-cli"
-version = "0.29.0"
+version = "0.30.0"
 description = "Unofficial CLI for Google Flow — drive Veo image-to-video generations from the terminal."
 readme = "README.md"
 license = { file = "LICENSE" }