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

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

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

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

@@ -7,6 +7,42 @@ 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
@@ -3784,7 +3820,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.66.2...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

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

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

@@ -162,6 +162,8 @@ 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.

{gflow_cli-0.66.2 → gflow_cli-0.66.3}/docs/LIVE_VERIFICATION_v0.66.2.md

@@ -153,18 +153,69 @@ the *cached* state. Because the lang-derived locale is deliberately not persiste
 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.** 72/72 navigations landed on the old host, so no migrated load
-  was available to time. The gate is proven by unit tests and A/B control, **not** by a live run.
-  The instrument is committed; the honest next step is a later flap or a run from the reporter's
-  permanently-migrated account.
-- **The achieved time-to-exit-36 on a real migrated run.** Unmeasured, and deliberately not
-  estimated. The design does not depend on it — the guard sits where the run already blocks.
+- ~~**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.2 → gflow_cli-0.66.3}/docs/PROJECT_STATUS.md

@@ -4,6 +4,40 @@
 
 ## Current release
 
+**v0.66.3 — alpha.** **gflow was reading Flow's locale off the `en` shell it serves before the
+app rewrites it, so every account whose URL could not answer came back English.**
+
+Flow serves an `en` shell and sets the real `<html lang>` during hydration. The single early read
+added by [#643](https://github.com/ffroliva/gflow-cli/issues/643) therefore returned `en` — for
+exactly the accounts #643 existed to help, the ones whose 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 was right, and it **reproduces on the old host** — so this was never a migration bug.
+Measured, two consecutive loads:
+
+| t (ms) | `lang` | `readyState` |
+|---|---|---|
+| 887 | `en` | interactive |
+| **1510** | `en` | **complete** |
+| 2092 | `en` | complete |
+| **2488** | **`pt`** | complete |
+
+The useful part of that table is the negative result: **`readyState` 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. DOM node count oscillates and does not discriminate either. Nothing
+cheap predicts the flip, so the resolver now **observes** it — read, bounded-wait for a change,
+re-read — and treats a timeout as an *answer* (the shell value was already correct) rather than a
+failure, logged distinctly so the field can tell the two apart.
+
+Verification: [LIVE_VERIFICATION_v0.66.3](LIVE_VERIFICATION_v0.66.3.md). Proven at zero credits:
+the helper captures the flip live (`en` → `pt`, +638 ms) and a real bootstrap on an `en` account
+resolves correctly at the cost of the 4 s bound. Those two are reported **separately**, because
+collapsing a component measurement into a user-facing claim is the mistake v0.66.1 made and
+v0.66.2 corrected.
+
+<details><summary>v0.66.2 — the fast-fail that had never fired, and a locale cache answering the wrong question</summary>
+
 **v0.66.2 — alpha.** **The fast-fail v0.66.1 announced had never once fired, and the locale
 cache was answering a question nobody asked it.**
 
@@ -42,11 +76,21 @@ day it shipped).
 Still not drivable — #639 stays open for that.
 
 Verification: [LIVE_VERIFICATION_v0.66.2](LIVE_VERIFICATION_v0.66.2.md). The old host is proven
