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

gflow_cli-0.42.0/.claude/commands/gflow/live-verify.md

@@ -0,0 +1,9 @@
+---
+description: Two-part gate for gflow-cli feature work — pre-flight state check at the start, live-verification against real Flow before claiming done.
+---
+
+# `/gflow:live-verify` — Live-verification enforcement
+
+**Read `skills/live-verify/SKILL.md` and follow the protocol**, passing `$ARGUMENTS` if given.
+
+> Do **not** call `Skill(skill="live-verify")` — read the file directly.

{gflow_cli-0.40.0 → gflow_cli-0.42.0}/.claude/commands/gflow/llm-council.md

@@ -1,10 +1,10 @@
 ---
-description: Run pr-council-review (PR or branch mode) plus an external-tools corroboration layer (codex, gemini, opt-in agy) for high-stakes reviews where a same-model-family blind spot is a real risk. Tiers: small (internal only, default) / medium (+codex) / high (+codex+gemini). Wrapper around skills/llm-council/SKILL.md.
+description: Run pr-council-review (PR or branch mode) plus an external-tools corroboration layer (codex, plus Antigravity via the agy harness) for high-stakes reviews where a same-model-family blind spot is a real risk. Tiers: small (internal only, default) / medium (+codex) / high (+codex+antigravity). Wrapper around skills/llm-council/SKILL.md.
 ---
 
-# `/gflow:llm-council [PR# | --base <ref>] [--tier small|medium|high] [--include-agy]`
+# `/gflow:llm-council [PR# | --base <ref>] [--tier small|medium|high]`
 
-**Read `skills/llm-council/SKILL.md` and follow its protocol now**, treating `$ARGUMENTS` as: the PR number or `--base <ref>` (branch mode, same as `/gflow:pr-council-review` / `/gflow:branch-review`), plus `--tier <small|medium|high>` (default `small`) and the optional `--include-agy` flag.
+**Read `skills/llm-council/SKILL.md` and follow its protocol now**, treating `$ARGUMENTS` as: the PR number or `--base <ref>` (branch mode, same as `/gflow:pr-council-review` / `/gflow:branch-review`), plus `--tier <small|medium|high>` (default `small`). The `high` tier adds Antigravity (`agy`) alongside `codex`.
 
 > Do **not** call `Skill(skill="llm-council")` or `Skill(skill="pr-council-review")` — the repo's `skills/*/SKILL.md` files are plain Markdown, not registered as Skill-tool-invocable (only `.claude/commands/gflow/*` are). Invoking either errors with `Unknown skill: ...`. Read the files directly instead.
 

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

@@ -102,17 +102,21 @@
 #   auto = text on TTY, json when piped (default)
 # GFLOW_CLI_LOG_FORMAT=auto
 
-# Per-worker Playwright Page-pool size for batch runs (1-16). FlowApiClient
-# opens N Pages inside one shared persistent BrowserContext; `gflow video batch`
-# fans out via asyncio.gather. ~30-60 MiB memory per Page on Chromium headless;
-# don't exceed 8 without measuring. Shipped in v0.4.0a2.
+# Per-worker Playwright Page-pool size (1-16). FlowApiClient opens N Pages
+# inside one shared persistent BrowserContext. No current CLI command fans
+# out multiple generations concurrently through this pool, so raising it has
+# no effect today. ~30-60 MiB memory per Page on Chromium headless if that
+# changes; don't exceed 8 without measuring. Shipped in v0.4.0a2.
 # GFLOW_CLI_CONCURRENCY=1
 
 # Run Playwright in headless mode for non-`auth login` commands (true|false).
-# Default: true. Set to false if reCAPTCHA Enterprise refuses to mint tokens
-# (Google's bot-detection sometimes refuses headless Chromium but accepts a
-# visible window). The session is still reused from the persistent profile.
-# GFLOW_CLI_HEADLESS=true
+# Default: false — headed real Chrome is the PRODUCTION default, not a
+# fallback. The ui_automation transport (the only production transport)
+# requires headed Chrome: reCAPTCHA Enterprise rejects headless Chromium
+# outright (immediate 403). Only set true for CI/CD on a non-ui_automation
+# transport (bearer/sapisidhash, experimental). For WAF-sensitive runs, pin
+# GFLOW_CLI_HEADLESS=false explicitly rather than relying on the default.
+# GFLOW_CLI_HEADLESS=false
 
 # Browser automation engine — playwright (default) | patchright
 # patchright is an OPT-IN, drop-in patched Playwright (Chromium) that avoids the

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

@@ -87,6 +87,37 @@ jobs:
           path: coverage.xml
           retention-days: 1
 
+  # ── Focused OS matrix: ProfileLease cross-process contract (Task D2) ──────
+  # Everything else in this file runs Ubuntu-only (the `test` job above).
+  # This job exists because ProfileLease's kernel lock is genuinely
+  # OS-specific (msvcrt.locking on Windows vs. fcntl.flock on POSIX) and D1's
+  # local Windows-only run left the POSIX fcntl branch reasoned-but-unexecuted
+  # (see .superpowers/sdd/task-D1-report.md). Runs ONLY the lease unit +
+  # subprocess tests, not the full suite.
+  profile-lease-matrix:
+    name: ProfileLease (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    env:
+      PYTHONUTF8: "1"
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, macos-latest, ubuntu-latest]
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Install deps
+        run: uv sync --extra dev
+
+      - name: ProfileLease unit + subprocess tests
+        run: uv run python -m pytest tests/test_profile_lease.py tests/test_profile_lease_subprocess.py -q
+
   # ── SonarCloud analysis ───────────────────────────────────────────────────
   sonar:
     name: SonarCloud analysis

