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

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

@@ -7,6 +7,20 @@ 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
@@ -1919,7 +1933,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.32.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

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

@@ -798,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
@@ -815,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.32.0 → gflow_cli-0.32.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.32.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.32.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.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)
+**"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.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.32.0 → gflow_cli-0.32.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gflow-cli"
-version = "0.32.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.32.0 → gflow_cli-0.32.1}/src/gflow_cli/__init__.py

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

{gflow_cli-0.32.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.32.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.

{gflow_cli-0.32.0 → gflow_cli-0.32.1}/src/gflow_cli/api/image_upscale.py

@@ -19,12 +19,13 @@ Wire facts (reverse-engineered, see ``docs/IMAGE_UPSCALE_RECON.md``)::
 
 from __future__ import annotations
 
-import re
 from dataclasses import dataclass, field
 from enum import StrEnum
 from types import MappingProxyType
 from typing import Any
 
+from gflow_cli.api.video import is_media_uuid
+
 __all__ = [
     "DEFAULT_PAYGATE_TIER",
     "TargetResolution",
@@ -45,10 +46,6 @@ DEFAULT_PAYGATE_TIER = "PAYGATE_TIER_ONE"
 # Strict UUID allowlist for the source mediaId and the owning projectId. Both
 # are interpolated into the request body (not a URL path), but validating up
 # front rejects malformed input before any reCAPTCHA mint or network call fires
-# (scenario #9). Flow media + project ids are both 8-4-4-4-12 hex UUIDs.
-_UUID_RE = re.compile(
-    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
-)
 
 
 class TargetResolution(StrEnum):
@@ -114,13 +111,13 @@ class UpsampleImageRequest:
     recaptcha_token: str = field(default="")
 
     def __post_init__(self) -> None:
-        if not _UUID_RE.fullmatch(self.media_id):
+        if not is_media_uuid(self.media_id):
             msg = (
                 f"UpsampleImageRequest.media_id must be a bare UUID "
                 f"(8-4-4-4-12 hex, no whitespace); got {self.media_id!r}"
             )
             raise ValueError(msg)
-        if not _UUID_RE.fullmatch(self.project_id):
+        if not is_media_uuid(self.project_id):
             msg = (
                 f"UpsampleImageRequest.project_id must be a bare UUID "
                 f"(8-4-4-4-12 hex, no whitespace); got {self.project_id!r}"

{gflow_cli-0.32.0 → gflow_cli-0.32.1}/src/gflow_cli/api/transports/drivers/agentic.py

@@ -478,6 +478,14 @@ class AgenticFlowUiDriver:
         interval of wall time up front; the total poll timeout budget
         (``_AWAIT_TIMEOUT_S``) is unchanged.
 
+        **Stable break (issue #283):** reaching ``expected_count`` on a single
+        scrape is not trusted — a lazily-rendered pre-existing tile can
+        transiently hit the exact count. The loop breaks only when the same
+        new-UUID set holds across two consecutive scrapes (~one extra 0.5s
+        poll). Deliberate fall-through: a set that first reaches the exact
+        count on the final poll before the deadline is returned unconfirmed —
+        better a last-second success than a spurious timeout.
+
         **Ambiguity fail-fast (issue #281):** if more new UUIDs appear than
         were requested, there is no reliable way to tell which ones belong to
         this generation. Rather than arbitrarily slice the unordered set (the
@@ -503,6 +511,7 @@ class AgenticFlowUiDriver:
 
         deadline = asyncio.get_event_loop().time() + _AWAIT_TIMEOUT_S
         new_uuids: set[str] = set()
+        prev_new_uuids: set[str] | None = None
 
         while asyncio.get_event_loop().time() < deadline:
             await asyncio.sleep(_POLL_INTERVAL_S)
@@ -522,8 +531,14 @@ class AgenticFlowUiDriver:
             current_uuids = _extract_uuids(current_srcs)
             new_uuids = current_uuids - baseline_uuids
 
-            if len(new_uuids) >= expected_count:
+            if len(new_uuids) > expected_count:
+                break  # ambiguity — fail fast below (#281)
+            # Stable-break (#283): exact-count on a single scrape can still be
+            # a lazy-render race; require the SAME set on two consecutive
+            # scrapes (~one extra poll interval) before trusting it.
+            if len(new_uuids) == expected_count and new_uuids == prev_new_uuids:
                 break
+            prev_new_uuids = set(new_uuids)
 
         if len(new_uuids) < expected_count:
             if new_uuids:
@@ -543,9 +558,7 @@ class AgenticFlowUiDriver:
             raise MediaAttributionError(
                 detail=(
                     f"Cannot attribute the generation among {len(candidates)} candidate "
-                    f"media UUIDs (expected {expected_count}): {candidates}. Re-run the "
-                    "generation; a dedicated project with fewer pre-existing assets "
-                    "avoids lazy-render ambiguity."
+                    f"media UUIDs (expected {expected_count}): {candidates}."
                 ),
                 route="agentic:await_images",
             )

{gflow_cli-0.32.0 → gflow_cli-0.32.1}/src/gflow_cli/api/transports/experimental/evaluate_fetch.py

@@ -267,10 +267,10 @@ class EvaluateFetchTransport:
         """
         if self._owns_playwright:
             if self._ctx is not None:
+                from gflow_cli.api._engine import close_context_bounded  # noqa: PLC0415
+
                 try:
-                    await self._ctx.close()
-                except Exception:
-                    log.warning("evaluate_fetch.teardown: ctx.close() failed", exc_info=True)
+                    await close_context_bounded(self._ctx, owner="evaluate_fetch")
                 finally:
                     self._ctx = None
                     self._page = None

{gflow_cli-0.32.0 → gflow_cli-0.32.1}/src/gflow_cli/api/transports/ui_automation.py

@@ -35,6 +35,7 @@ from gflow_cli.api.transports.ui_automation_video import (
     ENTITY_ATTACH_DRIFT_HINT,
     MODE_SWITCH_TRIGGER_SELECTORS,
     VideoGenerationMixin,
+    screenshot_clause,
     selector_drift_detail,
     zip_entity_refs,
 )
@@ -178,6 +179,7 @@ async def _capture_debug_screenshot(
         )
     except Exception as e:
         log.debug("ui_automation.screenshot_capture_failed", error=str(e))
+        return None  # never report a path that was not written (#283)
     return shot_path
 
 
@@ -741,6 +743,7 @@ class UiAutomationTransport(VideoGenerationMixin):
         # opt-in patchright engine routes through the resolver.
         from gflow_cli.api._engine import (
             active_engine,
+            close_context_bounded,
             log_engine_selected,
             resolve_async_playwright,
         )
@@ -766,6 +769,7 @@ class UiAutomationTransport(VideoGenerationMixin):
         # ``.chromium.launch_persistent_context`` surface; type as Any so this
         # standalone path is engine-agnostic without per-engine stubs.
         pw: Any = await pw_cm.__aenter__()
+        ctx = None
         try:
             import os
 
@@ -805,7 +809,11 @@ class UiAutomationTransport(VideoGenerationMixin):
                 profile_dir=str(profile_dir),
             )
         except Exception:
-            # Partial-setup leak guard.
+            # Partial-setup leak guard. The context must be closed BEFORE the
+            # driver exits — stopping only the driver leaves the detached
+            # system-Chrome alive holding the profile dir (issue #293).
+            if ctx is not None:
+                await close_context_bounded(ctx, owner="ui_automation")
             await pw_cm.__aexit__(None, None, None)
             raise
 
@@ -1039,8 +1047,8 @@ class UiAutomationTransport(VideoGenerationMixin):
 
         shot_path = await _capture_debug_screenshot(page, out_dir, "debug_new_project.png")
         msg = (
-            f"Could not find 'New project' CTA on Flow gallery. URL: {page.url}. "
-            f"Screenshot: {shot_path}"
+            f"Could not find 'New project' CTA on Flow gallery. "
+            f"URL: {page.url}.{screenshot_clause(shot_path)}"
         )
         raise RuntimeError(
             msg,
@@ -1182,7 +1190,7 @@ class UiAutomationTransport(VideoGenerationMixin):
                 continue
 
         shot_path = await _capture_debug_screenshot(page, out_dir, "debug_prompt_not_found.png")
-        msg = f"Prompt input not found in Flow UI. URL: {page.url}. Screenshot: {shot_path}"
+        msg = f"Prompt input not found in Flow UI. URL: {page.url}.{screenshot_clause(shot_path)}"
         raise RuntimeError(msg)
 
     async def _click_submit(self, page: Page) -> None:
@@ -2767,7 +2775,7 @@ class UiAutomationTransport(VideoGenerationMixin):
             )
             msg = (
                 f"Character editor not ready: prompt textbox not visible "
-                f"within 20 s. URL: {page.url}. Screenshot: {shot}"
+                f"within 20 s. URL: {page.url}.{screenshot_clause(shot)}"
             )
             raise RuntimeError(msg) from exc
 
@@ -3026,13 +3034,20 @@ class UiAutomationTransport(VideoGenerationMixin):
         if not self._setup_done:
             return
         if self._owns_playwright and self._pw_cm is not None:
+            from gflow_cli.api._engine import (  # noqa: PLC0415
+                DRIVER_STOP_TIMEOUT_S,
+                close_context_bounded,
+            )
+
+            if self._ctx is not None:
+                # Bounded close + force-close fallback (issue #293) — same
+                # helper as FlowApiClient's teardown; this standalone path had
+                # the identical unbounded-close-and-swallow gap.
+                await close_context_bounded(self._ctx, owner="ui_automation")
             try:
-                if self._ctx is not None:
-                    await self._ctx.close()
-            except Exception as e:
-                log.warning("ui_automation.context_close_failed", error=str(e))
-            try:
-                await self._pw_cm.__aexit__(None, None, None)
+                await asyncio.wait_for(
+                    self._pw_cm.__aexit__(None, None, None), timeout=DRIVER_STOP_TIMEOUT_S
+                )
             except Exception as e:
                 log.warning("ui_automation.playwright_exit_failed", error=str(e))
         self._pw_cm = None

{gflow_cli-0.32.0 → gflow_cli-0.32.1}/src/gflow_cli/api/transports/ui_automation_video.py

@@ -423,9 +423,16 @@ async def _capture_debug_screenshot(page: Any, out_dir: Path | None, filename: s
         )
     except Exception as e:
         log.debug("ui_automation_video.screenshot_capture_failed", error=str(e))
+        return None  # never report a path that was not written (#283)
     return shot_path
 
 
+def screenshot_clause(shot: Path | None) -> str:
+    """' Screenshot: <path>' when one was captured, else '' — a capture
+    failure must not put a phantom path (or 'None') in the error text."""
+    return f" Screenshot: {shot}" if shot is not None else ""
+
+
 def selector_drift_detail(probe: str, what: str, shot: Path | None) -> str:
     """Build a :class:`UiSelectorDriftError` detail string for a probe miss.
 
@@ -1050,7 +1057,7 @@ class VideoGenerationMixin:
                 msg = (
                     f"model picker trigger not found; cannot select {model.value!r} "
                     f"for i2v. Refusing to proceed (Flow's default would drop the "
-                    f"frames to T2V — issue #125). Screenshot: {shot}"
+                    f"frames to T2V — issue #125).{screenshot_clause(shot)}"
                 )
                 raise VideoModelSelectionError(detail=msg, route="model_picker_trigger")
             return
@@ -1092,7 +1099,7 @@ class VideoGenerationMixin:
                 f"could not select video model {model.value!r} for i2v after 2 "
                 f"attempts. Refusing to proceed — Flow's default model "
                 f"({VideoModel.OMNI_FLASH.value}) silently drops the start/end "
-                f"frames and routes to T2V (issue #125). Screenshot: {shot}"
+                f"frames and routes to T2V (issue #125).{screenshot_clause(shot)}"
             )
             raise VideoModelSelectionError(detail=msg, route="model_option")
 
@@ -1280,7 +1287,7 @@ class VideoGenerationMixin:
             shot = await _capture_debug_screenshot(
                 page, out_dir, f"debug_no_{label.lower()}_slot.png"
             )
-            msg = f"frame slot {label!r} not found on the Flow editor. Screenshot: {shot}"
+            msg = f"frame slot {label!r} not found on the Flow editor.{screenshot_clause(shot)}"
             raise RuntimeError(msg) from e
 
         struct_count = await structs.count()
@@ -1423,12 +1430,13 @@ class VideoGenerationMixin:
                 msg = (
                     f"Neither the icon nor the text 'Upload media' selector opened a file "
                     f"chooser for {log_label!r} — Google likely changed the media dialog "
-                    f"(issue #56). Screenshot: {shot}. Workaround: set the CHROME BROWSER "
+                    f"(issue #56). Workaround: set the CHROME BROWSER "
                     f"PROFILE's language to English (chrome://settings/languages). NOTE: "
                     f"this is the Chrome PROFILE language, NOT the Google ACCOUNT language "
                     f"— changing only the Google account language does NOT work, because "
                     f"Flow follows the Chrome profile locale (and the --lang=en-US launch "
                     f"arg cannot override an already-configured profile)."
+                    f"{screenshot_clause(shot)}"
                 )
                 raise RuntimeError(
                     msg,
@@ -1488,7 +1496,8 @@ class VideoGenerationMixin:
             except Exception as e:
                 if i == 0:
                     shot = await _capture_debug_screenshot(page, out_dir, "debug_no_add_media.png")
-                    msg = f"'Add Media' button not found for first reference. Screenshot: {shot}"
+                    clause = screenshot_clause(shot)
+                    msg = f"'Add Media' button not found for first reference.{clause}"
                     raise RuntimeError(
                         msg,
                     ) from e
@@ -1611,6 +1620,10 @@ class VideoGenerationMixin:
                     visible = True
                     break
                 await VideoGenerationMixin._scroll_picker_grid(page)
+            # Final re-check (#283 off-by-one): the count runs BEFORE each
+            # scroll, so a tile rendered by the LAST scroll was never seen.
+            if not visible and await tile.count():
+                visible = True
             if visible:
                 try:
                     await tile.wait_for(state="visible", timeout=4000)
@@ -1728,7 +1741,9 @@ class VideoGenerationMixin:
         """Locate the Personagens-tab tile for a character entity. Each tile is
         keyed by the entity id as `data-tile-id="fe_id_<entityId>"` (exact — no
         display-name ambiguity). Scroll the grid until it renders, then return
-        the locator (the caller still waits for visibility)."""
+        the locator (the caller still waits for visibility — which also covers
+        a tile rendered by the final scroll, so the #283 off-by-one fixed in
+        `_select_existing_asset` has no effect here)."""
         tile = page.locator(f"[data-tile-id='fe_id_{entity_id}']").first
         for _ in range(PICKER_GRID_SCROLL_ATTEMPTS):
             if await tile.count():
@@ -1781,7 +1796,7 @@ class VideoGenerationMixin:
         await page.keyboard.press("Escape")
         raise TransportTimeoutError(
             f"{detail} include action did not appear (no selector tier "
-            f"matched on surface {surface!r}). Screenshot: {shot}",
+            f"matched on surface {surface!r}).{screenshot_clause(shot)}",
             remediation_hint=(
                 "Flow's resource picker may have changed, or your account's "
                 "UI language is not yet covered by the selector fallbacks. "