From a3b1f28ed28b2ed8c0eb4c242c5455ed077b2c0c Mon Sep 17 00:00:00 2001
From: Gage Larsen <glarsen@aquaveo.com>
Date: Tue, 1 Sep 2026 13:45:05 -0600
Subject: [PATCH 1/3] Move the GitLab Windows jobs onto the GLR-UV runner
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The per-ABI GLR-py310 / GLR-py313 images are gone, replaced by a single
GLR-UV image carrying uv and pre-loaded 3.10 / 3.13 / 3.14 interpreters.

Those images existed for one reason: to make `python` on PATH the matrix
version. The recipe hands CMake `Python3_EXECUTABLE = sys.executable` and
the generated CMakeLists.txt requires `find_package(Python3 ... EXACT
REQUIRED)`, so the interpreter running conan *is* the ABI being built --
which meant the ABI had to be chosen by picking an image and could not be
changed inside the job. That is what PY_TAG and `image: GLR-${PY_TAG}`
were for, and both are now gone: the job establishes the interpreter
itself with `uv venv --python ${PYTHON_TARGET_VERSION}`, activates it,
and installs conan and xmsconan into it with `uv pip install`. GitLab
runs a job's script lines as one shell, so the activation carries.

`uv --version` runs first so a runner without uv fails on a line that
says so rather than four lines later on an install that reads like a
packaging problem. `tags: WinVM` is unchanged -- the tag routes to the
Windows fleet, `image:` only picks the VM template it starts.

Also drops the hard-coded /c/Users/admin from the deploy job's cache
snapshot in favor of ${HOME}. The conan home is `~/.conan2`, so that
literal was an assumption about the old service account, and under any
other one the job shipped an empty artifact and stayed green -- exactly
the kind of assumption a move to a different machine has to stop making.

Docs: USAGE.md §5.6, §9.x, §10.2 and the troubleshooting list, including
two new entries for the failures this shape can produce.
---
 docs/USAGE.md                                 |  18 +--
 tests/test_ci_file_generator.py               | 108 +++++++++++++++++-
 .../ci_templates/gitlab-ci.yml.jinja          |  67 ++++++++---
 3 files changed, 167 insertions(+), 26 deletions(-)

diff --git a/docs/USAGE.md b/docs/USAGE.md
index 5dcb60b..0cc2bba 100644
--- a/docs/USAGE.md
+++ b/docs/USAGE.md
@@ -454,10 +454,10 @@ it did before.
 
 Why three lists instead of one:
 
-- **Windows** interpreters all come from `actions/setup-python` (GitHub) or a
-  `GLR-pyXYZ` runner tag (GitLab), so a version costs only runner minutes. 3.10
-  lives here because the desktop products (GMS/SMS/WMS) consume a 3.10 Windows
-  wheel; nothing else needs it.
+- **Windows** interpreters all come from `actions/setup-python` (GitHub) or
+  `uv venv --python` on the `GLR-UV` runner (GitLab), so a version costs only
+  runner minutes. 3.10 lives here because the desktop products (GMS/SMS/WMS)
+  consume a 3.10 Windows wheel; nothing else needs it.
 - **macOS** is cheap to fan out too, but inherits nothing from the Windows list —
   adding 3.10 for the desktop products should not triple the mac matrix.
 - **Linux** runs in a container, and each version needs a published
