gflow-cli 0.31.0__tar.gz → 0.32.1__tar.gz

{gflow_cli-0.31.0 → gflow_cli-0.32.1}/AGENTS.md

@@ -57,7 +57,7 @@ Or invoke the wrapper: `/gflow:check`.
 
 - Type hints everywhere; `pyright` strict on `src/gflow_cli`.
 - Structured logging only (`structlog`) — **never** raw `print()` or `import logging` in `src/`.
-- Errors as RFC 9457 Problem Details with stable per-class exit codes (3–25, e.g. 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`, 22 `UpscaleUnavailableError`, 25 `FlowAgentUiError`). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping.
+- Errors as RFC 9457 Problem Details with stable per-class exit codes (3–27, e.g. 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`, 22 `UpscaleUnavailableError`, 25 `FlowAgentUiError`). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping.
 - 100-char line length, `ruff` configured. Imports sorted by `ruff` (isort rules).
 - **MCP & CLI Schema Symmetry**: Any updates or additions to user-facing CLI command parameters (e.g., `gflow image t2i`, `gflow video`) must be mirrored in the corresponding MCP tool definitions. Never add option/argument fields to Click commands without updating the MCP server implementation. This symmetry is enforced programmatically in CI via `tests/mcp/test_cli_parity.py` (every CLI leaf command needs a mapped MCP tool or an explicit, reasoned exemption) plus the schema checks in `tests/mcp/test_server.py`.
 

