feat(cache): --cargo-cache flag and [cargo_cache] config section

Default on, because the cache is safe by construction rather than by
convention: it engages only where a Cargo.lock exists, and refuses to publish
anything the prune assertion cannot vouch for. Two independent off switches --
the flag for one job, `enabled = false` for the host.

The store root is resolved after the environment overrides are applied, so
CI_ROOT relocates it along with everything else, while an explicit root in the
config still wins. Both directions are covered by tests.

Also asserts that the Windows branch never receives the argument at all: the
cache is Linux-only and the two branches stay separate, per AGENTS.md.

tests/python/test_commands_job.py

@@ -1630,3 +1630,96 @@ def test_probe_transport_ssh_not_ready_returns_false(
         ssh_known_hosts=None,
     )
     assert result is False
+
+
+# ── cargo cache plumbing ─────────────────────────────────────────────────────
+
+
+def test_job_passes_cache_root_to_linux_build(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, template_vmx: Path
+) -> None:
+    backend = _FakeBackend(running_after=1)
+    calls = _patch_common(monkeypatch, backend)
+    result = CliRunner().invoke(
+        cli,
+        _common_args(
+            template_vmx,
+            clone_base=tmp_path / "build-vms",
+            artifact_base=tmp_path / "artifacts",
+        ),
+    )
+    assert result.exit_code == 0, result.output
+    assert calls["linux_build"][0]["cargo_cache_root"] is not None
+
+
+def test_job_no_cargo_cache_disables_it(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, template_vmx: Path
+) -> None:
+    backend = _FakeBackend(running_after=1)
+    calls = _patch_common(monkeypatch, backend)
+    result = CliRunner().invoke(
+        cli,
+        _common_args(
+            template_vmx,
+            clone_base=tmp_path / "build-vms",
+            artifact_base=tmp_path / "artifacts",
+            extra=["--no-cargo-cache"],
+        ),
+    )
+    assert result.exit_code == 0, result.output
+    assert calls["linux_build"][0]["cargo_cache_root"] is None
+
+
+def test_job_respects_config_disabling_the_cache(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, template_vmx: Path
+) -> None:
+    """`enabled = false` in the config wins even without --no-cargo-cache."""
+    from ci_orchestrator.config import CargoCacheConfig, Config
+
+    backend = _FakeBackend(running_after=1)
+    calls = _patch_common(monkeypatch, backend)
+    # _patch_common already replaced load_config, so override its return value
+    # rather than the environment.
+    base = job_module.load_config()
+    patched = Config(
+        paths=base.paths,
+        backend=base.backend,
+        vmrun_path=base.vmrun_path,
+        ssh_key_path=base.ssh_key_path,
+        guest_cred_target=base.guest_cred_target,
+        ip_pool=base.ip_pool,
+        cargo_cache=CargoCacheConfig(enabled=False),
+    )
+    monkeypatch.setattr(job_module, "load_config", lambda: patched)
+    result = CliRunner().invoke(
+        cli,
+        _common_args(
+            template_vmx,
+            clone_base=tmp_path / "build-vms",
+            artifact_base=tmp_path / "artifacts",
+        ),
+    )
+    assert result.exit_code == 0, result.output
+    assert calls["linux_build"][0]["cargo_cache_root"] is None
+
+
+def test_job_windows_build_gets_no_cargo_cache_argument(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    """The Windows branch must be untouched by the Linux-only cache."""
+    # Guest OS comes from the *clone* VMX, which the fake backend writes.
+    backend = _FakeBackend(running_after=1, clone_guest_os="windows2019srvNext-64")
+    calls = _patch_common(monkeypatch, backend)
+    vmx = tmp_path / "templates" / "WinBuild2025.vmx"
+    vmx.parent.mkdir(parents=True)
+    vmx.write_text('guestOS = "windows2019srvNext-64"\n', encoding="utf-8")
+    result = CliRunner().invoke(
+        cli,
+        _common_args(
+            vmx,
+            clone_base=tmp_path / "build-vms",
+            artifact_base=tmp_path / "artifacts",
+        ),
+    )
+    assert result.exit_code == 0, result.output
+    assert "cargo_cache_root" not in calls["windows_build"][0]