@@ -501,9 +501,9 @@ several wheels locally, invoke `python build.py` once per version (or construct
 the resolved coverage ABI (§5.7) before invoking `build.py`, so a local coverage run
 needs no manual export — and an ambient value does not win over `build.toml`.
 
-Either way, a local pybind build only works **from an interpreter of the version being built**: the recipe points CMake at `sys.executable` and the generated `CMakeLists.txt` requires that exact version. CI never notices because `actions/setup-python` supplies a matching interpreter; on a workstation you supply it, which is why the VS2019 wheel workflow is one run per Python version from a virtual environment of that version (§16.8).
+Either way, a local pybind build only works **from an interpreter of the version being built**: the recipe points CMake at `sys.executable` and the generated `CMakeLists.txt` requires that exact version. CI never notices because it arranges one: `actions/setup-python` on GitHub, `uv venv --python ${PYTHON_TARGET_VERSION}` on the GitLab Windows jobs (§10.2). On a workstation you supply it, which is why the VS2019 wheel workflow is one run per Python version from a virtual environment of that version (§16.8).
 
-> **Runner / image expectations.** A Windows opt-in assumes the matching `GLR-pyXYZ` GitLab runner tag exists (`GLR-py310`, `GLR-py314`). A Linux opt-in assumes the matching `conan-gcc13-py<version>` image exists **and is readable by CI** — on GHCR the 3.13 image is public while 3.14 is private, and the generated `container:` block pulls anonymously, so a private image needs its visibility flipped (or a `credentials:` stanza added) before its leg can start.
+> **Runner / image expectations.** On GitLab a Windows opt-in assumes the `GLR-UV` image can supply the interpreter — it carries `uv` and pre-loaded 3.10 / 3.13 / 3.14, and `uv venv --python` downloads anything else it is asked for, so a version outside that set costs a download on every job rather than failing. A Linux opt-in assumes the matching `conan-gcc13-py<version>` image exists **and is readable by CI** — on GHCR the 3.13 image is public while 3.14 is private, and the generated `container:` block pulls anonymously, so a private image needs its visibility flipped (or a `credentials:` stanza added) before its leg can start.
 
 ---
 
@@ -607,7 +607,7 @@ The generated jobs follow the pattern:
 - `[ci].split_tests` is also rejected when the `[filter]` table leaves no Linux testing configuration (`options.testing = false`, or a `pybind = true` pin). Splitting makes the build job export `XMS_SKIP_CXX_TESTS=1`, so with no runner staged there is nowhere left for the suite to run — the pipeline would pass having tested nothing. Note that `[ci].build_types` is not the axis here: a `pybind = true` pin keeps Release configurations while staging no runner at all.
 - **One test job per testing configuration, each naming its own.** `[ci].split_tests` emits a `Run C++ Tests - <label>` job for every testing configuration the Linux build stages — `Release-testing` and `Debug-testing` on the default matrix — and each passes its own `--label`. They are peers in the `Test` stage off the single `Conan Build`, and each uploads only its own `test_artifacts/<label>/` (the `needs: artifacts: true` download hands every job the whole staged tree, so an unscoped path would have each one re-upload the others' runners too). Every job writes `TEST-cxxtest.xml`; GitLab keys the pipeline test report on the job name, so the configurations stay distinguishable in the MR widget. The labels are computed by the generator with the same `config_label()` the build names the directories with, so the two cannot drift — a template concatenating `<build_type>-testing` would be a second implementation free to. **This is what a single job got wrong:** it found its directory by falling back to the first of `Debug-testing`, `Release-testing` that existed, so a matrix building both compiled the Release runner on every pipeline and never executed it, with nothing red to show for it. `xmsconan_test_shards` keeps that fallback for interactive use after a local `build.py`, but no generated pipeline relies on it any more.
 - **Each job shards inside one container.** The job downloads the build job's `test_artifacts/`, then runs `xmsconan_test_shards`, which restores the executable bit on the runner (a GitLab artifact round-trip drops it), relinks `test_files/` next to the runner, and forks `[ci].test_shards` runner processes with `GTEST_TOTAL_SHARDS`/`GTEST_SHARD_INDEX` set. Each shard writes its own gtest XML, which the tool merges by suite name into `TEST-cxxtest.xml` and declares as `artifacts:reports:junit`, so a failing case shows up in the MR widget by name. Per-shard console output is held and replayed as one contiguous block rather than interleaved. A shard that dies before writing XML — a timeout, a segfault — contributes a synthetic error suite to the merged report, so a red job never shows an all-green test tab. Without `test_shards` the same script runs a single shard: one code path, so the artifact discovery and `test_files` relinking do not have to exist twice. With `[ci].xvfb = true` each shard gets its own X display, because `xvfb-run -a` picks a free server number and N simultaneous starts race for it.
-- `Conan Build - Windows`, `Conan Deploy - Windows`: `parallel:matrix` over `PYTHON_TARGET_VERSION` from `python_versions`. The matrix also sets `PY_TAG` (`py310` / `py313` / `py314`) which selects the runner via `image: GLR-${PY_TAG}`.
+- `Conan Build - Windows`, `Conan Deploy - Windows`: `parallel:matrix` over `PYTHON_TARGET_VERSION` from `python_versions`. Both run on `image: GLR-UV` with `tags: [WinVM]` — `image:` selects the VM template, the tag routes to the Windows fleet. One image serves every ABI: the job establishes the interpreter itself with `uv venv --python ${PYTHON_TARGET_VERSION} .venv`, activates it, and installs conan and xmsconan into it with `uv pip install`. That venv is load-bearing, not hygiene — the recipe points CMake at the interpreter running conan and the generated `CMakeLists.txt` requires that exact version, which is what the retired per-ABI `GLR-py310` / `GLR-py313` images existed to provide. `uv --version` runs first so a runner without uv fails on a line that says so, and nothing reads `python` before the venv is active.
 - Wheel-repair always runs `cp313-cp313`'s `xmsconan_wheel_repair` inside the manylinux container; auditwheel itself doesn't care about the host Python.
 - Required CI variables: `AQUAPI_URL`, `AQUAPI_USERNAME`, `AQUAPI_PASSWORD` (for wheel deploy).
   They are read from the process environment by `xmsconan_wheel_deploy` and are deliberately **not** placed in any
@@ -1148,7 +1148,9 @@ Wheels are tagged `cp310-cp310-...` or `cp313-cp313-...`; pip picks the right on
 - **`No pybind package found to extract`.** Means `build.py` ran but no pybind config was built. Check `build.py --preview` to see the matrix; common causes are `--filter` or the `[filter]` table in `build.toml` (§5.8) excluding the pybind variant, or every pybind variant having failed.
 - **`No configurations match the requested filters`.** The `[filter]` table and the `--filter` on the command line narrow the matrix together, and nothing survived both. The message lists what was applied; drop the conflicting `--filter`, loosen `[filter]` in `build.toml`, or pass `--ignore-build-filter` for a one-off build.
 - **Dual wheel uploads colliding on devpi.** With `python_versions=["3.10","3.13"]`, wheels carry distinct `cp3XY` tags, so devpi treats them as separate uploads of the same release. No special config required.
-- **Generated CI references a runner or image that doesn't exist.** A Windows opt-in needs the matching `GLR-pyXYZ` GitLab runner tag; a Linux opt-in needs the matching `conan-gcc13-py<version>` container. If one isn't available, drop that version from the relevant list until it is — the platforms are independent, so Windows can carry a version Linux cannot.
+- **Generated CI references a runner or image that doesn't exist.** A GitLab Windows opt-in needs the `GLR-UV` image on a runner tagged `WinVM`; a Linux opt-in needs the matching `conan-gcc13-py<version>` container. If one isn't available, drop that version from the relevant list until it is — the platforms are independent, so Windows can carry a version Linux cannot.
+- **Windows job dies on `uv: command not found`.** The job is on a runner image that predates the uv migration (the per-ABI `GLR-py310` / `GLR-py313` VMs). The generated pipeline requires `GLR-UV`; check that `image: GLR-UV` resolves on the `WinVM` fleet rather than pinning the old images back.
+- **Windows pybind leg fails `find_package(Python3 ... EXACT REQUIRED)`.** The venv was not active when `build.py` ran, so conan is running under the machine's interpreter rather than the matrix ABI. `uv venv --python ${PYTHON_TARGET_VERSION} .venv` and `source .venv/Scripts/activate` must both precede it; GitLab runs a job's `script:` lines as one shell, so the activation carries — but a step inserted above it does not get it.
 - **Linux job fails pulling its container.** The generated `container:` block pulls without credentials, which only works for a public image. On GHCR `conan-gcc13-py3.13` is public but `conan-gcc13-py3.14` is not, so a 3.14 Linux leg fails at pull until the package visibility is changed or a `credentials:` stanza is added.
 - **`xmsconan vs2019 build` stops at preflight with "outside the pinned `~=2.31.0` series".** Intentional (§16.3). Install the pinned client — `pip install "conan~=2.31.0"` — rather than working around the check; a different minor can change package_ids and detach your build from what's already published.
 - **VS2019 build fails on a boost option Conan says no recipe defines.** The legacy `boost/1.74.0.3` doesn't declare the conan-center 1.86 options. The driver already passes `apply_boost_defaults=False`; if you're constructing `XmsConanPackager` yourself for msvc 192, pass it too (§16.6).
diff --git a/tests/test_ci_file_generator.py b/tests/test_ci_file_generator.py
index c60ea22..c3a22b8 100644
--- a/tests/test_ci_file_generator.py
+++ b/tests/test_ci_file_generator.py
@@ -307,9 +307,14 @@ def test_gitlab_python_versions_opt_in_only_fans_out_windows(tmp_path):
     output_dir = tmp_path / "output"
     generate_ci(str(toml_file), "1.0.0", str(output_dir))
     content = (output_dir / ".gitlab-ci.yml").read_text(encoding="utf-8")
-    # Only Windows fans out; PY_TAG variable is windows-only.
-    assert "PY_TAG: 'py310'" in content
-    assert "PY_TAG: 'py313'" in content
+    # Only Windows fans out. Read that off the Windows jobs' parallel matrix
+    # rather than off a substring of the file: every Linux job also declares a
+    # PYTHON_TARGET_VERSION, under `variables`, so a bare `"3.10" in content`
+    # would keep passing on a Windows job that had stopped fanning out at all.
+    parsed = yaml.safe_load(content)
+    for name in ("Conan Build - Windows", "Conan Deploy - Windows"):
+        matrix = parsed[name]["parallel"]["matrix"]
+        assert [entry["PYTHON_TARGET_VERSION"] for entry in matrix] == ["3.10", "3.13"], name
     # Linux jobs are single-version and use a static image.
     assert "conan-gcc13-py3.13" in content
     assert "cp313-cp313" in content
@@ -317,6 +322,103 @@ def test_gitlab_python_versions_opt_in_only_fans_out_windows(tmp_path):
     assert "CP_TAG" not in content
 
 
+def test_gitlab_windows_jobs_run_on_the_uv_runner(tmp_path):
+    """Both Windows jobs select GLR-UV and still route to the WinVM fleet.
+
+    ``image:`` picks the VM template and ``tags:`` picks the fleet -- the two
+    are not interchangeable, and collapsing three per-ABI images into one could
+    plausibly have dropped either.
+    """
+    toml_file = write_gitlab_toml(tmp_path)
+    output_dir = tmp_path / "output"
+    generate_ci(str(toml_file), "1.0.0", str(output_dir))
+    content = (output_dir / ".gitlab-ci.yml").read_text(encoding="utf-8")
+    parsed = yaml.safe_load(content)
+
+    for name in ("Conan Build - Windows", "Conan Deploy - Windows"):
+        assert parsed[name]["image"] == "GLR-UV", name
+        assert parsed[name]["tags"] == ["WinVM"], name
+    # The retired per-ABI images, and the matrix variable whose only job was to
+    # spell one, must not survive anywhere in the file.
+    assert "GLR-py" not in content
+    assert "PY_TAG" not in content
+
+
+def test_gitlab_windows_jobs_build_a_uv_venv_of_the_matrix_abi(tmp_path):
+    """Each Windows job creates and activates a venv on its own PYTHON_TARGET_VERSION.
+
+    This is what let three per-ABI runner images collapse into one. The recipe
+    hands CMake ``Python3_EXECUTABLE = sys.executable`` and the generated
+    CMakeLists.txt does ``find_package(Python3 ... EXACT REQUIRED)``, so the
+    interpreter running conan *is* the ABI being built. GLR-py310 / GLR-py313
+    supplied that as the machine's own ``python``; on GLR-UV the job has to
+    establish it, and before anything else reaches for an interpreter.
+    """
+    toml_file = write_gitlab_toml(tmp_path, python_versions=["3.10", "3.13"])
+    output_dir = tmp_path / "output"
+    generate_ci(str(toml_file), "1.0.0", str(output_dir))
+    parsed = yaml.safe_load((output_dir / ".gitlab-ci.yml").read_text(encoding="utf-8"))
+
+    for name in ("Conan Build - Windows", "Conan Deploy - Windows"):
+        script = parsed[name]["script"]
+        venv = script.index("uv venv --python ${PYTHON_TARGET_VERSION} .venv")
+        activate = script.index("source .venv/Scripts/activate")
+        assert venv < activate, name
+        # Nothing may reach for an interpreter, or for a console script
+        # installed beside one, before the venv is on PATH.
+        for step in script[:activate]:
+            assert not step.startswith(("python ", "python-m", "pip ", "xmsconan_")), (
+                f"{name}: {step!r} runs before the venv is activated"
+            )
+        # uv is proven present before a package install depends on it, so a
+        # runner without uv fails on a line that says so.
+        assert script.index("uv --version") < venv, name
+
+
+def test_gitlab_windows_jobs_install_with_uv_not_pip(tmp_path):
+    """The Windows jobs install through ``uv pip``; bare ``pip`` is gone from them.
+
+    Asserted per job rather than over the whole file: the Linux jobs keep plain
+    pip, because they run in containers that ship one and have no uv.
+    """
+    toml_file = write_gitlab_toml(tmp_path)
+    output_dir = tmp_path / "output"
+    generate_ci(str(toml_file), "1.0.0", str(output_dir))
+    parsed = yaml.safe_load((output_dir / ".gitlab-ci.yml").read_text(encoding="utf-8"))
+
+    for name in ("Conan Build - Windows", "Conan Deploy - Windows"):
+        installs = [step for step in parsed[name]["script"] if "install" in step]
+        assert installs, name
+        for step in installs:
+            assert step.startswith("uv pip install "), f"{name}: {step!r}"
+            # `-i` is pip's spelling for the index; uv takes the long option.
+            assert " -i http" not in step, f"{name}: {step!r}"
+        assert any('"conan~=2.31.0"' in step for step in installs), name
+        assert any("xmsconan>=" in step for step in installs), name
+
+
+def test_gitlab_windows_conan_cache_snapshot_follows_home(tmp_path):
+    """The cache snapshot reads ${HOME}, not the retired runner's admin path.
+
+    The conan home is ``~/.conan2``; the hard-coded ``/c/Users/admin`` was an
+    assumption about the GLR-py* service account, and under any other one the
+    job shipped an empty artifact and stayed green.
+    """
+    toml_file = write_gitlab_toml(tmp_path)
+    output_dir = tmp_path / "output"
+    generate_ci(str(toml_file), "1.0.0", str(output_dir))
+    content = (output_dir / ".gitlab-ci.yml").read_text(encoding="utf-8")
+    parsed = yaml.safe_load(content)
+
+    copies = [
+        step for step in parsed["Conan Deploy - Windows"]["script"]
+        if step.startswith("cp -r")
+    ]
+    assert len(copies) == 1
+    assert "${HOME}/.conan2/p" in copies[0]
+    assert "/c/Users/admin" not in content
+
+
 def test_github_linux_no_setup_python(ci_toml, tmp_path):
     """Linux job does not use actions/setup-python (Python is in the container)."""
     output_dir = tmp_path / "output"
diff --git a/xmsconan/generator_tools/ci_templates/gitlab-ci.yml.jinja b/xmsconan/generator_tools/ci_templates/gitlab-ci.yml.jinja
index d06ad26..32c1228 100644
--- a/xmsconan/generator_tools/ci_templates/gitlab-ci.yml.jinja
+++ b/xmsconan/generator_tools/ci_templates/gitlab-ci.yml.jinja
@@ -352,12 +352,23 @@ Conan Build:
 <% else %>
   stage: Test
 <% endif %>
-  image: GLR-${PY_TAG}
+<# One Windows image for every ABI. It replaced the per-version GLR-py310 /
+   GLR-py313 images, whose whole purpose was to make `python` on PATH the
+   matrix version: the recipe points CMake at the interpreter running conan
+   and the generated CMakeLists.txt requires that exact version (see
+   check_python_versions), so before GLR-UV the ABI had to be chosen by
+   picking an image and could not be changed inside the job. GLR-UV carries
+   uv and the pre-loaded 3.10 / 3.13 / 3.14 interpreters, so the script picks
+   the ABI itself with `uv venv --python` -- and PY_TAG, which existed only to
+   spell an image name, is gone with it.
+
+   `tags: WinVM` below still routes the job to the Windows fleet; `image:`
+   only selects which VM template that fleet starts. #>
+  image: GLR-UV
   parallel:
     matrix:
 <% for v in ci_python_versions %>
       - PYTHON_TARGET_VERSION: '<< v >>'
-        PY_TAG: 'py<< v | replace(".", "") >>'
 <% endfor %>
   variables:
     AQUAPI_URL: "https://aquapi.aquaveo.com/aquaveo/dev"
@@ -399,9 +410,21 @@ Conan Build:
     - export PACKAGE_VERSION=${CI_COMMIT_TAG:-0.0.0}
     - export CTEST_PARALLEL_LEVEL=${CTEST_PARALLEL_LEVEL:-8}
     - echo ${PACKAGE_VERSION}
+<# uv, not pip, and into a venv of the matrix ABI rather than the machine's
+   own interpreter. GLR-UV serves every ABI, so there is no longer a `python`
+   on PATH that happens to be the right one -- `uv venv --python` is what
+   makes it right, and it must come before anything reads `python`. Activating
+   persists for the rest of the script: GitLab runs these lines as one shell.
+
+   `uv --version` first so a runner without uv fails on that line with an
+   obvious message, rather than four lines later on a `uv pip install` that
+   reads like a packaging problem. #>
+    - uv --version
+    - uv venv --python ${PYTHON_TARGET_VERSION} .venv
+    - source .venv/Scripts/activate
     - python --version
-    - pip install "conan~=2.31.0" toml packaging devpi-client
-    - python -m pip install --upgrade "xmsconan>=<< xmsconan_version >>" -i https://public.aquapi.aquaveo.com/aquaveo/dev/+simple
+    - uv pip install "conan~=2.31.0" toml packaging devpi-client
+    - uv pip install --upgrade "xmsconan>=<< xmsconan_version >>" --index-url https://public.aquapi.aquaveo.com/aquaveo/dev/+simple
     - xmsconan_conan_setup
     - xmsconan_gen --version ${PACKAGE_VERSION} build.toml
 <% if ci_wheel_only %>
@@ -586,12 +609,16 @@ Repair Wheel:
 
 "Conan Deploy - Windows":
   stage: Deploy
-  image: GLR-${PY_TAG}
+  # GLR-UV and `uv venv`, for the reasons spelled out on "Conan Build -
+  # Windows" above. This job only restores and uploads a cache tarball, so it
+  # does not compile against the interpreter -- it still builds the venv on
+  # the matrix ABI so both Windows jobs bootstrap identically and neither can
+  # be the one that rots.
+  image: GLR-UV
   parallel:
     matrix:
 <% for v in ci_python_versions %>
       - PYTHON_TARGET_VERSION: '<< v >>'
-        PY_TAG: 'py<< v | replace(".", "") >>'
 <% endfor %>
   # Depend on the whole build job rather than selecting one parallel instance.
   # GitLab does not expand variables inside needs:parallel:matrix, so a selector
@@ -609,18 +636,28 @@ Repair Wheel:
       - conan_packages/
   script:
     - export PACKAGE_VERSION=${CI_COMMIT_TAG:-0.0.0}
-    - pip install "conan~=2.31.0" -i https://public.aquapi.aquaveo.com/aquaveo/dev/+simple
-    - pip install --upgrade "xmsconan>=<< xmsconan_version >>" -i https://public.aquapi.aquaveo.com/aquaveo/dev/+simple
+    - uv --version
+    - uv venv --python ${PYTHON_TARGET_VERSION} .venv
+    - source .venv/Scripts/activate
+    - uv pip install "conan~=2.31.0" --index-url https://public.aquapi.aquaveo.com/aquaveo/dev/+simple
+    - uv pip install --upgrade "xmsconan>=<< xmsconan_version >>" --index-url https://public.aquapi.aquaveo.com/aquaveo/dev/+simple
     - xmsconan_conan_setup
     - xmsconan_conan_deploy << library_name >> ${PACKAGE_VERSION} --restore .export/<< library_name >>-windows-py${PYTHON_TARGET_VERSION}-${PACKAGE_VERSION}.tar.gz --upload
     - mkdir -p conan_packages
-    <# `|| echo`, not `|| true`: with nothing under the cache path -- a runner
-       whose user is not `admin`, or a restore that produced nothing -- the
-       job used to go green and ship an empty conan_packages/ artifact with
-       no line in the log saying so. It stays non-fatal because the upload
-       above has already succeeded by this point and nothing consumes this
-       artifact; it is a snapshot of the cache for debugging. #>
-    - cp -r /c/Users/admin/.conan2/p/* conan_packages/ || echo "warning - no Conan packages under /c/Users/admin/.conan2/p, conan_packages/ artifact will be empty"
+    <# ${HOME}, not the hard-coded /c/Users/admin the GLR-py* images ran as:
+       the conan home is `~/.conan2`, so a runner whose service account is
+       anyone else silently produced an empty artifact. GLR-UV is a different
+       machine, so the old literal is exactly the kind of assumption this
+       migration has to stop making.
+
+       `|| echo`, not `|| true`: with nothing under the cache path -- a
+       restore that produced nothing, or a HOME that is not where conan put
+       its cache -- the job used to go green and ship an empty
+       conan_packages/ artifact with no line in the log saying so. It stays
+       non-fatal because the upload above has already succeeded by this point
+       and nothing consumes this artifact; it is a snapshot of the cache for
+       debugging. #>
+    - cp -r ${HOME}/.conan2/p/* conan_packages/ || echo "warning - no Conan packages under ${HOME}/.conan2/p, conan_packages/ artifact will be empty"
   only:
     - tags
   tags:

From dd0142138b2500f469295f25a4d30ab6c26fc716 Mon Sep 17 00:00:00 2001
From: Gage Larsen <glarsen@aquaveo.com>
Date: Tue, 1 Sep 2026 14:07:25 -0600
Subject: [PATCH 2/3] Build the msvc 192 matrix in GitLab CI, behind
 [ci].windows_vs2019

GLR-UV carries VS2019 alongside VS2022, so the matrix that had to be
built by hand on a developer workstation can be built on every pipeline
instead. Opt-in: it roughly doubles the Windows half of a pipeline, and
only the libraries the VS2019-era desktop products consume need msvc 192
binaries at all.

The jobs are emitted beside the msvc 194 pair, not instead of it, and
reuse its shape -- same runner, same ABI fan-out, same tag-gated
export/restore split. Four things differ, and all four are load-bearing:

* `build.py --platform windows_vs2019` selects the matrix. The recipe
  already forks its third-party stack on compiler.version; what was not
  reachable from build.py is `apply_boost_defaults=False`, which the
  legacy boost/1.74.0.3 recipe needs because Conan fails a build outright
  when a profile sets an option no recipe in the graph defines. Both that
  and the upload destination are derived from --platform rather than
  exposed as separate flags: a pipeline cannot then set the matrix and
  the destination differently.
* The aquaveo-vs2019 remote is added with `xmsconan_conan_setup
  --remote-name ... --append`. The function already took both; only the
  CLI could not reach them. Appended, not inserted first, so it does not
  become the first stop for every conan install on a shared runner.
* Every deploy step carries --package-query compiler.version=192, which
  xmsconan_conan_deploy also gained. A runner's Conan cache is per
  machine, not per job, and both `conan cache save` and `conan upload`
  match by *reference* -- so an unqueried msvc 192 publish would carry a
  concurrent msvc 194 job's binaries onto the remote whose only purpose
  is to keep the two apart, and exit 0 having done it. `cache save`
  cannot take a query directly, so it resolves one through `conan list`
  into a package list, in a temp file deleted on both paths.
* No wheels. A wheel's tags say nothing about which MSVC built it, so an
  msvc 192 wheel and an msvc 194 wheel are the same devpi filename and
  publishing both would have them overwrite each other by upload order.
  The VS2019 wheels stay a deliberate manual step.

VS2019_PLATFORM_KEY moves to constants.py, where the generator and the
workstation driver both read it, and the generated build.py carries the
three msvc 192 literals rendered in rather than imported -- a new name in
xmsconan.constants would otherwise make a freshly generated build.py die
on an ImportError against an older installed client.

Docs: USAGE.md CLI table, [ci] table, build.py flag table, section 10.2,
section 16's premise (which said none of this runs in CI), the required
CI variables, and three troubleshooting entries.
---
 docs/USAGE.md                                 |  35 +++-
 tests/test_build_file_generator.py            | 105 +++++++++++-
 tests/test_ci_file_generator.py               | 158 ++++++++++++++++++
 tests/test_conan_deploy.py                    | 126 ++++++++++++++
 tests/test_conan_setup.py                     |  26 ++-
 xmsconan/build_toml.py                        |  15 ++
 xmsconan/build_tools/vs2019_build.py          |  10 +-
 xmsconan/ci_tools/conan_deploy.py             | 109 ++++++++++--
 xmsconan/ci_tools/conan_setup.py              |  20 ++-
 xmsconan/constants.py                         |  16 +-
 .../generator_tools/build_file_generator.py   |  16 +-
 xmsconan/generator_tools/ci_file_generator.py |  42 ++++-
 .../ci_templates/gitlab-ci.yml.jinja          | 115 +++++++++++++
 .../generator_tools/templates/build.py.jinja  |  40 ++++-
 14 files changed, 797 insertions(+), 36 deletions(-)

diff --git a/docs/USAGE.md b/docs/USAGE.md
index 0cc2bba..71b273d 100644
--- a/docs/USAGE.md
+++ b/docs/USAGE.md
@@ -70,11 +70,11 @@ All commands live under the `xmsconan` umbrella:
 | `xmsconan build` | Run `conan install` + `cmake configure` against a single profile. Used by the generated `build.py`; also useful for one-off configures. |
 | `xmsconan coverage` | Run the unified C++/Python coverage pipeline and enforce the `[coverage]` thresholds (see §11). `--phase collect` stops after producing the reports; `--phase report` gates an existing set of them (§11.4). |
 | `xmsconan test-shards` | Run a staged gtest runner as N parallel shards inside the current container and merge their JUnit reports into one. What the generated GitLab `Run C++ Tests - <label>` jobs call (see §10.2). |
-| `xmsconan vs2019` | Drive the manual Visual Studio 2019 (msvc 192) build and publish it to the `aquaveo-vs2019` remote (see §16). Never runs in CI. |
-| `xmsconan conan-setup` | Detect a Conan profile, add the aquaveo remote, optionally login. The password comes from `--password-file`, `$CONAN_PASSWORD`, or `~/.xmsconan.toml` — there is no `--password` flag (§17). |
+| `xmsconan vs2019` | Drive the manual Visual Studio 2019 (msvc 192) build and publish it to the `aquaveo-vs2019` remote (see §16). Never runs in CI itself; GitLab reaches the same matrix through `[ci].windows_vs2019` and `build.py --platform` instead. |
+| `xmsconan conan-setup` | Detect a Conan profile, add the aquaveo remote, optionally login. `--remote-name` / `--remote-url` name a different remote, and `--append` adds it *after* the remotes already configured rather than first — which is what a special-purpose remote such as `aquaveo-vs2019` needs, so it does not become the first stop for every `conan install` on a shared machine. The password comes from `--password-file`, `$CONAN_PASSWORD`, or `~/.xmsconan.toml` — there is no `--password` flag (§17). |
 | `xmsconan wheel-repair` | Run platform-appropriate wheel repair (auditwheel / delocate / delvewheel). |
 | `xmsconan wheel-deploy` | Upload repaired wheels to devpi. |
-| `xmsconan conan-deploy` | Save / restore / upload Conan packages between CI stages. |
+| `xmsconan conan-deploy` | Save / restore / upload Conan packages between CI stages. `--remote` picks the destination; `--package-query` restricts **both** the save and the upload to matching binaries (e.g. `compiler.version=192`). The query is required when publishing to a toolchain-specific remote from a shared runner: `conan cache save` and `conan upload` match by *reference*, and a CI runner's Conan cache is per machine, not per job. |
 | `xmsconan publish` | The full release pipeline (gen → build → repair → deploy). |
 
 Run `xmsconan <cmd> --help` for the full flag set. The legacy underscored names (`xmsconan_gen`, `xmsconan_ci`, …) still work and are what the generated CI scripts call.
@@ -195,6 +195,7 @@ These drive the CI templates. All optional.
 | `ci_type` | — | `"github"` or `"gitlab"`. **Required** for `xmsconan ci`. (Lives at the top level, not under `[ci]`.) |
 | `[ci].windows` | `true` | Emit a Windows job. |
 | `[ci].linux` | `true` | Emit the Linux jobs. **GitLab only**, like `[ci].windows` — the GitHub templates ignore both. Setting it to `false` also removes `Repair Wheel`, `Wheel Deploy`, `Conan Deploy - Linux` and the `Package` stage: those three jobs are Linux-specific and consume the Linux job's artifacts through `dependencies:`. The Windows wheel jobs are unaffected — each platform stages and publishes its own wheel (§10.2). Intended for libraries that cannot build on Linux at all; see the note below. |
+| `[ci].windows_vs2019` | `false` | Also build the `windows_vs2019` (msvc 192) matrix and publish it to the `aquaveo-vs2019` remote. **GitLab only** — a GitHub project setting it gets a warning and no jobs. Emits `Conan Build - Windows VS2019` and (with `[ci].deploy`) `Conan Deploy - Windows VS2019`, beside the msvc 194 pair rather than instead of it, so it requires `[ci].windows` and is rejected with it off. Opt-in because it roughly doubles the Windows half of a pipeline and only the libraries the VS2019-era desktop products consume need msvc 192 binaries. No wheels: see §10.2. |
 | `[ci].windows_wheel_repair` | **derived from `ci_type`**: `true` on `github`, `false` on `gitlab` | Repair the Windows wheel. `false` drops `xmsconan_wheel_repair --platform windows` from the Windows job on **both** GitLab and GitHub, drops the same step from `xmsconan publish` when it runs on Windows and from the `xmsconan vs2019` track, and passes `--skip-dependency-libs` to `build.py` so the Conan cache's DLLs are not staged for a repair that no longer happens. The unrepaired wheel is still built, uploaded as an artifact, and deployed. Windows-scoped by design — see §12.1 for the default's rationale. |
 | `[ci].linux_arm` | `false` | Emit a Linux ARM job (GitHub only). |
 | `[ci].deploy` | `true` | Emit deploy jobs (only run on tag pushes). |
@@ -472,7 +473,10 @@ What opting in turns on:
   linux-arm and windows jobs from their respective lists. GitLab: `parallel:matrix`
   over `PYTHON_TARGET_VERSION` on `Conan Build` / `Conan Deploy - Linux` (from
   `linux_python_versions`) and on `Conan Build - Windows` / `Conan Deploy - Windows`
-  (from `python_versions`, which also derives `PY_TAG`).
+  (from `python_versions`) — plus the `… - Windows VS2019` pair when
+  `[ci].windows_vs2019` is set, over the same list. On Windows the variable is
+  what `uv venv --python` is given, so it selects the interpreter directly
+  rather than naming a per-ABI runner image.
 - **Linux container images follow the matrix leg** —
   `ghcr.io/aquaveo/conan-gcc13-py${{ matrix.python-version }}:latest` on GitHub and
   `…/conan-gcc13-py${PYTHON_TARGET_VERSION}` on GitLab. An explicit
@@ -525,6 +529,7 @@ python build.py   --version 0.0.0 --wheel-dir wheelhouse --artifacts-dir test_ar
 | `--python-only` | Equivalent to `--filter '{"options": {"pybind": true}}'`. |
 | `--preview` | Print the configuration table and exit. Nothing is built. |
 | `--build-missing` | Pass `--build=missing` to `conan create`. |
+| `--platform KEY` | Which matrix to build: `windows`, `windows_vs2019`, `linux`, `darwin`. Defaults to detecting the running machine, which is what every leg other than the msvc 192 ones passes. `--platform windows_vs2019` also drops the boost option defaults (the legacy `boost/1.74.0.3` recipe does not declare them, and Conan fails a build when a profile sets an option no recipe in the graph defines) and, with `--upload`, sends the result to `aquaveo-vs2019` under a `compiler.version=192` package query. All three follow from the one flag, so the matrix and its destination cannot be set differently. |
 | `--wheel-dir DIR` | After the build, copy each `pybind` package's wheel into `DIR`. With `python_versions=["3.10","3.13"]`, you get one wheel per version. **A run that asked for wheels and got no complete set exits 1** — the flag is a request, not a hint, so only pass it where a wheel is expected. A matrix with no pybind configuration at all (`--filter '{"build_type": "Debug"}'` with the default `[matrix].pybind_build_types`, §5.4.1) is that case. |
 | `--repair` | Run `repair_linux_wheel` after extraction (Docker required). |
 | `--artifacts-dir DIR` | Save per-config test artifacts (LastTest.log, runner binary, `_package/`, `test_files/`) for debugging. |
@@ -608,6 +613,11 @@ The generated jobs follow the pattern:
 - **One test job per testing configuration, each naming its own.** `[ci].split_tests` emits a `Run C++ Tests - <label>` job for every testing configuration the Linux build stages — `Release-testing` and `Debug-testing` on the default matrix — and each passes its own `--label`. They are peers in the `Test` stage off the single `Conan Build`, and each uploads only its own `test_artifacts/<label>/` (the `needs: artifacts: true` download hands every job the whole staged tree, so an unscoped path would have each one re-upload the others' runners too). Every job writes `TEST-cxxtest.xml`; GitLab keys the pipeline test report on the job name, so the configurations stay distinguishable in the MR widget. The labels are computed by the generator with the same `config_label()` the build names the directories with, so the two cannot drift — a template concatenating `<build_type>-testing` would be a second implementation free to. **This is what a single job got wrong:** it found its directory by falling back to the first of `Debug-testing`, `Release-testing` that existed, so a matrix building both compiled the Release runner on every pipeline and never executed it, with nothing red to show for it. `xmsconan_test_shards` keeps that fallback for interactive use after a local `build.py`, but no generated pipeline relies on it any more.
 - **Each job shards inside one container.** The job downloads the build job's `test_artifacts/`, then runs `xmsconan_test_shards`, which restores the executable bit on the runner (a GitLab artifact round-trip drops it), relinks `test_files/` next to the runner, and forks `[ci].test_shards` runner processes with `GTEST_TOTAL_SHARDS`/`GTEST_SHARD_INDEX` set. Each shard writes its own gtest XML, which the tool merges by suite name into `TEST-cxxtest.xml` and declares as `artifacts:reports:junit`, so a failing case shows up in the MR widget by name. Per-shard console output is held and replayed as one contiguous block rather than interleaved. A shard that dies before writing XML — a timeout, a segfault — contributes a synthetic error suite to the merged report, so a red job never shows an all-green test tab. Without `test_shards` the same script runs a single shard: one code path, so the artifact discovery and `test_files` relinking do not have to exist twice. With `[ci].xvfb = true` each shard gets its own X display, because `xvfb-run -a` picks a free server number and N simultaneous starts race for it.
 - `Conan Build - Windows`, `Conan Deploy - Windows`: `parallel:matrix` over `PYTHON_TARGET_VERSION` from `python_versions`. Both run on `image: GLR-UV` with `tags: [WinVM]` — `image:` selects the VM template, the tag routes to the Windows fleet. One image serves every ABI: the job establishes the interpreter itself with `uv venv --python ${PYTHON_TARGET_VERSION} .venv`, activates it, and installs conan and xmsconan into it with `uv pip install`. That venv is load-bearing, not hygiene — the recipe points CMake at the interpreter running conan and the generated `CMakeLists.txt` requires that exact version, which is what the retired per-ABI `GLR-py310` / `GLR-py313` images existed to provide. `uv --version` runs first so a runner without uv fails on a line that says so, and nothing reads `python` before the venv is active.
+- `Conan Build - Windows VS2019`, `Conan Deploy - Windows VS2019` (only with `[ci].windows_vs2019`, §5.6): the second Windows toolchain, msvc 192. Same runner, same ABI fan-out and same tag-gated export/restore split as the msvc 194 pair; four things differ, and all four are load-bearing.
+  - `build.py --platform windows_vs2019` selects the msvc 192 matrix. The recipe forks its third-party stack on `compiler.version` (boost 1.74.0.3 + zlib 1.2.11 rather than 1.86.0 + 1.3.1), and `build.py` drops the boost option defaults for this platform because the legacy recipe does not declare them. `--build-missing` goes with it: the legacy dependency graph is not fully prebuilt.
+  - The `aquaveo-vs2019` remote is added with `xmsconan_conan_setup --remote-name … --append`. Appended, not inserted first: on a shared runner it must not become the first stop for every `conan install`. It is where the legacy dependencies resolve from as well as where the results go.
+  - Every deploy step carries `--package-query compiler.version=192`. The Conan cache on a runner is per machine, not per job, so both `conan cache save` and `conan upload` — which match by *reference* — would otherwise carry a concurrent msvc 194 job's binaries onto the remote whose only purpose is to keep the two toolchains apart, and exit 0 having done it.
+  - **No wheels.** A wheel's tags (`cp310-cp310-win_amd64`) say nothing about which MSVC built it, so an msvc 192 wheel and an msvc 194 wheel are the same devpi filename and publishing both would have them overwrite each other by upload order. The VS2019 wheels the desktop products consume are still produced deliberately, by hand (§16.8).
 - Wheel-repair always runs `cp313-cp313`'s `xmsconan_wheel_repair` inside the manylinux container; auditwheel itself doesn't care about the host Python.
 - Required CI variables: `AQUAPI_URL`, `AQUAPI_USERNAME`, `AQUAPI_PASSWORD` (for wheel deploy).
   They are read from the process environment by `xmsconan_wheel_deploy` and are deliberately **not** placed in any
@@ -615,9 +625,14 @@ The generated jobs follow the pattern:
   `conan create`, so a credential put there is printed to the job log in cleartext. Nothing in the recipe or the
   generated CMake reads them, so a build is unaffected. This is why they are absent from the `[filter.buildenv]`
   names in §5.8 -- they are not names the profiles set.
+- Required CI variables with `[ci].windows_vs2019`: `CONAN_LOGIN_USERNAME_AQUAVEO_VS2019` and
+  `CONAN_PASSWORD_AQUAVEO_VS2019`, for the upload to `aquaveo-vs2019`. Conan derives those names by uppercasing
+  the remote name and replacing hyphens with underscores, and reads them from the environment — the generated job
+  adds the remote but never logs in explicitly, exactly as it does for `aquaveo`. Without them the build jobs still
+  pass and only the tag-time deploy fails, so add the variables before the first release rather than after.
 - `[ci].linux = false` yields a **Windows-only pipeline**: `Conan Build - Windows`, `Lint`, and (on tags) `Wheel Deploy - Windows` and `Conan Deploy - Windows`. Two combinations are rejected at generation time rather than producing a pipeline that fails opaquely later — `linux = false` together with `windows = false` (nothing would build), and `linux = false` with `coverage = true` (coverage compiles with `--coverage` under gcc, and the generated `CMakeLists.txt` rejects MSVC when `XMS_COVERAGE` is set).
 - **Each platform stages and publishes its own wheel.** Linux builds one, repairs it in the Package-stage `Repair Wheel` job, and uploads it from `Wheel Deploy`. Windows passes `--wheel-dir wheelhouse` and then repairs *in place* inside `Conan Build - Windows`, because `delvewheel` reads the DLL imports of a `win_amd64` `.pyd` and only runs on a Windows host — the manylinux container that repairs the Linux wheel cannot stand in. `Wheel Deploy - Windows` uploads the result on tags from a plain `python:3.13` image, since a devpi upload needs no MSVC toolchain. A Windows-only pipeline therefore publishes wheels, and the manual VS2019 track (§16.8) is no longer the only route. `[ci].windows_wheel_repair = false` drops the Windows repair step for a library that has nothing to vendor — see §12.1; the deploy job is unaffected either way.
-- **The Windows cache snapshot is best-effort, and says so.** `Conan Deploy - Windows` copies the Conan cache into a `conan_packages/` artifact for debugging after the upload has already succeeded. It used to end in `|| true`, which made "copied nothing" indistinguishable from "copied everything" — a runner whose home directory is not `/c/Users/admin` shipped an empty artifact with no line in the log. It now prints a warning instead, and stays non-fatal: nothing consumes the artifact, and the upload it follows fails loudly on its own.
+- **The Windows cache snapshot is best-effort, and says so.** `Conan Deploy - Windows` copies the Conan cache into a `conan_packages/` artifact for debugging after the upload has already succeeded. It reads `${HOME}/.conan2/p`, since the Conan home is `~/.conan2`; it used to name `/c/Users/admin` outright, which was an assumption about the retired runner's service account. It also used to end in `|| true`, which made "copied nothing" indistinguishable from "copied everything" — any other account shipped an empty artifact with no line in the log. It now prints a warning instead, and stays non-fatal: nothing consumes the artifact, and the upload it follows fails loudly on its own.
 - **The Windows wheel jobs fan out with the build matrix.** `Conan Build - Windows` runs once per `PYTHON_TARGET_VERSION`, and each instance stages its own wheel into `wheelhouse/`. Each wheel's own ABI tag (`cp310` / `cp313` / `cp314`) keeps the files distinct, so the merged artifact holds every wheel and one `Wheel Deploy - Windows` job uploads the set.
 
 ### 10.3 Toolchain versions
@@ -863,9 +878,13 @@ What it runs (with `--no-deploy=false`):
 
 ## 16. VS2019 / msvc 192 packages (`xmsconan vs2019`)
 
-GitHub retired the `windows-2019` runner image, so the msvc 192 (Visual Studio 2019) binaries that the Aquaveo desktop products (GMS/SMS/WMS) consume can no longer be produced in CI. They are built **by hand, on a developer workstation that has VS2019 installed**, and published to a **separate Conan remote, `aquaveo-vs2019`**, so they never mix with the CI-published binaries.
+The msvc 192 (Visual Studio 2019) binaries that the Aquaveo desktop products (GMS/SMS/WMS) consume are published to a **separate Conan remote, `aquaveo-vs2019`**, so they never mix with the CI-published binaries. `xmsconan vs2019` drives that build **by hand, on a developer workstation that has VS2019 installed**.
 
-> **None of this runs in CI, and that is deliberate.** CI is untouched: it still builds gcc 13 / apple-clang 17 / msvc 194 and publishes to the `aquaveo` remote (the `aquaveo-stable` Artifactory repo). There is no Windows-2019 job to "restore" — the runner image is gone. If you are looking for the CI matrix, see §10.
+> **GitLab CI can now build this matrix too.** The GitLab `GLR-UV` runner carries VS2019 alongside VS2022, so a repository can set `[ci].windows_vs2019 = true` (§5.6) and get `Conan Build - Windows VS2019` on every pipeline, publishing to the same `aquaveo-vs2019` remote — reproducibly, rather than whenever someone remembers to run this by hand. GitHub cannot: it retired the `windows-2019` image and has no replacement.
+>
+> This track stays, and is still the only route for two things: **wheels**, which CI deliberately does not publish for msvc 192 (a wheel's tags do not record which MSVC built it, so it would collide with the msvc 194 wheel on devpi — see §10.2 and §16.8), and **libraries whose repository has not opted in**. It is also what you want for a one-off local rebuild.
+>
+> If you are looking for the CI matrix, see §10.
 
 Available both as `xmsconan vs2019 <subcommand>` and as the console script `xmsconan_vs2019 <subcommand>`. Three subcommands: `setup`, `build`, `upload`.
 
@@ -1154,6 +1173,8 @@ Wheels are tagged `cp310-cp310-...` or `cp313-cp313-...`; pip picks the right on
 - **Linux job fails pulling its container.** The generated `container:` block pulls without credentials, which only works for a public image. On GHCR `conan-gcc13-py3.13` is public but `conan-gcc13-py3.14` is not, so a 3.14 Linux leg fails at pull until the package visibility is changed or a `credentials:` stanza is added.
 - **`xmsconan vs2019 build` stops at preflight with "outside the pinned `~=2.31.0` series".** Intentional (§16.3). Install the pinned client — `pip install "conan~=2.31.0"` — rather than working around the check; a different minor can change package_ids and detach your build from what's already published.
 - **VS2019 build fails on a boost option Conan says no recipe defines.** The legacy `boost/1.74.0.3` doesn't declare the conan-center 1.86 options. The driver already passes `apply_boost_defaults=False`; if you're constructing `XmsConanPackager` yourself for msvc 192, pass it too (§16.6).
+- **`Conan Deploy - Windows VS2019` fails authenticating to `aquaveo-vs2019`.** The job adds the remote but never logs in explicitly; Conan reads `CONAN_LOGIN_USERNAME_AQUAVEO_VS2019` / `CONAN_PASSWORD_AQUAVEO_VS2019` from the environment. Add both as GitLab CI variables. Only the tag-time deploy needs them, so the branch pipelines pass without them and the gap surfaces at the first release.
+- **msvc 194 binaries turned up on the `aquaveo-vs2019` remote.** Something published without `--package-query compiler.version=192`. Both `conan cache save` and `conan upload` match by reference, and a runner's Conan cache is shared across the jobs on that machine, so an unqueried publish from the msvc 192 job carries whatever the msvc 194 job left behind. The generated pipeline passes the query on every deploy step; a hand-run `xmsconan_conan_deploy` or a `build.py --upload` without `--platform windows_vs2019` does not.
 - **VS2019 packages don't show up for consumers.** They go to `aquaveo-vs2019`, not `aquaveo` — the consuming machine needs that remote configured too. Note that `xmsconan_vs2019 setup` *appends* the remote rather than putting it first (§16.2), so it does not shadow `aquaveo` for your other work.
 - **`xmsconan vs2019 build` exits 3 with a table of `skipped` rows.** Nothing was built. Almost always a typo in `--root` (each library is looked for at `<root>/<library>`), a `--filter` that matches no configuration, or a library that has no `build.toml` yet. See the exit-code table in §16.4.
 - **`Could NOT find Python3: Found unsuitable version "3.12.0", but required is exact version "3.10"`.** The interpreter running conan *is* the target Python for a pybind build (§16.8). Re-run from a 3.10 virtual environment, or build the version you're running with `--python-versions 3.12`. `xmsconan vs2019 build` now catches this at preflight and exits 2 before compiling anything — but only when the filtered matrix actually contains a pybind configuration.
diff --git a/tests/test_build_file_generator.py b/tests/test_build_file_generator.py
index 48ea164..4a9be0c 100644
--- a/tests/test_build_file_generator.py
+++ b/tests/test_build_file_generator.py
@@ -706,6 +706,106 @@ def test_generated_build_py_passes_the_matrix_to_the_packager(tmp_path):
     assert "matrix=conanfile.CONAN_MATRIX," in content
 
 
+def _render_build_py_text(tmp_path):
+    """Render build.py from this repository's template and return its text."""
+    toml_file = tmp_path / "build.toml"
+    toml_file.write_text(
+        'library_name = "xmscore"\ndescription = "desc"\n', encoding="utf-8"
+    )
+    tpl_dir = tmp_path / "tpl"
+    tpl_dir.mkdir()
+    _copy_template("build.py.jinja", tpl_dir)
+    output_dir = tmp_path / "output"
+    render_template_with_toml(
+        toml_file_path=str(toml_file),
+        version="1.0.0",
+        template_dir=str(tpl_dir),
+        output_dir=str(output_dir),
+    )
+    return (output_dir / "build.py").read_text(encoding="utf-8")
+
+
+def test_generated_build_py_carries_the_vs2019_identity_as_literals(tmp_path):
+    """The msvc 192 platform, remote and version are rendered in, not imported.
+
+    build.py already calls into the installed xmsconan for the packager, but a
+    *new name* in xmsconan.constants would make a freshly generated build.py
+    die on an ImportError at line 8 against an older installed client -- before
+    argparse, with nothing said about versions. The values are rendered from
+    the same constants, so they cannot disagree with the tools that read them.
+    """
+    content = _render_build_py_text(tmp_path)
+
+    assert 'VS2019_PLATFORM = "windows_vs2019"' in content
+    assert 'VS2019_REMOTE = "aquaveo-vs2019"' in content
+    assert 'VS2019_MSVC_VERSION = "192"' in content
+    assert "from xmsconan.constants import" not in content
+    compile(content, "build.py", "exec")
+
+
+def test_generated_build_py_ties_boost_defaults_and_upload_remote_to_platform(tmp_path):
+    """--platform alone decides the matrix, the boost defaults and the remote.
+
+    All three have to move together. The boost option defaults name conan-center
+    boost 1.86 options that the legacy boost/1.74.0.3 recipe does not declare,
+    and Conan fails a build outright when a profile sets an option no recipe in
+    the graph defines; the msvc 192 binaries belong on their own remote, and
+    `conan upload` matches by reference, so a query is what keeps a machine's
+    msvc 194 binaries from going with them. Deriving all three from one flag is
+    what makes it impossible to set the matrix and the destination differently.
+    """
+    content = _render_build_py_text(tmp_path)
+
+    assert "apply_boost_defaults = args.platform != VS2019_PLATFORM" in content
+    assert "apply_boost_defaults=apply_boost_defaults," in content
+    assert "builder.generate_configurations(system_platform=args.platform)" in content
+    assert "if args.platform == VS2019_PLATFORM:" in content
+    assert '"remote": VS2019_REMOTE,' in content
+    assert '"package_query": f"compiler.version={VS2019_MSVC_VERSION}",' in content
+
+
+def test_generated_build_py_builds_the_msvc_192_matrix_when_asked(tmp_path):
+    """`build.py --preview --platform windows_vs2019` really produces msvc 192.
+
+    The neighbouring tests assert the flag is rendered and wired; this one runs
+    it, because "wired to generate_configurations" and "generates the legacy
+    matrix" are different claims -- and the platform key is a string the
+    packager could stop recognizing without any of the text changing.
+    """
+    import os
+    import subprocess
+    import sys
+
+    from xmsconan import generator_tools
+
+    toml_file = tmp_path / "build.toml"
+    toml_file.write_text('library_name = "xmscore"\ndescription = "Core"\n', encoding="utf-8")
+    output_dir = tmp_path / "output"
+    render_template_with_toml(
+        toml_file_path=str(toml_file),
+        version="1.0.0",
+        template_dir=str(REAL_TEMPLATE_DIR),
+        output_dir=str(output_dir),
+    )
+    copy_xms_conan2_file(str(output_dir))
+
+    # PYTHONPATH pins the subprocess to *this* checkout. build.py runs from the
+    # generated directory, so it would otherwise import whatever xmsconan is
+    # installed on the machine and the test would grade someone else's tree.
+    repo_root = Path(generator_tools.__file__).resolve().parents[2]
+    result = subprocess.run(
+        [sys.executable, "build.py", "--preview", "--platform", "windows_vs2019"],
+        cwd=str(output_dir), capture_output=True, text=True,
+        env={**os.environ, "PYTHONPATH": str(repo_root)},
+    )
+
+    assert result.returncode == 0, result.stdout + result.stderr
+    assert "boost defaults not applied" in result.stdout
+    # Every configuration in the table is msvc 192, and none is the CI toolchain.
+    assert "192" in result.stdout
+    assert "194" not in result.stdout
+
+
 def test_generated_build_py_can_skip_the_dependency_libs_pass(tmp_path):
     """build.py exposes --skip-dependency-libs, which the CI passes when repair is off.
 
@@ -984,7 +1084,10 @@ def test_generated_build_py_exits_nonzero_on_upload_failure(build_toml, tmp_path
     content = (output_dir / "build.py").read_text(encoding="utf-8")
     # Matched loosely: the guarantee is that upload()'s return code is compared
     # against 0 and drives exit(1), not the exact spacing of the generated line.
-    assert re.search(r"if\s+builder\.upload\(version=args\.version\)\s*!=\s*0\s*:", content)
+    assert re.search(
+        r"if\s+builder\.upload\(version=args\.version,\s*\*\*upload_kwargs\)\s*!=\s*0\s*:",
+        content,
+    )
     assert "exit(1)" in content
     compile(content, "build.py", "exec")
 
diff --git a/tests/test_ci_file_generator.py b/tests/test_ci_file_generator.py
index c3a22b8..af33cd0 100644
--- a/tests/test_ci_file_generator.py
+++ b/tests/test_ci_file_generator.py
@@ -1611,6 +1611,164 @@ def _gitlab_jobs(tmp_path, **ci_flags):
     return yaml.safe_load((output_dir / ".gitlab-ci.yml").read_text(encoding="utf-8"))
 
 
+def test_gitlab_vs2019_jobs_are_opt_in(tmp_path):
+    """No [ci].windows_vs2019 means no msvc 192 jobs.
+
+    The matrix roughly doubles the Windows half of a pipeline and only the
+    libraries the VS2019-era desktop products consume need it, so a repository
+    that has never asked for msvc 192 must not start building it because its
+    runner acquired a second toolchain.
+    """
+    pipeline = _gitlab_jobs(tmp_path)
+
+    assert "Conan Build - Windows VS2019" not in pipeline
+    assert "Conan Deploy - Windows VS2019" not in pipeline
+    # The msvc 194 jobs are untouched by the opt-in being absent.
+    assert "Conan Build - Windows" in pipeline
+
+
+def test_gitlab_vs2019_build_selects_the_msvc_192_matrix(tmp_path):
+    """The build job passes --platform windows_vs2019 and nothing else does.
+
+    That flag is the whole difference in what gets compiled: it selects the
+    msvc 192 platform key, and `build.py` reads it to drop the boost option
+    defaults the legacy boost/1.74.0.3 recipe does not declare. The msvc 194
+    job must not acquire it.
+    """
+    pipeline = _gitlab_jobs(tmp_path, windows_vs2019=True)
+
+    builds = [step for step in pipeline["Conan Build - Windows VS2019"]["script"]
+              if step.startswith("python build.py")]
+    assert len(builds) == 1
+    assert "--platform windows_vs2019" in builds[0]
+    # The legacy dependency graph is not fully prebuilt for msvc 192.
+    assert "--build-missing" in builds[0]
+
+    other = [step for step in pipeline["Conan Build - Windows"]["script"]
+             if step.startswith("python build.py")]
+    assert all("--platform" not in step for step in other)
+
+
+def test_gitlab_vs2019_build_publishes_no_wheel(tmp_path):
+    """No --wheel-dir, and no wheel artifact, on either msvc 192 job.
+
+    A wheel's tags (cp310-cp310-win_amd64) say nothing about which MSVC built
+    it, so an msvc 192 wheel and an msvc 194 wheel are the same devpi filename
+    -- publishing both would have them overwrite each other by upload order.
+    """
+    pipeline = _gitlab_jobs(tmp_path, windows_vs2019=True)
+
+    job = pipeline["Conan Build - Windows VS2019"]
+    assert all("--wheel-dir" not in step for step in job["script"])
+    assert all("wheel" not in path for path in job["artifacts"]["paths"])
+    # And no deploy job was added for a wheel that is never staged.
+    assert "Wheel Deploy - Windows VS2019" not in pipeline
+
+
+def test_gitlab_vs2019_jobs_keep_msvc_192_off_the_ci_remote(tmp_path):
+    """Every msvc 192 deploy step names the VS2019 remote and the 192 query.
+
+    Both halves, on both jobs. The Conan cache on a runner is per machine, not
+    per job, so a save or an upload matching by reference alone would carry the
+    msvc 194 job's binaries onto a remote whose only purpose is to keep the two
+    toolchains apart -- and exit 0 having done it.
+    """
+    pipeline = _gitlab_jobs(tmp_path, windows_vs2019=True)
+
+    deploys = [
+        step
+        for name in ("Conan Build - Windows VS2019", "Conan Deploy - Windows VS2019")
+        for step in pipeline[name]["script"]
+        if step.startswith("xmsconan_conan_deploy")
+    ]
+    assert len(deploys) == 2
+    for step in deploys:
+        assert "--package-query compiler.version=192" in step
+    upload = [step for step in deploys if "--upload" in step]
+    assert len(upload) == 1
+    assert "--remote aquaveo-vs2019" in upload[0]
+
+    # The VS2019 remote is added, and appended rather than inserted first: on a
+    # shared runner it must not become the first stop for every conan install.
+    for name in ("Conan Build - Windows VS2019", "Conan Deploy - Windows VS2019"):
+        setups = [step for step in pipeline[name]["script"]
+                  if step.startswith("xmsconan_conan_setup")]
+        assert any(
+            "--remote-name aquaveo-vs2019" in step and "--append" in step
+            for step in setups
+        ), name
+        # The CI remote is still configured: the recipe's own dependencies
+        # resolve from it even on the legacy toolchain.
+        assert "xmsconan_conan_setup" in setups
+
+
+def test_gitlab_vs2019_jobs_match_the_msvc_194_shape(tmp_path):
+    """Same runner, same ABI fan-out, same tag-gated deploy as the msvc 194 pair."""
+    pipeline = _gitlab_jobs(
+        tmp_path, windows_vs2019=True, python_versions=["3.10", "3.13"],
+    )
+
+    for name in ("Conan Build - Windows VS2019", "Conan Deploy - Windows VS2019"):
+        job = pipeline[name]
+        assert job["image"] == "GLR-UV", name
+        assert job["tags"] == ["WinVM"], name
+        matrix = job["parallel"]["matrix"]
+        assert [entry["PYTHON_TARGET_VERSION"] for entry in matrix] == ["3.10", "3.13"], name
+        assert job["script"].index("uv venv --python ${PYTHON_TARGET_VERSION} .venv") < \
+            job["script"].index("source .venv/Scripts/activate"), name
+
+    assert pipeline["Conan Build - Windows VS2019"]["stage"] == \
+        pipeline["Conan Build - Windows"]["stage"]
+    deploy = pipeline["Conan Deploy - Windows VS2019"]
+    assert deploy["stage"] == "Deploy"
+    assert deploy["only"] == ["tags"]
+    assert deploy["needs"] == [{"job": "Conan Build - Windows VS2019", "artifacts": True}]
+
+
+def test_gitlab_vs2019_without_deploy_exports_nothing(tmp_path):
+    """[ci].deploy = false leaves the msvc 192 build with no export and no deploy job.
+
+    `artifacts: paths:` with nothing under it is not a harmless no-op -- GitLab
+    parses the key as null and rejects the file -- so the build job has to keep
+    a path of its own when the export goes away.
+    """
+    pipeline = _gitlab_jobs(tmp_path, windows_vs2019=True, deploy=False)
+
+    job = pipeline["Conan Build - Windows VS2019"]
+    assert job["artifacts"]["paths"] == ["test_artifacts/"]
+    assert all(not step.startswith("xmsconan_conan_deploy") for step in job["script"])
+    assert "Conan Deploy - Windows VS2019" not in pipeline
+
+
+def test_gitlab_vs2019_requires_windows(tmp_path):
+    """windows_vs2019 with [ci].windows = false is rejected, not silently honored.
+
+    The msvc 192 jobs are an addition to the Windows jobs; emitting them under
+    [ci].windows = false would resurrect the Windows half of a pipeline the
+    repository asked not to have.
+    """
+    toml_file = write_gitlab_toml(tmp_path, windows_vs2019=True, windows=False)
+
+    with pytest.raises(ValueError, match=r"windows_vs2019 = true with \[ci\].windows"):
+        generate_ci(str(toml_file), "1.0.0", str(tmp_path / "output"))
+
+
+def test_github_warns_that_vs2019_is_gitlab_only(tmp_path, caplog):
+    """A GitHub project opting into msvc 192 is told it gets nothing.
+
+    windows_vs2019 is a plain bool, so it cannot join the tri-state flags the
+    neighbouring warning covers -- and silence here would leave a repository
+    believing it publishes msvc 192 until a consumer failed to resolve it.
+    """
+    toml_file = write_github_toml(tmp_path, windows_vs2019=True)
+
+    with caplog.at_level(logging.WARNING):
+        generate_ci(str(toml_file), "1.0.0", str(tmp_path / "output"))
+
+    assert "windows_vs2019" in caplog.text
+    assert "GitLab-only" in caplog.text
+
+
 def test_gitlab_windows_build_stages_a_wheel(tmp_path):
     """The Windows build job asks build.py for a wheel and keeps it as an artifact.
 
diff --git a/tests/test_conan_deploy.py b/tests/test_conan_deploy.py
index ecb43be..1399153 100644
--- a/tests/test_conan_deploy.py
+++ b/tests/test_conan_deploy.py
@@ -1,6 +1,8 @@
 """Tests for ci_tools.conan_deploy."""
+import os
 import subprocess
 import sys
+import tempfile
 from unittest.mock import patch
 
 import pytest
@@ -79,6 +81,127 @@ def test_save_and_upload(mock_run):
     assert "upload" in calls[1][0][0]
 
 
+@patch("xmsconan.ci_tools.conan_deploy.subprocess.run")
+def test_save_with_a_package_query_resolves_a_package_list_first(mock_run):
+    """A query turns --save into `conan list` + `conan cache save --list`.
+
+    ``conan cache save`` accepts a pattern *or* a package list, and only the
+    list can be narrowed by a binary query -- so the pattern form cannot be
+    used here at all. The Conan cache on a CI runner is per machine, not per
+    job, so the pattern form would tarball a concurrent msvc 194 job's
+    binaries under the same reference.
+    """
+    conan_deploy(
+        "xmscore", "7.0.0", save="out.tar.gz", package_query="compiler.version=192",
+    )
+
+    assert mock_run.call_count == 2
+    list_command = mock_run.call_args_list[0][0][0]
+    assert list_command[:3] == ["conan", "list", "xmscore/7.0.0:*"]
+    assert list_command[-3:] == ["-p", "compiler.version=192", "--format=json"]
+
+    save_command = mock_run.call_args_list[1][0][0]
+    assert save_command[:3] == ["conan", "cache", "save"]
+    assert "--list" in save_command
+    assert save_command[-2:] == ["--file", "out.tar.gz"]
+    # The unrestricted pattern must not appear: it is what the query exists to
+    # avoid, and passing both is a Conan error anyway.
+    assert "xmscore/7.0.0:*" not in save_command
+
+
+@patch("xmsconan.ci_tools.conan_deploy.subprocess.run")
+def test_save_with_a_package_query_removes_the_list_file(mock_run):
+    """The resolved package list is a temp file and does not outlive the save.
+
+    It is written outside the artifact tree and deleted either way, so a
+    pipeline cannot pick up a stale list from a previous job -- which would
+    publish that job's package ids.
+    """
+    written = []
+
+    def record(command, **kwargs):
+        if command[1] == "cache":
+            written.append(command[command.index("--list") + 1])
+
+    mock_run.side_effect = record
+    conan_deploy(
+        "xmscore", "7.0.0", save="out.tar.gz", package_query="compiler.version=192",
+    )
+
+    assert len(written) == 1
+    assert not os.path.exists(written[0])
+
+
+@patch("xmsconan.ci_tools.conan_deploy.subprocess.run")
+def test_save_with_a_package_query_removes_the_list_file_on_failure(mock_run):
+    """A failed `conan cache save` still cleans up, and still raises."""
+    seen = []
+
+    def record(command, **kwargs):
+        if command[1] == "cache":
+            seen.append(command[command.index("--list") + 1])
+            raise subprocess.CalledProcessError(1, "conan")
+
+    mock_run.side_effect = record
+    with pytest.raises(subprocess.CalledProcessError):
+        conan_deploy(
+            "xmscore", "7.0.0", save="out.tar.gz", package_query="compiler.version=192",
+        )
+
+    assert len(seen) == 1
+    assert not os.path.exists(seen[0])
+
+
+@patch("xmsconan.ci_tools.conan_deploy.subprocess.run")
+def test_package_list_removed_when_conan_list_fails(mock_run):
+    """A failed resolve leaves no file behind for a later step to trust.
+
+    An empty or partial list is worse than none: `conan cache save --list`
+    would accept it and produce a tarball missing binaries, and the deploy that
+    follows would publish that as a complete release.
+    """
+    tempfiles = []
+    real_mkstemp = tempfile.mkstemp
+
+    def spy(*args, **kwargs):
+        handle, path = real_mkstemp(*args, **kwargs)
+        tempfiles.append(path)
+        return handle, path
+
+    mock_run.side_effect = subprocess.CalledProcessError(1, "conan")
+    with patch("xmsconan.ci_tools.conan_deploy.tempfile.mkstemp", side_effect=spy):
+        with pytest.raises(subprocess.CalledProcessError):
+            conan_deploy(
+                "xmscore", "7.0.0", save="out.tar.gz",
+                package_query="compiler.version=192",
+            )
+
+    assert len(tempfiles) == 1
+    assert not os.path.exists(tempfiles[0])
+
+
+@patch("xmsconan.ci_tools.conan_deploy.subprocess.run")
+def test_upload_honors_the_remote_and_the_package_query(mock_run):
+    """--upload sends only matching binaries, and to the named remote.
+
+    `conan upload` matches by reference, so the query is what keeps msvc 194
+    binaries sitting in a shared runner's cache from being published to the
+    VS2019 remote -- silently, and with exit 0.
+    """
+    conan_deploy(
+        "xmscore", "7.0.0", upload=True,
+        remote="aquaveo-vs2019", package_query="compiler.version=192",
+    )
+
+    mock_run.assert_called_once_with(
+        [
+            "conan", "upload", "xmscore/7.0.0", "-r", "aquaveo-vs2019", "--confirm",
+            "-p", "compiler.version=192",
+        ],
+        check=True,
+    )
+
+
 @patch("xmsconan.ci_tools.conan_deploy.subprocess.run")
 def test_no_action_does_nothing(mock_run):
     """No flags → no subprocess calls."""
@@ -103,6 +226,7 @@ def test_main_passes_flags_through(mock_deploy, monkeypatch):
     monkeypatch.setattr(sys, "argv", [
         "xmsconan_conan_deploy", "xmscore", "7.0.0",
         "--save", "out.tar.gz", "--restore", "in.tar.gz", "--upload",
+        "--remote", "aquaveo-vs2019", "--package-query", "compiler.version=192",
     ])
 
     main()
@@ -113,6 +237,8 @@ def test_main_passes_flags_through(mock_deploy, monkeypatch):
         save="out.tar.gz",
         restore="in.tar.gz",
         upload=True,
+        remote="aquaveo-vs2019",
+        package_query="compiler.version=192",
     )
 
 
diff --git a/tests/test_conan_setup.py b/tests/test_conan_setup.py
index ecff634..c69e78b 100644
--- a/tests/test_conan_setup.py
+++ b/tests/test_conan_setup.py
@@ -5,7 +5,9 @@
 
 import pytest
 
-from xmsconan.ci_tools.conan_setup import conan_setup, DEFAULT_REMOTE_URL, main
+from xmsconan.ci_tools.conan_setup import (
+    conan_setup, DEFAULT_REMOTE_NAME, DEFAULT_REMOTE_URL, main,
+)
 from xmsconan.ci_tools.credentials import CredentialsError
 from .utils import patch_env
 
@@ -246,6 +248,7 @@ def test_main_passes_flags_through(mock_setup, monkeypatch, tmp_path):
         "xmsconan_conan_setup", "--remote-url", "https://example.com/conan",
         "--login", "--remove-conancenter", "--username", "u",
         "--password-file", str(password_file),
+        "--remote-name", "aquaveo-vs2019", "--append",
     ])
 
     main()
@@ -256,9 +259,30 @@ def test_main_passes_flags_through(mock_setup, monkeypatch, tmp_path):
         remove_conancenter=True,
         username="u",
         password="p",
+        remote_name="aquaveo-vs2019",
+        # --append maps to index=None; the default is index=0, i.e. first.
+        index=None,
     )
 
 
+@patch("xmsconan.ci_tools.conan_setup.conan_setup")
+def test_main_adds_the_remote_first_by_default(mock_setup, monkeypatch):
+    """Without --append the remote goes to index 0, as the CI remote always has.
+
+    The pair matters more than either value: --append exists so a
+    special-purpose remote does not become the first stop for every conan
+    install on a shared machine, and that is only true if omitting it keeps the
+    old behavior.
+    """
+    monkeypatch.setattr(sys, "argv", ["xmsconan_conan_setup"])
+
+    main()
+
+    _, kwargs = mock_setup.call_args
+    assert kwargs["index"] == 0
+    assert kwargs["remote_name"] == DEFAULT_REMOTE_NAME
+
+
 @patch("xmsconan.ci_tools.conan_setup.conan_setup")
 def test_main_has_no_password_flag(mock_setup, monkeypatch, capsys):
     """There is no --password: the secret never goes on this process's argv.
diff --git a/xmsconan/build_toml.py b/xmsconan/build_toml.py
index f5b33ad..00e4e88 100644
--- a/xmsconan/build_toml.py
+++ b/xmsconan/build_toml.py
@@ -65,6 +65,20 @@ class CiTable:
 
     windows: Optional[bool] = None
     linux: Optional[bool] = None
+    #: Also build the ``windows_vs2019`` (msvc 192) matrix in GitLab CI and
+    #: publish it to the ``aquaveo-vs2019`` remote.
+    #:
+    #: Opt-in, and a plain ``bool`` rather than one of the tri-state fields
+    #: above: unset means "no", not "decide later". It roughly doubles the
+    #: Windows half of a pipeline, and only the libraries the VS2019-era
+    #: desktop products consume need msvc 192 binaries at all -- so a
+    #: repository that has never asked for them should not start paying for
+    #: them because its runner acquired a second toolchain.
+    #:
+    #: Requires ``windows`` to be enabled: it fans out over the same
+    #: ``python_versions`` and is emitted beside the msvc 194 jobs, not
+    #: instead of them. See ``docs/USAGE.md`` §10.2.
+    windows_vs2019: bool = False
     linux_arm: bool = False
     deploy: bool = True
     coverage: bool = False
@@ -196,6 +210,7 @@ def _validate_top_level_keys(toml_data, toml_path):
 #: that the two name the same keys.
 _CI_KEY_TYPES = {
     "windows": bool,
+    "windows_vs2019": bool,
     "linux": bool,
     "linux_arm": bool,
     "deploy": bool,
diff --git a/xmsconan/build_tools/vs2019_build.py b/xmsconan/build_tools/vs2019_build.py
index 6a18b48..1c860a5 100644
--- a/xmsconan/build_tools/vs2019_build.py
+++ b/xmsconan/build_tools/vs2019_build.py
@@ -100,7 +100,8 @@
 from xmsconan.ci_tools.conan_setup import conan_setup
 from xmsconan.ci_tools.credentials import load_conan_credentials, read_password_file
 from xmsconan.constants import (
-    MSVC_VS2019_VERSION, version_sort_key, VS2019_REMOTE_NAME, VS2019_REMOTE_URL,
+    MSVC_VS2019_VERSION, version_sort_key, VS2019_PLATFORM_KEY, VS2019_REMOTE_NAME,
+    VS2019_REMOTE_URL,
 )
 from xmsconan.package_tools.packager import XmsConanPackager
 
@@ -108,8 +109,11 @@
 #: CLI, the environment, nor ``~/.xmsconan.toml`` names one.
 DEFAULT_REMOTE_USERNAME = "aquaveo"
 
-#: Key into :data:`xmsconan.package_tools.packager.configurations`.
-PLATFORM_KEY = "windows_vs2019"
+#: Key into :data:`xmsconan.package_tools.packager.configurations`.  Aliases
+#: :data:`~xmsconan.constants.VS2019_PLATFORM_KEY`, which the GitLab generator
+#: also reads, so the workstation build and the generated pipeline cannot end
+#: up naming different matrices.
+PLATFORM_KEY = VS2019_PLATFORM_KEY
 
 #: Conan client requirement, matching the pin used by the CI workflows.
 CONAN_PIN = "~=2.31.0"
diff --git a/xmsconan/ci_tools/conan_deploy.py b/xmsconan/ci_tools/conan_deploy.py
index ce2e130..4c8d215 100644
--- a/xmsconan/ci_tools/conan_deploy.py
+++ b/xmsconan/ci_tools/conan_deploy.py
@@ -5,15 +5,54 @@
     xmsconan_conan_deploy <library> <version> --save FILE
     xmsconan_conan_deploy <library> <version> --restore FILE [--upload]
     xmsconan_conan_deploy <library> <version> --upload
+    xmsconan_conan_deploy <library> <version> --restore FILE --upload \
+        --remote aquaveo-vs2019 --package-query compiler.version=192
 """
 import argparse
+import os
 import subprocess
 import sys
+import tempfile
 
 from xmsconan.constants import DEFAULT_REMOTE_NAME
 
 
-def conan_deploy(library, version, save=None, restore=None, upload=False):
+def _package_list(ref, package_query):
+    """Write a Conan package list of ``ref``'s binaries matching ``package_query``.
+
+    ``conan cache save`` takes either a pattern or a package list, and only the
+    list can be narrowed by a binary query -- so a query is resolved to a list
+    first, with ``conan list``, and the list is what gets saved.
+
+    Args:
+        ref: ``<library>/<version>`` reference.
+        package_query: Conan binary query, e.g. ``"compiler.version=192"``.
+
+    Returns:
+        Path to the package list JSON. The caller owns it and must delete it.
+
+    Raises:
+        subprocess.CalledProcessError: ``conan list`` failed. The file is
+            removed first, so a failed resolve leaves nothing behind for a
+            later step to mistake for a complete list.
+    """
+    handle, path = tempfile.mkstemp(prefix="xmsconan-pkglist-", suffix=".json")
+    os.close(handle)
+    # `-c` is the default when no `--remote` is given, but it is spelled out:
+    # this list decides what gets published, and "the local cache" must not be
+    # something a reader has to know a default to be sure of.
+    command = ["conan", "list", f"{ref}:*", "-c", "-p", package_query, "--format=json"]
+    try:
+        with open(path, "w", encoding="utf-8") as output:
+            subprocess.run(command, check=True, stdout=output)
+    except subprocess.CalledProcessError:
+        os.unlink(path)
+        raise
+    return path
+
+
+def conan_deploy(library, version, save=None, restore=None, upload=False,
+                 remote=DEFAULT_REMOTE_NAME, package_query=None):
     """Perform Conan cache save, restore, or upload operations.
 
     Args:
@@ -21,20 +60,42 @@ def conan_deploy(library, version, save=None, restore=None, upload=False):
         version: Package version string.
         save: Path to write the cache tarball to (``conan cache save``).
         restore: Path to read a cache tarball from (``conan cache restore``).
-        upload: If ``True``, upload the package to the
-            :data:`~xmsconan.constants.DEFAULT_REMOTE_NAME` remote.
+        upload: If ``True``, upload the package to ``remote``.
+        remote: Conan remote to upload to. Defaults to
+            :data:`~xmsconan.constants.DEFAULT_REMOTE_NAME`; the msvc 192 jobs
+            pass :data:`~xmsconan.constants.VS2019_REMOTE_NAME` so those
+            binaries stay out of the CI remote.
+        package_query: Conan binary query restricting both ``--save`` and
+            ``--upload`` to matching binaries, e.g. ``"compiler.version=192"``.
+
+            Not optional decoration for a toolchain-specific remote. Both
+            ``conan cache save <ref>:*`` and ``conan upload <ref>`` match by
+            *reference*, and the Conan cache on a CI runner is per machine, not
+            per job -- so a msvc 192 job sharing a Windows VM with a msvc 194
+            job would tarball and publish the other one's binaries to the
+            VS2019 remote, and exit 0 having done it.
     """
     ref = f"{library}/{version}"
 
     if save:
-        # `conan cache save` treats a bare `pkg/version` as a recipe-only pattern, so
-        # the tarball would carry the recipe and none of the binaries built alongside
-        # it. `:*` selects every package id under the reference. Without it the deploy
-        # job restores a recipe with no packages and silently uploads nothing.
-        subprocess.run(
-            ["conan", "cache", "save", "--file", save, f"{ref}:*"],
-            check=True,
-        )
+        if package_query:
+            list_file = _package_list(ref, package_query)
+            try:
+                subprocess.run(
+                    ["conan", "cache", "save", "--list", list_file, "--file", save],
+                    check=True,
+                )
+            finally:
+                os.unlink(list_file)
+        else:
+            # `conan cache save` treats a bare `pkg/version` as a recipe-only pattern, so
+            # the tarball would carry the recipe and none of the binaries built alongside
+            # it. `:*` selects every package id under the reference. Without it the deploy
+            # job restores a recipe with no packages and silently uploads nothing.
+            subprocess.run(
+                ["conan", "cache", "save", "--file", save, f"{ref}:*"],
+                check=True,
+            )
 
     if restore:
         subprocess.run(
@@ -43,10 +104,10 @@ def conan_deploy(library, version, save=None, restore=None, upload=False):
         )
 
     if upload:
-        subprocess.run(
-            ["conan", "upload", ref, "-r", DEFAULT_REMOTE_NAME, "--confirm"],
-            check=True,
-        )
+        command = ["conan", "upload", ref, "-r", remote, "--confirm"]
+        if package_query:
+            command += ["-p", package_query]
+        subprocess.run(command, check=True)
 
 
 def main():
@@ -69,7 +130,21 @@ def main():
     parser.add_argument(
         "--upload",
         action="store_true",
-        help=f"Upload the package to the {DEFAULT_REMOTE_NAME} remote.",
+        help=f"Upload the package to the --remote (default: {DEFAULT_REMOTE_NAME}).",
+    )
+    parser.add_argument(
+        "--remote",
+        default=DEFAULT_REMOTE_NAME,
+        help=f"Conan remote to upload to (default: {DEFAULT_REMOTE_NAME}).",
+    )
+    parser.add_argument(
+        "--package-query",
+        default=None,
+        help="Restrict --save and --upload to binaries matching this Conan "
+             "query, e.g. 'compiler.version=192'. Required when publishing to "
+             "a toolchain-specific remote from a shared runner: both commands "
+             "otherwise match by reference and would carry another job's "
+             "binaries.",
     )
     args = parser.parse_args()
 
@@ -83,6 +158,8 @@ def main():
             save=args.save,
             restore=args.restore,
             upload=args.upload,
+            remote=args.remote,
+            package_query=args.package_query,
         )
     except subprocess.CalledProcessError as exc:
         sys.exit(exc.returncode)
diff --git a/xmsconan/ci_tools/conan_setup.py b/xmsconan/ci_tools/conan_setup.py
index 029a97f..7844662 100644
--- a/xmsconan/ci_tools/conan_setup.py
+++ b/xmsconan/ci_tools/conan_setup.py
@@ -4,6 +4,7 @@
 
     xmsconan_conan_setup [--remote-url URL] [--login] [--remove-conancenter]
     xmsconan_conan_setup --login --username USER --password-file PATH
+    xmsconan_conan_setup --remote-name aquaveo-vs2019         --remote-url https://.../aquaveo-vs2019 --append
 """
 import argparse
 import os
@@ -153,10 +154,25 @@ def main():
         default=None,
         help="Conan remote URL (default: Aquaveo stable).",
     )
+    parser.add_argument(
+        "--remote-name",
+        default=DEFAULT_REMOTE_NAME,
+        help=f"Conan remote name to add (default: {DEFAULT_REMOTE_NAME}). Pair "
+             f"it with --remote-url; a name and URL that disagree configure a "
+             f"remote pointing somewhere nobody expects.",
+    )
+    parser.add_argument(
+        "--append",
+        action="store_true",
+        help="Add the remote after the ones already configured instead of "
+             "first. Use it for a special-purpose remote: inserting a second "
+             "Aquaveo remote at index 0 makes it the first stop for every "
+             "conan install on the machine, including unrelated ones.",
+    )
     parser.add_argument(
         "--login",
         action="store_true",
-        help="Run 'conan remote login aquaveo' after adding the remote.",
+        help="Run 'conan remote login <remote-name>' after adding the remote.",
     )
     parser.add_argument(
         "--remove-conancenter",
@@ -201,6 +217,8 @@ def main():
             remove_conancenter=args.remove_conancenter,
             username=args.username,
             password=password,
+            remote_name=args.remote_name,
+            index=None if args.append else 0,
         )
     except CredentialsError as exc:
         # load_conan_credentials() raises this for a ~/.xmsconan.toml that does
diff --git a/xmsconan/constants.py b/xmsconan/constants.py
index fb357ac..20694f3 100644
--- a/xmsconan/constants.py
+++ b/xmsconan/constants.py
@@ -67,11 +67,21 @@ def version_sort_key(version) -> tuple:
 VS2019_REMOTE_URL = f"{ARTIFACTORY_BASE_URL}/aquaveo-vs2019"
 
 #: Conan ``compiler.version`` value identifying the Visual Studio 2019
-#: toolset.  GitHub retired the ``windows-2019`` runner image, so packages
-#: with this compiler version are built by hand and published to
-#: :data:`VS2019_REMOTE_NAME`.
+#: toolset.  Packages with this compiler version are published to
+#: :data:`VS2019_REMOTE_NAME` rather than to :data:`DEFAULT_REMOTE_NAME`.
 MSVC_VS2019_VERSION = "192"
 
+#: Key into :data:`xmsconan.package_tools.packager.configurations` selecting
+#: the msvc 192 matrix.
+#:
+#: Named here rather than in one of its callers because there are now two:
+#: :mod:`xmsconan.build_tools.vs2019_build`, which drives the workstation
+#: build, and the GitLab generator, which writes the key into the generated
+#: pipeline's ``build.py --platform`` invocation.  A literal in each would be
+#: free to drift, and the failure mode is quiet -- an unknown key raises, but
+#: a *stale* one would build the wrong matrix and publish it as msvc 192.
+VS2019_PLATFORM_KEY = "windows_vs2019"
+
 
 #: Build-folder suffix for each CMake generator.  CMake refuses to reuse a
 #: binary directory configured by a different generator, so a Ninja build and a
diff --git a/xmsconan/generator_tools/build_file_generator.py b/xmsconan/generator_tools/build_file_generator.py
index 79a49cb..7d77747 100644
--- a/xmsconan/generator_tools/build_file_generator.py
+++ b/xmsconan/generator_tools/build_file_generator.py
@@ -14,7 +14,10 @@
 
 # 3. Aquaveo modules
 from xmsconan.build_toml import BuildToml, read_build_toml, XmsDependency
-from xmsconan.constants import PYTHON_BINDING_TYPES, TESTING_FRAMEWORKS
+from xmsconan.constants import (
+    MSVC_VS2019_VERSION, PYTHON_BINDING_TYPES, TESTING_FRAMEWORKS, VS2019_PLATFORM_KEY,
+    VS2019_REMOTE_NAME,
+)
 from xmsconan.generator_tools.build_filter import load_build_filter
 from xmsconan.package_tools.packager import XmsConanPackager
 
@@ -173,6 +176,17 @@ def _render_context(config: BuildToml, version: str) -> dict:
         config.extra_dependency_cmake_names,
         config.xms_dependencies,
     )
+    # Rendered in rather than imported by the generated build.py. build.py
+    # already calls into the installed xmsconan for the packager itself, but a
+    # *new name* in xmsconan.constants would make a freshly generated build.py
+    # unrunnable against an older installed client -- an ImportError on line 8,
+    # before argparse, with nothing said about versions. These are three short
+    # literals; carrying them keeps the generated file runnable against
+    # whatever xmsconan is on the machine, and it is regenerated by
+    # `xmsconan_gen` on every CI run anyway, so it cannot go stale in CI.
+    context["vs2019_platform_key"] = VS2019_PLATFORM_KEY
+    context["vs2019_remote_name"] = VS2019_REMOTE_NAME
+    context["vs2019_msvc_version"] = MSVC_VS2019_VERSION
     return context
 
 
diff --git a/xmsconan/generator_tools/ci_file_generator.py b/xmsconan/generator_tools/ci_file_generator.py
index 24371c2..83986a4 100644
--- a/xmsconan/generator_tools/ci_file_generator.py
+++ b/xmsconan/generator_tools/ci_file_generator.py
@@ -11,7 +11,14 @@
 # 3. Aquaveo modules
 from xmsconan.build_toml import BuildToml, CiTable, CoverageTable, read_build_toml
 from xmsconan.ci_options import repairs_windows_wheel
-from xmsconan.constants import SUPPORTED_PYTHON_VERSIONS, version_sort_key
+from xmsconan.constants import (
+    MSVC_VS2019_VERSION,
+    SUPPORTED_PYTHON_VERSIONS,
+    version_sort_key,
+    VS2019_PLATFORM_KEY,
+    VS2019_REMOTE_NAME,
+    VS2019_REMOTE_URL,
+)
 from xmsconan.generator_tools.build_filter import (
     ci_build_jobs,
     ci_filter_effects,
@@ -348,6 +355,18 @@ def generate_ci(
                 "Coverage builds with --coverage under gcc; the generated "
                 "CMakeLists rejects MSVC when XMS_COVERAGE is set."
             )
+        # The msvc 192 jobs are emitted beside the msvc 194 ones and reuse
+        # their shape -- the same runner, the same ABI fan-out, the same
+        # export/restore split. With Windows switched off there is nothing to
+        # emit them beside, and silently honoring the opt-in would resurrect
+        # the Windows half of a pipeline the repository asked not to have.
+        if config.ci.windows_vs2019 and not config.ci.windows_enabled:
+            raise ValueError(
+                "build.toml sets [ci].windows_vs2019 = true with [ci].windows = "
+                "false. The VS2019 (msvc 192) jobs are an addition to the Windows "
+                "jobs, not a replacement for them. Enable [ci].windows, or drop "
+                "windows_vs2019."
+            )
     if ci_type == "github":
         # Every wheel step in the GitHub workflow is gated on
         # `matrix.build_type == 'Release'` -- including the build step's
@@ -381,6 +400,17 @@ def generate_ci(
                 "these are" if len(ignored) > 1 else "this is",
                 "them" if len(ignored) > 1 else "it",
             )
+        # Same reasoning, separate check: windows_vs2019 is a plain bool, so
+        # "explicitly set" and "true" are the same thing and it cannot join the
+        # tri-state list above. Worth its own warning rather than silence --
+        # a repository that opted into msvc 192 and got no msvc 192 job would
+        # otherwise find out from a consumer that cannot resolve the package.
+        if config.ci.windows_vs2019:
+            LOGGER.warning(
+                "build.toml sets [ci].windows_vs2019, but the VS2019 (msvc 192) "
+                "jobs are GitLab-only; the generated GitHub workflow emits none "
+                "and publishes nothing to the aquaveo-vs2019 remote."
+            )
 
     ci_python_versions = list(config.ci.python_versions)
     ci_mac_python_versions = _platform_python_versions(config.ci, "mac", ci_python_versions)
@@ -458,6 +488,16 @@ def generate_ci(
         "version": version,
         "python_namespaced_dir": config.python_namespaced_dir,
         "ci_windows": config.ci.windows_enabled,
+        # Opt-in second Windows toolchain. Not derived from windows_enabled:
+        # the msvc 192 matrix resolves a different third-party stack (the
+        # recipe forks boost/zlib on compiler.version) and publishes to a
+        # different remote, so it is a deliberate per-repository choice rather
+        # than something every Windows repository should inherit.
+        "ci_windows_vs2019": config.ci.windows_vs2019,
+        "vs2019_remote_name": VS2019_REMOTE_NAME,
+        "vs2019_remote_url": VS2019_REMOTE_URL,
+        "vs2019_platform_key": VS2019_PLATFORM_KEY,
+        "vs2019_msvc_version": MSVC_VS2019_VERSION,
         # Windows-scoped on purpose: a manylinux wheel has to be repaired to be
         # installable, so there is no equivalent switch for Linux or macOS. The
         # default follows ci_type -- see repairs_windows_wheel.
diff --git a/xmsconan/generator_tools/ci_templates/gitlab-ci.yml.jinja b/xmsconan/generator_tools/ci_templates/gitlab-ci.yml.jinja
index 32c1228..0654078 100644
--- a/xmsconan/generator_tools/ci_templates/gitlab-ci.yml.jinja
+++ b/xmsconan/generator_tools/ci_templates/gitlab-ci.yml.jinja
@@ -451,6 +451,79 @@ Conan Build:
   tags:
     - WinVM
 
+<% if ci_windows_vs2019 %>
+<# The second Windows toolchain: msvc << vs2019_msvc_version >> (Visual Studio
+   2019), from [ci].windows_vs2019. It was built by hand on a developer
+   workstation for as long as no CI runner had VS2019 on it; GLR-UV does, so
+   the same matrix is produced here instead -- reproducibly, on every pipeline,
+   from the same `build.py` the msvc 194 job runs.
+
+   Four things separate it from that job, and all four are load-bearing:
+
+   * `--platform << vs2019_platform_key >>` selects the msvc 192 matrix. The
+     recipe forks its third-party stack on compiler.version (boost 1.74.0.3 +
+     zlib 1.2.11 rather than 1.86.0 + 1.3.1), and `build.py` drops the boost
+     option defaults for this platform because the legacy recipe does not
+     declare them -- Conan fails a build outright when a profile sets an
+     option no recipe in the graph defines.
+   * The `<< vs2019_remote_name >>` remote is added, and appended rather than
+     inserted first: it must not become the first stop for every `conan
+     install` on a shared runner. It is where the legacy dependencies are
+     resolved from as well as where the results go.
+   * Every deploy step carries `--package-query compiler.version=<<
+     vs2019_msvc_version >>`. The Conan cache on a runner is per machine, not
+     per job, so without it this job's `conan cache save` would tarball the
+     msvc 194 job's binaries and publish them to the VS2019 remote, exit 0,
+     and leave two toolchains mixed on a remote whose whole purpose is to keep
+     them apart.
+   * No `--wheel-dir`. A wheel's tags (`cp310-cp310-win_amd64`) say nothing
+     about which MSVC built it, so an msvc 192 wheel and an msvc 194 wheel are
+     the same devpi filename -- publishing both would have them overwrite each
+     other by upload order. The VS2019 wheels the desktop products consume are
+     still produced deliberately, by hand (USAGE section 16.8).
+
+   `--build-missing` for the same reason the workstation driver passes it: the
+   legacy dependency graph is not fully prebuilt for msvc 192. #>
+"Conan Build - Windows VS2019":
+<% if ci_split_tests %>
+  stage: Build
+<% else %>
+  stage: Test
+<% endif %>
+  image: GLR-UV
+  parallel:
+    matrix:
+<% for v in ci_python_versions %>
+      - PYTHON_TARGET_VERSION: '<< v >>'
+<% endfor %>
+  artifacts:
+    expire_in: '1d'
+    when: always
+    paths:
+<% if ci_deploy %>
+      - .export
+<% endif %>
+      - test_artifacts/
+  script:
+    - export PACKAGE_VERSION=${CI_COMMIT_TAG:-0.0.0}
+    - export CTEST_PARALLEL_LEVEL=${CTEST_PARALLEL_LEVEL:-8}
+    - uv --version
+    - uv venv --python ${PYTHON_TARGET_VERSION} .venv
+    - source .venv/Scripts/activate
+    - python --version
+    - uv pip install "conan~=2.31.0" --index-url https://public.aquapi.aquaveo.com/aquaveo/dev/+simple
+    - uv pip install --upgrade "xmsconan>=<< xmsconan_version >>" --index-url https://public.aquapi.aquaveo.com/aquaveo/dev/+simple
+    - xmsconan_conan_setup
+    - xmsconan_conan_setup --remote-name << vs2019_remote_name >> --remote-url << vs2019_remote_url >> --append
+    - xmsconan_gen --version ${PACKAGE_VERSION} build.toml
+    - python build.py --version ${PACKAGE_VERSION} --platform << vs2019_platform_key >> --build-missing --artifacts-dir test_artifacts
+<% if ci_deploy %>
+    - xmsconan_conan_deploy << library_name >> ${PACKAGE_VERSION} --save .export/<< library_name >>-windows-vs2019-py${PYTHON_TARGET_VERSION}-${PACKAGE_VERSION}.tar.gz --package-query compiler.version=<< vs2019_msvc_version >>
+<% endif %>
+  tags:
+    - WinVM
+
+<% endif %>
 <% endif %>
 Lint:
   stage: Test
@@ -662,6 +735,48 @@ Repair Wheel:
     - tags
   tags:
     - WinVM
+
+<% if ci_windows_vs2019 %>
+<# Publishes what "Conan Build - Windows VS2019" exported, to
+   << vs2019_remote_name >> rather than to the CI remote. The package query is
+   repeated here rather than trusted from the save step: this is the command
+   that actually reaches a shared remote, and a tarball restored into a cache
+   that already holds msvc 194 binaries of the same reference would otherwise
+   publish those too.
+
+   No wheel deploy counterpart, and no `conan_packages/` snapshot -- see the
+   header on the build job for the wheel reasoning; the snapshot exists to
+   debug the msvc 194 pair and a second copy of it would only double the
+   artifact. #>
+"Conan Deploy - Windows VS2019":
+  stage: Deploy
+  image: GLR-UV
+  parallel:
+    matrix:
+<% for v in ci_python_versions %>
+      - PYTHON_TARGET_VERSION: '<< v >>'
+<% endfor %>
+  # The whole build job, not one parallel instance, for the reason given on
+  # "Conan Deploy - Windows" above: GitLab does not expand variables inside
+  # needs:parallel:matrix.
+  needs:
+    - job: "Conan Build - Windows VS2019"
+      artifacts: true
+  script:
+    - export PACKAGE_VERSION=${CI_COMMIT_TAG:-0.0.0}
+    - uv --version
+    - uv venv --python ${PYTHON_TARGET_VERSION} .venv
+    - source .venv/Scripts/activate
+    - uv pip install "conan~=2.31.0" --index-url https://public.aquapi.aquaveo.com/aquaveo/dev/+simple
+    - uv pip install --upgrade "xmsconan>=<< xmsconan_version >>" --index-url https://public.aquapi.aquaveo.com/aquaveo/dev/+simple
+    - xmsconan_conan_setup
+    - xmsconan_conan_setup --remote-name << vs2019_remote_name >> --remote-url << vs2019_remote_url >> --append
+    - xmsconan_conan_deploy << library_name >> ${PACKAGE_VERSION} --restore .export/<< library_name >>-windows-vs2019-py${PYTHON_TARGET_VERSION}-${PACKAGE_VERSION}.tar.gz --upload --remote << vs2019_remote_name >> --package-query compiler.version=<< vs2019_msvc_version >>
+  only:
+    - tags
+  tags:
+    - WinVM
+<% endif %>
 <% endif %>
 <% endif %>
 
diff --git a/xmsconan/generator_tools/templates/build.py.jinja b/xmsconan/generator_tools/templates/build.py.jinja
index beffca1..7bea7ba 100644
--- a/xmsconan/generator_tools/templates/build.py.jinja
+++ b/xmsconan/generator_tools/templates/build.py.jinja
@@ -14,6 +14,15 @@ import conanfile
 # --ignore-build-filter to build a configuration it excludes.
 BUILD_FILTER = {{ build_filter }}
 
+# The msvc 192 identity, rendered in rather than imported from
+# xmsconan.constants: a new name there would make a freshly generated build.py
+# fail at import against an older installed client, before argparse and with
+# nothing said about versions. `xmsconan_gen` rewrites this file on every CI
+# run, so the literals cannot drift from the tools that read them.
+VS2019_PLATFORM = "{{ vs2019_platform_key }}"
+VS2019_REMOTE = "{{ vs2019_remote_name }}"
+VS2019_MSVC_VERSION = "{{ vs2019_msvc_version }}"
+
 # arg parse for skip build and skip upload
 parser = argparse.ArgumentParser()
 parser.add_argument("--skip-build", help="Skip the build step", action="store_true")
@@ -31,6 +40,9 @@ parser.add_argument("--filter", help="Filter dictionary in JSON format")
 parser.add_argument("--ignore-build-filter", action="store_true",
                     help="Ignore the [filter] table from build.toml")
 parser.add_argument("--build-missing", help="Build missing dependencies from source", action="store_true")
+parser.add_argument("--platform", default=None,
+                    help=f"Matrix to build ('windows', '{VS2019_PLATFORM}', 'linux', "
+                         "'darwin'). Default: detect from the running machine.")
 parser.add_argument("--python-only", help="Only build the Python (pybind) configuration", action="store_true")
 parser.add_argument("--wheel-dir", help="Extract pre-built wheel from pybind package to this directory")
 parser.add_argument("--skip-dependency-libs", action="store_true",
@@ -47,6 +59,17 @@ if __name__ == "__main__":
         test_shards = max((os.cpu_count() or 4) // 2, 2)
     else:
         test_shards = int(args.test_shards)
+    # The msvc 192 matrix resolves the legacy third-party stack (the recipe
+    # forks boost/zlib on compiler.version), and the boost defaults the
+    # packager would otherwise inject name conan-center boost 1.86 options
+    # that boost/1.74.0.3 does not declare -- Conan fails a build outright
+    # when a profile sets an option no recipe in the graph defines. The
+    # packager deliberately does not imply this from the platform key, so the
+    # caller has to; deriving it from --platform here rather than exposing a
+    # second flag means a pipeline cannot get one right and the other wrong.
+    apply_boost_defaults = args.platform != VS2019_PLATFORM
+    if not apply_boost_defaults:
+        print(f"Building the {args.platform} matrix: boost defaults not applied.")
     builder = packager.XmsConanPackager(
         conanfile.LIBRARY_NAME,
         conanfile.__file__,
@@ -55,8 +78,9 @@ if __name__ == "__main__":
         test_shards=test_shards,
         profile_options=conanfile.CONAN_PROFILE_OPTIONS,
         matrix=conanfile.CONAN_MATRIX,
+        apply_boost_defaults=apply_boost_defaults,
     )
-    builder.generate_configurations()
+    builder.generate_configurations(system_platform=args.platform)
     if BUILD_FILTER and not args.ignore_build_filter:
         print(f"Applying build.toml [filter]: {BUILD_FILTER}")
         builder.filter_configurations(BUILD_FILTER)
@@ -113,6 +137,18 @@ if __name__ == "__main__":
             print("error: --upload needs a concrete version. Pass --version, or set "
                   "XMS_VERSION (every generated CI leg does).")
             exit(1)
-        if builder.upload(version=args.version) != 0:
+        # msvc 192 binaries belong on their own remote, and `conan upload`
+        # matches by reference only -- so without the query an --upload from a
+        # machine that has also built msvc 194 would publish those to the
+        # VS2019 remote and exit 0. Both halves are derived from --platform for
+        # the same reason apply_boost_defaults is: one flag, no way to set the
+        # matrix and the destination to disagree.
+        upload_kwargs = {}
+        if args.platform == VS2019_PLATFORM:
+            upload_kwargs = {
+                "remote": VS2019_REMOTE,
+                "package_query": f"compiler.version={VS2019_MSVC_VERSION}",
+            }
+        if builder.upload(version=args.version, **upload_kwargs) != 0:
             print("errors when uploading... exiting...")
             exit(1)

From 8779d95f83acbac387e4dd9f43d76b27404cbdd3 Mon Sep 17 00:00:00 2001
From: Gage Larsen <glarsen@aquaveo.com>
Date: Tue, 1 Sep 2026 15:38:33 -0600
Subject: [PATCH 3/3] Address review: close the mirror leak, and the docs that
 outran it

M2 was the real defect. The msvc 192 publishes were queried; the msvc 194
ones were not, and the hazard is symmetric. A runner's Conan cache is per
machine, and `conan cache save <ref>:*` / `conan upload <ref>` match by
reference, so once both toolchains build the same reference on the same
fleet, the unqueried side ships the other's binaries -- and that direction
is the worse one, because it puts msvc 192 binaries on the production
`aquaveo` remote at exit 0. Both Windows jobs now carry
`--package-query compiler.version=...`, unconditionally rather than only
under the opt-in: a guard present in just the configuration that needs it
is one refactor from being dropped from the one that does.

Both values are read from the packager's `configurations` rather than
written into the template. A stale literal would not fail loudly -- a
query naming a version the matrix no longer builds matches nothing, and
the job goes green having published no binaries at all.

M1: this PR made four in-tree passages false and only fixed one of them.
README's VS2019 section, `vs2019_build`'s module docstring, the
`windows_vs2019` comment in `packager.configurations`, and
`VS2019_REMOTE_NAME`'s in constants all still said msvc 192 cannot be
built in CI. README also gains the `[ci].windows_vs2019` row.

Minor items:

* `_package_list` is a context manager. The ownership contract lived in a
  docstring, and the cleanup was on `CalledProcessError` alone -- so a
  `conan` missing from PATH leaked the file the docstring promised would
  never be left behind. Now covered by a parametrized test for both
  failures.
* `--platform` takes `choices` from the packager's matrix, so a typo
  fails at parse time rather than after the boost-defaults and upload
  destination have been decided against a value matching nothing.
* The msvc 192 preview test reads the `compiler.version` column instead
  of searching stdout for "192"; the substring form also passed on an
  empty matrix, which is the failure most worth catching.
* The subprocess PYTHONPATH pin derives the repo root from the test
  file, not from an imported module's `__file__` -- which resolves into
  site-packages under an installed layout, defeating the pin.
* Whole-command assertions in the conan_deploy tests: the `[:3]`/`[-3:]`
  slices skipped `-c`, the flag that keeps the list a list of *cached*
  binaries. One shared recorder helper instead of two copies.
* A test that the VS2019 save and restore spell the same tarball, the
  pairing the Linux jobs already have, because a mismatch fails only at
  tag time.
* `"pip install"` rather than `"install"` when filtering steps; the
  un-flagged `conan_setup` call asserted by shape; the eleven msvc 192
  tests grouped under one class; the `\` continuation restored in
  conan_setup's usage docstring.

Investigated and documented rather than changed: conan 2.31 writes
`remotes.json` via a `.tmp` plus `os.replace`, so concurrent jobs cannot
tear the file, but nothing locks the read-modify-write and a simultaneous
add can lose one remote. The failure is loud and the fix -- a per-job
CONAN_HOME -- gives up the shared package cache these builds need, so it
is noted at both call sites and in the troubleshooting list instead.

Declined, with reasons: marking the preview test `integration` (that
marker means real conan + gcovr and multi-minute wall time; this runs no
conan and takes a second, and the file already has other unmocked
subprocess calls), merging the two `if ci_type == "github"` blocks (both
predate this PR -- master has the same four), and splitting the generated
build.py `__main__` (pre-existing shape this diff adds ~15 lines to;
restructuring the script every repo runs belongs in its own change).
---
 README.md                                     |   7 +-
 docs/USAGE.md                                 |   5 +-
 tests/test_build_file_generator.py            |  47 +-
 tests/test_ci_file_generator.py               | 401 +++++++++++-------
 tests/test_conan_deploy.py                    |  84 ++--
 xmsconan/build_tools/vs2019_build.py          |  21 +-
 xmsconan/ci_tools/conan_deploy.py             |  40 +-
 xmsconan/ci_tools/conan_setup.py              |   3 +-
 xmsconan/constants.py                         |   8 +-
 xmsconan/generator_tools/ci_file_generator.py |  35 ++
 .../ci_templates/gitlab-ci.yml.jinja          |  31 +-
 .../generator_tools/templates/build.py.jinja  |  10 +-
 xmsconan/package_tools/packager.py            |  11 +-
 13 files changed, 462 insertions(+), 241 deletions(-)

diff --git a/README.md b/README.md
index c94cb49..6b90b9c 100644
--- a/README.md
+++ b/README.md
@@ -92,6 +92,7 @@ The `build.toml` file defines the structure and dependencies of your XMS library
 | `pybind_advertises_module` | boolean | `false` | Advertise the pybind module's import library (`_<name>`) to C++ consumers instead of the static library, and install the module to `bin/` + `lib/`. Windows-only in effect; opt-in because module consumers see only exported symbols. Also what renames the Windows Debug module to `_<name>_d`, matching what `cpp_info` advertises. See `docs/USAGE.md` §7.5. |
 | `[matrix].compiler_runtime` | array[string] | `["dynamic", "static"]` | Which MSVC runtimes the fan-out builds. `["dynamic"]` drops the static-CRT configurations (and their `wchar_t` / `testing` copies) for a library nothing consumes a `/MT` build of. Inert on Linux and macOS. See `docs/USAGE.md` §5.4.1. |
 | `[matrix].wheel_only` | boolean | `false` | Build only what a wheel release needs — Release with tests, Debug with tests, and the pybind build. Three configurations for a single-ABI library (down from 5 on Linux/macOS, 13 on Windows), matching in everything but `build_type` and `pybind`. The pybind leg fans out, so each extra `python_versions` or `pybind_build_types` entry adds one configuration on top of the three. Drops the library-only and `wchar_t=typedef` configurations and narrows `compiler_runtime` to `["dynamic"]` unless set explicitly. See `docs/USAGE.md` §5.4.1. |
+| `[ci].windows_vs2019` | boolean | `false` | Also build the `windows_vs2019` (msvc 192) matrix in CI and publish it to the `aquaveo-vs2019` remote. **GitLab only** — a GitHub project setting it is warned and gets no jobs. Emitted beside the msvc 194 Windows jobs, so it requires `[ci].windows` and is rejected with it off. No wheels: an msvc 192 wheel and an msvc 194 wheel are the same devpi filename. See `docs/USAGE.md` §10.2. |
 | `[matrix].pybind_build_types` | array[string] | `["Release"]` | Which build types get a pybind configuration. Add `"Debug"` when consumers link a Debug module; `XMS_COVERAGE=1` no longer adds `Debug` on top, because coverage takes its Python half from the Release pybind build. On Windows the Debug leg publishes no wheel and runs no Python tests. See `docs/USAGE.md` §5.4.1 and §7.5. |
 
 ### Build Matrix Filter (`[filter]`)
@@ -380,9 +381,11 @@ On Windows, use `nextms-dev-x86` for x86_64 Linux builds. The commands are ident
 
 ## VS2019 (msvc 192) Packages
 
-GitHub retired the `windows-2019` runner image, so the msvc 192 binaries the Aquaveo desktop products (GMS/SMS/WMS) consume are built **manually, on a developer workstation with Visual Studio 2019 installed**, and published to a separate Conan remote, `aquaveo-vs2019`.
+The msvc 192 binaries the Aquaveo desktop products (GMS/SMS/WMS) consume are published to a separate Conan remote, `aquaveo-vs2019`, so they never mix with the CI-published ones. `xmsconan vs2019` drives that build **manually, on a developer workstation with Visual Studio 2019 installed**.
 
-**None of this runs in CI, by design.** CI is unchanged: it still builds gcc 13 / apple-clang 17 / msvc 194 and publishes to the `aquaveo` remote (the `aquaveo-stable` Artifactory repo). There is no Windows-2019 CI job to restore — the runner image is gone.
+**GitLab CI can build this matrix too.** The `GLR-UV` runner carries VS2019 alongside VS2022, so a repository can set `[ci].windows_vs2019 = true` and get a `Conan Build - Windows VS2019` job on every pipeline, publishing to the same `aquaveo-vs2019` remote — see `docs/USAGE.md` §10.2. GitHub cannot: it retired the `windows-2019` image and has no replacement, so a GitHub project setting the flag is warned and gets no jobs.
+
+The manual track below stays, and is still the only route for **wheels** (CI deliberately publishes none for msvc 192 — a wheel's tags do not record which MSVC built it, so it would collide with the msvc 194 wheel on devpi) and for **libraries whose repository has not opted in**.
 
 ```bash
 # One time: add + log in to the aquaveo-vs2019 remote, then check the machine
diff --git a/docs/USAGE.md b/docs/USAGE.md
index 71b273d..8727583 100644
--- a/docs/USAGE.md
+++ b/docs/USAGE.md
@@ -616,7 +616,7 @@ The generated jobs follow the pattern:
 - `Conan Build - Windows VS2019`, `Conan Deploy - Windows VS2019` (only with `[ci].windows_vs2019`, §5.6): the second Windows toolchain, msvc 192. Same runner, same ABI fan-out and same tag-gated export/restore split as the msvc 194 pair; four things differ, and all four are load-bearing.
   - `build.py --platform windows_vs2019` selects the msvc 192 matrix. The recipe forks its third-party stack on `compiler.version` (boost 1.74.0.3 + zlib 1.2.11 rather than 1.86.0 + 1.3.1), and `build.py` drops the boost option defaults for this platform because the legacy recipe does not declare them. `--build-missing` goes with it: the legacy dependency graph is not fully prebuilt.
   - The `aquaveo-vs2019` remote is added with `xmsconan_conan_setup --remote-name … --append`. Appended, not inserted first: on a shared runner it must not become the first stop for every `conan install`. It is where the legacy dependencies resolve from as well as where the results go.
-  - Every deploy step carries `--package-query compiler.version=192`. The Conan cache on a runner is per machine, not per job, so both `conan cache save` and `conan upload` — which match by *reference* — would otherwise carry a concurrent msvc 194 job's binaries onto the remote whose only purpose is to keep the two toolchains apart, and exit 0 having done it.
+  - Every deploy step carries `--package-query compiler.version=192`. The Conan cache on a runner is per machine, not per job, so both `conan cache save` and `conan upload` — which match by *reference* — would otherwise carry a concurrent msvc 194 job's binaries onto the remote whose only purpose is to keep the two toolchains apart, and exit 0 having done it. **The mitigation is symmetric:** the msvc 194 jobs carry `--package-query compiler.version=194` on their own save and upload, unconditionally, whether or not `[ci].windows_vs2019` is set. The mirror leak is the worse of the two — it puts msvc 192 binaries on the production `aquaveo` remote — and a guard present only in the configuration that needs it is one refactor from being dropped from the one that does. Both values are read from the packager's own matrix rather than written into the template, so a toolchain bump cannot leave a query that matches nothing behind (which would publish nothing, greenly).
   - **No wheels.** A wheel's tags (`cp310-cp310-win_amd64`) say nothing about which MSVC built it, so an msvc 192 wheel and an msvc 194 wheel are the same devpi filename and publishing both would have them overwrite each other by upload order. The VS2019 wheels the desktop products consume are still produced deliberately, by hand (§16.8).
 - Wheel-repair always runs `cp313-cp313`'s `xmsconan_wheel_repair` inside the manylinux container; auditwheel itself doesn't care about the host Python.
 - Required CI variables: `AQUAPI_URL`, `AQUAPI_USERNAME`, `AQUAPI_PASSWORD` (for wheel deploy).
@@ -625,6 +625,7 @@ The generated jobs follow the pattern:
   `conan create`, so a credential put there is printed to the job log in cleartext. Nothing in the recipe or the
   generated CMake reads them, so a build is unaffected. This is why they are absent from the `[filter.buildenv]`
   names in §5.8 -- they are not names the profiles set.
+- **Concurrent `conan remote add` on one runner.** Each Windows job adds its remotes at the start, and several jobs share a machine, so they write one `~/.conan2/remotes.json`. Conan writes it as `remotes.json.tmp` plus an `os.replace`, so the file cannot be torn — but there is no lock around the read-modify-write, so two jobs adding remotes in the same instant can lose one of the two additions. The failure is loud (the job that lost its remote fails resolving dependencies; it does not publish to the wrong place) and the fix — a per-job `CONAN_HOME` — would give up the shared package cache these builds depend on, so it is left alone deliberately. Retry the job.
 - Required CI variables with `[ci].windows_vs2019`: `CONAN_LOGIN_USERNAME_AQUAVEO_VS2019` and
   `CONAN_PASSWORD_AQUAVEO_VS2019`, for the upload to `aquaveo-vs2019`. Conan derives those names by uppercasing
   the remote name and replacing hyphens with underscores, and reads them from the environment — the generated job
@@ -1174,7 +1175,7 @@ Wheels are tagged `cp310-cp310-...` or `cp313-cp313-...`; pip picks the right on
 - **`xmsconan vs2019 build` stops at preflight with "outside the pinned `~=2.31.0` series".** Intentional (§16.3). Install the pinned client — `pip install "conan~=2.31.0"` — rather than working around the check; a different minor can change package_ids and detach your build from what's already published.
 - **VS2019 build fails on a boost option Conan says no recipe defines.** The legacy `boost/1.74.0.3` doesn't declare the conan-center 1.86 options. The driver already passes `apply_boost_defaults=False`; if you're constructing `XmsConanPackager` yourself for msvc 192, pass it too (§16.6).
 - **`Conan Deploy - Windows VS2019` fails authenticating to `aquaveo-vs2019`.** The job adds the remote but never logs in explicitly; Conan reads `CONAN_LOGIN_USERNAME_AQUAVEO_VS2019` / `CONAN_PASSWORD_AQUAVEO_VS2019` from the environment. Add both as GitLab CI variables. Only the tag-time deploy needs them, so the branch pipelines pass without them and the gap surfaces at the first release.
-- **msvc 194 binaries turned up on the `aquaveo-vs2019` remote.** Something published without `--package-query compiler.version=192`. Both `conan cache save` and `conan upload` match by reference, and a runner's Conan cache is shared across the jobs on that machine, so an unqueried publish from the msvc 192 job carries whatever the msvc 194 job left behind. The generated pipeline passes the query on every deploy step; a hand-run `xmsconan_conan_deploy` or a `build.py --upload` without `--platform windows_vs2019` does not.
+- **Binaries from the wrong toolchain turned up on a remote.** Something published without its `--package-query compiler.version=...`. Both `conan cache save` and `conan upload` match by reference, and a runner's Conan cache is shared across the jobs on that machine, so an unqueried publish from the msvc 192 job carries whatever the msvc 194 job left behind. The generated pipeline passes the matching query on every Windows deploy step, in both directions; a hand-run `xmsconan_conan_deploy` without `--package-query`, or a `build.py --upload` whose `--platform` does not match the binaries in the cache, does not.
 - **VS2019 packages don't show up for consumers.** They go to `aquaveo-vs2019`, not `aquaveo` — the consuming machine needs that remote configured too. Note that `xmsconan_vs2019 setup` *appends* the remote rather than putting it first (§16.2), so it does not shadow `aquaveo` for your other work.
 - **`xmsconan vs2019 build` exits 3 with a table of `skipped` rows.** Nothing was built. Almost always a typo in `--root` (each library is looked for at `<root>/<library>`), a `--filter` that matches no configuration, or a library that has no `build.toml` yet. See the exit-code table in §16.4.
 - **`Could NOT find Python3: Found unsuitable version "3.12.0", but required is exact version "3.10"`.** The interpreter running conan *is* the target Python for a pybind build (§16.8). Re-run from a 3.10 virtual environment, or build the version you're running with `--python-versions 3.12`. `xmsconan vs2019 build` now catches this at preflight and exits 2 before compiling anything — but only when the filtered matrix actually contains a pybind configuration.
diff --git a/tests/test_build_file_generator.py b/tests/test_build_file_generator.py
index 4a9be0c..680ec9d 100644
--- a/tests/test_build_file_generator.py
+++ b/tests/test_build_file_generator.py
@@ -191,7 +191,15 @@ def test_copy_xms_conan2_file_copies(tmp_path):
 
 # --- Template generation tests ---
 
-REAL_TEMPLATE_DIR = Path(__file__).resolve().parent.parent / "xmsconan" / "generator_tools" / "templates"
+#: This checkout's root, derived from the test file's own location.
+#:
+#: Deliberately not from an imported module's ``__file__``: under an installed
+#: (non-editable) layout that resolves into site-packages, so anything using it
+#: to pin a subprocess to "this tree" would silently pin it to another one --
+#: which is the exact failure the pin exists to prevent.
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+REAL_TEMPLATE_DIR = REPO_ROOT / "xmsconan" / "generator_tools" / "templates"
 
 
 def _copy_template(name, dest_dir):
@@ -764,6 +772,24 @@ def test_generated_build_py_ties_boost_defaults_and_upload_remote_to_platform(tm
     assert '"package_query": f"compiler.version={VS2019_MSVC_VERSION}",' in content
 
 
+def _preview_column(stdout, header):
+    """Return one column of ``build.py --preview``'s table, one entry per configuration.
+
+    The table is a tabulate grid, so the rows worth reading are the ones whose
+    first cell is the configuration number; the separator rows and the banner
+    above the table are not.
+    """
+    rows = [
+        [cell.strip() for cell in line.strip().strip("|").split("|")]
+        for line in stdout.splitlines()
+        if line.strip().startswith("|")
+    ]
+    if not rows:
+        return []
+    index = rows[0].index(header)
+    return [row[index] for row in rows[1:] if row[0].isdigit()]
+
+
 def test_generated_build_py_builds_the_msvc_192_matrix_when_asked(tmp_path):
     """`build.py --preview --platform windows_vs2019` really produces msvc 192.
 
@@ -772,12 +798,6 @@ def test_generated_build_py_builds_the_msvc_192_matrix_when_asked(tmp_path):
     matrix" are different claims -- and the platform key is a string the
     packager could stop recognizing without any of the text changing.
     """
-    import os
-    import subprocess
-    import sys
-
-    from xmsconan import generator_tools
-
     toml_file = tmp_path / "build.toml"
     toml_file.write_text('library_name = "xmscore"\ndescription = "Core"\n', encoding="utf-8")
     output_dir = tmp_path / "output"
@@ -792,18 +812,21 @@ def test_generated_build_py_builds_the_msvc_192_matrix_when_asked(tmp_path):
     # PYTHONPATH pins the subprocess to *this* checkout. build.py runs from the
     # generated directory, so it would otherwise import whatever xmsconan is
     # installed on the machine and the test would grade someone else's tree.
-    repo_root = Path(generator_tools.__file__).resolve().parents[2]
     result = subprocess.run(
         [sys.executable, "build.py", "--preview", "--platform", "windows_vs2019"],
         cwd=str(output_dir), capture_output=True, text=True,
-        env={**os.environ, "PYTHONPATH": str(repo_root)},
+        env={**os.environ, "PYTHONPATH": str(REPO_ROOT)},
     )
 
     assert result.returncode == 0, result.stdout + result.stderr
     assert "boost defaults not applied" in result.stdout
-    # Every configuration in the table is msvc 192, and none is the CI toolchain.
-    assert "192" in result.stdout
-    assert "194" not in result.stdout
+    # Read the compiler.version column rather than searching stdout for "192".
+    # A substring check passes on any table that mentions the number anywhere —
+    # a package version, a path — and `"194" not in stdout` would pass on an
+    # empty matrix, which is the failure most worth catching here.
+    versions = _preview_column(result.stdout, "compiler.version")
+    assert versions, f"no configurations in the preview table:\n{result.stdout}"
+    assert set(versions) == {"192"}, versions
 
 
 def test_generated_build_py_can_skip_the_dependency_libs_pass(tmp_path):
diff --git a/tests/test_ci_file_generator.py b/tests/test_ci_file_generator.py
index af33cd0..e0ad7b0 100644
--- a/tests/test_ci_file_generator.py
+++ b/tests/test_ci_file_generator.py
@@ -387,7 +387,9 @@ def test_gitlab_windows_jobs_install_with_uv_not_pip(tmp_path):
     parsed = yaml.safe_load((output_dir / ".gitlab-ci.yml").read_text(encoding="utf-8"))
 
     for name in ("Conan Build - Windows", "Conan Deploy - Windows"):
-        installs = [step for step in parsed[name]["script"] if "install" in step]
+        # "pip install", not "install": a future `conan install` step in these
+        # jobs would otherwise be swept in and asserted to start with "uv pip".
+        installs = [step for step in parsed[name]["script"] if "pip install" in step]
         assert installs, name
         for step in installs:
             assert step.startswith("uv pip install "), f"{name}: {step!r}"
@@ -1611,162 +1613,249 @@ def _gitlab_jobs(tmp_path, **ci_flags):
     return yaml.safe_load((output_dir / ".gitlab-ci.yml").read_text(encoding="utf-8"))
 
 
-def test_gitlab_vs2019_jobs_are_opt_in(tmp_path):
-    """No [ci].windows_vs2019 means no msvc 192 jobs.
-
-    The matrix roughly doubles the Windows half of a pipeline and only the
-    libraries the VS2019-era desktop products consume need it, so a repository
-    that has never asked for msvc 192 must not start building it because its
-    runner acquired a second toolchain.
-    """
-    pipeline = _gitlab_jobs(tmp_path)
-
-    assert "Conan Build - Windows VS2019" not in pipeline
-    assert "Conan Deploy - Windows VS2019" not in pipeline
-    # The msvc 194 jobs are untouched by the opt-in being absent.
-    assert "Conan Build - Windows" in pipeline
-
-
-def test_gitlab_vs2019_build_selects_the_msvc_192_matrix(tmp_path):
-    """The build job passes --platform windows_vs2019 and nothing else does.
-
-    That flag is the whole difference in what gets compiled: it selects the
-    msvc 192 platform key, and `build.py` reads it to drop the boost option
-    defaults the legacy boost/1.74.0.3 recipe does not declare. The msvc 194
-    job must not acquire it.
-    """
-    pipeline = _gitlab_jobs(tmp_path, windows_vs2019=True)
-
-    builds = [step for step in pipeline["Conan Build - Windows VS2019"]["script"]
-              if step.startswith("python build.py")]
-    assert len(builds) == 1
-    assert "--platform windows_vs2019" in builds[0]
-    # The legacy dependency graph is not fully prebuilt for msvc 192.
-    assert "--build-missing" in builds[0]
-
-    other = [step for step in pipeline["Conan Build - Windows"]["script"]
-             if step.startswith("python build.py")]
-    assert all("--platform" not in step for step in other)
-
-
-def test_gitlab_vs2019_build_publishes_no_wheel(tmp_path):
-    """No --wheel-dir, and no wheel artifact, on either msvc 192 job.
-
-    A wheel's tags (cp310-cp310-win_amd64) say nothing about which MSVC built
-    it, so an msvc 192 wheel and an msvc 194 wheel are the same devpi filename
-    -- publishing both would have them overwrite each other by upload order.
-    """
-    pipeline = _gitlab_jobs(tmp_path, windows_vs2019=True)
-
-    job = pipeline["Conan Build - Windows VS2019"]
-    assert all("--wheel-dir" not in step for step in job["script"])
-    assert all("wheel" not in path for path in job["artifacts"]["paths"])
-    # And no deploy job was added for a wheel that is never staged.
-    assert "Wheel Deploy - Windows VS2019" not in pipeline
-
-
-def test_gitlab_vs2019_jobs_keep_msvc_192_off_the_ci_remote(tmp_path):
-    """Every msvc 192 deploy step names the VS2019 remote and the 192 query.
-
-    Both halves, on both jobs. The Conan cache on a runner is per machine, not
-    per job, so a save or an upload matching by reference alone would carry the
-    msvc 194 job's binaries onto a remote whose only purpose is to keep the two
-    toolchains apart -- and exit 0 having done it.
-    """
-    pipeline = _gitlab_jobs(tmp_path, windows_vs2019=True)
-
-    deploys = [
-        step
-        for name in ("Conan Build - Windows VS2019", "Conan Deploy - Windows VS2019")
-        for step in pipeline[name]["script"]
-        if step.startswith("xmsconan_conan_deploy")
-    ]
-    assert len(deploys) == 2
-    for step in deploys:
-        assert "--package-query compiler.version=192" in step
-    upload = [step for step in deploys if "--upload" in step]
-    assert len(upload) == 1
-    assert "--remote aquaveo-vs2019" in upload[0]
-
-    # The VS2019 remote is added, and appended rather than inserted first: on a
-    # shared runner it must not become the first stop for every conan install.
-    for name in ("Conan Build - Windows VS2019", "Conan Deploy - Windows VS2019"):
-        setups = [step for step in pipeline[name]["script"]
-                  if step.startswith("xmsconan_conan_setup")]
-        assert any(
-            "--remote-name aquaveo-vs2019" in step and "--append" in step
-            for step in setups
-        ), name
-        # The CI remote is still configured: the recipe's own dependencies
-        # resolve from it even on the legacy toolchain.
-        assert "xmsconan_conan_setup" in setups
-
-
-def test_gitlab_vs2019_jobs_match_the_msvc_194_shape(tmp_path):
-    """Same runner, same ABI fan-out, same tag-gated deploy as the msvc 194 pair."""
-    pipeline = _gitlab_jobs(
-        tmp_path, windows_vs2019=True, python_versions=["3.10", "3.13"],
-    )
-
-    for name in ("Conan Build - Windows VS2019", "Conan Deploy - Windows VS2019"):
-        job = pipeline[name]
-        assert job["image"] == "GLR-UV", name
-        assert job["tags"] == ["WinVM"], name
-        matrix = job["parallel"]["matrix"]
-        assert [entry["PYTHON_TARGET_VERSION"] for entry in matrix] == ["3.10", "3.13"], name
-        assert job["script"].index("uv venv --python ${PYTHON_TARGET_VERSION} .venv") < \
-            job["script"].index("source .venv/Scripts/activate"), name
-
-    assert pipeline["Conan Build - Windows VS2019"]["stage"] == \
-        pipeline["Conan Build - Windows"]["stage"]
-    deploy = pipeline["Conan Deploy - Windows VS2019"]
-    assert deploy["stage"] == "Deploy"
-    assert deploy["only"] == ["tags"]
-    assert deploy["needs"] == [{"job": "Conan Build - Windows VS2019", "artifacts": True}]
-
-
-def test_gitlab_vs2019_without_deploy_exports_nothing(tmp_path):
-    """[ci].deploy = false leaves the msvc 192 build with no export and no deploy job.
-
-    `artifacts: paths:` with nothing under it is not a harmless no-op -- GitLab
-    parses the key as null and rejects the file -- so the build job has to keep
-    a path of its own when the export goes away.
-    """
-    pipeline = _gitlab_jobs(tmp_path, windows_vs2019=True, deploy=False)
-
-    job = pipeline["Conan Build - Windows VS2019"]
-    assert job["artifacts"]["paths"] == ["test_artifacts/"]
-    assert all(not step.startswith("xmsconan_conan_deploy") for step in job["script"])
-    assert "Conan Deploy - Windows VS2019" not in pipeline
-
-
-def test_gitlab_vs2019_requires_windows(tmp_path):
-    """windows_vs2019 with [ci].windows = false is rejected, not silently honored.
-
-    The msvc 192 jobs are an addition to the Windows jobs; emitting them under
-    [ci].windows = false would resurrect the Windows half of a pipeline the
-    repository asked not to have.
-    """
-    toml_file = write_gitlab_toml(tmp_path, windows_vs2019=True, windows=False)
-
-    with pytest.raises(ValueError, match=r"windows_vs2019 = true with \[ci\].windows"):
-        generate_ci(str(toml_file), "1.0.0", str(tmp_path / "output"))
-
-
-def test_github_warns_that_vs2019_is_gitlab_only(tmp_path, caplog):
-    """A GitHub project opting into msvc 192 is told it gets nothing.
-
-    windows_vs2019 is a plain bool, so it cannot join the tri-state flags the
-    neighbouring warning covers -- and silence here would leave a repository
-    believing it publishes msvc 192 until a consumer failed to resolve it.
-    """
-    toml_file = write_github_toml(tmp_path, windows_vs2019=True)
-
-    with caplog.at_level(logging.WARNING):
-        generate_ci(str(toml_file), "1.0.0", str(tmp_path / "output"))
+class TestVs2019Ci:
+    """The msvc 192 opt-in: the jobs it adds, and the toolchain separation it needs.
+
+    Grouped because they share one premise -- two Windows toolchains building
+    the same reference on one runner fleet -- and because the msvc 194
+    assertions here only make sense next to the msvc 192 ones they mirror.
+    """
+
+    def test_gitlab_windows_publishes_are_restricted_to_their_own_toolchain(self, tmp_path):
+        """Both Windows toolchains restrict every publish to their own compiler.version.
+
+        The hazard is symmetric and the mitigation has to be. A runner's Conan cache
+        is per machine, not per job, and `conan cache save <ref>:*` / `conan upload
+        <ref>` match by *reference* -- so with both toolchains building the same
+        reference on the same fleet at the same time, an unqueried step on either
+        side ships the other's binaries. The msvc 192 direction pollutes a legacy
+        remote; the msvc 194 direction pollutes the production one.
+
+        Asserted with the opt-in *off* as well, because the msvc 194 query has to be
+        unconditional: a guard that appears only in the configuration that needs it
+        is one refactor away from being dropped from the one that does.
+        """
+        for vs2019 in (False, True):
+            case_dir = tmp_path / f"vs2019-{vs2019}"
+            case_dir.mkdir()
+            pipeline = _gitlab_jobs(case_dir, windows_vs2019=vs2019)
+            expected = {
+                "Conan Build - Windows": "compiler.version=194",
+                "Conan Deploy - Windows": "compiler.version=194",
+                "Conan Build - Windows VS2019": "compiler.version=192",
+                "Conan Deploy - Windows VS2019": "compiler.version=192",
+            }
+            for name, query in expected.items():
+                if name not in pipeline:
+                    assert not vs2019 and "VS2019" in name, name
+                    continue
+                deploys = [
+                    step for step in pipeline[name]["script"]
+                    if step.startswith("xmsconan_conan_deploy")
+                ]
+                assert deploys, name
+                for step in deploys:
+                    assert f"--package-query {query}" in step, (name, step)
+
+    def test_windows_package_query_tracks_the_packager_matrix(self, tmp_path):
+        """The rendered compiler.version comes from the matrix it is meant to select.
+
+        A literal in the template would not fail loudly if the matrix moved on: a
+        `conan upload -p compiler.version=194` after a bump to 195 matches nothing,
+        and the job goes green having published no binaries at all.
+        """
+        from xmsconan.package_tools.packager import configurations
+
+        pipeline = _gitlab_jobs(tmp_path, windows_vs2019=True)
+        for name, platform in (
+            ("Conan Deploy - Windows", "windows"),
+            ("Conan Deploy - Windows VS2019", "windows_vs2019"),
+        ):
+            version, = configurations[platform]["compiler.version"]
+            step, = [
+                s for s in pipeline[name]["script"] if s.startswith("xmsconan_conan_deploy")
+            ]
+            assert f"--package-query compiler.version={version}" in step, (name, step)
+
+    def test_gitlab_vs2019_jobs_are_opt_in(self, tmp_path):
+        """No [ci].windows_vs2019 means no msvc 192 jobs.
+
+        The matrix roughly doubles the Windows half of a pipeline and only the
+        libraries the VS2019-era desktop products consume need it, so a repository
+        that has never asked for msvc 192 must not start building it because its
+        runner acquired a second toolchain.
+        """
+        pipeline = _gitlab_jobs(tmp_path)
+
+        assert "Conan Build - Windows VS2019" not in pipeline
+        assert "Conan Deploy - Windows VS2019" not in pipeline
+        # The msvc 194 jobs are untouched by the opt-in being absent.
+        assert "Conan Build - Windows" in pipeline
+
+    def test_gitlab_vs2019_build_selects_the_msvc_192_matrix(self, tmp_path):
+        """The build job passes --platform windows_vs2019 and nothing else does.
+
+        That flag is the whole difference in what gets compiled: it selects the
+        msvc 192 platform key, and `build.py` reads it to drop the boost option
+        defaults the legacy boost/1.74.0.3 recipe does not declare. The msvc 194
+        job must not acquire it.
+        """
+        pipeline = _gitlab_jobs(tmp_path, windows_vs2019=True)
+
+        builds = [step for step in pipeline["Conan Build - Windows VS2019"]["script"]
+                  if step.startswith("python build.py")]
+        assert len(builds) == 1
+        assert "--platform windows_vs2019" in builds[0]
+        # The legacy dependency graph is not fully prebuilt for msvc 192.
+        assert "--build-missing" in builds[0]
+
+        other = [step for step in pipeline["Conan Build - Windows"]["script"]
+                 if step.startswith("python build.py")]
+        assert all("--platform" not in step for step in other)
+
+    def test_gitlab_vs2019_build_publishes_no_wheel(self, tmp_path):
+        """No --wheel-dir, and no wheel artifact, on either msvc 192 job.
+
+        A wheel's tags (cp310-cp310-win_amd64) say nothing about which MSVC built
+        it, so an msvc 192 wheel and an msvc 194 wheel are the same devpi filename
+        -- publishing both would have them overwrite each other by upload order.
+        """
+        pipeline = _gitlab_jobs(tmp_path, windows_vs2019=True)
+
+        job = pipeline["Conan Build - Windows VS2019"]
+        assert all("--wheel-dir" not in step for step in job["script"])
+        assert all("wheel" not in path for path in job["artifacts"]["paths"])
+        # And no deploy job was added for a wheel that is never staged.
+        assert "Wheel Deploy - Windows VS2019" not in pipeline
+
+    def test_gitlab_vs2019_jobs_keep_msvc_192_off_the_ci_remote(self, tmp_path):
+        """Every msvc 192 deploy step names the VS2019 remote and the 192 query.
+
+        Both halves, on both jobs. The Conan cache on a runner is per machine, not
+        per job, so a save or an upload matching by reference alone would carry the
+        msvc 194 job's binaries onto a remote whose only purpose is to keep the two
+        toolchains apart -- and exit 0 having done it.
+        """
+        pipeline = _gitlab_jobs(tmp_path, windows_vs2019=True)
+
+        deploys = [
+            step
+            for name in ("Conan Build - Windows VS2019", "Conan Deploy - Windows VS2019")
+            for step in pipeline[name]["script"]
+            if step.startswith("xmsconan_conan_deploy")
+        ]
+        assert len(deploys) == 2
+        for step in deploys:
+            assert "--package-query compiler.version=192" in step
+        upload = [step for step in deploys if "--upload" in step]
+        assert len(upload) == 1
+        assert "--remote aquaveo-vs2019" in upload[0]
+
+        # The VS2019 remote is added, and appended rather than inserted first: on a
+        # shared runner it must not become the first stop for every conan install.
+        for name in ("Conan Build - Windows VS2019", "Conan Deploy - Windows VS2019"):
+            setups = [step for step in pipeline[name]["script"]
+                      if step.startswith("xmsconan_conan_setup")]
+            assert any(
+                "--remote-name aquaveo-vs2019" in step and "--append" in step
+                for step in setups
+            ), name
+            # The CI remote is still configured, by a call that names no remote:
+            # the recipe's own dependencies resolve from it even on the legacy
+            # toolchain. Asserted as "an entry with no --remote-name" rather than
+            # as an exact string, so the bare call gaining an unrelated flag does
+            # not read as the CI remote having been dropped.
+            assert any("--remote-name" not in step for step in setups), name
+
+    def test_gitlab_vs2019_save_and_restore_spell_the_same_tarball(self, tmp_path):
+        """The VS2019 build's --save name and the deploy's --restore name agree.
+
+        The same pairing the Linux jobs are held to, and for the same reason: the
+        deploy restores by name, so a build that saved one name while the deploy
+        asked for another fails only on a tag, in the job that publishes. The msvc
+        192 tarball carries an extra `-vs2019-` segment to keep it distinct from the
+        msvc 194 one in the same artifact space, which is exactly the kind of
+        detail one end can acquire without the other.
+        """
+        pipeline = _gitlab_jobs(tmp_path, windows_vs2019=True)
+
+        def tarball(job_name, flag):
+            steps = [
+                step for step in pipeline[job_name]["script"]
+                if step.startswith("xmsconan_conan_deploy") and flag in step
+            ]
+            assert len(steps) == 1, (job_name, steps)
+            return steps[0].split(flag, 1)[1].split()[0]
+
+        saved = tarball("Conan Build - Windows VS2019", "--save ")
+        restored = tarball("Conan Deploy - Windows VS2019", "--restore ")
+        assert saved == restored, (saved, restored)
+        # And distinct from the msvc 194 pair's, which shares the artifact space.
+        assert "-vs2019-" in saved
+        assert saved != tarball("Conan Build - Windows", "--save ")
+
+    def test_gitlab_vs2019_jobs_match_the_msvc_194_shape(self, tmp_path):
+        """Same runner, same ABI fan-out, same tag-gated deploy as the msvc 194 pair."""
+        pipeline = _gitlab_jobs(
+            tmp_path, windows_vs2019=True, python_versions=["3.10", "3.13"],
+        )
 
-    assert "windows_vs2019" in caplog.text
-    assert "GitLab-only" in caplog.text
+        for name in ("Conan Build - Windows VS2019", "Conan Deploy - Windows VS2019"):
+            job = pipeline[name]
+            assert job["image"] == "GLR-UV", name
+            assert job["tags"] == ["WinVM"], name
+            matrix = job["parallel"]["matrix"]
+            assert [entry["PYTHON_TARGET_VERSION"] for entry in matrix] == ["3.10", "3.13"], name
+            assert job["script"].index("uv venv --python ${PYTHON_TARGET_VERSION} .venv") < \
+                job["script"].index("source .venv/Scripts/activate"), name
+
+        assert pipeline["Conan Build - Windows VS2019"]["stage"] == \
+            pipeline["Conan Build - Windows"]["stage"]
+        deploy = pipeline["Conan Deploy - Windows VS2019"]
+        assert deploy["stage"] == "Deploy"
+        assert deploy["only"] == ["tags"]
+        assert deploy["needs"] == [{"job": "Conan Build - Windows VS2019", "artifacts": True}]
+
+    def test_gitlab_vs2019_without_deploy_exports_nothing(self, tmp_path):
+        """[ci].deploy = false leaves the msvc 192 build with no export and no deploy job.
+
+        `artifacts: paths:` with nothing under it is not a harmless no-op -- GitLab
+        parses the key as null and rejects the file -- so the build job has to keep
+        a path of its own when the export goes away.
+        """
+        pipeline = _gitlab_jobs(tmp_path, windows_vs2019=True, deploy=False)
+
+        job = pipeline["Conan Build - Windows VS2019"]
+        assert job["artifacts"]["paths"] == ["test_artifacts/"]
+        assert all(not step.startswith("xmsconan_conan_deploy") for step in job["script"])
+        assert "Conan Deploy - Windows VS2019" not in pipeline
+
+    def test_gitlab_vs2019_requires_windows(self, tmp_path):
+        """windows_vs2019 with [ci].windows = false is rejected, not silently honored.
+
+        The msvc 192 jobs are an addition to the Windows jobs; emitting them under
+        [ci].windows = false would resurrect the Windows half of a pipeline the
+        repository asked not to have.
+        """
+        toml_file = write_gitlab_toml(tmp_path, windows_vs2019=True, windows=False)
+
+        with pytest.raises(ValueError, match=r"windows_vs2019 = true with \[ci\].windows"):
+            generate_ci(str(toml_file), "1.0.0", str(tmp_path / "output"))
+
+    def test_github_warns_that_vs2019_is_gitlab_only(self, tmp_path, caplog):
+        """A GitHub project opting into msvc 192 is told it gets nothing.
+
+        windows_vs2019 is a plain bool, so it cannot join the tri-state flags the
+        neighbouring warning covers -- and silence here would leave a repository
+        believing it publishes msvc 192 until a consumer failed to resolve it.
+        """
+        toml_file = write_github_toml(tmp_path, windows_vs2019=True)
+
+        with caplog.at_level(logging.WARNING):
+            generate_ci(str(toml_file), "1.0.0", str(tmp_path / "output"))
+
+        assert "windows_vs2019" in caplog.text
+        assert "GitLab-only" in caplog.text
 
 
 def test_gitlab_windows_build_stages_a_wheel(tmp_path):
diff --git a/tests/test_conan_deploy.py b/tests/test_conan_deploy.py
index 1399153..e8b63b1 100644
--- a/tests/test_conan_deploy.py
+++ b/tests/test_conan_deploy.py
@@ -96,54 +96,58 @@ def test_save_with_a_package_query_resolves_a_package_list_first(mock_run):
     )
 
     assert mock_run.call_count == 2
+    # Whole commands, not slices with the middle skipped: `-c` sits in that
+    # middle, and it is the flag that keeps the list a list of *cached*
+    # binaries. Deleting it passed a `[:3]` / `[-3:]` pair of assertions.
     list_command = mock_run.call_args_list[0][0][0]
-    assert list_command[:3] == ["conan", "list", "xmscore/7.0.0:*"]
-    assert list_command[-3:] == ["-p", "compiler.version=192", "--format=json"]
+    assert list_command == [
+        "conan", "list", "xmscore/7.0.0:*", "-c",
+        "-p", "compiler.version=192", "--format=json",
+    ]
 
     save_command = mock_run.call_args_list[1][0][0]
-    assert save_command[:3] == ["conan", "cache", "save"]
-    assert "--list" in save_command
-    assert save_command[-2:] == ["--file", "out.tar.gz"]
+    list_file = save_command[save_command.index("--list") + 1]
+    assert save_command == [
+        "conan", "cache", "save", "--list", list_file, "--file", "out.tar.gz",
+    ]
     # The unrestricted pattern must not appear: it is what the query exists to
     # avoid, and passing both is a Conan error anyway.
     assert "xmscore/7.0.0:*" not in save_command
 
 
-@patch("xmsconan.ci_tools.conan_deploy.subprocess.run")
-def test_save_with_a_package_query_removes_the_list_file(mock_run):
-    """The resolved package list is a temp file and does not outlive the save.
+def _list_file_recorder(seen, fail=False):
+    """Record the ``--list`` path each `conan cache save` is handed.
 
-    It is written outside the artifact tree and deleted either way, so a
-    pipeline cannot pick up a stale list from a previous job -- which would
-    publish that job's package ids.
+    Shared by the cleanup tests so the two do not drift apart, and so neither
+    has to know the flag's argv position.
     """
-    written = []
-
     def record(command, **kwargs):
-        if command[1] == "cache":
-            written.append(command[command.index("--list") + 1])
-
-    mock_run.side_effect = record
-    conan_deploy(
-        "xmscore", "7.0.0", save="out.tar.gz", package_query="compiler.version=192",
-    )
-
-    assert len(written) == 1
-    assert not os.path.exists(written[0])
+        if "--list" in command:
+            seen.append(command[command.index("--list") + 1])
+            if fail:
+                raise subprocess.CalledProcessError(1, "conan")
+    return record
 
 
+@pytest.mark.parametrize("fail", [False, True], ids=["save-succeeds", "save-fails"])
 @patch("xmsconan.ci_tools.conan_deploy.subprocess.run")
-def test_save_with_a_package_query_removes_the_list_file_on_failure(mock_run):
-    """A failed `conan cache save` still cleans up, and still raises."""
-    seen = []
+def test_save_with_a_package_query_removes_the_list_file(mock_run, fail):
+    """The resolved package list never outlives the save, on either path.
 
-    def record(command, **kwargs):
-        if command[1] == "cache":
-            seen.append(command[command.index("--list") + 1])
-            raise subprocess.CalledProcessError(1, "conan")
+    It is a temp file rather than an artifact-tree file so a pipeline cannot
+    pick up a stale list from a previous job and publish that job's package
+    ids -- which only holds if the cleanup is unconditional.
+    """
+    seen = []
+    mock_run.side_effect = _list_file_recorder(seen, fail=fail)
 
-    mock_run.side_effect = record
-    with pytest.raises(subprocess.CalledProcessError):
+    if fail:
+        with pytest.raises(subprocess.CalledProcessError):
+            conan_deploy(
+                "xmscore", "7.0.0", save="out.tar.gz",
+                package_query="compiler.version=192",
+            )
+    else:
         conan_deploy(
             "xmscore", "7.0.0", save="out.tar.gz", package_query="compiler.version=192",
         )
@@ -152,13 +156,19 @@ def record(command, **kwargs):
     assert not os.path.exists(seen[0])
 
 
+@pytest.mark.parametrize(
+    "error", [subprocess.CalledProcessError(1, "conan"), FileNotFoundError("conan")],
+    ids=["conan-exits-nonzero", "conan-not-on-path"],
+)
 @patch("xmsconan.ci_tools.conan_deploy.subprocess.run")
-def test_package_list_removed_when_conan_list_fails(mock_run):
-    """A failed resolve leaves no file behind for a later step to trust.
+def test_package_list_removed_when_conan_list_fails(mock_run, error):
+    """A failed resolve leaves no file behind, however `conan list` failed.
 
     An empty or partial list is worse than none: `conan cache save --list`
     would accept it and produce a tarball missing binaries, and the deploy that
-    follows would publish that as a complete release.
+    follows would publish that as a complete release. The first version caught
+    ``CalledProcessError`` only, so a `conan` missing from PATH -- a
+    ``FileNotFoundError`` out of the same call -- leaked the file.
     """
     tempfiles = []
     real_mkstemp = tempfile.mkstemp
@@ -168,9 +178,9 @@ def spy(*args, **kwargs):
         tempfiles.append(path)
         return handle, path
 
-    mock_run.side_effect = subprocess.CalledProcessError(1, "conan")
+    mock_run.side_effect = error
     with patch("xmsconan.ci_tools.conan_deploy.tempfile.mkstemp", side_effect=spy):
-        with pytest.raises(subprocess.CalledProcessError):
+        with pytest.raises(type(error)):
             conan_deploy(
                 "xmscore", "7.0.0", save="out.tar.gz",
                 package_query="compiler.version=192",
diff --git a/xmsconan/build_tools/vs2019_build.py b/xmsconan/build_tools/vs2019_build.py
index 1c860a5..50b85e9 100644
--- a/xmsconan/build_tools/vs2019_build.py
+++ b/xmsconan/build_tools/vs2019_build.py
@@ -1,10 +1,21 @@
 r"""Drive the manual Visual Studio 2019 (msvc 192) package build.
 
-GitHub retired the ``windows-2019`` runner image, so the msvc 192 binaries
-can no longer be produced in CI.  They are built by hand, on a developer
-workstation that has Visual Studio 2019 installed, and published to a
-separate Conan remote (``aquaveo-vs2019``) so they never mix with the
-CI-published ``aquaveo`` remote.  Nothing in this module runs in CI.
+The msvc 192 binaries are published to a separate Conan remote
+(``aquaveo-vs2019``) so they never mix with the CI-published ``aquaveo``
+remote.  This module builds them by hand, on a developer workstation that has
+Visual Studio 2019 installed; nothing in it runs in CI.
+
+It is no longer the only route.  The GitLab ``GLR-UV`` runner carries VS2019,
+so a repository that sets ``[ci].windows_vs2019`` gets the same matrix built on
+every pipeline and published to the same remote (see ``docs/USAGE.md``
+section 10.2); that path drives ``build.py --platform windows_vs2019`` rather
+than this module.  GitHub still cannot -- it retired the ``windows-2019``
+image and has no replacement.
+
+This track remains the only way to produce msvc 192 *wheels*, which CI
+deliberately does not publish (a wheel's tags do not record which MSVC built
+it, so it would collide with the msvc 194 wheel on devpi), and the way to
+build a library whose repository has not opted in.
 
 Three subcommands::
 
diff --git a/xmsconan/ci_tools/conan_deploy.py b/xmsconan/ci_tools/conan_deploy.py
index 4c8d215..914994a 100644
--- a/xmsconan/ci_tools/conan_deploy.py
+++ b/xmsconan/ci_tools/conan_deploy.py
@@ -9,7 +9,9 @@
         --remote aquaveo-vs2019 --package-query compiler.version=192
 """
 import argparse
+import contextlib
 import os
+from pathlib import Path
 import subprocess
 import sys
 import tempfile
@@ -17,24 +19,33 @@
 from xmsconan.constants import DEFAULT_REMOTE_NAME
 
 
+@contextlib.contextmanager
 def _package_list(ref, package_query):
-    """Write a Conan package list of ``ref``'s binaries matching ``package_query``.
+    """Yield a Conan package list of ``ref``'s binaries matching ``package_query``.
 
     ``conan cache save`` takes either a pattern or a package list, and only the
     list can be narrowed by a binary query -- so a query is resolved to a list
     first, with ``conan list``, and the list is what gets saved.
 
+    A context manager rather than a function returning a path: the file must not
+    outlive the save, and an ownership contract that lives only in a docstring
+    is one that a later caller can miss. It also makes the cleanup total. The
+    first version unlinked on ``CalledProcessError`` alone, which left the file
+    behind for the two failures that do not raise it -- ``conan`` missing from
+    PATH (``FileNotFoundError``) and an unwritable temp directory (``OSError``
+    from ``open``) -- while the docstring promised a failed resolve leaves
+    nothing behind.
+
     Args:
         ref: ``<library>/<version>`` reference.
         package_query: Conan binary query, e.g. ``"compiler.version=192"``.
 
-    Returns:
-        Path to the package list JSON. The caller owns it and must delete it.
+    Yields:
+        Path to the package list JSON, valid for the duration of the block.
 
     Raises:
-        subprocess.CalledProcessError: ``conan list`` failed. The file is
-            removed first, so a failed resolve leaves nothing behind for a
-            later step to mistake for a complete list.
+        subprocess.CalledProcessError: ``conan list`` exited nonzero.
+        OSError: The list could not be written, or ``conan`` is not on PATH.
     """
     handle, path = tempfile.mkstemp(prefix="xmsconan-pkglist-", suffix=".json")
     os.close(handle)
@@ -45,10 +56,14 @@ def _package_list(ref, package_query):
     try:
         with open(path, "w", encoding="utf-8") as output:
             subprocess.run(command, check=True, stdout=output)
-    except subprocess.CalledProcessError:
-        os.unlink(path)
-        raise
-    return path
+        yield path
+    finally:
+        # missing_ok rather than an `if os.path.exists` guard: mkstemp created
+        # the file, so the only way it is gone is that the body moved or
+        # removed it -- and a cleanup that raised would mask whatever exception
+        # is being unwound. Expressed without a branch because that branch is
+        # not reachable from any caller and so could not be tested.
+        Path(path).unlink(missing_ok=True)
 
 
 def conan_deploy(library, version, save=None, restore=None, upload=False,
@@ -79,14 +94,11 @@ def conan_deploy(library, version, save=None, restore=None, upload=False,
 
     if save:
         if package_query:
-            list_file = _package_list(ref, package_query)
-            try:
+            with _package_list(ref, package_query) as list_file:
                 subprocess.run(
                     ["conan", "cache", "save", "--list", list_file, "--file", save],
                     check=True,
                 )
-            finally:
-                os.unlink(list_file)
         else:
             # `conan cache save` treats a bare `pkg/version` as a recipe-only pattern, so
             # the tarball would carry the recipe and none of the binaries built alongside
diff --git a/xmsconan/ci_tools/conan_setup.py b/xmsconan/ci_tools/conan_setup.py
index 7844662..e244377 100644
--- a/xmsconan/ci_tools/conan_setup.py
+++ b/xmsconan/ci_tools/conan_setup.py
@@ -4,7 +4,8 @@
 
     xmsconan_conan_setup [--remote-url URL] [--login] [--remove-conancenter]
     xmsconan_conan_setup --login --username USER --password-file PATH
-    xmsconan_conan_setup --remote-name aquaveo-vs2019         --remote-url https://.../aquaveo-vs2019 --append
+    xmsconan_conan_setup --remote-name aquaveo-vs2019 \
+        --remote-url https://.../aquaveo-vs2019 --append
 """
 import argparse
 import os
diff --git a/xmsconan/constants.py b/xmsconan/constants.py
index 20694f3..2a35e93 100644
--- a/xmsconan/constants.py
+++ b/xmsconan/constants.py
@@ -58,9 +58,11 @@ def version_sort_key(version) -> tuple:
 #: ``aquaveo-stable`` repository).
 DEFAULT_REMOTE_URL = f"{ARTIFACTORY_BASE_URL}/aquaveo-stable"
 
-#: Conan remote name for the manually built Visual Studio 2019 (msvc 192)
-#: packages.  Kept separate from :data:`DEFAULT_REMOTE_NAME` so the legacy
-#: binaries never mix with the CI-published ones.
+#: Conan remote name for the Visual Studio 2019 (msvc 192) packages, built
+#: either on a developer workstation or by the GitLab jobs a repository opts
+#: into with ``[ci].windows_vs2019``.  Kept separate from
+#: :data:`DEFAULT_REMOTE_NAME` so the legacy binaries never mix with the
+#: msvc 194 ones.
 VS2019_REMOTE_NAME = "aquaveo-vs2019"
 
 #: Artifactory URL backing :data:`VS2019_REMOTE_NAME`.
diff --git a/xmsconan/generator_tools/ci_file_generator.py b/xmsconan/generator_tools/ci_file_generator.py
index 83986a4..146bed6 100644
--- a/xmsconan/generator_tools/ci_file_generator.py
+++ b/xmsconan/generator_tools/ci_file_generator.py
@@ -26,6 +26,36 @@
     empty_ci_jobs,
     load_build_filter,
 )
+from xmsconan.package_tools.packager import configurations as _platform_configurations
+
+
+def _only_msvc_version(platform_key: str) -> str:
+    """Return the single ``compiler.version`` the named Windows matrix pins.
+
+    Read from the packager's own matrix rather than written as a literal in the
+    template. The generated pipeline restricts every Windows publish to this
+    value, so a literal that fell behind a toolchain bump would not fail --
+    ``conan upload -p compiler.version=194`` after a move to 195 matches
+    nothing, and the job would go green having published no binaries at all.
+
+    Args:
+        platform_key: Key into the packager's ``configurations``.
+
+    Returns:
+        The compiler version as a string.
+
+    Raises:
+        ValueError: When the matrix pins more or fewer than one version, which
+            would make "the version this job publishes" ambiguous.
+    """
+    versions = _platform_configurations[platform_key]["compiler.version"]
+    if len(versions) != 1:
+        raise ValueError(
+            f"platform {platform_key!r} pins {len(versions)} compiler.version values "
+            f"({', '.join(versions)}); the generated publish steps restrict to exactly "
+            f"one, so this needs a decision rather than a guess."
+        )
+    return versions[0]
 
 
 LOGGER = logging.getLogger(__name__)
@@ -498,6 +528,11 @@ def generate_ci(
         "vs2019_remote_url": VS2019_REMOTE_URL,
         "vs2019_platform_key": VS2019_PLATFORM_KEY,
         "vs2019_msvc_version": MSVC_VS2019_VERSION,
+        # The msvc 194 jobs restrict their publishes too, not just the 192 ones.
+        # A runner's Conan cache is per machine, so the hazard is symmetric: an
+        # unqueried save/upload on this side would carry the VS2019 job's
+        # binaries onto the production `aquaveo` remote.
+        "windows_msvc_version": _only_msvc_version("windows"),
         # Windows-scoped on purpose: a manylinux wheel has to be repaired to be
         # installable, so there is no equivalent switch for Linux or macOS. The
         # default follows ci_type -- see repairs_windows_wheel.
diff --git a/xmsconan/generator_tools/ci_templates/gitlab-ci.yml.jinja b/xmsconan/generator_tools/ci_templates/gitlab-ci.yml.jinja
index 0654078..7c3d435 100644
--- a/xmsconan/generator_tools/ci_templates/gitlab-ci.yml.jinja
+++ b/xmsconan/generator_tools/ci_templates/gitlab-ci.yml.jinja
@@ -447,7 +447,17 @@ Conan Build:
    on purpose. A library with nothing to vendor opts out. #>
     - xmsconan_wheel_repair --wheel-dir wheelhouse --platform windows
 <% endif %>
-    - xmsconan_conan_deploy << library_name >> ${PACKAGE_VERSION} --save .export/<< library_name >>-windows-py${PYTHON_TARGET_VERSION}-${PACKAGE_VERSION}.tar.gz
+<# Queried, like the VS2019 job's save below and for the same reason in the
+   mirror direction. A runner's Conan cache is per machine, not per job, and
+   `conan cache save <ref>:*` matches by reference -- so with
+   [ci].windows_vs2019 on, both toolchains build the same reference on the same
+   fleet at the same time, and an unqueried save here would tarball the msvc
+   192 binaries and the deploy below would publish them to the production
+   `aquaveo` remote at exit 0. Emitted unconditionally rather than only under
+   the opt-in: the restriction is a no-op when this is the only toolchain on
+   the machine, and a guard that appears only in the configuration that needs
+   it is one refactor away from being dropped from the one that does. #>
+    - xmsconan_conan_deploy << library_name >> ${PACKAGE_VERSION} --save .export/<< library_name >>-windows-py${PYTHON_TARGET_VERSION}-${PACKAGE_VERSION}.tar.gz --package-query compiler.version=<< windows_msvc_version >>
   tags:
     - WinVM
 
@@ -514,6 +524,18 @@ Conan Build:
     - uv pip install "conan~=2.31.0" --index-url https://public.aquapi.aquaveo.com/aquaveo/dev/+simple
     - uv pip install --upgrade "xmsconan>=<< xmsconan_version >>" --index-url https://public.aquapi.aquaveo.com/aquaveo/dev/+simple
     - xmsconan_conan_setup
+<# Two `conan remote add` calls per job, on a fleet that runs several jobs per
+   machine, all writing one ~/.conan2/remotes.json. Conan 2.31 writes it as
+   `remotes.json.tmp` followed by `os.replace` (conan/api/subapi/remotes.py
+   `_save`), so the file cannot be torn: a reader sees one complete document or
+   the other. There is no lock around the read-modify-write, though, so two
+   jobs adding remotes in the same instant can lose one of the two additions.
+
+   Left as is deliberately. The lost update is loud -- the job that lost its
+   remote fails resolving dependencies rather than publishing somewhere wrong
+   -- and the alternative, a per-job CONAN_HOME, gives up the shared package
+   cache these Windows builds depend on. That is a cache-model change with its
+   own blast radius, not a footnote to this one. #>
     - xmsconan_conan_setup --remote-name << vs2019_remote_name >> --remote-url << vs2019_remote_url >> --append
     - xmsconan_gen --version ${PACKAGE_VERSION} build.toml
     - python build.py --version ${PACKAGE_VERSION} --platform << vs2019_platform_key >> --build-missing --artifacts-dir test_artifacts
@@ -715,7 +737,11 @@ Repair Wheel:
     - uv pip install "conan~=2.31.0" --index-url https://public.aquapi.aquaveo.com/aquaveo/dev/+simple
     - uv pip install --upgrade "xmsconan>=<< xmsconan_version >>" --index-url https://public.aquapi.aquaveo.com/aquaveo/dev/+simple
     - xmsconan_conan_setup
-    - xmsconan_conan_deploy << library_name >> ${PACKAGE_VERSION} --restore .export/<< library_name >>-windows-py${PYTHON_TARGET_VERSION}-${PACKAGE_VERSION}.tar.gz --upload
+<# The query is repeated on the upload rather than trusted from the save: this
+   is the command that reaches the shared remote, and a tarball restored into a
+   cache that already holds the other toolchain's binaries of the same
+   reference would otherwise publish those too. #>
+    - xmsconan_conan_deploy << library_name >> ${PACKAGE_VERSION} --restore .export/<< library_name >>-windows-py${PYTHON_TARGET_VERSION}-${PACKAGE_VERSION}.tar.gz --upload --package-query compiler.version=<< windows_msvc_version >>
     - mkdir -p conan_packages
     <# ${HOME}, not the hard-coded /c/Users/admin the GLR-py* images ran as:
        the conan home is `~/.conan2`, so a runner whose service account is
@@ -770,6 +796,7 @@ Repair Wheel:
     - uv pip install "conan~=2.31.0" --index-url https://public.aquapi.aquaveo.com/aquaveo/dev/+simple
     - uv pip install --upgrade "xmsconan>=<< xmsconan_version >>" --index-url https://public.aquapi.aquaveo.com/aquaveo/dev/+simple
     - xmsconan_conan_setup
+<# Concurrent remotes.json writers: see the note on the build job above. #>
     - xmsconan_conan_setup --remote-name << vs2019_remote_name >> --remote-url << vs2019_remote_url >> --append
     - xmsconan_conan_deploy << library_name >> ${PACKAGE_VERSION} --restore .export/<< library_name >>-windows-vs2019-py${PYTHON_TARGET_VERSION}-${PACKAGE_VERSION}.tar.gz --upload --remote << vs2019_remote_name >> --package-query compiler.version=<< vs2019_msvc_version >>
   only:
diff --git a/xmsconan/generator_tools/templates/build.py.jinja b/xmsconan/generator_tools/templates/build.py.jinja
index 7bea7ba..40c6a6f 100644
--- a/xmsconan/generator_tools/templates/build.py.jinja
+++ b/xmsconan/generator_tools/templates/build.py.jinja
@@ -40,9 +40,13 @@ parser.add_argument("--filter", help="Filter dictionary in JSON format")
 parser.add_argument("--ignore-build-filter", action="store_true",
                     help="Ignore the [filter] table from build.toml")
 parser.add_argument("--build-missing", help="Build missing dependencies from source", action="store_true")
-parser.add_argument("--platform", default=None,
-                    help=f"Matrix to build ('windows', '{VS2019_PLATFORM}', 'linux', "
-                         "'darwin'). Default: detect from the running machine.")
+# choices from the packager's own matrix, not a hand-kept list: --platform is a
+# closed set compared by exact equality below, so a typo has to fail at parse
+# time naming the valid keys. Without it `--platform windows-vs2019` reaches
+# generate_configurations, and `apply_boost_defaults` and the upload remote have
+# already been decided against a value that matches nothing.
+parser.add_argument("--platform", default=None, choices=sorted(packager.configurations),
+                    help="Matrix to build. Default: detect from the running machine.")
 parser.add_argument("--python-only", help="Only build the Python (pybind) configuration", action="store_true")
 parser.add_argument("--wheel-dir", help="Extract pre-built wheel from pybind package to this directory")
 parser.add_argument("--skip-dependency-libs", action="store_true",
diff --git a/xmsconan/package_tools/packager.py b/xmsconan/package_tools/packager.py
index 8876459..b008de3 100644
--- a/xmsconan/package_tools/packager.py
+++ b/xmsconan/package_tools/packager.py
@@ -109,10 +109,13 @@ class ProfilePlan(NamedTuple):
         'compiler.version': ['194'],
         'compiler.runtime': ['dynamic', 'static'],
     },
-    # Visual Studio 2019 (msvc 192). GitHub retired the `windows-2019`
-    # runner image, so this matrix is built manually on a developer
-    # workstation and published to the `aquaveo-vs2019` remote rather than
-    # to `aquaveo` (see XmsConanPackager.upload's `remote` argument).
+    # Visual Studio 2019 (msvc 192). Published to the `aquaveo-vs2019` remote
+    # rather than to `aquaveo` (see XmsConanPackager.upload's `remote`
+    # argument), so the two toolchains never mix. Built either on a developer
+    # workstation (xmsconan.build_tools.vs2019_build) or, where a repository
+    # sets `[ci].windows_vs2019`, by the GitLab jobs that pass
+    # `build.py --platform windows_vs2019`. GitHub cannot build it: it retired
+    # the `windows-2019` runner image.
     # Identical to 'windows' apart from the compiler version.
     'windows_vs2019': {
         'os': ['Windows'],