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.

src/ci_orchestrator/commands/job.py

@@ -326,6 +326,14 @@ def _destroy_clone(
     help="In-guest git clone (default) vs host-side clone + zip transfer.",
 )
 @click.option("--use-shared-cache", "use_shared_cache", is_flag=True, default=False)
+@click.option(
+    "--cargo-cache/--no-cargo-cache",
+    "cargo_cache",
+    default=True,
+    show_default=True,
+    help="Reuse compiled Rust dependency artifacts between jobs (Linux only; "
+    "engages only when the workspace has a Cargo.lock).",
+)
 @click.option("--skip-artifact", "skip_artifact", is_flag=True, default=False)
 @click.option(
     "--xvfb",
@@ -409,6 +417,7 @@ def job(
     submodules: bool,
     use_git_clone: bool,
     use_shared_cache: bool,
+    cargo_cache: bool,
     skip_artifact: bool,
     use_xvfb: bool,
     gitea_credential_target: str,
@@ -634,6 +643,11 @@ def job(
                     extra_env=extra_env,
                     skip_artifact=skip_artifact,
                     use_xvfb=use_xvfb,
+                    cargo_cache_root=(
+                        config.cargo_cache.root
+                        if cargo_cache and config.cargo_cache.enabled
+                        else None
+                    ),
                 )
             else:
                 _windows_build(

src/ci_orchestrator/config.py

@@ -65,6 +65,19 @@ class BackendConfig:
     options: dict[str, Any] = field(default_factory=dict)
 
 
+@dataclass(frozen=True)
+class CargoCacheConfig:
+    """Where compiled Rust dependency artifacts are filed between jobs.
+
+    ``root`` defaults to ``<paths.root>/cache/cargo``; it is resolved in
+    :func:`load_config` because it depends on the resolved paths.
+    """
+
+    enabled: bool = True
+    root: Path = Path("/var/lib/ci/cache/cargo")
+    retention_days: int = 30
+
+
 @dataclass(frozen=True)
 class Config:
     """Top-level configuration object."""
@@ -75,6 +88,7 @@ class Config:
     ssh_key_path: Path | None = None
     guest_cred_target: str = "BuildVMGuest"
     ip_pool: IpPoolConfig | None = None
+    cargo_cache: CargoCacheConfig = field(default_factory=CargoCacheConfig)
 
 
 def _platform_defaults() -> Paths:
@@ -158,6 +172,7 @@ def load_config(
     ssh_key_path = Path(env["CI_SSH_KEY_PATH"]) if env.get("CI_SSH_KEY_PATH") else None
     guest_cred_target = env.get("CI_GUEST_CRED_TARGET", "BuildVMGuest")
     ip_pool: IpPoolConfig | None = None
+    cargo_cache_section: dict[str, Any] = {}
 
     if toml_path and toml_path.is_file():
         data = _load_toml(toml_path)
@@ -187,9 +202,18 @@ def load_config(
                     gateway=str(pool_section.get("gateway", "")),
                     lease_file=Path(pool_section.get("lease_file") or _lease_default),
                 )
+        cargo_cache_section = data.get("cargo_cache", {}) or {}
 
     paths = _apply_env(paths, env)
 
+    # Resolved after _apply_env so CI_ROOT relocates the store with everything
+    # else; an explicit root in the file still wins.
+    cargo_cache = CargoCacheConfig(
+        enabled=bool(cargo_cache_section.get("enabled", True)),
+        root=Path(cargo_cache_section.get("root") or paths.root / "cache" / "cargo"),
+        retention_days=int(cargo_cache_section.get("retention_days", 30)),
+    )
+
     return Config(
         paths=paths,
         backend=backend,
@@ -197,7 +221,15 @@ def load_config(
         ssh_key_path=ssh_key_path,
         guest_cred_target=guest_cred_target,
         ip_pool=ip_pool,
+        cargo_cache=cargo_cache,
     )
 
 
-__all__ = ["BackendConfig", "Config", "IpPoolConfig", "Paths", "load_config"]
+__all__ = [
+    "BackendConfig",
+    "CargoCacheConfig",
+    "Config",
+    "IpPoolConfig",
+    "Paths",
+    "load_config",
+]