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

{gflow_cli-0.16.0 → gflow_cli-0.18.0}/.claude/commands/gflow/check.md

@@ -50,3 +50,10 @@ If the coverage run crashes the current MCP/sandbox session with `Connection clo
 same marker-filtered suite in smaller chunks without coverage and rely on CI for the coverage XML.
 Project pytest defaults already exclude `e2e` and `live`; those markers are explicit,
 credit-spending gates and must be requested with a separate `-m e2e` / `-m live` command.
+
+**Windows agent sessions:** `uv run pytest` is unreliable — invoke
+`.venv/Scripts/python.exe -m pytest` directly, and prefix Python invocations with
+`PYTHONUTF8=1` when output contains non-ASCII. The unscoped full-coverage sweep
+(step 4) can OOM locally (exit 137 / SIGKILL): run the suites scoped to the dirs you
+touched and trust CI for the full coverage gate — **a green full-suite CI run on the
+same tree (e.g. the just-merged PR) satisfies step 4 for release purposes.**

{gflow_cli-0.16.0 → gflow_cli-0.18.0}/.claude/commands/gflow/release.md

@@ -70,6 +70,19 @@ memory) or the release branch will hit conflicts on `pyproject.toml` / `__init__
 
 Run `/gflow:check` — all gates must pass. Abort if any fail.
 
+**4b. Live-verify the release's user-facing features (REQUIRED gate).**
+
+For every new/changed user-facing feature in this release, exercise it against
+live Flow (credit-free wherever possible — image gen, entity attach, upscale, and
+scene/timeline ops cost no Veo credits) and write the evidence to
+`docs/LIVE_VERIFICATION_v<NEW_VERSION>.md` using the 5-layer ledger (file count +
+magic bytes + dimensions/shape + structlog invariants + a user-confirmable
+artifact). Add it to the "what was live-verified" entry in `docs/INDEX.md`. This
+doc shipped for every release v0.7.0→v0.13.0, then lapsed for v0.14.0–v0.15.1 —
+which is why it is now an explicit gate. If a feature genuinely cannot be verified
+this cycle, record that and the reason in the doc; never silently omit it. Stage
+the doc into the release-prep commit (step 11).
+
 **5. Create a release branch off `develop`.**
 
 ```bash
@@ -116,6 +129,12 @@ rg -n "__version__|<OLD_VERSION>|version assertion" tests src pyproject.toml
 
 Run `/gflow:doc-review` — audit all version refs, INDEX completeness, evidence files, skill files, CHANGELOG footer, and memory files. Fix every **FAIL** before continuing. Fold all discovered fixes into the release prep commit.
 
+Also **consolidate shipped planning artifacts** here: extract any durable patterns
+into auto-memory, then remove the now-shipped `docs/superpowers/` plan / spec /
+verification files (keep only in-flight work). `check_repo_hygiene.py` enforces the
+root-doc allowlist, so a stray review doc or session marker left at the repo root
+will fail the gate.
+
 **11. Commit the release prep.**
 
 ```bash

{gflow_cli-0.16.0 → gflow_cli-0.18.0}/.gitignore

@@ -66,6 +66,9 @@ test_assets/debug_*/
 # Phase-2 live-spike capture outputs — NEVER commit (may contain real API payloads)
 scripts/dev/_spike_out/
 
+# Agent session marker — machine/session-local handoff state, regenerated per run
+.continue-here.md
+
 # Live Flow traffic captures — NEVER commit (contain real Bearer tokens / API keys).
 # Diagnostic scripts MUST default-write here, NOT to samples/captured/.
 # Sanitised reference samples (no secrets) can still live under samples/captured/.

{gflow_cli-0.16.0 → gflow_cli-0.18.0}/AGENTS.md

@@ -56,7 +56,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–21, e.g. 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`). 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–22, e.g. 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`, 22 `UpscaleUnavailableError`). 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).
 
 ## PR instructions

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

