gflow-cli 0.84.0__tar.gz → 0.86.0__tar.gz

gflow_cli-0.86.0/.codex-plugin/plugin.json

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

gflow_cli-0.86.0/.env.template

@@ -0,0 +1,272 @@
+# gflow-cli — example environment variables.
+# Copy to `.env` in the directory where you invoke `gflow` (project-local
+# overrides) or to `$GFLOW_CLI_HOME/.env` (machine-wide defaults; used by
+# processes with arbitrary working directories, e.g. the MCP server) and
+# uncomment what you want to override. On conflicts the CWD `.env` wins.
+# All variables are OPTIONAL — defaults work out of the box for most users.
+# Lines below are commented to show the SHIPPED DEFAULT — uncomment to override.
+
+# -----------------------------------------------------------------------------
+# Auth & profiles
+# -----------------------------------------------------------------------------
+
+# Root directory for Playwright persistent contexts (signed-in Google sessions).
+# Default (via `platformdirs`):
+#   Windows: %LOCALAPPDATA%\gflow-cli                    (e.g. C:\Users\<you>\AppData\Local\gflow-cli)
+#   macOS:   ~/Library/Application Support/gflow-cli
+#   Linux:   $XDG_DATA_HOME/gflow-cli                    (typically ~/.local/share/gflow-cli)
+# GFLOW_CLI_HOME=
+
+# Default profile name. When unset, the resolution chain auto-picks (see
+# docs/CONFIGURATION.md § GFLOW_CLI_PROFILE). Override per-call with
+# `--profile <name>`.
+# GFLOW_CLI_PROFILE=default
+
+# Maximum wait time (seconds) for `gflow auth login` to complete Google sign-in.
+# Useful for agent pipelines — set low to surface hung logins as exit 12 fast.
+# GFLOW_CLI_AUTH_LOGIN_TIMEOUT=600
+
+# Anti-bot pause between prompt submissions in multi-prompt image runs
+# (image batch, t2i --prompts-file/--stdin, gflow run). 'MIN-MAX' seconds, a
+# single number for 0-N, or 0 to disable. Default 0.5-1.5 (small on purpose);
+# widen (e.g. 10-30) if runs hit WAF 403s. The --jitter flag beats this.
+# See docs/CONFIGURATION.md § GFLOW_CLI_JITTER_RANGE.
+# GFLOW_CLI_JITTER_RANGE=0.5-1.5
+
+# -----------------------------------------------------------------------------
+# Output paths
+# -----------------------------------------------------------------------------
+
+# Where downloaded assets land. Subfolders are created per kind/date:
+#   <output_dir>/images/<YYYY-MM-DD>/<job_id>_<index>.png
+#   <output_dir>/videos/<YYYY-MM-DD>/<job_id>.mp4
+#
+# Default (via `platformdirs`):
+#   Windows: %USERPROFILE%\Downloads\gflow-cli
+#   macOS:   ~/Downloads/gflow-cli
+#   Linux:   $XDG_DOWNLOAD_DIR/gflow-cli  (falls back to ~/Downloads/gflow-cli)
+# GFLOW_CLI_OUTPUT_DIR=
+
+# -----------------------------------------------------------------------------
+# Provider selection
+# -----------------------------------------------------------------------------
+
+# Backend to use for generations.
+#   flow      - reverse-engineered Flow REST API (default, requires Ultra/Pro)
+#   official  - official Veo SDK (planned for v0.5+, requires Gemini API key)
+# GFLOW_CLI_PROVIDER=flow
+
+# -----------------------------------------------------------------------------
+# Prompt tools LLM (--tool creative-director / reverse-engineer / storyboard)
+#
+# Any OpenAI-compatible Chat Completions endpoint: OpenAI, OpenRouter, a
+# corporate gateway, a local proxy, Ollama, or Google's compat endpoint.
+# Provider keys stay with your gateway — gflow only holds the one credential it
+# presents to the endpoint below.
+#
+# NOTE: GFLOW_CLI_GEMINI_API_KEY / GFLOW_CLI_GEMINI_MODEL were REMOVED in
+# v0.46.0 and are not forwarded. Use GFLOW_CLI_LLM_API_KEY — an existing Google
+# AIza… key still works, since the default endpoint is Google's compat surface.
+# -----------------------------------------------------------------------------
+
+# Endpoint. This is the on/off switch for the prompt tools.
+# https only, except loopback (127.0.0.1 / localhost / ::1) which may use http.
+# Use 127.0.0.1 rather than localhost — gateways often bind IPv4 only and
+# Windows resolves ::1 first, which stalls.
+# GFLOW_CLI_LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
+
+# Credential for that endpoint (Authorization: Bearer). OPTIONAL — omit it for a
+# keyless local gateway and no header is sent at all.
+# Google key: https://aistudio.google.com/apikey
+# GFLOW_CLI_LLM_API_KEY=
+
+# Model, which is also the provider selector since gateways route on it
+# (e.g. openai/gpt-4o-mini). Unset = the gateway chooses.
+# GFLOW_CLI_LLM_MODEL=
+
+# -----------------------------------------------------------------------------
+# Cloud storage
+# -----------------------------------------------------------------------------
+
+# Upload generated assets directly to a cloud bucket instead of saving local
+# asset copies. Supported schemes:
+#   gs://   – Google Cloud Storage (requires: pip install 'gflow-cli[gcs]')
+#   s3://   – Amazon S3 or any S3-compatible store, e.g. MinIO
+#             (requires: pip install 'gflow-cli[s3]')
+#
+# Examples:
+#   GFLOW_CLI_STORAGE_URI=gs://my-gcs-bucket/gflow/
+#   GFLOW_CLI_STORAGE_URI=s3://my-s3-bucket/gflow/
+#   GFLOW_CLI_STORAGE_URI=s3://gflow-test/gflow/   # MinIO local dev
+#
+# For S3 / MinIO you also need the standard AWS SDK env vars:
+#   AWS_ACCESS_KEY_ID=minioadmin
+#   AWS_SECRET_ACCESS_KEY=minioadmin
+#   AWS_ENDPOINT_URL=http://localhost:9000   # omit for real AWS
+#   AWS_DEFAULT_REGION=us-east-1
+#
+# For GCS (local emulator):
+#   STORAGE_EMULATOR_HOST=http://localhost:4443
+#
+# When unset, assets are saved to GFLOW_CLI_OUTPUT_DIR (local disk). gflow-cli
+# does not dual-write local + cloud copies; configure one storage target per run.
+# GFLOW_CLI_STORAGE_URI=
+
+# -----------------------------------------------------------------------------
+# Runtime tuning
+# -----------------------------------------------------------------------------
+
+# Per-request HTTP timeout (seconds). Veo videos can take 60-180s each.
+# GFLOW_CLI_TIMEOUT_SECONDS=600
+
+# Logging level — DEBUG | INFO | WARNING | ERROR
+# GFLOW_CLI_LOG_LEVEL=INFO
+
+# Log format — auto | text | json
+#   auto = text on TTY, json when piped (default)
+# GFLOW_CLI_LOG_FORMAT=auto
+
+# 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
+
+# Seconds to wait for another gflow process to release the profile lease
+# before giving up with ProfileLockedError (0 = fail fast, the default).
+# Holders always run to completion; the waiter takes over on release (#478).
+# GFLOW_CLI_LEASE_WAIT_SECONDS=0
+
+# Once-a-day best-effort PyPI check that shows an update banner on stderr when
+# a newer gflow-cli exists (#479; one plain line when stderr is piped). Never
+# blocks; skipped in CI and for editable/source installs. Set to 0 to disable.
+# Upgrade with `gflow update`.
+# GFLOW_CLI_UPDATE_CHECK=1
+
+# Whether generation prompts (and the prompt-derived display names used as the
+# picker search key) are stored in the local catalog — store | redacted.
+# Under 'redacted', `gflow doctor` reports missing display names as info
+# (backfill is deliberately suppressed) instead of warn, and name backfill via
+# `gflow data sync --names` requires switching back to 'store' first.
+# GFLOW_CLI_HISTORY_PROMPTS=store
+
+# MCP no-spend mode (#496): when set to 1, the MCP server (gflow mcp run AND
+# gflow serve) never registers the credit-spending generate tools — agents
+# cannot see them in tools/list. Equivalent to the --no-spend flag.
+# GFLOW_MCP_NO_SPEND=0
+
+# Run Playwright in headless mode for non-`auth login` commands (true|false).
+# 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
+
+# Screen position X,Y of the headed generation browser. Default -30000,-30000 opens it
+# off-screen: still real headed Chrome (reCAPTCHA unaffected), just not over your
+# desktop. Set 0,0 (or a second monitor's origin) to watch or debug a run; set empty
+# for Chrome's own placement. It does NOT stop Chrome taking keyboard focus at launch.
+# Login windows are always visible: for an account chooser / consent screen, run
+# `gflow auth login --profile <name>` rather than making this window visible.
+# GFLOW_CLI_BROWSER_WINDOW_POSITION=-30000,-30000
+
+# Browser automation engine — playwright (default) | patchright
+# patchright is an OPT-IN, drop-in patched Playwright (Chromium) that avoids the
+# Runtime.enable CDP leak for stronger reCAPTCHA-Enterprise evasion on the HEADED
+# path. It is NOT a headless unlock. Requires a separate install:
+#   pip install patchright        (or: pip install 'gflow-cli[patchright]')
+# When using system Chrome (channel=chrome, the gflow default) you do NOT need
+# `patchright install chromium`. Unset to revert to the default playwright engine.
+# GFLOW_CLI_BROWSER_ENGINE=playwright
+
+# Which Flow UI arm a command needs: auto (default — no arm asked for, so it
+# resolves to classic, the arm that can satisfy a generation request) | classic
+# (require the hard aspect controls) | agentic (require the chat surface; needed
+# for -i instructions). gflow switches to the required arm, verifies via re-probe,
+# and aborts with exit 28 (retryable — the cohort flaps per load) if it can't be
+# reached. -i instructions force agentic automatically. See docs/CONFIGURATION.md.
+# GFLOW_CLI_UI_MODE=auto
+
+# Which Flow frontend gflow drives (#639). auto (default): flow.google.com is the
+# default host for what it can serve today (video t2v; video i2v from a local
+# --initial-frame; video r2v from local --ref files; image t2i; and image i2i from
+# local files — all with --project) on every
+# account; requests it cannot serve yet keep the labs driver on an unmoved
+# account; where Flow serves flow.google.com you get the migrated composer for
+# everything ported to it.
+# flow.google.com: force the migrated composer for everything.
+# labs.google: never use it — where Flow serves flow.google.com, requests fail
+# with exit 36 (kill switch).
+# GFLOW_CLI_FLOW_HOST=auto
+
+# Agent-only composer (#799): "Confirm before generating" applied before a run.
+# account (default): leave the Flow account's setting; gflow approves one
+# confirmation its own submit produced and stops on a second. Only that second
+# one is stopped before billing: one confirmation can cover several clips, and an
+# over-count under it is caught after the fact.
+# always: set Always. never: set Never — no approval step, so an agent that
+# queues more than asked is only caught after credits are spent.
+# Saved to the Flow account and not restored after the run.
+# GFLOW_CLI_AGENT_CONFIRM=account
+
+# DEPRECATED — use GFLOW_CLI_UI_MODE=classic. true maps to ui_mode=classic, but the
+# old silent agentic fallback is gone: a classic-required run now aborts (exit 28).
+# GFLOW_CLI_PREFER_CLASSIC=false
+
+# DEPRECATED — use GFLOW_CLI_UI_MODE=agentic. true maps to ui_mode=agentic.
+# GFLOW_CLI_FORCE_AGENT_UI=false
+
+
+# BCP-47 locale tag passed to Playwright's launch `locale=` parameter
+# (controls Accept-Language only — Chrome's UI language is forced to
+# en-US via the `--lang=en-US` launch arg regardless of this setting, so
+# Flow stays on /fx/tools/flow/ instead of /fx/<locale>/). Default:
+# `en-US`. Override to capture locale-invariant DOM via
+# scripts/dev/capture_locale_invariants.py or to live-verify a non-EN
+# language end-to-end (see KNOWN_ISSUES § issue #24).
+# GFLOW_CLI_LOCALE=en-US
+
+# Display name of the --project project, used by `gflow video i2v` to select
+# the target project in the media picker's project menu when attaching a
+# media-UUID frame (#287 — the menu lists projects by NAME; unnamed projects
+# show only creation timestamps). Same as the `--project-name` flag, which
+# takes precedence when both are set. Escape hatch when automatic name
+# derivation (tab title / page hints) fails.
+# GFLOW_CLI_PROJECT_NAME=
+
+# -----------------------------------------------------------------------------
+# Debugging (see docs/CONFIGURATION.md; HAR/traceback are opt-in and can
+# expose secrets)
+# -----------------------------------------------------------------------------
+
+# Automatic private incident bundles (DEFAULT: true). On relevant operational
+# failures (Flow app crash, UI drift, transport timeout, WAF/network errors,
+# profile-lock contention) gflow writes a bounded diagnostic bundle under
+# <GFLOW_CLI_HOME>/incidents/. Automatic JSON is allowlisted structural
+# metadata only; screenshots live under sensitive/ and must be reviewed
+# before sharing. Nothing is ever uploaded. Set false to disable.
+# GFLOW_CLI_INCIDENT_CAPTURE=true
+
+# Captures full Playwright network traffic (requests, responses, headers,
+# cookies) to this HAR file for the session. SECURITY: a HAR file contains
+# live auth cookies and bearer tokens -- never share one publicly.
+# GFLOW_CLI_HAR_PATH=
+
+# Prints the real exception message + traceback for unhandled errors, to the
+# console and (under --json) into the payload, instead of the generic
+# placeholder. SECURITY: may leak tokens/cookies present in exception text.
+# GFLOW_CLI_DEBUG_TRACEBACK=
+
+# -----------------------------------------------------------------------------
+# Headless Daemon (gflow serve)
+# -----------------------------------------------------------------------------
+
+# API Token header for gflow serve authentication (required when binding to non-local interface, e.g. 0.0.0.0).
+# GFLOW_DAEMON_TOKEN=
+
+# Port for gflow serve. Default is 8000.
+# GFLOW_DAEMON_PORT=8000
+

