gflow-cli 0.17.0__tar.gz → 0.18.0__tar.gz

{gflow_cli-0.17.0 → gflow_cli-0.18.0}/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.18.0] — 2026-06-12
+
+### Added
+
+- `UiSelectorDriftError` (exit code 23): UI-automation selector-probe failures — e.g. the
+  mode-switch `crop_*` trigger missing from the Flow editor (issue #183) — now raise a typed
+  error carrying the probe name, the debug-screenshot path, and a remediation hint, instead
+  of an opaque "Unexpected error" (exit 1) whose message was hashed away in logs. Converted
+  probes: mode-switch trigger, Image/Video mode tabs, and video sub-mode tabs, in both the
+  image and video transports.
+
+### Fixed
+
+- `gflow image` commands (`t2i` / `i2i` / `upscale` / `upload`) now plumb their output
+  directory into the API client, so debug screenshots are actually captured on
+  UI-automation failures. Previously the transport's screenshot directory was never set on
+  the image path and drift errors reported `Screenshot: None` even with `--verbose`.
+
 ## [0.17.0] — 2026-06-12
 
 ### Added
@@ -1509,7 +1527,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.17.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.18.0...HEAD
+[0.18.0]: https://github.com/ffroliva/gflow-cli/compare/v0.17.0...v0.18.0
 [0.17.0]: https://github.com/ffroliva/gflow-cli/compare/v0.16.0...v0.17.0
 [0.16.0]: https://github.com/ffroliva/gflow-cli/compare/v0.15.1...v0.16.0
 [0.15.1]: https://github.com/ffroliva/gflow-cli/compare/v0.15.0...v0.15.1

{gflow_cli-0.17.0 → gflow_cli-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.17.0
+Version: 0.18.0
 Summary: Unofficial CLI for Google Flow — drive Veo image-to-video generations from the terminal.
 Project-URL: Homepage, https://github.com/ffroliva/gflow-cli
 Project-URL: Issues, https://github.com/ffroliva/gflow-cli/issues

{gflow_cli-0.17.0 → gflow_cli-0.18.0}/docs/INDEX.md

@@ -111,7 +111,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.17.0](LIVE_VERIFICATION_v0.17.0.md) (#168 cookie verification live e2e_auth; #177 exit-7 hint recorded not-triggerable, credit-free). v0.14.0 / v0.15.0 / v0.15.1 shipped without a dedicated doc (CI + the v0.13.0 baseline). Prior: [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.18.0](LIVE_VERIFICATION_v0.18.0.md) (#183 exit-23 selector-drift error: live drift simulation + happy path, credit-free). v0.14.0 / v0.15.0 / v0.15.1 shipped without a dedicated doc (CI + the v0.13.0 baseline). Prior: [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.18.0/docs/LIVE_VERIFICATION_v0.18.0.md

@@ -0,0 +1,72 @@
+# Live verification — v0.18.0
+
+> Evidence record for the v0.18.0 release. v0.18.0 ships one feature — typed
+> `UiSelectorDriftError` (exit code 23) for UI-automation selector-probe failures
+> (issue #183, PR #184) — and one fix: the `gflow image` command family now wires
+> its output directory into the API client so debug screenshots are actually
+> captured on UI-automation failures.
+
+## Summary
+
+- **Verified by:** ffroliva (Claude Code)
+- **Date:** 2026-06-12 (live runs on the PR #184 head `45ae442`, merged unchanged
+  into `develop @ 9f1d80b`)
+- **gflow-cli version:** 0.18.0 (pre-tag verification)
+- **Status:** 🟢 Green — both the failure path (drift simulation) and the happy
+  path live-verified, **credit-free** (image generation spends no Veo credits)
+
+## 1. Pre-tag gates
+
+- `ruff check src tests` — clean; `ruff format --check` — 220 files formatted
+- `pyright src` — 0 errors (7 pre-existing `browser_cookie3` resolution errors in
+  the local env only, untouched `auth/cookies.py`; CI green)
+- Scoped pytest (errors + transports + cli surfaces) — 475 passed, 1 skipped
+- PR #184 CI — 7/7 checks green on `45ae442` (test matrix 3.11/3.12/3.13,
+  gitleaks, SonarCloud)
+
+## 2. Failure path — live drift simulation (the issue-#183 condition)
+
+`MODE_SWITCH_TRIGGER_SELECTORS` was patched (in both transport module namespaces)
+to a guaranteed-miss selector, reproducing exactly the reporter's DOM condition —
+the crop_* mode-switch trigger absent from the Flow editor. The real CLI t2i path
+was then run against live Flow (profile `denon82`, project created, $0 credits —
+the failure fires before any generation).
+
+| Ledger layer | Evidence |
+|---|---|
+| Exit code | **23** (`UiSelectorDriftError` via `EXIT_CODE_MAP`) |
+| File count | 1 — `debug_no_mode_trigger.png` written to the `--out` dir |
+| Magic bytes | `\x89PNG\r\n\x1a\n` ✅ (valid PNG) |
+| Dimensions | 1280×720 (Pillow) |
+| structlog invariants | `selector_miss` ×1 (bogus selector) → `selector_probe_failed` → `error_raised` with full RFC 9457 problem payload; **zero** `error_unhandled` / `message_hash` events |
+| User-visible artifact | `Flow UI selector drift: probe=mode_switch_trigger: no matching element found on the Flow editor. Screenshot: <out-dir>/debug_no_mode_trigger.png` + remediation hint (no `--verbose` claim, PII warning present) |
+
+This is the user-facing contract the release exists for: the issue-#183 reporter
+saw `Unexpected error` (exit 1) with the real message hashed away; on v0.18.0 the
+same condition produces an actionable, screenshot-carrying exit-23 error.
+
+## 3. Happy path — mode-switch unregressed
+
+`gflow --verbose image t2i "<prompt>" --profile denon82 --aspect 9:16 --out <dir>`
+against live Flow:
+
+| Ledger layer | Evidence |
+|---|---|
+| Exit code | 0 |
+| File count | 1 (`ec262f4c-….jpg`) |
+| Magic bytes | `\xff\xd8\xff` ✅ (valid JPEG) |
+| Dimensions | 768×1376 (portrait — matches `--aspect 9:16`) |
+| structlog invariants | `image_mode_entered` fired (mode-switch dropdown found and used); no `UiSelectorDriftError` in the run |
+| User gallery | image present in the Flow project gallery (denon82) |
+
+## 4. Not verified this cycle (recorded, not omitted)
+
+- **The drift error on a genuinely affected account:** the issue-#183 reporter's
+  account is in the (suspected) issue-#174 new-UI A/B cohort; both maintainer
+  accounts probed as the old dialog UI on 2026-06-12, so the organic condition is
+  not reproducible on our side. The simulation in § 2 exercises the identical
+  code path (selector cascade miss → typed raise → CLI boundary → exit 23).
+  Reporter confirmation is requested on #183.
+- **`cli_character.py` screenshot wiring:** intentionally out of scope for this
+  release (tracked as a follow-up); its drift errors correctly omit the
+  `Screenshot:` clause.

{gflow_cli-0.17.0 → gflow_cli-0.18.0}/docs/USAGE.md

@@ -1022,9 +1022,15 @@ shell scripts can branch on the failure mode without parsing stderr.
 | `12` | `AuthLoginTimeoutError` | Browser sign-in was not completed in time       | Re-run login or raise `GFLOW_CLI_AUTH_LOGIN_TIMEOUT`       |
 | `13` | `SecurityError`       | Unsafe local profile or secret handling blocked   | Follow the error's safety guidance                         |
 | `14` | `AuthBrowserRejectedError` | Google rejected the login browser             | `gflow auth login --browser chrome`                        |
+| `15` | `BrowserSessionClosedError` | The automation browser window was closed mid-operation | Re-run; keep the browser window open until the command finishes |
 | `16` | `DataStoreError`      | Local database cannot be opened, a migration failed, or the DB schema is newer than the installed gflow-cli | See below                                  |
 | `17` | `ModelModeIncompatibilityError` | The chosen video model can't do the requested mode (e.g. `--model omni-flash` with an `i2v` start/end frame — issue #125) | Use `--model veo-lite` (or veo-fast / veo-quality / veo-lite-lp) for `i2v` |
 | `18` | `VideoModelSelectionError` | gflow could not select the requested video model in Flow's editor for an `i2v` run (model-picker option not found) | Usually transient — retry; if it persists, Flow's model-picker UI changed (report referencing #125) |
+| `19` | `SceneConcatError`    | Server-side scene render/concat failed (`gflow scene --output`) | Retry; the recorded compose survives, so re-render is safe |
+| `20` | `FrameExtractionError` | Could not extract the last frame for a video chain link | Check the source video downloaded intact; retry the link  |
+| `21` | `ChainPartialError`   | A video chain stopped mid-way; earlier links completed | Resume from the last completed link shown in the error     |
+| `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 |
 | `130`| SIGINT                | User-interrupted (Ctrl-C)                        | —                                                          |
 
 **Exit code 16 — data store / migration error.** Fires when:

{gflow_cli-0.17.0 → gflow_cli-0.18.0}/pyproject.toml

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

{gflow_cli-0.17.0 → gflow_cli-0.18.0}/src/gflow_cli/__init__.py

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

{gflow_cli-0.17.0 → gflow_cli-0.18.0}/src/gflow_cli/api/transports/ui_automation.py

@@ -32,6 +32,7 @@ from gflow_cli.api.transports.ui_automation_video import (
     ENTITY_ATTACH_DRIFT_HINT,
     MODE_SWITCH_TRIGGER_SELECTORS,
     VideoGenerationMixin,
+    selector_drift_detail,
     zip_entity_refs,
 )
 from gflow_cli.errors import (
@@ -39,6 +40,7 @@ from gflow_cli.errors import (
     BatchPartialError,
     ContentPolicyError,
     GFlowError,
+    UiSelectorDriftError,
     WafRejectionError,
     WireFormatError,
 )
@@ -989,9 +991,12 @@ class UiAutomationTransport(VideoGenerationMixin):
         )
         if trigger is None:
             shot = await _capture_debug_screenshot(page, out_dir, "debug_no_mode_trigger.png")
-            msg = f"mode-switch dropdown trigger not found on the Flow editor. Screenshot: {shot}"
-            raise RuntimeError(
-                msg,
+            raise UiSelectorDriftError(
+                selector_drift_detail(
+                    "mode_switch_trigger",
+                    "no matching element found on the Flow editor.",
+                    shot,
+                )
             )
         await trigger.click()
         await page.wait_for_timeout(800)
@@ -1002,8 +1007,13 @@ class UiAutomationTransport(VideoGenerationMixin):
         )
         if image_tab is None:
             shot = await _capture_debug_screenshot(page, out_dir, "debug_no_image_tab.png")
-            msg = f"Image tab not found in the mode dropdown. Screenshot: {shot}"
-            raise RuntimeError(msg)
+            raise UiSelectorDriftError(
+                selector_drift_detail(
+                    "image_mode_tab",
+                    "Image tab not found in the mode dropdown.",
+                    shot,
+                )
+            )
         await image_tab.click()
         await page.wait_for_timeout(1200)
         await page.keyboard.press("Escape")

{gflow_cli-0.17.0 → gflow_cli-0.18.0}/src/gflow_cli/api/transports/ui_automation_video.py

@@ -41,6 +41,7 @@ from gflow_cli.errors import (
     AuthExpiredError,
     ModelModeIncompatibilityError,
     TransportTimeoutError,
+    UiSelectorDriftError,
     VideoModelSelectionError,
     WafRejectionError,
     WireFormatError,
@@ -396,6 +397,20 @@ async def _capture_debug_screenshot(page: Any, out_dir: Path | None, filename: s
     return shot_path
 
 
+def selector_drift_detail(probe: str, what: str, shot: Path | None) -> str:
+    """Build a :class:`UiSelectorDriftError` detail string for a probe miss.
+
+    Shared by the image and video transports so the message shape stays
+    symmetric, and so the ``Screenshot:`` clause is omitted (rather than
+    rendering a literal ``None``) when no debug screenshot was captured —
+    the caller had no ``out_dir`` to write into.
+    """
+    detail = f"probe={probe}: {what}"
+    if shot is not None:
+        detail = f"{detail} Screenshot: {shot}"
+    return detail
+
+
 def _summarize_request_image_inputs(request: Any) -> dict[str, Any]:
     """Privacy-safe summary of the image inputs in a generate request body:
     presence of startImage/endImage + referenceImages count, each as an 8-char
@@ -811,9 +826,12 @@ class VideoGenerationMixin:
         )
         if trigger is None:
             shot = await _capture_debug_screenshot(page, out_dir, "debug_no_mode_trigger.png")
-            msg = f"mode-switch dropdown trigger not found on the Flow editor. Screenshot: {shot}"
-            raise RuntimeError(
-                msg,
+            raise UiSelectorDriftError(
+                selector_drift_detail(
+                    "mode_switch_trigger",
+                    "no matching element found on the Flow editor.",
+                    shot,
+                )
             )
         await trigger.click()
         await page.wait_for_timeout(800)
@@ -824,8 +842,13 @@ class VideoGenerationMixin:
         )
         if video_tab is None:
             shot = await _capture_debug_screenshot(page, out_dir, "debug_no_video_tab.png")
-            msg = f"Video tab not found in the mode dropdown. Screenshot: {shot}"
-            raise RuntimeError(msg)
+            raise UiSelectorDriftError(
+                selector_drift_detail(
+                    "video_mode_tab",
+                    "Video tab not found in the mode dropdown.",
+                    shot,
+                )
+            )
         await video_tab.click()
         await page.wait_for_timeout(1200)
         log.info("ui_automation_video.video_mode_entered")
@@ -996,9 +1019,12 @@ class VideoGenerationMixin:
         )
         if tab is None:
             shot = await _capture_debug_screenshot(page, out_dir, f"debug_no_submode_{sub}.png")
-            msg = f"video sub-mode tab {sub!r} not found on the Flow editor. Screenshot: {shot}"
-            raise RuntimeError(
-                msg,
+            raise UiSelectorDriftError(
+                selector_drift_detail(
+                    f"video_submode_{sub}",
+                    f"video sub-mode tab {sub!r} not found on the Flow editor.",
+                    shot,
+                )
             )
         await tab.click()
         await page.wait_for_timeout(900)

{gflow_cli-0.17.0 → gflow_cli-0.18.0}/src/gflow_cli/cli_image.py

@@ -353,6 +353,7 @@ async def _run_upload(
             profile_dir=profile_dir,
             headless=headless,
             transport=transport,
+            out_dir=settings.output_dir,
         ) as client:
             console.print(_CREATING_PROJECT_MSG)
             project = await client.create_project(title="gflow-cli upload")
@@ -544,6 +545,7 @@ async def _run_upscale(
         profile_dir=profile_dir,
         headless=headless,
         transport=transport,
+        out_dir=output_root,
     ) as client:
         console.print(f"Upscaling [bold]{media_id}[/bold] to {scale_label.upper()}...")
         target = await client.upsample_image(
@@ -871,6 +873,7 @@ async def _run_t2i(
             profile_dir=profile_dir,
             headless=headless,
             transport=transport,
+            out_dir=out if out is not None else output_root,
         ) as client:
             # Title is a `gflow-cli ...` prefix per project convention (post-rename a02684f).
             # cli_video.py's _run_t2v / _run_i2v don't currently set a title — tracked separately.
@@ -1264,6 +1267,7 @@ async def _run_i2i(
             profile_dir=profile_dir,
             headless=headless,
             transport=transport,
+            out_dir=out if out is not None else output_root,
         ) as client:
             # Title is a `gflow-cli ...` prefix per project convention (post-rename a02684f).
             # cli_video.py's _run_t2v / _run_i2v don't currently set a title — tracked separately.

{gflow_cli-0.17.0 → gflow_cli-0.18.0}/src/gflow_cli/errors.py

@@ -28,6 +28,7 @@ __all__ = [
     "SceneConcatError",
     "SecurityError",
     "TransportTimeoutError",
+    "UiSelectorDriftError",
     "UpscaleUnavailableError",
     "VideoModelSelectionError",
     "WafRejectionError",
@@ -381,6 +382,32 @@ class UpscaleUnavailableError(GFlowError):
     )
 
 
+class UiSelectorDriftError(GFlowError):
+    """Raised when a UI-automation selector cascade finds no matching element.
+
+    Indicates that Flow's frontend has changed in a way that invalidates one
+    of the selector probes (mode-switch trigger, mode tab, sub-mode tab, etc.).
+    The ``detail`` names the probe label and includes the debug screenshot path
+    when one was captured.
+
+    This is a hard failure — gflow cannot safely proceed without the control —
+    but it is *diagnosed*, not opaque: the user gets the probe name and the
+    screenshot for inspection.  Exit code 23 lets scripted callers branch on
+    "the UI changed and needs a selector update" versus generic error (1).
+    """
+
+    problem_type = "https://gflow-cli.dev/errors/ui-selector-drift"
+    title = "Flow UI selector drift"
+    _default_remediation = (
+        "A Flow editor UI element could not be located — Google may have updated "
+        "their frontend. Check for a newer gflow-cli release, then file a bug at "
+        "https://github.com/ffroliva/gflow-cli/issues referencing the probe name "
+        "and attaching the debug screenshot from this message, if one was captured "
+        "(review it first — the viewport may show your account name/avatar; do NOT "
+        "include tokens or signed URLs)."
+    )
+
+
 class SecurityError(GFlowError):
     """Raised when a security boundary is violated (e.g. profile_dir outside HOME)."""
 
@@ -643,6 +670,10 @@ EXIT_CODE_MAP: dict[type[GFlowError], int] = {
     # from WafRejectionError's 10 even though both are HTTP 403. Direct GFlowError
     # subclass, so unconstrained by the ordering invariant.
     UpscaleUnavailableError: 22,
+    # UiSelectorDriftError (issue #183): Flow UI changed, selector probe failed.
+    # Direct GFlowError subclass; exit 23 lets scripts distinguish "UI drifted"
+    # from generic error (1) without parsing stderr.
+    UiSelectorDriftError: 23,
     # ModelModeIncompatibilityError + VideoModelSelectionError BEFORE
     # ConfigurationError (their parent) so the isinstance walk lands on 17/18,
     # not 11. Per [[exit-code-map-ordering-invariant-test-pitfall]].

{gflow_cli-0.17.0 → gflow_cli-0.18.0}/src/gflow_cli/exceptions.py

@@ -24,6 +24,7 @@ from gflow_cli.errors import ProblemDetails as ProblemDetails
 from gflow_cli.errors import RateLimitError as RateLimitError
 from gflow_cli.errors import SecurityError as SecurityError
 from gflow_cli.errors import TransportTimeoutError as TransportTimeoutError
+from gflow_cli.errors import UiSelectorDriftError as UiSelectorDriftError
 from gflow_cli.errors import UpscaleUnavailableError as UpscaleUnavailableError
 from gflow_cli.errors import WafRejectionError as WafRejectionError
 from gflow_cli.errors import WireFormatError as WireFormatError

{gflow_cli-0.17.0 → gflow_cli-0.18.0}/tests/api/transports/test_ui_automation_image_mode.py

@@ -9,6 +9,7 @@ otherwise an account whose last-used mode was Video silently routes
 
 from __future__ import annotations
 
+from pathlib import Path
 from unittest.mock import AsyncMock, MagicMock
 
 import pytest
@@ -18,6 +19,7 @@ from gflow_cli.api.transports.ui_automation import UiAutomationTransport
 from gflow_cli.api.transports.ui_automation_video import (
     MODE_SWITCH_TRIGGER_SELECTORS,
 )
+from gflow_cli.errors import UiSelectorDriftError
 
 
 def _cascade_page(visible: set[str]) -> MagicMock:
@@ -53,15 +55,35 @@ class TestSwitchToImageMode:
     @pytest.mark.asyncio
     async def test_raises_when_trigger_missing(self) -> None:
         page = _cascade_page(set())
-        with pytest.raises(RuntimeError, match="mode-switch"):
+        with pytest.raises(UiSelectorDriftError, match="mode_switch_trigger"):
             await UiAutomationTransport._switch_to_image_mode(page, out_dir=None)
 
     @pytest.mark.asyncio
     async def test_raises_when_image_tab_missing(self) -> None:
         page = _cascade_page({MODE_SWITCH_TRIGGER_SELECTORS[0]})
-        with pytest.raises(RuntimeError, match="Image tab"):
+        with pytest.raises(UiSelectorDriftError, match="Image tab"):
             await UiAutomationTransport._switch_to_image_mode(page, out_dir=None)
 
+    @pytest.mark.asyncio
+    async def test_trigger_miss_detail_carries_screenshot_path(self, tmp_path: Path) -> None:
+        # The screenshot path is the diagnostic payload issue-#183 reporters
+        # need — assert it survives into the user-visible detail.
+        page = _cascade_page(set())
+        page.screenshot = AsyncMock()
+        with pytest.raises(UiSelectorDriftError, match="debug_no_mode_trigger.png"):
+            await UiAutomationTransport._switch_to_image_mode(page, out_dir=tmp_path)
+        page.screenshot.assert_awaited()
+
+    @pytest.mark.asyncio
+    async def test_trigger_miss_detail_omits_screenshot_clause_without_out_dir(self) -> None:
+        # No out_dir → no capture; the detail must drop the clause entirely
+        # rather than render a literal "Screenshot: None".
+        page = _cascade_page(set())
+        with pytest.raises(UiSelectorDriftError) as excinfo:
+            await UiAutomationTransport._switch_to_image_mode(page, out_dir=None)
+        assert "Screenshot" not in str(excinfo.value)
+        assert "None" not in str(excinfo.value)
+
 
 class TestModeSwitchCallSite:
     """Regression guard: assert ``_switch_to_image_mode`` is actually

{gflow_cli-0.17.0 → gflow_cli-0.18.0}/tests/api/transports/test_ui_automation_video.py

@@ -19,7 +19,12 @@ from gflow_cli.api.transports.ui_automation_video import (
     VideoGenerationMixin,
 )
 from gflow_cli.api.video import Aspect, GenerateVideoRequest, Mode, VideoModel, VideoStatus
-from gflow_cli.errors import AuthExpiredError, TransportTimeoutError, WireFormatError
+from gflow_cli.errors import (
+    AuthExpiredError,
+    TransportTimeoutError,
+    UiSelectorDriftError,
+    WireFormatError,
+)
 
 
 def _make_listener_page() -> tuple[MagicMock, list]:
@@ -227,7 +232,7 @@ class TestSwitchToVideoMode:
     @pytest.mark.asyncio
     async def test_raises_when_trigger_missing(self) -> None:
         page = _cascade_page(set())
-        with pytest.raises(RuntimeError, match="mode-switch"):
+        with pytest.raises(UiSelectorDriftError, match="mode_switch_trigger"):
             await VideoGenerationMixin._switch_to_video_mode(page, out_dir=None)
 
     @pytest.mark.asyncio
@@ -235,9 +240,17 @@ class TestSwitchToVideoMode:
         from gflow_cli.api.transports import ui_automation_video as mod
 
         page = _cascade_page({mod.MODE_SWITCH_TRIGGER_SELECTORS[0]})
-        with pytest.raises(RuntimeError, match="Video tab"):
+        with pytest.raises(UiSelectorDriftError, match="Video tab"):
             await VideoGenerationMixin._switch_to_video_mode(page, out_dir=None)
 
+    @pytest.mark.asyncio
+    async def test_submode_miss_raises_drift_error(self) -> None:
+        # The sub-mode probe is the same selector-cascade pattern as the
+        # mode-switch trigger and must carry the same typed-error contract.
+        page = _cascade_page(set())
+        with pytest.raises(UiSelectorDriftError, match="video_submode_references"):
+            await VideoGenerationMixin._switch_video_sub_mode(page, "references", out_dir=None)
+
 
 class TestWaitVideoEditorReady:
     @pytest.mark.asyncio

gflow_cli-0.18.0/tests/cli/test_cli_image_selector_drift.py

@@ -0,0 +1,74 @@
+"""CLI tests for the ``UiSelectorDriftError`` surface (issue #183).
+
+Proves the two user-visible guarantees the typed error exists for:
+
+1. exit code 23 with the probe name in the output — instead of the old bare
+   ``RuntimeError`` whose message was hashed by the unhandled-error handler,
+   leaving the user with an opaque "Unexpected error" (exit 1);
+2. the ``out_dir`` wiring on the image surface — the transport can only
+   capture debug screenshots when ``FlowApiClient`` receives ``out_dir``,
+   and it was silently ``None`` for every ``gflow image`` command.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from click.testing import CliRunner, Result
+
+from gflow_cli.errors import UiSelectorDriftError
+
+
+@pytest.fixture
+def runner() -> CliRunner:
+    return CliRunner()
+
+
+def _drifting_client() -> MagicMock:
+    """Stub FlowApiClient whose generate_image hits selector drift."""
+    client = MagicMock()
+    client.__aenter__ = AsyncMock(return_value=client)
+    client.__aexit__ = AsyncMock(return_value=None)
+    client.create_project = AsyncMock(
+        return_value=MagicMock(project_id="proj-1", title="gflow-cli t2i")
+    )
+    client.generate_image = AsyncMock(
+        side_effect=UiSelectorDriftError(
+            "probe=mode_switch_trigger: no matching element found on the Flow editor."
+        )
+    )
+    return client
+
+
+def _invoke_t2i(runner: CliRunner, tmp_path: Path, out_dir: Path) -> tuple[Result, MagicMock]:
+    client = _drifting_client()
+    with (
+        patch("gflow_cli.cli_image.FlowApiClient", return_value=client) as client_cls,
+        patch("gflow_cli.cli_image._make_provider_dir", return_value=tmp_path / "prof"),
+        patch("gflow_cli.cli_image._resolve_profile", return_value="default"),
+    ):
+        from gflow_cli.cli import main
+
+        result = runner.invoke(
+            main,
+            ["image", "t2i", "a cat", "--out", str(out_dir)],
+            catch_exceptions=False,
+        )
+    return result, client_cls
+
+
+def test_t2i_selector_drift_maps_exit_23_with_probe_name(runner: CliRunner, tmp_path: Path) -> None:
+    result, _ = _invoke_t2i(runner, tmp_path, tmp_path / "out")
+    assert result.exit_code == 23, result.output
+    assert "mode_switch_trigger" in result.output
+    # Regression guard for the issue-#183 root cause: the typed error's real
+    # message must reach the user, not the hashed "Unexpected error" fallback.
+    assert "Unexpected error" not in result.output
+
+
+def test_t2i_wires_out_dir_into_client(runner: CliRunner, tmp_path: Path) -> None:
+    out_dir = tmp_path / "out"
+    _, client_cls = _invoke_t2i(runner, tmp_path, out_dir)
+    assert client_cls.call_args.kwargs["out_dir"] == out_dir

{gflow_cli-0.17.0 → gflow_cli-0.18.0}/tests/test_errors.py

@@ -22,6 +22,7 @@ from gflow_cli.errors import (
     ProblemDetails,
     RateLimitError,
     TransportTimeoutError,
+    UiSelectorDriftError,
     UpscaleUnavailableError,
     VideoModelSelectionError,
     WafRejectionError,
@@ -452,3 +453,39 @@ def test_chain_partial_error_partial_results_defaults_empty() -> None:
     (but present) ``partial_results`` list — never None."""
     err = ChainPartialError(detail="first link failed")
     assert err.partial_results == []
+
+
+# ---------- UiSelectorDriftError (issue #183) ----------
+
+
+def test_ui_selector_drift_error_exit_code_23() -> None:
+    """UiSelectorDriftError -> exit code 23 (issue #183).
+
+    Raised when a UI-automation selector cascade finds no matching element,
+    indicating that Flow's frontend has changed.  Exit 23 lets scripted
+    callers distinguish "UI drifted" from generic error (1)."""
+    err = UiSelectorDriftError(
+        detail="probe=mode_switch_trigger: no matching element found on the Flow editor."
+    )
+    assert _exit_code_for(err) == 23
+    assert EXIT_CODE_MAP[UiSelectorDriftError] == 23
+    assert isinstance(err, GFlowError)
+    assert err.remediation_hint != ""
+
+
+def test_ui_selector_drift_error_problem_details() -> None:
+    """UiSelectorDriftError carries RFC 9457 Problem Details with a stable type URI."""
+    err = UiSelectorDriftError(detail="probe=image_mode_tab: Image tab not found.")
+    pd = err.to_problem_details()
+    assert pd["type"] == "https://gflow-cli.dev/errors/ui-selector-drift"
+    assert pd["title"] == "Flow UI selector drift"
+    assert "image_mode_tab" in pd.get("detail", "")
+    assert "remediation_hint" in pd
+
+
+def test_ui_selector_drift_error_not_a_subclass_of_flow_api_error() -> None:
+    """UiSelectorDriftError is a direct GFlowError subclass — it is NOT a
+    FlowApiError (it is a UI-automation concern, not a wire-protocol error)."""
+    err = UiSelectorDriftError(detail="probe=mode_switch_trigger: selector cascade failed.")
+    assert isinstance(err, GFlowError)
+    assert not isinstance(err, FlowApiError)

{gflow_cli-0.17.0 → gflow_cli-0.18.0}/uv.lock

@@ -765,7 +765,7 @@ wheels = [
 
 [[package]]
 name = "gflow-cli"
-version = "0.17.0"
+version = "0.18.0"
 source = { editable = "." }
 dependencies = [
     { name = "browser-cookie3" },