@@ -7,6 +7,39 @@ 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
+
+- Added `verify_flow_profile` in `gflow_cli.auth.verification` using `browser_cookie3` and `httpx` to verify sessions directly from the Chrome cookie store (fast path), with a marker-gated Playwright fallback for encrypted/locked stores. `RealChromeStrategy` now writes the Chrome marker before verification (the fallback reads it) and, on failure, rolls back only a speculative write — a marker that legitimately pre-existed (a previously-verified chrome profile) survives a transient probe failure, and an interrupted verification never leaves an unverified profile claiming the chrome strategy. Cookie extraction is centralised in the new `gflow_cli.auth.cookies` module.
+
+### Fixed
+
+- `gflow_cli.auth.cookies._get_chrome_cookies3` now catches `RuntimeError` (Windows DPAPI failure — `RuntimeError('Failed to decrypt the cipher text with DPAPI')`) in addition to `browser_cookie3.BrowserCookieError`, and re-raises both as `PermissionError` so the Playwright fallback is triggered instead of propagating an unhandled exception.
+- `verify_flow_profile` now retries transient HTTP failures (429/503/504) and network errors up to `_MAX_ATTEMPTS` times with exponential backoff, matching the retry behaviour of the existing Playwright-based `verify_flow_session`.
+
+### Changed
+
+- Entity-attach `WireFormatError` failures (exit 7) now carry a remediation hint pointing at Flow's new full-page media-library UI rollout ([#174](https://github.com/ffroliva/gflow-cli/issues/174)) — affected accounts can stage entities via the include action but the submit never carries `referenceEntities`; the error now explains how to tell which UI an account has and where to follow the fix, instead of the generic file-a-bug hint. Both backstops also emit an `entity_attach_context` discovery field (`video`/`image`) for drift telemetry. New KNOWN_ISSUES entry documents the rollout
+
 ## [0.16.0] — 2026-06-12
 
 ### Fixed
@@ -1494,7 +1527,9 @@ shell-script template that branches on these codes.
 
 First skeleton. Not functional end-to-end yet.
 
