gflow-cli 0.42.0__tar.gz → 0.44.0__tar.gz

gflow_cli-0.44.0/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "gflow-cli",
+  "interface": {
+    "displayName": "gflow-cli"
+  },
+  "plugins": [
+    {
+      "name": "gflow",
+      "source": {
+        "source": "local",
+        "path": "./"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}

gflow_cli-0.44.0/.codex-plugin/plugin.json

@@ -0,0 +1,34 @@
+{
+  "name": "gflow",
+  "version": "0.44.0",
+  "description": "Reusable development and operations workflows for gflow-cli",
+  "author": {
+    "name": "Flavio Oliva",
+    "url": "https://github.com/ffroliva"
+  },
+  "homepage": "https://github.com/ffroliva/gflow-cli",
+  "repository": "https://github.com/ffroliva/gflow-cli",
+  "license": "MIT",
+  "keywords": [
+    "gflow-cli",
+    "codex",
+    "google-flow"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "gflow-cli",
+    "shortDescription": "Develop, validate, review, and operate gflow-cli.",
+    "longDescription": "Project workflows for planning, validation, issue handling, reviews, releases, and Google Flow CLI operations.",
+    "developerName": "Flavio Oliva",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Interactive",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/ffroliva/gflow-cli",
+    "defaultPrompt": [
+      "Show the current gflow-cli task with $gflow:status.",
+      "Run the gflow-cli quality gates with $gflow:check."
+    ]
+  }
+}

{gflow_cli-0.42.0 → gflow_cli-0.44.0}/.env.template

@@ -160,9 +160,18 @@
 # GFLOW_CLI_PROJECT_NAME=
 
 # -----------------------------------------------------------------------------
-# Debugging (opt-in only — both can expose secrets, see docs/CONFIGURATION.md)
+# Debugging (see docs/CONFIGURATION.md; HAR/traceback are opt-in and can
+# expose secrets)
 # -----------------------------------------------------------------------------
 
+# Automatic private incident bundles (DEFAULT: true). On relevant operational
+# failures (Flow app crash, UI drift, transport timeout, WAF/network errors,
+# profile-lock contention) gflow writes a bounded diagnostic bundle under
+# <GFLOW_CLI_HOME>/incidents/. Automatic JSON is allowlisted structural
+# metadata only; screenshots live under sensitive/ and must be reviewed
+# before sharing. Nothing is ever uploaded. Set false to disable.
+# GFLOW_CLI_INCIDENT_CAPTURE=true
+
 # Captures full Playwright network traffic (requests, responses, headers,
 # cookies) to this HAR file for the session. SECURITY: a HAR file contains
 # live auth cookies and bearer tokens -- never share one publicly.

{gflow_cli-0.42.0 → gflow_cli-0.44.0}/.github/workflows/ci.yml

@@ -63,6 +63,12 @@ jobs:
       - name: Documentation links
         run: uv run python scripts/ci/check_doc_links.py
 
+      - name: Website docs PII guard (no private identifiers in the published mirror)
+        run: uv run python scripts/ci/check_website_docs_pii.py
+
+      - name: Website docs mirror in sync (regenerate-and-diff)
+        run: uv run python scripts/ci/generate_website_docs.py --check
+
       - name: Lint
         run: uv run ruff check src tests
 

{gflow_cli-0.42.0 → gflow_cli-0.44.0}/AGENTS.md

@@ -39,6 +39,7 @@ Run these gates in order before every commit:
 $env:PYTHONUTF8=1
 uv run python scripts/ci/check_repo_hygiene.py
 uv run python scripts/ci/check_doc_links.py
+uv run python scripts/ci/check_website_docs_pii.py
 uv run ruff check src tests
 uv run ruff format --check src tests
 uv run pyright src
@@ -108,7 +109,21 @@ and must be resolvable by ANY agent via this file. Vendor directories hold thin
 only (`.claude/commands/gflow/*.md` are pointers into `skills/`); never put protocol
 content in a vendor directory.
 
-**Cursor / Aider / Codex / Antigravity (`agy`):** paste or include the relevant `SKILL.md` in your system context. Note: in the `agy` TUI prompt, custom slash commands (e.g. `/gflow:pr-council-review`) are blocked by the TUI's command parser. Type them as plain text without the leading slash (e.g. `gflow:pr-council-review`, `gflow:branch-review`, or `gflow:check`) to trigger the corresponding agent skill workflow.
+**Codex CLI / desktop app:** install the repo's skills-only plugin from the repository root,
+then start a new session:
+
+```powershell
+codex plugin marketplace add .
+codex plugin add gflow@gflow-cli
+```
+
+Invoke skills with Codex's `$` syntax, for example `$gflow:status`, `$gflow:check`, or
+`$gflow:pr-council-review`. Codex reserves slash commands for its own command surface; the
+Claude Code spelling `/gflow:*` is therefore intentionally not reproduced. The Codex IDE
+extension does not currently load plugins, so IDE-only users should include the relevant
+`skills/<name>/SKILL.md` directly.
+
+**Cursor / Aider / Antigravity (`agy`):** paste or include the relevant `SKILL.md` in your system context. Note: in the `agy` TUI prompt, custom slash commands (e.g. `/gflow:pr-council-review`) are blocked by the TUI's command parser. Type them as plain text without the leading slash (e.g. `gflow:pr-council-review`, `gflow:branch-review`, or `gflow:check`) to trigger the corresponding agent skill workflow.
 **Claude Code:** the `/gflow:` slash commands in `.claude/commands/gflow/` are auto-discovered when the project is open — no extra setup needed. To register a skill globally, copy the command file to `~/.claude/commands/`.
 **Custom agents:** fetch `skills/gflow-cli/SKILL.md` into your knowledge base before answering gflow questions.
 

{gflow_cli-0.42.0 → gflow_cli-0.44.0}/CHANGELOG.md

@@ -7,6 +7,165 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.44.0] — 2026-07-26
+
+### Added
+
+- **Dual-Side Project Naming & Management (`gflow project`)** (#381). Added
+  `gflow project` subcommand group (`list`, `show`, `rename`, `create`),
+  `--project-name` / `--project-title` options across `gflow image` and `gflow video`
+  generation commands, prompt slugging for scratch projects, and dual-side title sync
+  updating Google Flow's tRPC server/UI and local SQLite catalog in lockstep.
+- **Namespaced Codex project skills.** The canonical workflows under `skills/`
+  now ship as a repo-local, skills-only Codex plugin. Register and install it
+  with `codex plugin marketplace add .` followed by
+  `codex plugin add gflow@gflow-cli`, then invoke workflows such as
+  `$gflow:status`, `$gflow:check`, and `$gflow:pr-council-review` in a new
+  Codex CLI or desktop-app session. Claude Code's `/gflow:*` commands and the
+  agent-agnostic skill files remain unchanged.
+- **`gflow data errors` — bounded retention + export for failed-operation
+  history** (#345). `gflow data errors export [--older-than AGE] [-o FILE]`
+  dumps failed operations as JSONL (unbounded, newest-first) for offline
+  archival — also closing the export path deferred from #341. `gflow data
+  errors prune --older-than AGE [--dry-run]` deletes failures older than AGE
+  (`90d` / `24h` / `30m`); `--older-than` is **required** and there is no
+  automatic/background pruning — deletion is always an explicit operator
+  action. Both honor `--profile` and the exit-16 `DataStoreError` convention.
+
+### Fixed
+
+- **`gflow character create` safely activates the current Create-Body
+  composer.** Flow can autosave the body triptych over the stored portrait
+  prompt when the mode switch has not settled (observed live 2026-07-25 on
+  0.43.0). Current Flow reuses one Slate editor and exposes Create Body through
+  the locale-independent `accessibility_new` icon beside the portrait image;
+  gflow now clicks that scoped mode control, requires a new generated-face
+  reference chip to mount, and verifies the shared editor owns focus **before
+  any clearing or typing**. Readback failures abort before submit. The older
+  `add_2`/second-box cohort remains supported through its count-rise gate.
+  Post-type isolation still aborts before the credited submit. Live DOM
+  evidence and the one-box failure were captured on 2026-07-26. Face-only
+  creates are unchanged.
+
+- **Profile-lock remediation message** now names the real cause and recovery.
+  `ProfileLockedError` (exit 11) previously told operators to "wait for it to
+  finish" — implying an unbounded wait — and to hunt for a `gflow`/Chrome
+  process. In practice a blocking lock is a kernel *advisory* lock held by a
+  **live** process (often a `python.exe` a `chrome.exe` scan misses); the OS
+  releases it the instant the holder dies, so a leftover lock *file* never
+  blocks acquisition. The message now points to the recorded owner PID
+  (surfaced locally since v0.43.0) and says to just retry when nothing is
+  running. The lock itself is unchanged — auto-reclaim was considered and
+  rejected as unsafe (an unlink→new-inode race could put two browsers on one
+  profile, the exact corruption the lease prevents). Refs #370.
+
+## [0.43.0] — 2026-07-23
+
+### Added
+
+- **Private incident diagnostics** (`GFLOW_CLI_INCIDENT_CAPTURE`, default
+  **on**). Relevant operational failures — Flow app crashes, agentic-cohort /
+  UI-mode errors, selector drift, transport timeouts, WAF/network/wire-format
+  errors, profile-lock contention, unexpected exceptions — now automatically
+  write a bounded, **private** incident bundle under
+  `<GFLOW_CLI_HOME>/incidents/`: an allowlisted `manifest.json`, structural
+  `ui.json` (ligatures/signals/overlay geometry — never raw text),
+  `network.json` + `browser.json` ring journals (host categories, canonical
+  routes, status codes, text lengths — never prompts/tokens/cookies/bodies/
+  signed URLs), and a `sensitive/screenshot.png` for UI-state failures that
+  every surface marks review-before-sharing. Nothing is ever uploaded; remote
+  MCP/HTTP/worker error envelopes carry only an opaque `{id, capture_status}`
+  while the local CLI prints the bundle path. Retention is bounded
+  (50 bundles / 250 MiB) and validates ownership before pruning. Raw HAR
+  stays separate and opt-in; the manifest's `har_state` now reports honestly
+  whether the session's HAR demonstrably finalized. See
+  [DEBUGGING § Automatic incident bundles](docs/DEBUGGING.md#automatic-incident-bundles).
+  Refs #369, #370, #174, #183.
+- **Profile-lock owner evidence.** `ProfileLockedError` contention now
+  surfaces the recorded lease owner's PID and observed start time locally
+  (never in remote envelopes or logs; identities are per-command HMACs, never
+  the raw owner token). The lock-file layout is v1-versioned: byte 0 is the
+  kernel-locked sentinel and metadata starts at offset 1, so Windows
+  contenders can read it while the lock is held (legacy byte-0 files degrade
+  to "evidence unavailable"). The kernel lock remains authoritative — no
+  reclaim, unlink, or PID kill is ever performed from metadata. Refs #370.
+- **UI-drift debug engine** (`capture_ui_diagnostics`). On a `mode_switch_trigger`
+  failure, gflow dumps the composer's **structural** DOM signature — the
+  Material-Symbols ligature inventory, `crop_*` presence, textbox count, and
+  bounded overlay geometry — to a JSON alongside a **full-page** screenshot,
+  so a Flow frontend change is diagnosable from one artifact instead of a
+  bare (often black) viewport shot. Consolidated onto the incident-bundle
+  engine: the earlier in-development raw URL/title/body-text fields were
+  removed before release. (#183)
+- **`website/docs/` PII-leak CI guard** (`scripts/ci/check_website_docs_pii.py`).
+  The published mkdocs mirror under `website/docs/` is an anonymized copy of
+  canonical `docs/`; this new gate fails CI (and runs in `/gflow:check`) if a
+  known private identifier — `denon82`, the OS username `ffrol`, a real
+  name/email — appears in a published file, catching an anonymization miss
+  before it ships (the failure mode of #362). Public references such as
+  `github.com/ffroliva/gflow-cli` and the APP_AUTHOR path are trap-free by
+  construction, so the guard needs no allow-list.
+
+### Fixed
+
+- **Incident-capture hardening from the max-effort review** (14 confirmed
+  findings fixed pre-release): journals now stage first and page artifacts
+  share the 8s budget via a deadline, so a fully wedged renderer can no longer
+  cost the whole bundle or bypass suppression; the legacy mode-switch debug
+  dump writes structural JSON only (the unmarked full-page screenshot that
+  previously landed in the plain output dir on every ordinary run is gone —
+  the bundle's `sensitive/` screenshot is the one imagery artifact); capture
+  now also covers `generate_character_image` (which additionally gains the
+  exit-15 closed-browser mapping) and `upsample_image`, plus the common
+  stale-Chrome launch-crash contention path (#293); manifests report
+  `har_state: complete` only when the context demonstrably closed gracefully;
+  bundles staged for unexpected non-typed exceptions are now surfaced (path in
+  human output and `--json`); retention runs even when capture is disabled
+  (an opt-out no longer freezes previously captured bundles on disk), runs off
+  the event loop, and an undeletable pending bundle can no longer condemn
+  healthy ones; a Windows sharing violation during manifest finalization gets
+  a bounded retry; `browser.json` records the real JS error class
+  (`TypeError`/`ReferenceError`) instead of the constant `Error`; worker
+  daemon tasks rebind a per-task correlation id so incident ids are unique
+  and joinable to queue rows.
+- **`FlowAppError` and `FlowAgentUiError` now report `retryable: true` on
+  every machine-readable surface.** Both are documented (and presented to
+  humans) as transient/retryable, but the CLI `--json` payload said
+  `retryable: false` and the MCP / worker-queue error envelopes carried no
+  retry signal at all. The classification now lives in one shared
+  `errors.is_retryable()` consumed by CLI JSON, MCP tool envelopes, and
+  persisted worker-queue error payloads — the three surfaces can no longer
+  drift.
+- **Documentation drift corrected against the code:** `gflow image batch` docs
+  claimed generations run in parallel inside Flow (the transport is strictly
+  serial — each prompt's generation is awaited before the next submission)
+  and listed `--fail-fast` as the default (the CLI default is
+  `--continue-on-error`); the root plan still labeled the MCP server as
+  unshipped (shipped v0.21.0/v0.23.0).
+- **Flow's new media-library / agentic A/B cohort now fails cleanly.** When a
+  project opens into Flow's full-page media-library (or agentic chat) composer —
+  which has no classic `crop_*` aspect/mode control — `gflow image` and
+  `gflow video` now raise a clear, retryable `FlowAgentUiError` ("this cohort
+  flaps; retry shortly") instead of the misleading `UiSelectorDriftError`
+  "file a bug". Detection is a runtime DOM scan at a new shared
+  `_mode_switch_error` raise site covering **both** the image and video paths.
+  Refs #174, #183.
+- **Flow web-app crashes now fail cleanly instead of "file a bug".** When Flow's
+  web app renders its client-side-exception error boundary (a transient Flow
+  crash) instead of the editor, the mode-switch raise site now raises a retryable
+  `FlowAppError` (exit code 31) — "transient Flow error, retry shortly" — rather
+  than the misleading `UiSelectorDriftError`. Detected via the Flow error-page
+  title; surfaced by the #183 UI-drift debug engine.
+- **Experimental transport self-lockout.** The `bearer` and `sapisidhash`
+  transports discard a caller-supplied Playwright page and re-acquire the profile
+  `ProfileLease` in their own `setup()`. Driving one via `GFLOW_CLI_TRANSPORT`
+  inside a `FlowApiClient` (which already holds the lease) self-locked with an
+  opaque `ProfileLockedError`. `FlowApiClient` now refuses these standalone-only
+  transports up front with a clear `ConfigurationError` naming the transport and
+  pointing to `ui_automation`/`evaluate_fetch` or standalone use. `evaluate_fetch`
+  is unaffected (it shares the client's page). New `STANDALONE_ONLY_TRANSPORTS`
+  set + `resolve_transport_name()` helper in `api/transports`.
+
 ## [0.42.0] — 2026-07-21
 
 ### Fixed
@@ -2225,7 +2384,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.42.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.44.0...HEAD
+[0.44.0]: https://github.com/ffroliva/gflow-cli/compare/v0.43.0...v0.44.0
+[0.43.0]: https://github.com/ffroliva/gflow-cli/compare/v0.42.0...v0.43.0
 [0.42.0]: https://github.com/ffroliva/gflow-cli/compare/v0.41.0...v0.42.0
 [0.41.0]: https://github.com/ffroliva/gflow-cli/compare/v0.40.0...v0.41.0
 [0.40.0]: https://github.com/ffroliva/gflow-cli/compare/v0.39.0...v0.40.0

{gflow_cli-0.42.0 → gflow_cli-0.44.0}/CONTRIBUTING.md

@@ -11,6 +11,22 @@ uv sync --extra dev
 uv run playwright install chromium
 ```
 
+### Codex project skills
+
+Codex CLI and the Codex desktop app can install the repository's canonical `skills/`
+workflows as the `gflow` plugin. From the repository root, run:
+
+```bash
+codex plugin marketplace add .
+codex plugin add gflow@gflow-cli
+```
+
+Start a new Codex session after installation, then invoke a workflow with `$gflow:<skill>`
+(for example, `$gflow:status`, `$gflow:check`, or `$gflow:pr-council-review`). Claude Code
+continues to use the equivalent `/gflow:*` commands. The Codex IDE extension does not
+currently load plugins; include the relevant `skills/<name>/SKILL.md` directly when using
+that surface.
+
 ## Test-driven development (mandatory)
 
 `gflow-cli` is built test-first. Every change must include tests, and CI rejects PRs that lower coverage.

{gflow_cli-0.42.0 → gflow_cli-0.44.0}/KNOWN_ISSUES.md

@@ -14,6 +14,61 @@ Living list of behaviour that's broken, surprising, or limited by design — alo
 
 ## Open
 
+### One-time Flow banner/modal can cover the composer on first load
+
+- **Status:** Open ([#369](https://github.com/ffroliva/gflow-cli/issues/369))
+- **Severity:** Low (transient) · **Affected:** any UI-automation command on a profile that hasn't seen the banner yet
+
+A Flow-side one-time announcement banner/modal can overlay the composer and
+make the mode-switch / settings probes miss. It shows once per
+profile+cookie state, so it is gone on re-run and cannot be reproduced on
+demand. gflow does **not** guess a dismiss selector for unknown overlays
+(clicking unknown UI is riskier than failing). Since v0.43.0 the automatic
+incident bundle records the overlay's bounded geometry, `role`,
+`aria-modal`, `z-index`, `pointer-events`, and inner Material-Symbol
+ligatures (no raw text) plus a `sensitive/` screenshot — enough to write a
+targeted dismissal once the next occurrence is captured. **Workaround:**
+re-run the command; open the project once manually in Chrome to consume the
+banner.
+
+### Profile lock reported as "held by another process" with no obvious owner
+
+- **Status:** Resolved ([#370](https://github.com/ffroliva/gflow-cli/issues/370)) · remediation message clarified
+- **Severity:** Low (by design; fails closed — never corrupts) · **Affected:** `ProfileLease` acquisition (exit 11)
+
+`ProfileLockedError` can surface when no `chrome.exe` / `gflow` process is
+obvious. This is **working as intended, not a stale-file bug.** The profile
+lock is a kernel *advisory* byte-range lock, which the OS releases the instant
+its holder dies — so a leftover lock *file* can never block acquisition. If
+`acquire` is blocked, a **live** process genuinely holds it, most often a
+`python.exe` (a prior gflow run, or a pytest child that outlived its shell)
+that a scan for `chrome.exe` misses. gflow deliberately never auto-deletes a
+lock file or kills a recorded PID from metadata: an unlink→new-inode race could
+put two browsers on one profile — the exact corruption the lease exists to
+prevent. Since v0.43.0 contention reports the recorded owner's PID and observed
+start time locally (metadata starts at offset 1 so Windows contenders can read
+it while byte 0 is kernel-locked), and the remediation message now names the
+live-owner reality and tells you to just retry when nothing is running.
+**Workaround:** close the process at the PID the error prints
+(`Get-Process -Id <pid>` / `ps -p <pid>`, then `Stop-Process -Id <pid>` /
+`kill <pid>`), or use a different `--profile`.
+
+### Unexplained image-generation HTTP 400 (observed live 2026-07-22)
+
+- **Status:** Open (no issue yet — evidence-gathering)
+- **Severity:** Low (single occurrence) · **Affected:** `image t2i` wire path
+
+One live `batchGenerateImages` call returned an HTTP 400 that was neither a
+content-safety rejection nor a known wire shape; the retry succeeded. Root
+cause unidentified and **not** claimed fixed by v0.43.0. A 400 that resolves
+on retry writes **no** incident bundle (successful commands capture nothing).
+The diagnostics help only when such a 400 *terminates* the command as a
+captured failure (e.g. a `WireFormatError`): its incident bundle's
+`network.json` then carries allowlisted discovery evidence for the failed
+request (numeric error code, status enum, known-key booleans, unknown-key
+count, message length — never the raw body), which is the evidence this entry
+is waiting on. **Workaround:** retry; the failure has not recurred.
+
 ### Flow's `uploadImage` endpoint rejects some JPEGs with HTTP 400 (metadata-sensitive)
 
 - **Status:** Open ([#287](https://github.com/ffroliva/gflow-cli/issues/287))
@@ -109,6 +164,17 @@ reaches the submit** — the request carries no `referenceEntities`, so the
 submit backstops raise `WireFormatError` (**exit 7**) instead of silently
 returning a text-only generation as success.
 
+**Plain generation on this cohort now fails cleanly (#183).** When a project
+opens into this full-page library (or the agentic chat composer) there is no
+classic `crop_*` aspect/mode control, so `gflow image`/`gflow video` can't drive
+generation. Rather than the old opaque `UiSelectorDriftError` "file a bug", the
+mode-switch raise site now runs a runtime DOM scan and raises a clear, **retryable**
+`FlowAgentUiError` (**exit 25**, "this cohort flaps; retry shortly"), and dumps a
+DOM-signature diagnostics artifact (`diag_mode_switch_miss.json` + a full-page
+screenshot) for reporting. The cohort is server-assigned per page load and flaps
+within ~12h, so a re-run often lands the classic UI. Driving the new UI directly
+is still out of scope.
+
 **How to tell which UI your account has:** in the Flow web editor, click
 **Add Media** — a small dialog means the old (working) UI; a navigation to a
 full-page library means the affected new UI.
@@ -352,6 +418,8 @@ The worker queue (`generation_queue`, used by the `gflow serve` daemon and MCP t
 
 **Why this can't be resolved automatically today:** Flow's generation-status REST endpoint rejects a bare, cookie-only `page.request` re-check with HTTP 401 — only a live, authenticated Playwright SPA re-poll (opening the project page and reading the DOM) can turn a preserved handle back into a real status, and that live re-poll path is not wired into recovery yet (tracked for a future phase; see the C1 handle-spike notes in `docs/superpowers/specs/2026-07-19-production-readiness-hardening-design.md` Appendix A).
 
+**Decision (2026-07-21):** keep the safe stub — `recover_processing` marks post-submit interruptions `indeterminate` and never auto-resubmits, which is already correct. Building the auto-reconciler is deferred until **F1** (credit-free project-page re-entry) is confirmed against live Flow; until then a blind reconciler would be speculative code against unverified blackbox behavior. The `client` reconcile-hook seam and the live-gated `tests/e2e/test_crash_recovery_e2e.py` are already in place for when F1 lands.
+
 **Manual reconciliation:** an `indeterminate` row's checkpoint retains whatever handle/project info was captured before interruption. To resolve one by hand: open the relevant Flow project in the browser and check whether the expected asset appears.
 - **Found** — the generation completed; no action needed (the credit was spent as intended, just not auto-recorded locally).
 - **Not found after a few minutes** — it likely never completed; safe to resubmit the same prompt manually.

{gflow_cli-0.42.0 → gflow_cli-0.44.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.42.0
+Version: 0.44.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.42.0 → gflow_cli-0.44.0}/PLAN.md

@@ -358,7 +358,7 @@ The video-generation feature has its own sub-phase plan (spike → Phase A → P
   - **Phase 3 (PR #90 / [#63](https://github.com/ffroliva/gflow-cli/issues/63), 2026-05-26, develop `9a0896a8`):** replaced `FRAME_SLOTS_STRUCT` with the locale-free pattern `div[type='button'][aria-haspopup='dialog']` (verified via DOM probe — matches exactly 2). Also fixed the End-frame OOB index after Start is attached. **I2V live-proof on de-DE: 124 s, mp4 with `ftyp` magic bytes, both `frame_attached` events fired (Start + End).**
   - **Phase 4 (Task #6, 2026-05-26, branch `claude/next-quick-win-gBPqS`, PR #93):** `NEW_PROJECT_SELECTORS` expanded to all 14 locales (icon-first tier + 14-locale text tier); English-only ARIA fallbacks (`[aria-label*='New project']`, `[aria-label*='Project']`) removed. `SUBMIT_BUTTON_SELECTORS` drops its English-only `button[aria-label*="Create"]` entry — `arrow_forward` icon selectors cover it in all locales. Both tuples are now fully locale-invariant. Note: issue #24 was closed 2026-05-24 after Phases 1–3; Phase 4 is cosmetic tail work. `--lang=en-US` retained only to stabilise `IMAGE_MODEL_OPTION_SELECTORS` (product names like "Nano Banana 2" may be localised). Removing it requires converting the image model picker to a structural anchor — tracked as issue #94 (Phase 5 below). **R2V live e2e on non-EN not yet exercised** — still open.
   - **Phase 5 (2026-05-30, branch `claude/issue-94-staleness-check-MnsEY`, PR #127):** `IMAGE_MODEL_OPTION_SELECTORS` and `VIDEO_MODEL_OPTION_SELECTORS` converted from `dict[Model, str]` to `dict[Model, tuple[str, ...]]` (cascade discipline; Tier 1 structural slots reserved for future DOM-probe-confirmed anchors). `--lang=en-US` removed from Chromium launch args — locale controlled by `locale=locale_env` Playwright kwarg (persists across all navigations including `/project/<uuid>` deep-links) + `FLOW_URL`'s `?hl=en` on initial load. Branded model names confirmed locale-stable. Four new `TestSelectorLocaleInvariance` tests + four `TestSelectImageModel` runtime tests. **R2V live e2e on non-EN still pending (owner gate — requires authenticated non-EN Chrome profile).**
-- [ ] **Model Context Protocol (MCP) Server.** (Backlog) Expose core gflow-cli tools via MCP for language-agnostic agentic access. Planned in [PREDICT.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-22-mcp-server/PREDICT.md) / [SCENARIO.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-22-mcp-server/SCENARIO.md) / [PLAN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-22-mcp-server/PLAN.md).
+- [x] **Model Context Protocol (MCP) Server — SHIPPED** (stdio + HTTP/SSE server in v0.21.0, MCP→FlowWorker generation wiring in v0.23.0/PR #228; `gflow mcp run/setup` + `gflow serve`). Planned in [PREDICT.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-22-mcp-server/PREDICT.md) / [SCENARIO.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-22-mcp-server/SCENARIO.md) / [PLAN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-22-mcp-server/PLAN.md).
 - [x] **Tools framework + Prompt Expansion ("Creative Director") — shipped → develop (PRs #210 + #211, 2026-06-28).** Prompt expansion evolved from the never-released `-e`/`--expand` flag into a TOML-defined **Tools framework**: `creative-director` is the first built-in tool, invoked uniformly via `--tool/-t <name>[:k=v]` on every generation command (`image t2i`/`i2i`/`batch`, `video t2v`/`i2v`/`r2v`/`chain`) or standalone via `gflow tools list/show/run`. The tool rewrites a terse prompt via Gemini's 5-component formula (`src/gflow_cli/tools/`, stdlib-urllib expander, never-fatal: missing key / 429-backoff / network / empty-clean all fall back to the original), with 15 domain styles and deterministic banned-keyword stripping. `operations.expanded_prompt` records original + submitted expansion (withheld under `history_prompts=redacted`); `metadata_json.tool` records `{name, version, model, params, config_hash}` provenance (minimized in redacted mode). Reuses `GFLOW_CLI_GEMINI_API_KEY`; `GFLOW_CLI_GEMINI_MODEL` overrides. MCP parity: `gflow_list_tools` + a `tools` array param per AGENTS.md §61. Docs: [TOOLS.md](file:///C:/development/github/gflow-cli/docs/TOOLS.md) + [PROMPT_EXPANSION.md](file:///C:/development/github/gflow-cli/docs/PROMPT_EXPANSION.md). Memory `[[prompt-expansion-feature]]`.
   - **PR #210 (framework):** `tools/` package (spec/loader/registry/runtime/expander/banned/invocation), `creative-director.toml`, `gflow tools list/show/run`, `--tool` on t2i/t2v (single-prompt guard kept), MCP `gflow_list_tools` + `tools` param.
   - **PR #211 (broaden surface):** `original_prompt`/`tool` carried on the request DTOs (`GenerateImageRequest`/`GenerateVideoRequest`/`BatchPromptItem`/`ChainLinkSpec`); recorder reads `request.original_prompt` (kwarg retired); `metadata_json.tool` recording; `--tool` wired into i2i/batch/i2v/r2v/chain; single-prompt guard removed. Silent-misrecord hazard resolved by carrying `original_prompt` on the DTO rather than re-threading a kwarg through each recorder method.

{gflow_cli-0.42.0 → gflow_cli-0.44.0}/RELEASE.md

@@ -85,13 +85,14 @@ python -m pip install --pre gflow-cli
    see the root-doc allowlist.)
 6. Update the version in:
    - `pyproject.toml`
+   - `.codex-plugin/plugin.json`
    - `src/gflow_cli/__init__.py`
    - any tests that assert the package version
 7. Move user-visible changes from `CHANGELOG.md` `[Unreleased]` into a dated
    release section.
 8. Commit the release prep:
    ```bash
-   git add pyproject.toml src/gflow_cli/__init__.py CHANGELOG.md tests docs
+   git add pyproject.toml .codex-plugin/plugin.json src/gflow_cli/__init__.py CHANGELOG.md tests docs
    git commit -m "chore(release): vX.Y.Z"
    ```
 9. Tag and push. **Must be a signed annotated tag** (`-s`) — `.github/workflows/release.yml` rejects unsigned or lightweight tags. Requires a GPG or SSH signing key registered with your GitHub account.

{gflow_cli-0.42.0 → gflow_cli-0.44.0}/docs/ARCHITECTURE.md

@@ -303,6 +303,41 @@ Format defaults to **human-readable on TTY**, **JSON when piped or `GFLOW_CLI_LO
 
 Pipes cleanly into `jq` / Loki / Datadog without configuration. See [`docs/USER_GUIDE.md` § Journey 6](USER_GUIDE.md#journey-6--read-the-structured-logs) for `jq` recipes.
 
+## Incident diagnostics (shipped, v0.43.0)
+
+`FlowApiClient` owns one session-scoped `IncidentRecorder`
+(`gflow_cli.diagnostics`) because it already owns the persistent
+`BrowserContext`, the Page pool, teardown ordering, settings, and the
+profile lease. Lifecycle, in order:
+
+1. **Construct before lease acquisition** (plus best-effort retention
+   pruning), so `ProfileLockedError` contention can produce a metadata-only
+   bundle without ever launching Chrome.
+2. **Attach listeners after context launch, before the bootstrap
+   navigation:** context-level `request`/`response`/`requestfailed` plus a
+   `page` hook, and `console`/`pageerror` on every pooled page. Callbacks do
+   synchronous primitive extraction into bounded ring journals only — they
+   never retain Playwright objects, read bodies, touch the DOM, or perform
+   I/O.
+3. **Capture at the generation boundaries** (`generate_image` /
+   `generate_images_batch` / `generate_video`) while the page is still
+   alive: structural DOM + sensitive screenshot + journal snapshots are
+   *staged*; the manifest is not yet written. Capture is observation-only
+   and serialized by a recorder-local lock; repeats of one failure
+   fingerprint only bump a suppression counter (max 3 bundles/command).
+4. **Teardown order (load-bearing):** detach + freeze journals → bounded
+   context close → resolve HAR state honestly from a pre-launch file
+   snapshot → atomically finalize staged manifests (`manifest.json` last)
+   → driver stop → lease release. Finalization runs through the same
+   bounded/shielded teardown-step helper as everything else and can never
+   mask a close/driver/lease failure or swallow a cancellation.
+
+The legacy `capture_ui_diagnostics` debug dump consumes the same structural
+DOM engine (`STRUCTURAL_DOM_JS` + `validate_structural_dom`) — there is one
+DOM/screenshot engine, not two artifact formats. See
+[DEBUGGING § Automatic incident bundles](DEBUGGING.md#automatic-incident-bundles)
+and [SECURITY § Automatic incident bundles](SECURITY.md#automatic-incident-bundles-gflow_cli_incident_capture-default-on).
+
 ## Testing topology
 
 | Layer | Test type | Where | Network? |
@@ -395,6 +430,8 @@ We attempted three pure-HTTP transport strategies before settling on `ui_automat
 
 All three now live as standalone modules under `src/gflow_cli/api/transports/experimental/` (`evaluate_fetch.py` / `bearer.py` / `sapisidhash.py`), preserved for reference and future iteration. None survives Google's anti-bot stack for mutation/generation endpoints, so the production path is `ui_automation`.
 
+**Standalone-only transports.** `bearer` and `sapisidhash` discard any caller-supplied Playwright page and launch their own browser under a fresh `ProfileLease`, so they are **standalone-only** — they cannot run inside a `FlowApiClient` that already holds the profile lease (the second acquire would self-lock with `ProfileLockedError`). Selecting either via `GFLOW_CLI_TRANSPORT` (or the Python API) while the client owns the profile now fails fast with a clear `ConfigurationError` naming the transport, rather than the opaque lock error. `evaluate_fetch` is exempt: it reuses the client's shared page and takes no second lease. The standalone-only set lives in `STANDALONE_ONLY_TRANSPORTS` (`api/transports/__init__.py`); to drive `bearer`/`sapisidhash`, run them outside an owning client.
+
 ### What this costs users
 
 - A **persistent Chrome profile** on disk (~150 MB after `playwright install chromium`).

{gflow_cli-0.42.0 → gflow_cli-0.44.0}/docs/CHARACTER.md

@@ -38,12 +38,22 @@ seeding the second step with the first:
 
 1. **Face (slot 0).** gflow submits your `--face-prompt` and Flow generates the **face** image. This becomes
    the character's first reference image.
-2. **Body (slot 1).** gflow clicks the editor's slot-add ("+") button, which **auto-attaches the just-generated
-   face image as the reference seed** for the new slot. gflow then submits its **own self-contained
+2. **Body (slot 1).** gflow activates the editor's Create-Body mode, which **auto-attaches the just-generated
+   face image as the reference seed**. gflow then submits its **own self-contained
    front/side/back triptych prompt** (it wraps your `--body-prompt` body/outfit description). Because the face
    is attached as the seed, a **single credited generation** produces all three body angles — front, side, and
    back — that match the face.
 
+   The character editor is a **two-mode surface** ("Portrait" / "Create Body"). Current Flow reuses one Slate
+   editor across both modes, so gflow anchors Create Body by the locale-independent `accessibility_new` icon
+   beside the portrait-image button and requires a new generated-face reference chip to mount before using the
+   shared box. Older cohorts that mount a second prompt box remain supported through a Slate-count-rise gate. In
+   both cases gflow verifies the selected
+   body box still owns focus **before clearing or typing**. If the structural mode signal or focus check fails,
+   the body step aborts before any autosaved prompt edit; post-type isolation failures abort before the credited
+   submit. This guards the race that corrupted a stored portrait prompt live on 2026-07-25/0.43.0. Re-run
+   `gflow character create` to retry; the saga reuses the entity and completed face slot (§4).
+
 The result: two generations (face + body-triptych), the body kept on-model by the face seed. Everything else —
 naming the character, setting the voice/personality, and saving — is free metadata (REST), not generation. See
 §4 for the full saga and §6.2 for the wire payload.
@@ -269,7 +279,7 @@ is **shipped** (see the table below).
 
 | Command | Maps to |
 |---|---|
-| `gflow character create --project <id> --name <name> --face-prompt … [--body-prompt …] [--voice <Name>] [--personality …] [--model nano2\|nanopro] [--profile …] [--locale en-US] [--json]` *(SHIPPED v0.12.0 — shipped option names; characters have NO aspect-ratio control)* | createEntity → gen face (slot 0) → commit_workflow → optional gen body (slot 1) → commit_workflow → patch_entity, via the persist-before-spend saga (§4). `--body-prompt` is a **body/outfit DESCRIPTION** — gflow wraps it in a self-contained **front/side/back triptych** instruction and seeds it with the generated face (auto-attached as the slot-add reference), so one body generation yields all three angles. Generated images are **downloaded** to storage; the result reports each slot's local path. |
+| `gflow character create --project <id> --name <name> --face-prompt … [--body-prompt …] [--voice <Name>] [--personality …] [--model nano2\|nanopro] [--profile …] [--locale en-US] [--json]` *(SHIPPED v0.12.0 — shipped option names; characters have NO aspect-ratio control)* | createEntity → gen face (slot 0) → commit_workflow → optional gen body (slot 1) → commit_workflow → patch_entity, via the persist-before-spend saga (§4). `--body-prompt` is a **body/outfit DESCRIPTION** — gflow wraps it in a self-contained **front/side/back triptych** instruction and seeds it with the generated face (auto-attached as the body-mode reference), so one body generation yields all three angles. Generated images are **downloaded** to storage; the result reports each slot's local path. |
 | `gflow character list --project <id> [--json]` *(SHIPPED v0.12.0)* | projectInitialData → entities[CHARACTER] |
 | `gflow character show --project <id> (--id <entityId> \| --name <displayName>) [--json]` *(SHIPPED v0.12.0)* | projectInitialData (single); name collision → exit 11 with disambiguation hint |
 | `gflow character voices [--json]` *(SHIPPED v0.12.0)* | list the 29 preset voices (name / description / sample-url); language-agnostic discovery, mirrors `gflow models --json` |
@@ -403,7 +413,7 @@ Built by `routes.character_editor_url(locale, projectId, entityId)`. The **`/fx/
 without it Flow 404s (caught by spike T-A; the fix sourced the URL from `LABS_FX_BASE`). Navigating to this
 URL (not the new-project flow) is what makes Flow's JS set `entityContext` on the generation. Name / voice /
 personality are REST `PATCH flow/entities`. The only *new* generation selectors are the prompt/submit (already
-owned by gflow) and the slot-add.
+owned by gflow) and the body-mode activation/settle signals.
 
 | Purpose | Selector | Conf. |
 |---|---|---|
@@ -413,7 +423,7 @@ owned by gflow) and the slot-add.
 | Name field | `input[placeholder]` — localized placeholder; **do NOT rely on the text** (structural: it is the editor's lone placeholdered input) | **VERIFIED** |
 | Personality field | the panel `textarea` (localized placeholder) — **prefer REST PATCH** | **VERIFIED** |
 | Slot 0 image (face) | aria-label `"Imagem do personagem 1"` — **localized**, note only (do not load-bear on the text) | med (localized) |
-| **Slot-add (body / slot 1)** | `add_2` google-symbols ligature; the editor has **TWO** `add_2` buttons → slot-add is **`.nth(1)`** (`_CHARACTER_SLOT_ADD_SELECTOR = "button:has(i.google-symbols:text('add_2'))"`). The **first** `add_2` is the gallery "+ New project" CTA → positional disambiguation. ⚠️ confirm `.nth(1)` in the live body-gen e2e (Task 12). | **VERIFIED** (selector) / ⚠️ ordering |
+| **Body mode (slot 1)** | Current cohort: portrait-image sibling `button:has(img) + button:has(i.google-symbols:text-is('accessibility_new'))`; settle signal: a newly mounted generated-media card with an `img` and exact `cancel` icon. Legacy cohort fallback: icon-only `[role=button]` carrying exact `add_2`, followed by Slate-box count rise. No localized button text or positional index. | **VERIFIED** live 2026-07-26 |
 | Model picker (char editor) | `button[aria-haspopup='menu']:has(i.google-symbols:text-is('arrow_drop_down'))` *(normal editor uses `crop_16_9`)* | **VERIFIED** |
 | Voice picker | `voice_selection` google-symbols ligature | **VERIFIED** (ligature) |
 | Personagens nav (project) | `button:has(i.google-symbols:text-is('accessibility_new'))` (cards are `div[role=button]`; tag disambiguates) | high |
@@ -421,10 +431,10 @@ owned by gflow) and the slot-add.
 | Picker tab → Personagens | `[role=dialog] button[role=tab]:has(i.google-symbols:text-is('accessibility_new'))` | high |
 | **Picker "include in command"** | primary `button` in the dialog footer — **no ligature → structural anchor (last/primary dialog button)**; only appears *after* an option is selected | low ⚠️ |
 
-⚠️ **Documented risk (Task-12 e2e):** the slot-add `.nth(1)` ordering and the picker include button (no
-ligature, localized text only) are positional/structural anchors that must be confirmed under a live non-EN
-locale. Slot 0's `"Imagem do personagem N"` aria-label is **localized** — used as a note, never as a
-load-bearing selector.
+⚠️ **Documented risk (Task-12 e2e):** the picker include button (no ligature, localized text only) remains a
+positional/structural anchor to confirm under a live non-EN locale. Body mode no longer uses the stale
+`.nth(1)` selector; its mode and settle icons are locale-independent. Slot 0's `"Imagem do personagem N"`
+aria-label is **localized** — used as a note, never as a load-bearing selector.
 
 Shared chrome already automated by gflow (reuse as-is): `add_2` (+/Criar add-media → opens picker),
 `arrow_forward` (submit), the Slate prompt box, model dropdown, `check`/Concluir.
@@ -472,7 +482,7 @@ table → test mapping):
 
 **Remaining LIVE-e2e-only (Task 12):** the live binding/recovery/UTF-8 e2e on denon82 — real
 `parentEntityId == entityId` against Flow's wire, mid-saga crash recovery against the real DB, and the
-slot-add `.nth(1)` + picker-include structural selectors under a non-EN locale.
+body-mode icon/reference settle signals + picker-include structural selectors under a non-EN locale.
 
 ## 13.1 Known issues
 

{gflow_cli-0.42.0 → gflow_cli-0.44.0}/docs/CONFIGURATION.md

@@ -261,6 +261,15 @@ GFLOW_CLI_HISTORY_PROMPTS=redacted gflow image t2i "confidential brief"
 **When to set it:** capturing locale-invariant DOM via `scripts/dev/capture_locale_invariants.py`, or live-verifying a generation under a non-EN account language.
 **Important:** Chrome's *UI* language is independently forced to `en-US` via the `--lang=en-US` launch arg (so Flow keeps serving `/fx/tools/flow/` and the editor's localized text selectors keep working). This env var only affects request headers — not the editor UI you see. See [KNOWN_ISSUES § issue #24](../KNOWN_ISSUES.md) for the path to dropping `--lang=en-US`.
 
+### `GFLOW_CLI_INCIDENT_CAPTURE`
+
+**What:** Automatically writes a **private incident bundle** on relevant operational failures (Flow app crash, agentic-cohort/UI-mode errors, selector drift, transport timeouts, WAF/network/wire-format errors, profile-lock contention, unexpected exceptions while a page is alive) under `<GFLOW_CLI_HOME>/incidents/<YYYY-MM-DD>/<UTC-stamp>-<incident-id>-<rand>/`. See [DEBUGGING § Automatic incident bundles](DEBUGGING.md#automatic-incident-bundles) for the bundle layout and triggers.
+**Values:** `true` | `false`
+**Default:** `true`
+**When to disable:** shared machines where even structural failure metadata should not persist, or scripted runs that must write nothing outside the output dir.
+
+**Privacy:** the automatic JSON artifacts (`manifest.json`, `ui.json`, `network.json`, `browser.json`) are built from an explicit allowlist — no prompts, tokens, cookies, headers, request/response bodies, signed URLs, raw page titles, raw error/console text, or unknown hosts/routes ever enter them. The screenshot is inherently sensitive (it can show your account identity, prompts, and media) and therefore lives under the bundle's `sensitive/` subdirectory — **review it before sharing**. Nothing is ever uploaded; retention is bounded (at most 50 complete bundles / 250 MiB, pruned oldest-first at startup). Raw HAR capture stays separate and strictly opt-in via `GFLOW_CLI_HAR_PATH`.
+
 ### `GFLOW_CLI_HAR_PATH`
 
 **What:** Captures full Playwright network traffic (requests, responses, headers, cookies) to a HAR file for the session — useful for diagnosing wire-format surprises or WAF rejections.