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

gflow_cli-0.41.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.41.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.41.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.41.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.41.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.41.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.41.0}/AGENTS.md

@@ -8,8 +8,8 @@ Supported tools that auto-discover this file: Cursor, Codex, Aider, Jules, Devin
 
 - 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)
 
@@ -98,6 +99,7 @@ The `skills/` directory ships installable agent skill docs in plain Markdown wit
 | `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 |
 

{gflow_cli-0.40.0 → gflow_cli-0.41.0}/CHANGELOG.md

@@ -7,6 +7,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +2169,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.40.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.41.0...HEAD
+[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.41.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.41.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
@@ -749,8 +728,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.41.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.40.0
+Version: 0.41.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'
@@ -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).
 

{gflow_cli-0.40.0 → gflow_cli-0.41.0}/PLAN.md

@@ -667,6 +667,8 @@ Records image, batch, T2V, I2V, and R2V provenance in a local SQLite catalog. Re
 
 **2026-07-09 verification — the current stealth fix is CONFIRMED SUFFICIENT (so this stays parked).** A 20-generation baseline on a live authed profile through the default stealth stack produced a **0.0% WAF 403 rate** (19/20 success; the one miss was a UI-scrape timeout, not a WAF block). This met ADR-13's "must verify before implementing" gate and closed the [Camoufox adoption roadmap](superpowers/plans/2026-07-09-camoufox-adoption/PLAN.md) at Phase 2 — the Camoufox engine was NOT built. Evidence: [superpowers/spikes/2026-07-09-camoufox-waf-403.md](superpowers/spikes/2026-07-09-camoufox-waf-403.md). Re-run `scripts/spike_waf_camoufox.py` if a repeatable WAF-403 is later observed; a materially non-zero rate would reopen CDP-Attach / Camoufox.
 
+**2026-07-19 — packaged CDP lifecycle removed.** The unused CDP attach/spawn lockfile lifecycle that previously shipped in `browser_manager.py` (`get_or_launch_browser` / `close_browser` and its port/lockfile/singleton-lock helpers) was deleted: zero production consumers, an unsafe no-lock attach-to-any-Chrome path, and no positive evidence outweighing the 2026-05-12 WAF rejection above. Chrome discovery/channel helpers (`is_chrome_available`, `channel_for_profile`, etc.) — used by the real auth/UI-automation path — were kept. This ADR's "parked" status is unchanged: CDP-attach as a distinct opt-in transport remains a backlog idea for a future contributor with a safe ownership model; see `.superpowers/sdd/cdp-decision.md` for the evidence.
+
 ---
 
 ### Phase 8 — Pluggable storage backend — BACKLOG

{gflow_cli-0.40.0 → gflow_cli-0.41.0}/README.md

@@ -104,7 +104,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)
 ```
@@ -117,7 +117,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).
 

{gflow_cli-0.40.0/website → gflow_cli-0.41.0}/docs/ARCHITECTURE.md

@@ -283,10 +283,10 @@ def generate(prompt: str) -> None:
 ## Concurrency model (shipped, Phase 4 / v0.4.0a2)
 
 - **Single-process, single-event-loop** (`asyncio`). No multiprocessing, no application-level threads (only what Playwright uses internally).