-live at zero credits (**exit 0**, real 768x1376 JPEG, twice). **The migrated path is recorded as
-NOT verified**: the rollout flapped back mid-work and 72/72 navigations landed on `labs.google`,
-so the gate rests on unit tests and A/B controls, and **no time-to-exit-36 is claimed anywhere**.
-Given this release exists because a number was reported from the wrong entrypoint, inventing a
-replacement would have repeated the error.
+live at zero credits (**exit 0**, real 768x1376 JPEG, twice). The **migrated** path — which no
+maintainer account could reach, because the rollout flapped back mid-work — was verified by
+[@maipmacrothorax-75](https://github.com/maipmacrothorax-75) on a permanently-migrated account:
+**57 s → 4.08–4.26 s**, `ui_driver.migrated_host_bail` present with `at=mode_control` on all nine
+runs, and the crop cascade and agent dismissal both gone. That measurement was posted to #639
+before the tag was cut and was not read in time, so the shipped verification doc understated its
+own result; the correction is recorded there rather than quietly applied.
+
+**Found by that same verification and NOT fixed here:** on a pt-BR account the locale resolves
+`en` while both pages serve `<html lang="pt">` — the probe appears to read before the app sets
+the attribute. That is the population #643 was written for, so the `<html lang>` fallback can
+latch a locale the account does not use. Tracked separately; it is not a migration bug.
+
+
+</details>
 
 <details><summary>v0.66.1 — a fast-fail that never fired (superseded by v0.66.2)</summary>
 

{gflow_cli-0.66.2 → gflow_cli-0.66.3}/pyproject.toml

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

gflow_cli-0.66.3/scripts/dev/measure_html_lang_settle.py

@@ -0,0 +1,81 @@
+"""Does `<html lang>` change between goto-return and hydration, and what signals it? (#651)
+
+The reporter measured `locale=en` on a pt-BR account whose pages serve
+`<html lang="pt">`, and offered the mechanism as an explicit guess: the probe reads
+the initial HTML shell before the app sets `lang`.
+
+Run 1 confirmed the race on the OLD host (no migrated account needed):
+`en` until ~1.9 s, `pt` from ~2.9 s.
+
+This run adds `readyState` and a DOM-node count alongside `lang`, to find a
+*hydration signal* the fix can key on instead of a guessed timing constant.
+
+Zero credits: navigation only.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from time import perf_counter
+from typing import Any
+
+sys.path.insert(0, r"C:\development\github\gflow-cli\src")
+sys.path.insert(0, r"C:\development\github\gflow-cli\scripts\dev")
+
+from gflow_cli.api import routes  # noqa: E402
+from gflow_cli.api.routes import locale_segment_from_lang_attr  # noqa: E402
+
+from _spike_common import build_client, resolve_profile_dir  # noqa: E402, isort: skip
+
+SAMPLES_MS = [0, 200, 400, 600, 900, 1200, 1600, 2000, 2400, 2800, 3200, 4000, 6000]
+
+_SNAP = """() => ({
+  lang: document.documentElement.lang || '',
+  ready: document.readyState,
+  nodes: document.querySelectorAll('*').length
+})"""
+
+
+async def _sample(page: Any, label: str, url: str) -> None:
+    t0 = perf_counter()
+    await page.goto(url, wait_until="domcontentloaded", timeout=45_000)
+    rows: list[tuple[int, str, str | None, str, int]] = []
+    prev = 0
+    for target in SAMPLES_MS:
+        if target - prev > 0:
+            await page.wait_for_timeout(target - prev)
+        prev = target
+        try:
+            snap = await page.evaluate(_SNAP)
+        except Exception as exc:  # noqa: BLE001
+            snap = {"lang": f"<{type(exc).__name__}>", "ready": "?", "nodes": -1}
+        rows.append(
+            (
+                round((perf_counter() - t0) * 1000),
+                snap["lang"],
+                locale_segment_from_lang_attr(snap["lang"]),
+                snap["ready"],
+                snap["nodes"],
+            )
+        )
+
+    print(f"\n--- {label}  {url}")
+    print(f"{'t_ms':>7}  {'lang':<8} {'seg':<8} {'readyState':<12} {'DOM nodes'}")
+    for ms, lang, seg, ready, nodes in rows:
+        print(f"{ms:>7}  {lang!r:<8} {seg!r:<8} {ready:<12} {nodes}")
+
+
+async def _main(profile: str) -> int:
+    pdir = resolve_profile_dir(profile)
+    async with build_client(pdir) as client:
+        page = client._page  # noqa: SLF001 — dev instrument
+        assert page is not None
+        print(f"profile={profile}  client-resolved locale={client._account_locale!r}")  # noqa: SLF001
+        await _sample(page, "bootstrap", routes.EDITOR_BOOTSTRAP_URL)
+        await _sample(page, "bootstrap (2nd load)", routes.EDITOR_BOOTSTRAP_URL)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(asyncio.run(_main(sys.argv[1] if len(sys.argv) > 1 else "denon82")))

gflow_cli-0.66.3/scripts/dev/verify_lang_settle_fix.py

@@ -0,0 +1,75 @@
+"""Live proof for #651 — `<html lang>` is read after hydration, not before.
+
+Two measurements, deliberately kept distinct, because conflating them is the error
+this whole line of work exists to correct (see the correction block atop
+``docs/LIVE_VERIFICATION_v0.66.1.md``):
+
+**A — the helper, exercised against a live page.** ``_settled_lang`` is called
+directly on a real bootstrap page of a **pt** account. This proves the flip is
+captured: the naive early read returns ``en``, the fixed read returns ``pt``. It is
+a component measurement and is labelled as one.
+
+**B — the real bootstrap, end to end.** ``FlowApiClient.__aenter__`` on a latched
+profile whose locale *equals* the shell default, which is the case that pays the
+settle timeout. This is the user-visible cost, on the path a user actually takes.
+
+Zero credits: navigation only.
+
+    uv run python scripts/dev/verify_lang_settle_fix.py denon82 ffroliva
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from pathlib import Path
+from time import perf_counter
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "src"))
+
+from gflow_cli.api import routes  # noqa: E402
+
+from _spike_common import build_client, resolve_profile_dir  # noqa: E402, isort: skip
+
+
+async def _component_check(profile: str) -> None:
+    """A — does the helper capture the post-hydration value on a live page?"""
+    async with build_client(resolve_profile_dir(profile)) as client:
+        page: Any = client._page  # noqa: SLF001 — dev instrument
+        await page.goto(routes.EDITOR_BOOTSTRAP_URL, wait_until="domcontentloaded", timeout=45_000)
+
+        naive = await page.evaluate("() => document.documentElement.lang || ''")
+        t0 = perf_counter()
+        settled = await client._settled_lang(page)  # type: ignore[attr-defined]  # noqa: SLF001
+        ms = round((perf_counter() - t0) * 1000)
+
+        print(f"\n[A · COMPONENT — helper on a live page]  profile={profile}")
+        print(f"    naive early read : {naive!r}")
+        print(f"    _settled_lang    : {settled!r}   (+{ms} ms)")
+        print(f"    verdict          : {'CAPTURED THE FLIP' if settled != naive else 'no flip seen'}")
+
+
+async def _end_to_end(profile: str) -> None:
+    """B — what a real bootstrap costs on the account that pays the timeout."""
+    t0 = perf_counter()
+    async with build_client(resolve_profile_dir(profile)) as client:
+        ms = round((perf_counter() - t0) * 1000)
+        print(f"\n[B · END-TO-END — real bootstrap]  profile={profile}")
+        print(f"    resolved locale  : {client._account_locale!r}")  # noqa: SLF001
+        print(f"    __aenter__ total : {ms} ms")
+
+
+async def _main(flip_profile: str, shell_profile: str) -> int:
+    await _component_check(flip_profile)
+    await _end_to_end(shell_profile)
+    print(
+        "\nA is a component measurement; B is the user path. Reporting A's number as"
+        "\nthe user-visible one is precisely the v0.66.1 mistake."
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    args = sys.argv[1:] or ["denon82", "ffroliva"]
+    raise SystemExit(asyncio.run(_main(args[0], args[1])))

{gflow_cli-0.66.2 → gflow_cli-0.66.3}/src/gflow_cli/__init__.py

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

{gflow_cli-0.66.2 → gflow_cli-0.66.3}/src/gflow_cli/api/client.py

@@ -22,7 +22,7 @@ import time
 import uuid
 from dataclasses import replace as _dataclass_replace
 from datetime import datetime
-from typing import TYPE_CHECKING, Any, NoReturn, Self, TypeVar, cast
+from typing import TYPE_CHECKING, Any, ClassVar, NoReturn, Self, TypeVar, cast
 from urllib.parse import quote, urlsplit, urlunsplit
 
 import structlog
@@ -849,11 +849,7 @@ class FlowApiClient:
         # returns None and `next_locale_state` DEMOTES an already-learned locale
         # to PROVISIONAL (measured: a pt account lost its "pt" on every migrated
         # load). Best-effort: a probe failure must never break navigation.
-        try:
-            lang = await page.evaluate("() => document.documentElement.lang || ''")
-        except Exception as exc:  # noqa: BLE001 - observation only
-            logger.info("client.account_locale_lang_probe_failed", error=type(exc).__name__)
-            lang = None
+        lang = await self._settled_lang(page)
         segment = routes.locale_segment_from_lang_attr(lang)
         if segment is not None:
             logger.info("client.account_locale_resolved", locale=segment, source="html_lang")
@@ -861,6 +857,66 @@ class FlowApiClient:
         logger.info("client.account_locale_unresolved", last_url=settled)
         return None, None
 
+    #: How long to wait for `<html lang>` to leave the server-default shell value
+    #: (#651). Measured on a pt account, two consecutive loads: the attribute reads
+    #: `en` until ~1.9 s and flips to `pt` at 2.26 / 2.49 s. 4 s leaves margin
+    #: without being open-ended; a slower network could still exceed it, which the
+    #: `lang_unchanged` event makes visible rather than silent.
+    _LANG_SETTLE_TIMEOUT_MS: ClassVar[float] = 4_000.0
+
+    async def _settled_lang(self, page: Any) -> str | None:
+        """Read ``<html lang>`` only after hydration has had a chance to set it (#651).
+
+        Flow serves an **`en` shell** and the app rewrites ``lang`` during
+        hydration, so a single early read returns ``en`` for every account. That is
+        not a migrated-origin quirk — it was measured on the OLD host:
+
+        ===========  ==========  ==============
+        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" is
+        wrong. The DOM node count oscillates (136 → 300 → 249 → 251) and does not
+        discriminate either. Nothing cheap predicts the flip, so this observes it.
+
+        Cost: an account whose real locale IS the shell default never changes the
+        attribute and pays the full timeout once per process. That is the price of
+        not guessing, and it is bounded; the alternative shipped a wrong locale for
+        every account whose URL could not answer.
+        """
+        try:
+            first = await page.evaluate("() => document.documentElement.lang || ''")
+        except Exception as exc:  # noqa: BLE001 - observation only
+            logger.info("client.account_locale_lang_probe_failed", error=type(exc).__name__)
+            return None
+        try:
+            await page.wait_for_function(
+                "initial => (document.documentElement.lang || '') !== initial",
+                arg=first,
+                timeout=self._LANG_SETTLE_TIMEOUT_MS,
+            )
+            after = await page.evaluate("() => document.documentElement.lang || ''")
+        except Exception as exc:  # noqa: BLE001 - a timeout is an ANSWER, not a failure
+            # Either the account's locale genuinely equals the shell default, or the
+            # page never hydrated within the window. Both leave the first read as the
+            # best available answer — which is exactly the pre-#651 behaviour, so this
+            # branch can never be worse than what it replaces.
+            logger.info(
+                "client.account_locale_lang_unchanged",
+                lang=first,
+                waited_ms=self._LANG_SETTLE_TIMEOUT_MS,
+                reason=type(exc).__name__,
+            )
+            return first
+        logger.info("client.account_locale_lang_settled", was=first, now=after)
+        return after
+
     async def _launch_persistent_context(self, kwargs: JsonObject) -> BrowserContext:
         """Launch the persistent context; translate a launch-time crash into ProfileLockedError."""
         assert self._pw is not None