gflow_cli-0.86.0/.github/workflows/ci.yml

@@ -0,0 +1,369 @@
+name: CI
+
+on:
+  push:
+    branches: [develop, main]
+  pull_request:
+
+# Least-privilege default token for every job (OpenSSF Scorecard:
+# Token-Permissions). Jobs that need more elevate per-job below.
+permissions:
+  contents: read
+
+env:
+  # Suppress Node.js deprecation warnings and align with user request to use Node 22/remove noise.
+  ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION: true
+  NODE_VERSION: '22'
+
+jobs:
+  # ── Security gate: runs first, on every push/PR, never skippable ──────────
+  secrets-scan:
+    name: Secret scan (gitleaks)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write  # gitleaks-action PR feedback comments
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+          fetch-depth: 0  # full history so gitleaks can diff against base
+
+      - name: Run gitleaks
+        uses: gitleaks/gitleaks-action@e0c47f4f8be36e29cdc102c57e68cb5cbf0e8d1e # v3
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  # ── Security gate: dependency CVE audit against locked deps ──────────────
+  deps-audit:
+    name: Dependency audit (pip-audit)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - name: Audit locked dependencies for known CVEs
+        # Fails the build on any known advisory. Accept later via: pip-audit --ignore-vuln <GHSA-id>
+        #
+        # `--all-extras` is REQUIRED, not tidiness. Without it `uv export` emits
+        # only the default dependency group, so everything reachable solely
+        # through an optional extra is never audited. That blind spot was real:
+        # aiohttp 3.13.5 and pyasn1 0.6.3 sat in uv.lock with published high
+        # advisories while this gate reported clean, because both arrive via the
+        # `gcs`/`s3` extras (gcsfs / s3fs / google-auth). GitHub's Dependabot
+        # alerts flagged them against uv.lock; this gate could not see them.
+        run: |
+          uv export --frozen --all-extras --format requirements-txt --no-emit-project > requirements-audit.txt
+          # pip-audit version pinned for a reproducible gate (uvx has no
+          # dependabot ecosystem — bump by hand when it drifts).
+          uvx pip-audit==2.10.1 -r requirements-audit.txt
+
+  # ── Security gate: static analysis of the workflows themselves ───────────
+  # Everything else in this file audits the Python we ship. Nothing audited the
+  # CI that ships it, and CI is a supply-chain surface in its own right: it
+  # holds a repository token, it publishes to PyPI, and its inputs (branch
+  # names, PR titles, fork content) are attacker-controllable text.
+  #
+  # zizmor is what turns that into a gate. It found real defects on its first
+  # run over this repo (#565): 12 checkouts persisting the job token into the
+  # workspace, and `${{ github.base_ref }}` interpolated straight into a
+  # governance-advisory shell script. Both are fixed; this job is what stops
+  # them coming back one copy-pasted step at a time.
+  workflow-audit:
+    name: Workflow audit (zizmor)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+
+      - name: Audit workflows (zizmor)
+        # --offline: the online audits need a GH token and reach the network, so
+        #   they would make this gate non-deterministic and unrunnable on fork
+        #   PRs. Action freshness/pinning is already covered by Dependabot plus
+        #   Scorecard's Pinned-Dependencies check.
+        # --min-severity low: informational findings are advisory, not defects.
+        #   The one open today is `superfluous-actions` on
+        #   softprops/action-gh-release; rewriting the release publisher is not
+        #   a hardening change and is deliberately declined (docs/GITHUB.md).
+        # Version pinned for a reproducible gate — uvx has no Dependabot
+        # ecosystem, so bump it by hand (the pin is asserted by
+        # tests/scripts/test_workflow_hardening.py, which fails if the two drift).
+        run: uvx zizmor==1.29.0 --offline --min-severity low .github/workflows/
+
+  # ── Supply-chain gate: resolve WITHOUT the lockfile ───────────────────────
+  # Every other job installs via `uv sync`, which honours uv.lock. That means CI
+  # never exercises the version RANGES in pyproject.toml — the exact blind spot
+  # that let `mcp>=1.0.0` (unbounded) ship a broken MCP surface to every fresh
+  # `pip install gflow-cli` while CI stayed green: mcp 2.0.0 deleted
+  # `mcp.server.fastmcp`, which the server imports at module load.
+  #
+  # This job installs the way a USER does — from the declared ranges, newest
+  # compatible versions, no lockfile — and smoke-imports the surfaces that break
+  # first. It is what turns "a dependency published a major bump" from a user
+  # bug report into a CI failure.
+  resolve-drift:
+    name: Dependency resolution drift (no lockfile)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Install from pyproject ranges (ignore uv.lock)
+        # --upgrade resolves to the newest versions the ranges allow, so a newly
+        # published major that our bounds do not exclude is caught here.
+        run: |
+          uv venv
+          uv pip install --upgrade .
+
+      - name: Smoke-import the MCP surface
+        # Import-time failures (deleted modules, moved symbols) surface here.
+        # Registration is a decorator side effect, so a successful import with a
+        # non-empty tool registry proves the whole surface still wires up.
+        run: |
+          uv run --no-sync python - <<'PY'
+          from gflow_cli.mcp.server import server, run_stdio, run_http, run_sse
+          from gflow_cli.mcp import prompts, resources, tools  # noqa: F401
+
+          n_tools = len(server._tool_manager._tools)
+          n_resources = len(server._resource_manager._resources)
+          n_prompts = len(server._prompt_manager._prompts)
+          print(f"tools={n_tools} resources={n_resources} prompts={n_prompts}")
+          assert n_tools, "no MCP tools registered"
+          assert n_resources, "no MCP resources registered"
+          assert n_prompts, "no MCP prompts registered"
+
+          import mcp.types as t
+          print("negotiable protocol ceiling:", t.LATEST_PROTOCOL_VERSION)
+          PY
+
+      - name: Smoke-run the CLI entry points
+        run: |
+          uv run --no-sync gflow --version
+          uv run --no-sync gflow --help
+          uv run --no-sync gflow serve --help
+
+      - name: Report the resolved versions
+        # Printed unconditionally so a green run still records what was resolved.
+        if: always()
+        run: uv pip list
+
+  # ── Main test matrix ──────────────────────────────────────────────────────
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      # --frozen: install from the committed uv.lock without re-resolving it.
+      # Plain `uv sync` REWRITES uv.lock in place, which would silently repair
+      # the exact version drift the hygiene gate below exists to catch.
+      - name: Install deps
+        run: uv sync --frozen --extra dev
+
+      # --no-sync for the same reason: `uv run` re-locks before running.
+      - name: Repo hygiene (no artefacts, no hardcoded paths, version lockstep)
+        run: uv run --no-sync python scripts/ci/check_repo_hygiene.py
+
+      - name: Documentation links
+        run: uv run python scripts/ci/check_doc_links.py
+
+      - name: Website docs PII guard (no private identifiers in the published mirror)
+        run: uv run python scripts/ci/check_website_docs_pii.py
+
+      - name: Website docs mirror in sync (regenerate-and-diff)
+        run: uv run python scripts/ci/generate_website_docs.py --check
+
+      - name: Council memory (every cited slug resolves, every file is cited)
+        run: uv run python scripts/ci/check_council_memory.py
+
+      - name: Plugin skills in sync (curated payload, no maintainer-only skill shipped)
+        run: uv run python scripts/ci/generate_plugin_skills.py --check
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Format check
+        run: uv run ruff format --check src tests
+
+      - name: Type check
+        run: uv run pyright src
+
+      # The overlay-precondition tests (#593) drive the captured changelog markup in
+      # a real headless Chromium — a mock cannot tell you whether
+      # `[role='dialog']:has(a[href*='changelog']) button` resolves against Flow's
+      # actual DOM, only a real CSS engine can. They skip cleanly when the browser is
+      # absent, which would make them silently decorative in CI, so one job in the
+      # matrix installs it. No account, no network, no credits.
+      - name: Install Chromium (real-DOM fixture tests)
+        if: matrix.python-version == '3.13'
+        run: uv run playwright install chromium --with-deps
+
+      - name: Test (smoke only) + coverage
+        # e2e/live tests require a logged-in Chromium profile and may spend
+        # Flow credits. pyproject.toml excludes both markers by default; CI
+        # intentionally relies on that default smoke set.
+        # -n auto: pytest-xdist, one worker per runner vCPU (~2x on the full suite;
+        # 198 s vs ~390 s measured locally at -n 8).
+        run: uv run python -m pytest -q -n auto --cov=gflow_cli --cov-report=xml --junitxml=pytest-report.xml
+
+      # Five files under tests/e2e/ are hermetic: every Flow origin is served by
+      # `page.route(...).fulfill(...)`, so they need no account, no profile, no
+      # network and no credits — only the Chromium installed above. They are the
+      # regression tests for #593, #773, #859 and #860, and because `-m e2e` is
+      # excluded by pyproject's addopts and no job overrode it, they ran nowhere:
+      # a regression of any of those fixes would have gone green. They are the
+      # only e2e tests that CAN run here; the other 42 need a logged-in profile.
+      - name: E2E (hermetic subset — route-intercepted, $0, no profile)
+        if: matrix.python-version == '3.13'
+        run: >
+          uv run python -m pytest -q -m e2e
+          tests/e2e/test_account_chooser_e2e.py
+          tests/e2e/test_blocking_dialog_dismissal_bdd.py
+          tests/e2e/test_click_attribution_bdd.py
+          tests/e2e/test_frame_picker_binding_bdd.py
+          tests/e2e/test_landing_state_diagnosis_bdd.py
+          --junitxml=pytest-e2e-hermetic.xml
+
+      - name: E2E-count guard (an empty e2e run is not a passing e2e run)
+        if: matrix.python-version == '3.13'
+        run: uv run python scripts/ci/check_test_count.py pytest-e2e-hermetic.xml 10
+
+      - name: Test-count guard (a green build that ran nothing is not green)
+        # Floor well below the real count (~2900): catches collection collapse
+        # (bad marker/-k filter, broken conftest), never routine deletions.
+        run: uv run python scripts/ci/check_test_count.py pytest-report.xml 2000
+
+      # Upload coverage XML so the sonar job can consume it. It must come from the job
+      # that installs Chromium: the real-DOM fixture tests skip everywhere else, so a
+      # 3.11 upload counted every browser-tested module as uncovered (#989's
+      # agent_only_composer.py measured 39% new coverage with its tests green).
+      - name: Upload coverage report
+        if: matrix.python-version == '3.13'
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
+        with:
+          name: coverage-xml
+          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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+
+      - 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 --junitxml=pytest-lease.xml
+
+      - name: Test-count guard (lease matrix ran its suite)
+        # Floor well below the ~29 executed per OS leg — catches collapse, not
+        # routine test consolidation.
+        run: uv run python scripts/ci/check_test_count.py pytest-lease.xml 10
+
+  # ── SonarCloud analysis ───────────────────────────────────────────────────
+  sonar:
+    name: SonarCloud analysis
+    runs-on: ubuntu-latest
+    needs: test   # wait for tests + coverage report
+    permissions:
+      contents: read
+      pull-requests: read  # PR-context analysis / decoration lookups
+    # Forked pull_request runs do not receive repository secrets, so SONAR_TOKEN
+    # is empty there and the scanner fails before analysis. Dependabot-triggered
+    # runs are the same case: GitHub serves them the separate Dependabot secrets
+    # namespace, so SONAR_TOKEN is also empty even though the branch is in-repo.
+    # Keep SonarCloud on trusted pushes/internal PRs where the token is available.
+    if: >
+      always() &&
+      github.actor != 'dependabot[bot]' &&
+      (
+        github.event_name != 'pull_request' ||
+        github.event.pull_request.head.repo.full_name == github.repository
+      )
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+          fetch-depth: 0  # shallow clones break blame / new-code detection
+
+      - name: Download coverage report
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
+        with:
+          name: coverage-xml
+        continue-on-error: true  # graceful if coverage upload was skipped
+
+      # SonarCloud is a third-party service; it does have outages (seen live
+      # 2026-07-16, ~504s across its whole API including the unauthenticated
+      # /api/system/status endpoint). Reassessed fresh on every run — no manual
+      # flag to remember to flip back once it recovers. A skip here still lets
+      # the job COMPLETE (green), it just doesn't run the scan step; local
+      # coverage during an outage comes from the shared SonarQube instance
+      # (scripts/dev/sonar-local-scan.sh) — see docs/GITHUB.md § SonarCloud
+      # outage handling.
+      - name: Check SonarCloud availability
+        id: sonarcloud_health
+        run: |
+          if curl -sf -m 10 "https://sonarcloud.io/api/system/status" | grep -q '"status":"UP"'; then
+            echo "up=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "up=false" >> "$GITHUB_OUTPUT"
+            echo "::warning::SonarCloud is unreachable or degraded — skipping the scan for this run (not a code quality failure). Verify locally with scripts/dev/sonar-local-scan.sh before merging if this persists, and re-run this job once SonarCloud recovers."
+          fi
+
+      - name: SonarCloud scan
+        if: steps.sonarcloud_health.outputs.up == 'true'
+        # sonarcloud-github-action is ARCHIVED upstream (dependabot never bumps
+        # archived actions, so its pin would rot silently); sonarqube-scan-action
+        # is SonarSource's maintained successor and serves SonarCloud when
+        # SONAR_HOST_URL points at it.
+        uses: SonarSource/sonarqube-scan-action@d209202bc7d53ff1cc128f7f907dac145c9d6ae9 # v8.3.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # PR decoration
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}    # set in repo → Settings → Secrets
+          SONAR_HOST_URL: https://sonarcloud.io