gflow-cli 0.91.0__tar.gz → 0.92.1__tar.gz

{gflow_cli-0.91.0 → gflow_cli-0.92.1}/.codex-plugin/plugin.json

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

{gflow_cli-0.91.0 → gflow_cli-0.92.1}/.env.template

@@ -45,6 +45,7 @@
 #   Windows: %USERPROFILE%\Downloads\gflow-cli
 #   macOS:   ~/Downloads/gflow-cli
 #   Linux:   $XDG_DOWNLOAD_DIR/gflow-cli  (falls back to ~/Downloads/gflow-cli)
+# MCP tools may only write inside this directory (their output / out_dir resolve against it).
 # GFLOW_CLI_OUTPUT_DIR=
 
 # -----------------------------------------------------------------------------

{gflow_cli-0.91.0 → gflow_cli-0.92.1}/.github/workflows/ci.yml

@@ -161,11 +161,14 @@ jobs:
         run: uv pip list
 
   # ── Main test matrix ──────────────────────────────────────────────────────
+  # 3.11 and 3.12 run everything in one job each. 3.13 is the coverage job and was
+  # the critical path (Chromium, real-DOM tests, the hermetic e2e), so it runs as
+  # parallel shards below and `test-313` aggregates them under the required name.
   test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12"]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
@@ -211,23 +214,79 @@ jobs:
       - name: Type check
         run: uv run pyright src
 