{gflow_cli-0.31.0 → gflow_cli-0.32.1}/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.32.1] — 2026-07-11
+
+### Fixed
+
+- **Browser teardown can no longer hang forever or leak a Chrome tree that locks the profile dir (#293).** A wedged `context.close()` used to be awaited unbounded and its failure swallowed to a warning; stopping the Playwright driver afterwards kills only the Node process, so the detached system-Chrome survived holding the profile — the next run then died at launch with an opaque `TargetClosedError` → "Unexpected error." (exit 1) (observed 3× live, 2026-07-11). Teardown now uses a shared bounded-close helper (generous 30s graceful bound — Playwright hard-kills Chrome mid-profile-flush if a second close arrives during a graceful close, so a slow-but-healthy close must not be escalated; 5s force-close fallback via `context.browser`; 10s driver-stop bound; field resets survive Ctrl-C) across **all three** owned-context teardown paths: `FlowApiClient`, the UI-automation transport's standalone path (its partial-setup guard now also closes a launched context before the driver exits), and the experimental evaluate-fetch transport. A launch-time `TargetClosedError` is now surfaced as `ProfileLockedError` (exit 11) carrying the original error and a kill-the-stale-Chrome remediation, hedged for non-lock startup crashes (#293).
+
+- **Picker grid scroll no longer misses a tile rendered by the final scroll (#283 off-by-one).** `_select_existing_asset` checked the tile count only *before* each scroll, so an asset the last scroll brought into the virtualised grid was never re-checked and the picker gave up with the tile on screen. A post-loop re-check closes it (`_find_picker_entity_tile` shares the loop shape but returns the locator unconditionally, so it was unaffected — now documented).
+- **Agentic `await_images` no longer trusts a single exact-count scrape (#283 hardening of the #281 race).** The poll loop breaks only when the new-UUID set is identical across two consecutive scrapes at the expected count (~one extra 0.5s poll); a set that transiently hits the exact count and then grows surfaces as the #281 `MediaAttributionError` instead of being returned as "the" generated media.
+- **Debug screenshots that fail to capture are no longer reported as if they existed.** `_capture_debug_screenshot` returned the target path even when `page.screenshot` raised (observed live 2026-07-11: an error message pointed at a file that was never written). It now returns `None` on capture failure and every error message appends its `Screenshot:` clause conditionally (new `screenshot_clause` helper) (#283).
+
+### Changed
+
+- **UUID-shape validation consolidated onto `gflow_cli.api.video.is_media_uuid`.** The four per-module private `_UUID_RE` copies (cli_image, cli_instructions, image_upscale, mcp/tools) now delegate to the public helper introduced in #290; no behavior change. `MediaAttributionError` raises in the recorder now carry `route=` provenance, the agentic ambiguity raise no longer duplicates the class remediation text, `image i2i --ref` help uses the same "media UUID" vocabulary as `video i2v`, and a bad value passed via the deprecated `--end-image` alias names `--end-image` (not `--end-frame`) in its usage error (#283).
+
+## [0.32.0] — 2026-07-11
+
+### Added
+
+- **`gflow video i2v` accepts an in-project asset media UUID for `--initial-frame` / `--end-frame` (and the positional IMAGE).** A UUID-shaped value selects the already-existing Flow asset in place via the same `_select_existing_asset` picker the image `--ref` flow uses (#282 scroll/search fixes included) instead of forcing a duplicate local-file upload — the duplicate-asset pileup and per-run re-upload from the 2026-07-11 chalkboard pilot. Pair with `--project` so the asset's project is the one generated in; a UUID that can't be located in the picker fails with `TransportTimeoutError` (exit 9) naming the slot and UUID (#287).
+
+### Fixed
+
+- **A Flow upload-endpoint rejection is now a typed error instead of "Unexpected error." (exit 1).** An `uploadImage` 4xx during frame/reference attach (observed live: one JPEG rejected with HTTP 400 while byte-identical-format siblings uploaded fine) raised a bare `RuntimeError` that fell through to the generic handler with no hint the *input image* was refused. It now raises the new `MediaUploadRejectedError` (**exit code 27**, RFC 9457 type `media-upload-rejected`) with a re-encode remediation hint (`ffmpeg -q:v 2 -map_metadata -1`) (#287).
+- **An explicit `--duration` that cannot be applied now fails fast instead of silently producing a clip of Flow's default length.** When the video settings panel's duration tab probe missed (observed 3/3 on a live 2026-07-11 Frames-submode run: `--duration 4` returned an 8-second clip and the JSON result reported success), `_select_video_duration` demoted the failure to a warning and generation continued on Flow's default. Duration is a contract parameter — downstream timeline math sizes cuts from the requested value — so a probe miss with an explicit `--duration` now raises `UiSelectorDriftError` (**exit code 23**, the #183 selector-drift semantics) with a `debug_no_duration_tab.png` viewport screenshot and an omit-`--duration` remediation hint. Omitting `--duration` is unaffected. Root cause confirmed live 2026-07-11: the duration control is absent from the affected cohort's settings popover (#288, #289).
+
 ## [0.31.0] — 2026-07-10
 
 ### Fixed
@@ -1908,7 +1933,10 @@ 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.30.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.32.1...HEAD
+[0.32.1]: https://github.com/ffroliva/gflow-cli/compare/v0.32.0...v0.32.1
+[0.32.0]: https://github.com/ffroliva/gflow-cli/compare/v0.31.0...v0.32.0
+[0.31.0]: https://github.com/ffroliva/gflow-cli/compare/v0.30.0...v0.31.0
 [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

{gflow_cli-0.31.0 → gflow_cli-0.32.1}/KNOWN_ISSUES.md

@@ -14,6 +14,63 @@ Living list of behaviour that's broken, surprising, or limited by design — alo
 
 ## Open
 
+### Flow's `uploadImage` endpoint rejects some JPEGs with HTTP 400 (metadata-sensitive)
+
+- **Status:** Open ([#287](https://github.com/ffroliva/gflow-cli/issues/287))
+- **Severity:** Low (typed + remediable) · **Affected:** i2v frame / reference uploads
+
+Observed live 2026-07-11: one JPEG was rejected with HTTP 400 while
+byte-identical-format siblings uploaded fine; re-encoding with
+`ffmpeg -q:v 2 -map_metadata -1` fixed it, implicating a metadata segment.
+Since #290 the rejection raises `MediaUploadRejectedError` (exit 27) with that
+remediation instead of a generic "Unexpected error." (exit 1). **Workaround:**
+re-encode the file, or reference the already-in-project asset by media UUID
+(`--initial-frame <UUID> --project <id>`). Root cause of Flow's metadata
+sensitivity is unidentified.
+
+### i2v frame-slot picker selection by UUID — RESOLVED live 2026-07-11
+
+- **Status:** **Verified live** ([#287](https://github.com/ffroliva/gflow-cli/issues/287) / PR [#290](https://github.com/ffroliva/gflow-cli/pull/290))
+- **Affected:** `gflow video i2v --initial-frame/--end-frame <UUID>`
+
+#290 routes i2v frame slots through `_select_existing_asset` (the UUID picker
+live-proven in the **Add-Media** dialog: v0.26.0 i2i-by-UUID, #282 scroll
+fixes). The **frame-slot** dialog carried a negative prior — #237's
+name-search there never surfaced generated media (v0.25.0 rework) — but the
+thumbnail-URL tile match succeeds where name search failed. Live evidence
+(2026-07-11, denon82): `frame_ref_attached {slot: Start}` → wire capture on
+`batchAsyncGenerateVideoStartImage` with the asset's `startImage` bound →
+SUCCESSFUL 720×1280 mp4; **zero** `image_uploaded` events (no duplicate
+upload). Negative check: a foreign UUID exits 9 pre-generation with a
+`debug_frame_ref_miss_start.png` screenshot. Caveat that stands: the asset's
+project must be entered via `--project`, and projects that open in the
+full-page media-library UI (#174) can fail earlier at `mode_switch_trigger`.
+
+### Video duration tab probe misses on the current Frames-submode DOM
+
+- **Status:** Open ([#288](https://github.com/ffroliva/gflow-cli/issues/288))
+- **Severity:** Medium · **Affected:** `gflow video` with an explicit `--duration`
+  on at least some Classic-profile cohorts (3/3 miss on a live 2026-07-11 run)
+
+The `duration_tab` selector cascade (`[role='tab']:text-is('4s')` /
+`:has-text('4s')`) fails to match on Flow's current Frames-submode settings
+panel. Pre-fix this silently produced a clip of Flow's default length; since
+the #289 fix the run fails fast with `UiSelectorDriftError` (exit 23) and a
+`debug_no_duration_tab.png` screenshot — live-verified 2026-07-11 on the
+denon82 profile (aborted pre-submit, saving the 10-credit generation).
+**Workaround:** omit `--duration` to accept Flow's default.
+
+**Root cause (confirmed live 2026-07-11, screenshot evidence on #288): the
+duration control is ABSENT from this cohort's settings popover** — the panel
+renders mode tabs (Imagem/Video), sub-mode (Frames/Elementos), aspect
+(9:16/16:9), count (1x–x4), and the model dropdown (Veo 3.1 - Lite), and
+nothing else. The earlier locale hypothesis is refuted: the UI renders in
+Portuguese and the sibling count tabs (`1x`/`x2`) match fine; there is simply
+no duration row to click. Whether Flow removed clip-length selection for this
+cohort/model or moved it elsewhere is unknown — until that's answered,
+`--duration` cannot be honored on affected cohorts and the fail-fast is the
+correct behavior, not a selector bug to patch.
+
 ### macOS: generation runs logged-out → HTTP 401, even with `--browser chrome`
 
 - **Status:** **RESOLVED in v0.23.0** ([#222](https://github.com/ffroliva/gflow-cli/issues/222),
@@ -741,8 +798,13 @@ through all three layers: wrong file on disk, exit 0. Mitigations until this
 is closed: run generations in a dedicated, low-asset project (fewer
 pre-existing tiles means a smaller lazy-render population to collide with),
 and visually verify anchor/canonical images before referencing them
-downstream in `i2i`. Follow-up hardening (a break condition stable across
-two consecutive scrapes, not one) is tracked upstream against this issue.
+downstream in `i2i`. The stable-break hardening shipped post-v0.32.0 (#283 /
+PR #292): the loop now requires the SAME new-UUID set on two consecutive
+scrapes at the expected count before trusting it, which narrows this window
+to a pre-existing tile that lazy-renders AND holds stable across two 0.5s
+scrapes at exactly the expected count (or first hits the count on the final
+poll before the 180s deadline). Narrowed, not closed — the dedicated-project
+mitigation still applies.
 
 **Known gap: the shell multi-prompt path records no history at all.**
 `gflow run --config <file>` and `gflow image t2i` with multiple prompts
@@ -758,7 +820,8 @@ collision escalation) both depend on local history via
 neither guard exists on this path — this is a pre-existing gap, not a
 regression from this fix. `gflow image batch` (the manifest path, via
 `run_manifest_image_batch`) already threads a recorder through and is covered
-by all three layers. Follow-up tracked in #283.
+by all three layers. Accepted low-risk gap (#283 closed with this noted as
+un-shipped remainder; re-file if it bites in practice).
 
 **Workaround (pre-fix):** none — on an affected version, manually verify the
 downloaded file matches the prompt before trusting a `t2i`/`i2i` result.

{gflow_cli-0.31.0 → gflow_cli-0.32.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.31.0
+Version: 0.32.1
 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.31.0 → gflow_cli-0.32.1}/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.31.0](LIVE_VERIFICATION_v0.31.0.md) (**#281 wrong-media defenses live-verified in BOTH directions, credit-free** — correct attribution downloads with real wire metadata [seed, 768×1376]; the incident-class lazy-render ambiguity reproduced live and hard-stopped with `MediaAttributionError` exit 26 naming every candidate UUID, no file written; **#282 two-UUID-ref i2i proven e2e** — both freshly generated portrait UUIDs picker-selected into one scene with both canonical identities visually transferred). Prior: [v0.30.0](LIVE_VERIFICATION_v0.30.0.md) (**agentic-cohort image path + both fixes live-verified credit-free** — native 768×1376 stills, i2i-chain + canonical-ref identity hold; the character-create `DataIntegrityError` and the `prefer_classic` WARNING were observed live then fixed [recorder idempotent + INFO log]; MCP video-param feature deferred-with-reason on Veo credits, per the stills-only goal). Prior: [v0.29.0](LIVE_VERIFICATION_v0.29.0.md) (**persistent `gflow instructions` CRUD proven live e2e GREEN, credit-free** — 11-command sequence on a fresh project: add incl. `--ref <image-UUID>` attach, list/enable/disable, master toggle both ways, TOML `apply` destructive full-sync with `enabled=false` honored, `rm` with server card-id preserved across mutations; movie brief-sync code-path-verified via the same primitives, deferred-with-reason on credits; MCP `gflow_instructions_*` tools are thin adapters over the live-verified primitives). Prior: [v0.28.0](LIVE_VERIFICATION_v0.28.0.md) (**agent instructions `-i` now steer agentic generation — crayon e2e GREEN**: a style-neutral prompt + an enabled "crayon" card produced an unmistakable crayon drawing through the real transport; root causes were conversational phrasing + the `project_brief.enabled` master switch). Prior: [v0.27.1](LIVE_VERIFICATION_v0.27.1.md) (**v0.27.0 release follow-up fixes and documentation sync**). Prior: [v0.27.0](LIVE_VERIFICATION_v0.27.0.md) (**`[style]` block with named variants + prompt-aware resume — credit-free CLI verification**: real `movie run --dry-run` 3-way ledger proving resolved-style display, `skip (done)` on matching `style_hash`, and `re-run (style changed)` after a style edit; composition is local, wire path untouched, so no Veo credits spent — first credited styled run will confirm visually). Prior: [v0.26.0](LIVE_VERIFICATION_v0.26.0.md) (**image i2i by generated-image UUID proven live e2e GREEN** — the existing asset is *selected in place* by its media UUID, no duplicate upload, producing an i2i output that references it; plus generated-image `display_name` capture, credited @C1ph3r404). Prior: [v0.25.0](LIVE_VERIFICATION_v0.25.0.md) (**#237 remote-UUID i2v proven live e2e GREEN** — a real 8s 720×1280 interpolation from a generated image's UUID, after the picker-search attach was reworked to local upload; #240 home-`.env` matrix live; plus two silent-failure guards root-caused live: video-as-image download rejection and rejected-upload fail-loud). Prior: [v0.24.0](LIVE_VERIFICATION_v0.24.0.md) (--project parity across CLI + MCP — automated coverage; live gen auth-gated). Prior: [v0.23.0](LIVE_VERIFICATION_v0.23.0.md) (MCP generation wiring proven live end-to-end — tool→worker→real Flow REST→structured-error translation; final image-write blocked by an expired session, environmental. #222 macOS fix reporter-verified e2e on Apple Silicon). Prior: [v0.22.0](LIVE_VERIFICATION_v0.22.0.md) (Tools framework — automated/CI coverage complete; credit/key-gated live feature run is a pending owner gate, see the doc) · [v0.21.0](LIVE_VERIFICATION_v0.21.0.md) (MCP server over stdio + HTTP/SSE — credit-free protocol handshake; 4 tools / 2 prompts / 3 resources confirmed on stdout) · [v0.20.1](LIVE_VERIFICATION_v0.20.1.md) · [v0.20.0](LIVE_VERIFICATION_v0.20.0.md) · [v0.19.0](LIVE_VERIFICATION_v0.19.0.md) · [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
+**"What was actually live-verified for the latest release?"** → latest: [LIVE_VERIFICATION_v0.32.1](LIVE_VERIFICATION_v0.32.1.md) (**#293 teardown fix live-verified credit-free** — error-path aborts leave ZERO chrome.exe holding the profile [3× leak reproduced pre-fix same day]; force-close fallback + ProfileLockedError translation unit-pinned; #283 wave logic fixes mock-verified to exact call counts). Prior: [v0.32.0](LIVE_VERIFICATION_v0.32.0.md) (**#287 UUID i2v frames proven live e2e** — an in-project asset selected by media UUID in the frame-slot dialog [frame_ref_attached, startImage bound on the wire, ZERO upload events] produced a real 720×1280 interpolation, resolving the #237 negative prior; foreign UUID → exit 9 pre-generation with screenshot; **#288 duration fail-fast proven live** — exit 23 pre-submit saved a 10-credit generation, and the debug screenshot confirmed the duration control is ABSENT from the cohort's settings popover [locale hypothesis refuted]; upload-400 exit-27 repro deferred-with-reason — the original rejected JPEG no longer exists). Prior: [v0.31.0](LIVE_VERIFICATION_v0.31.0.md) (**#281 wrong-media defenses live-verified in BOTH directions, credit-free** — correct attribution downloads with real wire metadata [seed, 768×1376]; the incident-class lazy-render ambiguity reproduced live and hard-stopped with `MediaAttributionError` exit 26 naming every candidate UUID, no file written; **#282 two-UUID-ref i2i proven e2e** — both freshly generated portrait UUIDs picker-selected into one scene with both canonical identities visually transferred). Prior: [v0.30.0](LIVE_VERIFICATION_v0.30.0.md) (**agentic-cohort image path + both fixes live-verified credit-free** — native 768×1376 stills, i2i-chain + canonical-ref identity hold; the character-create `DataIntegrityError` and the `prefer_classic` WARNING were observed live then fixed [recorder idempotent + INFO log]; MCP video-param feature deferred-with-reason on Veo credits, per the stills-only goal). Prior: [v0.29.0](LIVE_VERIFICATION_v0.29.0.md) (**persistent `gflow instructions` CRUD proven live e2e GREEN, credit-free** — 11-command sequence on a fresh project: add incl. `--ref <image-UUID>` attach, list/enable/disable, master toggle both ways, TOML `apply` destructive full-sync with `enabled=false` honored, `rm` with server card-id preserved across mutations; movie brief-sync code-path-verified via the same primitives, deferred-with-reason on credits; MCP `gflow_instructions_*` tools are thin adapters over the live-verified primitives). Prior: [v0.28.0](LIVE_VERIFICATION_v0.28.0.md) (**agent instructions `-i` now steer agentic generation — crayon e2e GREEN**: a style-neutral prompt + an enabled "crayon" card produced an unmistakable crayon drawing through the real transport; root causes were conversational phrasing + the `project_brief.enabled` master switch). Prior: [v0.27.1](LIVE_VERIFICATION_v0.27.1.md) (**v0.27.0 release follow-up fixes and documentation sync**). Prior: [v0.27.0](LIVE_VERIFICATION_v0.27.0.md) (**`[style]` block with named variants + prompt-aware resume — credit-free CLI verification**: real `movie run --dry-run` 3-way ledger proving resolved-style display, `skip (done)` on matching `style_hash`, and `re-run (style changed)` after a style edit; composition is local, wire path untouched, so no Veo credits spent — first credited styled run will confirm visually). Prior: [v0.26.0](LIVE_VERIFICATION_v0.26.0.md) (**image i2i by generated-image UUID proven live e2e GREEN** — the existing asset is *selected in place* by its media UUID, no duplicate upload, producing an i2i output that references it; plus generated-image `display_name` capture, credited @C1ph3r404). Prior: [v0.25.0](LIVE_VERIFICATION_v0.25.0.md) (**#237 remote-UUID i2v proven live e2e GREEN** — a real 8s 720×1280 interpolation from a generated image's UUID, after the picker-search attach was reworked to local upload; #240 home-`.env` matrix live; plus two silent-failure guards root-caused live: video-as-image download rejection and rejected-upload fail-loud). Prior: [v0.24.0](LIVE_VERIFICATION_v0.24.0.md) (--project parity across CLI + MCP — automated coverage; live gen auth-gated). Prior: [v0.23.0](LIVE_VERIFICATION_v0.23.0.md) (MCP generation wiring proven live end-to-end — tool→worker→real Flow REST→structured-error translation; final image-write blocked by an expired session, environmental. #222 macOS fix reporter-verified e2e on Apple Silicon). Prior: [v0.22.0](LIVE_VERIFICATION_v0.22.0.md) (Tools framework — automated/CI coverage complete; credit/key-gated live feature run is a pending owner gate, see the doc) · [v0.21.0](LIVE_VERIFICATION_v0.21.0.md) (MCP server over stdio + HTTP/SSE — credit-free protocol handshake; 4 tools / 2 prompts / 3 resources confirmed on stdout) · [v0.20.1](LIVE_VERIFICATION_v0.20.1.md) · [v0.20.0](LIVE_VERIFICATION_v0.20.0.md) · [v0.19.0](LIVE_VERIFICATION_v0.19.0.md) · [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
 **"Where is the reverse-engineered wire protocol for a feature?"** → the `*_RECON.md` design docs: [CHARACTER_RECON](CHARACTER_RECON.md) (Flow character entity protocol), [IMAGE_UPSCALE_RECON](IMAGE_UPSCALE_RECON.md) (`/v1/flow/upsampleImage` wire). Naming convention: one `<FEATURE>_RECON.md` per reverse-engineered surface, kept as the durable spec after the feature ships.
 **"What was live-verified for the data layer (PR #58)?"** → [LIVE_VERIFICATION_data_layer](LIVE_VERIFICATION_data_layer.md) — 1 Imagen + 1 Veo credit on denon82, 6-layer ledger (file + magic + Pillow + DB rows + CLI round-trip + structlog)
 **"What was live-verified for the video-download feature (#29)?"** → [LIVE_VERIFICATION_video_download](LIVE_VERIFICATION_video_download.md)

gflow_cli-0.32.1/docs/LIVE_VERIFICATION_v0.32.0.md

@@ -0,0 +1,74 @@
+# Live verification — v0.32.0 (2026-07-11)
+
+Scope: the two user-facing changes of this release, exercised against live Flow
+on the `denon82` profile (Classic strategy, Chrome, Windows 11; Flow renders in
+Portuguese for this profile — `/fx/pt/` redirect). Credits spent: **1 image +
+1 video generation**; every failure-path check completed pre-submit at zero
+credit cost.
+
+## 1. `gflow video i2v --initial-frame <UUID>` — in-project asset selection (#287, PR #290)
+
+The declared-riskiest surface: the frame-slot dialog carried a negative prior
+(#237's name-search never surfaced generated media there — see
+[LIVE_VERIFICATION_v0.25.0](LIVE_VERIFICATION_v0.25.0.md)). The thumbnail-URL
+tile match succeeds where name search failed.
+
+Run: seed `gflow image t2i` (asset `0bbcdf05-19e0-43c3-bbeb-ba0ff7246e54`,
+project `dd9e498c-22b1-4d73-a748-0bc0eac14c8b`), then
+`gflow video i2v --initial-frame 0bbcdf05-… "slow cinematic push-in toward the
+mug, steam rising gently" --project dd9e498c-… --profile denon82 --json`
+(correlation `92b99c8c-5d69-4e00-905f-734f8eb6dadc`).
+
+5-layer ledger:
+
+1. **File count:** exactly 1 mp4 in `--out-dir` (`b61bcce6-baca-4934-b6e5-5ca84e10b49a.mp4`, 3,031,564 bytes).
+2. **Magic bytes:** `00 00 00 20 66 74 79 70 69 73 6f 6d` — valid `ftypisom` MP4 header.
+3. **Dimensions/shape:** ffprobe `720×1280`, duration `8.000000` s (Flow default — no `--duration` passed, correct).
+4. **Structlog invariants:**
+   - `ui_automation_video.frame_ref_attached {slot: Start, media_id: 0bbcdf05…}` — UUID picker selection in the frame-slot dialog;
+   - `ui_automation_video.generate_captured {url: …/video:batchAsyncGenerateVideoStartImage, image_inputs.startImage: "0bbcdf05"}` — the asset is bound in the actual wire request (no #125 T2V fallback);
+   - **zero `image_uploaded` events** in the whole run — no duplicate upload (the founding goal of #287);
+   - `poll_terminal {status: MEDIA_GENERATION_STATUS_SUCCESSFUL}` → `video_saved`.
+5. **User-confirmable artifact:** video `b61bcce6-…` in Flow project `dd9e498c-…` (denon82 account) — a genuine motion interpolation of the seeded red-mug still.
+
+Negative check (free): a foreign UUID (`00000000-0000-4000-8000-000000000001`)
+in the same project → **exit 9** (`TransportTimeoutError`) pre-generation, the
+message naming slot + UUID + the `--project` hint, with
+`debug_frame_ref_miss_start.png` captured (valid PNG).
+
+Not verified this cycle: a live `uploadImage` HTTP-400 → exit 27
+(`MediaUploadRejectedError`) repro — the original Flow-rejected JPEG from the
+2026-07-11 pilot no longer exists on disk (only thumbnails survive). The typed
+raise is pinned by a unit test that drives the real `_upload_via_open_dialog`
+listener with a 400 response (`tests/api/transports/test_ui_automation_video.py::TestUploadRejectionTypedError`).
+The KNOWN_ISSUES entry on metadata-sensitive rejections tracks the live case.
+
+## 2. `--duration` fail-fast (#288, PR #289)
+
+Run: `gflow video i2v <local file> "slow pan across the mug" --duration 4
+--profile denon82 --json` (correlation `b8e66830-58bf-4928-9afe-1eecbbfcdb60`).
+
+- `duration_tab` probe missed (reproducing the pilot's 3/3) and the run
+  **aborted pre-submit with exit 23** (`UiSelectorDriftError`) — the settings
+  popover showed "A geração vai usar 10 créditos", so the fail-fast saved that
+  spend instead of delivering a silent 8-second clip reported as success.
+- `debug_no_duration_tab.png` captured (valid PNG, `89 50 4E 47` header) and
+  **answers the #288 investigation: the duration control is absent from this
+  cohort's Frames-submode settings popover** (rows rendered: Imagem/Vídeo →
+  Frames/Elementos → 9:16/16:9 → 1x/x2/x3/x4 → model dropdown; no duration
+  row). The council's locale hypothesis is refuted — the UI is Portuguese and
+  the sibling text-matched count tabs match fine.
+- Happy-path caveat, recorded per the honesty rule: "duration tab found →
+  clicked" is unverifiable on this cohort because the control does not exist.
+  If a cohort still renders duration tabs, the pre-existing selector cascade
+  should match them unchanged; the fail-fast only fires on a miss.
+
+## Incidental live findings (logged on their issues)
+
+- Project `f6caf027-…` opens in the full-page media-library UI (#174 shape,
+  "Agente" composer pill) where even `mode_switch_trigger` fails — fresh
+  projects still get the classic composer and work. Posted to #288/#174 trail.
+- Error-path browser teardown can leave Chrome holding the profile dir
+  (subsequent runs die with `TargetClosedError` until the process is killed),
+  and `_capture_debug_screenshot` can report a screenshot path it never wrote
+  when capture fails. Both noted as #283-wave follow-ups.

gflow_cli-0.32.1/docs/LIVE_VERIFICATION_v0.32.1.md

@@ -0,0 +1,46 @@
+# Live verification — v0.32.1 (2026-07-11)
+
+Patch release: the #293 teardown fix (PR #294) plus the #283 follow-up wave
+(PR #292). All verification credit-free.
+
+## 1. Browser teardown — no leaked Chrome after error exits (#293, PR #294)
+
+Baseline (pre-fix, same day): three separate error-exit runs on the `denon82`
+profile left a full Chrome tree holding the profile dir; the next run died at
+context launch with `TargetClosedError` → "Unexpected error." exit 1.
+
+Post-fix live repro, run twice (pre- and post-review-refactor):
+
+1. Trigger an error-path abort: `gflow video i2v --initial-frame
+   <foreign-UUID> … --project dd9e498c-… --profile denon82` → **exit 9**
+   (typed picker-miss abort, pre-credit).
+2. Immediately after process exit:
+   `Get-CimInstance Win32_Process -Filter "Name='chrome.exe'"` filtered on
+   `profile_denon82` in the command line → **0 processes**, both runs.
+3. Follow-up launches in the same session succeeded cleanly (no
+   `TargetClosedError` at launch).
+
+Honest caveat: in both post-fix runs the *graceful* close succeeded within the
+bound, so the force-close fallback did not fire live — its trigger (a wedged
+close) is nondeterministic. The fallback branch is pinned by unit tests
+(`tests/api/test_concurrency.py`: force-close ordering before driver stop,
+double-failure last resort, hang-timeout path, both `_is_target_closed`
+branches), and `context.browser` being non-None for persistent contexts was
+verified against the pinned Playwright 1.59.0 package source.
+
+The `ProfileLockedError` (exit 11) launch translation is unit-verified; a live
+sample requires deliberately wedging a browser and was not manufactured.
+
+## 2. #283 wave (PR #292) — logic-level fixes, unit-pinned
+
+The picker scroll off-by-one, `await_images` stable-break, and phantom
+screenshot paths are pure logic around mocked DOM scrapes — the unit tests are
+the affected surface (mock-verified to the exact call counts: 12 pre-scroll
+checks + 1 post-loop re-check). The phantom-screenshot fix's real-world
+trigger was itself observed live on 2026-07-11 (an error message named a
+`debug_no_mode_trigger.png` that was never written — the empty directory is
+the evidence); post-fix, capture failures return `None` and every message
+appends its `Screenshot:` clause conditionally.
+
+Deferred-with-reason: no credited generation was needed for this patch — no
+generation-path behavior changed.

{gflow_cli-0.31.0 → gflow_cli-0.32.1}/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, 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_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). Note the CLI's semantics diverge here (#287): `gflow video i2v --initial-frame <UUID>` selects the asset **in the project's media picker with no upload** and needs no local catalog entry — so the same UUID input can succeed on one surface and fail on the other.
 * `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.31.0 → gflow_cli-0.32.1}/docs/USAGE.md

@@ -67,7 +67,7 @@ See [AUTHENTICATION § Commands](AUTHENTICATION.md#commands).
 
 ## `gflow image upload`
 
-Upload a local PNG/JPEG/WebP/GIF into a fresh Flow project and print the asset UUID + dimensions Flow inferred. The UUID is what later subcommands (`gflow image i2i --ref UUID`, `video i2v`) accept as an initial frame.
+Upload a local PNG/JPEG/WebP/GIF into a fresh Flow project and print the asset UUID + dimensions Flow inferred. The UUID is what later subcommands (`gflow image i2i --ref UUID`, `video i2v`) accept as an initial frame. Note for `video i2v`: the UUID is selected from the generation project's media picker, and `upload` puts the asset in a *fresh scratch project* — so pass `--project <id>` of the project that holds the asset, or the picker lookup fails with exit 9 (#287).
 
 ```text
 gflow image upload PATH [OPTIONS]
@@ -460,9 +460,12 @@ gflow video t2v "a dog surfing" --tool creative-director:style=cinematic
 ## `gflow video i2v`
 
 Generate a video from an INITIAL frame (+ optional END frame) and a motion prompt.
-Each image is a local PNG/JPEG; it is bound into the editor's frame slot via the
-media dialog, then Flow fires `batchAsyncGenerateVideoStartImage` (initial only) or
-`…StartAndEndImage` (initial+end interpolation).
+Each frame is a local PNG/JPEG **or the media UUID of an existing in-project asset**
+(#287 — the asset is selected in place, no duplicate upload; pair with `--project`
+so the UUID's project is the one being generated in). A local file is bound into
+the editor's frame slot via the media dialog, then Flow fires
+`batchAsyncGenerateVideoStartImage` (initial only) or `…StartAndEndImage`
+(initial+end interpolation).
 
 ```text
 gflow video i2v --initial-frame INITIAL [--end-frame LAST] PROMPT [--model] [--duration] [--count] [--aspect] [...]
@@ -474,19 +477,28 @@ Arguments:
   PROMPT  Motion prompt.  [required]
 
 Options:
-  --initial-frame PATH  Initial frame to animate. Canonical form; replaces the positional IMAGE.
-  --end-frame PATH      Optional end frame — Flow interpolates initial frame -> end frame.
-  --project ID          Generate in this EXISTING Flow project instead of a
-                        scratch project (see "Sharing one project across calls").
+  --initial-frame PATH|UUID  Initial frame to animate: local image path or in-project
+                             asset media UUID. Canonical form; replaces the positional IMAGE.
+  --end-frame PATH|UUID      Optional end frame — Flow interpolates initial frame -> end frame.
+  --project ID               Generate in this EXISTING Flow project instead of a
+                             scratch project (see "Sharing one project across calls").
 ```
 
 ```bash
 gflow video i2v --initial-frame ./hero.png "Slow camera arc, soft golden light"
 gflow video i2v --initial-frame ./first.png --end-frame ./last.png "morph between scenes" --model veo-quality
+# Reference an existing in-project asset by media UUID (no re-upload, #287):
+gflow video i2v --initial-frame d6f1927a-3eae-4626-bc90-9a6ea7637bab "pan left" --project f6caf027-...
 # Back-compat positional form:
 gflow video i2v ./hero.png "Slow camera arc, soft golden light"
 ```
 
+Exit codes specific to this surface: **27** — Flow's upload endpoint rejected a
+local frame file (`MediaUploadRejectedError`; try re-encoding, e.g.
+`ffmpeg -i in.jpg -q:v 2 -map_metadata -1 out.jpg`, or reference the asset by
+UUID instead); **9** — a frame UUID could not be located in the project's media
+picker (`TransportTimeoutError`; wrong `--project` or foreign UUID).
+
 ## `gflow video r2v`
 
 Reference-to-video (Flow "ingredients"): condition a generation on reference
@@ -1212,7 +1224,7 @@ shell scripts can branch on the failure mode without parsing stderr.
 | `6`  | `NetworkError`        | Network failure persisted across 3 attempts      | Check connectivity                                         |
 | `7`  | `WireFormatError`     | Unexpected response shape — Flow API changed     | File a bug (do NOT include captured tokens or signed URLs) |
 | `8`  | `AuthMissingError`    | Required auth credential is absent from profile   | `gflow auth login --profile <name>`                        |
-| `9`  | `TransportTimeoutError` | Browser/API operation exceeded its timeout      | Retry; raise the relevant timeout if needed                |
+| `9`  | `TransportTimeoutError` | Browser/API operation exceeded its timeout (incl. an i2v frame UUID not found in the media picker, #287) | Retry; raise the relevant timeout — or, for a frame-UUID miss, verify the UUID belongs to the `--project` passed |
 | `10` | `WafRejectionError`   | Flow security layer rejected the request          | Change prompt/request and retry                            |
 | `11` | `ConfigurationError`  | Local configuration or browser mode is invalid    | Fix the option/env var shown in the error                  |
 | `12` | `AuthLoginTimeoutError` | Browser sign-in was not completed in time       | Re-run login or raise `GFLOW_CLI_AUTH_LOGIN_TIMEOUT`       |
@@ -1228,6 +1240,9 @@ shell scripts can branch on the failure mode without parsing stderr.
 | `22` | `UpscaleUnavailableError` | 4K upscale is gated to Flow **Ultra** accounts (HTTP 403) | Use `--scale 2k`, or upgrade the Flow plan                |
 | `23` | `UiSelectorDriftError` | A Flow editor control could not be located — Google changed the frontend (issue #183) | Update gflow-cli; file a bug with the probe name + debug screenshot from the error message |
 | `24` | `BrowserEngineUnavailableError` | `GFLOW_CLI_BROWSER_ENGINE=patchright` but the engine is not installed | `pip install 'gflow-cli[patchright]'`, or unset `GFLOW_CLI_BROWSER_ENGINE` |
+| `25` | `FlowAgentUiError`    | The profile is on Flow's Agentic UI cohort and the classic media panel is unrecoverable for this operation | Use a Classic-cohort profile; see KNOWN_ISSUES on the agentic cohort |
+| `26` | `MediaAttributionError` | Generated media could not be reliably attributed to this request (issue #281) | Re-run; a dedicated project with fewer pre-existing assets avoids the ambiguity |
+| `27` | `MediaUploadRejectedError` | Flow's upload endpoint refused the input file (`uploadImage` 4xx, issue #287) | Re-encode the image (`ffmpeg -q:v 2 -map_metadata -1`), or reference the asset by its media UUID |
 | `130`| SIGINT                | User-interrupted (Ctrl-C)                        | —                                                          |
 
 **Exit code 16 — data store / migration error.** Fires when:

{gflow_cli-0.31.0 → gflow_cli-0.32.1}/pyproject.toml

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

{gflow_cli-0.31.0 → gflow_cli-0.32.1}/scripts/dev/spike_movie_attach_payload.py

@@ -106,7 +106,7 @@ async def _run(
             if full:
                 await VideoGenerationMixin._select_video_aspect(page, Aspect.PORTRAIT)  # noqa: SLF001
                 await VideoGenerationMixin._set_output_count(page, 1)  # noqa: SLF001
-                await VideoGenerationMixin._select_video_duration(page, 8)  # noqa: SLF001
+                await VideoGenerationMixin._select_video_duration(page, 8, out_dir=None)  # noqa: SLF001
                 await page.keyboard.press("Escape")
                 await page.wait_for_timeout(600)
             await page.wait_for_timeout(800)

{gflow_cli-0.31.0 → gflow_cli-0.32.1}/skills/gflow-cli/SKILL.md

@@ -68,7 +68,7 @@ gflow image i2i "<prompt>" --ref PATH_OR_UUID [--ref ...] [...same as t2i]
 
 # Video generation (Veo 3.1)
 gflow video t2v "<prompt>" [--out-dir DIR] [--aspect ...] [--seed N]
-gflow video i2v --initial-frame <image> "<prompt>" [--out-dir DIR] [...same as t2v]
+gflow video i2v --initial-frame <image|media-UUID> "<prompt>" [--out-dir DIR] [...same as t2v]  # UUID = in-project asset, no re-upload (#287; pair with --project)
 gflow video batch <manifest.tsv> [--out-dir DIR]
 gflow video chain <manifest.jsonl> [--out-dir DIR] [--dry-run] \
                   [--max-links N] [--resume-from N]   # last-frame I2V chaining; veo models only
@@ -259,7 +259,7 @@ Documented errors agents commonly make — negative examples for the SkillOpt tr
 | `playwright install` or `playwright install --all` | `uvx --from gflow-cli playwright install chromium` (Chromium only, ~150 MB) |
 | Running two generations on the same `--profile` in parallel | Use different `--profile` names — Chromium refuses two persistent contexts on the same dir |
 | `GFLOW_CLI_HEADLESS=true` to fix reCAPTCHA failures | `GFLOW_CLI_HEADLESS=false` — headless mode *causes* bot-detection, not prevents it |
-| Calling `gflow image upload` again for an already-uploaded UUID | Pass the UUID directly to `--ref UUID` — no re-upload needed |
+| Calling `gflow image upload` again for an already-uploaded UUID | Pass the UUID directly to `--ref UUID` (i2i) or `--initial-frame/--end-frame UUID` (i2v, with `--project`) — no re-upload needed |
 | `--model imagen` / `--model quality` / `--model high` | `--model image4` (Imagen 3.5), `--model nano-pro` (Gem Pix 2), `--model nano2` (Narwhal) |
 | Python: `client = FlowApiClient(...)` then method calls | Must use `async with FlowApiClient(...) as client:` — it's an async context manager |
 | Python: `from gflow_cli import FlowApiClient` | `from gflow_cli.api.client import FlowApiClient` |

{gflow_cli-0.31.0 → gflow_cli-0.32.1}/src/gflow_cli/__init__.py

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

{gflow_cli-0.31.0 → gflow_cli-0.32.1}/src/gflow_cli/api/_engine.py

@@ -25,6 +25,7 @@ This module is the single place that reconciles the two engines' differences:
 
 from __future__ import annotations
 
+import asyncio
 import importlib
 from typing import TYPE_CHECKING, Any, cast
 
@@ -48,6 +49,66 @@ _PATCHRIGHT_PIP_HINT = (
 )
 
 
+# Teardown deadlines (issue #293). The graceful bound is generous on purpose:
+# for a persistent context, close() is Chrome flushing profile state (the
+# cookie DB is this product's auth store) and Playwright's driver hard-kills
+# the process if a second close arrives mid-graceful-close — so escalating a
+# merely-slow close would risk corrupting the profile. The force bound is
+# short: it only matters when the graceful close already failed, and a dead
+# driver connection would otherwise burn the full window as pure delay.
+_CONTEXT_CLOSE_TIMEOUT_S = 30.0
+_FORCE_CLOSE_TIMEOUT_S = 5.0
+DRIVER_STOP_TIMEOUT_S = 10.0
+
+
+async def _force_close_browser(context: Any, *, owner: str) -> None:
+    """Force-close ``context.browser``, bounded — never raises Exception."""
+    try:
+        browser = context.browser
+        if browser is not None:
+            await asyncio.wait_for(browser.close(), timeout=_FORCE_CLOSE_TIMEOUT_S)
+            logger.warning(
+                "browser_teardown.force_close_returned",
+                owner=owner,
+                note=(
+                    "graceful context close failed; browser.close() returned "
+                    "(the browser may also simply have been gone already)"
+                ),
+            )
+    except Exception:
+        # ponytail: an OS-level tree kill needs a chrome PID that
+        # playwright-python does not expose for persistent contexts.
+        logger.error(
+            "browser_teardown.force_close_failed",
+            owner=owner,
+            remediation=(
+                "a browser may still hold this profile dir — close Chrome "
+                "windows using it, or kill the Chrome processes (chrome.exe "
+                "on Windows) whose command line names the profile dir"
+            ),
+            exc_info=True,
+        )
+
+
+async def close_context_bounded(context: Any, *, owner: str) -> None:
+    """Close a persistent BrowserContext without hanging or leaking chrome.
+
+    Issue #293: an unbounded ``context.close()`` can hang forever on a wedged
+    page, and a close that FAILS leaves the system-Chrome tree alive holding
+    the profile dir once the driver stops — the graceful close is what asks
+    Chrome to exit. Bounds the graceful close, then force-closes the browser
+    on any failure. On cancellation (Ctrl-C mid-teardown) the force-close is
+    still attempted best-effort before the cancellation propagates.
+    """
+    try:
+        await asyncio.wait_for(context.close(), timeout=_CONTEXT_CLOSE_TIMEOUT_S)
+    except BaseException as exc:
+        logger.warning("browser_teardown.context_close_error", owner=owner, exc_info=True)
+        await _force_close_browser(context, owner=owner)
+        if not isinstance(exc, Exception):
+            raise
+
+
 def active_engine() -> BrowserEngine:
     """Return the configured browser engine (validated ``BrowserEngine`` enum)."""
     return get_settings().browser_engine

{gflow_cli-0.31.0 → gflow_cli-0.32.1}/src/gflow_cli/api/client.py

@@ -29,7 +29,9 @@ from playwright.async_api import BrowserContext, Page, Playwright, async_playwri
 
 from gflow_cli.api import routes
 from gflow_cli.api._engine import (
+    DRIVER_STOP_TIMEOUT_S,
     active_engine,
+    close_context_bounded,
     log_engine_selected,
     mint_evaluate_kwargs,
     resolve_async_playwright,
@@ -57,6 +59,7 @@ from gflow_cli.errors import (
     ContentPolicyError,
     FlowApiError,  # re-exported via gflow_cli.api.__init__
     NetworkError,
+    ProfileLockedError,
     RateLimitError,
     SceneConcatError,
     TransportTimeoutError,
@@ -547,7 +550,34 @@ class FlowApiClient:
         await self._preread_flow_session_cookies()
         kwargs = self._persistent_context_kwargs()
         self._log_and_guard_launch(kwargs)
-        self._context = await self._pw.chromium.launch_persistent_context(**kwargs)
+        try:
+            self._context = await self._pw.chromium.launch_persistent_context(**kwargs)
+        except Exception as exc:
+            if _is_target_closed(exc):
+                # A TargetClosedError at LAUNCH usually means the profile dir
+                # is held by another Chrome — most commonly a stale browser
+                # leaked by a crashed prior run (issue #293) or a concurrent
+                # gflow run. It CAN also be an unrelated startup crash, so
+                # the original error is carried in the detail and the wording
+                # hedges rather than asserts.
+                first_line = str(exc).splitlines()[0] if str(exc) else type(exc).__name__
+                raise ProfileLockedError(
+                    detail=(
+                        f"the browser exited immediately while launching on profile "
+                        f"dir {self.profile_dir} — most likely another Chrome holds "
+                        f"it (original error: {first_line})"
+                    ),
+                    remediation_hint=(
+                        "Another gflow run — or a stale Chrome left by a crashed one "
+                        "— may hold this profile. Close Chrome windows using this "
+                        "profile (or kill the Chrome processes — chrome.exe on "
+                        "Windows — whose command line names the profile dir) and "
+                        "re-run, or use a different --profile. If no such process "
+                        "exists, the browser crashed at startup for another reason; "
+                        "see the original error above."
+                    ),
+                ) from exc
+            raise
         # Hide the automation flag so reCAPTCHA Enterprise doesn't score
         # the session as a bot — navigator.webdriver=true causes low-score
         # tokens and HTTP 403 on batchGenerateImages.
@@ -655,23 +685,26 @@ class FlowApiClient:
         silently swallow). Resets the browser fields so a reused client never
         holds references to a dead BrowserContext.
         """
-        if self._context is not None:
-            try:
-                await self._context.close()
-            except Exception:
-                # Browser cleanup is best-effort but MUST be surfaced for
-                # diagnosis (CLAUDE.md: never silently swallow errors).
-                logger.warning("browser_context_close_error", exc_info=True)
-        if self._pw is not None:
-            try:
-                await self._pw.stop()
-            except Exception:
-                logger.warning("playwright_stop_error", exc_info=True)
-        self._pages = []
-        self._page_queue = None
-        self._page = None
-        self._context = None
-        self._pw = None
+        try:
+            if self._context is not None:
+                # Bounded close + force-close fallback (issue #293) — shared
+                # with the transports' own-context teardowns via _engine.
+                await close_context_bounded(self._context, owner="client")
+            if self._pw is not None:
+                try:
+                    # pw.stop() awaits the Node driver's exit with no deadline
+                    # of its own — a wedged driver would hang teardown forever.
+                    await asyncio.wait_for(self._pw.stop(), timeout=DRIVER_STOP_TIMEOUT_S)
+                except Exception:
+                    logger.warning("playwright_stop_error", exc_info=True)
+        finally:
+            # Field resets must survive even cancellation (Ctrl-C mid-close),
+            # or a reused client holds references to a dead BrowserContext.
+            self._pages = []
+            self._page_queue = None
+            self._page = None
+            self._context = None
+            self._pw = None
 
     async def _checkout_page(self) -> Page:
         """Block until a Page is available from the pool; FIFO.