-- **Within one `gflow video batch`:** `FlowApiClient.__aenter__` opens `Settings.concurrency` Playwright Pages inside **one shared persistent `BrowserContext`**. Operations check out a Page via an `asyncio.Queue` (FIFO, bounded by `maxsize=N`); a double-checkin raises `QueueFull` loudly rather than corrupting the pool. `gflow video batch` fans out manifest entries via `asyncio.gather`. See `gflow_cli.api.client.FlowApiClient._checkout_page` / `_checkin_page`.
+- **Page pool:** `FlowApiClient.__aenter__` opens `Settings.concurrency` Playwright Pages inside **one shared persistent `BrowserContext`**. Operations check out a Page via an `asyncio.Queue` (FIFO, bounded by `maxsize=N`); a double-checkin raises `QueueFull` loudly rather than corrupting the pool. See `gflow_cli.api.client.FlowApiClient._checkout_page` / `_checkin_page`. **No current CLI command drives more than one generation concurrently through this pool** — the one caller that used to fan out manifest entries via `asyncio.gather` (a manifest-driven video batch runner) never worked end-to-end and was removed as a nonfunctional stub; `gflow image batch` processes its manifest sequentially.
 - **Across profiles:** parallelism by spawning one shell per profile. Chromium refuses two persistent contexts on the same `user-data-dir`, so cross-profile parallelism is a process-level concern, not a coroutine one. See [KNOWN_ISSUES § Same profile can't be used in parallel](../KNOWN_ISSUES.md#same-profile-cant-be-used-in-parallel).
 - **Why a Page pool and not a `Semaphore`?** A semaphore over a single shared Page would serialize at `page.request.post` anyway (Playwright doesn't make a Page thread-safe). N Pages inside one Context let Chromium pipeline the requests while still sharing the auth cookies. T0 of the Phase 4 spike measured ~45 ms per Page creation at N=16 — well under the 200 ms/Page threshold.
-- **What's backlog (post-v0.5):** account-pool aware scheduling across multiple signed-in profiles (round-robin), and a separate-process driver so two `gflow video batch` invocations against the same profile can serialize properly via OS file lock.
+- **What's backlog (post-v0.5):** a concurrent caller that actually exercises the Page pool above `N=1`, account-pool aware scheduling across multiple signed-in profiles (round-robin), and a separate-process driver so two concurrent invocations against the same profile can serialize properly via OS file lock.
 
 ## Observability (shipped, Phase 4 / v0.4.0a2)
 

{gflow_cli-0.40.0 → gflow_cli-0.41.0}/docs/AUTHENTICATION.md

@@ -36,14 +36,17 @@ This page documents the full lifecycle: capture, storage, reuse, refresh, multi-
                               └────────────┬─────────────────────────┘
                                            │
                                            ▼
-  $ gflow image t2i ...                    (later, headless)
+  $ gflow image t2i ...                    (later, headed by default)
                                            │
                                            ▼
                               ┌──────────────────────────────────────┐
-                              │  Playwright launches HEADLESS        │
-                              │  Chromium with the same profile dir; │
-                              │  page.request.post(...) auto-sends   │
-                              │  cookies. No token plumbing needed.  │
+                              │  Playwright launches HEADED Chrome   │
+                              │  with the same profile dir (the      │
+                              │  production default — reCAPTCHA      │
+                              │  Enterprise rejects headless outright│
+                              │  with a 403); page.request.post(...) │
+                              │  auto-sends cookies. No token         │
+                              │  plumbing needed.                     │
                               └──────────────────────────────────────┘
 ```
 
@@ -342,9 +345,9 @@ gflow image t2i "test"          --profile personal
 gflow image t2i "client work"   --profile client-a
 ```
 
-Each profile is fully isolated (its own cookies, its own Flow project history). You can run multiple `gflow` calls concurrently across profiles since each launches its own Chromium context — but **never run two concurrent calls against the same profile**, because Chromium will refuse to open a second persistent context on a locked user-data-dir.
+Each profile is fully isolated (its own cookies, its own Flow project history). **Different profiles run fully in parallel** — each acquires its own cross-process `ProfileLease` on its own canonical directory, so concurrent `gflow` calls across profiles never contend. **The same profile can only ever have one active holder.** A cross-process advisory lock (`ProfileLease`, kernel `flock`/`msvcrt.locking`) enforces this fail-fast: a second call against an already-leased profile — whether it's another `gflow` invocation, the `gflow serve` daemon, or an MCP tool call — is rejected immediately with `ProfileLockedError` (exit code 11); it never blocks or waits for the lease to free up.
 
-For automated multi-account batching: concurrency *within* one profile shipped in v0.4.0a2 — set `GFLOW_CLI_CONCURRENCY=N` (1–16) and `gflow video batch` fans out across N Playwright Pages on one shared BrowserContext. Cross-profile parallel batches are still "one shell per profile" (Chromium per-profile lock; see [KNOWN_ISSUES § Same profile can't be used in parallel](../KNOWN_ISSUES.md#same-profile-cant-be-used-in-parallel)).
+For automated multi-account work: a per-profile Page pool (`GFLOW_CLI_CONCURRENCY=N`, 1–16, shipped in v0.4.0a2) opens N Playwright Pages on one shared BrowserContext within a single profile, but no current CLI command drives more than one generation concurrently through it — the one caller that used to (a manifest-driven video batch runner) never worked and was removed. Cross-profile parallel runs remain "one shell per profile"; same-profile contention is a fast, typed rejection rather than a Chromium crash (see [KNOWN_ISSUES § Same profile can't be used in parallel](../KNOWN_ISSUES.md#same-profile-cant-be-used-in-parallel)).
 
 ## Refresh / expiry
 
@@ -400,7 +403,7 @@ For deeper guidance see [SECURITY.md](SECURITY.md).
 ## FAQ
 
 **Q: Can I use `gflow-cli` without a browser at all?**
-A: Not for `auth login` — that step needs Chromium so you can solve any 2FA/CAPTCHA challenge interactively. After login, all generation calls run headless. Plan to use a workstation for the one-time auth, then copy the profile dir to a headless server (re-running `auth login` there is recommended though, see threat model above).
+A: No — not for `auth login`, and not for generation either. `auth login` needs Chromium so you can solve any 2FA/CAPTCHA challenge interactively. Generation calls also launch a real, **headed** Chrome window by default (`GFLOW_CLI_HEADLESS=false`) — the `ui_automation` transport is gflow-cli's only production transport, and reCAPTCHA Enterprise rejects headless Chromium with an immediate 403, so there is no way to run production generation on a display-less machine without a virtual display (e.g. Xvfb) or a workstation. Plan for that when choosing where to run gflow-cli long-term; see [CONFIGURATION.md § `GFLOW_CLI_HEADLESS`](CONFIGURATION.md#gflow_cli_headless).
 
 **Q: Does this support Google Workspace SSO?**
 A: Yes — sign in normally during `auth login`. Whatever your IdP flow looks like in the browser, that's what you'll go through. The captured cookies are the same.

{gflow_cli-0.40.0 → gflow_cli-0.41.0}/docs/CONFIGURATION.md

@@ -178,10 +178,10 @@ GFLOW_CLI_AUTH_LOGIN_TIMEOUT=120 gflow auth login   # abort after 2 minutes
 
 ### `GFLOW_CLI_CONCURRENCY`
 
-**What:** Per-worker Playwright Page-pool size for batch runs. `FlowApiClient.__aenter__` opens N Pages inside one shared persistent BrowserContext; operations check out a Page via an `asyncio.Queue` (FIFO, bounded by `maxsize=N`). `gflow video batch` fans out manifest entries via `asyncio.gather`.
+**What:** Per-worker Playwright Page-pool size. `FlowApiClient.__aenter__` opens N Pages inside one shared persistent BrowserContext; operations check out a Page via an `asyncio.Queue` (FIFO, bounded by `maxsize=N`). No current CLI command fans out multiple generations concurrently through this pool — `gflow image batch` processes prompts sequentially, and the manifest-driven video runner that used to fan out via `asyncio.gather` was removed as nonfunctional — so raising this above `1` has no effect until a concurrent caller exists.
 **Values:** `1`–`16`
 **Default:** `1` (no fan-out)
-**Recommended starting point:** `4`. Each Page costs ~30–60 MiB of memory on Chromium headless; don't exceed `8` without measuring resident-set size. Cookies and storage state are shared at Context level, so every Page inherits the signed-in profile for free.
+**Recommended starting point:** `1` until a concurrent caller lands. Each additional Page would cost ~30–60 MiB of memory on Chromium headless; don't exceed `8` without measuring resident-set size. Cookies and storage state are shared at Context level, so every Page would inherit the signed-in profile for free.
 **Shipped in:** v0.4.0a2.
 
 ### `GFLOW_CLI_DB_PATH`
@@ -218,8 +218,8 @@ GFLOW_CLI_HISTORY_PROMPTS=redacted gflow image t2i "confidential brief"
 
 **What:** Run Playwright in headless mode for non-`auth login` commands.
 **Values:** `true` | `false`
-**Default:** `true`
-**When to flip to `false`:** if reCAPTCHA Enterprise refuses to mint tokens (Google's bot-detection sometimes refuses headless Chromium but accepts a visible window). Set to `false` and re-run; the browser will appear during generation but the session is still reused from the persistent profile.
+**Default:** `false` — **headed real Chrome is the production default**, not an opt-in fallback. The `ui_automation` transport (gflow-cli's only production transport) requires a headed browser: reCAPTCHA Enterprise rejects headless Chromium with an immediate 403, so `headless=true` is not a WAF workaround — it only exists for CI/CD environments running a non-`ui_automation` transport (e.g. `bearer`/`sapisidhash`, experimental).
+**WAF-sensitive runs:** set `GFLOW_CLI_HEADLESS=false` explicitly (it is already the default, but pin it in CI/CD env files or scripts that also set `headless=true` for a different transport, so a transport switch back to `ui_automation` doesn't silently regress to a rejected headless launch).
 
 ### `GFLOW_CLI_BROWSER_ENGINE`
 
@@ -311,8 +311,8 @@ gflow image t2i "..." --out ./shots/
 # Video: --out-dir is a directory for the generated mp4
 gflow video t2v "..." --out-dir ./out/
 
-# Video batch: --out-dir overrides the videos/<date>/ root
-gflow video batch ./manifest.tsv --out-dir ./batch-out/
+# Image batch: --out overrides the images/<date>/ root
+gflow image batch ./manifest.tsv --out ./batch-out/
 
 # Video chain: --out-dir holds the per-link mp4s + seed frames
 gflow video chain ./story.jsonl --out-dir ./chain-out/ --yes
@@ -397,7 +397,7 @@ See [EXTERNAL_STORAGE.md](EXTERNAL_STORAGE.md) for MinIO and GCS examples.
 ```bash
 GFLOW_CLI_LOG_FORMAT=json \
 GFLOW_CLI_TIMEOUT_SECONDS=300 \
-gflow video batch ./manifest.tsv
+gflow image batch ./manifest.tsv
 ```
 
 ### "I want to test against the official Veo SDK"
@@ -426,4 +426,4 @@ gflow image t2i "test idea" --profile experiments
 | `FileNotFoundError: $GFLOW_CLI_HOME/profile_default not found` | First run, no auth yet | `gflow auth login` |
 | `AuthExpiredError` | Cookies expired or revoked | `gflow auth login --profile <name>` |
 | Output files don't appear where I expect | Flag > env > .env > default — check actual resolved path | `gflow image t2i ... --verbose` shows the resolved output path |
-| Two concurrent calls fail with "Chromium profile locked" | Same profile used twice | Use `--profile other` for the second call |
+| `ProfileLockedError` (exit code 11) | Two concurrent calls against the same profile — the cross-process `ProfileLease` fails fast (never waits) on same-profile contention, whether the second holder is another `gflow` process, the `gflow serve` daemon, or an MCP call | Wait for the first call to finish, or use `--profile other` — different profiles run fully in parallel, each with its own lease |