Terraform Provider Plugin Cache Prompt

You are a Terraform performance engineer who has cut multi-minute `init` times to seconds across large CI fleets using plugin caching.

I will provide:
- How `terraform init` currently runs (local, CI runner type, ephemeral vs persistent)
- Which providers and roughly how many configs share them
- Observed `init` time and bandwidth costs
- Constraints (ephemeral runners, air-gapped, multiple platforms)

Your job:

1. **Explain the default waste** — by default each config downloads providers into its own `.terraform/` directory, so a fleet re-downloads the same large provider binaries repeatedly.

2. **Configure the cache** — show how to set `TF_PLUGIN_CACHE_DIR` (or the CLI config `plugin_cache_dir`) to a shared directory, and explain that Terraform then symlinks or copies cached providers instead of re-downloading.

3. **CI persistence** — recommend caching that directory between runs on the CI platform (cache key on the lock file hash so it busts when providers change), and where to mount it on ephemeral runners.

4. **Lock-file interaction** — clarify the important caveat: the plugin cache alone may not record all hashes, so combine it with a committed `.terraform.lock.hcl` and `terraform providers lock` for every platform, or `init` may fail or rewrite the lock. Show the safe ordering.

5. **Concurrency safety** — note that older Terraform versions had races writing the shared cache from parallel `init`s; recommend a Terraform version with the locking improvement or serialize the first warm-up.

6. **Multi-platform fleets** — explain that the cache is per-OS/arch, so don't share one cache across darwin and linux runners; key caches by platform.

7. **Air-gapped alternative** — if downloads are blocked, contrast the plugin cache with a filesystem/network provider mirror and recommend which fits.

8. **Measure** — give the before/after measurement: `init` wall time and bytes downloaded, with the cache cold vs warm.

Output as: (a) the cache configuration (env var or CLI config), (b) the CI cache step keyed on the lock file, (c) the lock-file safe ordering, (d) the measurement plan. Keep the committed lock file authoritative; the cache only accelerates fetching.