+      - name: Test (smoke only)
+        # 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).
+        # --dist worksteal: the default `load` hands each worker a fixed chunk up
+        # front, and test_agent_only_composer_driver.py's 85 contiguous tests all
+        # landed on one worker (338 s there, ~20 s on the other three, measured).
+        run: uv run python -m pytest -q -n auto --dist worksteal --junitxml=pytest-report.xml
+
+      - 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
+
+  # ── 3.13: three unit shards + the hermetic e2e, in parallel ───────────────
+  # GFLOW_TEST_SHARD=k/N makes root conftest.py keep only shard k's files, split
+  # by whole file and balanced on tests/test_durations.json
+  # (scripts/ci/shard_tests.py). Every file runs in exactly one shard; the count
+  # floor is checked over the SUM in `test-313`, never per shard.
+  test-313-shard:
+    name: test 3.13 (${{ matrix.shard }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: ["1/3", "2/3", "3/3", "e2e"]
+    env:
+      SHARD: ${{ matrix.shard }}
+    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 --frozen --extra dev
+
+      # The repo gates are version-independent except pyright; 3.11/3.12 run them
+      # too. On 3.13 they ride on the first unit shard, the lightest after the split.
+      - name: Repo gates (hygiene, docs, plugin skills, lint, format, types)
+        if: matrix.shard == '1/3'
+        run: |
+          uv run --no-sync python scripts/ci/check_repo_hygiene.py
+          uv run python scripts/ci/check_doc_links.py
+          uv run python scripts/ci/check_website_docs_pii.py
+          uv run python scripts/ci/generate_website_docs.py --check
+          uv run python scripts/ci/check_council_memory.py
+          uv run python scripts/ci/generate_plugin_skills.py --check
+          uv run ruff check src tests
+          uv run ruff format --check src tests
+          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.
+      # absent, which would make them silently decorative in CI, so every 3.13 shard
+      # 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
+      - name: Test shard + coverage
+        if: matrix.shard != 'e2e'
+        env:
+          GFLOW_TEST_SHARD: ${{ matrix.shard }}
+        run: uv run python -m pytest -q -n auto --dist worksteal --cov=gflow_cli --cov-report= --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
@@ -237,7 +296,7 @@ jobs:
       # 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'
+        if: matrix.shard == 'e2e'
         run: >
           uv run python -m pytest -q -m e2e
           tests/e2e/test_account_chooser_e2e.py
@@ -248,26 +307,95 @@ jobs:
           --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'
+        if: matrix.shard == 'e2e'
         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)
+      # `.coverage` is a dotfile, which upload-artifact skips unless told otherwise.
+      - name: Upload shard report + coverage data
+        if: matrix.shard != 'e2e'
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
+        with:
+          name: shard-${{ strategy.job-index }}
+          path: |
+            pytest-report.xml
+            .coverage
+          include-hidden-files: true
+          if-no-files-found: error
+          retention-days: 1
+
+  # The required check `test (3.13)` lives HERE, so the ruleset needs no edit.
+  # `if: always()` plus the result gate are both load-bearing: GitHub reports a
+  # SKIPPED required check as passing, so without them a failed shard would skip
+  # this job and the PR would merge green.
+  test-313:
+    name: test (3.13)
+    runs-on: ubuntu-latest
+    needs: test-313-shard
+    if: always()
+    steps:
+      - name: Every 3.13 shard passed
+        env:
+          SHARDS: ${{ needs.test-313-shard.result }}
+        run: |
+          if [ "$SHARDS" != "success" ]; then
+            echo "::error::a 3.13 shard ended '$SHARDS' — see the test 3.13 (...) jobs"
+            exit 1
+          fi
+
+      - 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 --frozen --extra dev
+
+      - name: Download shard reports
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
+        with:
+          pattern: shard-*
+
+      # Each shard is named, not globbed: a shard that uploaded nothing must fail
+      # here rather than shrink the sum.
+      - name: Test-count guard over every shard (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
+        # (bad marker/-k filter, broken conftest, a lost shard), never routine deletions.
+        run: >
+          uv run --no-sync python scripts/ci/check_test_count.py
+          shard-0/pytest-report.xml shard-1/pytest-report.xml shard-2/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: Combine shard coverage
+        run: |
+          uv run --no-sync coverage combine shard-0/.coverage shard-1/.coverage shard-2/.coverage
+          uv run --no-sync coverage xml -o coverage.xml
+          uv run --no-sync coverage report --format=total
+
+      # Upload coverage XML so the sonar job can consume it. It must come from the
+      # Chromium-installing 3.13 shards: 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
 
+      # Report-only (watch mode): `continue-on-error` and the brace group mean nothing
+      # in this step can turn the job red. Reads the shard-*/pytest-report.xml already
+      # downloaded above (copied alone so the scan never sees coverage.xml or the repo); no new upload.
+      - name: Speed check (report only)
+        continue-on-error: true
+        run: |
+          { mkdir speed-in && cp --parents shard-*/pytest-report.xml speed-in/ \
+              && uv run --no-sync python -m scripts.ci.pytest_speed check speed-in --config pytest-speed.toml --out speed.md \
+              && cat speed.md >> "$GITHUB_STEP_SUMMARY"; } || echo "speed check: not run" >> "$GITHUB_STEP_SUMMARY"
+
   # ── 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
@@ -344,7 +472,7 @@ jobs:
   sonar:
     name: SonarCloud analysis
     runs-on: ubuntu-latest
-    needs: test   # wait for tests + coverage report
+    needs: [test, test-313]   # wait for tests + the combined coverage report
     permissions:
       contents: read
       pull-requests: read  # PR-context analysis / decoration lookups

{gflow_cli-0.91.0 → gflow_cli-0.92.1}/.gitignore

@@ -125,3 +125,7 @@ website/site/
 scripts/dev/har-spike/artifacts/
 scripts/dev/har-spike/.agent-browser/
 scripts/dev/har-spike/.npm-cache/
+
+# MCPJam bridge spike (scripts/dev/mcpjam): local npm install, never committed
+scripts/dev/mcpjam/node_modules/
+.junit/

{gflow_cli-0.91.0 → gflow_cli-0.92.1}/AGENTS.md

@@ -102,7 +102,7 @@ the five other mirror axes), which no command here can check and no CI gate can
 > list follows it.
 
 - Use `pytest -m "not live and not e2e and not smoke"` locally; full suite OOMs on small dev machines. Scope to changed dirs; trust CI for the full sweep.
-- **Parallel runs (`pytest-xdist`):** add `-n 8` (or `-n auto`) to cut the offline suite from ~390 s to ~200 s. Every worker is a full process, so cap `-n` on a small machine. CI runs `-n auto`. A test that passes alone but fails under `-n` shares state with another test: **fix the shared state** (two measured cases: `tests/mcp/conftest.py` and `test_every_shipped_skill_is_byte_identical_to_its_source`). If two tests genuinely need the same exclusive resource (a fixed port, a file lock), mark both `@pytest.mark.xdist_group("<resource>")` so they run on one worker, one after another, while the rest stays parallel.
+- **Parallel runs (`pytest-xdist`):** add `-n 8` (or `-n auto`) to cut the offline suite from ~390 s to ~200 s. Every worker is a full process, so cap `-n` on a small machine. CI runs `-n auto --dist worksteal` (the default `load` pinned one 85-test file to a single worker; add `--dist worksteal` locally too). A test that passes alone but fails under `-n` shares state with another test: **fix the shared state** (two measured cases: `tests/mcp/conftest.py` and `test_every_shipped_skill_is_byte_identical_to_its_source`). If two tests genuinely need the same exclusive resource (a fixed port, a file lock), mark both `@pytest.mark.xdist_group("<resource>")` — but a group is honoured only under `--dist loadgroup`, and CI's `worksteal` ignores it, so a mark alone does not serialize them in CI. Nothing uses one today; whoever adds the first must also switch CI to `loadgroup` (and re-measure) or guard the resource another way.
 - TDD is non-negotiable. Coverage floor: 80% overall.
 - Documentation is a first-class deliverable. Every behavior, workflow, config, or operator-facing change must update the relevant docs or state why no docs changed in the PR/checklist. `scripts/ci/check_doc_links.py` is a merge gate.
 - **A PR is not done until its SonarCloud gate is green (zero new issues).** The ten gates above are local/pre-commit; SonarCloud is server-side and runs in CI (`sonar.qualitygate.wait=true` → a red gate turns the `SonarCloud analysis` check red). Before calling a PR merge-ready, verify it with `/gflow:sonar <N>` (it is skipped on fork PRs — maintainer-checked there).

{gflow_cli-0.91.0 → gflow_cli-0.92.1}/CHANGELOG.md

@@ -7,6 +7,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.92.1] — 2026-10-30
+
+### Fixed
+
+- **MCP agents now see how to pass `tools` and character ids.** The generate tools'
+  schema stated neither the `tools` item shape (`{"name": <slug>, "options": {...}}`)
+  nor that, on flow.google.com, each `reference_entities` id needs its name at the same
+  position in `reference_entity_names` (and, for video, `mode: r2v`). The `tools` shape and
+  the video rules sat only in docstrings the MCP client never shows; the image pairing
+  rule sat in the long tool description, where agents missed it. The schema now also says that
+  `gflow_character_list` fails there with a `wire-format` error (the CLI's exit 7, #875)
+  and to ask the user for the name. In a
+  tool-selection eval with Claude Code as the host, a character given by id was sent
+  without its name in 4 of 5 runs, which fails before submit. With the rule in the
+  schema, that dropped to 0 of 5.
+- **The flow.google.com remediation hint no longer says video takes no character.** Since
+  v0.91.0 (#723) reference-to-video attaches a character by name there; the hint on the
+  `flow-host-migrated` refusal still said "video none", which an agent reads as a reason
+  not to try.
+
+### Added
+
+- **`scripts/dev/mcpjam/`: a local tool-selection eval for the MCP server.** It snapshots
+  the real `tools/list` with MCPJam's client, serves it from a stub that records calls
+  without running them ($0, no browser), and drives `claude -p` as the host. Dev-only;
+  not part of CI.
+
+## [0.92.0] — 2026-10-29
+
+### Fixed
+
+- **A video saved with `-o` onto another filesystem no longer fails after it is billed**
+  ([#1114](https://github.com/ffroliva/gflow-cli/issues/1114)). Moving the downloaded clip
+  to `--output` used a rename, which raises `EXDEV` across mounts (a tmpfs `/tmp`, another
+  drive), so the run ended in "Unexpected error" with the clip left in `./tmp/`. The CLI
+  and the MCP queued path now move it with a copy when a rename cannot. The MCP video
+  tool also refuses an `output` that names a directory before anything is billed, as the
+  CLI's `-o` already did ([spike](docs/superpowers/spikes/2026-10-29-cross-device-relocate.md)).
+
+### Security
+
+- **MCP tools can no longer write outside the configured output directory**
+  ([GHSA-hqfj-4jww-76f2](https://github.com/ffroliva/gflow-cli/security/advisories/GHSA-hqfj-4jww-76f2)).
+  `output` on `gflow_generate_image` / `gflow_generate_video` and `out_dir` on
+  `gflow_download_media` / `gflow_upscale_image` / `gflow_upscale_video` accepted any path,
+  so an MCP client, or content steering one, could write or replace files anywhere the
+  server's user can. They are now resolved against `GFLOW_CLI_OUTPUT_DIR` and refused with a
+  400 envelope when they resolve outside it; an `output` that resolves to a directory is
+  refused too. The `profile` argument of every MCP tool that opens a browser profile is likewise refused (400 `Invalid
+  Profile`) unless it is a plain name: a path in it pointed Chrome's user-data-dir, and the
+  files Chrome writes there, at any existing directory. **Breaking for MCP callers** that passed an absolute path outside the output
+  directory: pass a path relative to it, or set `GFLOW_CLI_OUTPUT_DIR`. The CLI is
+  unchanged. Reported by Filip Kulisiewicz; the `profile` path was found while reviewing the fix.
+
 ## [0.91.0] — 2026-10-28
 
 ### Fixed
@@ -6733,7 +6787,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.91.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.92.1...HEAD
+[0.92.1]: https://github.com/ffroliva/gflow-cli/compare/v0.92.0...v0.92.1
+[0.92.0]: https://github.com/ffroliva/gflow-cli/compare/v0.91.0...v0.92.0
 [0.91.0]: https://github.com/ffroliva/gflow-cli/compare/v0.90.0...v0.91.0
 [0.90.0]: https://github.com/ffroliva/gflow-cli/compare/v0.89.1...v0.90.0
 [0.89.1]: https://github.com/ffroliva/gflow-cli/compare/v0.89.0...v0.89.1

{gflow_cli-0.91.0 → gflow_cli-0.92.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gflow-cli
-Version: 0.91.0
+Version: 0.92.1
 Summary: CLI and MCP server for Google Flow — drive Veo text-to-video, image-to-video and Imagen image generation from the terminal.
 Project-URL: Homepage, https://github.com/ffroliva/gflow-cli
 Project-URL: Documentation, https://ffroliva.github.io/gflow-cli/

{gflow_cli-0.91.0 → gflow_cli-0.92.1}/conftest.py

@@ -7,6 +7,8 @@ Responsibilities:
 2. Auto-apply directory-based markers so tests in ``tests/e2e/`` and
    ``tests/smoke/`` are always tagged correctly even if a test author
    forgets the ``pytestmark`` declaration.
+3. ``GFLOW_TEST_SHARD=k/N``: keep only shard k's files (CI runs the 3.13 suite
+   as parallel shards; see ``scripts/ci/shard_tests.py``).
 
 The ``addopts`` and ``markers`` settings live in ``pyproject.toml`` so that
 ``pytest --help`` surfaces them correctly. See docs/E2E_TESTING.md for the
@@ -15,6 +17,7 @@ full marker reference and cost-tier run commands.
 
 from __future__ import annotations
 
+import os
 import pathlib
 
 import pytest
@@ -25,6 +28,37 @@ def pytest_configure(config) -> None:  # noqa: ANN001 — pytest config object
     if basetemp:
         parent = pathlib.Path(basetemp).expanduser().resolve().parent
         parent.mkdir(parents=True, exist_ok=True)
+    spec = os.environ.get("GFLOW_TEST_SHARD")
+    if spec:
+        from scripts.ci.shard_tests import parse_spec
+
+        config.pluginmanager.register(_Shard(*parse_spec(spec)), "gflow-test-shard")
+
+
+class _Shard:
+    """Deselect every file another shard owns.
+
+    ``trylast`` so it splits only what ``-m`` left selected: the weights then cover
+    the tests this run actually executes. Deselected, not skipped, so a shard's
+    junit counts only its own tests and the summed count guard stays exact.
+    """
+
+    def __init__(self, index: int, total: int) -> None:
+        self.index, self.total = index, total
+
+    @pytest.hookimpl(trylast=True)
+    def pytest_collection_modifyitems(
+        self, config: pytest.Config, items: list[pytest.Item]
+    ) -> None:
+        from scripts.ci.shard_tests import load_durations, shard_owner
+
+        files = [item.nodeid.split("::")[0] for item in items]
+        owner = shard_owner(files, self.total, load_durations())
+        kept = [i for i, f in zip(items, files, strict=True) if owner[f] == self.index]
+        dropped = [i for i, f in zip(items, files, strict=True) if owner[f] != self.index]
+        if dropped:
+            config.hook.pytest_deselected(items=dropped)
+        items[:] = kept
 
 
 def pytest_collection_modifyitems(items: list[pytest.Item]) -> None:

{gflow_cli-0.91.0 → gflow_cli-0.92.1}/docker/Dockerfile

@@ -45,7 +45,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 # Deliberately NOT pinned: google-chrome-stable. Chrome's apt repo keeps only the current
 # build, so a pinned version stops resolving within weeks. The trade-off is that this
 # layer caches indefinitely and a rebuild is what picks up a newer Chrome.
-ARG GFLOW_VERSION=0.91.0
+ARG GFLOW_VERSION=0.92.1
 RUN pip install --no-cache-dir "gflow-cli==${GFLOW_VERSION}"
 
 VOLUME ["/data"]

{gflow_cli-0.91.0/website → gflow_cli-0.92.1}/docs/CONFIGURATION.md

@@ -95,6 +95,11 @@ Set, `image t2i`/`i2i`, `video t2v`/`i2v`/`r2v`, `gflow run` and the MCP
 **CLI override:** command-specific output flags such as `--out` for image
 commands and `--out-dir` for video commands.
 
+**MCP boundary:** an MCP tool cannot direct a write outside this directory. A tool's
+`output` / `out_dir` is resolved against it and refused when it resolves outside
+([MCP.md](MCP.md), GHSA-hqfj-4jww-76f2), so set it to wherever an agent's files
+should land.
+
 If [`GFLOW_CLI_STORAGE_URI`](#gflow_cli_storage_uri) is set, generated asset
 bytes are uploaded to the configured cloud bucket instead of this local output
 root. `GFLOW_CLI_OUTPUT_DIR` still matters for local mode and for deriving the

{gflow_cli-0.91.0 → gflow_cli-0.92.1}/docs/GITHUB.md

@@ -97,6 +97,33 @@ This is intentional. Do not switch the normal PR workflow to
 repository privileges and can expose secrets if it checks out or executes
 untrusted PR code.
 
+## CI Test Layout
+
+`ci.yml` runs the offline suite on three Pythons. `develop` requires the checks
+`test (3.11)`, `test (3.12)` and `test (3.13)` (ruleset 25428466), so those
+names must not change.
+
+| Job | What it runs |
+|---|---|
+| `test (3.11)`, `test (3.12)` | Repo gates, lint, types, and the whole offline suite in one job each. |
+| `test 3.13 (1/3)`, `(2/3)`, `(3/3)` | One third of the offline suite each, with coverage and Chromium for the real-DOM tests. `GFLOW_TEST_SHARD=k/N` makes root `conftest.py` keep only shard k's files. Shard 1/3 also runs the repo gates. |
+| `test 3.13 (e2e)` | The hermetic e2e subset (route-intercepted, $0, no profile), floor 10 tests. |
+| `test (3.13)` | The required check. Fails unless every shard succeeded. Sums the shards' JUnit against the 2000-test floor, runs `coverage combine`, and uploads `coverage-xml` for SonarCloud. |
+
+The split is by whole file, balanced on the per-file seconds in
+`tests/test_durations.json`. A file without a record counts as the average, so a
+stale record only unbalances the shards; every file still runs exactly once.
+Refresh the record from CI, not from a local run: Windows inflates some files
+far past their Linux time (`test_cleanup.py` measured 242 s locally against 3 s on
+CI), and a record taken there sent the slow shard 181 s of CI work against 86 s on
+the lightest. Download the three `shard-*` artifacts of a recent `develop` push run
+(kept one day) and pass their reports: `gh run download <run-id> -p 'shard-*' -D tmp/shards`
+then `uv run python scripts/ci/shard_tests.py tmp/shards/shard-*/pytest-report.xml`.
+
+`test (3.13)` runs with `if: always()` and checks the shard result itself.
+GitHub reports a skipped required check as passing, so an aggregate that only
+ran on success would let a failed shard merge green.
+
 ## SonarCloud Quality Gate
 
 The gate is evaluated on **new code** (changed lines vs `main`, per