-[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.16.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
 [0.15.0]: https://github.com/ffroliva/gflow-cli/compare/v0.14.0...v0.15.0

{gflow_cli-0.16.0 → gflow_cli-0.18.0}/CLAUDE.md

@@ -22,6 +22,7 @@
 - Slash commands live under `.claude/commands/gflow/` (all prefixed `/gflow:`).
 - Skills under `skills/` are auto-discoverable; `gflow-cli` ships its own at [`skills/gflow-cli/SKILL.md`](skills/gflow-cli/SKILL.md).
 - Auto-memory at `~/.claude/projects/C--development-github-gflow-cli/memory/MEMORY.md` carries cross-session feedback and project state.
+- **Worktrees:** the native `EnterWorktree` tool branches from `origin/main` (the default branch). Feature work integrates via `develop` — after entering a fresh worktree, immediately `git switch -c <type>/<name> origin/develop` and delete the auto-created `worktree-*` branch. On Windows, worktree removal can fail on a file lock (the worktree's `.venv`); `git worktree prune` + manual delete later is fine.
 
 ## MCP GitHub tool — PR body rule (non-negotiable)
 

{gflow_cli-0.16.0 → gflow_cli-0.18.0}/KNOWN_ISSUES.md

@@ -14,6 +14,39 @@ Living list of behaviour that's broken, surprising, or limited by design — alo
 
 ## Open
 
+### Flow's new full-page media-library UI breaks entity attach (A/B rollout)
+
+- **Status:** **Open** — Flow-side staged rollout; tracked in
+  [#174](https://github.com/ffroliva/gflow-cli/issues/174)
+- **Severity:** High · **Affects:** `gflow image t2i --reference-entity` and
+  movie R2V entity attach on accounts that received the new UI, any locale
+
+Flow is A/B-rolling a new full-page media-library UI: clicking **Add Media**
+in the composer **navigates to a library page** (sidebar: All media /
+Characters / Scenes / Tools, with a floating quick-create composer) instead of
+opening the resource-picker dialog. On affected accounts the right-click
+include action still lands (a chip appears), **but the staged entity never
+reaches the submit** — the request carries no `referenceEntities`, so the
+submit backstops raise `WireFormatError` (**exit 7**) instead of silently
+returning a text-only generation as success.
+
+**How to tell which UI your account has:** in the Flow web editor, click
+**Add Media** — a small dialog means the old (working) UI; a navigation to a
+full-page library means the affected new UI.
+
+**Note:** the experiment appears to flap — the affected account observed on
+2026-06-12 00:13 was back on the old dialog UI by 12:48 the same day (variant
+probe, issue #174). If you hit exit 7 on entity attach, re-running later the
+same day may simply work again.
+
+**Workaround:** none yet on affected accounts — the attach gesture for the new
+UI is being reverse-engineered (recon plan in
+[docs/superpowers/plans/2026-06-12-issue-174-library-ui-attach/PLAN.md](docs/superpowers/plans/2026-06-12-issue-174-library-ui-attach/PLAN.md)).
+If you have a second profile/account still on the old UI, entity attach works
+there. Follow [#174](https://github.com/ffroliva/gflow-cli/issues/174) for
+status; please report whether your account shows the dialog or the full-page
+library (plus your locale) on that issue.
+
 ### 4K image upscale requires a Flow Ultra subscription
 
 - **Status:** **Open** (by design — a Flow platform limit, not a gflow bug)
@@ -595,6 +628,15 @@ success. The expected authenticated response shape is pinned by the
 change surfaces there as a failing test. Start any investigation of a sudden
 `gflow auth login` verification failure at that fixture and `verification.py`.
 
+Since PR #168 the production entry point is `verify_flow_profile`, which reads
+the session cookie **directly from Chrome's SQLite store** via `browser_cookie3`
+(a no-browser fast path) and only falls back to launching Playwright when that
+decryption fails. This adds two more local surfaces to check when verification
+fails unexpectedly: a Windows **DPAPI decrypt failure** (cross-user / cross-machine
+key — surfaces as a `RuntimeError` that `auth/cookies.py` normalizes to
+`PermissionError` to trigger the Playwright fallback) and a **locked cookie DB**
+(Chrome still running holds an exclusive SQLite lock). Both degrade fail-closed.
+
 ---
 
 ## Resolved
@@ -620,8 +662,8 @@ Profiles created before this fix continue to work and display `unknown` in the
 account column. Re-running `gflow auth login` against an existing profile backfills
 the `.gflow_account` file.
 
-See [AUTHENTICATION.md § Profile naming](AUTHENTICATION.md#profile-naming) for the
-new naming convention and [AUTHENTICATION.md § gflow auth list](AUTHENTICATION.md#gflow-auth-list)
+See [AUTHENTICATION.md § Profile naming](docs/AUTHENTICATION.md#profile-naming) for the
+new naming convention and [AUTHENTICATION.md § gflow auth list](docs/AUTHENTICATION.md#gflow-auth-list)
 for the updated `--json` schema.
 
 ---

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.16.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
@@ -37,6 +37,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Multimedia :: Video
 Requires-Python: >=3.11
+Requires-Dist: browser-cookie3>=0.20.1
 Requires-Dist: click>=8.1.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: platformdirs>=4.0.0

{gflow_cli-0.16.0 → gflow_cli-0.18.0}/RELEASE.md

@@ -68,28 +68,43 @@ python -m pip install --pre gflow-cli
    uv run pyright src
    uv run python -m pytest -q --cov=gflow_cli
    ```
-4. Update the version in:
+4. **Live-verify the release's user-facing features and record the evidence.**
+   **Required gate — do not skip.** Exercise each new/changed user-facing feature
+   against live Flow (credit-free wherever possible — image gen, entity attach,
+   upscale, and scene/timeline ops cost no Veo credits) and write the result to
+   `docs/LIVE_VERIFICATION_vX.Y.Z.md` using the 5-layer ledger (file count + magic
+   bytes + dimensions/shape + structlog invariants + user-confirmable artifact).
+   Then add it to the "what was live-verified" entry in `docs/INDEX.md`. Every
+   release v0.7.0→v0.13.0 had this doc; it lapsed for v0.14.0–v0.15.1 — that gap is
+   the reason this is now an explicit step. If a feature genuinely cannot be live-
+   verified this cycle, say so in the doc with the reason; never silently omit it.
+5. **Consolidate shipped planning artifacts.** Extract any durable patterns into
+   auto-memory, then remove the now-shipped `docs/superpowers/` plan / spec /
+   verification files (keep only in-flight work). Stale review docs and session
+   markers do not belong in the repo root. (Enforced by `check_repo_hygiene.py` —
+   see the root-doc allowlist.)
+6. Update the version in:
    - `pyproject.toml`
    - `src/gflow_cli/__init__.py`
    - any tests that assert the package version
-5. Move user-visible changes from `CHANGELOG.md` `[Unreleased]` into a dated
+7. Move user-visible changes from `CHANGELOG.md` `[Unreleased]` into a dated
    release section.
-6. Commit the release prep:
+8. Commit the release prep:
    ```bash
-   git add pyproject.toml src/gflow_cli/__init__.py CHANGELOG.md tests
+   git add pyproject.toml src/gflow_cli/__init__.py CHANGELOG.md tests docs
    git commit -m "chore(release): vX.Y.Z"
    ```
-7. Tag and push. **Must be a signed annotated tag** (`-s`) — `.github/workflows/release.yml` rejects unsigned or lightweight tags. Requires a GPG or SSH signing key registered with your GitHub account.
+9. Tag and push. **Must be a signed annotated tag** (`-s`) — `.github/workflows/release.yml` rejects unsigned or lightweight tags. Requires a GPG or SSH signing key registered with your GitHub account.
    ```bash
    git tag -s vX.Y.Z -m "vX.Y.Z"
    git push origin main
    git push origin vX.Y.Z
    ```
-8. Watch the release workflow:
-   <https://github.com/ffroliva/gflow-cli/actions/workflows/release.yml>
-9. Confirm the new version appears on:
-   - <https://pypi.org/project/gflow-cli/>
-   - <https://github.com/ffroliva/gflow-cli/releases>
+10. Watch the release workflow:
+    <https://github.com/ffroliva/gflow-cli/actions/workflows/release.yml>
+11. Confirm the new version appears on:
+    - <https://pypi.org/project/gflow-cli/>
+    - <https://github.com/ffroliva/gflow-cli/releases>
 
 ## Known Historical Quirk
 

{gflow_cli-0.16.0 → gflow_cli-0.18.0}/docs/AUTHENTICATION.md

@@ -364,6 +364,27 @@ Run: gflow auth login --profile default
 
 Re-running `auth login` refreshes the cookies in place — no other state is lost.
 
+## Session verification (cookie-store fast path)
+
+Since v0.17.0, profile verification (run by `gflow auth login --browser chrome` after
+capture) is handled by `gflow_cli.auth.verification.verify_flow_profile`, which probes
+Flow's `/fx/api/auth/session` endpoint **directly from the Chrome cookie store** via
+`browser_cookie3` + `httpx` — no browser launch needed (contributed in PR #168 by
+@3mora2). Two hardening behaviors:
+
+- **Encrypted/locked store fallback** — if the cookie store can't be read (e.g.
+  Windows DPAPI decryption fails, or the store is locked by a running Chrome), the
+  verifier falls back to a marker-gated Playwright probe. The chrome marker is written
+  before verification so the fallback can find the profile; on failure only a
+  *speculative* marker write is rolled back — a previously-verified profile survives a
+  transient probe failure.
+- **Transient-error retry** — HTTP 429/503/504 and network errors retry with
+  exponential backoff before the verifier gives up.
+
+The outcome is the same `AUTHENTICATED` / no-session decision documented under
+[`gflow auth status`](#gflow-auth-status); only the transport is faster. Cookie
+extraction lives in `gflow_cli.auth.cookies`.
+
 ## Threat model & limits
 
 | Threat | Mitigation |

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

@@ -85,6 +85,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"How do I run with multiple Google accounts?"** → [AUTHENTICATION § Multiple accounts](AUTHENTICATION.md#multiple-accounts)
 **"How do I know which Google account a profile is signed into?"** → [AUTHENTICATION § gflow auth list](AUTHENTICATION.md#gflow-auth-list)
 **"Why is my profile named 'default' and how do I rename it?"** → [AUTHENTICATION § Profile naming](AUTHENTICATION.md#profile-naming)
+**"How does login verification work without launching a browser?"** → [AUTHENTICATION § Session verification](AUTHENTICATION.md#session-verification-cookie-store-fast-path) (cookie-store fast path, v0.17.0)
 **"How does the layered structure work?"** → [ARCHITECTURE § Layers](ARCHITECTURE.md#layers)
 **"What env var should I set for X?"** → [CONFIGURATION § Reference](CONFIGURATION.md#reference)
 **"What does gflow remember after a generation finishes?"** → [DATA_LAYER § What is recorded](DATA_LAYER.md#what-is-recorded)
@@ -110,7 +111,8 @@ 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?"** → v0.15.0 / v0.14.x: no dedicated live-verification doc (CI + the v0.13.0 baseline). Latest doc: [LIVE_VERIFICATION_v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · prior: [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)
+**"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)
 **"What is the jitter matrix evidence for `gflow image batch`?"** → [`LIVE_VERIFICATION_image_batch.md`](LIVE_VERIFICATION_image_batch.md) — jitter matrix evidence for `gflow image batch` (always-same-project mode)

gflow_cli-0.18.0/docs/LIVE_VERIFICATION_v0.16.0.md

@@ -0,0 +1,77 @@
+# Live verification — v0.16.0
+
+> Evidence record for the v0.16.0 release. v0.16.0 ships two features: locale-free
+> resource-picker include selectors (issue #170, PR #173) and `gflow image upscale`
+> (issue #171, PR #172). Backfilled 2026-06-12 to close the live-verification
+> documentation gap that opened after v0.13.0 (see docs/INDEX.md).
+
+## Summary
+
+- **Verified by:** ffroliva (Claude Code)
+- **Dates:** #171 upscale — 2026-06-11 (feature branch); #170 selectors — 2026-06-12 (released PyPI artifact)
+- **gflow-cli version:** 0.16.0
+- **Status:** 🟢 Green — both features live-verified credit-free; no Veo credits spent
+
+All verification below is **credit-free**: image generation, character-entity attach,
+and image upscale are non-Veo operations (see the credits-are-videos-only note in
+`KNOWN_ISSUES.md`). No video generation was exercised for this release.
+
+## 1. Quality gates
+
+- [x] **Lint/format** — `ruff check` + `ruff format --check` clean (`src` + `tests`).
+- [x] **Type check** — `pyright src`: 0 errors.
+- [x] **Unit + BDD tests** — full suite green in CI across Python 3.11 / 3.12 / 3.13 (PR #173, PR #172).
+- [x] **Repo hygiene + doc links** — `check_repo_hygiene.py` + `check_doc_links.py` green.
+
+## 2. Issue #170 — locale-free picker include selectors (PR #173)
+
+The pt-BR-hardcoded resource-picker include selectors broke entity attach on every
+non-Portuguese account. PR #173 replaced them with sequentially-probed tier cascades
+(locale-invariant ligature anchor first, then localized-text fallback) and added an
+image-side submit backstop that fails loudly (`WireFormatError`, exit 7) if a staged
+entity never reaches the wire.
+
+### E2E evidence (live Flow, credit-free)
+
+| Layer | Criterion | Outcome |
+|---|---|---|
+| Selector tier | `include_selector_tier=icon` logged (locale-free anchor matched) | **PASS** |
+| Attach event | `ui_automation.character_entity_attached` fired | **PASS** |
+| Submit backstop | `ui_automation.image_entities_attached` — entity rode the wire | **PASS** |
+| Output artifact | t2i produced a JPEG, **768×1376**, character identity visibly preserved | **PASS** |
+| Version | all events emitted at `cli_version 0.16.0` | **PASS** |
+
+- **Pre-merge:** live credit-free `gflow image t2i --reference-entity` on **promo-denon82**
+  (pt-BR profile). Recon harness: `scripts/dev/spike_issue170_picker_locale_recon.py`.
+- **Released-artifact re-verification (2026-06-12):** installed `gflow-cli==0.16.0` from
+  PyPI (global `uv tool`) and re-ran the same flow on promo-denon82 — all four layers
+  above green at `cli_version 0.16.0`. **5-layer ledger PASS.**
+- The backstop earned its keep immediately: it converted Flow's new full-page library-UI
+  A/B (issue #174) from a silent text-only "success" into a typed exit-7 failure on its
+  first live encounter.
+
+## 3. Issue #171 — `gflow image upscale` (PR #172)
+
+`gflow image upscale <mediaId> --scale 2k|4k` upscales a platform-generated image via
+Flow's `POST /v1/flow/upsampleImage` (reCAPTCHA-gated, inline base64 response). 4K is
+Ultra-gated and fails fast with `UpscaleUnavailableError` (exit 22) on lower tiers.
+
+### E2E evidence (live Flow, credit-free)
+
+| Layer | Criterion | Outcome |
+|---|---|---|
+| Wire | `POST /v1/flow/upsampleImage` accepted (full 5-field `clientContext`, action `IMAGE_GENERATION`) | **PASS** |
+| File written | local JPEG written, **3,799,245 bytes** | **PASS** |
+| Magic bytes | header `FF D8 FF` (valid JPEG) | **PASS** |
+| Byte fidelity | written bytes matched the decoded wire payload | **PASS** |
+| Tier gate | 4K returns exit 22 (`UpscaleUnavailableError`) on non-Ultra, not a generic 403 | **PASS** |
+
+- Verified 2026-06-11 on the `feature/image-upscale` branch (= the code released as
+  v0.16.0): `gflow image upscale <mediaId> --scale 2k --project <pid>` end-to-end.
+- Wire protocol documented in [`docs/IMAGE_UPSCALE_RECON.md`](IMAGE_UPSCALE_RECON.md).
+
+## 4. Documentation
+
+- `CHANGELOG.md` — v0.16.0 entry covers both features.
+- `KNOWN_ISSUES.md` — 4K-Ultra limit documented; library-UI A/B (#174) tracked.
+- `docs/IMAGE_UPSCALE_RECON.md` — reverse-engineered upscale wire.

gflow_cli-0.18.0/docs/LIVE_VERIFICATION_v0.17.0.md

@@ -0,0 +1,94 @@
+# Live verification — v0.17.0
+
+> Evidence record for the v0.17.0 release. v0.17.0 ships one feature — cookie-store
+> Flow-session verification (`verify_flow_profile`, PR #168, contributed by @3mora2)
+> plus two hardening fixes to it — and one behavior change: the issue-#174
+> entity-attach exit-7 remediation hint + `entity_attach_context` telemetry (PR #177).
+
+## Summary
+
+- **Verified by:** ffroliva (Claude Code)
+- **Date:** 2026-06-12 (fresh run on the release tree, `develop @ 5444de8`)
+- **gflow-cli version:** 0.17.0 (pre-tag verification)
+- **Status:** 🟢 Green — cookie verification live-verified credit-free; the #174 hint
+  is intentionally not live-triggerable this cycle (reason recorded below)
+
+All verification below is **credit-free**: session verification probes
+`/fx/api/auth/session` and spends no Veo credits; no generation was exercised.
+
+## 1. Pre-tag gates
+
+- [x] **Repo hygiene + doc links** — `check_repo_hygiene.py` + `check_doc_links.py` green.
+- [x] **Lint/format** — `ruff check --fix` + `ruff format`: 219 files, nothing to fix.
+- [x] **Type check** — `pyright src`: 0 errors.
+- [x] **Unit + BDD tests** — full suite green in CI on the exact release tree
+  (`develop @ 5444de8`, CI run 2026-06-12 13:58 UTC, success).
+- [x] **`/gflow:doc-review`** — mechanical pass + 3-auditor council. *Council verdict:
+  GREEN / YELLOW / GREEN. 5 findings; 0 Tier 1 (release-blocking); 4 fixed in the
+  release-prep commit (KNOWN_ISSUES → AUTHENTICATION link path, AGENTS.md exit-code
+  range 3–22, new AUTHENTICATION § Session verification section, INDEX routing row);
+  1 Tier 3 deferred (dedicated `verify_flow_profile` API reference doc). Council
+  reports at `tmp/council/0{1,2,3}-*.md` (local-only).*
+
+## 2. PR #168 — cookie-store session verification (`verify_flow_profile`)
+
+`gflow_cli.auth.verification.verify_flow_profile` verifies a Flow session directly
+from the Chrome cookie store via `browser_cookie3` + `httpx` (fast path), falling
+back to a marker-gated Playwright probe when the store is encrypted/locked. The two
+Fixed entries harden the same path: Windows DPAPI `RuntimeError` now triggers the
+fallback instead of propagating, and transient HTTP failures (429/503/504) retry
+with backoff.
+
+### E2E evidence (live Google endpoint, credit-free)
+
+Fresh run on the release tree, 2026-06-12 15:5x (UTC+1), profile **denon82**:
+
+```
+$env:GFLOW_CLI_E2E_PROFILE='denon82'
+.venv\Scripts\python.exe -m pytest tests/e2e/test_auth_verification_e2e.py -m e2e_auth -v
+```
+
+| Case | Criterion | Outcome |
+|---|---|---|
+| `test_e2e_verify_flow_profile_authenticated` | Logged-in profile → `AUTHENTICATED` with a non-empty `user_email`, **and** the same profile passes `FlowApiClient.health_check()` | **PASS** |
+| `test_e2e_verify_flow_profile_no_session` | Sessionless store → typed non-authenticated outcome (no false positive, no crash) | **PASS** |
+| `test_e2e_verify_flow_profile_falls_back_to_playwright` | Cookie-store read failure → Playwright fallback engages and verifies | **PASS** |
+
+```
+3 passed in 17.20s
+```
+
+The same three cases were also verified green live on denon82 during the PR #168
+review council (pre-merge, same day) — this run re-confirms on the post-merge
+release tree.
+
+## 3. PR #177 — issue #174 entity-attach exit-7 hint + telemetry
+
+Entity-attach `WireFormatError` failures (exit 7) now carry `ENTITY_ATTACH_DRIFT_HINT`
+(dialog-vs-navigate self-diagnosis + link to #174) and both submit backstops emit an
+`entity_attach_context` discovery field (`video`/`image`).
+
+### Not live-triggerable this cycle — reason
+
+Triggering the hint live requires an account on Flow's new full-page media-library
+UI (the #174 A/B variant where staged entities are dropped from the submit). The
+A/B has **rolled back off both available accounts**: the variant re-probe on
+2026-06-12 15:48 (UTC+1) via `scripts/dev/spike_issue174_library_ui_recon.py`
+returned `variant=dialog` on **denon82** (15 ms) and **promo-denon82** (8 ms) —
+evidence posted on [#174](https://github.com/ffroliva/gflow-cli/issues/174).
+With no affected account, the backstop cannot fire live without a real wire
+regression to provoke it.
+
+Coverage in lieu of a live trigger:
+
+- The hint text, exit code, and `entity_attach_context` field are covered by the
+  PR #177 unit/BDD suites (green in CI on the release tree).
+- The underlying backstops themselves were live-verified for v0.16.0 (the image
+  backstop's first live encounter is what *opened* #174 — see
+  [LIVE_VERIFICATION_v0.16.0](LIVE_VERIFICATION_v0.16.0.md)).
+- The credit-free variant probe above exercised the real composer Add-Media path
+  on both accounts at the release tree without drift.
+
+## Post-tag evidence
+
+*(filled after the tag push and PyPI publish)*

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.16.0 → gflow_cli-0.18.0}/docs/PROJECT_STATUS.md

@@ -4,9 +4,9 @@
 
 ## Current release
 
-**v0.15.0 — alpha.** **Character-consistent images via entity references.** `gflow image t2i/i2i` can now reference locked Flow CHARACTER entities (`--reference-entity <id>`, repeatable) and generate in an existing project (`--project <id>`) where those entities live — entities attach through the editor's Personagens picker and ride the submit as `referenceEntities` (confirmed against the live API; the body builder serializes them for headless transports too). Live-verified 2026-06-08: a 3-frame Dragon-Hook smoke rendered drift-free with all three characters on-model. LLM-council-reviewed (security/correctness/dedup) before merge. Carries forward the v0.14.0 `gflow movie` line (multi-scene, character-consistent video).
+**v0.17.0 — alpha.** **Cookie-store session verification.** `verify_flow_profile` (contributed by @3mora2, PR #168) verifies a Flow session directly from the Chrome cookie store via `browser_cookie3` + `httpx` — a fast path that skips launching a browser — with a marker-gated Playwright fallback for encrypted/locked stores (Windows DPAPI failures included) and retry/backoff on transient HTTP errors. Entity-attach `WireFormatError` failures (exit 7) now carry an issue-#174-aware remediation hint plus `entity_attach_context` drift telemetry. Live-verified 2026-06-12 ([evidence](LIVE_VERIFICATION_v0.17.0.md)). Carries forward v0.16.0 (locale-free picker include selectors #170, `gflow image upscale` #171) and v0.15.1 (Docker `/dev/shm` hardening, mid-workflow 401 detection).
 
-**Develop (unreleased, post-v0.15.0):** *(empty — develop is the staging branch for the next release).*
+**Develop (unreleased, post-v0.17.0):** *(empty — develop is the staging branch for the next release).*
 
 ## Milestone history
 
@@ -58,6 +58,11 @@
 | `gflow scene` — Add Clip / Scenes compose + credit-free server-side extended video (`runVideoFxConcatenation`) | ✅ done (v0.12.0) |
 | `gflow video chain` — last-frame I2V chaining from a JSONL manifest (`--dry-run`/`--max-links`/`--resume-from`) | ✅ done (v0.12.0) |
 | Create-project generation works under Flow's Agent docked chat panel | ✅ done (v0.12.0) |
+| Video status poll raises `AuthExpiredError` (exit 3) on mid-workflow 401 (#156) + Docker `/dev/shm` hardening | ✅ done (v0.15.1) |
+| Locale-free resource-picker include selectors — entity attach works on every account language (#170) | ✅ done (v0.16.0) |
+| `gflow image upscale <mediaId> --scale 2k\|4k` — credit-free download-menu upscale, 4K Ultra-gated (#171) | ✅ done (v0.16.0) |
+| Cookie-store session verification fast path (`verify_flow_profile`, PR #168) + Playwright fallback | ✅ done (v0.17.0) |
+| Entity-attach exit-7 remediation hint + `entity_attach_context` drift telemetry (#174 interim) | ✅ done (v0.17.0) |
 | `gflow video batch` (TSV manifest) on `ui_automation` | ⏳ Phase B |
 | Persistence layer (stay-mounted batch sessions across project boundaries) | ⏳ Phase B |
 | Provider abstraction for official Veo 3.1 API | ⏳ planned |

{gflow_cli-0.16.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: