diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 73312467..54a6763c 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -10,6 +10,11 @@ on:
     branches:
       - main
   workflow_dispatch:
+    inputs:
+      registry_cache_test:
+        description: 'Also verify authenticated GHCR cache reuse (synthetic data only)'
+        type: boolean
+        default: false
 
 permissions:
   contents: read
@@ -33,3 +38,35 @@ jobs:
 
       - name: Lint generated GitLab Runner configuration
         run: bash tests/gitlab-runner-lint.sh
+
+      - name: Verify shared build cache with isolated builders
+        run: bash tests/build-cache-integration.sh
+
+  registry-cache:
+    name: Authenticated registry cache proof
+    if: github.event_name == 'workflow_dispatch' && inputs.registry_cache_test && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout trusted dispatch ref
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Verify cache export and import with job-owned credentials
+        shell: bash
+        env:
+          REGISTRY_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          export DOCKER_CONFIG
+          DOCKER_CONFIG="$(mktemp -d "$RUNNER_TEMP/crf-registry-auth.XXXXXX")"
+          trap 'rm -rf -- "$DOCKER_CONFIG"' EXIT
+          printf '%s' "$REGISTRY_TOKEN" | docker login ghcr.io -u "$GITHUB_ACTOR" --password-stdin
+          unset REGISTRY_TOKEN
+          export CRF_CACHE_TEST_REPOSITORY="ghcr.io/${GITHUB_REPOSITORY,,}-build-cache"
+          export CRF_CACHE_TEST_TAG="proof-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+          bash tests/build-cache-integration.sh
diff --git a/.limetech/ai-review-markers/feat-shared-build-cache-8c24ca91be08.json b/.limetech/ai-review-markers/feat-shared-build-cache-8c24ca91be08.json
new file mode 100644
index 00000000..c8672c06
--- /dev/null
+++ b/.limetech/ai-review-markers/feat-shared-build-cache-8c24ca91be08.json
@@ -0,0 +1,8 @@
+{
+  "disposition": "PATCH",
+  "forecast_commit": "c214cf26f7868ce28f4f7db38bb9993264e3f764",
+  "reviewed_sha": "8b5ad92f18df6276a0dc4562f6cfbd033259f5cb",
+  "schema": "limetech.ai-review-marker.v2",
+  "stage": "final",
+  "unresolved_proportionality_findings": []
+}
diff --git a/.mega-linter.yml b/.mega-linter.yml
index 390f156e..fa450c18 100644
--- a/.mega-linter.yml
+++ b/.mega-linter.yml
@@ -70,3 +70,10 @@ FILTER_REGEX_EXCLUDE: (^LICENSE$|^CHANGELOG\.md$|\.git/|megalinter-reports/)
 # uses .json with comments rather than .jsonc), so allow comments/trailing
 # commas for all JSON rather than relying on file extension.
 JSON_JSONLINT_ARGUMENTS: "--comments --trailing-newline --trailing-commas"
+
+# The shipped README needs public URLs, but new docs do not exist on main
+# before a PR merges. Validate this repository's main-file links against the
+# candidate checkout inside MegaLinter. Missing local targets still fail.
+SPELL_LYCHEE_ARGUMENTS:
+  - --remap
+  - '^https[:]//github[.]com/unraid/ci-runner-farm/blob/main/ file:///github/workspace/'
diff --git a/README.md b/README.md
index 5274d7c1..1130975e 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,8 @@ provider's credentials and runtime.
 | Concurrent runner slots | Each slot accepts one job at a time and can have CPU and memory limits, keeping CI from starving the rest of the host. |
 | GitHub and GitLab providers | Keep the existing GitHub Actions integration or select GitLab.com/self-managed GitLab. |
 | Warm shared caches | Reuse npm, yarn, pnpm, Playwright, Cargo, sccache, or custom cache directories across jobs. |
+| Optional registry build-cache profile | Supply explicit CI workflows with an existing registry cache location and a smaller per-builder GC budget. No new server or shared Docker data root. See the [setup guide](docs/build-cache.md). |
+| Cache-preserving Stop and Restart | Keep per-slot Docker and GitLab job caches across maintenance. Explicit `prune-cache` deletes retained caches. Permanent slot retirement still deletes that slot's data. See [cache retention](docs/build-cache.md#keep-caches-across-stop-and-restart). |
 | Slot-scoped Docker-in-Docker | Give each runner slot a private privileged Docker daemon without exposing Unraid's existing Docker socket by default; privileged DinD is still capable of host compromise. |
 | Bring your own job image | Pull a remote image or edit and build a provider-specific starter image in the plugin. |
 | Named runner pools | Route jobs to purpose-built pools with independent fixed capacity, labels/tags, CPU, memory, and images. |
diff --git a/docs/build-cache.md b/docs/build-cache.md
new file mode 100644
index 00000000..7a7c5d06
--- /dev/null
+++ b/docs/build-cache.md
@@ -0,0 +1,188 @@
+# Share build caches through an existing registry
+
+The optional **Build cache profile** lets CI jobs reuse exported Docker build
+layers across runners. Each slot keeps its own Docker daemon and writable data.
+The plugin supplies configuration, not a registry server or registry credentials.
+The existing pull-through image mirror remains separate and cannot accept cache
+exports.
+
+## Configure the farm
+
+1. Open **Settings → CI Runner Farm → Settings → Build cache profile**.
+2. Select **Existing registry (workflow opt-in)**.
+3. Enter a tagless repository, such as `registry.example.com/team/build-cache`.
+4. Set **Local cache budget per builder (GiB)**. The default is 20 GiB.
+5. Apply the settings. In classic mode, wait for runners to finish their jobs and adopt the new profile.
+6. For named pools, schedule a **Fleet Restart** after active jobs finish. Apply alone does not replace those runners.
+7. Wait for the replacement runners before updating build workflows as described below.
+
+The configuration keys are `BUILD_CACHE_MODE` (`off` or `registry`),
+`BUILD_CACHE_REPOSITORY`, and `BUILD_CACHE_LOCAL_GIB` (1–1024).
+Off preserves existing behavior, including runner configuration fingerprints.
+Registry mode requires Docker-in-Docker. Host-socket mode is not supported.
+
+Each GitHub runner and GitLab Docker-executor job receives two read-only files:
+
+- `/etc/ci-runner-farm/build-cache/profile.env`: the repository and config path.
+- `/etc/ci-runner-farm/build-cache/buildkitd.toml`: the OCI worker's GC budget.
+
+Profiles are immutable snapshots. Changes do not rewrite files mounted by busy
+jobs. Old snapshots remain in the plugin's runtime directory until reboot.
+The current snapshot is generated again during runner provisioning.
+
+## Use the profile in a workflow
+
+Use a current Buildx client and BuildKit version that supports `maxUsedSpace`.
+This profile targets the OCI worker in a `docker-container` builder. It does not
+configure arbitrary existing builders, remote builders, or `docker build` calls.
+GitLab job images must include the Docker CLI and Buildx plugin.
+
+Authenticate to the cache registry inside the job, using a credential with only
+the required repository permissions. The plugin does not expose its host PAT,
+runner token, or image-pull credentials through this profile. Configure private
+CA trust in the job/builder when required. The profile does not disable TLS or
+relax the farm's network firewall. A registry blocked by strict isolation remains
+blocked.
+
+This shell example works in a GitHub shell job or GitLab job. Set
+`CACHE_SCOPE` from a stable hash of the full project, build target, platform, and
+branch identity. Use the same scope on different runners to reuse their cache.
+Keep output image references separate from cache references.
+
+```bash
+set -euo pipefail
+. /etc/ci-runner-farm/build-cache/profile.env
+: "${CACHE_SCOPE:?Set a project/target/platform/branch-specific cache scope}"
+[[ "$CACHE_SCOPE" =~ ^[a-z0-9][a-z0-9_.-]{0,100}$ ]] || exit 1
+cache_ref="${CRF_BUILD_CACHE_REPOSITORY}:${CACHE_SCOPE}"
+builder="crf-$(cat /proc/sys/kernel/random/uuid)"
+docker buildx create --name "$builder" --driver docker-container \
+  --buildkitd-config "$CRF_BUILDKIT_CONFIG" --bootstrap
+trap 'docker buildx rm "$builder"' EXIT
+docker buildx build --builder "$builder" \
+  --cache-from "type=registry,ref=$cache_ref" \
+  --cache-to "type=registry,ref=$cache_ref,mode=max,image-manifest=true" \
+  --load -t example/app:ci .
+```
+
+The example removes only its own builder after the job. Registry cache survives
+that cleanup. A workflow may retain its own builder instead, but it must recreate
+that builder when the profile changes so the new GC budget takes effect.
+GitHub jobs using `container:` must also mount the profile directory read-only
+into their job container. Shell jobs receive it directly.
+
+For GitHub's Docker actions, load `profile.env` in a shell step and write the
+needed values to `$GITHUB_OUTPUT`. Pass the config path to
+`docker/setup-buildx-action` as `buildkitd-config`. Pass explicitly scoped refs to
+`docker/build-push-action` as `cache-from` and `cache-to`. Do not assume that the
+runner's environment automatically appears in GitHub's expression `env` context.
+See Docker's [builder configuration](https://docs.docker.com/build/ci/github-actions/configure-builder/)
+and [registry cache examples](https://docs.docker.com/build/ci/github-actions/cache/).
+
+## Scope, failure, and storage limits
+
+Cache names are not an access-control boundary. Only trusted jobs should share
+a writable cache repository. Separate projects and trust levels with registry
+permissions and separate repositories. Never give untrusted pull requests a
+credential that can overwrite trusted caches. Branch-specific tags avoid normal
+collisions but do not stop a credential holder from choosing another tag.
+Serialize exports to the same ref, or use separate refs for concurrent writers.
+Use BuildKit secret mounts for secrets; never bake credentials into layers.
+
+The profile provides no implicit `latest` cache tag. A missing import cache is a
+normal cold build under Docker's behavior. Export failures remain job failures
+unless the workflow deliberately changes Docker's default error handling. Do not
+add `ignore-error=true` or fall back to an unconfigured builder to hide failures.
+
+The local budget is a garbage-collection target, not a hard quota. Active build
+data can exceed it. It does not cover Docker images, other builders, workspaces,
+package caches, or the image mirror. Exported caches also need registry retention
+and garbage collection, controlled by the registry owner. Reducing local budgets
+trades disk use for cache downloads and depends on registry availability.
+
+Enabling this option does not prune old builders or immediately recover their
+disk space. Migrate workflows first, then retire unused builders through their
+normal owner. Remove workflow references to the profile before disabling the
+option. Classic fleets remove the mount as runners drain and are replaced.
+Named pools require the same scheduled Fleet Restart described above.
+
+## Keep caches across Stop and Restart
+
+**Stop** and **Restart** retain per-slot Docker data, GitLab job caches, and the
+shared image mirror cache. A later Start reuses the retained data for the same
+slot and cache root. This applies with the build cache profile on or off.
+The plugin records the provider and baked runner configuration identity for each
+retained slot. If that identity changes, including a provider, owner, project,
+registry, or trust-scope change, the plugin purges that slot's retained Docker,
+workspace, job-cache, socket, and log data before starting it again. The shared
+image mirror remains separate and is not treated as per-slot job state.
+The plugin still removes runner containers and performs provider credential
+cleanup. Plugin uninstall and active GitLab runner-token removal also retain
+caches because they use Stop.
+
+Stop does not guarantee that active jobs finish. Schedule maintenance before
+using Stop or Restart. Manual scale-down, autoscale-down, and permanent slot
+retirement still delete that slot's Docker data and GitLab job cache. Registry
+exports are unaffected.
+
+To delete retained local caches, stop the fleet, then run the explicit command:
+
+```bash
+/usr/local/emhttp/plugins/ci-runner-farm/include/runner-farm.sh prune-cache
+```
+
+This command deletes plugin-owned cache directories under the configured cache
+root. It refuses to proceed while managed runners, sidecars, or job containers
+remain. Cache retention does not reduce existing disk use.
+
+## Verification
+
+`bash tests/build-cache.sh` checks profile validation, snapshots, fingerprints,
+and both providers' mount contracts without external services.
+`bash tests/cache-retention.sh` checks Stop/Restart retention and explicit cache
+deletion for both providers using disposable on-disk fixtures.
+`bash tests/build-cache-integration.sh` uses disposable local Docker builders and
+a test registry to prove cross-builder cache reuse and effective GC settings.
+It does not contact a farm host or modify existing runners.
+
+### Verify an authenticated registry
+
+The **Lint** workflow has a manual **Also verify authenticated GHCR cache reuse**
+option. The package-writing job accepts dispatches only from the repository's
+`main` branch. Pull-request events and other refs cannot start it. Review the
+exact `main` commit before dispatching. GitHub assigns its runner.
+
+The job uses its short-lived `GITHUB_TOKEN` with `packages: write`, not a farm
+credential. It exports synthetic Busybox layers to
+`ghcr.io/<owner>/<repository>-build-cache:proof-<run-id>-<attempt>`.
+Two fresh builders must have different local volumes, and the second must reuse
+the exported `RUN` layer. Authentication or export errors fail the test.
+The test never substitutes a local registry when the external registry fails.
+
+Inspect the package's actual visibility, repository link, and workflow access
+after the run. Do not assume that it is private. This repository's initial
+synthetic proof produced a public package. Never use a public proof repository
+for private build caches. A private production cache needs its own authorized
+repository and access policy before the farm points to it.
+
+The job removes its temporary Docker credentials and local test resources. It
+leaves the small proof tag for inspection; the package owner controls retention.
+A successful proof against a public package establishes authenticated exports
+and cache reuse, but does not establish private-package read authorization.
+
+For another registry, authenticate through a temporary, job-owned Docker config.
+Set `CRF_CACHE_TEST_REPOSITORY` to its tagless repository and
+`CRF_CACHE_TEST_TAG` to a unique tag starting with `proof-`. Then run
+`bash tests/build-cache-integration.sh`. Both inputs are required together.
+Do not use the farm's host PAT, runner token, or image-pull credential.
+
+This check uses the plugin's generated profile in an isolated fixture. It does
+not prove that a deployed runner has adopted its profile or that a production
+workflow uses it. Verify the deployed read-only mount separately, then configure
+each authorized build workflow as described above. Enabling the farm option
+alone does not change existing build commands or reduce their old cache data.
+
+On macOS, use `bash tests/run-linux-checks.sh` with Docker running and Homebrew
+Coreutils installed (`brew install coreutils`). The wrapper runs the shell suite
+in Linux. Its real-Docker integration stage uses the installed GNU tools on the
+host because the production snapshot generator requires GNU `mv -T`.
diff --git a/src/usr/local/emhttp/plugins/ci-runner-farm/README.md b/src/usr/local/emhttp/plugins/ci-runner-farm/README.md
index 686c9df5..9e019edf 100644
--- a/src/usr/local/emhttp/plugins/ci-runner-farm/README.md
+++ b/src/usr/local/emhttp/plugins/ci-runner-farm/README.md
@@ -5,6 +5,12 @@ resource-capped slots, warm package/image caches, Docker-in-Docker, and optional
 autoscaling. One provider owns the farm at a time; GitHub remains the default so
 existing installations keep their behavior.
 
+The optional **Build cache profile** supplies an existing registry cache location
+and a per-builder garbage-collection budget (20 GiB by default). It is off by
+default and requires Docker-in-Docker plus explicit workflow integration.
+It creates no registry server, shares no writable Docker root, and passes no
+host credentials to jobs. See the [build-cache setup guide](https://github.com/unraid/ci-runner-farm/blob/main/docs/build-cache.md).
+
 Named pools work with both providers. Each pool can use its own fixed capacity,
 labels or tags, CPU, memory, and runner/job image. GitHub pools require
 organization scope. GitLab pools require a pool-specific `glrt-` runner token
diff --git a/src/usr/local/emhttp/plugins/ci-runner-farm/RunnerFarmSettings.page b/src/usr/local/emhttp/plugins/ci-runner-farm/RunnerFarmSettings.page
index 47b8678e..60c85aa3 100644
--- a/src/usr/local/emhttp/plugins/ci-runner-farm/RunnerFarmSettings.page
+++ b/src/usr/local/emhttp/plugins/ci-runner-farm/RunnerFarmSettings.page
@@ -35,6 +35,7 @@ $defaults = [
   'CACHE_ROOT'=>'/mnt/cache/github-runner', 'WORK_TMPFS_SIZE'=>'8g',
   'CACHE_MOUNTS'=>'pnpm-store:/home/runner/.local/share/pnpm/store npm:/home/runner/.npm yarn:/home/runner/.cache/yarn ms-playwright:/home/runner/.cache/ms-playwright',
   'DIND'=>'true', 'SHARE_DOCKER_SOCK'=>'false', 'SHARED_IMAGE_CACHE'=>'true', 'NETWORK_ISOLATION'=>'off',
+  'BUILD_CACHE_MODE'=>'off', 'BUILD_CACHE_REPOSITORY'=>'', 'BUILD_CACHE_LOCAL_GIB'=>'20',
   'IMAGE_AUTOUPDATE'=>'false', 'IMAGE_AUTOUPDATE_INTERVAL'=>'1800', 'IMAGE_DRAIN_TIMEOUT'=>'3600',
   'DASHBOARD_WIDGET_ENABLE'=>'true',
   'AUTOSCALE'=>'false', 'AUTOSCALE_MIN'=>'2', 'AUTOSCALE_MAX'=>'16', 'AUTOSCALE_MIN_IDLE'=>'2',
@@ -429,6 +430,34 @@ _(Shared image cache)_:
 > Runs a shared `registry:2` pull-through cache (Docker-in-Docker only) so images used across the fleet are pulled from Docker Hub once, not once per runner. Bound to the Docker bridge gateway, not the LAN — so it is not exposed off the host, though (being on the bridge gateway) it is reachable unauthenticated by any container on the default Docker bridge, not only this plugin's runners. It only caches public Docker Hub images. Turn off if you don't want the extra container. The host port defaults to 5000; if that clashes with another service, set `MIRROR_PORT` in `/boot/config/plugins/ci-runner-farm/ci-runner-farm.cfg` and Restart the fleet.
 :end
 
+### Build cache profile
+
+_(Shared build cache)_:
+: <select name="BUILD_CACHE_MODE" aria-label="Shared build cache" onchange="crfBuildCacheChange()">
+  <option value="off" <?=crf_sel($cfg,'BUILD_CACHE_MODE','off','off')?>>Off (existing behavior)</option>
+  <option value="registry" <?=crf_sel($cfg,'BUILD_CACHE_MODE','registry','off')?>>Existing registry (workflow opt-in)</option>
+  </select>
+
+:crf_build_cache_mode_plug:
+> Requires Docker-in-Docker and an existing writable registry. No registry server is created.
+:end
+
+_(Cache repository)_:
+: <input type="text" name="BUILD_CACHE_REPOSITORY" aria-label="Cache repository" maxlength="255" placeholder="registry.example.com/team/build-cache" value="<?=crf_g($cfg,'BUILD_CACHE_REPOSITORY','')?>">
+
+:crf_build_cache_repository_plug:
+> Enter a repository without a URL scheme, tag, digest, or credentials. Workflows must load `/etc/ci-runner-farm/build-cache/profile.env`, configure a `docker-container` builder with its BuildKit configuration, and explicitly import/export scoped cache references. Jobs supply their own registry credentials. See the [build-cache setup guide](https://github.com/unraid/ci-runner-farm/blob/main/docs/build-cache.md).
+:end
+
+_(Local cache budget per builder (GiB))_:
+: <input type="number" name="BUILD_CACHE_LOCAL_GIB" aria-label="Local cache budget per builder (GiB)" min="1" max="1024" step="1" value="<?=crf_g($cfg,'BUILD_CACHE_LOCAL_GIB','20')?>">
+
+:crf_build_cache_plug:
+> The budget controls BuildKit garbage collection, not total disk use or a hard quota. Other builders and active builds can exceed it. In classic mode, Apply updates runners after active jobs finish. Named pools require an explicit Fleet Restart. Wait for the new runners before using the profile in workflows. Existing caches are not pruned.
+:end
+
+### Network isolation
+
 _(Network isolation)_:
 : <select name="NETWORK_ISOLATION">
   <option value="off" <?=crf_sel($cfg,'NETWORK_ISOLATION','off','off')?>>off (default docker bridge)</option>
@@ -557,7 +586,7 @@ const CRF_DEFAULTS = <?=crf_json($defaults)?>;
 // nothing is written to flash until the user clicks Apply.
 function crfResetDefaults(){
   for (const k in CRF_DEFAULTS){ const el=document.getElementsByName(k)[0]; if(el) el.value=CRF_DEFAULTS[k]; }
-  crfProviderChange(); crfImgSrc();
+  crfProviderChange(); crfImgSrc(); crfBuildCacheChange();
   // programmatic .value changes fire no input event, so nudge the advisory
   // listeners (Min>Max, memory envelope) to re-evaluate against the reset values.
   ['AUTOSCALE_MIN','AUTOSCALE_MAX','RUNNER_MEMORY','RUNNER_COUNT','AUTOSCALE'].forEach(n=>{ const el=document.getElementsByName(n)[0]; if(el) el.dispatchEvent(new Event('input')); });
@@ -569,6 +598,13 @@ function crfTokState(ok){
   band.classList.toggle('crfs-tokband-missing',!ok);
   ball.className='crf-ball '+(ok?'crf-ball-idle':'crf-ball-error');
 }
+function crfBuildCacheChange(){
+  const enabled=document.getElementsByName('BUILD_CACHE_MODE')[0].value==='registry';
+  ['BUILD_CACHE_REPOSITORY','BUILD_CACHE_LOCAL_GIB'].forEach(name=>{
+    document.getElementsByName(name)[0].required=enabled;
+  });
+}
+crfBuildCacheChange();
 function crfCredentialOk(o,label){
   if(o&&o.ok===true)return true;
   crfToast(label+': '+((o&&o.error)||'operation failed')); return false;
diff --git a/src/usr/local/emhttp/plugins/ci-runner-farm/default.cfg b/src/usr/local/emhttp/plugins/ci-runner-farm/default.cfg
index dc3e65e5..4971175e 100644
--- a/src/usr/local/emhttp/plugins/ci-runner-farm/default.cfg
+++ b/src/usr/local/emhttp/plugins/ci-runner-farm/default.cfg
@@ -48,6 +48,9 @@ CACHE_MOUNTS="pnpm-store:/home/runner/.local/share/pnpm/store npm:/home/runner/.
 SHARE_DOCKER_SOCK="false"
 DIND="true"
 SHARED_IMAGE_CACHE="true"
+BUILD_CACHE_MODE="off"
+BUILD_CACHE_REPOSITORY=""
+BUILD_CACHE_LOCAL_GIB="20"
 NETWORK_ISOLATION="off"
 RUNNER_NETWORK="ci-runner-net"
 MIRROR_PORT="5000"
diff --git a/src/usr/local/emhttp/plugins/ci-runner-farm/include/providers/github.sh b/src/usr/local/emhttp/plugins/ci-runner-farm/include/providers/github.sh
old mode 100644
new mode 100755
index cb987898..1f5a3ae6
--- a/src/usr/local/emhttp/plugins/ci-runner-farm/include/providers/github.sh
+++ b/src/usr/local/emhttp/plugins/ci-runner-farm/include/providers/github.sh
@@ -454,7 +454,9 @@ github_registry_credentials() {
 
 github_build_args() {
   local idx="$1"
-  local name="${2:-${NAME_PREFIX}-${idx}}" role="${CRF_CONTAINER_ROLE:-runner}" host_service_ip image
+  local build_profile image
+  build_profile="$(build_cache_profile)" || return 1
+  local name="${2:-${NAME_PREFIX}-${idx}}" role="${CRF_CONTAINER_ROLE:-runner}" host_service_ip
   image="$(effective_image)" || return 1
   host_service_ip="$(runner_host_service_ipv4)" \
     || { err "could not resolve this farm host's local service address"; return 1; }
@@ -487,6 +489,7 @@ github_build_args() {
     hostdir="$(crf_safe_mount_subdir "${m%%:*}")" || { err "skipping unsafe cache mount '${m%%:*}'"; continue; }
     ARGS+=( -v "$hostdir:${m#*:}" )
   done
+  [ -z "$build_profile" ] || ARGS+=( -v "$build_profile:/etc/ci-runner-farm/build-cache:ro" )
   [ -n "$RUNNER_CPUS" ]   && ARGS+=( --cpus="$RUNNER_CPUS" )
   [ -n "$RUNNER_MEMORY" ] && ARGS+=( --memory="$RUNNER_MEMORY" )
   [ "$NETWORK_ISOLATION" != "off" ] && ARGS+=( --network "$RUNNER_NETWORK" )
diff --git a/src/usr/local/emhttp/plugins/ci-runner-farm/include/providers/gitlab.sh b/src/usr/local/emhttp/plugins/ci-runner-farm/include/providers/gitlab.sh
old mode 100644
new mode 100755
index 58af479a..76320787
--- a/src/usr/local/emhttp/plugins/ci-runner-farm/include/providers/gitlab.sh
+++ b/src/usr/local/emhttp/plugins/ci-runner-farm/include/providers/gitlab.sh
@@ -719,6 +719,8 @@ gitlab_registry_authority() {
 
 gitlab_write_config() {
   local idx="$1" name="$2" dir tmp url token job_image socket_source executor_host pull_policy slot_ca
+  local build_profile
+  build_profile="$(build_cache_profile)" || return 1
   dir="$(gitlab_slot_config_dir "$name")"; tmp="$dir/config.toml.tmp"
   slot_ca="$dir/certs/gitlab-ca.crt"
   url="$(gitlab_url)"; token="$GITLAB_RUNNER_TOKEN"; job_image="$(effective_image)"
@@ -737,6 +739,7 @@ gitlab_write_config() {
   local vols=() m hostdir dest i
   mkdir -p "$CACHE_ROOT/gitlab-cache/$name" || return 1
   vols+=( "$socket_source:/var/run/docker.sock" "$CACHE_ROOT/gitlab-cache/$name:/cache" )
+  [ -z "$build_profile" ] || vols+=( "$build_profile:/etc/ci-runner-farm/build-cache:ro" )
   # The helper image automatically installs a CA mounted at this documented
   # path. User-selected job images receive the file too, but must install or
   # explicitly use it themselves because their CA tooling is image-specific.
@@ -851,6 +854,8 @@ gitlab_build_args() { gitlab_build_manager_args "$@"; }
 
 gitlab_start_sidecar() {
   local idx="$1" name="$2" side sockdir sock data m hostdir registry_authority slot_ca
+  local build_profile
+  build_profile="$(build_cache_profile)" || return 1
   side="$(gitlab_sidecar_name "$name")"
   if [ "$DIND" != "true" ]; then
     if docker inspect "$side" >/dev/null 2>&1; then
@@ -906,6 +911,7 @@ gitlab_start_sidecar() {
     # shared cache directories—never the whole CACHE_ROOT or sibling slots.
     -v "$CACHE_ROOT/gitlab-cache/$name:$CACHE_ROOT/gitlab-cache/$name"
   )
+  [ -z "$build_profile" ] || sargs+=( -v "$build_profile:$build_profile:ro" )
   if [ -f "$slot_ca" ]; then
     # The nested daemon resolves config.toml bind sources in its own mount
     # namespace, so mirror the host CA at the identical absolute path. Also
@@ -1129,6 +1135,9 @@ gitlab_unregister_manager() {
 # confgen, restart the same manager and system ID without remote unregister.
 gitlab_start_stopped() {
   local c="$1" idx="$2" manager_id="${3:-}" current_id job side side_id i image dir
+  # Runtime profiles disappear on reboot. Recreate the unchanged snapshot before
+  # Docker can create an empty bind directory while restarting the old sidecar.
+  build_cache_profile >/dev/null || return 1
   printf '%s' "$manager_id" | grep -qE '^[0-9a-f]{64}$' \
     || { err "refusing to restart GitLab manager $c without a valid immutable container ID"; return 1; }
   dir="$(gitlab_slot_config_dir "$c")"
diff --git a/src/usr/local/emhttp/plugins/ci-runner-farm/include/runner-farm.sh b/src/usr/local/emhttp/plugins/ci-runner-farm/include/runner-farm.sh
old mode 100644
new mode 100755
index f63a2a35..e92bf5c9
--- a/src/usr/local/emhttp/plugins/ci-runner-farm/include/runner-farm.sh
+++ b/src/usr/local/emhttp/plugins/ci-runner-farm/include/runner-farm.sh
@@ -77,6 +77,9 @@ DIND="true"                           # docker-in-docker: each runner gets its o
                                       # Fixes GitHub Actions services: networking + 'port already allocated' collisions.
 SHARED_IMAGE_CACHE="true"             # run a shared pull-through registry mirror so every DinD runner
                                       # reuses pulled images (postgres, etc.) instead of each pulling cold.
+BUILD_CACHE_MODE="off"                # off | registry; workflows explicitly consume the read-only profile
+BUILD_CACHE_REPOSITORY=""             # tagless existing registry repository; credentials stay in CI jobs
+BUILD_CACHE_LOCAL_GIB="20"            # per-builder GC budget, not a disk quota
 MIRROR_NAME="ci-runner-mirror"        # cache persists on the pool across restarts.
 MIRROR_PORT="5000"
 # ---- network isolation -----------------------------------------------------
@@ -148,7 +151,8 @@ GITLAB_ALLOWED_IMAGES GITLAB_ALLOWED_SERVICES GITLAB_PULL_POLICY GITLAB_SHM_SIZE
 RUNNER_COUNT RUNNER_LABELS RUNNER_MODE RUNNER_POOLS \
 RUNNER_CPUS RUNNER_MEMORY CACHE_ROOT WORK_TMPFS_SIZE IMAGE_SOURCE IMAGE EPHEMERAL \
 RUN_AS_ROOT REGISTRY_SERVER REGISTRY_USERNAME CACHE_MOUNTS SHARE_DOCKER_SOCK DIND \
-SHARED_IMAGE_CACHE NETWORK_ISOLATION RUNNER_NETWORK MIRROR_PORT AUTOSCALE AUTOSCALE_MIN \
+SHARED_IMAGE_CACHE BUILD_CACHE_MODE BUILD_CACHE_REPOSITORY BUILD_CACHE_LOCAL_GIB \
+NETWORK_ISOLATION RUNNER_NETWORK MIRROR_PORT AUTOSCALE AUTOSCALE_MIN \
 AUTOSCALE_MAX AUTOSCALE_MIN_IDLE AUTOSCALE_STEP AUTOSCALE_INTERVAL \
 AUTOSCALE_IDLE_GRACE IMAGE_AUTOUPDATE IMAGE_AUTOUPDATE_INTERVAL IMAGE_DRAIN_TIMEOUT \
 DASHBOARD_WIDGET_ENABLE"
@@ -351,7 +355,7 @@ managed_runner_snapshot() {
 provider_token_ready() { provider_call token_ready; }
 provider_token_name()  { provider_call token_name; }
 builtin_image()        { provider_call builtin_image; }
-provider_validate_settings() { provider_call validate_settings; }
+provider_validate_settings() { validate_build_cache && provider_call validate_settings; }
 provider_public_problem() { provider_call public_repo_problem; }
 provider_registry_credentials() { provider_call registry_credentials; }
 provider_strict_endpoint() { provider_call strict_endpoint; }
@@ -537,7 +541,12 @@ busy_count() {
 # change and migrate them onto the new config as they go idle. IMPORTANT: whenever you
 # add a setting that build_args bakes into the container, add it here too.
 crf_confgen() {
-  provider_call confgen
+  local base
+  base="$(provider_call confgen)" || return 1
+  # Do not recycle existing installations merely because this option was added.
+  if [ "$BUILD_CACHE_MODE" = off ]; then printf '%s\n' "$base"; return; fi
+  validate_build_cache || return 1
+  { printf '%s\0' "$base"; build_cache_bytes; } | sha256sum | cut -c1-12
 }
 # The config fingerprint a managed runner was created with ('' for runners created before
 # this feature existed — they read as stale and migrate on the next reconcile).
@@ -1365,6 +1374,7 @@ host_docker_pull() {
 }
 
 ensure_dirs() {
+  validate_build_cache || return 1
   mkdir -p "$CACHE_ROOT/work"
   local m dir
   for m in $CACHE_MOUNTS; do
@@ -1384,6 +1394,77 @@ ensure_dirs() {
   write_dind_config
 }
 
+# Validate before arithmetic. CFG_NUMERIC_KEYS silently retains defaults for
+# malformed input; a bad build-cache budget must instead block provisioning.
+validate_build_cache() {
+  case "$BUILD_CACHE_MODE" in
+    off) return 0 ;;
+    registry) ;;
+    *) err "BUILD_CACHE_MODE must be off or registry"; return 1 ;;
+  esac
+  [ "$DIND" = true ] || { err "Registry build-cache profiles require Docker-in-Docker"; return 1; }
+  local authority port
+  authority="${BUILD_CACHE_REPOSITORY%%/*}"
+  # No URL, credentials, tag, digest, CSV options, or executable shell syntax.
+  if [ "${#BUILD_CACHE_REPOSITORY}" -gt 255 ] \
+    || ! printf '%s\n' "$BUILD_CACHE_REPOSITORY" | LC_ALL=C grep -qE '^[a-z0-9][a-z0-9.-]*(:[0-9]{1,5})?/[a-z0-9]+([._-][a-z0-9]+)*(/[a-z0-9]+([._-][a-z0-9]+)*)*$' \
+    || [[ "$BUILD_CACHE_REPOSITORY" == *$'\n'* ]]; then
+    err "BUILD_CACHE_REPOSITORY must be a tagless registry/repository path"; return 1
+  fi
+  case "$authority" in *.*|*:*|localhost) ;; *) err "BUILD_CACHE_REPOSITORY must include a registry hostname"; return 1 ;; esac
+  case "$authority" in *:*)
+    port="${authority##*:}"
+    [ "$((10#$port))" -ge 1 ] && [ "$((10#$port))" -le 65535 ] \
+      || { err "Build-cache registry port must be 1 through 65535"; return 1; } ;;
+  esac
+  if ! [[ "$BUILD_CACHE_LOCAL_GIB" =~ ^[1-9][0-9]{0,3}$ ]] \
+    || [ "$BUILD_CACHE_LOCAL_GIB" -gt 1024 ]; then
+    err "BUILD_CACHE_LOCAL_GIB must be a whole number from 1 through 1024"; return 1
+  fi
+}
+
+build_cache_env() {
+  printf '%s\n' 'CRF_BUILD_CACHE_SCHEMA=1' 'CRF_BUILD_CACHE_MODE=registry' \
+    "CRF_BUILD_CACHE_REPOSITORY=$BUILD_CACHE_REPOSITORY" \
+    'CRF_BUILDKIT_CONFIG=/etc/ci-runner-farm/build-cache/buildkitd.toml'
+}
+
+build_cache_toml() {
+  printf '%s\n' '[worker.oci]' '  gc = true' '  reservedSpace = "0B"' \
+    "  maxUsedSpace = \"${BUILD_CACHE_LOCAL_GIB}GiB\"" '  minFreeSpace = "0B"'
+}
+
+# Hash all rendered bytes, including schema. Renderer changes must also retire
+# old runner profiles, not merely changes to the operator's settings.
+build_cache_bytes() { build_cache_env; printf '\0'; build_cache_toml; }
+
+build_cache_profile() {
+  validate_build_cache || return 1
+  [ "$BUILD_CACHE_MODE" = registry ] || return 0
+  local root="$RUNDIR/build-cache-profiles" digest dir tmp
+  digest="$(build_cache_bytes | sha256sum | cut -d' ' -f1)" || return 1
+  dir="$root/$digest"
+  [ ! -L "$root" ] && [ ! -L "$dir" ] \
+    || { err "Refusing a symlink build-cache profile path"; return 1; }
+  mkdir -p "$root" && chmod 755 "$root" || return 1
+  tmp="$(mktemp -d "$root/.profile.XXXXXX")" || return 1
+  if ! { build_cache_env > "$tmp/profile.env" && build_cache_toml > "$tmp/buildkitd.toml" \
+      && chmod 644 "$tmp/profile.env" "$tmp/buildkitd.toml" && chmod 755 "$tmp"; }; then
+    rm -f -- "$tmp/profile.env" "$tmp/buildkitd.toml"; rmdir -- "$tmp"; return 1
+  fi
+  # GNU mv -T cannot nest staging files inside a concurrent snapshot. Existing
+  # paths are verified, never replaced or repaired while a job may use them.
+  if [ -e "$dir" ] || ! mv -T -- "$tmp" "$dir" 2>/dev/null; then
+    local valid=0
+    if [ ! -L "$dir" ] && [ ! -L "$dir/profile.env" ] && [ ! -L "$dir/buildkitd.toml" ] \
+      && [ -f "$dir/profile.env" ] && [ -f "$dir/buildkitd.toml" ] \
+      && cmp -s "$tmp/profile.env" "$dir/profile.env" && cmp -s "$tmp/buildkitd.toml" "$dir/buildkitd.toml"; then valid=1; fi
+    rm -f -- "$tmp/profile.env" "$tmp/buildkitd.toml"; rmdir -- "$tmp"
+    [ "$valid" = 1 ] || { err "Build-cache profile is incomplete or changed; refusing to reuse it"; return 1; }
+  fi
+  printf '%s\n' "$dir"
+}
+
 # Dedicated user-defined bridge for the fleet (created when NETWORK_ISOLATION is
 # on). Docker isolates user-defined bridges from each other, so runners here can't
 # reach your OTHER Unraid containers. Docker auto-allocates the subnet; strict mode
@@ -1889,14 +1970,18 @@ clear_args_tmpdir() {
 }
 
 start_one() {
-  local idx="$1" name="${NAME_PREFIX}-$1" snapshot
+  local idx="$1" name="${NAME_PREFIX}-$1" snapshot current_gen
   if docker inspect "$name" >/dev/null 2>&1; then
     snapshot="$(managed_runner_snapshot "$name")" \
       || { err "refusing fixed-name collision while starting $name"; return 1; }
     log "owned runner $name already exists; skipping"
     return 0
   fi
-  provider_call start_one "$idx" "$name"
+  current_gen="$(crf_confgen)" || return 1
+  crf_prepare_slot_cache "$name" "$CI_PROVIDER" "$current_gen" || return 1
+  provider_call start_one "$idx" "$name" || return 1
+  crf_record_cache_identity "$name" "$CI_PROVIDER" "$current_gen" \
+    || { err "runner $name started, but its cache identity could not be recorded; future starts will purge its retained data"; return 1; }
 }
 
 start_configured_capacity() {
@@ -1925,12 +2010,18 @@ start_configured_capacity() {
 # needs a fresh short-lived registration token; a stale/provider-switched GitLab
 # manager must unregister its old persisted identity before replacement.
 recreate_stopped_runner() {
-  local c="$1" supplied_snapshot="${2:-}" snapshot id provider role idx gen pool
+  local c="$1" supplied_snapshot="${2:-}" snapshot id provider role idx gen pool current_gen purge=true
   snapshot="$supplied_snapshot"
   [ -n "$snapshot" ] || snapshot="$(managed_runner_snapshot "$c")" || return 1
   IFS='|' read -r id provider role idx gen <<< "$snapshot"
   pool="$(runner_pool "$c")" || return 1
-  remove_runner "$c" false "$id" "$provider" || return 1
+  current_gen="$(expected_runner_confgen "$c")" || return 1
+  if [ "$provider" = "$CI_PROVIDER" ] \
+    && [ "$gen" = "$current_gen" ] \
+    && crf_cache_identity_matches "$c" "$provider" "$gen"; then
+    purge=false
+  fi
+  remove_runner "$c" "$purge" "$id" "$provider" || return 1
   pool_activate "$pool" || { err "runner $c belongs to unknown pool $pool"; return 1; }
   start_one "$idx"
 }
@@ -1941,7 +2032,7 @@ recreate_stopped_runner() {
 # routine outage would create needless remote churn and make recovery depend on
 # GitLab availability.
 start_stopped_managed() {
-  local c st provider idx names snapshot id role gen
+  local c st provider idx names snapshot id role gen current_gen
   names="$(managed_names)" || return 1
   for c in $names; do
     [ -n "$c" ] || continue
@@ -1950,8 +2041,10 @@ start_stopped_managed() {
     st="$(docker inspect -f '{{.State.Running}}' "$id" 2>/dev/null)" \
       || { err "could not inspect stopped/running state for owned runner $c"; return 1; }
     [ "$st" = "true" ] && continue
+    current_gen="$(expected_runner_confgen "$c")" || return 1
     if [ "$provider" = gitlab ] && [ "$CI_PROVIDER" = gitlab ] \
-      && [ "$gen" = "$(crf_confgen)" ]; then
+      && [ "$gen" = "$current_gen" ] \
+      && crf_cache_identity_matches "$c" "$provider" "$gen"; then
       log "restarting stopped GitLab manager $c with its persisted system ID"
       gitlab_start_stopped "$c" "$idx" "$id" || return 1
     else
@@ -1979,6 +2072,7 @@ start_stopped_managed() {
 # which would briefly drop egress protection for every strict runner.
 # (cmd_scale runs its own lighter inline subset and is intentionally not a caller.)
 provision_base() {
+  validate_build_cache || return 1
   check_cache_root || return 1
   ensure_dirs || return 1
   ensure_network || return 1
@@ -2323,7 +2417,10 @@ remove_runner() {
   CRF_REMOVE_SLOT="$c"
   CRF_REMOVE_ID="$immutable_id"
   CRF_REMOVE_PROVIDER="$provider"
-  "${provider}_remove_runner" "$c" "$purge"
+  "${provider}_remove_runner" "$c" "$purge" || return 1
+  if [ "$purge" = true ]; then
+    crf_purge_slot_cache "$c"
+  fi
 }
 
 # Stop every running GitLab manager concurrently before a full fleet teardown.
@@ -2380,10 +2477,9 @@ cleanup_orphan_github_validations() {
 
 # Full teardown: daemons, runner containers, and the shared pull-through mirror.
 # Reached from the UI Stop button AND from plugin uninstall (the .plg remove step
-# calls 'stop'), so it must leave nothing running. The mirror's on-pool cache dir
-# ($CACHE_ROOT/registry-mirror) is intentionally left behind — like the config and
-# token — so a later Start rebuilds the container with its cache warm; only the
-# container is removed here, not the cached layers.
+# calls 'stop'), so it must leave nothing running. Retain on-pool runner and
+# mirror caches so a later Start can reuse them. Explicit prune-cache deletes
+# retained caches. Permanent slot retirement still deletes that slot's data.
 cmd_stop() {
   # Cancel every process that can create fleet resources before examining the
   # current Docker state. In particular, a sleeping boot worker must not wake
@@ -2395,7 +2491,7 @@ cmd_stop() {
   lifecycle_stop || return 1
   reconcile_stop || return 1
   quiesce_gitlab_managers_for_stop || return 1
-  local names c remaining remaining_managers stop_failed=0
+  local names c remaining remaining_managers stop_failed=0 snapshot id provider role index gen
   names="$(managed_names)" \
     || { err "could not enumerate managed runners before stop"; return 1; }
   if [ -z "$names" ]; then
@@ -2404,7 +2500,14 @@ cmd_stop() {
     while IFS= read -r c; do
       [ -n "$c" ] || continue
       log "stopping $c (graceful deregister)"
-      remove_runner "$c" || stop_failed=1
+      snapshot="$(managed_runner_snapshot "$c")" || { stop_failed=1; continue; }
+      IFS='|' read -r id provider role index gen <<< "$snapshot"
+      if remove_runner "$c" false; then
+        crf_record_cache_identity "$c" "$provider" "$gen" \
+          || { err "could not record retained cache identity for $c; future starts will purge its per-slot data"; stop_failed=1; }
+      else
+        stop_failed=1
+      fi
     done <<< "$names"
   fi
   # A provider removal that failed closed can intentionally leave a manager and
@@ -2946,6 +3049,84 @@ crf_safe_cache_root() {
   esac
 }
 
+# Retained per-slot data is reusable only when provider and baked runner
+# configuration still match. Missing identity is treated as unsafe legacy data.
+crf_cache_slot_path() {
+  local kind="$1" name="$2" root path real
+  case "$kind" in
+    docker|work|dind-logs|gitlab-cache|gitlab-sockets) ;;
+    *) return 1 ;;
+  esac
+  case "$name" in ''|*[!A-Za-z0-9_.-]*) return 1 ;; esac
+  root="$(crf_safe_cache_root)" || return 1
+  path="$root/$kind/$name"
+  real="$(realpath -m -- "$path" 2>/dev/null)" || return 1
+  [ "$real" = "$path" ] || return 1
+  case "$real" in "$root"/*) printf '%s\n' "$real" ;; *) return 1 ;; esac
+}
+
+crf_cache_identity_path() {
+  local name="$1" root
+  case "$name" in ''|*[!A-Za-z0-9_.-]*) return 1 ;; esac
+  root="$(crf_safe_cache_root)" || return 1
+  printf '%s/.crf-cache-identities/%s\n' "$root" "$name"
+}
+
+crf_cache_identity_matches() {
+  local name="$1" provider="$2" gen="$3" path recorded_provider recorded_gen extra kind
+  path="$(crf_cache_identity_path "$name")" || return 1
+  [ -f "$path" ] && [ ! -L "$path" ] || return 1
+  IFS='|' read -r recorded_provider recorded_gen extra < "$path" || return 1
+  [ -n "$recorded_provider" ] && [ -n "$recorded_gen" ] && [ -z "$extra" ] \
+    || return 1
+  [ "$recorded_provider" = "$provider" ] && [ "$recorded_gen" = "$gen" ] || return 1
+  for kind in docker work dind-logs gitlab-cache gitlab-sockets; do
+    crf_cache_slot_path "$kind" "$name" >/dev/null || return 1
+  done
+}
+
+crf_record_cache_identity() {
+  local name="$1" provider="$2" gen="$3" path dir tmp
+  path="$(crf_cache_identity_path "$name")" || return 1
+  dir="${path%/*}"
+  [ ! -L "$dir" ] || return 1
+  mkdir -p "$dir" && chmod 700 "$dir" 2>/dev/null || return 1
+  [ ! -L "$path" ] || return 1
+  tmp="$(mktemp "$dir/.identity.XXXXXX")" || return 1
+  if ! ( umask 077; printf '%s|%s\n' "$provider" "$gen" > "$tmp" ); then
+    rm -f -- "$tmp"
+    return 1
+  fi
+  chmod 600 "$tmp" 2>/dev/null || { rm -f -- "$tmp"; return 1; }
+  mv -f -- "$tmp" "$path" || { rm -f -- "$tmp"; return 1; }
+}
+
+crf_forget_cache_identity() {
+  local path
+  path="$(crf_cache_identity_path "$1")" || return 1
+  rm -f -- "$path"
+}
+
+crf_purge_slot_cache() {
+  local name="$1" kind path failed=0
+  for kind in docker work dind-logs gitlab-cache gitlab-sockets; do
+    path="$(crf_cache_slot_path "$kind" "$name")" \
+      || { err "refusing cache cleanup for unsafe slot '$name'"; failed=1; continue; }
+    if [ -e "$path" ] || [ -L "$path" ]; then
+      rm -rf -- "$path" || failed=1
+    fi
+  done
+  crf_forget_cache_identity "$name" || failed=1
+  return "$failed"
+}
+
+crf_prepare_slot_cache() {
+  local name="$1" provider="$2" gen="$3"
+  crf_cache_identity_matches "$name" "$provider" "$gen" && return 0
+  log "cache identity for $name is absent or changed; purging retained per-slot data"
+  crf_purge_slot_cache "$name"
+}
+
 # Resolve a CACHE_MOUNTS host subdir against the (canonical) cache root and confirm
 # it stays UNDER that root — rejecting `../` traversal or absolute paths in the
 # space-separated, web-settable CACHE_MOUNTS list before they reach mkdir/chown -R
@@ -3622,7 +3803,7 @@ cmd_prune_cache() {
   [ -z "$active" ] \
     || { err "refusing to prune cache while GitLab executor containers exist"; return 1; }
   root="$(crf_safe_cache_root)" || { err "refusing to prune-cache: CACHE_ROOT='$CACHE_ROOT' is unsafe (system dir, share/pool root, or unresolvable — point it at /mnt/<pool>/<subdir>)"; return 1; }
-  dirs="docker work dind-logs gitlab-cache gitlab-sockets registry-mirror $CACHE_PKG_DIRS"
+  dirs="docker work dind-logs gitlab-cache gitlab-sockets registry-mirror .crf-cache-identities $CACHE_PKG_DIRS"
   for m in $CACHE_MOUNTS; do dirs="$dirs ${m%%:*}"; done
   for d in $dirs; do
     case "$d" in ''|.|..|*/*) continue ;; esac   # simple child names only — never a path/traversal
diff --git a/src/usr/local/emhttp/plugins/ci-runner-farm/include/runner-pools.sh b/src/usr/local/emhttp/plugins/ci-runner-farm/include/runner-pools.sh
old mode 100644
new mode 100755
diff --git a/tests/build-cache-integration.sh b/tests/build-cache-integration.sh
new file mode 100755
index 00000000..6771c392
--- /dev/null
+++ b/tests/build-cache-integration.sh
@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# Real registry reuse across two isolated builders. Never prunes a Docker daemon.
+# External mode uses caller-owned Docker auth and uploads only this dummy context.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+if [ "$(uname -s)" = Darwin ]; then
+  command -v brew >/dev/null 2>&1 || {
+    echo 'macOS cache integration requires Homebrew Coreutils (brew install coreutils).' >&2
+    exit 1
+  }
+  coreutils_bin="$(brew --prefix coreutils)/libexec/gnubin"
+  [ -x "$coreutils_bin/mv" ] || {
+    echo 'Install GNU tools for macOS cache integration: brew install coreutils' >&2
+    exit 1
+  }
+  export PATH="$coreutils_bin:$PATH"
+fi
+external_registry=false
+if [ -n "${CRF_CACHE_TEST_REPOSITORY+x}${CRF_CACHE_TEST_TAG+x}" ]; then
+  : "${CRF_CACHE_TEST_REPOSITORY:?External cache test requires a repository}"
+  : "${CRF_CACHE_TEST_TAG:?External cache test requires a unique proof tag}"
+  [[ "$CRF_CACHE_TEST_TAG" =~ ^proof-[a-z0-9][a-z0-9_.-]{0,100}$ ]] || {
+    echo 'External cache test tag must start with proof- and contain a safe, unique suffix.' >&2
+    exit 1
+  }
+  external_registry=true
+fi
+# DinD mounts its own tmpfs over /tmp, hiding nested bind sources there. Keep
+# the fixture outside that overlay and preserve identical host/sidecar paths.
+tmp="$(mktemp -d /var/tmp/crf-build-cache.XXXXXX)"
+suffix="$(basename "$tmp" | tr '[:upper:].' '[:lower:]-')"
+network="crf-cache-$suffix"
+registry="crf-registry-$suffix"
+builders=()
+registry_id=''
+network_id=''
+sidecar_id=''
+cleanup() {
+  [ -z "$sidecar_id" ] || docker rm -fv "$sidecar_id" >/dev/null 2>&1 || true
+  for builder in "${builders[@]}"; do docker buildx rm "$builder" >/dev/null 2>&1 || true; done
+  [ -z "$registry_id" ] || docker rm -fv "$registry_id" >/dev/null 2>&1 || true
+  [ -z "$network_id" ] || docker network rm "$network_id" >/dev/null 2>&1 || true
+  rm -rf "$tmp"
+}
+trap cleanup EXIT
+export CRF_CFGDIR="$tmp/config" CRF_RUNDIR="$tmp/run" CRF_SOURCE_ONLY=1
+mkdir -p "$CRF_CFGDIR" "$CRF_RUNDIR"
+# shellcheck source=/dev/null
+source src/usr/local/emhttp/plugins/ci-runner-farm/include/runner-farm.sh
+BUILD_CACHE_MODE=registry
+BUILD_CACHE_REPOSITORY="${CRF_CACHE_TEST_REPOSITORY:-cache.test:5000/team/cache}"
+BUILD_CACHE_LOCAL_GIB=20
+profile="$(build_cache_profile)"
+cache_ref="$BUILD_CACHE_REPOSITORY:${CRF_CACHE_TEST_TAG:-project-target-platform-main}"
+cp "$profile/buildkitd.toml" "$tmp/buildkitd.toml"
+registry_image='registry@sha256:a3d8aaa63ed8681a604f1dea0aa03f100d5895b6a58ace528858a7b332415373'
+buildkit_image='moby/buildkit@sha256:28a898719c18a33f4e8000685287fa36fd0dd9560c6440227d3a732d79bb41d8'
+network_id="$(docker network create "$network")"
+if [ "$external_registry" = false ]; then
+  # Plain HTTP belongs only to the disposable registry, never an external one.
+  printf '\n[registry."cache.test:5000"]\n  http = true\n' >> "$tmp/buildkitd.toml"
+  registry_id="$(docker run -d --name "$registry" --network "$network" --network-alias cache.test "$registry_image")"
+fi
+mkdir "$tmp/context"
+printf 'FROM busybox:1.37.0\nRUN echo registry-cache-proof > /proof\n' > "$tmp/context/Dockerfile"
+for n in 1 2; do
+  builder="crf-builder-$suffix-$n"
+  docker buildx create --name "$builder" --driver docker-container \
+    --driver-opt "network=$network" --driver-opt "image=$buildkit_image" \
+    --buildkitd-config "$tmp/buildkitd.toml" >/dev/null
+  builders+=("$builder")
+  docker buildx inspect "$builder" --bootstrap > "$tmp/builder-$n.log" 2>&1
+  container="buildx_buildkit_${builder}0"
+  docker exec "$container" buildctl debug workers --verbose > "$tmp/policy-$n.txt"
+  # Both effective final policies must obey the configured budget. A generated
+  # TOML assertion alone would miss BuildKit's implicit disk-percentage defaults.
+  docker exec "$container" buildctl debug workers --format '{{json .}}' > "$tmp/policy-$n.json"
+  jq -e 'length > 0 and all(.[]; (.gcPolicy | length > 0) and
+    all(.gcPolicy[]; (.maxUsedSpace | type == "number") and .maxUsedSpace > 0 and
+      .maxUsedSpace <= 21474836480 and (.reservedSpace | type == "number") and
+      .reservedSpace <= 21474836480))' "$tmp/policy-$n.json" >/dev/null || {
+        jq '[.[] | {gcPolicy}]' "$tmp/policy-$n.json" >&2
+        exit 1
+      }
+  docker inspect -f '{{range .Mounts}}{{if eq .Destination "/var/lib/buildkit"}}{{.Name}}{{end}}{{end}}' \
+    "$container" > "$tmp/volume-$n"
+  args=(--builder "$builder" --progress=plain
+    --cache-to "type=registry,ref=$cache_ref,mode=max,image-manifest=true")
+  if [ "$n" = 2 ]; then
+    args+=(--cache-from "type=registry,ref=$cache_ref")
+  fi
+  if ! docker buildx build "${args[@]}" "$tmp/context" > "$tmp/build-$n.log" 2>&1; then
+    tail -35 "$tmp/build-$n.log" >&2
+    exit 1
+  fi
+done
+[ -s "$tmp/volume-1" ]
+[ -s "$tmp/volume-2" ]
+if cmp -s "$tmp/volume-1" "$tmp/volume-2"; then
+  echo 'BuildKit builders must use distinct local volumes.' >&2
+  exit 1
+fi
+# The RUN operation, not just base-image metadata, must come from registry cache.
+awk '/RUN echo registry-cache-proof/ {step=$1} $1 == step && $2 == "CACHED" {found=1} END {exit !found}' "$tmp/build-2.log"
+grep -Fq "importing cache manifest from $cache_ref" "$tmp/build-2.log"
+docker run --rm --mount "type=bind,src=$profile,dst=/etc/ci-runner-farm/build-cache,readonly" \
+  busybox:1.37.0 sh -c '. /etc/ci-runner-farm/build-cache/profile.env &&
+    test "$CRF_BUILD_CACHE_MODE" = registry &&
+    ! touch /etc/ci-runner-farm/build-cache/forbidden' >/dev/null 2>&1
+# GitLab's private daemon must resolve the same source path for its nested job.
+sidecar_id="$(docker run -d --privileged --network "$network" \
+  --mount "type=bind,src=$profile,dst=$profile,readonly" \
+  docker@sha256:aa3df78ecf320f5fafdce71c659f1629e96e9de0968305fe1de670e0ca9176ce \
+  dockerd --host=unix:///var/run/docker.sock)"
+for attempt in $(seq 1 30); do
+  docker exec "$sidecar_id" docker info >/dev/null 2>&1 && break
+  sleep 1
+done
+docker exec "$sidecar_id" docker info >/dev/null 2>&1
+docker exec "$sidecar_id" test -s "$profile/profile.env"
+docker exec "$sidecar_id" test -s "$profile/buildkitd.toml"
+if docker exec "$sidecar_id" docker run --rm \
+  --mount "type=bind,src=$profile,dst=/etc/ci-runner-farm/build-cache,readonly" \
+  busybox:1.37.0 sh -c '. /etc/ci-runner-farm/build-cache/profile.env &&
+    test "$CRF_BUILD_CACHE_MODE" = registry &&
+    ! touch /etc/ci-runner-farm/build-cache/forbidden' > "$tmp/nested.log" 2>&1; then
+  :
+else
+  result=$?
+  echo 'Nested read-only profile test failed:' >&2
+  tail -20 "$tmp/nested.log" >&2
+  exit "$result"
+fi
+echo 'build-cache-integration: independent cache reuse, effective GC budgets, and direct/nested read-only profiles: OK'
+if [ "$external_registry" = true ]; then
+  printf 'External registry proof retained at %s (synthetic data only).\n' "$cache_ref"
+fi
diff --git a/tests/build-cache.sh b/tests/build-cache.sh
new file mode 100755
index 00000000..045c17ec
--- /dev/null
+++ b/tests/build-cache.sh
@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# Exercise the real profile generator and provider mounts without a live farm.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+export CRF_CFGDIR="$tmp/config" CRF_RUNDIR="$tmp/run" CRF_SOURCE_ONLY=1
+mkdir -p "$CRF_CFGDIR" "$CRF_RUNDIR"
+# shellcheck source=/dev/null
+source src/usr/local/emhttp/plugins/ci-runner-farm/include/runner-farm.sh
+fail() { echo "BUILD CACHE FAIL: $*" >&2; exit 1; }
+host() { echo testhost; }
+runner_host_service_ipv4() { echo 192.0.2.10; }
+CACHE_ROOT="$tmp/cache"; CACHE_MOUNTS=''; NO_REGISTER=1
+mkdir -p "$CACHE_ROOT"
+
+[ "${BUILD_CACHE_MODE:-missing}" = off ] || fail 'profile must default to off'
+legacy="$(github_confgen)"
+[ "$(crf_confgen)" = "$legacy" ] || fail 'off mode changes the legacy fingerprint'
+[ -z "$(build_cache_profile)" ] || fail 'off mode exposes a profile'
+[ ! -e "$RUNDIR/build-cache-profiles" ] || fail 'off mode creates files'
+github_build_args 1
+if printf '%s\n' "${ARGS[@]}" | grep -q 'build-cache'; then fail 'off mode mounts a profile'; fi
+
+BUILD_CACHE_MODE=registry
+BUILD_CACHE_REPOSITORY='registry.example.test:5443/team/build-cache'
+BUILD_CACHE_LOCAL_GIB=20
+profile="$(build_cache_profile)"
+[ -f "$profile/profile.env" ] && [ -f "$profile/buildkitd.toml" ] || fail 'profile missing'
+first_gen="$(crf_confgen)"
+[ "$first_gen" != "$legacy" ] || fail 'enabled mode omitted from fingerprint'
+grep -qx 'CRF_BUILD_CACHE_REPOSITORY=registry.example.test:5443/team/build-cache' "$profile/profile.env"
+grep -qx '  maxUsedSpace = "20GiB"' "$profile/buildkitd.toml"
+grep -qx '  reservedSpace = "0B"' "$profile/buildkitd.toml"
+first_bytes="$(sha256sum "$profile/profile.env" "$profile/buildkitd.toml")"
+[ "$(build_cache_profile)" = "$profile" ] || fail 'same configuration is not idempotent'
+(
+  # This is the documented workflow boundary. No host credential is exported.
+  source "$profile/profile.env"
+  [ "$CRF_BUILD_CACHE_MODE" = registry ]
+  [ "$CRF_BUILDKIT_CONFIG" = /etc/ci-runner-farm/build-cache/buildkitd.toml ]
+)
+github_build_args 1
+printf '%s\n' "${ARGS[@]}" | grep -qxF "$profile:/etc/ci-runner-farm/build-cache:ro"
+printf '%s\n' "${ARGS[@]}" | grep -qxF "$CACHE_ROOT/docker/ci-runner-1:/var/lib/docker"
+
+# Changing a setting must not rewrite the files used by a busy runner.
+BUILD_CACHE_LOCAL_GIB=10
+second="$(build_cache_profile)"
+[ "$second" != "$profile" ] && [ "$(crf_confgen)" != "$first_gen" ] || fail 'budget change is stale'
+[ "$(sha256sum "$profile/profile.env" "$profile/buildkitd.toml")" = "$first_bytes" ] || fail 'old profile was overwritten'
+BUILD_CACHE_REPOSITORY='registry.example.test/team/other-cache'
+[ "$(build_cache_profile)" != "$second" ] || fail 'repository omitted from hash'
+
+# Reject literal shell/config injection and invalid budgets before any arithmetic.
+for invalid in '' 'https://registry.example.test/cache' 'registry.example.test/cache:latest' \
+  'registry.example.test/cache@sha256:abc' 'registry.example.test/cache,mode=max' \
+  'registry.example.test/../cache' 'registry.example.test/cache;touch /tmp/never' \
+  'registry.example.test/$(id)' $'registry.example.test/cache\nEVIL=true'; do
+  BUILD_CACHE_REPOSITORY="$invalid"
+  if build_cache_profile >/dev/null 2>&1; then fail 'unsafe repository accepted'; fi
+done
+BUILD_CACHE_REPOSITORY='registry.example.test/team/cache'
+for invalid in 0 -1 01 1025 999999999999999999999 '1.5' 'a[$(id)]' $'20\n'; do
+  BUILD_CACHE_LOCAL_GIB="$invalid"
+  if build_cache_profile >/dev/null 2>&1; then fail 'invalid budget accepted'; fi
+done
+BUILD_CACHE_LOCAL_GIB=20; DIND=false
+if build_cache_profile >/dev/null 2>&1; then fail 'host-socket profile accepted'; fi
+DIND=true; BUILD_CACHE_MODE=unknown
+if provider_validate_settings >/dev/null 2>&1; then fail 'invalid mode passed settings validation'; fi
+BUILD_CACHE_MODE=registry
+
+# Both GitLab bind boundaries must refer to the same immutable source directory.
+CI_PROVIDER=gitlab; GITLAB_RUNNER_TOKEN='glrt-test-only-token'
+profile="$(build_cache_profile)"
+gitlab_write_config 1 ci-runner-1
+grep -qF "$profile:/etc/ci-runner-farm/build-cache:ro" "$CFGDIR/gitlab-runners/ci-runner-1/config.toml"
+docker() {
+  case "$1" in
+    inspect) return 1 ;;
+    run) printf '%s\n' "$@" > "$tmp/sidecar.args" ;;
+    --host) return 0 ;;
+    *) return 0 ;;
+  esac
+}
+gitlab_start_sidecar 1 ci-runner-1
+grep -qxF "$profile:$profile:ro" "$tmp/sidecar.args"
+if grep -qF "$GITLAB_RUNNER_TOKEN" "$profile/"*; then fail 'credential in profile'; fi
+
+# Reboot loses RUNDIR. The existing sidecar must not start with an empty bind.
+(
+  fixture_manager_id="$(printf '%064d' 1)"; fixture_side_id="$(printf '%064d' 2)"
+  rm "$profile/profile.env" "$profile/buildkitd.toml"
+  rmdir "$profile"
+  gitlab_validate_manager_version() { return 0; }
+  gitlab_sidecar_owned() { return 0; }
+  gitlab_running_executor_containers() { return 0; }
+  gitlab_start_sidecar() { return 0; }
+  gitlab_ensure_job_image() { return 0; }
+  docker() {
+    case "$1" in
+      inspect)
+        case "${3:-}" in
+          '{{.Id}}') [ "$4" = ci-runner-1 ] && echo "$fixture_manager_id" || echo "$fixture_side_id" ;;
+          '{{.Image}}') echo test-image ;;
+        esac ;;
+      start)
+        [ -s "$profile/profile.env" ] && [ -s "$profile/buildkitd.toml" ] || fail 'restart preceded profile recovery'
+        printf '%s\n' "$2" >> "$tmp/restarted" ;;
+    esac
+    return 0
+  }
+  gitlab_start_stopped ci-runner-1 1 "$fixture_manager_id"
+  grep -qx "$fixture_side_id" "$tmp/restarted"
+  grep -qx "$fixture_manager_id" "$tmp/restarted"
+)
+
+# Partial or substituted snapshots must fail, never be repaired in place.
+mv "$profile/profile.env" "$tmp/saved.env"
+if build_cache_profile >/dev/null 2>&1; then fail 'partial snapshot accepted'; fi
+ln -s "$tmp/saved.env" "$profile/profile.env"
+if build_cache_profile >/dev/null 2>&1; then fail 'symlink snapshot accepted'; fi
+BUILD_CACHE_MODE=off
+[ "$(crf_confgen)" = "$(gitlab_confgen)" ] || fail 'disabling does not restore legacy config'
+[ -z "$(build_cache_profile)" ] || fail 'disabled profile remains active'
+echo 'build-cache: OK'
diff --git a/tests/cache-retention.sh b/tests/cache-retention.sh
new file mode 100755
index 00000000..b89ca45e
--- /dev/null
+++ b/tests/cache-retention.sh
@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# Run the real Stop/removal policy against disposable on-disk cache fixtures.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+fail() { echo "CACHE RETENTION FAIL: $*" >&2; exit 1; }
+
+for provider in github gitlab; do
+  (
+    fixture_provider="$provider"
+    export CRF_SOURCE_ONLY=1 CRF_CFGDIR="$tmp/$provider/config" CRF_RUNDIR="$tmp/$provider/run"
+    mkdir -p "$CRF_CFGDIR" "$CRF_RUNDIR"
+    # shellcheck source=/dev/null
+    source src/usr/local/emhttp/plugins/ci-runner-farm/include/runner-farm.sh
+    CI_PROVIDER="$provider"
+    CACHE_ROOT="$tmp/$provider/cache"
+    NETWORK_ISOLATION=off
+    CACHE_MOUNTS=''
+    NO_REGISTER=1
+    slot=ci-runner-1
+    crf_safe_cache_root() { printf '%s\n' "$CACHE_ROOT"; }
+    fixture_id=$(printf '%064d' 1)
+    present="$tmp/$provider/present"
+    effects="$tmp/$provider/effects"
+    touch "$present" "$effects"
+    for dir in docker work dind-logs gitlab-cache gitlab-sockets registry-mirror; do
+      mkdir -p "$CACHE_ROOT/$dir/$slot"
+      printf 'retained\n' > "$CACHE_ROOT/$dir/$slot/proof"
+    done
+
+    # Unknown or changed identity must never reuse retained per-slot state.
+    crf_prepare_slot_cache "$slot" "$fixture_provider" old-generation || fail 'legacy cache identity was reused'
+    for dir in docker work dind-logs gitlab-cache gitlab-sockets; do
+      [ ! -e "$CACHE_ROOT/$dir/$slot" ] || fail "identity purge retained $dir data"
+    done
+    [ -f "$CACHE_ROOT/registry-mirror/$slot/proof" ] || fail 'identity purge deleted shared mirror data'
+    for dir in docker work dind-logs gitlab-cache gitlab-sockets; do
+      mkdir -p "$CACHE_ROOT/$dir/$slot"
+      printf 'retained\n' > "$CACHE_ROOT/$dir/$slot/proof"
+    done
+    crf_record_cache_identity "$slot" "$fixture_provider" old-generation \
+      || fail 'could not record cache identity'
+    crf_prepare_slot_cache "$slot" "$fixture_provider" old-generation \
+      || fail 'matching cache identity was not reusable'
+    crf_prepare_slot_cache "$slot" "$fixture_provider" new-generation \
+      || fail 'changed cache identity could not be purged'
+    [ ! -e "$CACHE_ROOT/docker/$slot" ] || fail 'changed identity retained Docker data'
+    [ -f "$CACHE_ROOT/registry-mirror/$slot/proof" ] || fail 'changed identity deleted shared mirror data'
+    for dir in docker work dind-logs gitlab-cache gitlab-sockets; do
+      mkdir -p "$CACHE_ROOT/$dir/$slot"
+      printf 'retained\n' > "$CACHE_ROOT/$dir/$slot/proof"
+    done
+    crf_record_cache_identity "$slot" "$fixture_provider" generation \
+      || fail 'could not restore current cache identity'
+
+    # Replace external Docker/API/process boundaries, not Stop, remove_runner,
+    # the provider removal adapters, or their cache retention decisions.
+    boot_autostart_stop() { return 0; }
+    autoscale_stop() { return 0; }
+    imageupdate_stop() { return 0; }
+    reconcile_stop() { return 0; }
+    quiesce_gitlab_managers_for_stop() { return 0; }
+    managed_names() { if [ -e "$present" ]; then echo "$slot"; fi; }
+    managed_runner_snapshot() { printf '%s|%s|runner|1|generation\n' "$fixture_id" "$fixture_provider"; }
+    provider_stop_container() { printf 'stopped %s\n' "$CRF_REMOVE_ID" >> "$effects"; }
+    provider_remove_container() { rm "$present"; }
+    provider_stop_remove_container() { provider_stop_container "$1" && provider_remove_container "$1"; }
+    github_deregister_runner_api() { printf 'unregistered\n' >> "$effects"; }
+    gitlab_unregister_manager() { printf 'unregistered\n' >> "$effects"; }
+    gitlab_running_executor_containers() { return 0; }
+    gitlab_remove_host_jobs() { return 0; }
+    gitlab_scrub_retired_slot_credentials() { printf 'credentials scrubbed\n' >> "$effects"; }
+    gitlab_assert_no_orphan_manager_configs() { return 0; }
+    gitlab_cleanup_orphan_sidecars() { return 0; }
+    cleanup_orphan_github_validations() { return 0; }
+    firewall_clear() { printf 'firewall cleared\n' >> "$effects"; }
+    docker() {
+      case "$1" in
+        inspect) return 1 ;;
+        ps)
+          if [ -e "$present" ] && [[ "$*" = *'label=net.unraid.ci-runner-farm.managed=true'* ]]; then
+            echo "$slot"
+          fi ;;
+        *) return 1 ;;
+      esac
+    }
+
+    cmd_stop >/dev/null || fail "$provider Stop failed"
+    [ ! -e "$present" ] || fail "$provider container survived Stop"
+    grep -qx 'unregistered' "$effects" || fail "$provider registration was not removed"
+    [ -f "$CACHE_ROOT/docker/$slot/proof" ] || fail "$provider Stop deleted Docker data"
+    [ -f "$CACHE_ROOT/gitlab-cache/$slot/proof" ] || fail "$provider Stop deleted job cache"
+    [ -f "$CACHE_ROOT/registry-mirror/$slot/proof" ] || fail "$provider Stop deleted mirror data"
+    if [ "$provider" = gitlab ]; then
+      grep -qx 'credentials scrubbed' "$effects" || fail 'retention skipped credential cleanup'
+    fi
+
+    # Restart uses the real Stop path before reloading and starting the fleet.
+    touch "$present"
+    reload_locked_snapshot() { return 0; }
+    cmd_start() {
+      [ ! -e "$present" ] || fail 'Restart did not stop the old container'
+      [ -f "$CACHE_ROOT/docker/$slot/proof" ] || fail 'Restart lost Docker data before Start'
+      [ -f "$CACHE_ROOT/gitlab-cache/$slot/proof" ] || fail 'Restart lost job cache before Start'
+      touch "$present"
+    }
+    cmd_restart >/dev/null || fail "$provider Restart failed"
+    [ -e "$present" ] || fail "$provider Restart did not start a replacement"
+
+    # Creation maps the retained slot directory, not a fresh per-container path.
+    (
+      DIND=true
+      BUILD_CACHE_MODE=off
+      host() { echo fixture; }
+      runner_host_service_ipv4() { echo 192.0.2.10; }
+      if [ "$fixture_provider" = github ]; then
+        github_build_args 1
+        printf '%s\n' "${ARGS[@]}" | grep -qxF "$CACHE_ROOT/docker/$slot:/var/lib/docker"
+      else
+        GITLAB_RUNNER_TOKEN=glrt-fixture-only
+        gitlab_write_config 1 "$slot"
+        grep -qF "$CACHE_ROOT/gitlab-cache/$slot:/cache" "$CFGDIR/gitlab-runners/$slot/config.toml"
+        docker() {
+          case "$1" in
+            inspect) return 1 ;;
+            run) printf '%s\n' "$@" > "$tmp/sidecar.args" ;;
+            --host) return 0 ;;
+            *) return 1 ;;
+          esac
+        }
+        gitlab_start_sidecar 1 "$slot"
+        grep -qxF "$CACHE_ROOT/docker/$slot:/var/lib/docker" "$tmp/sidecar.args"
+      fi
+      [ -f "$CACHE_ROOT/docker/$slot/proof" ] || fail 'creation overwrote retained data'
+    )
+
+    # Explicit prune must still refuse a live/retained manager.
+    if cmd_prune_cache >/dev/null 2>&1; then fail 'prune accepted an existing manager'; fi
+    [ -f "$CACHE_ROOT/docker/$slot/proof" ] || fail 'refused prune deleted Docker data'
+
+    # Failed removal cannot clear shared isolation or allow Restart to start.
+    (
+      provider_remove_container() { return 1; }
+      firewall_clear() { fail 'failed Stop cleared the firewall'; }
+      cmd_start() { fail 'failed Stop allowed Restart to start'; }
+      if cmd_restart >/dev/null 2>&1; then fail 'Restart accepted failed removal'; fi
+      [ -f "$CACHE_ROOT/docker/$slot/proof" ] || fail 'failed Stop deleted Docker data'
+    )
+
+    # Permanent slot retirement still opts into deletion, independent of Stop.
+    touch "$present"
+    remove_runner "$slot" true >/dev/null || fail "$provider permanent removal failed"
+    [ ! -e "$CACHE_ROOT/docker/$slot" ] || fail "$provider permanent removal retained Docker data"
+    [ -f "$CACHE_ROOT/registry-mirror/$slot/proof" ] || fail 'slot retirement deleted shared mirror data'
+
+    # The existing explicit prune removes retained data only after Stop.
+    mkdir -p "$CACHE_ROOT/docker/$slot"
+    touch "$CACHE_ROOT/docker/$slot/proof"
+    cmd_prune_cache >/dev/null || fail 'explicit prune failed'
+    [ ! -e "$CACHE_ROOT/docker" ] || fail 'explicit prune did not remove retained Docker data'
+    [ ! -e "$CACHE_ROOT/registry-mirror" ] || fail 'explicit prune did not remove mirror data'
+  )
+done
+
+echo 'cache-retention: Stop/Restart preserve both providers; explicit retirement/prune delete caches'
diff --git a/tests/check.sh b/tests/check.sh
index e0a847cd..d25befc1 100755
--- a/tests/check.sh
+++ b/tests/check.sh
@@ -29,6 +29,8 @@ done < <(find "$RUNTIME" -type f \( -name '*.php' -o -name '*.page' \) -print |
 
 echo "== Contracts and package =="
 bash tests/config-parity.sh
+bash tests/build-cache.sh
+bash tests/cache-retention.sh
 bash tests/image-validation.sh
 bash tests/boot-log.sh
 bash tests/editorconfig.sh
diff --git a/tests/exec-csrf.sh b/tests/exec-csrf.sh
old mode 100644
new mode 100755
diff --git a/tests/firewall-transition.sh b/tests/firewall-transition.sh
old mode 100644
new mode 100755
diff --git a/tests/gitlab-runner-lint.sh b/tests/gitlab-runner-lint.sh
old mode 100644
new mode 100755
diff --git a/tests/lease-selfheal.sh b/tests/lease-selfheal.sh
old mode 100644
new mode 100755
diff --git a/tests/log-redaction.sh b/tests/log-redaction.sh
old mode 100644
new mode 100755
diff --git a/tests/numeric-config.sh b/tests/numeric-config.sh
old mode 100644
new mode 100755
diff --git a/tests/ownership-safety.sh b/tests/ownership-safety.sh
old mode 100644
new mode 100755
diff --git a/tests/pool-runtime.sh b/tests/pool-runtime.sh
old mode 100644
new mode 100755
diff --git a/tests/provider-mocks.sh b/tests/provider-mocks.sh
old mode 100644
new mode 100755
index 965aa242..fa623ead
--- a/tests/provider-mocks.sh
+++ b/tests/provider-mocks.sh
@@ -1166,6 +1166,12 @@ fi
   DISPATCH_LOG="$tmp/start-stopped-dispatch.log"
   DISPATCH_MANAGER_ID=bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
   CI_PROVIDER=gitlab
+  crf_safe_cache_root() { printf '%s\n' "$CACHE_ROOT"; }
+  for cache_dir in docker work dind-logs gitlab-cache gitlab-sockets; do
+    mkdir -p "$CACHE_ROOT/$cache_dir/ci-runner-1"
+  done
+  crf_record_cache_identity ci-runner-1 gitlab dispatch-generation \
+    || fail "could not record stopped-manager cache identity"
   managed_names() { printf '%s\n' ci-runner-1; }
   managed_runner_snapshot() {
     printf '%s|gitlab|manager|1|dispatch-generation\n' "$DISPATCH_MANAGER_ID"
@@ -1608,6 +1614,7 @@ grep -qx 'recycle ci-runner-1' "$ACTION_LOG" || fail "image update bypassed cmd_
 # than weakening isolation underneath the survivor.
 : > "$ACTION_LOG"
 managed_names() { printf '%s\n' ci-runner-1; }
+managed_runner_snapshot() { printf '%s|gitlab|manager|1|stop-generation\n' manager-id; }
 remove_runner() { printf 'remove %s\n' "$1" >> "$ACTION_LOG"; return 1; }
 autoscale_stop() { :; }; imageupdate_stop() { :; }
 quiesce_gitlab_managers_for_stop() { :; }
diff --git a/tests/resource-ownership.sh b/tests/resource-ownership.sh
old mode 100644
new mode 100755
diff --git a/tests/run-linux-checks.sh b/tests/run-linux-checks.sh
index 0c9574f5..5ba7b20b 100755
--- a/tests/run-linux-checks.sh
+++ b/tests/run-linux-checks.sh
@@ -27,3 +27,4 @@ fi
 # needs a real Docker daemon to launch the pinned official Runner image, so run
 # that gate on the host after the portable suite succeeds.
 bash tests/gitlab-runner-lint.sh
+bash tests/build-cache-integration.sh
diff --git a/tests/runner-pools.sh b/tests/runner-pools.sh
old mode 100644
new mode 100755