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

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

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.0] — 2026-06-12
+
+### Fixed
+
+- **`--reference-entity` no longer fails on non-Portuguese Flow accounts** ([#170](https://github.com/ffroliva/gflow-cli/issues/170)) — the resource-picker include selectors hardcoded the pt-BR caption "Incluir no comando"; they are now locale-free tier cascades (context-menu `add`-ligature anchor + pt/ru/en text fallback), fixing `gflow image t2i --reference-entity`, movie R2V entity attach, and Vozes voice attach for every account language. Failures are now typed (`TransportTimeoutError`, exit 9) with a locale-neutral remediation hint, the matched selector tier is logged (`include_selector_tier`) for drift telemetry, and a new image-side submit backstop raises `WireFormatError` (exit 7) if a staged character never reaches the wire instead of silently returning a text-only generation. Thanks @papushin7987 for the live-verified report
+
+### Added
+
+- **`gflow image upscale <mediaId> --scale 2k|4k`** — upscale a platform-generated image to 2K or 4K (Flow's download-menu 1K/2K/4K options) and save it locally; credit-free. The owning project is resolved from the local catalog (or pass `--project` for images gflow didn't record). 4K requires a Flow Ultra subscription — a non-Ultra 4K request fails fast with exit code 22 (`UpscaleUnavailableError`) rather than a generic 403. Reverse-engineered wire documented in [docs/IMAGE_UPSCALE_RECON.md](docs/IMAGE_UPSCALE_RECON.md); live-verified end-to-end (issue #171)
+
 ## [0.15.1] — 2026-06-10
 
 ### Changed
@@ -1484,7 +1494,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.15.1...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.16.0...HEAD
+[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
 [0.14.0]: https://github.com/ffroliva/gflow-cli/compare/v0.13.0...v0.14.0

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

@@ -14,6 +14,22 @@ Living list of behaviour that's broken, surprising, or limited by design — alo
 
 ## Open
 
+### 4K image upscale requires a Flow Ultra subscription
+
+- **Status:** **Open** (by design — a Flow platform limit, not a gflow bug)
+- **Severity:** Low · **Affects:** `gflow image upscale --scale 4k` on non-Ultra accounts
+
+`gflow image upscale <mediaId> --scale 4k` returns **exit code 22**
+(`UpscaleUnavailableError`) on accounts below the Ultra tier — Flow gates 4K
+upscaling behind Ultra (the web UI shows an "Upgrade" button instead of a 4K
+option). The account tier is reported on the wire as `userPaygateTier` but is
+enforced server-side, so gflow cannot grant 4K locally.
+
+**Workaround:** use `--scale 2k` (available on all tiers), or upgrade the Flow
+account to Ultra. If you just upgraded, re-run `gflow auth login --profile <name>`
+to refresh the session before retrying 4K. Wire detail:
+[docs/IMAGE_UPSCALE_RECON.md](docs/IMAGE_UPSCALE_RECON.md) (#171).
+
 ### Image generation returns HTTP 401 — `aisandbox-pa` generation endpoint
 
 - **Status:** **RESOLVED in v0.7.0** — moved to [Resolved](#resolved) section
@@ -332,7 +348,7 @@ issue and not blocked by any code change in this repo.
 
 ### `UiAutomationTransport` selectors locale-agnostic — issue #24 Phase 5 complete
 
-- **Status:** Resolved (pending owner live e2e on non-EN profile) · **Severity:** Low · **Tracking:** [issue #24](https://github.com/ffroliva/gflow-cli/issues/24), [issue #94](https://github.com/ffroliva/gflow-cli/issues/94)
+- **Status:** Resolved (pending owner live e2e on non-EN profile) · **Severity:** Low · **Tracking:** [issue #24](https://github.com/ffroliva/gflow-cli/issues/24), [issue #94](https://github.com/ffroliva/gflow-cli/issues/94), [issue #170](https://github.com/ffroliva/gflow-cli/issues/170)
 
   `--lang=en-US` removed in PR #127 (2026-05-30). All selector groups now use
   locale-stable anchors: `IMAGE_MODEL_OPTION_SELECTORS` and
@@ -343,6 +359,20 @@ issue and not blocked by any code change in this repo.
   Playwright kwarg (persists across all in-session navigations). Full resolution
   gate: live e2e with `gflow image t2i` (each model) on a non-EN Chrome profile.
 
+  **2026-06-12 correction (issue #170):** the "all selector groups" claim above
+  had two stragglers — `PICKER_INCLUDE_BUTTON` and `PICKER_CONTEXT_INCLUDE`
+  hardcoded the pt-BR caption "Incluir no comando", breaking
+  `--reference-entity` (image t2i), movie R2V entity attach, and Vozes voice
+  attach on every non-Portuguese account (Flow renders in the ACCOUNT language;
+  `?hl=en` cannot override it). Fixed by converting both constants to sequential
+  tier cascades — context-menu Tier 1 is the locale-free `add`-ligature menuitem
+  scoped to the open menu; the Vozes button has no ligature, so pt/ru/en text
+  leads with a lone-iconless-dialog-button structural fallback. The matched tier
+  is emitted as `ui_automation_video.include_selector_tier` (drift telemetry),
+  exhaustion raises typed `TransportTimeoutError` (exit 9) with a locale-neutral
+  remediation hint, and an image-side submit backstop now raises
+  `WireFormatError` when a requested entity never rode the wire.
+
 **Phase 2 progress (2026-05-25, develop / post-v0.8.1, unreleased):**
 
 - **`ONBOARDING_SELECTORS` restructured** — replaced the original 9 English/PT-BR

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.15.1
+Version: 0.16.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.15.1 → gflow_cli-0.16.0}/docs/CHARACTER.md

@@ -375,7 +375,8 @@ convenience later.
     generate) so Flow's JS sets `entityContext` and passes the WAF; gflow captures `media[]`/`workflows[]`
     from the response. Reuse gflow's prompt-submit + response-capture machinery (`ui_automation.py`), but in
     the character-editor context (NOT the new-project flow). Video `--character` reuse = resource picker
-    (`Pesquisar recursos` → Personagens → *Incluir no comando*) → generate; mirrors #123 `_attach_likeness`.
+    (search resources → Personagens → *include-in-prompt* context-menu action; captions are localized,
+    selectors locale-free since issue #170) → generate; mirrors #123 `_attach_likeness`.
     All selectors **ligature/structural only** (language-agnostic).
   - **Cost reality:** the feature is UI-automation-heavy (new character-editor + picker selectors), not the
     "mostly REST" earlier framing. Structural metadata is REST; the value-generating steps are UI.

gflow_cli-0.16.0/docs/IMAGE_UPSCALE_RECON.md

@@ -0,0 +1,115 @@
+# Image Upscale — Reverse-Engineering Recon
+
+> Status: **recon complete, pre-implementation**. Wire empirically captured 2026-06-11
+> (denon82 Pro account, project `ffb768fb…`). Spikes: `scripts/dev/spike_image_upscale_drive.py`
+> (UI drive + capture) and `scripts/dev/spike_image_upscale_rest_probe.py` (schema + REST probe).
+
+## Feature
+
+Flow's image editor download menu offers **1K Original / 2K Upscaled / 4K Upscaled**. gflow
+today saves only the 1K original (the pre-signed `fifeUrl` from the generation response). This
+feature adds `gflow image upscale <mediaId> --scale 2k|4k` to fetch the upscaled variant.
+
+Scope: **platform-generated images only** (referenced by `mediaId`). Uploaded images are not
+supported by this endpoint. **4K is Ultra-tier-gated**; Pro accounts see "Upgrade" in the UI.
+
+## Wire protocol
+
+### Endpoint
+```
+POST https://aisandbox-pa.googleapis.com/v1/flow/upsampleImage
+```
+Same host + auth class as image generation (`batchGenerateImages`).
+
+### Request body
+```json
+{
+  "mediaId": "<source-image-uuid>",
+  "targetResolution": "UPSAMPLE_IMAGE_RESOLUTION_2K",
+  "clientContext": {
+    "recaptchaContext": {
+      "token": "<reCAPTCHA-Enterprise-token>",
+      "applicationType": "RECAPTCHA_APPLICATION_TYPE_WEB"
+    },
+    "projectId": "<project-that-owns-the-media>",
+    "sessionId": ";<epoch_ms>",
+    "tool": "PINHOLE",
+    "userPaygateTier": "PAYGATE_TIER_ONE"
+  }
+}
+```
+- `targetResolution` enum: `UPSAMPLE_IMAGE_RESOLUTION_2K` | `UPSAMPLE_IMAGE_RESOLUTION_4K`.
+  1K = original (no API call — gflow already has it).
+- **The FULL `clientContext` is required.** A minimal `{recaptchaContext}` body returns
+  **403 even with a valid token** (confirmed by live smoke). All five fields are needed;
+  `projectId` (the project owning the media) is load-bearing.
+- `sessionId` format is `;<epoch_ms>` (e.g. `;1781190457842`), same as image generation.
+- `userPaygateTier` is **where the account tier surfaces on the wire** (`PAYGATE_TIER_ONE`
+  on a Pro account). It is client-reported telemetry — the server enforces the real tier
+  independently (a non-Ultra 4K request 403s regardless), so it is not a security control.
+
+### reCAPTCHA action — `IMAGE_GENERATION`
+The token MUST be minted with action **`IMAGE_GENERATION`** (uppercase). reCAPTCHA Enterprise
+scores by action; the guessed `"upsampleImage"` scored low and 403'd. Captured live by hooking
+`grecaptcha.enterprise.execute` (`scripts/dev/spike_image_upscale_recaptcha_action.py`). The
+site key is page-discovered, so it auto-matches; minting on the bootstrap page is fine — the
+action was the only gap. **Live-verified 2026-06-11**: a 2K upscale wrote a 3.8 MB JPEG.
+
+### Response
+```json
+{ "encodedImage": "<base64>" }
+```
+- Single field. ~3.8–5.1 MB base64 observed (varies by source image). Decode → write image bytes.
+- Synchronous: one call returns the result. **No async poll/status loop** (unlike video gen).
+
+## Transport decision — browser required, REST is dead
+
+| Approach | Viable? | Evidence |
+|---|---|---|
+| Pure REST / Bearer-only | ❌ No | Bearer `ya29` + **no** reCAPTCHA token → **403** (probed with and without `clientContext`) |
+| Browser reCAPTCHA-mint + POST | ✅ Yes | UI drive returns 200; reuses the existing `batchGenerateImages` transport |
+| Hybrid (browser submit + Bearer poll) | ⚠️ N/A | No poll/download phase exists — response is synchronous inline base64 |
+
+**Conclusion:** reCAPTCHA token is **mandatory**. Reuse the existing image-generation reCAPTCHA
+minting path; there is no Bearer-only slice to peel off. See [REST-path capability matrix] — a
+generative-class op stays reCAPTCHA-gated.
+
+## Tier gating (4K = Ultra)
+
+- 4K is Ultra-only. On Pro, the UI renders "Fazer upgrade" (Upgrade) instead of a clickable 4K.
+- Account tier is **NOT** in `GET /fx/api/auth/session` (only `user` / `expires` / `access_token`).
+  It surfaces via the upsell recommendations (`fetchUserRecommendations` onramp list) and is
+  enforced server-side. A 4K request on a non-Ultra account is expected to 403 (permission), which
+  must be distinguished from a WAF/reCAPTCHA 403.
+- Session staleness is real: an idle session returns `error: ACCESS_TOKEN_REFRESH_NEEDED` and
+  re-auths before the call succeeds — so a freshly-upgraded account may need a session refresh
+  before 4K unlocks.
+
+## UI navigation facts (for the spike/transport)
+
+- **Cold-loading `/project/<pid>/edit/<mediaId>` 500s** ("Algo deu errado"). Must land on the
+  gallery `/project/<pid>` then click the `a[href*=<mediaId>]` tile (in-app SPA routing).
+- A "What's new" changelog modal overlays the gallery but does **not** block the href tile click.
+- Working selectors (locale leaks into the UI — match language-neutral tokens):
+  - Download button: `button:has(i.google-symbols:text-is('download'))`
+  - Scale menu item: `[role='menuitem']:has-text('2K')` (and `'4K'`)
+  - pt labels are 1K="Tamanho original", 2K/4K="Aumentada" — **never** match on "Aumentada".
+
+## Implementation sketch (from `/gflow:predict` GO, 7.5/10)
+
+- `api/routes.py`: `UPSAMPLE_IMAGE = f"{FLOW_API_BASE}/flow/upsampleImage"`.
+- `api/image.py`: frozen `UpsampleImageRequest(media_id, target_resolution, recaptcha_token="")`;
+  `TargetResolution` enum with `from_cli("2k"|"4k")`.
+- `api/client.py`: `upsample_image()` — mint reCAPTCHA (existing path), POST, validate + decode
+  `encodedImage` with `MAX_UPSAMPLE_B64_LEN ≈ 50 MB` cap + `del` + PNG/JPEG magic-byte check
+  (mirror `concatenate_scene`).
+- `cli_image.py`: `gflow image upscale <mediaId> --scale 2k|4k [--out]`.
+- `errors.py`: `UpscaleUnavailableError` (exit 22), distinct from WAF/reCAPTCHA 403; **no auto-retry**
+  on a 4K 403.
+- Never log `encodedImage`. Record the output via `OperationRecorder` honoring the redaction gate.
+- Discover mediaIds via the existing `gflow data list images`.
+
+## Credit cost
+
+Image operation → expected **credit-free** (only video generation spends credits). Not yet
+stress-confirmed; treat as free but do not batch aggressively (per-profile WAF heat).

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

@@ -34,6 +34,7 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 | **[docs/DATA_LAYER.md](DATA_LAYER.md)** | Local SQLite catalog: goals, schema, recording flow, redaction, `gflow data` CLI, migrations, extension guide | Anything touching `gflow_cli.data`, debugging missing rows, building I2V/repair tooling, auditing what is stored |
 | **[docs/CHARACTER.md](CHARACTER.md)** | Characters feature spec & system design: domain model, endpoint/cost matrix, sequence diagrams, JSON payloads (I/O), CLI surface, reuse via `referenceEntities` (#145) | Working on `gflow character`, reusing a character in generations, or understanding Flow's character wire protocol |
 | **[docs/MOVIE.md](MOVIE.md)** | `gflow movie` — multi-scene character-consistent films: manifest format, run lifecycle (browser stays open through generate→poll→download), entity-attach mechanism (Personagens right-click), resume/handoff, credits | Working on `gflow movie`, debugging scene generation, or understanding the character-entity attach + consistency model |
+| **[docs/IMAGE_UPSCALE_RECON.md](IMAGE_UPSCALE_RECON.md)** | `gflow image upscale` wire protocol: `upsampleImage` endpoint, full clientContext (projectId/sessionId/tool/userPaygateTier), reCAPTCHA action `IMAGE_GENERATION`, inline base64 response, 4K Ultra-gating, REST-is-dead proof | Working on `gflow image upscale`, debugging the 403/reCAPTCHA path, or understanding Flow's image-upscale wire protocol (#171) |
 | **[tasks/lessons.md](../tasks/lessons.md)** | Running notebook of patterns + reviewer findings, dated and traced to commits | Starting a new phase; debugging "why did the council flag this?" |
 | **[skills/README.md](../skills/README.md)** | Installable agent skill docs (gflow-cli, predict, pr-council-review, scenario) — cross-tool portable Markdown consumed by Claude Code, Cursor, Codex, Gemini CLI, Aider, etc. | Any agent wanting to use gflow-cli correctly |
 | **[scripts/dev/skillopt/README.md](../scripts/dev/skillopt/README.md)** | SkillOpt mock harness — rollout→score loop for measuring and improving skill doc accuracy across multiple LLM providers | Measuring a skill edit's impact; comparing Claude vs GPT-4o vs Gemini on gflow tasks |

{gflow_cli-0.15.1 → gflow_cli-0.16.0}/docs/MOVIE.md

@@ -100,10 +100,13 @@ attached by driving Flow's resource picker:
 1. Click **Add Media** in the composer (references sub-mode).
 2. Switch to the **Personagens** (Characters) tab.
 3. **Right-click** the entity tile — addressed by entity id as
-   `data-tile-id="fe_id_<entityId>"` — and choose **"Incluir no comando"** from
-   the context menu. *(A plain left-click navigates into the character editor;
-   the inline "Incluir" button on the **Tudo** tab attaches the character's
-   thumbnail as a plain image, not the entity.)*
+   `data-tile-id="fe_id_<entityId>"` — and choose the **include-in-prompt**
+   action from the context menu (the `add`-ligature menu item; its caption is
+   localized per account language, e.g. "Incluir no comando" on pt-BR or
+   "Добавить в запрос" on ru — selectors are locale-free since issue #170).
+   *(A plain left-click navigates into the character editor; the inline include
+   button on the **Tudo** tab attaches the character's thumbnail as a plain
+   image, not the entity.)*
 
 This puts `referenceEntities:[{entityId}]` on the
 `video:batchAsyncGenerateVideoReferenceImages` **request**. Flow's **response**

{gflow_cli-0.15.1 → gflow_cli-0.16.0}/docs/USAGE.md

@@ -105,6 +105,44 @@ UUID=$(gflow image upload hero.png | awk '/Asset UUID:/ {print $3}')
 gflow image i2i "make it cinematic" --ref "$UUID"
 ```
 
+## `gflow image upscale`
+
+Upscale a **platform-generated** image to 2K or 4K (the same 1K/2K/4K options Flow's
+download menu offers) and save it locally. Uploaded images are not supported.
+
+```text
+gflow image upscale MEDIA_ID --scale 2k|4k [OPTIONS]
+
+Arguments:
+  MEDIA_ID                  UUID of a Flow-generated image (find one with
+                            `gflow data list images`).
+
+Options:
+  --scale [2k|4k]           Target resolution. 4k requires a Flow Ultra
+                            subscription; 1k is the original (no upscale).
+  --project ID              Project that owns the image. Resolved from the local
+                            catalog when omitted; pass it explicitly for images
+                            gflow didn't record (e.g. generated in the web UI).
+  --out PATH                Output directory (see "Output paths" below).
+  --profile NAME            Profile name (overrides default).
+```
+
+```bash
+# Upscale a previously generated image to 2K (project auto-resolved from the catalog)
+gflow image upscale 3a56bb5e-92a2-44f4-9992-3c6a9bf0cd14 --scale 2k
+
+# Upscale an image generated in the Flow web UI (not in the local catalog)
+gflow image upscale <mediaId> --scale 2k --project <projectId>
+```
+
+Notes:
+
+- **Credit-free** — upscaling is an image operation and spends no credits.
+- **4K is Ultra-only.** On a non-Ultra account a 4K request fails with exit code 22
+  (`UpscaleUnavailableError`) and a hint to use `--scale 2k` or upgrade.
+- The result is saved as `<output_dir>/images/<YYYY-MM-DD>/<mediaId>_<scale>.<ext>`
+  (extension matches the returned format — usually `.jpg`).
+
 ## `gflow image t2i`
 
 Generate 1–4 images from one text prompt, or run a shell-friendly batch of 1–50

gflow_cli-0.16.0/docs/superpowers/plans/2026-06-11-image-upscale/PLAN.md

@@ -0,0 +1,206 @@
+# Image Upscale Implementation Plan
+
+> **For agentic workers:** Run `/gflow:status --feature image-upscale` to find the next
+> unchecked task. Implement one task at a time. Run `/gflow:check` before every commit.
+
+**Goal:** Add `gflow image upscale <mediaId> --scale 2k|4k` so a user can fetch Flow's
+server-side 2K/4K upscaled variant of a platform-generated image and save it locally.
+
+**Architecture:** Reuses the existing image-generation reCAPTCHA browser transport — same host
+(`aisandbox-pa.googleapis.com`) and `recaptchaContext` shape as `batchGenerateImages`. New work is
+glue: a route constant, a frozen request value object, a synchronous `FlowApiClient.upsample_image()`
+that mints a reCAPTCHA token, POSTs, and decodes the inline `{encodedImage: base64}` (mirroring
+`concatenate_scene`'s cap + `del` + magic-byte pattern), a new exit-coded error, and a Click
+subcommand. No transport-Protocol change (it's a client-level op like `concatenate_scene`). No new
+auth, no new persistent state, no async poll loop.
+
+**Tracking issue:** [#171](https://github.com/ffroliva/gflow-cli/issues/171)
+
+**Predict verdict:** GO — confidence 7.5/10. Recon: `docs/IMAGE_UPSCALE_RECON.md`. Scenario matrix
+complete (20 scenarios; 12 Critical/High are must-cover).
+
+**Risk register:**
+| Severity | Risk | Mitigation |
+|---|---|---|
+| Critical | 403 ambiguity: tier-gate (4K/Pro) vs WAF heat vs expired token all return 403 | Disambiguate by response context; `UpscaleUnavailableError` (exit 22) for tier; **never auto-retry** a 4K 403 |
+| Critical | ~5 MB `encodedImage` base64 leaks into logs / error context | Never log the field; decode then `del`; structlog carries size only |
+| High | Pathological oversized base64 (4K PNG) → OOM | `MAX_UPSAMPLE_B64_LEN` (~50 MB) cap **before** decode; typed error |
+| High | Response missing `encodedImage` / decodes to non-image | `WireFormatError` (redacted discovery payload); PNG/JPEG magic-byte check |
+| High | Per-profile reCAPTCHA/WAF heat (a 4th gated op) | One upscale per invocation; no implicit batch; document the heat |
+| High | mediaId injection / malformed input | UUID allowlist; reject before any request fires |
+| Medium | Selector drift (download button / scale menu) on Flow UI update | Structural-first, locale-neutral selectors (`download`, `2K`/`4K`); re-capture via spike |
+
+---
+
+## File structure
+
+### New files
+```
+src/gflow_cli/api/image_upscale.py        (or extend api/image.py)
+  UpsampleImageRequest frozen dataclass + TargetResolution enum (from_cli "2k"/"4k")
+tests/api/test_image_upscale.py
+  Unit tests: request build, response parse (cap/magic-byte/missing-field), 403 disambiguation
+tests/features/image_upscale.feature
+  BDD scenarios from /gflow:scenario (happy 2K, 4K-on-Pro, oversized, malformed mediaId)
+tests/features/test_image_upscale_steps.py
+  Step defs mirroring runtime signatures
+```
+
+### Modified files
+```
+src/gflow_cli/api/routes.py
+  + UPSAMPLE_IMAGE = f"{FLOW_API_BASE}/flow/upsampleImage"
+src/gflow_cli/api/client.py
+  + MAX_UPSAMPLE_B64_LEN; + async def upsample_image(media_id, target_resolution, out_path)
+    (mint reCAPTCHA via _mint_recaptcha_token; POST; cap+decode+magic-byte; write via image_output_path)
+src/gflow_cli/errors.py
+  + UpscaleUnavailableError (exit 22) registered in EXIT_CODE_MAP; distinct from WAF/reCAPTCHA 403
+src/gflow_cli/cli_image.py
+  + `upscale` Click command: <mediaId> arg, --scale Choice(['2k','4k']), --out, --profile
+src/gflow_cli/paths.py
+  (reuse image_output_path; add <mediaId>_<scale> naming if needed)
+docs/USAGE.md, README.md, docs/INDEX.md, CHANGELOG.md
+  document the command + the platform-only / Ultra-only constraints
+```
+
+---
+
+## Task 1 — Error type + exit code (test-first)
+
+**What:** Add `UpscaleUnavailableError` (exit 22) for tier-gated/permission failures, distinct from WAF/reCAPTCHA 403.
+
+**Files:**
+- `tests/test_errors.py` — assert exit code 22, EXIT_CODE_MAP registration, ordering invariant
+- `src/gflow_cli/errors.py` — new class + map entry
+
+**Steps:**
+- [x] Red test: `UpscaleUnavailableError` maps to 22; not equal to WAF 403 code
+- [x] Add the class (RFC 9457 fields: type/title/status/detail/remediation_hint) + register in `EXIT_CODE_MAP`
+- [x] Verify `test_exit_code_map_ordering_invariant` still passes (inheritance trap — see memory)
+
+**Tests created (red):**
+- [x] `test_upscale_unavailable_exit_code` — exit 22, distinct from WAF/reCAPTCHA
+
+---
+
+## Task 2 — Value objects (test-first)
+
+**What:** `TargetResolution` enum (`2K`/`4K` ↔ wire `UPSAMPLE_IMAGE_RESOLUTION_*`, `from_cli`) and frozen `UpsampleImageRequest`.
+
+**Files:**
+- `tests/api/test_image_upscale.py` — enum mapping, `from_cli` rejects bad values, request immutability
+- `src/gflow_cli/api/image.py` (or new `image_upscale.py`) — enum + dataclass + body builder
+
+**Steps:**
+- [x] Red tests: `TargetResolution.from_cli("2k")` → enum; `"1k"`/`"8k"` rejected; request frozen
+- [x] Add enum + `UpsampleImageRequest(media_id, target_resolution, recaptcha_token="")`
+- [x] Body builder → `{mediaId, targetResolution, clientContext:{recaptchaContext:{token}}}`
+- [x] mediaId UUID-allowlist validation (reject malformed before request)
+
+**Tests created (red):**
+- [x] `test_target_resolution_from_cli` / `test_target_resolution_rejects_1k_and_unknown`
+- [x] `test_upsample_request_body_shape`
+- [x] `test_media_id_uuid_validation`
+
+---
+
+## Task 3 — Client `upsample_image()` (test-first)
+
+**What:** Synchronous client method: mint reCAPTCHA, POST `upsampleImage`, parse `{encodedImage}` with cap + magic-byte, write file. Route constant added.
+
+**Files:**
+- `tests/api/test_image_upscale.py` — mocked transport/HTTP: happy path, oversized cap, missing field, non-image bytes, 403→typed error, no-retry on 4K 403, `encodedImage` never logged
+- `src/gflow_cli/api/routes.py` — `UPSAMPLE_IMAGE`
+- `src/gflow_cli/api/client.py` — `MAX_UPSAMPLE_B64_LEN = 50 * 1024 * 1024`; `upsample_image(...)`
+
+**Steps:**
+- [x] Red tests for: 200 happy (decode → PNG/JPEG bytes written); response > cap → typed error before decode; missing `encodedImage` → `WireFormatError` (redacted); decoded bytes fail magic-byte → typed error
+- [x] Red tests for 403 disambiguation: tier 403 → `UpscaleUnavailableError` (no retry); WAF 403 → existing `WafRejectionError`; expired-token 401 → existing refresh+single-retry
+- [x] Red test: structlog capture asserts `encodedImage` value never present in any event
+- [x] Add route + method; reuse `_mint_recaptcha_token("upscaleImage" or correct action)`; single Page checkout (no nested checkout — use `context.request` if aux call needed)
+- [x] Decode mirrors `concatenate_scene` (cap → `b64decode` → magic-byte → `del encoded`)
+- [x] Write via `paths.image_output_path` as `<mediaId>_<scale>.<ext>` (ext from magic byte)
+
+**Tests created (red):**
+- [x] `test_upsample_happy_2k`, `test_upsample_oversized_rejected`, `test_upsample_missing_field`,
+      `test_upsample_non_image_bytes`, `test_upsample_4k_pro_403_no_retry`,
+      `test_upsample_waf_403_distinct`, `test_upsample_encoded_image_never_logged`
+
+---
+
+## Task 4 — CLI surface (test-first)
+
+**What:** `gflow image upscale <mediaId> --scale 2k|4k [--out] [--profile]` with self-contained `--help`.
+
+**Files:**
+- `tests/test_cli_image.py` — Click invocation: arg/flag parsing, `--scale` Choice, exit codes, 4K/Pro hint, malformed mediaId usage error (no request), structlog `upscale_started/completed/unavailable`
+- `src/gflow_cli/cli_image.py` — `upscale` command
+
+**Steps:**
+- [x] Red tests: happy invocation calls `upsample_image` with mapped enum; `--scale 8k` rejected by Click; `--scale 1k` rejected with "1k is the original" hint; malformed mediaId → usage error, no HTTP
+- [x] Red test: 4K-on-Pro path surfaces exit 22 + Ultra-only remediation; no auto-retry
+- [x] Implement command; emit `upscale_started/completed/unavailable` (stable keys); `--help` states platform-only + Ultra-only constraints + "find mediaId via `gflow data list images`"
+- [x] Record the output asset via `OperationRecorder` honoring the redaction gate; wrap callback in try/except `DataStoreError`
+
+**Tests created (red):**
+- [x] `test_upscale_cli_happy`, `test_upscale_cli_scale_choice`, `test_upscale_cli_1k_rejected`,
+      `test_upscale_cli_bad_media_id`, `test_upscale_cli_4k_pro_exit22`
+
+---
+
+## Task 5 — BDD scaffold + green
+
+**What:** Gherkin feature covering all Critical+High scenarios; step defs mirror runtime signatures.
+
+**Files:**
+- `tests/features/image_upscale.feature` — happy 2K, 4K-on-Pro, oversized, malformed mediaId
+- `tests/features/test_image_upscale_steps.py` — typed step defs (mirror signatures — see memory)
+
+**Steps:**
+- [x] Add the four `/gflow:scenario` BDD scenarios as a feature file
+- [x] Implement step defs against the real command; assert exit codes + redaction
+- [x] All BDD green
+
+**Tests created:**
+- [x] BDD: 2K happy, 4K/Pro exit 22, oversized rejected, malformed mediaId usage error
+
+---
+
+## Task 6 — Docs + recon finalize
+
+**What:** User-facing docs + cross-references; recon already written.
+
+**Files:**
+- `docs/USAGE.md` — `gflow image upscale` section (workflow: `data list images` → `upscale`)
+- `README.md` command table; `docs/INDEX.md` route to `IMAGE_UPSCALE_RECON.md`
+- `docs/KNOWN_ISSUES.md` — note 4K Ultra-gating + per-profile WAF heat from the extra gated op
+- `CHANGELOG.md` `[Unreleased]` — `feat(image): upscale to 2K/4K (#171)`
+
+**Steps:**
+- [x] Write usage + constraints (platform-only, Ultra-only, credit-free expectation)
+- [x] Index the recon doc; cross-link spikes
+- [x] CHANGELOG entry referencing #171
+
+---
+
+## Task 7 — Full gates + PR
+
+**What:** Green `/gflow:check`; open PR to `develop`.
+
+**Steps:**
+- [x] `/gflow:check` green (ruff + format + `pyright src` + pytest ≥ 80% on changed dirs)
+- [x] Live smoke (opt-in, supervised): one real 2K upscale on a known mediaId (credit-free) confirms wire still matches
+- [x] PR `feature/image-upscale` → `develop`, `Closes #171`
+
+---
+
+## Definition of done
+
+- [x] All task steps checked off
+- [x] `/gflow:check` green (ruff / format / pyright / pytest ≥ 80% coverage)
+- [x] `CHANGELOG.md` `[Unreleased]` updated (`#171`)
+- [x] Docs updated (`USAGE.md`, `README.md`, `INDEX.md`, `KNOWN_ISSUES.md`)
+- [x] BDD feature covers all Critical + High scenarios from `/gflow:scenario`
+- [x] `encodedImage` proven absent from logs (test) — Critical mitigation verified
+- [x] 4K/Pro 403 → exit 22, no auto-retry — Critical mitigation verified
+- [x] No `# TODO` in diff without a tracked issue link

gflow_cli-0.16.0/docs/superpowers/plans/2026-06-11-image-upscale/SCENARIO.md

@@ -0,0 +1,79 @@
+# Scenario: `gflow image upscale <mediaId> --scale 2k|4k`
+
+> `/gflow:scenario` output for issue #171. Produced pre-implementation, then
+> revised against the **live-verified** wire (see `docs/IMAGE_UPSCALE_RECON.md`).
+> Feeds the test matrix in `tests/api/test_client_upscale.py`,
+> `tests/cli/test_cli_image_upscale.py`, and `tests/features/image_upscale.feature`.
+
+## Coverage map
+
+**Active dimensions:**
+- **D1 Auth & session lifecycle** — Bearer/session staleness observed live
+  (`ACCESS_TOKEN_REFRESH_NEEDED`); the existing refresh-on-401 path applies.
+- **D2 WAF / reCAPTCHA** — the gating mechanism. Action `IMAGE_GENERATION` is
+  mandatory; per-profile heat is the dominant operational risk.
+- **D3 Selector drift** — download button + 1K/2K/4K menu (locale-neutral).
+- **D6 Data layer** — the catalog resolves the owning `projectId` from `mediaId`.
+- **D7 Error propagation & exit codes** — 403 disambiguation, base64 redaction.
+- **D8 Cross-platform paths** — `<mediaId>_<scale>.<ext>` output, Windows.
+- **D9 Transport edge cases** — `encodedImage` parse/cap/magic-byte.
+- **D11 Input validation** — mediaId/projectId UUID, `--scale`, 4K/Pro, uploads.
+- **D12 Observability** — `image.upscale_{started,completed}` events, RFC 9457.
+
+**Skipped:**
+- **D4 Batch manifest** — v1 is single-image; no batch runner.
+- **D5 Concurrency / Page pool** — one synchronous op, single Page checkout, no
+  fan-out (no `asyncio.gather`, no nested checkout).
+- **D10 Headless/CI** — the browser + reCAPTCHA requirement is identical to the
+  existing image-generation path; inherited, not new.
+
+## Scenario table
+
+| # | Dimension | Scenario | Severity | Expected behaviour | Test |
+|---|---|---|---|---|---|
+| 1 | D2 | reCAPTCHA action mismatch (e.g. wrong/guessed action) | **Critical** | Token scores low → 403. Action MUST be `IMAGE_GENERATION`. *(Root-caused live; locked by the action constant.)* | Live + recon spike |
+| 2 | D9 | Incomplete `clientContext` (missing projectId/sessionId/tool/tier) | **Critical** | Server 403s even with a valid token. Full 5-field clientContext is sent. *(Root-caused live.)* | Unit (`test_body_shape`) |
+| 3 | D2/D7 | 4K requested on a non-Ultra account → server 403 | **Critical** | `UpscaleUnavailableError` (exit 22), "Ultra-only" hint; **no auto-retry** | Unit + CLI + BDD |
+| 4 | D7 | 403 disambiguation: 4K-tier vs WAF vs expired token | **Critical** | 4K-403 → exit 22; 2K-403 → `WafRejectionError` (10); 401 → refresh+retry | Unit (`test_upsample_4k_403…`, `…2k_403_stays_waf`) |
+| 5 | D7/D12 | The ~4 MB `encodedImage` base64 leaks into logs | **Critical** | Never logged; event carries `bytes` int only | Unit (`…never_logged`, `capture_logs`) |
+| 6 | D9 | Oversized response (pathological 4K base64 > cap) | **High** | Reject before decode at `MAX_UPSAMPLE_B64_LEN` (50 MB); no write | Unit (`…oversized…`) |
+| 7 | D9 | Response missing `encodedImage` / unexpected shape | **High** | `WireFormatError` + discovery payload, not a crash | Unit (`…missing…`) |
+| 8 | D9 | `encodedImage` decodes but isn't PNG/JPEG | **High** | Magic-byte check → `WireFormatError`; no garbage written | Unit (`…non_image…`, `…undecodable…`) |
+| 9 | D11/D6 | `projectId` unresolvable (not in catalog, no `--project`) | **High** | Fail fast exit 2 + "pass --project" hint; no browser/mint | CLI + BDD (`…unresolvable…`) |
+| 10 | D11 | Malformed `mediaId` / `--project` (non-UUID) | **High** | Rejected before any work (exit 2) | Unit + CLI + BDD (`…bad_media_id…`) |
+| 11 | D6 | mediaId owned by a different account/profile | **High** | Catalog lookup is profile-scoped (ownership proof); server is final arbiter | CLI (catalog resolve path) |
+| 12 | D1 | Bearer/session stale at call time (`ACCESS_TOKEN_REFRESH_NEEDED`) | **High** | Existing refresh-on-401 mints fresh token + single retry | Live-observed |
+| 13 | D11 | `--scale 1k` (the original, no upscale) | **Medium** | Rejected with "1k is the original" hint (exit 2) | Unit + CLI |
+| 14 | D11 | `--scale` outside {2k,4k} | **Medium** | Rejected before I/O (exit 2) | Unit + CLI |
+| 15 | D3 | Flow renames the download ligature / restructures the menu | **Medium** | Structural, locale-neutral selectors (`download`, `2K`/`4K`); re-capture via spike | Spike (manual) |
+| 16 | D8 | Output filename on Windows; large binary write; PYTHONUTF8 unset | **Medium** | `write_bytes` (encoding-agnostic); platformdirs; `<mediaId>_<scale>.<ext>` | Unit (extension) |
+| 17 | D12 | New structlog events stable + documented | **Medium** | `image.upscale_started/completed`; RFC 9457 on error | Covered by event asserts |
+| 18 | D6 | `--project` disagrees with catalog's project for the mediaId | **Low** | Warn (non-fatal); use `--project` as given | CLI (resolve path) |
+
+## Must-cover before merge (Critical + High) — all covered
+
+1. **reCAPTCHA action = `IMAGE_GENERATION` + full clientContext** (#1, #2) — root-caused
+   by live smoke; locked by the action constant and `build_upsample_image_body`.
+2. **403 disambiguation, no auto-retry on 4K** (#3, #4) — `UpscaleUnavailableError` (22).
+3. **base64 never logged + capped + magic-byte validated** (#5, #6, #7, #8).
+4. **projectId resolution + fail-fast + UUID validation** (#9, #10, #11).
+5. **Session refresh** (#12) — reuses the existing 401 path.
+
+## Deferred (Medium + Low — follow-ups, not blockers)
+
+- Record the upscaled output in the data catalog (D6) — future follow-up.
+- `gflow image t2i --upscale` convenience flow (one reCAPTCHA mint) — future follow-up.
+- Selector-drift re-capture is manual via `scripts/dev/spike_image_upscale_drive.py`.
+
+## BDD scenarios (`tests/features/image_upscale.feature`)
+
+Implemented: 2K happy (explicit project), catalog-resolved project, 4K→exit 22,
+unresolvable project→exit 2, malformed mediaId→exit 2.
+
+## Known-issues cross-reference
+
+- **reCAPTCHA Enterprise 403 / per-profile WAF heat** (KNOWN_ISSUES) — #1, #12 map
+  here. Upscale reuses the gated transport and adds a 4th gated op; mitigated by
+  one-at-a-time + no-auto-retry. Not resolved (inherent to the platform).
+- **4K requires Ultra** — now a documented Open limitation in KNOWN_ISSUES (#171).
+- **Locale leak / icon ligatures** — #15; selectors stay language-neutral.