{gflow_cli-0.40.0 → gflow_cli-0.42.0}/.github/workflows/main-base-guard.yml

@@ -30,7 +30,7 @@ jobs:
     name: Release must carry /gflow:release artifacts
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - name: Verify release artifacts
         env:
           BASE_REF: ${{ github.base_ref }}

{gflow_cli-0.40.0 → gflow_cli-0.42.0}/.github/workflows/pages.yml

@@ -26,8 +26,8 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
       - name: Install MkDocs Material
@@ -40,7 +40,7 @@ jobs:
           mkdir -p _site
           cp index.html _site/
           cp -r website/site _site/docs
-      - uses: actions/upload-pages-artifact@v3
+      - uses: actions/upload-pages-artifact@v5
         with:
           path: _site
 
@@ -52,4 +52,4 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

{gflow_cli-0.40.0 → gflow_cli-0.42.0}/.gitignore

@@ -58,10 +58,6 @@ gflow-output/
 !test_assets/fixtures/**/*.jpeg
 samples/*.captured.json # sandbox-recorded API exchanges may contain PII
 
-# CDP browser session lock files (contain PID, port, profile name)
-.gflow-cdp.lock
-**/.gflow-cdp.lock
-
 # Runtime artefact dirs written by smoke/debug scripts — belong under tmp/ only
 test_assets/smoke_*/
 test_assets/debug_*/

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

@@ -2,14 +2,14 @@
 
 > Universal entry point for AI coding agents. Read this first; everything else routes from here.
 
