gflow-cli 0.66.1__tar.gz → 0.66.3__tar.gz

{gflow_cli-0.66.1 → gflow_cli-0.66.3}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gflow",
-  "version": "0.66.1",
+  "version": "0.66.3",
   "description": "Reusable development and operations workflows for gflow-cli",
   "author": {
     "name": "Flavio Oliva",

{gflow_cli-0.66.1 → gflow_cli-0.66.3}/CHANGELOG.md

@@ -7,6 +7,89 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.66.3] — 2026-09-03
+
+### Fixed
+
+- **`<html lang>` was read before the app set it, so every account whose URL could not answer
+  resolved to `en` ([#651](https://github.com/ffroliva/gflow-cli/issues/651)).** Flow serves an
+  **`en` shell** and rewrites `lang` during hydration. The single early read added by
+  [#643](https://github.com/ffroliva/gflow-cli/issues/643) therefore returned the shell value —
+  and the accounts it hit are exactly the ones #643 was written for: those where the URL carries
+  no locale segment. Reported by
+  [@maipmacrothorax-75](https://github.com/maipmacrothorax-75) on a pt-BR account resolving `en`
+  while both pages served `<html lang="pt">`, with the mechanism offered explicitly as a guess.
+
+  The guess is confirmed, and it reproduces on the **old** host — so this was never a migration
+  bug. Measured on a pt account, two consecutive loads:
+
+  | t (ms) | `lang` | `readyState` |
+  |---|---|---|
+  | 887 | `en` | interactive |
+  | **1510** | `en` | **complete** |
+  | 2092 | `en` | complete |
+  | **2488** | **`pt`** | complete |
+
+  **`readyState` is not a usable signal** — it reaches `complete` a full second *before* the
+  flip, so the obvious "wait for complete, then read" would have shipped the same bug with more
+  code. The DOM node count oscillates (136 → 300 → 249 → 251) and does not discriminate either.
+  Nothing cheap predicts the flip, so `_resolve_account_locale` now **observes** it: read once,
+  bounded-wait for the value to change, re-read.
+
+  A timeout is an **answer**, not a failure — either the account's locale genuinely equals the
+  shell default, or the page never hydrated in the window. Both leave the first read as the best
+  available answer, which is exactly the previous behaviour, so the branch can never be worse
+  than what it replaces. It is logged as `client.account_locale_lang_unchanged` so the field can
+  tell the two apart. Cost: an account whose locale **is** the shell default pays the 4 s bound
+  once per process.
+
+## [0.66.2] — 2026-09-03
+
+### Fixed
+
+- **v0.66.1's migrated-origin fast-fail never fired on a real run
+  ([#639](https://github.com/ffroliva/gflow-cli/issues/639)).** The guard read `page.url` once,
+  at `get_ui_driver` entry — but `routes.project_editor_url` only ever builds a `labs.google`
+  URL and the hop to `flow.google.com` is a *post-`goto`* redirect that neither settle path
+  waits for (no locale → `_settle_if_redirecting` returns immediately; a known locale →
+  `await_url_settled` short-circuits because the labs URL already matches the localised shape).
+  So the guard classified a pre-redirect URL, declined, and the run paid ~54 s before failing
+  anyway through the slow selector-probe path. Measured by the reporter on three consecutive
+  v0.66.1 runs: **57.0 / 57.1 / 58.3 s**, with `ui_driver.migrated_host_bail` absent from the
+  timeline entirely. The host check is now a shared `raise_if_migrated` helper called at the
+  three points the run is *about to spend time* — `get_ui_driver` entry, each `detect_ui_mode`
+  poll tick, and `_exit_agent_mode` once the media panel is found absent — so it adds no wait
+  and no navigation to the old host, and aborts as soon as the redirect is observable. The
+  event now names its call site, so the fast path is visible in a field timeline instead of
+  inferred. Two blanket `except Exception` handlers that would have demoted the abort to a
+  warning now re-raise it.
+
+- **A `NOT_REDIRECTED` locale cache was an absorbing state, which made the #643 `<html lang>`
+  recovery unreachable on exactly the profiles that needed it
+  ([#643](https://github.com/ffroliva/gflow-cli/issues/643)).** `_bootstrap_and_resolve_locale`
+  returned *before* `_resolve_account_locale` — the only site of that recovery and the only
+  caller of `next_locale_state` — so nothing could ever move a latched profile off the state.
+  Every profile that saw two migrated loads on ≤0.66.0 latched this way. `NOT_REDIRECTED` now
+  skips the settle only, and still reads the locale: measured 56/56 on a latched profile whose
+  page declares `lang="en"` on every load. The 4 s settle stays skipped — deleting the early
+  return outright was rejected, because on that account the cached "not redirected" is a true
+  observation.
+
+- **A `<html lang>` locale was treated as evidence that Flow redirects the account, which
+  switched the URL settle back on permanently ([#643](https://github.com/ffroliva/gflow-cli/issues/643)).**
+  Shipped in v0.66.1 and present on `develop`: #643's `<html lang>` fallback returns a segment for
+  an account Flow serves **bare** and never redirects, and `next_locale_state` recorded it as the
+  cached state. Every later bootstrap then saw `cached != NOT_REDIRECTED`, settled, and burned the
+  full 4 s `URL_SETTLE_TIMEOUT_MS` waiting for a redirect that never comes — the exact cost #587
+  exists to remove, on any non-redirecting account with a `lang` attribute. Only a **URL-derived**
+  segment is now folded into that cache; the lang-derived one is used in-process to build URLs and
+  never persisted. Measured on a real profile: warm bootstrap **7.41 s → 2.66 s**, with the locale
+  still recovered.
+
+- **`docs/MCP.md`'s retryable-class list was incomplete**, which would have told an MCP agent not
+  to auto-retry failures the envelope marks `retryable: true`. It omitted `FlowHostMigratedError`,
+  `UiModeUnavailableError` and `SyncPartialError`; it now matches `errors.RETRYABLE_ERRORS`.
+
 ## [0.66.1] — 2026-09-03
 
 ### Fixed
@@ -3737,7 +3820,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.66.1...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.66.3...HEAD
+[0.66.3]: https://github.com/ffroliva/gflow-cli/compare/v0.66.2...v0.66.3
+[0.66.2]: https://github.com/ffroliva/gflow-cli/compare/v0.66.1...v0.66.2
 [0.66.1]: https://github.com/ffroliva/gflow-cli/compare/v0.66.0...v0.66.1
 [0.66.0]: https://github.com/ffroliva/gflow-cli/compare/v0.65.0...v0.66.0
 [0.65.0]: https://github.com/ffroliva/gflow-cli/compare/v0.64.0...v0.65.0

{gflow_cli-0.66.1 → gflow_cli-0.66.3}/KNOWN_ISSUES.md

@@ -50,7 +50,7 @@ callers get this for free: the failure is `FlowHostMigratedError` (exit 36) with
 `retryable: true`, so retry loops driven by the `--json` / MCP / worker error
 envelope will keep trying.
 
-**What gflow does today (v0.66.0):** recognises the migrated origin and fails
+**What gflow does today (v0.66.2):** recognises the migrated origin and fails
 with the distinct, retryable exit 36 instead of the misleading
 `UiSelectorDriftError` (exit 23, "file a selector bug"). `_check_logged_in` also
 accepts the migrated host, so a migrated load is no longer misread as a
@@ -58,6 +58,18 @@ logged-out session. **Support for driving the new frontend is separate work and
 is not implemented** — once the rollout completes for an account, no retry will
 help until then.
 
+> **v0.66.1's fast-fail did not fire in the field, and v0.66.2 is the correction.**
+> The guard read `page.url` once, at `get_ui_driver` entry — before the hop to
+> `flow.google.com` had landed, because `project_editor_url` only builds
+> `labs.google` URLs and the redirect arrives *after* `page.goto` returns.
+> Measured by the reporter on three consecutive v0.66.1 runs: exit 36 at **57.0 /
+> 57.1 / 58.3 s**, through the slow selector-probe path. v0.66.2 re-checks the host
+> at the points the run already blocks, so the abort costs the old host nothing and
+> lands as soon as the redirect is observable. The same release stops a
+> `NOT_REDIRECTED` locale cache from disabling the `<html lang>` recovery (#643),
+> which had made that state unrecoverable on exactly the profiles it was written
+> for.
+
 ---
 
 ### A Veo extend segment is 7 seconds, not the 8 Flow advertises — so concat pads a frozen second

{gflow_cli-0.66.1 → gflow_cli-0.66.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gflow-cli
-Version: 0.66.1
+Version: 0.66.3
 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.66.1 → gflow_cli-0.66.3}/docs/INDEX.md

@@ -162,6 +162,10 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 
 **"What was live-verified for v0.66.0?"** → [LIVE_VERIFICATION_v0.66.0](LIVE_VERIFICATION_v0.66.0.md) — **#639 Flow's `flow.google.com` migration, verified 2026-09-03 on profile `ffroliva` at ZERO credits.** The maintainer's own account turned out to be inside the rollout, so the fix was proven against the real migrated frontend rather than a reconstructed DOM: a read-only probe of `flow.google.com/project/<id>` measured `i_total: 0` (independently reproducing the reporter's central measurement) and drove the production functions against the live page — `flow_host_kind: "migrated"`, `_check_logged_in: true` (it was `false` before the fix, i.e. a valid session read as logged-out), and `_mode_switch_error` returning `FlowHostMigratedError` / exit 36 / `retryable: true`. The flap is confirmed on ONE account: a credit-free `image t2i` minutes earlier landed on the OLD host and completed exit 0 with a real 768x1376 JPEG (`ffd8ffe0`, 401,939 bytes, Pillow dims matching the API claim), proving the rewritten host gate does not regress the old path. Also recorded: the migrated URL **drops `/fx/tools/flow` entirely** — it is `/project/<id>` — which is why a substring gate on `labs.google` could never match it; and the migrated composer is not control-less but exposes **no `data-testid`, zero ligature `<i>`, and 13 `button[aria-label]`** (`Settings trigger`, `Start generation`, …), recorded as recon for the follow-up WITH the caveat that `aria-label` is translated and therefore Tier-2 at best under the locale-invariance rule. One item is recorded as NOT verified rather than omitted: gflow **driving** the migrated frontend, which is out of scope and keeps #639 open. Verification also hit pre-existing [#561](https://github.com/ffroliva/gflow-cli/issues/561) (401 on `project.createProject`), A/B'd against unmodified `develop` to prove it was not this change, then routed around with an existing `--project`.
 
+**"What was live-verified for v0.66.3?"** → [LIVE_VERIFICATION_v0.66.3](LIVE_VERIFICATION_v0.66.3.md) — the `<html lang>` hydration race, with the negative result that chose the design: **`readyState` reaches `complete` a full second BEFORE the attribute flips**, so "wait for complete, then read" would have shipped the same bug. Component and end-to-end measurements are reported separately on purpose. NOT verified: the migrated origin (fix proven on the old host, where the race also occurs) and the 4 s bound against a cold first load.
+
+**"What was live-verified for v0.66.2?"** → [LIVE_VERIFICATION_v0.66.2](LIVE_VERIFICATION_v0.66.2.md) — the old host proven live at zero credits (**exit 0**, real 768x1376 JPEG, twice), the locale cache measured **7.41 s → 2.66 s**, and the migrated path recorded as **NOT verified** because the rollout flapped back (72/72 navigations landed on `labs.google`). No time-to-exit-36 is claimed — this release exists because v0.66.1 reported one from the wrong entrypoint, so see also the correction block atop [LIVE_VERIFICATION_v0.66.1](LIVE_VERIFICATION_v0.66.1.md).
+
 **"What was live-verified for v0.65.0?"** → [LIVE_VERIFICATION_v0.65.0](LIVE_VERIFICATION_v0.65.0.md) — the guard A/B (three runs, zero credits, control included); the `chain`/`movie` duration guards are validation that refuses **before** any transport call, so they are covered by a red state that reproduces the mid-spend crash in a test plus negative controls, and the reason they were not live-run is recorded rather than omitted.
 
 **"Does the `referenceEntity` guard actually run, and is it a Web Worker or a Service Worker?"** → [LIVE_VERIFICATION_reference_entity_guard](LIVE_VERIFICATION_reference_entity_guard.md) — **A/B-proven live on denon82 2026-09-02, zero credits.** Control (without #618): the guard never fired and the test failed; with #618: it fired and passed. Same account, same prompt, one variable. Settles the question that held #618 — it is a **dedicated Web Worker**, so `context.route` suffices and no `service_workers="block"` is needed. Also confirms `route.continue_(post_data=...)` does not corrupt the body (both runs produced a real image). The **video** glob was equally dead, which #615 never mentions. Residual: direct-wire routes still bypass structurally (#619).

{gflow_cli-0.66.1 → gflow_cli-0.66.3}/docs/LIVE_VERIFICATION_v0.66.1.md

@@ -3,6 +3,34 @@
 **Date:** 2026-09-03 · **Account:** ffroliva@gmail.com · **Platform:** Windows 11, Chrome strategy
 **Credits spent:** **0** — one Imagen image (images are credit-free) plus read-only probes.
 
+> ## ⚠️ Correction (2026-09-03, same day) — Layer 1's latency numbers are not user-visible
+>
+> **Layer 1 below measured `get_ui_driver` in isolation, on a page already sitting on
+> `flow.google.com`.** That precondition never holds on a real run: `project_editor_url`
+> only ever builds a `labs.google` URL and the hop to the migrated origin is a
+> *post-`goto`* redirect that neither settle path waits for, so on the CLI route the guard
+> read a pre-redirect URL and declined.
+>
+> The reporter of #639 measured the real path on three consecutive v0.66.1 runs: **57.0 /
+> 57.1 / 58.3 s**, terminating through `ui_automation_video.selector_probe_failed` — the
+> slow path — with `ui_driver.migrated_host_bail` **absent from the timeline entirely**.
+>
+> So of the rows below: `"get_ui_driver": {"ms": 0}` and **`time to exit 36 — 0 ms` are
+> true of the isolated probe and false of every CLI run.** The claim
+> *"`ui_driver.migrated_host_bail` is logged, so the fast path is observable rather than
+> inferred"* is the one the field timeline falsified — the event was never emitted, and
+> nothing here noticed because the isolated probe emitted it.
+>
+> The same gap hid the locale fix: `client.py` returned before `_resolve_account_locale`
+> on a `NOT_REDIRECTED` cache, so the `<html lang>` recovery Layer 1 exercised **directly**
+> is unreachable through the client on exactly the profiles that need it. `profile_ffroliva`
+> is latched that way today.
+>
+> Both are fixed for v0.66.2 — see [LIVE_VERIFICATION_v0.66.2](LIVE_VERIFICATION_v0.66.2.md).
+> **Layer 2 (no regression on the old host) stands unchanged and is still the load-bearing
+> result here.** The lesson is recorded rather than the numbers quietly edited: a function
+> measured in isolation is not a verification of the path users take.
+
 ## What had to be proven
 
 Two fixes, both on the migrated-origin path, and both verifiable live because the account is
@@ -31,10 +59,13 @@ Plus the property that matters more than either: **the old host still works.**
 | `detect_ui_mode` poll window | ~8 s | skipped |
 | crop selector cascade | ~24 s | skipped |
 | `await_url_settled` | 4018 ms | **0 ms** |
-| **time to exit 36** | **~36 s** | **0 ms** |
+| **time to exit 36** (isolated probe) | ~36 s | **0 ms** |
+| **time to exit 36** (real CLI run) | ~57 s | **~57 s — UNCHANGED, see the correction above** |
 | locale on migrated origin | `null` (and demoted a learned locale) | **`en`** recovered from `<html lang>` |
 
-`ui_driver.migrated_host_bail` is logged, so the fast path is observable rather than inferred.
+~~`ui_driver.migrated_host_bail` is logged, so the fast path is observable rather than inferred.~~
+**Retracted.** It is logged by the isolated probe and by nothing on the CLI route — the field
+timeline has no such event. Observability of a path you did not exercise is not observability.
 
 ## Layer 2 — no regression on the old host (full generation, exit 0)
 

gflow_cli-0.66.3/docs/LIVE_VERIFICATION_v0.66.2.md

@@ -0,0 +1,221 @@
+# Live Verification — v0.66.2 (the migrated-host gate actually fires; the locale cache stops lying)
+
+**Date:** 2026-09-03 · **Account:** ffroliva@gmail.com · **Platform:** Windows 11, Chrome strategy
+**Credits spent:** **0** — two Imagen images (images are credit-free) plus 72 read-only navigations.
+
+## What had to be proven, and the honest constraint
+
+This release fixes defects that v0.66.1's *own* verification missed, so the bar for it is higher
+than usual: **v0.66.1 measured `get_ui_driver` in isolation on an already-migrated page and
+reported `0 ms`, which was true of the probe and false of every CLI run.** See the correction at
+the top of [LIVE_VERIFICATION_v0.66.1](LIVE_VERIFICATION_v0.66.1.md).
+
+**The constraint this time is the inverse of last time.** Google's rollout flapped *back* on both
+maintainer accounts during this work:
+
+| profile | navigations | landed migrated | landed old host |
+|---|---|---|---|
+| `ffroliva` | 60 | **0** | 60 |
+| `denon82` | 12 | **0** | 12 |
+
+Measured with `scripts/dev/measure_migrated_host_flip.py` across three sweeps on `ffroliva` and
+one on `denon82`, over ~2 hours (the raw per-navigation record is in the `scripts/dev/_spike_out/` JSON the
+instrument writes; the planning artifacts were consolidated at release per the repo's
+spec-to-memory convention).
+
+So **the migrated path was not reachable from this machine and is NOT live-verified here.** It is
+unit-tested and A/B-controlled only. That is stated in the NOT-verified section below rather than
+folded into the green column — which is precisely the mistake being corrected.
+
+What *is* live-verifiable is the property that matters most today: **the old host, which 100% of
+real loads currently take, is unaffected** — and the locale behaviour, which is fully exercisable.
+
+## Layer 1 — the locale cache stops conflating two different questions
+
+`profile_ffroliva/.gflow_locale` was **empty** — `NOT_REDIRECTED` — before the run. Under v0.66.1
+that state returned before `_resolve_account_locale`, so the `<html lang>` recovery #643 shipped
+could never run on it.
+
+```
+cache before:  ''                                                    (NOT_REDIRECTED)
+client.account_locale_resolved   locale=en  source=html_lang
+client.account_locale_cached     locale=en  settle_skipped=true
+cache after:   ''                                                    (NOT_REDIRECTED — unchanged)
+```
+
+Three things at once, all measured:
+
+1. **The locale is recovered from the document**, not the URL — `source=html_lang`. The latch no
+   longer blocks it.
+2. **The settle stays skipped** (`settle_skipped=true`). The #587 win is intact — which is why
+   deleting the early return outright was rejected: on this account "not redirected" is a *true*
+   observation, confirmed 60/60.
+3. **The cached state is unchanged.** This is the correction the council forced (see below): the
+   cache answers *"does Flow redirect this account?"*, and a `<html lang>` attribute is no
+   evidence of a redirect — every account has one.
+
+### The regression the council caught, and the measurement that proved it
+
+The first cut of this fix folded the recovered locale into the cache. Two independent reviewers
+(D1 correctness, D4 tests) flagged it; `scripts/dev/measure_locale_probe.py` then reproduced it
+without being asked:
+
+```
+BEFORE:  ffroliva  warm  7.41s   cached 'en'    !! warm arm slower than cold — investigate
+                                 transport.url_settle_gave_up  timeout_ms=4000.0   (x2)
+
+AFTER:   ffroliva  cold  6.99s   cached '?'
+         ffroliva  warm  2.66s   cached ''      settle off, locale still 'en'
+```
+
+Writing the locale in flipped `cached != NOT_REDIRECTED`, which turned the settle back on
+permanently and cost the full 4 s `URL_SETTLE_TIMEOUT_MS` on every future bootstrap — the exact
+cost #587 exists to remove.
+
+**Tracing it found a live defect in v0.66.1 itself, present on `develop` today.** #643's
+`<html lang>` fallback returns a segment for an account Flow serves *bare* and never redirects, and
+`next_locale_state` recorded that as evidence of a redirect. So **any** non-redirecting account
+with a `lang` attribute has been paying 4 s per bootstrap since v0.66.1 — no latch required. The
+fix folds only the **URL-derived** segment into the state; the lang-derived one is used in-process
+for URL building and never persisted.
+
+## Layer 2 — the risk this fix introduces, exercised rather than assumed
+
+Recovering the locale changes what gflow navigates to: this profile previously built the **bare**
+`labs.google/fx/tools/flow/project/<id>` and now builds `/fx/en/tools/flow/project/<id>`. If `en`
+were the wrong segment, every navigation would bounce.
+
+```
+ui_automation.entering_existing_project  url=https://labs.google/fx/en/tools/flow/project/c5550ed7-…
+ui_automation.url_stable_after_goto      same URL, +549 ms, settle_skipped=false
+ui_driver.ui_mode.attempt_exit_agent     +507 ms
+ui_driver.bound                          mode=classic
+```
+
+`url_stable_after_goto`, **not** `url_redirected_after_goto`: Flow accepted the segment and did
+not bounce it. Confirmed on both live runs.
+
+## Layer 3 — no regression on the old host: full generation, exit 0, twice
+
+```
+run 1 (pre-council-fix build)   EXIT=0   768×1376 JPEG · 427.8 KB · ff d8 ff
+run 2 (final build)             EXIT=0   768×1376 JPEG · 413.5 KB · ff d8 ff
+```
+
+Real images generated and written; `ui_driver.bound  mode=classic` on both; no
+`ui_driver.migrated_host_bail` event on either — correct, the host is `labs.google`.
+
+**On wall-clock:** run 1 took 36.6 s and run 2 took 86 s, and **neither number is evidence about
+this diff.** Run 2's extra time is Flow's own generation latency plus a 34.4 s
+`browser_teardown.context_close_error` — a bounded Chrome-close timeout at `api/_engine.py:159`
+that fires *after* all generation work, is already handled (warning → force close → exit 0), and
+is untouched by this branch. A single-run timing delta sits well inside that variance, so the
+"adds no wait" claim rests on the A/B control and on code shape (`page.url` is a cached property;
+`flow_host_kind` is one `urlsplit` plus a dict lookup; `_media_panel_present` uses `.count()` and
+does not wait) — **not** on the totals. Claiming "faster" from these runs would repeat exactly the
+error this release corrects.
+
+## Layer 4 — offline
+
+- Tests written **red first**: 4 red for the locale latch, 4 red for the host gate, before any
+  production change.
+- **A/B controls**, re-derived independently by a council reviewer with its own harness:
+  neutering `raise_if_migrated` fails **exactly 7** and **no** old-host test; restoring the
+  pre-#639 early return fails **exactly 5**. Nothing passes vacuously in either direction.
+- The council's must-fix added two more tests that would have caught the regression it found:
+  a two-bootstrap cycle (one bootstrap cannot observe a cache flipping the settle back on), and
+  a lang-only-locale case pinning that a `lang` attribute is not evidence of a redirect.
+- `ruff check` / `ruff format --check` clean on `src tests`; `pyright src` at the `develop`
+  baseline; repo hygiene, doc links, website-docs PII, and the `website/docs` mirror all green.
+
+## Layer 5 — the MCP surface
+
+No CLI leaf, option, or request-DTO field changed, so `tests/mcp/test_cli_parity.py` needs no new
+mapping and `worker/codec.py` no new payload key — the fix is in the transport both surfaces
+share (independently traced by the parity reviewer: `worker/daemon.py` and `mcp/tools.py` both
+construct the same `FlowApiClient`). What *is* MCP-specific is the queue envelope, different code
+from the CLI's `--json` path, carrying the flag the reporter's orchestrator actually reads:
+
+```
+queue error record:  exit_code = 36,  retryable = True
+```
+
+Pinned by `tests/worker/test_daemon.py::test_migrated_host_error_crosses_the_queued_path`. Noted
+honestly: that test pins the write side; the `wait=True` read-back in `mcp/tools.py` is generic
+code exercised by its neighbours, so the round trip is pinned end-to-end only by construction.
+
+`docs/MCP.md` listed the retryable classes by name and omitted three of them
+(`FlowHostMigratedError`, `UiModeUnavailableError`, `SyncPartialError`); the list now matches
+`errors.RETRYABLE_ERRORS` exactly, mirror regenerated.
+
+Side effect: `mcp/tools.py` builds project editor links from `account_locale_for()`, which reads
+the *cached* state. Because the lang-derived locale is deliberately not persisted, those links are
+unchanged by this branch — the earlier claim that they become "account-correct" was wrong and is
+retracted here rather than shipped.
+
+## Layer 6 — the migrated path, verified independently by the reporter
+
+Everything above was measured on maintainer accounts that had flapped back to the old host. The
+migrated path was verified by [@maipmacrothorax-75](https://github.com/maipmacrothorax-75) on a
+permanently-migrated account — branch installed from git, reverted afterwards, zero credits,
+posted to [#639](https://github.com/ffroliva/gflow-cli/issues/639).
+
+| | v0.66.1 | branch, before the `mode_control` guard | v0.66.2 |
+|---|---|---|---|
+| total, per run | 57.0 / 58.3 / 57.0 s | 19.4 / 15.0 / 14.9 s | **4.08 – 4.26 s** |
+| `ui_driver.migrated_host_bail` | **absent** | present, `at=detect_ui_mode` | present, **`at=mode_control`** |
+| `mode_control.ensure_media_incomplete` | every run | every run | **never** |
+| `ui_automation_video.selector_probe_failed` | every run | never | never |
+
+Typical v0.66.2 timeline on a migrated load:
+
+```
+2.82  ui_automation.url_stable_after_goto
+3.44  ui_driver.migrated_host_bail   at=mode_control   (+0.62)
+4.09  error_raised                   FlowHostMigratedError, exit 36, retryable
+```
+
+**~0.6 s from the host becoming knowable to the abort**; ~4 s total, essentially browser launch
+plus navigation. Nine runs on the final build, `at=mode_control` every time.
+
+Two things this settles that no maintainer measurement could:
+
+1. **The `at=` field earned itself.** The intermediate run bailed at `detect_ui_mode`, not
+   `exit_agent_mode` — which is how the reporter identified, from the log alone, that the
+   `exit_agent_mode` guard sat *after* the ~11 s dismissal rather than before it. A late review
+   angle found the same gap independently; the log field is what made it visible from outside
+   the codebase.
+2. **57 s → 4 s is real**, and it is the difference between a caller's retry loop being viable
+   and not.
+
+**One unexplained anomaly, recorded because it was observed.** The first run after a fresh
+install ended in `error_unhandled` at 3.42 s — after `setup_shared_page`, before
+`entering_existing_project` — `exception_class: "Error"` (Playwright's base class), message
+redacted to hashes. It did not reproduce; the other 8 runs on that build were clean exit 36. A
+one-off that cannot be reproduced is not evidence, and it is here only so a second sighting has
+something to match against.
+
+## Recorded as NOT verified rather than omitted
+
+- ~~**The migrated path firing fast.**~~ **Now verified — see Layer 6.** This entry originally
+  said unverified because 72/72 navigations *from this machine* landed on the old host. That was
+  true of this machine and false of the project: the reporter had already run it on a
+  permanently-migrated account and posted the numbers to #639 before the tag was cut, and they
+  were not read in time. Kept rather than deleted — "I could not measure it" and "nobody measured
+  it" are different claims, and this doc conflated them.
+- **Driving the migrated frontend.** Still impossible. #639 stays open; this PR says `Refs`.
+- **A non-English profile recovering live.** `denon82` is cached `"pt"` (it genuinely redirects),
+  so the lang-recovery path was exercised live only on `en`. The `pt` case is unit-tested.
+- **The `en-GB` → `en` region reduction where region is load-bearing** (`zh-Hans`/`zh-Hant`).
+  Unchanged from v0.66.1, still only two locales observed.
+- **A defect this verification found, shipped in v0.66.2 and not fixed by it.** On the reporter's
+  **pt-BR** account the locale resolves to `en`, while `document.documentElement.lang` reads `pt`
+  on both `flow.google.com/` and `flow.google.com/project/<id>`, `navigator.language` is `pt-BR`,
+  and the whole UI renders in Portuguese. The probe logs at ~1.63 s, before
+  `entering_existing_project` at ~2.31 s — early enough that it may be reading the initial HTML
+  shell before the app sets `lang`. **The mismatch is measured; the mechanism is a hypothesis and
+  was not instrumented.** This is precisely the population #643 was written for, so the
+  `<html lang>` fallback (shipped v0.66.1) can latch a locale the account does not use. Tracked
+  separately — it is not a migration bug.
+- **Full-suite coverage %.** The targeted suites ran without `--cov` (an unscoped `pytest --cov`
+  OOMs this machine); the 80% floor is enforced by CI.

gflow_cli-0.66.3/docs/LIVE_VERIFICATION_v0.66.3.md

@@ -0,0 +1,97 @@
+# Live Verification — v0.66.3 (`<html lang>` is read after hydration, not before)
+
+**Date:** 2026-09-03 · **Accounts:** `denon82` (pt), `ffroliva` (en) · **Platform:** Windows 11, Chrome strategy
+**Credits spent:** **0** — navigation and DOM reads only; nothing submits.
+
+## What had to be proven
+
+One fix ([#651](https://github.com/ffroliva/gflow-cli/issues/651)): the account locale must come
+from `<html lang>` **after** Flow's app has set it, not from the `en` shell it serves first.
+
+## Layer 1 — the defect, measured (this is what chose the design)
+
+Sampling `document.documentElement.lang` after `page.goto(wait_until="domcontentloaded")` returns,
+on a **pt** account, two consecutive loads (`scripts/dev/measure_html_lang_settle.py`):
+
+| t (ms) | `lang` | `readyState` | DOM nodes |
+|---|---|---|---|
+| 887 | `en` | interactive | 136 |
+| **1510** | `en` | **complete** | 300 |
+| 2092 | `en` | complete | 249 |
+| **2488** | **`pt`** | complete | 262 |
+| 7398 | `pt` | complete | 251 |
+
+Two negative results that mattered more than the positive one:
+
+- **`readyState` is not a hydration signal for `lang`.** It reaches `complete` a full second
+  *before* the flip. "Wait for complete, then read" — the obvious fix — would have shipped the
+  same bug with more code.
+- **DOM node count does not discriminate.** It oscillates 136 → 300 → 249 → 251 and settles
+  within 2 of its pre-flip value.
+
+Nothing cheap predicts the flip, so the fix **observes** it.
+
+## Layer 2 — the fix, on a live page (COMPONENT measurement)
+
+`scripts/dev/verify_lang_settle_fix.py`, part A. This calls the helper directly against a real
+bootstrap page — **it is a component measurement and is labelled as one.**
+
+```
+[A · COMPONENT — helper on a live page]  profile=denon82
+    naive early read : 'en'
+    _settled_lang    : 'pt'   (+638 ms)
+    verdict          : CAPTURED THE FLIP
+```
+
+## Layer 3 — the real bootstrap (END-TO-END measurement)
+
+Part B, on the account that exercises the *timeout* branch — its locale equals the `en` shell, so
+the attribute never changes:
+
+```
+client.account_locale_lang_unchanged  lang=en  waited_ms=4000  reason=TimeoutError
+client.account_locale_resolved        locale=en  source=html_lang
+```
+
+Correct answer, and the cost is visible: **the 4 s bound, once per process** (bootstrap ~2.7 s →
+~6 s on this account). That is the price of not guessing, and it is bounded. The event name makes
+"the shell value was already right" distinguishable from "we timed out" in any field log.
+
+**Layers 2 and 3 are reported separately on purpose.** Collapsing a component number into a
+user-facing claim is precisely the error corrected at the top of
+[LIVE_VERIFICATION_v0.66.1](LIVE_VERIFICATION_v0.66.1.md), and this release is not going to
+repeat it one version later.
+
+## Layer 4 — offline
+
+- Tests written red first; **A/B control**: neutering `_settled_lang` fails **exactly 3** — the
+  two new cases plus the probe-failure test, since the helper owns the error handling too.
+- `1663 passed / 3 skipped` across `tests/api`, `tests/features`, `tests/mcp`, `tests/worker`.
+- `ruff check` / `ruff format --check` clean on `src tests`; `pyright src` at the `develop`
+  baseline; repo hygiene, doc links, website-docs PII and the `website/docs` mirror all green.
+- CI on [#652](https://github.com/ffroliva/gflow-cli/pull/652): **15/15**, including the
+  SonarCloud quality gate.
+
+## Layer 5 — MCP
+
+No CLI leaf, option, or request-DTO field changed. The fix is in `FlowApiClient`, which the MCP
+worker constructs identically to the CLI, so both surfaces inherit it and no `mcp/tools.py`
+change is implied.
+
+## Recorded as NOT verified rather than omitted
+
+- **A non-`en` account on the MIGRATED origin.** The fix is proven on the old host, where the
+  race also occurs — that is what made it testable at all. The reporter's pt-BR migrated account
+  is where it originally surfaced, and it has not been re-run there since the fix.
+- **The 4 s bound against a cold first load.** One observed session had `lang` fail to flip
+  within 4 s on its first navigation, yet flip in 638 ms two seconds later. Either Flow served
+  English on that load (its URL settle also timed out, so no redirect either) or the bound is
+  short cold. Unresolved; `client.account_locale_lang_unchanged` is the signal that will tell us.
+- **The `was=pt now=?` demotion introduced in v0.66.2.** Folding only the URL-derived segment
+  means a learned `pt` drops to PROVISIONAL whenever the URL settle times out. Self-healing on
+  the next redirecting run, and the locale is re-derived per run, so nothing is permanently lost
+  — but it is the same *shape* of demotion #643 complained about and deserves a decision.
+- **Whether a wrong locale segment causes a redirect bounce** (`/fx/en/...` on a non-`en`
+  account) or merely an English UI. Only the reporter's account can settle this.
+- **Full-suite coverage %.** Run without `--cov` (an unscoped `pytest --cov` OOMs this machine);
+  the 80% floor is enforced by CI.

{gflow_cli-0.66.1/website → gflow_cli-0.66.3}/docs/MCP.md

@@ -127,7 +127,13 @@ marks a transient failure a scheduler can re-run without operator intervention
 WAF/reCAPTCHA bounce (`WafRejectionError`), rate-limit (`RateLimitError`),
 transport timeout (`TransportTimeoutError`), network blip (`NetworkError`), a
 dropped browser session (`BrowserSessionClosedError`), a Flow web-app crash
-(`FlowAppError`), and an agentic-cohort flap (`FlowAgentUiError`). Everything
+(`FlowAppError`), an agentic-cohort flap (`FlowAgentUiError`), a page load served
+by the migrated `flow.google.com` frontend (`FlowHostMigratedError`,
+[#639](https://github.com/ffroliva/gflow-cli/issues/639) — the rollout flaps per
+page load, so a retry often lands the frontend gflow can drive), an unreachable
+UI arm (`UiModeUnavailableError`), and a partially-completed sync
+(`SyncPartialError`). That list is the whole of `errors.RETRYABLE_ERRORS`.
+Everything
 else (auth, content-policy, configuration, security) is terminal
 (`retryable: false`): retrying the identical request fails the same way. This
 flag is the **same shared classification** the CLI `--json` payload and the