-Supported tools that auto-discover this file: Cursor, Codex, Aider, Jules, Devin, Windsurf, Zed, Warp, opencode, RooCode, Amp, Junie, Phoenix, GitHub Copilot, VS Code, Factory, Augment, Semgrep, Kilo Code, UiPath. Gemini CLI reads [GEMINI.md](GEMINI.md) and Claude Code reads [CLAUDE.md](CLAUDE.md), both of which cross-reference this file.
+Supported tools that auto-discover this file: Cursor, Codex, Aider, Antigravity (`agy`), Jules, Devin, Windsurf, Zed, Warp, opencode, RooCode, Amp, Junie, Phoenix, GitHub Copilot, VS Code, Factory, Augment, Semgrep, Kilo Code, UiPath. Claude Code reads [CLAUDE.md](CLAUDE.md), which cross-references this file.
 
 ## Project at a glance
 
 - Unofficial Python CLI for [Google Flow](https://labs.google/fx/tools/flow) — drives Veo (image-to-video, text-to-video) and Imagen (text-to-image) generations from the terminal by reverse-engineering Flow's private REST API at `aisandbox-pa.googleapis.com`.
 - Python 3.11+ · `uv`-managed · `hatchling` builds · Playwright Chromium transport · `pyright` strict · `ruff` · `pytest`.
-- Single-package modular monolith. Top-level modules under `src/gflow_cli/`: `api/`, `auth/`, `data/`, `mcp/`, `services/`, `tools/`, `ui/`, `worker/`, `browser_manager.py`, `cli.py`, `_cli_helpers.py`, `cli_character.py`, `cli_data.py`, `cli_image.py`, `cli_instructions.py`, `cli_models.py`, `cli_movie.py`, `cli_run.py`, `cli_scene.py`, `cli_tools.py`, `cli_video.py`, `chain.py`, `chain_manifest.py`, `composition.py`, `config.py`, `errors.py`, `exceptions.py`, `image_batch.py`, `manifest.py`, `movie_manifest.py`, `observability.py`, `paths.py`, `profile_store.py`.
-- Command surface: `gflow auth`, `gflow image` (t2i/i2i/batch/upload/upscale), `gflow video` (t2v/i2v/r2v/chain — `batch` is a Phase B stub), `gflow character` (create/list/show/rm/voices — reusable project-scoped Flow Character entities), `gflow scene` (create/show — Add Clip / Scenes, with `create --output` for credit-free server-side extended video), `gflow instructions` (persistent Agent-Mode brief cards — add/list/enable/disable/rm/apply/toggle-mode, credits-free, `--project` required), `gflow movie` (run/template — multi-scene manifest pipeline), `gflow tools` (list/show/run — prompt-rewriting tools, also `--tool` on generation commands), `gflow data` (catalog queries), `gflow models`, `gflow run`, `gflow mcp` (run/setup — stdio MCP server), and `gflow serve` (HTTP/SSE).
+- Single-package modular monolith. Top-level modules under `src/gflow_cli/`: `api/`, `auth/`, `data/`, `mcp/`, `services/`, `tools/`, `ui/`, `worker/`, `browser_manager.py`, `cli.py`, `_cli_helpers.py`, `cli_character.py`, `cli_data.py`, `cli_image.py`, `cli_instructions.py`, `cli_models.py`, `cli_movie.py`, `cli_run.py`, `cli_scene.py`, `cli_tools.py`, `cli_video.py`, `chain.py`, `chain_manifest.py`, `composition.py`, `config.py`, `errors.py`, `exceptions.py`, `image_batch.py`, `movie_manifest.py`, `observability.py`, `paths.py`, `profile_store.py`.
+- Command surface: `gflow auth`, `gflow image` (t2i/i2i/batch/upload/upscale), `gflow video` (t2v/i2v/r2v/chain — no `batch` subcommand; the nonfunctional stub was removed, loop `gflow video t2v`/`i2v` from the shell for multi-clip runs), `gflow character` (create/list/show/rm/voices — reusable project-scoped Flow Character entities), `gflow scene` (create/show — Add Clip / Scenes, with `create --output` for credit-free server-side extended video), `gflow instructions` (persistent Agent-Mode brief cards — add/list/enable/disable/rm/apply/toggle-mode, credits-free, `--project` required), `gflow movie` (run/template — multi-scene manifest pipeline), `gflow tools` (list/show/run — prompt-rewriting tools, also `--tool` on generation commands), `gflow data` (catalog queries), `gflow models`, `gflow run`, `gflow mcp` (run/setup — stdio MCP server), and `gflow serve` (HTTP/SSE).
 - Requires a Google AI Ultra or Pro subscription with Flow access. All generations bill against the user's own Google account.
 
 ## Headed-browser dependency (architectural reality)
@@ -57,7 +57,7 @@ Or invoke the wrapper: `/gflow:check`.
 
 - Type hints everywhere; `pyright` strict on `src/gflow_cli`.
 - Structured logging only (`structlog`) — **never** raw `print()` or `import logging` in `src/`.
-- Errors as RFC 9457 Problem Details with stable per-class exit codes (3–27, e.g. 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`, 22 `UpscaleUnavailableError`, 25 `FlowAgentUiError`). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping.
+- Errors as RFC 9457 Problem Details with stable per-class exit codes (3–30, e.g. 11 is `ConfigurationError` — including `ProfileLockedError` for same-profile lease contention, 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`, 22 `UpscaleUnavailableError`, 25 `FlowAgentUiError`, 28 `UiModeUnavailableError`, 29 `MentionIndexUnavailableError`, 30 `QueueSchemaError`). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping.
 - 100-char line length, `ruff` configured. Imports sorted by `ruff` (isort rules).
 - **YAGNI / least-code**: prefer the smallest change that works. No speculative abstractions (interface/factory with one implementation), no config or flags nobody sets, no dead constants/helpers, no reinventing the stdlib. Review carries this as its own lens — the **D14 over-engineering** dimension of [`pr-council-review`](skills/pr-council-review/SKILL.md) (baseline, always runs). Its rubric is portable; the `ponytail` plugin (see CONTRIBUTING) is an optional accelerant, not a dependency.
 - **MCP & CLI Schema Symmetry**: Any updates or additions to user-facing CLI command parameters (e.g., `gflow image t2i`, `gflow video`) must be mirrored in the corresponding MCP tool definitions. Never add option/argument fields to Click commands without updating the MCP server implementation. This symmetry is enforced programmatically in CI via `tests/mcp/test_cli_parity.py` (every CLI leaf command needs a mapped MCP tool or an explicit, reasoned exemption) plus the schema checks in `tests/mcp/test_server.py`.
@@ -78,6 +78,7 @@ These rules exist because docs alone don't bind under momentum: a "check open PR
 - **Truth is the CLI and running the code — not IDE/LSP "reminder" diagnostics.** Editor / `pyright`-in-worktree warnings go stale for an entire session and throw false positives (especially across multiple worktrees). Confirm with `ruff` / `pyright` / `pytest` from the terminal — or trust the worktree's own venv — never an IDE squiggle.
 - **Verify third-party runtime behavior empirically before wiring it in.** Don't assume how an external library, API, or browser actually behaves — exercise it once and observe, then build on the observed contract.
 - **If a claim can't be verified in the current environment, it's LIKELY — not CONFIRMED.** Keep the issue open, reference it with `Refs #N` (not `Closes #N`), and ship diagnostics rather than a blind fix. When you can't reproduce it, hand the fix to whoever can.
+- **This project reverse-engineers a blackbox.** gflow-cli doesn't own Google Flow — it drives real Flow through inspected HAR/DOM/browser-log behavior. Offline checks (types, lint, unit/BDD tests) verify *our* code does what we think it does; they cannot verify Flow still behaves the way we captured it. Every feature that touches a generation path is **live-verified**, not just offline-tested, before it's called done — see `/gflow:live-verify`.
 
 ## Skills reference (cross-tool)
 
@@ -91,13 +92,14 @@ The `skills/` directory ships installable agent skill docs in plain Markdown wit
 | `plan` | [`skills/plan/SKILL.md`](skills/plan/SKILL.md) | Create a structured task-by-task implementation plan for a feature |
 | `status` | [`skills/status/SKILL.md`](skills/status/SKILL.md) | Show current plan state, progress, and next unchecked task |
 | `pr-council-review` | [`skills/pr-council-review/SKILL.md`](skills/pr-council-review/SKILL.md) | Multi-dimensional PR council review |
-| `llm-council` | [`skills/llm-council/SKILL.md`](skills/llm-council/SKILL.md) | Wraps `pr-council-review` with external CLI reviewers (`codex`/`gemini`, opt-in `agy`) for high-stakes reviews |
+| `llm-council` | [`skills/llm-council/SKILL.md`](skills/llm-council/SKILL.md) | Wraps `pr-council-review` with external CLI reviewers (`codex` + Antigravity `agy`) for high-stakes reviews |
 | `issue-assessment` | [`skills/issue-assessment/SKILL.md`](skills/issue-assessment/SKILL.md) | Triage a GitHub issue (read-only) before any fix work |
 | `issue-resolve` | [`skills/issue-resolve/SKILL.md`](skills/issue-resolve/SKILL.md) | Drive an assessed issue to a test-first fix + draft PR |
 | `check` | [`skills/check/SKILL.md`](skills/check/SKILL.md) | Quality gates (lint/format/types/tests) before every commit |
 | `changelog` | [`skills/changelog/SKILL.md`](skills/changelog/SKILL.md) | Unreleased changes + last tagged version |
 | `known-issues` | [`skills/known-issues/SKILL.md`](skills/known-issues/SKILL.md) | Open/mitigated known issues — before auth/reCAPTCHA work |
 | `sonar` | [`skills/sonar/SKILL.md`](skills/sonar/SKILL.md) | Drive the SonarCloud quality gate to zero for a PR/branch |
+| `live-verify` | [`skills/live-verify/SKILL.md`](skills/live-verify/SKILL.md) | Pre-flight state check at start of work; live-verification against real Flow before claiming done |
 | `doc-review` | [`skills/doc-review/SKILL.md`](skills/doc-review/SKILL.md) | Council-driven documentation audit before a release |
 | `release` | [`skills/release/SKILL.md`](skills/release/SKILL.md) | Cut a release — bump, CHANGELOG, tag, push, back-merge |
 
@@ -106,7 +108,7 @@ 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 / Gemini CLI (`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.
+**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.
 **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.40.0 → gflow_cli-0.42.0}/CHANGELOG.md

@@ -7,6 +7,121 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.42.0] — 2026-07-21
+
+### Fixed
+
+- Content-safety `400` responses from Flow are now classified as
+  `ContentPolicyError` (exit code 5) instead of the misleading `WireFormatError`,
+  so callers can branch on a policy rejection deterministically. (#359)
+- Corrected a false `flow_operation_id` invariant. Live verification found
+  `veo-lite` can produce a `remote_started` checkpoint with `operation_id` unset,
+  contradicting the prior claim that only `omni-flash` omits the operation name.
+  `flow_operation_id` is best-effort/optional; `media_id` is the canonical handle
+  used by polling, download, and every CLI lookup. No behaviour change; a
+  regression test now locks the operation-name parser against the real veo
+  capture fixture. (#361)
+
+### Changed
+
+- **Replaced Gemini CLI with Antigravity (`agy`) as the supported Google coding
+  agent** across skills and docs (Google retired Gemini CLI in favor of the
+  Antigravity harness). Antigravity auto-discovers `AGENTS.md` natively, so the
+  dedicated `GEMINI.md` hub is **removed** and Antigravity is listed among the
+  auto-discovering tools in `AGENTS.md`. (#360)
+- **`llm-council` skill:** the `high` tier's second external reviewer is now
+  Antigravity (`agy`) instead of Gemini CLI; `agy` is promoted from an opt-in
+  tool to the pinned `high`-tier slot and the `--include-agy` flag is dropped.
+  When `agy` is unavailable or fails non-interactively, the skill suggests
+  installing Antigravity or substituting another external CLI coding agent rather
+  than failing. (#360)
+- Forward-looking agent references updated for consistency across `AGENTS.md`,
+  `CLAUDE.md`, `README.md`, `llms.txt`, `docs/INDEX.md`, `docs/AGENT_GUIDE.md`,
+  `skills/*`, and CI helper strings. Historical release notes and past
+  verification records are left unchanged. (#360)
+
+### Removed
+
+- Removed the dead `fail_processing_tasks` daemon-recovery method, superseded by
+  the checkpoint-classifying `recover_processing` (internal cleanup; no
+  user-facing behaviour change). (#361)
+
+### Documentation
+
+- Added an onboarding page and quickstart flow to the published docs site, and
+  anonymized personal account data across it. Security vulnerabilities now report
+  through GitHub's private vulnerability reporting rather than a personal email. (#362)
+- Corrected the same-profile concurrency framing (MCP page and docs) to the
+  cross-process `ProfileLease` fail-fast contract (`ProfileLockedError`, exit 11),
+  and recorded that the POSIX `fcntl.flock` lease was verified green on the
+  Windows/macOS/Linux CI matrix. (#361)
+
+### Tests
+
+- Added live-gated end-to-end tests for crash-recovery (a crashed post-submit task
+  recovers as `indeterminate` and is never resubmitted) and cancellation-safe
+  teardown (the profile lease releases on mid-launch cancel). Both were confirmed
+  against real Flow on 2026-07-21. (#361)
+
+## [0.41.0] — 2026-07-20
+
+### Added
+
+- **Cross-process profile lease** ([#357]): new `ProfileLease` with
+  process-local guard + kernel advisory lock (`msvcrt` on Windows, `fcntl`
+  on POSIX), keyed by canonical profile dir. `ProfileLockedError` (exit 11)
+  on contention. Integrated at all 10 persistent-context-owning boundaries.
+  Daemon's overwriteable `profile.lock` removed.
+- **Versioned worker queue payloads** ([#357]): `schema_version: 1` codec
+  validates before Playwright starts; unknown versions raise typed
+  `QueueSchemaError` (exit 30). Legacy V0 (missing field) still accepted.
+- **Atomic queue task claims** ([#357]): single SQLite `BEGIN IMMEDIATE`
+  transaction (select → decode → fail-invalid-without-browser → conditional
+  `pending→processing`) shared by daemon and MCP; duplicate per-profile lock
+  maps removed. Checkpointed execution phases (`claimed → submit_attempted →
+  remote_started → terminal`) with conservative `may_have_spent`.
+- **`/gflow:live-verify` skill**: pre-flight state check + per-feature
+  live-verification gate before claiming feature completion.
+- **Driver honesty improvements** ([#357]): removed classic driver's
+  `await_images()` that only raised; replaced late `driver._transport = self`
+  mutation with typed `SupportsSendPrompt` injection; agentic submit takes
+  request + expected count directly. Frozen `TransportSetup` applied through
+  public `apply_setup()` seam replacing client writes to transport-private
+  fields.
+
+### Changed
+
+- **Cancellation-safe browser teardown** ([#357]): per-step
+  `shield(wait_for(...))` bounded cleanup in required order (stop work →
+  cancel worker → persist state → close browser/driver → close stores →
+  release lease), re-raising original cancellation last.
+- **Mention-index outages fail closed** ([#357]): `MentionIndexUnavailableError`
+  (exit 29) with unavailable source name; mention-free prompts stay
+  pass-through. Empty source ≠ unavailable source.
+- **`OperationRecorder`/chain-repo datastore ownership** ([#357]): stores
+  only close the `DataStore` they create; injected stores never closed by a
+  non-owner.
+- External-CDP browser lifecycle removed by evidence (no production
+  consumer, unauthenticated debug port, ambiguous ownership, recorded
+  WAF-rejection); Chrome discovery/channel helpers preserved.
+
+### Removed
+
+- **`gflow video batch`** — the manifest-driven video batch command was
+  removed. It never worked end-to-end; every invocation exited immediately
+  with a stub error before reaching Flow. `gflow image batch` (manifest-driven
+  image generation) is unaffected and remains supported.
+- External-CDP browser lifecycle (no production consumer).
+
+### Security
+
+- Cancellation-safe teardown prevents resource leaks on interrupt.
+- Profile lease kernel advisory lock prevents concurrent profile access
+  across processes.
+
+[#357]: https://github.com/ffroliva/gflow-cli/pull/357
+[`docs/LIVE_VERIFICATION_v0.40.0-production-readiness.md`]: https://github.com/ffroliva/gflow-cli/blob/main/docs/LIVE_VERIFICATION_v0.40.0-production-readiness.md
+
 ## [0.40.0] — 2026-07-19
 
 ### Added
@@ -2110,7 +2225,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.40.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.42.0...HEAD
+[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
 [0.39.0]: https://github.com/ffroliva/gflow-cli/compare/v0.38.1...v0.39.0
 [0.38.1]: https://github.com/ffroliva/gflow-cli/compare/v0.38.0...v0.38.1

{gflow_cli-0.40.0 → gflow_cli-0.42.0}/CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md
 
-> Project memory hub for **Claude Code**. The universal coding-agent rules for any tool (Cursor, Codex, Aider, Gemini CLI, etc.) live in [AGENTS.md](AGENTS.md) — this file carries Claude-Code-specific session protocol only.
+> Project memory hub for **Claude Code**. The universal coding-agent rules for any tool (Cursor, Codex, Aider, Antigravity, etc.) live in [AGENTS.md](AGENTS.md) — this file carries Claude-Code-specific session protocol only.
 
 ## What this project is
 

gflow_cli-0.42.0/CONFIGURATION.md

@@ -0,0 +1,39 @@
+# gflow-cli Configuration Reference
+
+## Environment variables
+
+| Env var | Default | Description |
+|---|---|---|
+| `GFLOW_CLI_HOME` | Platform data dir | Root directory for profiles and config. |
+| `GFLOW_CLI_OUTPUT_DIR` | `~/Downloads/gflow-cli` | Where generated images and videos are saved. |
+| `CHROME_BINARY` | (autodetect) | Override Chrome binary path. Falls back to platform-standard locations. |
+| `GFLOW_CLI_CONCURRENCY` | `4` | Maximum parallel API requests per batch. |
+| `GFLOW_CLI_GEMINI_API_KEY` | _(unset)_ | Public Gemini key enabling prompt expansion (`-e`/`--expand`). Unset = expansion is a graceful no-op. [Get one](https://aistudio.google.com/apikey). |
+| `GFLOW_CLI_GEMINI_MODEL` | `gemini-2.5-flash` | Gemini model used for prompt expansion. |
+| `GFLOW_LIVE` | _(unset)_ | Set to `1` to enable live-API test markers (`@pytest.mark.live`). |
+
+---
+
+## Browser
+
+There is no `GFLOW_CLI_BROWSER` mode switch — the production path is
+`UiAutomationTransport`, a Playwright persistent context using Playwright's
+own internal CDP port (never externally exposed). A separate packaged
+CDP attach/spawn lifecycle (`auto`/`fresh`/`cdp:<port>` modes, a port-probe
+range, and a `.gflow-cdp.lock` file) previously existed in
+`browser_manager.py` but had no CLI wiring and no production consumer; it
+was removed 2026-07-19 (see `.superpowers/sdd/cdp-decision.md`). Only Chrome
+binary discovery remains, used to pick a channel for the real transport.
+
+### Chrome binary autodetection order
+
+1. `CHROME_BINARY` env var (checked first — always wins)
+2. `shutil.which("chrome")` / `shutil.which("google-chrome")` / `shutil.which("chromium")`
+3. Platform-standard paths:
+   - **Windows**: `C:\Program Files\Google\Chrome\Application\chrome.exe`,
+     `C:\Program Files (x86)\Google\Chrome\Application\chrome.exe`,
+     `%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe`
+   - **macOS**: `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`
+   - **Linux**: `/usr/bin/google-chrome`, `/usr/bin/chromium`, `/usr/bin/chromium-browser`
+
+If Chrome is not found, gflow-cli raises a `ConfigurationError` with an install hint.

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

@@ -275,26 +275,6 @@ Re-running `auth login` reuses the existing profile dir (you typically just clic
 
 ---
 
-### Same profile can't be used in parallel
-
-- **Status:** Open (by design) · **Severity:** Low · **Affects:** all versions
-
-Chromium refuses to open two persistent contexts on the same `user-data-dir` simultaneously. So running two concurrent `gflow ...` calls with the same `--profile` will fail the second one with a "ProcessSingleton: profile is locked" error.
-
-**Workaround:** use different profiles for parallel work.
-
-```bash
-# Terminal 1
-gflow video batch ./batch-a.tsv --profile work
-
-# Terminal 2 — different profile, same time, OK
-gflow video batch ./batch-b.tsv --profile personal
-```
-
-**Roadmap:** Phase 4 (v0.4.0a2) added concurrency *inside* one `gflow-cli` process via `GFLOW_CLI_CONCURRENCY=N` (per-worker Page pool on one shared BrowserContext). Cross-process same-profile serialization is a Chromium constraint we cannot work around without rewriting the auth model — multiple shells against the same profile remains a "use different profiles" workaround.
-
----
-
 ### Chromium cookie database locks block yt-dlp integrations (Instagram/restricted download paths)
 
 - **Status:** Mitigated · **Severity:** Low-Medium · **Affects:** any downstream helper calling `yt-dlp` (including `claude-video`, `cg-decode`/`refanalyzer`, or `experience-vault`)
@@ -364,36 +344,35 @@ playwright._impl._errors.TimeoutError: Locator.click: Timeout 30000ms exceeded.
 
 ---
 
-### Aspect-ratio support depends on the Veo / Imagen model version
+### `gflow serve` / MCP worker queue: interrupted post-submit tasks need manual reconciliation
 
-- **Status:** Open · **Severity:** Low
+- **Status:** Open (by design — no automated reconciliation) · **Severity:** Low · **Affects:** `gflow serve` daemon and MCP worker paths only (not the plain CLI, which has no queue)
 
-Currently confirmed:
-- Veo I2V: `9:16`, `16:9`, `1:1`
-- Imagen: `1:1`, `9:16`, `16:9`, `4:3`, `3:4`
+The worker queue (`generation_queue`, used by the `gflow serve` daemon and MCP tool calls) checkpoints every task's progress through `claimed` → `submit_attempted` → `remote_started` → terminal. If a task is interrupted (daemon restart, crash, or cancellation) while still `claimed` (before any submit), gflow-cli safely marks it `failed` — nothing was spent, safe to retry. But if it's interrupted at `submit_attempted` or `remote_started` — **after** the credit-spending submit click may have fired — it is marked `indeterminate` instead: a credit *may* have been spent and the outcome is unknown. An `indeterminate` task is **never** silently reported as `failed` and **never** auto-resubmitted (that could double-spend a credit for one generation).
 
-Other ratios may be silently rejected or coerced server-side. We validate in the CLI to whitelisted values to fail fast.
+**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).
 
----
+**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 video batch` does not skip already-completed entries
+**Queue payload schema (V0/V1):** the queue's `payload_json` carries an additive `schema_version` key. A payload with no `schema_version` key is legacy **V0** and decodes with the same field lookups as **V1** (the shape is otherwise identical) — both remain readable. The codec always *writes* the current version (`1`) on any re-encode. Any other version is treated as unknown and rejected with `QueueSchemaError` (**exit code 30**) rather than interpreted optimistically — this is a fail-closed guard against decoding a payload written by an incompatible future (or hand-edited) version.
 
-- **Status:** Open · **Severity:** Medium · **Affects:** v0.2.0a1+
+---
 
-If a `gflow video batch` run dies partway through (auth expiry, network blip, Ctrl-C) and you rerun the same TSV manifest, every row is re-submitted to Flow. Flow's private API does not expose a "have I generated this before?" predicate, and `gflow-cli` does not yet maintain a local manifest-of-outputs to compare against.
+### Aspect-ratio support depends on the Veo / Imagen model version
 
-**Cost implication:** re-running a partially completed manifest **may consume additional Veo / Imagen credits**. We cannot guarantee that Flow de-duplicates server-side — credit accounting on a private API is not contractual.
+- **Status:** Open · **Severity:** Low
 
-**Workaround:** before rerunning, trim the manifest down to the rows whose `output_path` does not yet exist on disk:
-```bash
-awk -F'\t' 'NR==1 || (system("test -e " $NF) != 0)' manifest.tsv > manifest.remaining.tsv
-gflow video batch manifest.remaining.tsv
-```
+Currently confirmed:
+- Veo I2V: `9:16`, `16:9`, `1:1`
+- Imagen: `1:1`, `9:16`, `16:9`, `4:3`, `3:4`
 
-**Roadmap:** under consideration for Phase 6 (operations history with a local SQLite ledger — see `PLAN.md`).
+Other ratios may be silently rejected or coerced server-side. We validate in the CLI to whitelisted values to fail fast.
 
 ---
 
+
 ### REST API 401 — all `aisandbox-pa.googleapis.com` generation endpoints blocked
 
 - **Status:** **RESOLVED in v0.7.0** — image generation live-verified end-to-end
@@ -606,31 +585,37 @@ one of the 14 supported locales or in English.
 
 ---
 
-### `omni-flash` t2v response omits operation name — `flow_operation_id` persists NULL
+### t2v response can omit operation name — `flow_operation_id` persists NULL
 
 - **Status:** Open · **Severity:** Low · **Affects:** v0.9.0+ (data layer)
 
 The data layer's `on_started` callback captures
 `operations[0].operation.name` from each `batchAsyncGenerateVideoText`
-response and persists it as `operations.flow_operation_id`. The
-`omni-flash` model's response shape does not carry that field, so
-omni-flash rows end up with `flow_operation_id` NULL while `veo-*` rows
-carry the expected `operations/...` identifier. The rest of the row
-(prompt, model, aspect, started/completed timestamps, batch ID, output
-paths) is recorded normally.
-
-**Impact:** cosmetic for now — `gflow data media <id>` and provenance
-lookup by Flow media ID still work. Any future feature that joins on
-`flow_operation_id` (none in the current CLI) would miss omni-flash
-rows.
+response and persists it as `operations.flow_operation_id`. This field
+is **best-effort, not guaranteed for any model**: `omni-flash`'s response
+shape does not carry it, so omni-flash rows end up with
+`flow_operation_id` NULL. **Update 2026-07-21 (live):** the same NULL
+was observed on a live `veo-lite` t2v run (`remote_started` checkpoint
+with `operation_id=None`), on an agentic-UI-cohort account — so `veo-*`
+is not a reliable guarantee either; the original claim that veo-* rows
+always carry the operation name was false. The rest of the row (prompt,
+model, aspect, started/completed timestamps, batch ID, output paths) is
+recorded normally regardless.
+
+**Impact:** cosmetic/provenance-only — `media_id` is the canonical
+handle (poll, download, and every CLI lookup use it, not
+`flow_operation_id`). `gflow data media <id>` and provenance lookup by
+Flow media ID still work. Nothing in the current CLI queries by
+`flow_operation_id`; a future feature that did would miss rows on any
+model whose response omits the operation name.
 
 **Workaround:** none needed if you don't query by `flow_operation_id`.
 
-**Roadmap:** capture an `omni-flash` `batchAsyncGenerateVideoText`
-response sample, identify the equivalent provenance handle (if any), and
-either map it into `flow_operation_id` or document that omni-flash
-legitimately has no such identifier. Track via a follow-up issue once a
-sample is captured.
+**Roadmap:** capture response samples across models (including veo-lite)
+where the operation name is absent, identify the equivalent provenance
+handle (if any), and either map it into `flow_operation_id` or document
+that these cases legitimately have no such identifier. Track via a
+follow-up issue once samples are captured.
 
 ---
 
@@ -749,8 +734,44 @@ key — surfaces as a `RuntimeError` that `auth/cookies.py` normalizes to
 
 ---
 
+### Same profile can't be used in parallel
+
+- **Status:** Mitigated (crash → typed fail-fast rejection) · **Severity:** Low · **Affects:** all versions
+
+Chromium refuses to open two persistent contexts on the same `user-data-dir` simultaneously. Historically this surfaced as an unhelpful Chromium "ProcessSingleton: profile is locked" error partway through a run. As of the profile-lease hardening (production-readiness plan, slice D1/D3), gflow-cli enforces this itself: a cross-process advisory lock (`ProfileLease`, kernel `flock` on POSIX / `msvcrt.locking` on Windows) guards every profile directory. A second `gflow` invocation, `gflow serve` daemon task, or MCP call against an already-leased profile is rejected **immediately** — before any Chrome process starts — with a typed `ProfileLockedError` (**exit code 11**); it never waits and never silently corrupts the profile.
+
+**Workaround:** use different profiles for parallel work — different profiles acquire independent leases and run fully concurrently.
+
+```bash
+# Terminal 1
+gflow image batch ./batch-a.tsv --profile work
+
+# Terminal 2 — different profile, same time, OK
+gflow image batch ./batch-b.tsv --profile personal
+```
+
+**Roadmap:** Phase 4 (v0.4.0a2) added a per-worker Page pool on one shared BrowserContext (`GFLOW_CLI_CONCURRENCY=N`), intended to let one `gflow-cli` process fan out multiple in-flight generations, but no current CLI command drives more than one generation at a time through it — the only feature that did (a manifest-driven video batch runner) never worked and was removed. Cross-process same-profile serialization remains a hard constraint (Chromium can only own one persistent context per `user-data-dir`) — but it is now a clean, typed, fail-fast rejection instead of an unstructured crash. Multiple shells against the same profile remains a "use different profiles" workaround; there is no queueing/waiting mode.
+
+---
+
 ## Resolved
 
+### `gflow video`'s manifest-driven batch subcommand didn't skip already-completed entries — RESOLVED as obsolete
+
+- **Status:** Resolved (obsolete) · **Severity:** Was-Medium · **Was-affecting:** v0.2.0a1 through the command's removal · **Fixed in:** n/a — removed in production-readiness hardening (see `fix: remove nonfunctional video batch command`)
+
+This entry described a gap in `gflow video`'s `batch` subcommand: it never
+maintained a local manifest-of-outputs, so rerunning a partially completed
+TSV manifest after a mid-run failure would re-submit already-rendered rows
+and could burn additional credits. The command itself, however, never
+actually worked end-to-end — it always exited with a stub error before
+reaching Flow — so no run could have been "partially completed" in the
+first place. It has since been removed entirely as a nonfunctional stub.
+The underlying command no longer exists, so this gap is moot rather than
+fixed; kept here for searchability. `gflow image batch` (the real, working
+batch command) is unaffected. For video, loop `gflow video t2v`/`i2v` from
+the shell — see [`docs/USAGE.md` § Batch video generation (shell loop)](docs/USAGE.md#batch-video-generation-shell-loop).
+
 ### False "forced agentic — not recoverable" aborts from an icon-heuristic cohort probe
 
 - **Status:** Resolved · **Severity:** Was-Medium (spurious exit-25 aborts on profiles that could in fact reach classic mode) · **Was-affecting:** `--ui-mode classic` and classic-only operations through v0.37.0 · **Fixed in:** 0.38.0 · **Tracked:** [#299](https://github.com/ffroliva/gflow-cli/issues/299), [#332](https://github.com/ffroliva/gflow-cli/issues/332)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.40.0
+Version: 0.42.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
@@ -58,7 +58,7 @@ Requires-Dist: numpy>=1.24; extra == 'dev'
 Requires-Dist: pyright>=1.1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
-Requires-Dist: ruff==0.15.21; extra == 'dev'
+Requires-Dist: ruff==0.15.22; extra == 'dev'
 Provides-Extra: gcs
 Requires-Dist: gcsfs>=2024.2.0; extra == 'gcs'
 Requires-Dist: universal-pathlib>=0.2.5; extra == 'gcs'
@@ -161,7 +161,7 @@ gflow-cli ships four agent entry points. Pick the one your tool reads first.
 
 | File | Audience | Tools |
 |---|---|---|
-| [**AGENTS.md**](AGENTS.md) | Universal coding-agent spec | Cursor · Codex · Aider · Gemini CLI · Jules · Devin · Windsurf · Zed · Warp · opencode · Copilot |
+| [**AGENTS.md**](AGENTS.md) | Universal coding-agent spec | Cursor · Codex · Aider · Antigravity · Jules · Devin · Windsurf · Zed · Warp · opencode · Copilot |
 | [**CLAUDE.md**](CLAUDE.md) | Claude Code's auto-loaded memory | Claude Code |
 | [**llms.txt**](llms.txt) | LLM-readable summary (llmstxt.org format) | Paste into ChatGPT, Claude, or Gemini to onboard the model |
 | [`skills/gflow-cli/SKILL.md`](skills/gflow-cli/SKILL.md) | Claude Code Skill | Symlink into `~/.claude/skills/` |
@@ -175,7 +175,7 @@ Onboard any agent in one line. Paste this into your agent of choice:
 ```text
 gflow CLI  →  Provider (interchangeable)  →  Flow (ui_automation) / Mock (tests) / [planned: Official Veo]
                                               ↓
-                                      Playwright Chromium (headed login, headless after)
+                                      Playwright Chromium (headed — login AND generation, by default)
                                               ↓
                               aisandbox-pa.googleapis.com  (Google's private Flow API)
 ```
@@ -188,7 +188,7 @@ gflow CLI  →  Provider (interchangeable)  →  Flow (ui_automation) / Mock (te
 
 ## Project status
 
-**Alpha.** Image (t2i, i2i, upload, upscale, batch) and video (t2v, i2v, r2v, batch, chain) run end-to-end on `ui_automation`, with a 5-model Veo picker plus `--duration` and `--count`. Beyond single generations: `gflow movie` renders multi-scene manifests, `gflow instructions` manages persistent Agent-Mode brief cards (credits-free), `gflow character` handles reusable subjects, `gflow scene` does credit-free server-side stitching, `--tool` applies prompt-rewriting tools, and an MCP server (`gflow mcp run` stdio / `gflow serve` HTTP-SSE) exposes the core surface to AI agents with a CI-enforced CLI↔MCP parity contract.
+**Alpha.** Image (t2i, i2i, upload, upscale, batch) and video (t2v, i2v, r2v, chain) run end-to-end on `ui_automation`, with a 5-model Veo picker plus `--duration` and `--count`. Beyond single generations: `gflow movie` renders multi-scene manifests, `gflow instructions` manages persistent Agent-Mode brief cards (credits-free), `gflow character` handles reusable subjects, `gflow scene` does credit-free server-side stitching, `--tool` applies prompt-rewriting tools, and an MCP server (`gflow mcp run` stdio / `gflow serve` HTTP-SSE) exposes the core surface to AI agents with a CI-enforced CLI↔MCP parity contract.
 
 Full milestone history lives in [CHANGELOG.md](CHANGELOG.md). Where the project is heading: [ROADMAP.md](ROADMAP.md).