docs(cache): write down the producer half of the depended-upon names contract

daniel/gitdan's ci-cache-reclaim.sh hard-codes four dot-prefixed names it reads to make correctness decisions but never reclaims as leftovers — .ci-lock-*, .cache-last-used, .gitea-last-used, .ci-keep — none of which carried a matching note here (gitdan#32, the follow-up shape to #28/#30 that #7/PR #8 covered for the leftover names specifically). Of the four, this repo actually produces two: - .ci-lock-<id>, written by scripts/cache-lock.sh (acquire/release) and cache-lib.sh's write_cache_lock(). Documents the contract at cache-lock.sh's header, the site someone renaming the marker would most likely be editing. - .cache-last-used, stamped every run by cargo-cache/action.yml. Documents the contract at the exact line that writes it. The other two are read by gitdan's script but produced by nothing in this repo: .gitea-last-used is a legacy naming convention individual repos used before adopting the shared cargo-cache action (nothing here writes it today), and .ci-keep is a per-repo, hand-placed opt-out any consuming repo's own workflow may drop directly into a cache directory, with no single owner. Both get a paragraph in README.md's new subsection explaining why no producer-side counterpart exists for them, rather than inventing an owner this repo doesn't have. README.md's "Scratch names in a cache root are a cross-repo contract" section gains a new subsection, "Names this repo doesn't reclaim, but the arbiter depends on", covering all four and pointing at gitdan's DEPENDED-UPON NAMES CONTRACT block as the canonical description. No behaviour change: comments and docs only. Ref: gitdan#32. Consumer-side counterpart: daniel/gitdan (this branch's sibling PR). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MJHKJFJVUjnvVsemVBnvrd
2026-08-24 17:08:54 -05:00
16 changed files with 178 additions and 2372 deletions
@@ -1,103 +0,0 @@
 name: CI
 on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
    # Spelled out only to keep `edited` in the list — naming any type replaces
    # the whole default set, so the other three have to be restated.
    #
    # `edited`, not `ready_for_review`: draft here is the `WIP:` title prefix,
    # so un-drafting is a title edit and no ready-for-review action is ever
    # raised. That edit is what creates the run which lifts the `if:` skip
    # below (decided once, when a run is CREATED). Do not swap it back and do
    # not drop this to the bare default — either restores the bug. The accepted
    # cost and the evidence are in README's Development section.
    types: [opened, synchronize, reopened, edited]
 # gitdan-ci runs four repos' CI on two capacity slots, and the compiler-backed
 # suites below are multi-minute. A superseded run costs a slot in front of
 # somebody's build, so drop it.
 #
 # `push` groups on `github.sha` rather than `github.ref`: a constant per-branch
 # group is what let this Gitea cancel two of daniel/gitdan's merge runs
 # outright while `cancel-in-progress` was gated away from `push` entirely —
 # see the long note in that repo's ci.yaml. Observed on 1.26.0; the instance
 # is 1.27.2 now and whether it persists is unverified, which is why every
 # commit gets its own group instead of trusting the flag.
 concurrency:
  group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.sha }}
  cancel-in-progress: true
 jobs:
  selftest:
    name: shellcheck + selftests
    # Two clauses, both load-bearing. The second skips draft PRs: Gitea sets
    # draft:true when the title starts with `WIP:`, so work-in-progress pushes
    # cost the shared runner nothing until the PR is un-WIP'd. The first is
    # what keeps that from also skipping pushes to `main` — a `push` event has
    # no `pull_request` context, so `github.event.pull_request.draft` is empty
    # there and the negation alone would be unreliable. Never drop it.
    if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }}
    runs-on: ubuntu-latest
    timeout-minutes: 20
    # Deliberately no `container.volumes:` entry, unlike every repo that
    # CONSUMES this action. The suites below build throwaway workspaces under
    # `mktemp -d` and want a cold target dir every time — a persistent cache
    # would make "did this run rebuild?" unanswerable, which is the question
    # restore-mtimes-selftest.sh exists to ask. So this job takes no share of
    # the shared CI cache disk budget.
    steps:
      - name: Checkout sources
        uses: actions/checkout@v4
      - name: Install shellcheck
        uses: taiki-e/install-action@v2
        with:
          tool: shellcheck
      # `hardlink-clone-selftest.sh` and `restore-mtimes-selftest.sh` drive a
      # real Cargo against a real scratch workspace — they are the only things
      # here that verify the hardlink-aliasing and mtime-freshness behaviour
      # against the compiler rather than against a fixture, and selftest.sh's
      # own header says `--fast` is for iterating, not for signing off a
      # change. So CI installs a toolchain and runs the full set.
      #
      # The scratch workspaces use path dependencies only, so nothing here
      # reaches crates.io.
      # Nightly first, stable second, so stable ends up the default and
      # nightly is only reachable through an explicit `+nightly`.
      #
      # `hardlink-clone-selftest.sh`'s last scenario needs a Cargo that
      # resolves freshness by CONTENT — the mode where the dep-info file
      # carries per-source checksums, which is the mutation that turns a
      # hardlink clone into silent stale-artifact reuse rather than a slow
      # build. This step is what supplies it, and as of 2026-08-26 it does:
      # the scenario ran and passed against 1.100.0-nightly.
      #
      # It briefly did not. Cargo PR #17382 (2026-08-22) demoted
      # `-Z checksum-freshness` to a gate and gave `build.fingerprint` the
      # choice, defaulting to `mtime`, so the suite — which set only the gate —
      # measured a genuine INACTIVE and skipped its strongest scenario. That
      # read as "upstream withdrew content freshness" and was written up here
      # as this step buying nothing. It was a moved switch, not a withdrawal;
      # the suite now exports both and the coverage is back. See
      # daniel/gitdan#62 for the investigation.
      - name: Install Rust nightly
        uses: dtolnay/rust-toolchain@nightly
      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable
      # Every script, including the suites themselves. `-x` follows the
      # `. cache-lib.sh` each one sources, which is where most of the logic
      # being checked actually lives; without it shellcheck reports SC1091 and
      # analyses each file with a hole in it.
      - name: shellcheck
        run: shellcheck -x --source-path=scripts scripts/*.sh
      # One command, not six: selftest.sh is the entry point a developer runs,
      # so a suite added there is gated here without a matching edit in this
      # file.
      - name: Selftests
        run: bash scripts/selftest.sh
@@ -29,63 +29,16 @@ on the runner having a single execution slot.
 One thing neither project had, and the reason the clone is not a plain
 `cp -al`: **a build inside a hardlink clone does mutate the directory it was
-cloned from.** rustc renames its own outputs into place, but Cargo writes its
+cloned from.** Cargo writes real artifacts by replacing them, but writes its
 metadata — and build scripts write their `OUT_DIR` — with a plain truncating
-write, straight through the shared inode. When Cargo resolves freshness by
+write, straight through the shared inode. Under
-content the file that gets corrupted is its dep-info fingerprint —
+`CARGO_UNSTABLE_CHECKSUM_FRESHNESS` the file that gets corrupted is
-`.fingerprint/<unit>/dep-<target>`, or
+`.fingerprint/<unit>/dep-<target>`, which holds the per-source checksums that
-`build/<pkg>/<hash>/fingerprint/dep-<target>` under Cargo's build-dir layout v2
+decide freshness, and the failure is silent stale-artifact reuse rather than a
-— which holds the per-source checksums that decide freshness, and the failure
+slow build. `scripts/hardlink-clone-selftest.sh` reproduces it as an explicit
-is silent stale-artifact reuse rather than a slow build.
+control and asserts the fix. The fix is to hardlink the artifacts (the GB) and
-
+real-copy the metadata (the MB) — about 3.7% of a Bevy-sized target directory,
-One more family joins them, and it is not metadata: **anything the linker
+against 100% for a full copy.
 writes**. rustc writes an `.rlib` or `.rmeta` to a temporary and renames it
 into place, but a linked executable is written through whatever inode is
 already at its path — so a `cargo test --no-run` in a raw `cp -al` clone
 rewrites the source's own test binary. Measured 2026-08-27 on cargo 1.93.1
 stable, 1.96.0-nightly, 1.98.0-nightly and 1.100.0-nightly, under both
 build-dir layouts.
 `scripts/hardlink-clone-selftest.sh` reproduces both as explicit controls and
 asserts the fix. The fix is to hardlink what rustc renames into place — the
 `.rlib`, `.rmeta` and `incremental/` bulk — and real-copy the metadata and the
 linker outputs.
 **The selection names that set directly, under either build-dir layout.**
 Layout v2 regroups everything per build unit under
 `build/<pkg>/<hash>/{fingerprint,out,run}/`, artifacts included, so there is no
 `.fingerprint` and no `deps` to key off and `build/` is no longer a proxy for
 "metadata" — it is the whole tree. The one place the two layouts genuinely
 differ is that under v2 a build script's `OUT_DIR` and a compile unit's rlib
 are both a directory called `out`.
 **Ambiguity there resolves toward unsharing**, because over-unsharing costs
 bytes and under-unsharing costs corruption. An `out` directory stays shared
 only when two independent signals agree it is a compile unit's: it holds an
 `.rlib`/`.rmeta` of its own, *and* its unit carries no record of a build-script
 execution beside it (`run/` under v2, a loose `root-output` under v1). The
 execution record alone is not enough — Cargo writes it only after the script
 succeeds, so a build script that populates `OUT_DIR` and then fails leaves a
 unit that reads as a compile unit. v2 is the nightly default and stabilises in
 cargo 1.100.0 on 2026-11-12.
 ### What it costs
 Real-copied share of a 5.5 GB Bevy target directory, before and after the
 linker-output rule landed:
 | tree | before | after |
 |---|---|---|
 | **excluding `incremental/`** — the figure to plan against, since the quick-start below sets `CARGO_INCREMENTAL: 0` | **36.4%** | **57.0%** |
 | whole tree, `incremental/` included (a local dev checkout, not CI) | 9.0% | 14.1% |
 The first row is the one a CI consumer gets. The increase is the linker-output
 rule, not the layout work: on a scratch crate the layout fix alone takes v2
 from 99.996% to 0.2%.
 The copy is paid per clone and does not amortise — a fresh `cp -al` leaves
 every file with `nlink >= 2`, so the `-links +1` filter cannot skip anything —
 and a clone happens twice per job, once seeding and once publishing.
 ---
@@ -111,14 +64,10 @@ jobs:
    steps:
      - uses: actions/checkout@v4
        with:
-          # REQUIRED, for two things. The mtime restore walks every commit
+          # REQUIRED. The mtime restore walks every commit that ever touched a
-          # that ever touched a tracked file; a depth-1 checkout makes every
+          # tracked file; a depth-1 checkout makes every file resolve to the
-          # file resolve to the tip commit and the cache stops working, and
+          # tip commit and the cache stops working. The action fails loudly
-          # the action fails loudly rather than silently degrading. The prune
+          # rather than silently degrading if this is missing.
          # also decides whether a branch has been merged by asking this
          # checkout for ancestry, which a shallow one cannot answer — there
          # it withholds that half of the pass and says so, so merged-but-
          # undeleted branches keep their caches.
          fetch-depth: 0
      - uses: https://gitdan.com/daniel/gitdan-actions/cargo-cache@v1
@@ -149,14 +98,10 @@ env:
  CARGO_INCREMENTAL: 0                  # per-run bloat on a persistent volume
  CARGO_PROFILE_DEV_DEBUG: line-tables-only
  CARGO_PROFILE_TEST_DEBUG: line-tables-only
-  # Nightly only, and BOTH are needed. Content-addressed freshness instead of
+  # Nightly only. Content-addressed freshness instead of mtime-based — a
-  # mtime-based — a strictly stronger guarantee, complementary to the mtime
+  # strictly stronger guarantee, complementary to the mtime restore (which
-  # restore (which still covers directory-form `rerun-if-changed` build-script
+  # still covers directory-form `rerun-if-changed` build-script watches).
  # watches). Since cargo PR #17382 (2026-08-22) the `-Z` gate below only
  # unlocks the feature; `build.fingerprint` selects it and defaults to
  # `mtime`, so the gate on its own is accepted and does nothing.
  CARGO_UNSTABLE_CHECKSUM_FRESHNESS: "true"
  CARGO_BUILD_FINGERPRINT: "content"
 ```
 ---
@@ -267,73 +212,14 @@ not collapsed into one:
  disk, normally as the cache restored under its own name and otherwise as one
  set aside for a later pass to reclaim.
-**Eviction** runs three passes, ahead of the seed so that what it frees is
+**Eviction** runs three passes: caches for branches that no longer exist on
-available to the clone that follows. Caches for branches that are DEAD are
+origin are removed unconditionally; then, only if free space is under the
-removed unconditionally; then, only if free space is under the requirement,
+threshold, live caches are evicted oldest-first; then, as a last resort, this
-live caches are evicted oldest-first; then, as a last resort, this run's own
+run's own cache. Protected refs and any cache held open by a running job are
-cache. Protected refs, the source this run is about to clone, and any cache
+never candidates. Within the pressure pass, `target-*` directories are evicted
-held open by a running job are never candidates. Within the pressure pass,
+before `snapshot-*` ones — the reverse of the obvious order, because a
-`target-*` directories are evicted before `snapshot-*` ones — the reverse of
+snapshot is hardlinked to everything cloned from it, so removing one frees
-the obvious order, because a snapshot is hardlinked to everything cloned from
+almost no real bytes while costing every future PR its warm start.
 it, so removing one frees almost no real bytes while costing every future PR
 its warm start.
 **A branch is dead in two ways, and neither signal makes the other
 redundant.** The first is that the branch is gone from origin. The second is
 ancestry: a branch still on origin whose tip is an ancestor of a protected
 branch's tip holds no commit that branch does not, so its cache will never be
 read again and goes in the same pass.
 **Turn delete-on-merge on** (`default_delete_branch_after_merge`, per repo) —
 it is the setting this scheme is cheapest under, because a deleted branch is
 decidable from `ls-remote` alone, with no checkout, no objects and no walk.
 The ancestry signal is what covers the rest, and the rest is not a corner:
 - **Every branch merged before the setting was turned on.** They stay on
  origin forever; nothing retroactively deletes them. zemyna carried 48 of
  them at the time the setting was enabled, and ancestry is the only thing
  that reclaims a cache dir belonging to any of them.
 - **Every merge the deletion declines or fails.** Gitea's delete is
  best-effort and silent: it declines for a protected branch and for one
  another open PR still uses, and an API merge that omits the flag — which
  `tea pulls merge` does — simply never asks.
 - **Repos that have not enabled it**, which is the default.
 That is the difference between reclaiming nothing and reclaiming a 40 GB
 directory per merged PR on a full volume (issue 20).
 Ancestry is answered from the commits in the job's own checkout, so it is only
 answered where they are there to answer it — and "cannot tell" is never folded
 into "dead", at either granularity. A shallow checkout withholds the signal
 entirely, because a missing object is its normal case rather than evidence; a
 single branch whose tip is not in the checkout is kept, with a warning naming
 it. A squash or rebase merge leaves no ancestry at all, so its branch reads as
 live until it is deleted. All three are missed reclamations, which cost disk;
 the alternative direction costs a branch its cache while it is still being
 built on.
 **How much free space is enough is measured, not chosen.** What the seed is
 about to do is hardlink-clone a snapshot and then real-copy that clone's
 *mutable set* — the dep-info, build-script metadata and linked outputs that a
 build would otherwise write through a shared inode. The rest stays hardlinked
 and costs nothing. So the requirement is derived per run, from that set,
 measured off the very snapshot the seed will read using the same enumeration
 `unshare_mutable_paths` copies from; the pass evicts oldest-first until it is
 met and then stops. A percentage of the volume cannot express this: how much a
 clone needs is a property of the snapshot, and a threshold sized for a
 different failure is one that never fires before the seed refuses. `cp -al`
 still materialises every directory for real, and the unshare stages each
 subtree through a sibling copy, so the measurement carries a margin —
 `CACHE_CLONE_HEADROOM_PERCENT` and `CACHE_CLONE_HEADROOM_FLOOR_KB`, both
 hand-written defaults, both erring toward asking for more.
 A run that cannot reach the derived requirement after evicting everything
 eligible **fails, naming the shortfall and every directory it kept instead**.
 The seed would otherwise fail seconds later, reporting a staging path and
 nothing about which cache was holding the space — which is the failure this
 pass now pre-empts. `min-free-percent` is an additional floor on top and
 nothing more: it defaults to `0`, it only ever raises the requirement, and
 falling short of it is still a warning and a self-clear rather than a failure.
 **File mtimes.** `actions/checkout` stamps every file with "now", which makes
 every crate look changed to Cargo's mtime-based freshness check — a persistent
@@ -431,39 +317,6 @@ spelling of some new dot-prefixed name — a name it reads for a decision but
 never reclaims — that is exactly this category, and it needs the matching
 `DEPEND_*` entry on gitdan's side before it ships, not after.
 ### The directory LAYOUT is part of that contract as well
 Names are one half; where they sit is the other. gitdan's arbiter walks a
 volume's `_data` tree to `CI_CACHE_MAX_DEPTH`, which is **2** — deliberately
 tight, because a deeper walk starts meeting Cargo's own
 `incremental/<crate>-<hash>` directories, which match the same name shape it
 uses to recognise a cache dir and must never be evicted individually. So:
 ```
 _data/target-<key>                    depth 1 — no lineage
 _data/<lineage>/target-<key>          depth 2 — a lineage
 _data/<a>/<b>/target-<key>            depth 3 — INVISIBLE to the arbiter
 ```
 That budget is the whole reason `cache-lineage` is one path component and not
 a path. Nesting deeper is not an error anywhere: the caches work, the
 in-workflow prune pass keeps managing them, and the one script whose job is
 the shared disk budget across every repo simply never sees them again.
 It is also why the fix for daniel/gitdan#60 nests rather than suffixing the
 cache key. A `target-<key>-<lineage>` name would be read as dead by
 `prune-cache.sh`'s liveness pass — which classifies by recomputing
 `target-<cache_key(branch)>` for every branch on origin — and evicted
 unconditionally on every run; and it falls out of the arbiter's own
 `BRANCH_DIR_RE` too, so the same directories would never be candidates there
 either. Nesting leaves both matchers reading exactly the names they already
 read, one level down.
 One known rough edge, on gitdan's side and cosmetic: that script logs an
 eviction as `<volume>/<basename>`, so a nested `target-<key>` and a flat one
 of the same key are indistinguishable in its output. It evicts the right
 directory; the line just doesn't say which.
 ---
 ## Inputs
@@ -473,16 +326,15 @@ directory; the line just doesn't say which.
 | input | default | meaning |
 |---|---|---|
 | `cache-root` | `/cache` | mount point of the persistent volume inside the job container |
 | `cache-lineage` | *(empty)* | one directory level under `cache-root`, for a second job building the same ref for a different target or profile — see [Multiple jobs in one workflow](#multiple-jobs-in-one-workflow) |
 | `protected-branches` | `dev main` | refs that publish snapshots and are never evicted |
-| `min-free-percent` | `0` | an ADDITIONAL free-space floor, as a percentage of the volume. The gate is derived per run from what the seed is about to clone; this only ever raises it |
+| `min-free-percent` | `10` | prune when free space drops below this |
 | `restore-mtimes` | `true` | restore tracked-file mtimes from git history |
-| `prune` | `true` | run the eviction pass — before the seed, so what it frees is available to the clone |
+| `prune` | `true` | run the eviction pass |
-| `liveness-prune` | `true` | within eviction, remove caches for branches that are dead: gone from origin, or merged into a protected branch |
+| `liveness-prune` | `true` | within eviction, remove caches for branches gone from origin |
 | `own-ref` | *(auto)* | override; defaults to `github.head_ref`, else `github.ref_name` |
 | `base-ref` | *(auto)* | override; defaults to `github.base_ref` (empty on push) |
 | `seed-fallback-dir` | *(empty)* | absolute path to seed from when no snapshot exists — for migrating off an existing flat cache |
-| `watermark-file` | `.ci-watermark-<job>-sha` | must differ per job when two jobs share one target directory; the default already does |
+| `watermark-file` | `.ci-watermark-<job>-sha` | must differ per job when two jobs share one cache key |
 | `lock-id` | `<job>-<run_id>` | identifies this job's cache lock |
 | `stale-lock-seconds` | `7200` | age past which another job's lock is treated as abandoned |
@@ -498,7 +350,6 @@ Exports to the job environment: `CARGO_TARGET_DIR`, `CARGO_CACHE_ROOT`,
 | input | default | meaning |
 |---|---|---|
 | `cache-root` | `/cache` | must match the consume action |
 | `cache-lineage` | *(empty)* | must match the consume action; a mismatch fails the step rather than publishing the wrong tree |
 | `protected-branches` | `dev main` | refs that publish snapshots |
 | `mode` | `publish` | `publish`, or `release-lock` for the `if: always()` step |
 | `own-ref` | *(auto)* | override; defaults to `github.head_ref`, else `github.ref_name` |
@@ -515,70 +366,13 @@ of a merge-preview build, which is not what `dev` is.
 ## Multiple jobs in one workflow
-Two jobs building the same ref — a `ci` job and a `wasm` job, say — are two
+Jobs sharing a cache key (a `ci` job and a `wasm` job on the same branch, say)
-consumers of one cache key, and the cache key alone is not enough to keep them
+each need their **own** watermark file. A shared one breaks the moment two
-apart.
+jobs run in sequence within one trigger: job A advances the watermark to HEAD,
-
+and job B then reads that just-advanced value, computes an empty diff, and
-**Give each its own lineage.** A cache key names a *ref*; what a target
+loses the merge protection entirely. The default (`.ci-watermark-<job>-sha`)
-directory holds is the product of a ref and a build configuration. Left to the
+already gives each job its own; only override `watermark-file` if you also
-key alone, both jobs export the same `CARGO_TARGET_DIR`, and Cargo's
+override `lock-id`, and then keep both distinct per job.
 build-directory lock is exclusive — so on a runner with more than one slot the
 second job sits on `Blocking waiting for file lock on build directory` for the
 length of the first, occupying a capacity slot while doing nothing
 (daniel/gitdan#60). `cache-lineage` is that second dimension:
 ```yaml
      - name: Restore the Cargo cache
        uses: https://gitdan.com/daniel/gitdan-actions/cargo-cache@v1
        with:
          cache-lineage: wasm32          # the `ci` job sets none
      # ... build steps ...
      - name: Record watermark, publish cache snapshot
        uses: https://gitdan.com/daniel/gitdan-actions/cargo-cache-publish@v1
        with:
          cache-lineage: wasm32          # the SAME value, or the step fails
 ```
 A lineage nests one directory level under the cache root
 (`<cache-root>/<lineage>/target-<key>`), so each lineage gets its own target
 dirs, its own snapshots, and its own prune pass. Everything else works as it
 already did, one level down: a PR branch in a lineage layers over **that
 lineage's** base snapshot, the publisher branch publishes into it, and a prune
 pass run inside it never sees a sibling lineage's caches.
 Setting no lineage resolves to the cache root unchanged, byte for byte, so a
 workflow that does not use one keeps the exact directories it already has on
 the volume.
 **Both actions need the same value.** `cargo-cache-publish` derives both ends
 of the snapshot swap from its own `cache-root`, so a publish step left at the
 default while its consume step nested would republish a *different* lineage's
 live target dir over that lineage's snapshot, on every push, with nothing in
 the log to say so. The publish action therefore compares its own inputs
 against the `CARGO_CACHE_ROOT` the consume step exported and fails the step on
 a mismatch. (The `mode: release-lock` call is exempt: it releases a lock on
 `$CARGO_TARGET_DIR` and never touches a cache root, so it takes no lineage.)
 **Some lineage names are refused.** A lineage is one path component, drawn
 from `[A-Za-z0-9._-]`, and several otherwise-reasonable names are rejected at
 resolve time because a *reader elsewhere* would stop seeing the caches
 underneath them: a Cargo profile name (`debug`, `release`, `doc`, …) is one
 gitdan's arbiter never descends into, a `target-`/`snapshot-` prefix makes the
 lineage directory itself an eviction candidate for this repo's own prune pass,
 and a hex-suffixed name is read by that arbiter as a per-branch cache dir in
 its own right. `validate_cache_lineage()` in `scripts/cache-lib.sh` states each
 rejection with the reader that imposes it.
 **Watermarks are still per job.** Two jobs in one lineage — or one job before
 lineages were introduced — each need their **own** watermark file. A shared one
 breaks the moment two jobs run in sequence within one trigger: job A advances
 the watermark to HEAD, and job B then reads that just-advanced value, computes
 an empty diff, and loses the merge protection entirely. The default
 (`.ci-watermark-<job>-sha`) already gives each job its own; only override
 `watermark-file` if you also override `lock-id`, and then keep both distinct
 per job.
 ---
@@ -651,71 +445,16 @@ not automatic.
 ## Development
 ```bash
-shellcheck -x --source-path=scripts scripts/*.sh
+bash scripts/selftest.sh          # everything (~1 min; needs cargo)
 bash scripts/selftest.sh          # everything (needs cargo)
 bash scripts/selftest.sh --fast   # fixture-only suites, no compiler
 ```
 Both run in CI — `.gitea/workflows/ci.yaml`, one job, on pushes to `main` and
 on PRs that were non-draft when the run was created. It installs shellcheck
 and both a stable and a nightly Rust toolchain (nightly so
 `hardlink-clone-selftest.sh` can run its content-freshness scenario, which as
 of 2026-08-26 a nightly does enable — 1.100.0-nightly (787af2b8c 2026-08-25)
 resolves freshness by content given both `CARGO_UNSTABLE_CHECKSUM_FRESHNESS`
 and `CARGO_BUILD_FINGERPRINT: content`, per cargo PR #17382; the suite still
 settles that by experiment on every run and skips the scenario loudly when it
 cannot measure) and references no credentials; the scratch workspaces the
 compiler-backed suites build use path dependencies only, so nothing reaches
 crates.io. It runs the full suite rather than `--fast`,
 because the two compiler-backed suites are the ones that check this scheme
 against real Cargo instead of against a fixture.
 **Draft (`WIP:`-titled) PRs skip it; un-drafting un-skips them, through
 `edited`** — no empty commit needed. The skip is decided when a run is
 *created*, so lifting it needs an event that creates one, and un-drafting on
 this Gitea is a title edit: `edited` is in the workflow's `pull_request` types
 for exactly that reason. `ready_for_review` held that slot first and never
 fired — this Gitea has no draft column and no ready-for-review event at all,
 draft being computed from the title prefix — so a PR opened as `WIP:` carried
 its skip decision all the way to merge unless some later push happened to
 create a run. Do not swap the type back and do not drop the `types:` list to
 its bare default; either restores the bug.
 **Accepted cost: a body edit on an already-non-draft PR now triggers a real
 run.** Gitea populates no `changes` field for a title-or-body edit, unlike
 GitHub, so the workflow cannot tell the edit that un-drafts a PR from an
 ordinary body PATCH — a closing-reference fix-up, say. The price is around
 **90 seconds** of a runner shared across four repos on two capacity slots: the
 last twelve non-skipped runs of this job, `started_at` to `completed_at` off
 the Actions API, are 83 s median over 77–106 s. `timeout-minutes: 20` is a
 ceiling for a hung suite, not a duration. It is also bounded: the workflow's
 `concurrency:` block groups `pull_request` runs on `github.ref` with
 `cancel-in-progress: true`, so a burst of edits collapses to one run rather
 than N. A still-draft PR pays nothing extra — the `if:` guard skips those
 exactly as before.
 The evidence for `edited` comes from `daniel/emowheel`, which hit the identical
 bug, shipped the identical wrong fix, and corrected it in commit `08da820` (see
 `daniel/emowheel#71`): Gitea 1.27.2's `HookIssueAction` enum has no
 `ready_for_review` entry and no notifier emits one, while
 `issue.IsWorkInProgress` derives draft from the title. Live since: emowheel PR
 #141 was un-drafted at 19:01:13 on 2026-08-31 and run 2801 was created two
 seconds later on the **same** head SHA as the two runs skipped before it — a
 run created by the title edit alone, with no push, that executed and passed.
 `daniel/gitdan` ported the same one-word change. That it behaves the same way
 *here* has not been demonstrated in this repo; the next `WIP:` PR opened
 against `main` is the test.
 This repo is consumed by three other repos' CI at `@v1`, a moving tag, so a
 change here reaches all of them at once. That is what the gate is for.
 | suite | covers |
 |---|---|
-| `cache-root-selftest.sh` | that a lineage nests one level and nothing else moves: no lineage resolves byte-for-byte to the cache root, two lineages on one cache key get disjoint target dirs, seed/publish/prune all stay inside their own lineage, a PR layers over its own lineage's base snapshot — **and one rejection per lineage name a reader elsewhere would stop seeing**, plus the publish-side mismatch guard |
+| `hardlink-clone-selftest.sh` | that a build in a clone cannot mutate its source — with a control proving a raw `cp -al` does. Needs a real compiler. |
-| `hardlink-clone-selftest.sh` | that a build in a clone cannot mutate its source — with a control proving a raw `cp -al` does. Needs a real compiler, **and a nightly that actually resolves freshness by content for its last scenario**: the source's-next-build check reasons about content rather than mtime, so under mtime freshness it would assert a bug. Whether the toolchain does is settled by experiment on a throwaway crate, not by asking it — accepting `-Z checksum-freshness` stopped implying it on 2026-08-22, when cargo PR #17382 demoted the flag to a gate and gave `build.fingerprint` (default `mtime`) the choice; the suite now exports both and 1.100.0-nightly measures ACTIVE again. The experiment reports **three** outcomes, not two: active, measured-inactive, and *not measured*. Its answer codes are `0` and `3`, deliberately clear of every status bash generates for its own errors — so nothing that goes wrong inside the probe, including an expansion failure no guard can catch, can be read as an answer. The scenario is skipped for the last two alike, but a failure to measure is never reported as a measurement. The control also reports which mutation families the running Cargo exhibits — a note, not an assertion, since that set moves upstream. It also pins the SELECTION itself against both of Cargo's build-dir layouts, from two file-only fixtures that need no compiler — so the layout the installed Cargo does not happen to write is still covered — and asserts the partition in both directions: every file Cargo rewrites in place is privately owned, and every `.rlib`/`.rmeta` still shares its inode. The second half is what the old suite never checked beyond `shared > 0`, and it is what a layout change silently inverts. |
+| `seed-target-dir-selftest.sh` | seed-source preference, lock-file stripping, two jobs racing on one cache key, **and one scenario per check a hardlink clone is validated against**: a source rotated wholesale, a subtree silently lost from the walk, a copy that reports failure over a tree both other checks read as whole, and a source identity that resolved at neither end — plus a staging tree that could not be privately owned being discarded rather than published |
 | `seed-target-dir-selftest.sh` | seed-source preference, lock-file stripping, two jobs racing on one cache key, **and one scenario per check a hardlink clone is validated against**: a source rotated wholesale, a subtree silently lost from the walk, a copy that reports failure over a tree both other checks read as whole, and a source identity that resolved at neither end — plus a staging tree that could not be privately owned being discarded rather than published, and the publisher's log showing it waited on the consumer's own reader-lock marker before reclaiming a rotated snapshot |
 | `publish-snapshot-selftest.sh` | the atomic swap, that a live consumer survives a republish, and the publisher's side of the rotation race: deferred reclamation under a live reader, and its sweep once the reader is gone |
-| `prune-cache-selftest.sh` | liveness in both its forms — a branch deleted from origin, and one still on it whose tip is already merged — plus protection, locking, eviction order, self-clear, **that a cache a job claims *inside* the check-to-unlink window survives it**, and that a requirement derived from the clone's mutable set evicts exactly enough and then fails rather than under-delivering. Against a real scratch `origin`, including a genuinely shallow clone of it and a `df` that answers from the fixture's own size, since a fixed one cannot show a pass stopping |
+| `prune-cache-selftest.sh` | liveness, protection, locking, eviction order, self-clear, **and that a cache a job claims *inside* the check-to-unlink window survives it** — against a real scratch `origin` |
 | `restore-mtimes-selftest.sh` | the merge hazard and the watermark that closes it, including the two-jobs-one-namespace case. Needs a real compiler. |
 Every suite runs the actual script, not a reimplementation of its logic, and
@@ -733,7 +472,7 @@ key and asserts only what must be true whichever of them wins the rename.
 which places the interference inside the window rather than hoping it lands
 there. `prune-cache-selftest.sh` scenario 12 stubs `du`, so the pass's own
 measurement publishes a reader marker strictly between its check and its
-unlink. `seed-target-dir-selftest.sh` uses the shape five times over, on two
+unlink. `seed-target-dir-selftest.sh` uses the shape four times over, on two
 different commands. Scenarios 8a, 8b and 8c stub `cp`, so the consumer's own
 clone is what rotates the snapshot underneath it, loses a subtree of its own
 source, or reports a failure over a tree that is in fact whole — each strictly
@@ -744,14 +483,9 @@ could not be READ rather than on one that changed, and the only way to make
 that the sole witness is to fail the identity reads while the copy between
 them succeeds. 8a also starts a second real process — the actual
 `publish-snapshot.sh` — but the stub is what fixes where its swap lands; the
-concurrency is incidental to the determinism. Scenario 11 reuses 8a's exact
+concurrency is incidental to the determinism. Every stub asserts that it
-stub and the same forced rotation, but reads a different witness: not the
+fired, because a scenario whose interference silently did not happen passes
-consumer's own checks, but a line in the *publisher's* log reporting that it
+for the wrong reason.
 waited on the reader marker this consumer's clone wrote — `reader_lock_acquire`
 is exercised by 8a already, but nothing asserts it actually fired until this
 scenario reads that line back. Every stub asserts that it fired, because a
 scenario whose interference silently did not happen passes for the wrong
 reason.
 **A synthetic stand-in for the other side, where that artefact *is* the
 contract.** `publish-snapshot-selftest.sh` scenarios 6 to 8 hold a
@@ -783,15 +517,6 @@ how both `[ "$cp_rc" -eq 0 ]` and `[ "$i_before" != missing ]` sat unpinned
 (issue #5) while looking well covered. Isolating a check means constructing
 the state only it can see, not the state that trips several at once.
 Scenario 11 applies the same discipline to a witness outside the clone
 entirely: not which of several checks inside `hardlink_clone_into` caught a
 fault, but whether `reader_lock_acquire`'s marker was observed by anything
 outside it at all. The consumer's own log and exit status are silent either
 way — a run with the marker deleted still succeeds — so what is asserted is
 one line in the *publisher's* log reporting that it waited. Deleting
 `reader_lock_acquire` (issue #10) leaves that line unwritten without failing
 anything else in the suite.
 The action YAML holds no logic beyond wiring; everything testable lives in
 `scripts/`. A composite action needs `shell: bash` on every `run:` step, and
 the actions reach their shared scripts through
@@ -10,15 +10,6 @@ inputs:
    description: 'Mount point of the persistent cache volume. Must match the consume action.'
    required: false
    default: '/cache'
  cache-lineage:
    description: >-
      Must match the cargo-cache step in this job. Checked rather than
      assumed: this action derives both ends of the snapshot swap from its own
      cache-root, so a publish step left at the default while its consume step
      nested would republish a DIFFERENT lineage's live target dir over that
      lineage's snapshot, on every push, silently. A mismatch fails the step.
    required: false
    default: ''
  protected-branches:
    description: >-
      Space-separated refs that publish snapshots. A run whose own ref is not
@@ -76,11 +67,6 @@ runs:
    # Everything here reads the environment the consume action exported, so a
    # workflow that forgets to run cargo-cache first fails loudly here rather
    # than silently publishing a snapshot of the wrong directory.
    #
    # The cache root is taken from that same environment for the same reason,
    # and this action's own cache-root/cache-lineage inputs are checked against
    # it rather than used. The two have always had to agree; until a lineage
    # existed they always did, because nobody overrode the default.
    - id: resolve
      shell: bash
      env:
@@ -106,18 +92,6 @@ runs:
        : "${CARGO_CACHE_KEY:?cargo-cache-publish: CARGO_CACHE_KEY not set by the cargo-cache action}"
        echo "active=yes" >> "$GITHUB_OUTPUT"
        # Only in publish mode. The `release-lock` call is an `if: always()`
        # step that consuming workflows invoke with `mode:` and nothing else —
        # it releases $CARGO_CACHE_LOCK_ID on $CARGO_TARGET_DIR and never
        # touches a cache root at all, so holding its default inputs to the
        # consume step's would fail the cleanup step of every job that sets a
        # lineage, for a value it does not use.
        if [ "${{ inputs.mode }}" = "publish" ]; then
          : "${CARGO_CACHE_ROOT:?cargo-cache-publish: CARGO_CACHE_ROOT not set by the cargo-cache action}"
          bash "${CARGO_CACHE_SCRIPTS}/cache-root.sh" verify \
            "${{ inputs.cache-root }}" "${{ inputs.cache-lineage }}" "$CARGO_CACHE_ROOT"
        fi
        OWN_REF="${{ inputs.own-ref }}"
        [ -n "$OWN_REF" ] || OWN_REF="${{ github.head_ref || github.ref_name }}"
@@ -157,7 +131,7 @@ runs:
      run: |
        set -euo pipefail
        bash "${CARGO_CACHE_SCRIPTS}/publish-snapshot.sh" \
-          "$CARGO_CACHE_KEY" "$CARGO_CACHE_ROOT" \
+          "$CARGO_CACHE_KEY" "${{ inputs.cache-root }}" \
          "${{ github.job }}-${{ github.run_id }}-$$"
    # Released in both modes. In `publish` mode this is the normal end-of-job
@@ -10,18 +10,6 @@ inputs:
    description: 'Mount point of the persistent cache volume inside the job container.'
    required: false
    default: '/cache'
  cache-lineage:
    description: >-
      Distinguishes two jobs that build the SAME ref for different targets or
      profiles (a host build and a wasm32 build, say) and would otherwise
      resolve to one CARGO_TARGET_DIR and serialise on Cargo's exclusive
      build-directory lock. Names one directory level under cache-root:
      <cache-root>/<lineage>/target-<key>. Must be a single path component;
      several names are refused outright because a reader elsewhere would stop
      seeing the caches under them (see validate_cache_lineage in
      scripts/cache-lib.sh). Pass the same value to cargo-cache-publish.
    required: false
    default: ''
  protected-branches:
    description: >-
      Space-separated refs that publish snapshots and are never evicted.
@@ -29,18 +17,9 @@ inputs:
    required: false
    default: 'dev main'
  min-free-percent:
-    description: >-
+    description: 'Prune when free space on the cache volume drops below this percentage.'
      An ADDITIONAL free-space floor, as a percentage of the cache volume.
      The prune's own requirement is derived per run from what the seed is
      about to clone — the mutable set it has to real-copy out of the source
      snapshot, which is a property of that snapshot and not of the volume —
      and this floor only ever raises it. 0, the default, leaves the derived
      requirement as the only gate. Set it to keep headroom for something
      other than the clone (the build's own output, another job on the same
      volume); it will not make the clone fit, because it does not know how
      big the clone is.
    required: false
-    default: '0'
+    default: '10'
  restore-mtimes:
    description: >-
      Restore every tracked file's mtime from git history. Requires a
@@ -49,20 +28,13 @@ inputs:
    required: false
    default: 'true'
  prune:
-    description: >-
+    description: 'Run the eviction pass (dead-branch liveness + disk pressure).'
      Run the eviction pass (dead-branch liveness + disk pressure). It runs
      BEFORE the seed step, so what it frees is available to the clone that
      step makes.
    required: false
    default: 'true'
  liveness-prune:
    description: >-
-      Within the prune pass, remove caches for branches that are dead: gone
+      Within the prune pass, remove caches for branches that no longer exist
-      from origin, or still on origin with a tip already merged into a
+      on origin. Set to false on a runner that cannot reach origin.
      protected branch. The second signal is what reclaims anything at all on
      a forge that keeps branches after merge, and it needs the protected
      branches' commits in the checkout — a shallow one withholds it and says
      so. Set to false on a runner that cannot reach origin.
    required: false
    default: 'true'
  own-ref:
@@ -82,9 +54,8 @@ inputs:
  watermark-file:
    description: >-
      Name of this job's build-watermark file inside the target dir. MUST be
-      distinct per job when two jobs share one target directory — which two
+      distinct per job when two jobs share one cache key. Defaults to
-      jobs no longer need to do; cache-lineage gives them separate ones.
+      .ci-watermark-<job>-sha.
      Defaults to .ci-watermark-<job>-sha, already distinct per job.
    required: false
    default: ''
  lock-id:
@@ -103,12 +74,6 @@ outputs:
  cache-key:
    description: 'Sanitized cache key for this run''s own ref.'
    value: ${{ steps.resolve.outputs.cache-key }}
  cache-root:
    description: >-
      Resolved cache root — cache-root, plus the lineage directory when one is
      set. Every directory this action reads or writes is under it. Also
      exported as CARGO_CACHE_ROOT.
    value: ${{ steps.resolve.outputs.cache-root }}
  seeded-from:
    description: 'Where the target dir came from: own | base-snapshot | own-snapshot | fallback-dir | concurrent-peer | cold.'
    value: ${{ steps.seed.outputs.seeded-from }}
@@ -130,16 +95,6 @@ runs:
    # `base_ref` is populated only for pull_request events. A push run has
    # nothing to layer over: its own ref IS the reference branch. It
    # publishes, it does not consume.
    #
    # The cache root is resolved first because every path below hangs off it.
    # A lineage nests one directory level (`<root>/<lineage>/target-<key>`),
    # which is what lets two jobs on ONE ref hold two build directories and so
    # not serialise on Cargo's exclusive lock. It is resolved through
    # cache-root.sh rather than interpolated here so the name is validated —
    # several otherwise-reasonable lineage names put their whole subtree out of
    # reach of a pass that has to see it. Everything downstream reads the
    # resolved value, and it is exported as CARGO_CACHE_ROOT so the publish
    # action can check it agrees with its own inputs.
    - id: resolve
      shell: bash
      run: |
@@ -147,8 +102,6 @@ runs:
        SCRIPTS=$(cd "${{ github.action_path }}/.." && pwd)/scripts
        [ -d "$SCRIPTS" ] || { echo "::error::cargo-cache: scripts/ not found at $SCRIPTS"; exit 1; }
        echo "CARGO_CACHE_SCRIPTS=${SCRIPTS}" >> "$GITHUB_ENV"
        CACHE_ROOT=$(bash "${SCRIPTS}/cache-root.sh" resolve \
          "${{ inputs.cache-root }}" "${{ inputs.cache-lineage }}")
        OWN_REF="${{ inputs.own-ref }}"
        [ -n "$OWN_REF" ] || OWN_REF="${{ github.head_ref || github.ref_name }}"
        BASE_REF="${{ inputs.base-ref }}"
@@ -163,7 +116,7 @@ runs:
          echo "cache: own ref '${OWN_REF}' -> ${OWN_KEY} (no base ref — this ref publishes, it does not consume)"
        fi
-        TARGET_DIR="${CACHE_ROOT}/target-${OWN_KEY}"
+        TARGET_DIR="${{ inputs.cache-root }}/target-${OWN_KEY}"
        WATERMARK="${{ inputs.watermark-file }}"
        [ -n "$WATERMARK" ] || WATERMARK=".ci-watermark-${{ github.job }}-sha"
        LOCK_ID="${{ inputs.lock-id }}"
@@ -175,49 +128,15 @@ runs:
          echo "base-key=${BASE_KEY}"
          echo "lock-id=${LOCK_ID}"
          echo "watermark-file=${WATERMARK}"
          echo "cache-root=${CACHE_ROOT}"
        } >> "$GITHUB_OUTPUT"
        {
          echo "CARGO_TARGET_DIR=${TARGET_DIR}"
-          echo "CARGO_CACHE_ROOT=${CACHE_ROOT}"
+          echo "CARGO_CACHE_ROOT=${{ inputs.cache-root }}"
          echo "CARGO_CACHE_KEY=${OWN_KEY}"
          echo "CARGO_CACHE_LOCK_ID=${LOCK_ID}"
          echo "CI_WATERMARK_FILE=${WATERMARK}"
        } >> "$GITHUB_ENV"
    # Runs BEFORE the seed, which is the only order in which its work can
    # help: the eviction it performs is what makes room for the clone the seed
    # step is about to make, and the requirement it evicts against is measured
    # off the snapshot that clone will read. Running afterwards — where this
    # step used to be — meant every run freed space for the NEXT one and the
    # seed met whatever the last run happened to leave.
    #
    # Two things this ordering has to be safe against, and is:
    #
    #   The source it is about to read is excluded from every pass by name
    #   (see protected_reason in prune-cache.sh), so pass 1 cannot take the
    #   snapshot out from under the seed that follows it.
    #   A concurrent job's target dir carries its lock from the instant it
    #   appears under its final name — the seed writes it into the staging
    #   tree before the rename — so there is no window in which running this
    #   earlier sees an unlocked directory somebody is using.
    - if: ${{ inputs.prune == 'true' }}
      shell: bash
      env:
        STALE_LOCK_SECONDS: ${{ inputs.stale-lock-seconds }}
        CACHE_LIVENESS: ${{ inputs.liveness-prune }}
      run: |
        set -euo pipefail
        SCRIPTS=$(cd "${{ github.action_path }}/.." && pwd)/scripts
        bash "${SCRIPTS}/prune-cache.sh" \
          "${{ steps.resolve.outputs.cache-root }}" \
          "${{ steps.resolve.outputs.target-dir }}" \
          "${{ inputs.protected-branches }}" \
          "${{ inputs.min-free-percent }}" \
          "${{ steps.resolve.outputs.cache-key }}" \
          "${{ steps.resolve.outputs.base-key }}" \
          "${{ inputs.seed-fallback-dir }}"
    # Seeds this ref's target dir from the base's published snapshot. See
    # scripts/seed-target-dir.sh — the staging-then-atomic-rename is what
    # makes concurrent jobs sharing one cache key safe by construction rather
@@ -236,7 +155,7 @@ runs:
        bash "${SCRIPTS}/seed-target-dir.sh" \
          "${{ steps.resolve.outputs.cache-key }}" \
          "${{ steps.resolve.outputs.base-key }}" \
-          "${{ steps.resolve.outputs.cache-root }}" \
+          "${{ inputs.cache-root }}" \
          "${{ github.job }}-${{ github.run_id }}-$$" \
          "${{ inputs.seed-fallback-dir }}" \
          "${{ steps.resolve.outputs.lock-id }}"
@@ -277,3 +196,17 @@ runs:
        CARGO_TARGET_DIR: ${{ steps.resolve.outputs.target-dir }}
        CI_WATERMARK_FILE: ${{ steps.resolve.outputs.watermark-file }}
      run: bash "$(cd "${{ github.action_path }}/.." && pwd)/scripts/restore-mtimes.sh"
    - if: ${{ inputs.prune == 'true' }}
      shell: bash
      env:
        STALE_LOCK_SECONDS: ${{ inputs.stale-lock-seconds }}
        CACHE_LIVENESS: ${{ inputs.liveness-prune }}
      run: |
        set -euo pipefail
        SCRIPTS=$(cd "${{ github.action_path }}/.." && pwd)/scripts
        bash "${SCRIPTS}/prune-cache.sh" \
          "${{ inputs.cache-root }}" \
          "${{ steps.resolve.outputs.target-dir }}" \
          "${{ inputs.protected-branches }}" \
          "${{ inputs.min-free-percent }}"
@@ -114,106 +114,6 @@ cache_key() {
 target_dir_for() { printf '%s/target-%s' "$1" "$2"; }
 snapshot_dir_for() { printf '%s/snapshot-%s' "$1" "$2"; }
 # ---------------------------------------------------------------------------
 # Cache lineages
 # ---------------------------------------------------------------------------
 #
 # A cache key names a REF. What a target directory holds is the product of a
 # ref and a BUILD CONFIGURATION, and the two are not the same thing: emowheel
 # builds the same ref twice on every push, once for the host and once for
 # wasm32, in two jobs that run concurrently. Keyed on the ref alone both
 # resolve to one CARGO_TARGET_DIR, and Cargo's build-directory lock is
 # exclusive — so the second job sits on `Blocking waiting for file lock on
 # build directory` for the length of the first, holding a runner capacity slot
 # while doing nothing (daniel/gitdan#60).
 #
 # A lineage is that second dimension, and it is expressed as ONE DIRECTORY
 # LEVEL above the per-ref directories rather than as a suffix on the key:
 #
 #   <cache-root>/target-<key>              no lineage (the flat layout)
 #   <cache-root>/<lineage>/target-<key>    a lineage
 #
 # Nesting rather than suffixing is what keeps every existing reader correct
 # without teaching any of them a new name shape. `prune-cache.sh` resolves
 # liveness by recomputing `target-<cache_key(branch)>` for every branch on
 # origin and evicting whatever does not match — a suffixed `target-<key>-wasm32`
 # matches nothing, so it would be classified dead and unconditionally evicted
 # on every single run. The host-level arbiter in daniel/gitdan reads the same
 # shape (its BRANCH_DIR_RE), and a suffixed name falls out of it too: not
 # evicted there, but never a candidate either, so a whole lineage becomes
 # invisible to the global disk budget. Nesting leaves both matchers reading
 # exactly the names they already read, one directory deeper.
 #
 # ONE LEVEL, AND NOT TWO. The arbiter walks a volume to CI_CACHE_MAX_DEPTH,
 # which is 2 — `_data/target-<key>` and `_data/<lineage>/target-<key>`. It is
 # kept tight there on purpose (a deeper walk starts meeting Cargo's own
 # `incremental/<crate>-<hash>` directories, which match the same name shape and
 # must never be evicted individually), so a lineage is a single path component
 # and validate_cache_lineage refuses one containing a slash.
 # Directory names daniel/gitdan's ci-cache-reclaim.sh refuses to descend into
 # (its CI_CACHE_NODESCEND_NAMES). A lineage named one of these puts its whole
 # subtree outside the global arbiter's reach: the caches accumulate and the one
 # script whose job is the shared disk budget cannot see them.
 CACHE_LINEAGE_RESERVED_NAMES="debug release deps incremental build .fingerprint tmp examples doc"
 # The shape that same script reads as a per-branch cache directory (its
 # BRANCH_DIR_RE). A lineage matching it is taken for a cache dir in its own
 # right — never descended into, and an eviction candidate whole, which is the
 # entire lineage rather than one ref's share of it.
 CACHE_LINEAGE_BRANCH_DIR_RE='^.+-[0-9a-f]{7,40}$'
 # Every rejection below names the reader that imposes it, because that is the
 # only way the constraint survives: none of these is a filesystem limit, and a
 # name that trips one produces no error anywhere — it produces a lineage that
 # silently stops being pruned, or silently stops being reclaimed.
 validate_cache_lineage() {
  local lineage="$1" reserved
  [ -n "$lineage" ] || return 0
  case "$lineage" in
    */*)
      echo "::error::cache lineage '${lineage}' must be a single path component: the host-level arbiter walks a cache volume to depth 2, so <cache-root>/<lineage>/target-<key> is as deep as a cache directory may sit and still be reclaimable" >&2
      return 1
      ;;
    .*)
      echo "::error::cache lineage '${lineage}' must not start with a dot: every dot-prefixed entry under a cache root belongs to the leftover-naming contract (see the top of this file), and a lineage is not garbage to be reclaimed" >&2
      return 1
      ;;
    target-* | snapshot-*)
      echo "::error::cache lineage '${lineage}' must not start with 'target-' or 'snapshot-': prune-cache.sh globs both prefixes at the cache root, so the lineage directory itself would become an eviction candidate" >&2
      return 1
      ;;
    *[!A-Za-z0-9._-]*)
      echo "::error::cache lineage '${lineage}' may contain only [A-Za-z0-9._-] — the same charset cache_key() sanitises a ref down to" >&2
      return 1
      ;;
  esac
  for reserved in $CACHE_LINEAGE_RESERVED_NAMES; do
    if [ "$lineage" = "$reserved" ]; then
      echo "::error::cache lineage '${lineage}' is one of the Cargo directory names daniel/gitdan's ci-cache-reclaim.sh never descends into (CI_CACHE_NODESCEND_NAMES) — every cache under it would be invisible to the host-level disk budget" >&2
      return 1
    fi
  done
  if [[ $lineage =~ $CACHE_LINEAGE_BRANCH_DIR_RE ]]; then
    echo "::error::cache lineage '${lineage}' ends in a hex suffix, which is the shape daniel/gitdan's ci-cache-reclaim.sh reads as a per-branch cache directory — it would treat the lineage directory as one cache and evict the whole thing" >&2
    return 1
  fi
  return 0
 }
 # The cache root a lineage's directories actually live under. An empty lineage
 # resolves to the cache root unchanged, byte for byte: that is what makes this
 # a no-op for every consumer that does not set one, rather than a migration.
 cache_root_for() {
  local root="$1" lineage="${2:-}"
  validate_cache_lineage "$lineage" || return 1
  printf '%s%s' "$root" "${lineage:+/$lineage}"
 }
 # ---------------------------------------------------------------------------
 # Disk accounting
 # ---------------------------------------------------------------------------
@@ -310,193 +210,33 @@ _unshare_files() {
  # The inner shell propagates a failure of any individual copy-and-rename out
  # through xargs (which exits 123 if any invocation exits 1-125), so a
  # partially-unshared tree is reported rather than silently accepted.
  # shellcheck disable=SC2016  # the quoted program is for the INNER shell: $f
  # is its loop variable, $rc its accumulator and $$ its pid. Expanding any of
  # them here is what the single quotes exist to prevent.
  find "$@" -links +1 -print0 2>/dev/null |
    xargs -0 -r -n 64 bash -c 'rc=0; for f; do cp -p -- "$f" "$f.unshare.$$" && mv -f -- "$f.unshare.$$" "$f" || rc=1; done; exit $rc' _
 }
 # True when a directory holds a compiled library artifact of its own.
 #
 # The glob is left unquoted and unmatched-glob-safe on purpose: with nullglob
 # off an unmatched pattern stays literal and the `-e` test fails, which is the
 # answer wanted.
 _holds_compiled_artifact() {
  local f
  for f in "$1"/*.rlib "$1"/*.rmeta; do
    [ -e "$f" ] && return 0
  done
  return 1
 }
 # The directory names that select a mutable subtree, as one find predicate.
 #
 # Named once because THREE readers have to agree on it: the selection in
 # _mutable_dirs, the prune that skips those subtrees when it sizes the file
 # rules, and anything later that measures what a clone will cost. Two
 # spellings of this list would size a different tree than the one copied, and
 # the direction that fails is silent — an under-measured clone runs out of
 # disk mid-unshare, which is gitdan-actions#20.
 _MUTABLE_DIR_NAMES=( -name .fingerprint -o -name fingerprint -o -name run -o -name out )
 # _mutable_file_rules <fn>
 #
 # The FILE half of the mutable set, applied one rule at a time:
 #
 #     <fn> <label> <maxdepth|-> <find-predicate...>
 #
 # Same reason as the array above — `unshare_mutable_paths` copies these and
 # `mutable_set_kb` measures them, and a rule that exists in only one of the
 # two is exactly the under-estimate the headroom gate cannot survive. The
 # maxdepth is a separate field because GNU find wants it ahead of every other
 # predicate, so it cannot live inside the predicate vector.
 #
 # `-type f` is each caller's to add: the sizer needs it inside the `-o`
 # alternation it builds, the copier ahead of it.
 _mutable_file_rules() {
  local fn="$1"
  "$fn" 'dep-info files' - -name '*.d' || return 1
  # Layout v1's build-script run metadata, which v2 groups under `run/` and v1
  # leaves loose in the run unit's directory. `invoked.timestamp` is empty and
  # carries its meaning in its mtime, which a shared inode carries too.
  "$fn" 'build-script run metadata' - \
    \( -name output -o -name root-output -o -name stderr -o -name invoked.timestamp \) || return 1
  # Linked outputs. Unlike an rlib or an rmeta — which rustc writes to a
  # temporary and renames into place — an executable or shared object is
  # written by the LINKER, and the linker writes THROUGH an existing inode.
  # Measured 2026-08-27 on cargo 1.93.1 stable, 1.96.0-nightly, 1.98.0-nightly
  # (layout v1) and 1.100.0-nightly (e8cb624d5, layout v2), mold and the
  # default linker alike: a `cargo test --no-run` binary in a `cp -al` clone
  # rewrote the SOURCE's copy of itself in place, under both layouts.
  #
  # What separates that from the executables measured INTACT is not
  # established. Every intact case observed was one Cargo has to re-create
  # anyway to maintain an uplift hardlink — a bin target's
  # `deps/<bin>-<hash>`, twinned at `<profile>/<bin>`. Whether the twin is the
  # mechanism or a correlate of it was not determined, and the rule below does
  # not depend on the answer: exempting twinned executables would recover no
  # bytes this function newly copies. See gitdan-actions#17.
  #
  # The executable bit is the discriminator because it is the linker's own
  # output that is at risk, not the directory it happens to land in — `.rlib`,
  # `.rmeta` and `incremental/` stay shared and they are the bytes that matter.
  "$fn" 'linked outputs' - -perm -u+x || return 1
  "$fn" '.rustc_info.json' 3 -name '.rustc_info.json' || return 1
  return 0
 }
 # The directories `unshare_mutable_paths` replaces, under either layout.
 #
 # All four names are pruned, so nothing selected here can contain anything else
 # selected here and the caller never unshares a subtree twice.
 #
 # `out` is the one that needs deciding rather than naming, and it is the whole
 # difficulty of layout v2: a compile unit's rlib and a build script's OUT_DIR
 # are both a directory called `out`, one directory apart, and they need
 # opposite treatment.
 #
 # AMBIGUITY RESOLVES TOWARD UNSHARING, and that direction is the rule rather
 # than a default: over-unsharing costs bytes, under-unsharing costs corruption.
 # So an `out` directory is left shared only when TWO independent signals agree
 # it is a compile unit's artifact directory, and either one missing is enough
 # to real-copy it:
 #
 #   1. it holds an `.rlib`/`.rmeta` of its own — the artifact whose sharing is
 #      the entire point of the clone; and
 #   2. its unit directory has no record of a build-script execution beside it
 #      (`run/` under layout v2, a loose `root-output` under v1).
 #
 # Signal 2 alone was the first cut of this and it is NOT sufficient, because
 # Cargo writes `root-output` only AFTER the script exits successfully. A build
 # script that populates `OUT_DIR` and then FAILS leaves a unit with no record
 # at all, which reads as "compile unit" — and the old `-name build` selection
 # covered that state by real-copying `build/` wholesale, so trusting signal 2
 # alone was a regression against it. Reproduced on cargo 1.93.1 stable: the
 # clone's build wrote through the shared inode into the source's OUT_DIR.
 # Signal 1 closes it, because a failed build script's OUT_DIR holds no rlib.
 #
 # The residual is a build script that writes a file NAMED `*.rlib`/`*.rmeta`
 # into `OUT_DIR` and has never once succeeded. Nothing bounds that away; it is
 # simply far narrower than what it replaces.
 #
 # Requiring signal 1 also means a bin, test or build-script COMPILE unit's
 # `out` is real-copied rather than shared — at no cost in bytes, since
 # everything in one is an executable or a `*.d`, and both are privately owned
 # by the file rules below either way.
 _mutable_dirs() {
  local root="$1" d unit
  while IFS= read -r d; do
    if [ "${d##*/}" = out ]; then
      unit="${d%/out}"
      if ! [ -d "$unit/run" ] && ! [ -e "$unit/root-output" ] \
         && _holds_compiled_artifact "$d"; then
        continue
      fi
    fi
    printf '%s\n' "$d"
  done < <(find "$root" -type d \
    \( "${_MUTABLE_DIR_NAMES[@]}" \) \
    -prune -print 2>/dev/null)
 }
 # _mutable_file_rules' callback for the copying side. The root travels in a
 # variable rather than an argument because the callback's own signature is the
 # rule's, and every rule has to reach the same tree.
 _unshare_one_rule() {
  local label="$1" maxdepth="$2"; shift 2
  local -a depth=()
  [ "$maxdepth" = - ] || depth=(-maxdepth "$maxdepth")
  _unshare_files "$_MUTABLE_ROOT" ${depth[@]+"${depth[@]}"} -type f "$@" || {
    echo "::error::unshare_mutable_paths: failed to unshare ${label} under ${_MUTABLE_ROOT}" >&2
    return 1
  }
  return 0
 }
 # THE load-bearing function of this whole design.
 #
 # A hardlink clone is only safe if every write the clone's build performs
-# lands on a NEW inode, leaving the source's data untouched. That is true of
+# lands on a NEW inode, leaving the source's data untouched. That is true for
-# rustc's own outputs — it writes an `.rlib` or `.rmeta` to a temporary and
+# compilation artifacts — rustc and the linker replace `deps/*.rlib`,
-# renames it into place — and it is NOT true of the metadata Cargo and build
+# `*.rmeta`, and binaries rather than truncating them in place — and it is
-# scripts write with a plain truncating write, nor of anything the LINKER
+# NOT true for the metadata Cargo and build scripts write with a plain
-# produces. Measured directly (Linux, ext4: `cp -al` a warm target dir, change
+# truncating write. Measured directly (Linux, ext4, cargo 1.9x nightly:
-# a source file, build in the clone, diff the source) the following files in
+# `cp -al` a warm target dir, change a source file, build in the clone, diff
-# the SOURCE were mutated through the shared inode:
+# the source) the following files in the SOURCE were mutated through the
 # shared inode:
 #
-#   <profile>/.fingerprint/<unit>/dep-<target>   (build-dir layout v1) — or,
+#   <profile>/.fingerprint/<unit>/dep-<target>   (only under
-#   <profile>/build/<pkg>/<hash>/fingerprint/dep-<target>
+#                                                CARGO_UNSTABLE_CHECKSUM_FRESHNESS,
-#                                               (build-dir layout v2; see the
+#                                                where this file carries the
-#                                                dated note below for which
+#                                                per-source blake3 checksums)
-#                                                Cargo writes which). Only
+#   <profile>/build/<pkg>/output, root-output   (Cargo build-script metadata)
 #                                                when Cargo resolves freshness
 #                                                by CONTENT, where this file
 #                                                carries the per-source blake3
 #                                                checksums.
 #   <profile>/build/<pkg>/output, root-output   (Cargo build-script metadata;
 #                                                `<pkg>/<hash>/run/root-output`
 #                                                under layout v2)
 #   <profile>/build/<pkg>/out/**                (whatever the build script
 #                                                writes into OUT_DIR — build
 #                                                scripts overwhelmingly use a
 #                                                plain fs::write)
 #   <profile>/deps/*.d, <profile>/*.d           (Cargo's post-processed
 #                                                dep-info)
 #   <profile>/deps/<test>-<hash>                (a linked TEST binary; under
 #                                                layout v2,
 #                                                `build/<pkg>/<hash>/out/`)
 #
 # THE LINKED-OUTPUT CASE IS NOT LAYOUT-SPECIFIC AND WAS NOT PART OF THIS
 # FUNCTION UNTIL 2026-08-27 (gitdan-actions#14). A `cargo test --no-run` inside
 # a raw `cp -al` clone rewrote the source's own test binary in place on cargo
 # 1.93.1 stable, 1.96.0-nightly, 1.98.0-nightly (layout v1) and 1.100.0-nightly
 # (layout v2) alike. Cargo re-creates the path first when it also has to uplift
 # the result — a bin target's `deps/<bin>-<hash>` has a hardlink twin at
 # `<profile>/<bin>` — and other crate shapes relinked to a fresh inode for
 # reasons this measurement did not pin down. Since the safe cases could not be
 # enumerated, every executable is treated as mutable; `.rlib`, `.rmeta` and
 # `incremental/` are what stay shared, and they are the bytes worth sharing.
 #
 # The checksum-freshness case is not a cosmetic one. Reproduced end to end:
 # branch B clones base's cache, builds its own content, and thereby rewrites
@@ -506,54 +246,10 @@ _unshare_one_rule() {
 # sources, reports `Fresh`, and reuses a binary built from the PRE-merge code.
 # That is silent stale-artifact reuse — a wrong answer, not a slow one.
 #
-# WHAT UPSTREAM CHANGED, AND WHAT IT DID NOT (measured 2026-08-26, daniel/gitdan#62).
+# So: hardlink the artifacts (the GB), real-copy the metadata (the MB).
-#
+# Measured on a 6.9 GB Bevy workspace target dir, the unshared set is
-# An earlier revision of this comment recorded that the dep-info write was
+# .fingerprint 22 MB + build/ 237 MB + a handful of dep-info files — about
-# "NOT reproduced on 1.100.0-nightly (2026-08-25) — upstream appears to have
+# 3.7% of the tree, against 100% for a plain `cp -a`.
 # stopped writing it in place". That reading was wrong, and the way it was
 # wrong is the reason this paragraph is dated. Two unrelated upstream changes
 # landed within days of each other, and between them they moved both the
 # switch that turns the behaviour on and the path it writes to:
 #
 #   1. The ON-SWITCH MOVED. cargo PR #17382 `feat(config): Add build.fingerprint`
 #      (merged 2026-08-22) demoted `-Z checksum-freshness` to a gate: it now
 #      only UNLOCKS the feature, and `build.fingerprint` SELECTS it, defaulting
 #      to `"mtime"`. So `CARGO_UNSTABLE_CHECKSUM_FRESHNESS=true` on its own is
 #      accepted and does nothing, which is exactly the "flag accepted, mtime
 #      anyway" result that was mistaken for a withdrawal. Content freshness
 #      needs BOTH, and with both it is entirely intact:
 #
 #          CARGO_UNSTABLE_CHECKSUM_FRESHNESS=true CARGO_BUILD_FINGERPRINT=content
 #
 #      Measured on cargo 1.100.0-nightly (e8cb624d5 2026-08-22): with the gate
 #      alone a `cp -al` clone mutates only the build/ and *.d families; add
 #      `CARGO_BUILD_FINGERPRINT=content` and the source's dep-info file is
 #      mutated through the shared inode again. Same toolchain, same clone, one
 #      env var apart. The hazard was never removed — it was switched off.
 #
 #   2. THE PATH MOVED. Build-dir layout v2 (`-Z build-dir-new-layout`, cargo
 #      1.91) became the nightly default in cargo 1.99 (PR #17258) and was
 #      stabilised by PR #17354, merged 2026-08-18, shipping in cargo 1.100.0
 #      stable on 2026-11-12. Under v2 there is no `<profile>/.fingerprint` and
 #      no `<profile>/deps` at all: everything is regrouped per build unit under
 #      `<profile>/build/<pkg>/<hash>/{fingerprint,out,run}/`, artifacts
 #      included. Bracketed locally: cargo 1.97.1 and 1.98.0-nightly write v1,
 #      1.100.0-nightly writes v2.
 #
 # Until 2026-08-27 the selection was `-name .fingerprint -o -name build`,
 # which under a v2 Cargo matched nothing on its first clause and the entire
 # tree on its second, because the artifacts moved under `build/` too. The guard
 # held by accident and the saving did not: on one scratch crate (serde +
 # serde_json + regex plus a build script), same sources both ways —
 #
 #     cargo 1.98.0-nightly (layout v1)   64.9 MB unshared of 165.1 MB — 39.3%
 #          1.100.0-nightly (layout v2)  110.4 MB unshared of 110.4 MB — 99.996%
 #
 # The selection now names the mutable set directly rather than by the container
 # it used to live in, so it holds under both layouts; the same crate measures
 # 45.3% (v1) and 38.4% (v2), both dominated by the linked-output rule above
 # rather than by the layout. On a real 5.5 GB Bevy target dir the whole change
 # moves the real-copied share from 9.0% to 14.1%.
 #
 # `incremental/` is deliberately left shared: rustc writes each incremental
 # session to a fresh `s-*-working` directory and finalises it with a rename,
@@ -563,12 +259,12 @@ _unshare_one_rule() {
 unshare_mutable_paths() {
  local root="$1" d
  [ -d "$root" ] || return 0
  _MUTABLE_ROOT="$root"
  # The list is materialised in full before anything is replaced: each
  # replacement deletes and recreates a directory, and a live `find` walk over
-  # a tree being mutated underneath it is a needless hazard.
+  # a tree being mutated underneath it is a needless hazard. `-prune` keeps a
  # match's own contents out of the list.
  local -a dirs=()
-  mapfile -t dirs < <(_mutable_dirs "$root")
+  mapfile -t dirs < <(find "$root" -type d \( -name .fingerprint -o -name build \) -prune -print 2>/dev/null)
  for d in "${dirs[@]}"; do
    [ -n "$d" ] || continue
    unshare_subtree "$d" || {
@@ -576,121 +272,14 @@ unshare_mutable_paths() {
      return 1
    }
  done
-  _mutable_file_rules _unshare_one_rule || return 1
+  _unshare_files "$root" -type f -name '*.d' || {
-  return 0
+    echo "::error::unshare_mutable_paths: failed to unshare dep-info files under ${root}" >&2
    return 1
  }
-
+  _unshare_files "$root" -maxdepth 3 -type f -name '.rustc_info.json' || {
-# ---------------------------------------------------------------------------
+    echo "::error::unshare_mutable_paths: failed to unshare .rustc_info.json under ${root}" >&2
-# What the seed will clone, and what that clone costs in disk
+    return 1
 # ---------------------------------------------------------------------------
 # The sources seed-target-dir.sh considers, most specific first, as
 # `<dir>:<label>` lines.
 #
 # Read by the seed, which clones the first one that exists, and by the prune
 # that has to size the volume for that clone BEFORE it happens. One derivation
 # rather than two agreeing ones: a prune that sizes a different tree than the
 # seed clones is measuring nothing, and nothing downstream would say so.
 seed_source_candidates() {
  local root="$1" own_key="$2" base_key="$3" fallback="${4:-}"
  [ -n "$base_key" ] && printf '%s:base snapshot\n' "$(snapshot_dir_for "$root" "$base_key")"
  printf '%s:own snapshot\n' "$(snapshot_dir_for "$root" "$own_key")"
  [ -n "$fallback" ] && printf '%s:fallback dir\n' "$fallback"
  return 0
  }
 # The directory the seed will actually hardlink-clone on this run, or nothing
 # at all when it will not clone: its own target dir already exists (the seed
 # reuses it and returns before the candidate list is consulted), or no
 # candidate exists (it starts cold).
 seed_clone_source() {
  local root="$1" own_key="$2" base_key="$3" fallback="${4:-}" entry src
  [ -d "$(target_dir_for "$root" "$own_key")" ] && return 0
  while IFS= read -r entry; do
    src="${entry%%:*}"
    if [ -d "$src" ]; then printf '%s' "$src"; return 0; fi
  done < <(seed_source_candidates "$root" "$own_key" "$base_key" "$fallback")
  return 0
 }
 # _mutable_file_rules' callback for the measuring side.
 #
 # One find per rule, skipping the subtrees `_mutable_dirs` already selects
 # whole — those are measured by the `du` in mutable_set_kb, and counting a
 # file twice would inflate the requirement into evicting caches nothing
 # needed. `%k` is allocated 1K blocks, the same unit `du -sk` reports, so the
 # two halves add.
 _size_one_rule() {
  local maxdepth="$2"; shift 2
  local -a depth=()
  [ "$maxdepth" = - ] || depth=(-maxdepth "$maxdepth")
  find "$_MUTABLE_ROOT" ${depth[@]+"${depth[@]}"} \
    \( "${_MUTABLE_DIR_NAMES[@]}" \) -prune -o \
    -type f \( "$@" \) -printf '%k\n' 2>/dev/null
  return 0
 }
 # The kilobytes `unshare_mutable_paths` will really-copy out of <dir> — the
 # part of a hardlink clone that costs new disk, as opposed to the `.rlib`,
 # `.rmeta` and `incremental/` bytes that stay shared with the source.
 #
 # Measured off the SAME enumeration the copier uses (`_mutable_dirs` and
 # `_mutable_file_rules`), which is the only thing that makes this a
 # measurement rather than an estimate.
 #
 # Two residuals, both named because neither is bounded away:
 #
 #   OVER by any file matching two rules at once — an executable named
 #   `output`, say. Rare, and small.
 #   UNDER by the `*.d` files inside an `out` directory that _mutable_dirs
 #   leaves SHARED (the compile-unit case: it holds an .rlib and has no
 #   build-script record beside it). Such a directory holds a library artifact
 #   by definition, so what is missed is dep-info, not executables. Also under
 #   by a `.rustc_info.json` deeper than the copier's own maxdepth, which is
 #   kilobytes.
 #
 # The margin in clone_headroom_kb is what covers the under-count; it is not
 # there to make the measurement optional.
 mutable_set_kb() {
  local root="$1"
  [ -d "$root" ] || { printf '0'; return 0; }
  _MUTABLE_ROOT="$root"
  {
    _mutable_dirs "$root" | tr '\n' '\0' | xargs -0 -r du -sk 2>/dev/null | awk '{print $1}'
    _mutable_file_rules _size_one_rule
  } | awk '{s += $1} END { printf "%d", s + 0 }'
  return 0
 }
 # How much free space the seed needs on the volume before it clones <dir>.
 #
 # CACHE_CLONE_HEADROOM_PERCENT scales the measured mutable set;
 # CACHE_CLONE_HEADROOM_FLOOR_KB is added on top. BOTH DEFAULTS ARE
 # HAND-WRITTEN — nothing measures them, and they are separate because they
 # cover different things:
 #
 #   The percentage covers what scales with the tree: `unshare_subtree` stages
 #   each mutable directory through a sibling copy before dropping the shared
 #   original, so at its peak one subtree is held twice, and the under-count
 #   named on mutable_set_kb scales with the tree too.
 #   The floor covers what does not: `cp -al` materialises every DIRECTORY for
 #   real (only files are linked), and a Bevy-sized target dir has hundreds of
 #   thousands of them.
 #
 # Both are overridable, and the direction of error is deliberate. Over-asking
 # evicts a cache that would have fitted, costing one branch a cold start;
 # under-asking lets the clone start and run out of disk halfway through the
 # unshare, which fails the job with an error naming a staging path — the
 # failure gitdan-actions#20 is filed about.
 CACHE_CLONE_HEADROOM_PERCENT="${CACHE_CLONE_HEADROOM_PERCENT:-150}"
 CACHE_CLONE_HEADROOM_FLOOR_KB="${CACHE_CLONE_HEADROOM_FLOOR_KB:-2097152}"
 clone_headroom_kb() {
  local src="${1:-}" kb
  if [ -z "$src" ] || [ ! -d "$src" ]; then printf '0'; return 0; fi
  kb=$(mutable_set_kb "$src")
  awk -v k="$kb" -v pct="$CACHE_CLONE_HEADROOM_PERCENT" -v floor="$CACHE_CLONE_HEADROOM_FLOOR_KB" \
    'BEGIN { printf "%d", (k * pct / 100) + floor }'
  return 0
 }
@@ -1,194 +0,0 @@
 #!/usr/bin/env bash
 # Regression test for cache-root.sh and the lineage rules in cache-lib.sh —
 # the fix for daniel/gitdan#60, where two jobs building the same ref for
 # different targets resolved to one CARGO_TARGET_DIR and serialised on Cargo's
 # exclusive build-directory lock.
 #
 #   1. NO LINEAGE CHANGES NOTHING — the effective root is the cache root byte
 #      for byte, so every consumer that does not set a lineage keeps the exact
 #      directories it already has on the volume. This is the whole of the
 #      migration story for lublub, zemyna and emowheel's `ci` job, so it is
 #      asserted rather than assumed.
 #   2. TWO LINEAGES, ONE REF, TWO TARGET DIRS — the bug itself. The two jobs
 #      keep one cache key (they are the same ref) and still get directories
 #      that are neither equal nor nested one inside the other, which is what
 #      Cargo's per-directory lock needs in order not to serialise them.
 #   3. THE WHOLE PIPELINE MOVES TOGETHER — seed, publish and prune all operate
 #      inside the lineage root. A pass run in one lineage must not evict, or
 #      even see, a sibling lineage's caches or the flat layout's.
 #   4. BASE SEEDING IS PER LINEAGE — a PR branch layers over ITS OWN lineage's
 #      base snapshot, not over whatever the flat root happens to hold. This is
 #      the property that keeps a warm start for both jobs rather than one.
 #   5. A NAME NO READER CAN HANDLE IS REFUSED AT RESOLVE TIME — one assertion
 #      per constraint, each named for the reader that imposes it. None of these
 #      is a filesystem limit: every one of them produces a working directory
 #      that some pass silently stops seeing, which is the failure mode this
 #      whole scheme exists to avoid rather than to relocate.
 #   6. A PUBLISH THAT DISAGREES WITH ITS CONSUME STEP FAILS LOUDLY — the
 #      footgun the lineage input introduces. cargo-cache-publish derives both
 #      ends of the snapshot swap from its own `cache-root`, so a publish step
 #      left at the default while its consume step nested would republish the
 #      OTHER lineage's live target dir over that lineage's snapshot, silently.
 set -euo pipefail
 script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 . "$script_dir/cache-lib.sh"
 scratch=$(mktemp -d)
 trap 'rm -rf "$scratch"' EXIT
 root="$scratch/cache"; mkdir -p "$root"
 pass_count=0
 fail() { echo "ASSERTION FAILED: $*" >&2; exit 1; }
 ok() { pass_count=$((pass_count + 1)); echo "PASS: $*"; }
 resolve() { bash "$script_dir/cache-root.sh" resolve "$@"; }
 # A tree that looks enough like a Cargo target dir for the pipeline scripts,
 # with a marker naming which lineage produced it — scenario 4 turns on reading
 # that marker back out of a seeded directory.
 make_tree() {
  local d="$1" marker="$2"
  mkdir -p "$d/debug/deps" "$d/debug/.fingerprint/x"
  echo "$marker" > "$d/debug/deps/libx.rlib"
  echo "$marker" > "$d/lineage-marker"
  echo "$marker" > "$d/debug/.fingerprint/x/dep-lib-x"
 }
 echo "=== 1. no lineage changes nothing ==="
 [ "$(resolve /cache)" = /cache ] || fail "an omitted lineage changed the root"
 [ "$(resolve /cache '')" = /cache ] || fail "an empty lineage changed the root"
 ok "no lineage resolves to the cache root unchanged"
 KEY=$(cache_key dev)
 [ "$(target_dir_for "$(resolve /cache '')" "$KEY")" = "/cache/target-$KEY" ] \
  || fail "the flat target-dir name moved"
 [ "$(snapshot_dir_for "$(resolve /cache '')" "$KEY")" = "/cache/snapshot-$KEY" ] \
  || fail "the flat snapshot name moved"
 ok "the flat layout's directory names are untouched"
 echo
 echo "=== 2. two lineages, one ref, two target dirs ==="
 HOST_ROOT=$(resolve /cache)
 WASM_ROOT=$(resolve /cache wasm32)
 [ "$WASM_ROOT" = /cache/wasm32 ] || fail "lineage root resolved to '$WASM_ROOT'"
 HOST_DIR=$(target_dir_for "$HOST_ROOT" "$KEY")
 WASM_DIR=$(target_dir_for "$WASM_ROOT" "$KEY")
 [ "$HOST_DIR" != "$WASM_DIR" ] || fail "both lineages resolved to $HOST_DIR"
 case "$WASM_DIR" in "$HOST_DIR"/*) fail "the wasm target dir sits inside the host one" ;; esac
 case "$HOST_DIR" in "$WASM_DIR"/*) fail "the host target dir sits inside the wasm one" ;; esac
 ok "one cache key ($KEY), two disjoint target dirs: $HOST_DIR and $WASM_DIR"
 echo
 echo "=== 3. the whole pipeline moves together ==="
 DEAD=$(cache_key feat/dead)
 lin="$root/wasm32"
 mkdir -p "$lin"
 make_tree "$root/target-$DEAD" flat
 make_tree "$root/native/target-$DEAD" native
 make_tree "$lin/target-$DEAD" wasm32
 bash "$script_dir/seed-target-dir.sh" "$KEY" "" "$lin" tag-3 > "$scratch/seed3.log" 2>&1 \
  || { cat "$scratch/seed3.log"; fail "seed inside a lineage root failed"; }
 [ -d "$lin/target-$KEY" ] || fail "seed did not create $lin/target-$KEY"
 [ -d "$root/target-$KEY" ] && fail "seed created a directory at the flat root as well"
 ok "seed creates its directory under the lineage root and nowhere else"
 make_tree "$lin/target-$KEY" wasm32
 bash "$script_dir/publish-snapshot.sh" "$KEY" "$lin" tag-3 > "$scratch/pub3.log" 2>&1 \
  || { cat "$scratch/pub3.log"; fail "publish inside a lineage root failed"; }
 [ -d "$lin/snapshot-$KEY" ] || fail "publish did not create $lin/snapshot-$KEY"
 [ -d "$root/snapshot-$KEY" ] && fail "publish created a snapshot at the flat root as well"
 ok "publish writes its snapshot under the lineage root and nowhere else"
 # Free space far below the threshold, so pass 2 evicts every eligible
 # directory it can see. What it can see is the point of the scenario.
 CACHE_LIVENESS=false CACHE_DF_OVERRIDE="1000000 1000" \
  bash "$script_dir/prune-cache.sh" "$lin" "$lin/target-$KEY" 'dev main' 10 \
  > "$scratch/prune3.log" 2>&1 || { cat "$scratch/prune3.log"; fail "prune inside a lineage root failed"; }
 [ -d "$lin/target-$DEAD" ] && { cat "$scratch/prune3.log"; fail "prune left its own lineage's evictable cache in place"; }
 [ -d "$root/target-$DEAD" ] || fail "prune reached out of its lineage and evicted the flat root's cache"
 [ -d "$root/native/target-$DEAD" ] || fail "prune reached into a sibling lineage and evicted its cache"
 ok "prune under disk pressure evicts inside its own lineage only"
 echo
 echo "=== 4. base seeding is per lineage ==="
 BASE=$(cache_key dev)
 PR=$(cache_key feat/pr)
 rm -rf "$lin" "$root/snapshot-$BASE"
 mkdir -p "$lin"
 make_tree "$root/snapshot-$BASE" flat-base
 make_tree "$lin/snapshot-$BASE" wasm32-base
 bash "$script_dir/seed-target-dir.sh" "$PR" "$BASE" "$lin" tag-4 > "$scratch/seed4.log" 2>&1 \
  || { cat "$scratch/seed4.log"; fail "seeding a PR branch inside a lineage failed"; }
 [ -d "$lin/target-$PR" ] || fail "the PR branch's lineage target dir was not created"
 got=$(cat "$lin/target-$PR/lineage-marker")
 [ "$got" = wasm32-base ] || fail "the PR branch layered over '$got', not its own lineage's base snapshot"
 grep -q 'base snapshot' "$scratch/seed4.log" || { cat "$scratch/seed4.log"; fail "seed did not report a base-snapshot clone"; }
 ok "a PR branch layers over its own lineage's base snapshot ($got)"
 echo
 echo "=== 5. a name no reader can handle is refused ==="
 reject() {
  local lineage="$1" want="$2" desc="$3" out
  if out=$(resolve /cache "$lineage" 2>&1); then
    fail "lineage '$lineage' was accepted (resolved to '$out') — $desc"
  fi
  case "$out" in
    *"$want"*) ;;
    *) fail "lineage '$lineage' was rejected without naming '$want': $out" ;;
  esac
  ok "rejected '$lineage' — $desc"
 }
 reject 'a/b' 'single path component' "the arbiter walks a volume to depth 2"
 reject '.hidden' 'dot' "every dot-prefixed name under a cache root is leftover-contract territory"
 reject 'target-x' 'prune-cache.sh' "prune-cache.sh globs target-* at the cache root"
 reject 'snapshot-x' 'prune-cache.sh' "prune-cache.sh globs snapshot-* at the cache root"
 reject 'wasm 32' 'A-Za-z0-9._-' "a cache key is sanitised to that charset and a lineage sits beside one"
 reject 'release' 'CI_CACHE_NODESCEND_NAMES' "the arbiter never descends into a Cargo profile name"
 reject 'doc' 'CI_CACHE_NODESCEND_NAMES' "same, for the docs profile directory"
 reject 'lineage-deadbeef' 'per-branch cache directory' "the arbiter reads a hex-suffixed name as one cache dir"
 for good in wasm32 web android host wasm32.release lineage_2; do
  out=$(resolve /cache "$good") || fail "lineage '$good' was rejected: $out"
  [ "$out" = "/cache/$good" ] || fail "lineage '$good' resolved to '$out'"
 done
 ok "ordinary lineage names still resolve"
 echo
 echo "=== 6. a publish that disagrees with its consume step fails loudly ==="
 verify() { bash "$script_dir/cache-root.sh" verify "$@"; }
 verify /cache wasm32 /cache/wasm32 > /dev/null 2>&1 \
  || fail "verify rejected a publish step that agrees with its consume step"
 verify /cache '' /cache > /dev/null 2>&1 \
  || fail "verify rejected an unmigrated consumer's matching default pair"
 ok "verify accepts a publish step whose inputs match what the consume step exported"
 # The exact shape of the mistake: the consume step nested, the publish step
 # kept the default. Left unchecked this republishes the host lineage's live
 # target dir over the host lineage's snapshot, from the wasm job.
 if out=$(verify /cache '' /cache/wasm32 2>&1); then
  fail "verify accepted a publish step that resolved to /cache while the job exported /cache/wasm32"
 fi
 case "$out" in
  *'/cache/wasm32'*) ;;
  *) fail "the mismatch error does not quote what the consume step exported: $out" ;;
 esac
 case "$out" in
  *'SAME cache-root and cache-lineage'*) ;;
  *) fail "the mismatch error does not say what to do about it: $out" ;;
 esac
 ok "verify rejects a publish step that forgot the lineage, and says so"
 if verify /cache 'a/b' /cache/a/b > /dev/null 2>&1; then
  fail "verify accepted an invalid lineage as long as both sides agreed on it"
 fi
 ok "verify validates the lineage as well as comparing it"
 echo
 echo "cache-root-selftest: ${pass_count} assertions passed"
@@ -1,61 +0,0 @@
 #!/usr/bin/env bash
 # Resolves — and cross-checks — the cache root a job's directories live under.
 #
 #   cache-root.sh resolve <cache-root> [lineage]
 #   cache-root.sh verify  <cache-root> <lineage> <exported-root>
 #
 # `resolve` prints the effective root: the cache root unchanged when no lineage
 # is given, or `<cache-root>/<lineage>` when one is. Invalid lineage names are
 # rejected here rather than downstream — see validate_cache_lineage() in
 # cache-lib.sh, where every rejection names the reader that imposes it.
 #
 # `verify` is the publish side's guard. cargo-cache-publish resolves the same
 # two inputs the consume action was given and compares the result against the
 # CARGO_CACHE_ROOT the consume step exported into the job environment. The two
 # actions have always had to agree — `cache-root`'s description in the publish
 # action says "must match the consume action" — and until a lineage existed
 # they always did, because nobody overrode the default. A disagreement is not
 # a harmless no-op: publish-snapshot.sh takes the root as an argument and
 # derives BOTH ends of the swap from it, so a publish step that kept the
 # default while its consume step nested would read `<root>/target-<key>` — the
 # OTHER lineage's live target dir — and republish it over `<root>/snapshot-<key>`,
 # which is that lineage's snapshot. Two jobs would then be publishing one
 # snapshot from one tree on every push, and nothing in either action would say
 # so. Hence: fail the job, loudly, rather than resolve the ambiguity in
 # either direction.
 #
 # A thin CLI over cache-lib.sh, kept as its own entry point for the same
 # reason branch-cache-key.sh is: an out-of-band job that needs to find a
 # lineage's directories should resolve the path the way the action does
 # instead of reimplementing the rule.
 set -euo pipefail
 . "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/cache-lib.sh"
 MODE="${1:-}"
 case "$MODE" in
  resolve)
    [ $# -ge 2 ] && [ $# -le 3 ] || {
      echo "::error::cache-root.sh resolve: expected <cache-root> [lineage]" >&2
      exit 1
    }
    [ -n "$2" ] || { echo "::error::cache-root.sh: cache-root must not be empty" >&2; exit 1; }
    cache_root_for "$2" "${3:-}"
    ;;
  verify)
    [ $# -eq 4 ] || {
      echo "::error::cache-root.sh verify: expected <cache-root> <lineage> <exported-root>" >&2
      exit 1
    }
    [ -n "$2" ] || { echo "::error::cache-root.sh: cache-root must not be empty" >&2; exit 1; }
    expected=$(cache_root_for "$2" "$3")
    if [ "$expected" != "$4" ]; then
      echo "::error::cache-root.sh: this step resolves its cache root to '${expected}' (cache-root '$2', cache-lineage '$3') but the cargo-cache step in this job exported '$4'. Pass the SAME cache-root and cache-lineage to both actions." >&2
      exit 1
    fi
    echo "cache root: ${expected} (agrees with the cargo-cache step in this job)"
    ;;
  *)
    echo "::error::cache-root.sh: unknown mode '${MODE}' (expected resolve or verify)" >&2
    exit 1
    ;;
 esac
@@ -5,10 +5,8 @@
 #
 # That assumption is FALSE for a plain `cp -al`. Measured, and asserted below
 # as an explicit control: build in a raw `cp -al` clone and the source's
-# dep-info file (`.fingerprint/<unit>/dep-*` under Cargo's build-dir layout
+# `.fingerprint/<unit>/dep-*` (under CARGO_UNSTABLE_CHECKSUM_FRESHNESS),
-# v1, `build/<pkg>/<hash>/fingerprint/dep-*` under v2 — and under content
+# `build/<pkg>/output`, `build/<pkg>/out/**` and `deps/*.d` all change,
 # freshness only, see the probe below), `build/<pkg>/output`,
 # `build/<pkg>/out/**` and `deps/*.d` all change,
 # because Cargo and build scripts write those with a plain truncating write
 # rather than the write-then-rename Cargo uses for real artifacts.
 #
@@ -28,6 +26,8 @@ set -euo pipefail
 script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 . "$script_dir/cache-lib.sh"
 command -v cargo >/dev/null || { echo "SKIP: no cargo on PATH"; exit 0; }
 scratch=$(mktemp -d)
 trap 'rm -rf "$scratch"' EXIT
 pass_count=0
@@ -57,14 +57,6 @@ version = "0.1.0"
 edition = "2021"
 [workspace]
 TOML
  # A binary as well as a library, because the two are written differently and
  # only one of them is safe to share: rustc writes an rlib to a temporary and
  # renames it into place, while the LINKER writes an executable through the
  # existing inode. Without a bin target this suite never relinks anything and
  # cannot see that difference.
  cat > "$dir/src/main.rs" <<'RS'
 fn main() { println!("{}", probe::f()); }
 RS
  cat > "$dir/build.rs" <<'RS'
 use std::{env, fs, path::PathBuf};
 fn main() {
@@ -76,390 +68,26 @@ fn main() {
 RS
 }
 # ---------------------------------------------------------------------------
 # Both build-dir layouts, without a compiler
 # ---------------------------------------------------------------------------
 #
 # Every other scenario in this file runs whichever layout the installed Cargo
 # happens to write, so on any one machine it exercises exactly ONE of the two —
 # and gitdan-ci's is v1. The two fixtures below reproduce both directory shapes
 # from files alone, clone them through the real `hardlink_clone_into()`, and
 # assert file by file which side of the partition each one lands on.
 #
 # Shapes taken from a scratch crate (serde + serde_json + regex, plus a build
 # script) built on 2026-08-27: cargo 1.98.0-nightly (a335d47ff 2026-06-26)
 # writes v1, cargo 1.100.0-nightly (e8cb624d5 2026-08-22) writes v2.
 #
 # v2 is where the partition is easy to get wrong, and the fixtures are built to
 # say so: a build script's OUT_DIR and a compile unit's rlib are BOTH a
 # directory called `out`, one directory apart, and they need opposite
 # treatment.
 mkfile() { mkdir -p "$(dirname "$1")"; printf '%s' "$2" > "$1"; }
 # Big enough that the byte-fraction assertion below measures something.
 artifact_bytes=$(head -c 4096 /dev/zero | tr '\0' 'A')
 # Spec lines are `<shared|private>|<path relative to the tree root>`.
 assert_partition() {
  local label="$1" src="$2" spec="$3"
  local clone="${src}-clone" want rel si ci total=0 copied=0 sz
  hardlink_clone_into "$src" "$clone" "selftest-$label" \
    || fail "$label: hardlink_clone_into refused the destination"
  while IFS='|' read -r want rel; do
    [ -n "${rel:-}" ] || continue
    [ -e "$clone/$rel" ] || fail "$label: $rel is missing from the clone"
    si=$(stat -c '%i' "$src/$rel"); ci=$(stat -c '%i' "$clone/$rel")
    case "$want" in
      shared)
        [ "$si" = "$ci" ] \
          || fail "$label: $rel was real-copied, but it is an artifact and must stay shared" ;;
      private)
        [ "$si" != "$ci" ] \
          || fail "$label: $rel still shares an inode with the source, so a build in the clone can rewrite it" ;;
      *) fail "$label: unknown spec verb '$want'" ;;
    esac
  done <<< "$spec"
  ok "$label: every file landed on the right side of the partition"
  # The cost model, asserted rather than assumed. Selecting too much is not a
  # correctness bug, which is exactly why nothing caught layout v2 taking the
  # selection from 39.3% of one scratch crate's tree to 99.996% of it
  # (gitdan-actions#14):
  # a hardlink clone that real-copies everything is a `cp -a` with extra steps.
  # The bound is loose on purpose. It is not a budget — the honest figure moves
  # with how much of a tree is linker output, and these fixtures are mostly
  # that by construction — it is a floor under "still a hardlink clone at all".
  while IFS= read -r rel; do
    # `.cargo-*lock*` is stripped from every clone by design, so it has no
    # counterpart to compare against.
    [ -e "$clone/$rel" ] || continue
    sz=$(stat -c '%s' "$src/$rel")
    total=$((total + sz))
    [ "$(stat -c '%i' "$src/$rel")" = "$(stat -c '%i' "$clone/$rel")" ] || copied=$((copied + sz))
  done < <(cd "$src" && find . -type f -printf '%P\n')
  [ "$total" -gt 0 ] || fail "$label: fixture has no bytes to measure"
  [ $((copied * 100 / total)) -lt 90 ] \
    || fail "$label: the clone real-copied $((copied * 100 / total))% of its source's bytes — the hardlink saving is gone"
  ok "$label: clone real-copies $((copied * 100 / total))% of ${total} B (${copied} B), the rest is shared"
 }
 # Layout v2: no `.fingerprint`, no `deps`. Everything regroups per build unit
 # under `build/<pkg>/<hash>/{fingerprint,out,run}`, artifacts included — which
 # is what took `-name build` from "the metadata" to "the whole tree".
 #
 # THE THREE UNIT KINDS ARE THE POINT. `1bf...` is a compile unit: its `out`
 # holds the rlib. `08c...` is the build script's own compile unit: its `out`
 # holds the build-script binary. `da9...` is the build-script RUN unit: its
 # `out` IS the OUT_DIR, and it is the only one of the three whose `out` is
 # mutable. The `run/` directory beside it is the structural difference.
 v2="$scratch/layout-v2"
 mkfile "$v2/CACHEDIR.TAG" 'Signature: 8a477f597d28d172'
 mkfile "$v2/.rustc_info.json" '{"rustc_fingerprint":1}'
 mkfile "$v2/debug/.cargo-lock" ''
 mkfile "$v2/debug/libprobe.rlib" "$artifact_bytes"
 mkfile "$v2/debug/libprobe.d" '/probe/src/lib.rs:'
 for f in dep-lib-probe lib-probe lib-probe.json invoked.timestamp; do
  mkfile "$v2/debug/build/probe/1bf5493368dce3cd/fingerprint/$f" "$f"
 done
 mkfile "$v2/debug/build/probe/1bf5493368dce3cd/out/libprobe-1bf5493368dce3cd.rlib" "$artifact_bytes"
 mkfile "$v2/debug/build/probe/1bf5493368dce3cd/out/libprobe-1bf5493368dce3cd.rmeta" "$artifact_bytes"
 mkfile "$v2/debug/build/probe/1bf5493368dce3cd/out/probe-1bf5493368dce3cd.d" '/probe/src/lib.rs:'
 for f in build-script-build-script-build build-script-build-script-build.json \
         dep-build-script-build-script-build invoked.timestamp; do
  mkfile "$v2/debug/build/probe/08c7dda6eacd6dca/fingerprint/$f" "$f"
 done
 mkfile "$v2/debug/build/probe/08c7dda6eacd6dca/out/build_script_build" "$artifact_bytes"
 chmod +x "$v2/debug/build/probe/08c7dda6eacd6dca/out/build_script_build"
 mkfile "$v2/debug/build/probe/08c7dda6eacd6dca/out/build_script_build.d" '/probe/build.rs:'
 # A test binary: the same `out` directory as the rlib above, and the largest
 # thing in a real tree that a linker writes.
 for f in dep-test-lib-probe test-lib-probe test-lib-probe.json invoked.timestamp; do
  mkfile "$v2/debug/build/probe/6a091d813b2be60d/fingerprint/$f" "$f"
 done
 mkfile "$v2/debug/build/probe/6a091d813b2be60d/out/probe-6a091d813b2be60d" "$artifact_bytes"
 chmod +x "$v2/debug/build/probe/6a091d813b2be60d/out/probe-6a091d813b2be60d"
 mkfile "$v2/debug/build/probe/6a091d813b2be60d/out/probe-6a091d813b2be60d.d" '/probe/src/lib.rs:'
 for f in run-build-script-build-script-build run-build-script-build-script-build.json; do
  mkfile "$v2/debug/build/probe/da96cf45111f80dd/fingerprint/$f" "$f"
 done
 mkfile "$v2/debug/build/probe/da96cf45111f80dd/out/gen.txt" 'generated from 24 bytes'
 for f in invoked.timestamp root-output stdout stderr; do
  mkfile "$v2/debug/build/probe/da96cf45111f80dd/run/$f" "$f"
 done
 # A build script that wrote into OUT_DIR and then FAILED: Cargo records the
 # run only on success, so this unit has `out/` populated and no `run/` at all.
 # Reading "no execution record" as "compile unit" left this shared, which is
 # the one state the old `-name build` selection covered and the first cut of
 # this one did not.
 mkfile "$v2/debug/build/probe/f00ded00f00ded00/out/gen.txt" 'half-written'
 mkfile "$v2/debug/incremental/probe-abc/s-xyz/dep-graph.bin" "$artifact_bytes"
 assert_partition "layout v2" "$v2" "$(cat <<'SPEC'
 private|.rustc_info.json
 private|debug/libprobe.d
 private|debug/build/probe/1bf5493368dce3cd/fingerprint/dep-lib-probe
 private|debug/build/probe/1bf5493368dce3cd/fingerprint/lib-probe
 private|debug/build/probe/1bf5493368dce3cd/fingerprint/lib-probe.json
 private|debug/build/probe/1bf5493368dce3cd/fingerprint/invoked.timestamp
 private|debug/build/probe/1bf5493368dce3cd/out/probe-1bf5493368dce3cd.d
 private|debug/build/probe/08c7dda6eacd6dca/fingerprint/dep-build-script-build-script-build
 private|debug/build/probe/08c7dda6eacd6dca/fingerprint/invoked.timestamp
 private|debug/build/probe/08c7dda6eacd6dca/out/build_script_build.d
 private|debug/build/probe/da96cf45111f80dd/fingerprint/run-build-script-build-script-build
 private|debug/build/probe/da96cf45111f80dd/out/gen.txt
 private|debug/build/probe/da96cf45111f80dd/run/root-output
 private|debug/build/probe/da96cf45111f80dd/run/stdout
 private|debug/build/probe/da96cf45111f80dd/run/stderr
 private|debug/build/probe/da96cf45111f80dd/run/invoked.timestamp
 private|debug/build/probe/f00ded00f00ded00/out/gen.txt
 shared|debug/libprobe.rlib
 shared|debug/build/probe/1bf5493368dce3cd/out/libprobe-1bf5493368dce3cd.rlib
 shared|debug/build/probe/1bf5493368dce3cd/out/libprobe-1bf5493368dce3cd.rmeta
 private|debug/build/probe/08c7dda6eacd6dca/out/build_script_build
 private|debug/build/probe/6a091d813b2be60d/out/probe-6a091d813b2be60d
 private|debug/build/probe/6a091d813b2be60d/out/probe-6a091d813b2be60d.d
 private|debug/build/probe/6a091d813b2be60d/fingerprint/dep-test-lib-probe
 shared|debug/incremental/probe-abc/s-xyz/dep-graph.bin
 SPEC
 )"
 # Layout v1: one `.fingerprint` and one `deps` per profile; `build/<pkg>-<hash>`
 # holds the build script's compiled binary in one unit directory and its run
 # metadata plus OUT_DIR in another.
 v1="$scratch/layout-v1"
 mkfile "$v1/CACHEDIR.TAG" 'Signature: 8a477f597d28d172'
 mkfile "$v1/.rustc_info.json" '{"rustc_fingerprint":1}'
 mkfile "$v1/debug/.cargo-lock" ''
 mkfile "$v1/debug/libprobe.rlib" "$artifact_bytes"
 mkfile "$v1/debug/libprobe.d" '/probe/src/lib.rs:'
 mkfile "$v1/debug/deps/libprobe-1bf5493368dce3cd.rlib" "$artifact_bytes"
 mkfile "$v1/debug/deps/libprobe-1bf5493368dce3cd.rmeta" "$artifact_bytes"
 mkfile "$v1/debug/deps/probe-1bf5493368dce3cd.d" '/probe/src/lib.rs:'
 # A test binary, which layout v1 leaves in `deps/` beside the rlibs.
 mkfile "$v1/debug/deps/probe-6a091d813b2be60d" "$artifact_bytes"
 chmod +x "$v1/debug/deps/probe-6a091d813b2be60d"
 mkfile "$v1/debug/deps/probe-6a091d813b2be60d.d" '/probe/src/lib.rs:'
 for f in dep-lib-probe lib-probe lib-probe.json invoked.timestamp; do
  mkfile "$v1/debug/.fingerprint/probe-1bf5493368dce3cd/$f" "$f"
 done
 mkfile "$v1/debug/build/probe-08c7dda6eacd6dca/build-script-build" "$artifact_bytes"
 mkfile "$v1/debug/build/probe-08c7dda6eacd6dca/build_script_build-08c7dda6eacd6dca" "$artifact_bytes"
 chmod +x "$v1/debug/build/probe-08c7dda6eacd6dca/build-script-build" \
         "$v1/debug/build/probe-08c7dda6eacd6dca/build_script_build-08c7dda6eacd6dca"
 mkfile "$v1/debug/build/probe-08c7dda6eacd6dca/build_script_build-08c7dda6eacd6dca.d" '/probe/build.rs:'
 for f in invoked.timestamp output root-output stderr; do
  mkfile "$v1/debug/build/probe-da96cf45111f80dd/$f" "$f"
 done
 mkfile "$v1/debug/build/probe-da96cf45111f80dd/out/gen.txt" 'generated from 24 bytes'
 # The same never-succeeded build script under layout v1.
 mkfile "$v1/debug/build/probe-f00ded00f00ded00/out/gen.txt" 'half-written'
 mkfile "$v1/debug/incremental/probe-abc/s-xyz/dep-graph.bin" "$artifact_bytes"
 assert_partition "layout v1" "$v1" "$(cat <<'SPEC'
 private|.rustc_info.json
 private|debug/libprobe.d
 private|debug/deps/probe-1bf5493368dce3cd.d
 private|debug/.fingerprint/probe-1bf5493368dce3cd/dep-lib-probe
 private|debug/.fingerprint/probe-1bf5493368dce3cd/lib-probe
 private|debug/.fingerprint/probe-1bf5493368dce3cd/lib-probe.json
 private|debug/.fingerprint/probe-1bf5493368dce3cd/invoked.timestamp
 private|debug/build/probe-08c7dda6eacd6dca/build_script_build-08c7dda6eacd6dca.d
 private|debug/deps/probe-6a091d813b2be60d
 private|debug/deps/probe-6a091d813b2be60d.d
 private|debug/build/probe-da96cf45111f80dd/invoked.timestamp
 private|debug/build/probe-da96cf45111f80dd/output
 private|debug/build/probe-da96cf45111f80dd/root-output
 private|debug/build/probe-da96cf45111f80dd/stderr
 private|debug/build/probe-da96cf45111f80dd/out/gen.txt
 private|debug/build/probe-f00ded00f00ded00/out/gen.txt
 shared|debug/libprobe.rlib
 shared|debug/deps/libprobe-1bf5493368dce3cd.rlib
 shared|debug/deps/libprobe-1bf5493368dce3cd.rmeta
 private|debug/build/probe-08c7dda6eacd6dca/build-script-build
 private|debug/build/probe-08c7dda6eacd6dca/build_script_build-08c7dda6eacd6dca
 shared|debug/incremental/probe-abc/s-xyz/dep-graph.bin
 SPEC
 )"
 echo
 command -v cargo >/dev/null || {
  echo "SKIP: no cargo on PATH — the fixture scenarios above ran, the live-Cargo ones cannot"
  echo "hardlink-clone-selftest: ${pass_count} assertions passed"
  exit 0
 }
 crate_dir="$scratch/probe"
 mkcrate "$crate_dir"
 cd "$crate_dir"
 export CARGO_INCREMENTAL=0
 # Every assertion below reads cargo's own words out of a build log
 # (`Compiling libdep`, `Fresh probe`). A CI image that forces colour splices an
 # ANSI reset between the status word and the crate name, at which point every
 # one of those greps silently stops matching and the suite reports the
 # opposite of what happened — observed on gitdan-ci's runner image, where
 # scenario 2 failed while the log it printed plainly showed `Compiling libdep`.
 # Pin the format the assertions are written against.
 export CARGO_TERM_COLOR=never
 # Checksum freshness is where the worst failure lives (the dep-* file carries
 # per-source checksums and is rewritten in place). Only available on nightly;
 # without it the test still covers the build/ and *.d families.
 CONTENT_A='pub fn f() -> u32 { 1 }'
 CONTENT_B='pub fn f() -> u32 { 22222 } pub fn g() -> u32 { 7 }'
 # Probe the BEHAVIOUR, not the channel and not the flag. Two weaker probes
 # were tried against gitdan-ci's runner and each let the suite assert a
 # property the toolchain did not have:
 #
 #   `cargo +nightly -V`                     — answers "did a proxy called with
 #                                             +nightly exit 0". `-V`
 #                                             short-circuits before `-Z` is
 #                                             even parsed.
 #   `cargo +nightly -Z checksum-freshness   — answers "is this flag still
 #    locate-project`                          accepted", which since cargo PR
 #                                             #17382 (2026-08-22) is a
 #                                             different question from "is
 #                                             content freshness on". That PR
 #                                             demoted the flag to a gate and
 #                                             gave `build.fingerprint` the
 #                                             choice, defaulting to `mtime` —
 #                                             so 1.100.0-nightly accepts the
 #                                             flag and resolves freshness by
 #                                             mtime unless
 #                                             CARGO_BUILD_FINGERPRINT=content
 #                                             is set too. Measured 2026-08-26;
 #                                             see daniel/gitdan#62.
 #
 # The scenario at the end of this file depends on one thing and it is neither
 # of those: that changed content with an OLDER mtime rebuilds. Under mtime
 # freshness the correct answer is Fresh, so under mtime freshness that
 # scenario asserts a bug. So the probe simply performs that experiment, on its
 # own crate and its own target dir, with no clone anywhere near it — which is
 # also what makes it a control rather than a restatement of the scenario: the
 # probe establishes that the toolchain rebuilds on content, the scenario
 # establishes that a hardlink clone did not take that away.
 # THREE OUTCOMES, NOT TWO. An experiment that cannot tell a negative result
 # from a failed measurement is not settling the question, and the two are not
 # interchangeable here: "this toolchain resolves freshness by mtime" is a
 # statement about Cargo, while "a probe build failed" is a statement about this
 # machine. Collapsing them — which an earlier cut of this did, by returning
 # non-zero for both — makes a half-installed toolchain print a confident and
 # wrong explanation and quietly drop a scenario. The scenario still has to be
 # skipped in either case; what must not happen is the log claiming to know why.
 #
 #   0  content freshness measured ACTIVE   — both builds ran, the backdated
 #                                            rebuild recompiled
 #   3  measured INACTIVE                   — both builds ran, the backdated
 #                                            rebuild reported Fresh
 #   anything else  NOT MEASURED            — nothing was learned about the
 #                                            toolchain
 #
 # THE ANSWER CODES ARE 0 AND 3, AND THE GAP IS THE MECHANISM. Bash produces 1
 # for an ordinary command failure, 2 for a usage error, 126/127 for a command
 # it could not run, 128+n for a signal, and — this is the one that matters —
 # 1 for an unbound-variable or other EXPANSION failure, which happens before
 # the command runs and is therefore invisible to a `||` guard and to an ERR
 # trap alike. It never produces 3. So "not an answer code" is decided by a
 # property of the shell rather than by an enumeration of the ways a step can
 # go wrong, and a step added later without a guard, or with a guard that
 # cannot fire, lands on NOT MEASURED by construction.
 #
 # That is the whole reason INACTIVE is not 1. It was, and three review rounds
 # on this function each found a narrower way for a shell-generated 1 to be read
 # as a measurement — an unguarded command, then a typo'd variable name on a
 # line that HAS its guard. Each was closed by narrowing the failure surface,
 # which is a game with no last move. Moving the answer off the codes bash can
 # generate ends it instead: there is no longer a mutation that turns an error
 # into an answer, only mutations that turn an error into a different error.
 #
 # The guards below stay, and so does the trap, but their job is now reporting
 # rather than correctness: they make a failed step land on 2 with its logs
 # printed instead of on some incidental status, which is nicer to debug and
 # lands in the same place either way.
 #
 # One piece of that reporting layer is load-bearing and not obvious. A command
 # on the left of `||` — or in an `if` condition — runs with errexit suppressed,
 # and that suppression propagates into a subshell and is NOT undone by a
 # `set -e` inside it (measured on bash 5.3: an unguarded `false` there falls
 # through to `exit 0`). Calling with errexit disarmed at the site is the only
 # form that lets the subshell re-arm it; hence the `set +e` bracket. The ERR
 # trap is then required on top, because a bare `set -e` abort exits with the
 # FAILING COMMAND's status, and `false` gives 1.
 #
 # WHY NOT-MEASURED SKIPS RATHER THAN FAILS. The scenario it gates is the only thing in
 # this suite that depends on freshness mode; everything else still runs and
 # still catches real regressions. Failing instead would turn a statement about
 # one machine's toolchain into a red gate reading "the hardlink scheme is
 # broken" across the three repos consuming this action — the same category
 # error the three-state split exists to prevent, one level up. What would
 # change the answer is not-measured becoming the everyday CI outcome; it is not
 # — gitdan-ci's outcome is a measurement either way. It reported a measured
 # INACTIVE until 2026-08-26, for the reason recorded at the `export` below, and
 # an ACTIVE once both switches were set.
 CHECKSUM_MODE="off"
-CHECKSUM_REASON="no nightly on PATH accepting -Z checksum-freshness"
+if cargo +nightly -V >/dev/null 2>&1; then
 CARGO_BIN=(cargo)
 checksum_freshness_probe() {
  local d="$scratch/freshness-probe" t="$scratch/freshness-probe-target"
  mkcrate "$d" || return 2  # 2 is simply "not 0 and not 3"; see the header
  (
    set -e
    trap 'exit 2' ERR
    cd "$d" || exit 2
    printf '%s\n' "$CONTENT_A" > src/lib.rs || exit 2
    CARGO_TARGET_DIR="$t" cargo +nightly build -q > "$scratch/freshness-probe-warm.log" 2>&1 || exit 2
    printf '%s\n' "$CONTENT_B" > src/lib.rs || exit 2
    touch -d '@1000000000' src/lib.rs || exit 2
    CARGO_TARGET_DIR="$t" cargo +nightly build -v > "$scratch/freshness-probe.log" 2>&1 || exit 2
    # 3, not 1: see the header. This is the only statement in the subshell that
    # may report a measurement, and it is the only one that may exit 3.
    if grep -qE '^\s+Fresh probe' "$scratch/freshness-probe.log"; then exit 3; fi
    exit 0
  )
 }
 if cargo +nightly -Z checksum-freshness locate-project > /dev/null 2>&1; then
  export CARGO_UNSTABLE_CHECKSUM_FRESHNESS=true
  # BOTH, since cargo PR #17382 (2026-08-22): the -Z flag only unlocks the
  # feature and `build.fingerprint` selects it, defaulting to `mtime`. Setting
  # the gate alone is what made this suite report a measured INACTIVE on
  # 1.100.0-nightly and skip its strongest scenario (daniel/gitdan#62). Safe to
  # export unconditionally — a Cargo that does not know the key ignores it
  # silently, verified 2026-08-26 on 1.93.1 stable and 1.96.0-nightly, both of
  # which still measure ACTIVE from the gate alone.
  export CARGO_BUILD_FINGERPRINT=content
  # Errexit off across the call, so the subshell can arm its own — see the
  # header. `probe_rc` is read before it is restored.
  probe_rc=0
  set +e
  checksum_freshness_probe
  probe_rc=$?
  set -e
  case "$probe_rc" in
    0)
  CARGO_BIN=(cargo +nightly)
  CHECKSUM_MODE="on"
-      CHECKSUM_REASON=""
+else
-      ;;
+  CARGO_BIN=(cargo)
    3)
      unset CARGO_UNSTABLE_CHECKSUM_FRESHNESS CARGO_BUILD_FINGERPRINT
      CHECKSUM_REASON="this nightly accepts -Z checksum-freshness and build.fingerprint=content but still resolves freshness by mtime"
      ;;
    *)
      unset CARGO_UNSTABLE_CHECKSUM_FRESHNESS CARGO_BUILD_FINGERPRINT
      CHECKSUM_MODE="unmeasured"
      CHECKSUM_REASON="the probe exited ${probe_rc}, which is not one of its answer codes, so this was NOT MEASURED — this toolchain may or may not resolve freshness by content"
      # Loud, because the cost is silently lost coverage on a machine that
      # might have had it. The suite continues: everything else it asserts is
      # independent of freshness mode.
      echo "::warning::hardlink-clone-selftest: could not measure whether this toolchain resolves freshness by content — the probe exited ${probe_rc}. This is a failure to measure, not a finding about Cargo."
      tail -n 15 "$scratch/freshness-probe-warm.log" "$scratch/freshness-probe.log" 2>/dev/null | sed 's/^/    /' >&2 || true
      ;;
  esac
 fi
-cd "$crate_dir"
+echo "=== checksum-freshness mode: ${CHECKSUM_MODE} ==="
-echo "=== checksum-freshness mode: ${CHECKSUM_MODE}${CHECKSUM_REASON:+ — ${CHECKSUM_REASON}} ==="
+
 CONTENT_A='pub fn f() -> u32 { 1 }'
 CONTENT_B='pub fn f() -> u32 { 22222 } pub fn g() -> u32 { 7 }'
 build_base() {
  local dir="$1"
@@ -484,35 +112,11 @@ fi
 ok "raw cp -al clone mutates the source ($(printf '%s\n' "$ctl_mutated" | wc -l) paths)"
 printf '%s\n' "$ctl_mutated" | sed 's/^/       /'
 # Reported, not asserted, and the distinction is the point. The control's job
 # is to prove the hazard exists at all, which the non-empty set above already
 # does; this line records WHICH families a given Cargo exhibits.
 #
 # The dep-info file is the worst of them — it carries the per-source
 # checksums, so mutating it through a shared inode turns a hardlink clone into
 # silent stale-artifact reuse rather than a slow build. Failing on its absence
 # would mean this suite goes red whenever upstream stops doing something we
 # never wanted it to do — and it would go red in the CONTROL, where a failure
 # reads as "the hazard is gone" rather than "upstream changed". Nothing is lost
 # by reporting it: the fix scenario below asserts the source is byte-identical
 # after a full rebuild in the clone, which covers every family this Cargo has,
 # named or not.
 #
 # THE PATTERN MUST MATCH BOTH LAYOUTS, and that is not a detail. Cargo's
 # build-dir layout v2 moved the file from `<profile>/.fingerprint/<unit>/dep-*`
 # to `<profile>/build/<pkg>/<hash>/fingerprint/dep-*` (stabilised by cargo PR
 # #17354, cargo 1.100.0, stable 2026-11-12; nightly default since 1.99). An
 # earlier cut of this line looked for the v1 path only, so on 2026-08-26,
 # against 1.100.0-nightly with content freshness genuinely on, it printed
 # "does NOT rewrite ... in place" directly beneath a control listing that
 # showed the rewrite. A reporting line that can contradict the data three
 # lines above it is worse than no line at all. `fingerprint/.*dep-` matches
 # either layout and neither `.d` family.
 if [ "$CHECKSUM_MODE" = "on" ]; then
-  if printf '%s' "$ctl_mutated" | grep -q 'fingerprint/.*dep-'; then
+  if printf '%s' "$ctl_mutated" | grep -q '\.fingerprint/.*/dep-'; then
-    echo "  note: this cargo DOES rewrite its dep-info fingerprint file in place under content freshness"
+    ok "control confirms the checksum-freshness dep-info file is among the mutated set"
  else
-    echo "  note: this cargo does NOT rewrite its dep-info fingerprint file in place; only the build/ and *.d families appear above"
+    fail "expected .fingerprint/*/dep-* in the control's mutated set under checksum freshness"
  fi
 fi
@@ -523,44 +127,27 @@ build_base "$base_fix"
 before=$(snapshot_tree "$base_fix")
 hardlink_clone_into "$base_fix" "$clone_fix" "selftest" || fail "hardlink_clone_into reported the destination already existed"
-# The clone's contract, asserted before anything builds in it and asserted in
+# The clone's contract, asserted before anything builds in it: artifacts
-# BOTH directions: every file Cargo rewrites in place is privately owned (that
+# share inodes (that is what makes the clone near-free), and every file Cargo
-# is what makes the clone sound), and every artifact still shares its inode
+# rewrites in place does not (that is what makes it sound). Checking after a
-# (that is what makes it near-free). Checking after a rebuild would prove
+# rebuild would prove nothing — the rebuild replaces those files anyway.
-# nothing — the rebuild replaces those files anyway.
+shared=0; unshared=0
 #
 # The mutable-family patterns cover both layouts: `.fingerprint/` is v1's,
 # `fingerprint/` and `run/` are v2's, and `gen.txt` is this crate's build
 # script's OUT_DIR product, which under v2 sits in a directory called `out`
 # beside sibling units whose `out` holds artifacts.
 shared=0; unshared=0; shared_bytes=0; copied_bytes=0
 while IFS= read -r f; do
-  rel="${f#"$base_fix"/}"
+  rel="${f#$base_fix/}"
  [ -e "$clone_fix/$rel" ] || continue
  sz=$(stat -c '%s' "$f")
  if [ "$(stat -c '%i' "$f")" = "$(stat -c '%i' "$clone_fix/$rel")" ]; then
    case "$rel" in
-      */.fingerprint/*|*/fingerprint/*|*/run/*|*/out/gen.txt|*/output|*/root-output|*/stderr|*/invoked.timestamp|*.d|.rustc_info.json)
+      */.fingerprint/*|*/build/*|*.d|.rustc_info.json)
        fail "mutable path still shares an inode with the source: $rel" ;;
    esac
-    shared=$((shared + 1)); shared_bytes=$((shared_bytes + sz))
+    shared=$((shared + 1))
  else
-    case "$rel" in
+    unshared=$((unshared + 1))
      *.rlib|*.rmeta)
        fail "artifact was real-copied rather than shared: $rel" ;;
    esac
    unshared=$((unshared + 1)); copied_bytes=$((copied_bytes + sz))
  fi
 done < <(find "$base_fix" -type f)
 [ "$shared" -gt 0 ] || fail "nothing is shared — the clone degenerated into a full copy"
 [ "$unshared" -gt 0 ] || fail "nothing was unshared — unshare_mutable_paths did not run"
 total_bytes=$((shared_bytes + copied_bytes))
 ok "fresh clone shares ${shared} artifact files and privately owns ${unshared} mutable ones"
 # Reported, not asserted. This crate has no dependencies, so almost all of its
 # bytes are the two executables — a ratio that says nothing about a real tree.
 # The fixtures above are where the cost model is gated, because there the
 # composition is fixed.
 echo "  note: this clone real-copies $((copied_bytes * 100 / total_bytes))% of ${total_bytes} B"
 printf '%s\n' "$CONTENT_B" > src/lib.rs
 CARGO_TARGET_DIR="$clone_fix" "${CARGO_BIN[@]}" build -q
@@ -574,105 +161,10 @@ fi
 ok "no file in the source changed after a full rebuild in the clone"
 echo
 echo "=== a linked TEST binary, which nothing uplifts and nothing replaces ==="
 # The one artifact family that is NOT safe to share, and the reason
 # `unshare_mutable_paths` privately owns every executable. rustc writes an
 # rlib to a temporary and renames it in; the LINKER writes an executable
 # through whatever inode is already at the path.
 #
 # THE CRATE SHAPE IS LOAD-BEARING AND WAS WRONG ONCE. An earlier cut of this
 # scenario reused the lib+bin probe crate above, whose test binaries relink to
 # a FRESH inode — a shape gitdan-actions#17 records as measured safe. Both
 # halves then passed green against the unfixed selection, on the strength of
 # dep-info mutations the previous scenario already covers, and the scenario
 # pinned nothing. A bin-only crate with a unit test does exhibit the rewrite,
 # on cargo 1.93.1 stable and on 1.98.0-nightly and 1.100.0-nightly, so that is
 # what this builds. The shape is chosen by measurement rather than derived:
 # what separates a rewritten executable from an intact one is not established,
 # so the only crate shape this scenario may rest on is one observed to exhibit
 # the rewrite.
 mkbincrate() {
  local dir="$1" marker="$2"
  mkdir -p "$dir/src"
  cat > "$dir/Cargo.toml" <<'TOML'
 [package]
 name = "binprobe"
 version = "0.1.0"
 edition = "2021"
 [workspace]
 TOML
  cat > "$dir/src/main.rs" <<RS
 fn main() { println!("${marker}"); }
 #[cfg(test)]
 mod t { #[test] fn a() { assert_eq!("${marker}".len() > 0, true); } }
 RS
 }
 bin_dir="$scratch/binprobe"
 mkbincrate "$bin_dir" MARKER_AAAA
 cd "$bin_dir"
 base_exe="$scratch/base-exe"; clone_exe_ctl="$scratch/clone-exe-ctl"; clone_exe="$scratch/clone-exe"
 # Only the executables are read here. The families the other scenarios cover
 # would satisfy a "something changed" assertion on their own, which is exactly
 # how the earlier cut of this passed while pinning nothing.
 source_exe_digest() {
  (cd "$1" && find . -type f -executable -print0 | sort -z | xargs -0 -r sha1sum) 2>/dev/null
 }
 CARGO_TARGET_DIR="$base_exe" "${CARGO_BIN[@]}" test --no-run -q > /dev/null 2>&1 \
  || fail "the bin-only probe crate failed to build"
 before=$(source_exe_digest "$base_exe")
 cp -al "$base_exe" "$clone_exe_ctl"
 strip_cargo_locks "$clone_exe_ctl"
 mkbincrate "$bin_dir" MARKER_BBBB
 CARGO_TARGET_DIR="$clone_exe_ctl" "${CARGO_BIN[@]}" test --no-run -q > /dev/null 2>&1
 exe_ctl_mutated=$(mutated_paths "$before" "$(source_exe_digest "$base_exe")")
 # THREE OUTCOMES, as the freshness probe above has, and for the same reason: a
 # scenario that cannot tell "the fix works" from "the hazard never fired" is
 # not a gate. If this Cargo does not rewrite the source's test binary, the
 # assertion below would pass for a toolchain reason rather than a code one, so
 # it is skipped LOUDLY instead of passing quietly.
 if [ -z "$exe_ctl_mutated" ]; then
  echo "::warning::hardlink-clone-selftest: this toolchain did not rewrite the source's test binary through a raw cp -al clone, so the linked-output scenario proves nothing here and was SKIPPED. That is a statement about this Cargo, not about unshare_mutable_paths."
 else
  ok "control: a raw cp -al clone rewrites the source's own linked test binary"
  printf '%s\n' "$exe_ctl_mutated" | sed 's/^/       /'
  # Rebuild the base from the original marker so it is warm and consistent
  # again, then do the same thing through the real clone.
  mkbincrate "$bin_dir" MARKER_AAAA
  CARGO_TARGET_DIR="$base_exe" "${CARGO_BIN[@]}" test --no-run -q > /dev/null 2>&1
  before=$(snapshot_tree "$base_exe")
  hardlink_clone_into "$base_exe" "$clone_exe" "selftest-exe" \
    || fail "hardlink_clone_into refused the destination"
  mkbincrate "$bin_dir" MARKER_BBBB
  CARGO_TARGET_DIR="$clone_exe" "${CARGO_BIN[@]}" test --no-run -q > /dev/null 2>&1
  exe_mutated=$(mutated_paths "$before" "$(snapshot_tree "$base_exe")")
  if [ -n "$exe_mutated" ]; then
    printf '%s\n' "$exe_mutated" | sed 's/^/       /' >&2
    fail "a test build in the clone mutated the source through a shared inode"
  fi
  ok "no file in the source changed after a full test build in the clone"
 fi
 cd "$crate_dir"
 echo
 if [ "$CHECKSUM_MODE" = "on" ]; then
 echo "=== the whole point: the source's next build is still correct ==="
-  # The source's cache holds artifacts built from CONTENT_A. Advance the
+# The source's cache holds artifacts built from CONTENT_A. Advance the source
-  # source to CONTENT_B (as a merge would) and rebuild in it. If the clone had
+# to CONTENT_B (as a merge would) and rebuild in it. If the clone had
 # corrupted its dep-info, Cargo would report Fresh and keep the stale rlib.
  #
  # CHECKSUM-FRESHNESS ONLY, and the backdated mtime is why. Under checksum
  # freshness the dep-info file's per-source checksums decide, so a 2001
  # timestamp on changed content must still rebuild — the assertion below.
  # Under Cargo's ordinary MTIME freshness the same timestamp means the source
  # is older than the artifact, and reporting Fresh is the correct answer;
  # asserting otherwise asserts a bug. This scenario was written against a
  # machine with a nightly installed and, run without one, failed on that
  # correct answer.
 printf '%s\n' "$CONTENT_B" > src/lib.rs
 touch -d '@1000000000' src/lib.rs
 log="$scratch/rebuild.log"
@@ -681,10 +173,6 @@ if [ "$CHECKSUM_MODE" = "on" ]; then
  fail "source declared its own crate Fresh against sources it has never built — stale-artifact reuse"
 fi
 ok "source correctly rebuilt its crate after advancing to the clone's content"
 else
  echo "=== skipped: the source's-next-build scenario needs content-based freshness ==="
  echo "  reason: ${CHECKSUM_REASON}"
 fi
 echo
 echo "hardlink-clone-selftest: ${pass_count} assertions passed"
@@ -46,36 +46,10 @@
 #      empty a tree its owner may still restore under a live cache name. Its
 #      fixture is an OLD directory renamed a moment ago — production's shape,
 #      and what lets it tell the two timestamps apart.
 #  15. A MERGED-BUT-UNDELETED BRANCH IS DEAD TOO. A branch the forge did not
 #      delete at merge stays on `ls-remote` forever, so scenario 1's signal
 #      never fires for it — which is how three 40 GB caches sat on a full
 #      volume until somebody removed them by hand (gitdan-actions#20). A
 #      branch whose tip is an ancestor of a protected branch's tip is pruned
 #      like a deleted one; an unmerged branch beside it is not.
 #  16. AND "CANNOT TELL" IS STILL NOT DEATH, at both granularities: a branch
 #      whose tip is not in this checkout is kept with a warning naming it,
 #      and a shallow checkout — where a missing object is the normal case —
 #      withholds the whole signal rather than reading it as "nothing merged".
 #      The deleted-branch signal keeps working in both.
 #  17. THE FREE-SPACE REQUIREMENT IS MEASURED OFF THE SOURCE, not taken as a
 #      percentage of the volume: the pass evicts until the clone the seed is
 #      about to make fits, and stops there rather than draining the volume.
 #      When it cannot get there it FAILS, naming the shortfall and every
 #      directory it kept instead — because the seed would otherwise fail
 #      seconds later against a staging path that names nothing.
 #  18. AND ON THE LAYOUT THAT PRODUCED THE BUG: three equal-sized caches, one
 #      of them a merged-but-undeleted branch's, with disk to spare. Exactly
 #      that one goes. Equal sizes and no pressure are the point — nothing but
 #      the merge state can be what decides.
 set -euo pipefail
 script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 . "$script_dir/cache-lib.sh"
 prune="$script_dir/prune-cache.sh"
 # Two scenarios below put a stub of a real tool on PATH for one command.
 # Captured once, here, rather than read back at each of those sites: a `$PATH`
 # read after the first of them is indistinguishable, to a static check, from
 # reading the modification the subshell lost.
 outer_path="$PATH"
 scratch=$(mktemp -d)
 trap 'rm -rf "$scratch"' EXIT
@@ -91,10 +65,10 @@ origin="$scratch/origin.git"; git init -q --bare "$origin"
 work="$scratch/work"; git init -q "$work"
 (
  cd "$work"
-  git -c user.email=t@t -c user.name=t -c commit.gpgsign=false commit -q --allow-empty -m init
+  git -c user.email=t@t -c user.name=t commit -q --allow-empty -m init
  git branch -M main
-  git checkout -q -b dev; git -c user.email=t@t -c user.name=t -c commit.gpgsign=false commit -q --allow-empty -m dev
+  git checkout -q -b dev; git -c user.email=t@t -c user.name=t commit -q --allow-empty -m dev
-  git checkout -q -b feat/live; git -c user.email=t@t -c user.name=t -c commit.gpgsign=false commit -q --allow-empty -m live
+  git checkout -q -b feat/live; git -c user.email=t@t -c user.name=t commit -q --allow-empty -m live
  git remote add origin "$origin"
  git push -q origin main dev feat/live
 )
@@ -261,7 +235,7 @@ done
 exec "$real_du" "\$@"
 EOF
 chmod +x "$scratch/bin/du"
-( PATH="$scratch/bin:$outer_path"; run_prune "1000000 900000" )
+( PATH="$scratch/bin:$PATH"; run_prune "1000000 900000" )
 [ -e "$root/.reading-target-$DEAD-racer" ] || fail "the racing marker was never published — scenario 12 proves nothing"
 assert_kept "$root/target-$DEAD" "a cache claimed inside the eviction window is not unlinked"
 assert_kept "$root/target-$DEAD/blob" "the reprieved cache still has its contents"
@@ -312,172 +286,5 @@ assert_kept "$aside" "an aside younger than the settle window is not reclaimed"
 assert_kept "$aside/blob" "and is left intact, not part-way emptied"
 assert_log "may still be evicting it" "the deferral gives its actual reason"
 echo
 echo "=== 15: a merged-but-undeleted branch is dead too ==="
 # A branch the forge did not delete at merge, which `ls-remote` then reports
 # forever. Built the way that happens: a branch merged into dev with a merge
 # commit, still pushed, beside one branched at the same point and NOT merged.
 git="git -c user.email=t@t -c user.name=t -c commit.gpgsign=false"
 (
  cd "$work"
  git checkout -q dev
  git checkout -q -b feat/merged
  $git commit -q --allow-empty -m merged
  git checkout -q dev
  $git merge -q --no-ff feat/merged -m "merge feat/merged"
  git checkout -q -b feat/unmerged
  $git commit -q --allow-empty -m unmerged
  git checkout -q dev
  git push -q origin dev feat/merged feat/unmerged
 )
 MERGED=$(cache_key feat/merged); UNMERGED=$(cache_key feat/unmerged)
 reset_cache
 mk "target-$MERGED"   '2030-01-01'
 mk "snapshot-$MERGED" '2030-01-01'
 mk "target-$UNMERGED" '2020-01-01'   # older, deliberately: merge state decides, not age
 run_prune "1000000 900000"           # 90% free: no pressure at all
 assert_log "merged-branch detection anchored on" "the pass says what it anchored ancestry on"
 assert_gone "$root/target-$MERGED" "a merged branch's cache is pruned though its branch is still on origin"
 assert_gone "$root/snapshot-$MERGED" "and so is its snapshot"
 assert_kept "$root/target-$UNMERGED" "an unmerged branch's cache survives, though it is the older of the two"
 assert_log "merged into dev" "the eviction names the branch it was merged into"
 echo
 echo "=== 16: 'cannot tell' is not death, per branch and per checkout ==="
 # A branch whose tip this checkout has never seen. Pushed from a second clone,
 # so `ls-remote` reports a SHA that `$work` holds no object for — which is
 # what "cannot determine" actually looks like, rather than a stubbed failure.
 other="$scratch/other"; git clone -q "$origin" "$other"
 (
  cd "$other"
  git checkout -q -b feat/elsewhere origin/dev
  git -c user.email=t@t -c user.name=t -c commit.gpgsign=false commit -q --allow-empty -m elsewhere
  git push -q origin feat/elsewhere
 )
 ELSEWHERE=$(cache_key feat/elsewhere)
 reset_cache
 mk "target-$ELSEWHERE" '2030-01-01'
 mk "target-$MERGED"    '2030-01-01'
 run_prune "1000000 900000"
 assert_kept "$root/target-$ELSEWHERE" "a branch whose tip is not in this checkout is kept, not classified dead"
 assert_log "cannot tell merged from live" "and the undecidable branch is named, not silently skipped"
 assert_gone "$root/target-$MERGED" "while a branch it CAN decide is still pruned in the same pass"
 # A shallow checkout, where a missing object is the ordinary case rather than
 # a signal — so the whole merged half is withheld. The deleted-branch half is
 # unaffected, which is what keeps this a narrowing rather than an outage.
 shallow="$scratch/shallow"; git clone -q --depth 1 -b dev "file://$origin" "$shallow"
 [ "$(git -C "$shallow" rev-parse --is-shallow-repository)" = true ] \
  || fail "the fixture clone is not shallow — scenario 16's second half proves nothing"
 reset_cache
 mk "target-$MERGED" '2030-01-01'
 (
  cd "$shallow"
  CACHE_DF_OVERRIDE="1000000 900000" GITHUB_STEP_SUMMARY="$scratch/summary" \
    bash "$prune" "$root" "$root/target-$OWN" "dev main" 10
 ) > "$scratch/log" 2>&1 || { cat "$scratch/log"; fail "prune-cache.sh exited non-zero in a shallow checkout"; }
 assert_log "checkout is shallow" "a shallow checkout withholds the merged signal and says why"
 assert_kept "$root/target-$MERGED" "and keeps a merged branch's cache rather than guessing"
 assert_gone "$root/target-$DEAD" "while the deleted-branch signal still fires"
 echo
 echo "=== 17: the free-space requirement is measured off the clone's source ==="
 # A `df` that answers from the cache root's actual size, because the property
 # under test is that the pass STOPS once the requirement is met — which a
 # fixed CACHE_DF_OVERRIDE cannot express, since evicting never changes it.
 mkdir -p "$scratch/bin17"
 real_du=$(command -v du)
 build_seed_fixture() {
  rm -rf "$root"; mkdir -p "$root"
  # The source the seed is about to clone. 8 MB of dep-info, which
  # unshare_mutable_paths has to real-copy, beside 16 MB of .rlib that it
  # leaves hardlinked — so a requirement derived from the SIZE of the source
  # would be three times the one derived from its mutable set.
  mkdir -p "$root/snapshot-$DEV/debug/.fingerprint/unit" "$root/snapshot-$DEV/debug/deps"
  head -c $((8 * 1024 * 1024)) /dev/zero > "$root/snapshot-$DEV/debug/.fingerprint/unit/dep-lib"
  head -c $((16 * 1024 * 1024)) /dev/zero > "$root/snapshot-$DEV/debug/deps/libx.rlib"
  touch -d '2020-01-01' "$root/snapshot-$DEV/.cache-last-used"
  # Three live, unmerged branches' caches of 4 MB each, oldest first.
  local i=0
  for b in a b c; do
    i=$((i + 1))
    mkdir -p "$root/target-$(cache_key "feat/$b")"
    head -c $((4 * 1024 * 1024)) /dev/zero > "$root/target-$(cache_key "feat/$b")/blob"
    touch -d "202${i}-01-01" "$root/target-$(cache_key "feat/$b")/.cache-last-used"
  done
  # A volume with 2 MB to spare: under the requirement, over nothing else.
  cap=$(( $($real_du -sk "$root" | awk '{print $1}') + 2048 ))
  cat > "$scratch/bin17/df" <<DFEOF
 #!/usr/bin/env bash
 used=\$($real_du -sk "$root" | awk '{print \$1}')
 echo "Filesystem 1024-blocks Used Available Capacity Mounted-on"
 echo "fake $cap \$used \$(( $cap - used )) 50% $root"
 DFEOF
  chmod +x "$scratch/bin17/df"
 }
 (
  cd "$work"
  for b in a b c; do
    git checkout -q dev
    git checkout -q -b "feat/$b"
    git -c user.email=t@t -c user.name=t -c commit.gpgsign=false commit -q --allow-empty -m "$b"
  done
  git checkout -q dev
  git push -q origin feat/a feat/b feat/c
 )
 # run_seeded_prune <own-ref> <base-ref> — the form cargo-cache/action.yml uses:
 # the same pass, told what the seed step it now runs ahead of will clone. The
 # headroom knobs are pinned so the arithmetic is the fixture's, not the
 # defaults' (whose 2 GiB floor would dwarf any fixture on a test host).
 seeded_rc=0
 run_seeded_prune() {
  seeded_rc=0
  PATH="$scratch/bin17:$outer_path" \
    CACHE_CLONE_HEADROOM_PERCENT=100 CACHE_CLONE_HEADROOM_FLOOR_KB=1024 \
    GITHUB_STEP_SUMMARY="$scratch/summary" \
    bash "$prune" "$root" "$root/target-$(cache_key "$1")" "dev main" 0 \
      "$(cache_key "$1")" "$(cache_key "$2")" "" \
    > "$scratch/log" 2>&1 || seeded_rc=$?
 }
 build_seed_fixture
 run_seeded_prune feat/own dev
 [ "$seeded_rc" = 0 ] || { cat "$scratch/log"; fail "prune-cache.sh exited ${seeded_rc} with the requirement satisfiable"; }
 assert_log "measured from its mutable set" "the requirement says where it came from"
 assert_gone "$root/target-$(cache_key feat/a)" "the oldest cache is evicted to make room for the clone"
 assert_gone "$root/target-$(cache_key feat/b)" "and the next oldest, because one was not enough"
 assert_kept "$root/target-$(cache_key feat/c)" "and the pass STOPS there rather than draining the volume"
 assert_kept "$root/snapshot-$DEV" "the source the seed is about to clone is never a candidate"
 # Nothing eligible: every sibling is held open by a running job. The pass
 # cannot reach the requirement, and the seed that follows would fail against a
 # staging path naming none of this.
 build_seed_fixture
 for b in a b c; do date +%s > "$root/target-$(cache_key "feat/$b")/.ci-lock-ci-1"; done
 run_seeded_prune feat/own dev
 [ "$seeded_rc" = 1 ] || { cat "$scratch/log"; fail "expected exit 1 when the clone cannot fit, got ${seeded_rc}" ; }
 ok "a clone that cannot be made to fit fails the pass rather than the seed"
 assert_log "short by" "the failure names the shortfall"
 assert_log "held open by a running job" "and what was kept instead of it, with the reason"
 assert_kept "$root/target-$(cache_key feat/a)" "a locked cache is still not evicted, however tight the disk"
 echo
 echo "=== 18: the layout that produced the bug ==="
 # zemyna's volume on 2026-09-07: the base branch's snapshot and target dir,
 # plus one target dir for a branch merged the day before and never deleted.
 # Equal sizes and 90% free, so neither age nor pressure nor size can be what
 # decides — only the merge state.
 rm -rf "$root"; mkdir -p "$root"
 mk "snapshot-$DEV"  '2026-09-01'
 mk "target-$DEV"    '2026-09-01'
 mk "target-$MERGED" '2026-09-06'
 run_prune "1000000 900000"
 assert_kept "$root/snapshot-$DEV" "the base snapshot stays"
 assert_kept "$root/target-$DEV" "and the base target dir stays"
 assert_gone "$root/target-$MERGED" "and the merged-but-undeleted branch's cache is the one reclaimed"
 [ "$(grep -c 'pruned dead-branch cache' "$scratch/log")" = 1 ] \
  || { cat "$scratch/log"; fail "expected exactly one eviction on the zemyna layout"; }
 ok "exactly one directory is evicted, and it is that one"
 echo
 echo "prune-cache-selftest: ${pass_count} assertions passed"
@@ -1,16 +1,8 @@
 #!/usr/bin/env bash
 # Eviction for the per-ref cache directories on the persistent volume.
 #
-# Usage: prune-cache.sh <cache-root> <own-target-dir> <protected-branches> \
+# Usage: prune-cache.sh <cache-root> <own-target-dir> <protected-branches> <min-free-percent>
 #          <min-free-percent> [own-key] [base-key] [fallback-dir]
 #   protected-branches  space-separated raw refs (e.g. "dev main")
 #   min-free-percent    a FLOOR, not the gate — 0 to rely on the derived
 #                       requirement alone (the default)
 #   own-key, base-key, fallback-dir
 #                       the same three the seed step resolves its source from.
 #                       Given them, this pass sizes the volume for the clone
 #                       that step is about to make; without them it has only
 #                       the percentage floor, and says so.
 #
 # Optional environment:
 #   STALE_LOCK_SECONDS  age past which a .ci-lock-* marker is treated as
@@ -24,42 +16,19 @@
 #
 # Three passes, in order:
 #
-#   1. LIVENESS — every target-*/snapshot-* directory whose branch is DEAD is
+#   1. LIVENESS — every target-*/snapshot-* directory whose branch no longer
-#      removed UNCONDITIONALLY, not gated on free space. A directory for a
+#      exists on origin is removed UNCONDITIONALLY, not gated on free space.
-#      branch nothing will build again is pure loss; waiting for disk pressure
+#      A directory for a branch deleted days ago is pure loss: nothing will
-#      to notice means paying for it until then. Two signals make a branch
+#      ever read it again, since a merged PR's branch cannot be reopened.
-#      dead, and the second exists because the first alone is inert wherever
+#      Waiting for disk pressure to notice means paying for it until then.
-#      a merged branch stays on origin — the default, and still the outcome
+#      Skipped entirely, loudly, if the liveness signal itself is
-#      whenever delete-on-merge declines or is not asked (gitdan-actions#20):
+#      unavailable — "couldn't determine" is never folded into "dead".
-#
+#   2. PRESSURE — if free space is still under the threshold, evict remaining
-#        DELETED — the branch is no longer on origin at all.
+#      (now necessarily live) directories oldest-first until it clears.
-#        MERGED  — the branch is still on origin, but its tip is an ancestor
+#   3. SELF-CLEAR — if pass 2 still isn't enough, wipe this run's own target
-#                  of a protected branch's tip, so every commit it holds is
+#      dir and pay a cold rebuild, reported to the job summary as well as the
-#                  already on the branch its cache would be re-cloned from.
+#      log, because a warning on a green run is what lets a silently 4x-slower
-#
+#      job go unnoticed.
 #      Skipped entirely, loudly, if the signal itself is unavailable —
 #      "couldn't determine" is never folded into "dead", for either signal
 #      and at either granularity: a checkout that cannot answer ancestry at
 #      all skips the merged half, and a single branch whose tip is not in the
 #      checkout is kept with a warning naming it.
 #   2. PRESSURE — if free space is under the requirement, evict remaining
 #      (now necessarily live) directories oldest-first until it clears. The
 #      requirement is what the seed step is about to need to clone its source,
 #      MEASURED off that source (see clone_headroom_kb in cache-lib.sh), and a
 #      percentage floor only if one is configured. A percentage cannot express
 #      this: the failure it has to prevent is a clone running out of disk
 #      part-way through unsharing its mutable paths, and how much that needs
 #      is a property of the snapshot, not of the volume.
 #   3. SELF-CLEAR — if pass 2 still isn't enough for the percentage floor,
 #      wipe this run's own target dir and pay a cold rebuild, reported to the
 #      job summary as well as the log, because a warning on a green run is
 #      what lets a silently 4x-slower job go unnoticed. It is not a way out of
 #      the derived requirement: a run that has an own target dir to wipe is a
 #      run whose seed reuses it and clones nothing, so that requirement is
 #      zero. Falling short of a NON-ZERO derived requirement fails the job
 #      here, naming the shortfall and what was kept instead of it — the seed
 #      would otherwise fail seconds later against a half-unshared staging
 #      tree, which is the failure this pass exists to pre-empt.
 #
 # Reactive-only, with no hard cap on cache size: a workspace's natural working
 # set is what it is, and bounding the footprint preemptively means wiping
@@ -106,34 +75,16 @@
 # than reimplementing a lookalike is what makes the classification sound; any
 # drift between two spellings would silently misclassify every directory.
 #
 # The merged half reads the TIP SHA out of that same `ls-remote` output and
 # asks `git merge-base --is-ancestor` against each protected branch's tip,
 # using the objects in this job's own checkout. Ancestry is only decidable
 # where the objects are there to decide it, so the answer "I cannot tell"
 # exists and is distinct from "not merged" everywhere it can arise:
 #
 #   - a shallow checkout makes a MISSING object prove nothing, so the whole
 #     signal is withheld rather than read as "no branch is merged";
 #   - a protected tip that is not in the checkout is not used as an anchor;
 #   - a branch tip that is not in the checkout is kept, loudly.
 #
 # A squash or rebase merge leaves no ancestor relationship at all, so its
 # branch reads as live here. That is a missed reclamation, not a wrong one,
 # and the deleted-branch signal still covers it once the branch is removed.
 #
 # Only ever globs inside <cache-root>. Another project's volume is a different
 # Docker named volume and is not mounted in this container at all, so "stays
 # scoped to this repo's cache" holds structurally, not by convention.
 set -euo pipefail
 . "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/cache-lib.sh"
-ROOT="${1:?usage: prune-cache.sh <cache-root> <own-target-dir> <protected-branches> <min-free-percent> [own-key] [base-key] [fallback-dir]}"
+ROOT="${1:?usage: prune-cache.sh <cache-root> <own-target-dir> <protected-branches> <min-free-percent>}"
 OWN_DIR="${2:?}"
 PROTECTED_REFS="${3:-}"
-MIN_FREE_PCT="${4:-0}"
+MIN_FREE_PCT="${4:-10}"
 OWN_KEY="${5:-}"
 BASE_KEY="${6:-}"
 FALLBACK="${7:-}"
 # Mirrored by daniel/gitdan's ci-cache-reclaim.sh, whose copy must be >= this
 # one — raising this without raising theirs first lets that script treat a lock
 # this side still honours as abandoned. Same direction and same reasoning as
@@ -151,34 +102,6 @@ STALE_LOCK_SECONDS="${STALE_LOCK_SECONDS:-7200}"
 # the volume is under pressure.
 EVICTION_ASIDE_SETTLE_SECONDS="${EVICTION_ASIDE_SETTLE_SECONDS:-60}"
 # What the seed step is about to do, resolved through the same function that
 # step resolves it with (cache-lib.sh's seed_source_candidates). Empty when it
 # will clone nothing at all: its own target dir already exists and it reuses
 # it, or no source exists and it starts cold. Either way the derived
 # requirement is zero, because nothing is about to be copied.
 #
 # gb() is for reporting only. Every comparison below is in KB, because
 # `read_df` reports KB and rounding a threshold to a tenth of a GB either
 # passes a run that cannot fit or evicts a cache the run did not need.
 gb() { awk -v k="${1:-0}" 'BEGIN { printf "%.1f", k / 1048576 }'; }
 SEED_SRC=""
 CLONE_KB=0
 if [ -n "$OWN_KEY" ]; then
  SEED_SRC=$(seed_clone_source "$ROOT" "$OWN_KEY" "$BASE_KEY" "$FALLBACK")
  if [ -n "$SEED_SRC" ]; then
    # A full walk of the source, and the reason this pass moved ahead of the
    # seed rather than staying where it was: the number is only useful before
    # the clone it describes.
    CLONE_KB=$(clone_headroom_kb "$SEED_SRC")
    echo "clone requirement: seeding from $(basename "$SEED_SRC") needs $(gb "$CLONE_KB") GB free (measured from its mutable set)"
  else
    echo "clone requirement: none — this run reuses its own cache or starts cold, so nothing will be copied"
  fi
 else
  echo "clone requirement: not derivable — no cache key was passed to this pass; the ${MIN_FREE_PCT}% floor is the only gate"
 fi
 declare -A protected_ns=()
 for ref in $PROTECTED_REFS; do
  suffix=$(cache_key "$ref")
@@ -186,26 +109,14 @@ for ref in $PROTECTED_REFS; do
  protected_ns["snapshot-${suffix}"]=1
 done
-# Prints why <dir> is off limits to every pass, or nothing when it is a
+is_protected() {
 # candidate. The reason is not decoration: it is what the failure report at
 # the bottom lists against each directory it kept while running out of space.
 #
 # SEED_SRC is the third exclusion and the one this script did not used to need.
 # The prune ran after the seed, so the source had already been cloned and the
 # reader marker over it was gone; running BEFORE the seed puts the directory
 # this run is about to read squarely in the candidate set, and pass 1 would
 # take it the moment its branch merged.
 protected_reason() {
  local dir="$1" name
  name=$(basename "$dir")
-  [ "$dir" = "$OWN_DIR" ] && { printf 'this run own cache'; return 0; }
+  [ "$dir" = "$OWN_DIR" ] && return 0
-  [ -n "$SEED_SRC" ] && [ "$dir" = "$SEED_SRC" ] && { printf 'the source this run is about to clone'; return 0; }
+  [ -n "${protected_ns[$name]:-}" ] && return 0
  [ -n "${protected_ns[$name]:-}" ] && { printf 'a protected branch cache'; return 0; }
  return 1
 }
 is_protected() { protected_reason "$1" >/dev/null; }
 # is_locked <dir> [name]
 #
 # `name` is the directory's own name for reporting and for the reader-marker
@@ -366,11 +277,6 @@ done
 echo "=== pass 1: liveness (unconditional, not gated on free space) ==="
 declare -A live_ns=()
 # The tip SHA origin reports for the branch each directory name belongs to.
 # Same output, same loop, one field over — reading it from a second `git` call
 # would be reading a different instant.
 declare -A live_tip=()
 declare -A remote_tip_of=()
 LIVENESS_AVAILABLE=0
 LIVENESS_REASON=""
 if [ "${CACHE_LIVENESS:-true}" = "0" ] || [ "${CACHE_LIVENESS:-true}" = "false" ]; then
@@ -383,13 +289,9 @@ elif remote_heads=$(timeout 20 git ls-remote --heads origin 2>&1); then
    case "$line" in *refs/heads/*) ;; *) continue ;; esac
    branch="${line#*refs/heads/}"
    [ -n "$branch" ] || continue
    sha="${line%%[[:space:]]*}"
    suffix=$(cache_key "$branch")
    live_ns["target-${suffix}"]=1
    live_ns["snapshot-${suffix}"]=1
    live_tip["target-${suffix}"]="$sha"
    live_tip["snapshot-${suffix}"]="$sha"
    remote_tip_of["$branch"]="$sha"
    branch_count=$((branch_count + 1))
  done <<< "$remote_heads"
  echo "liveness: ${branch_count} live branches on origin"
@@ -397,80 +299,6 @@ else
  LIVENESS_REASON="git ls-remote --heads origin failed or timed out"
 fi
 # The merged half of pass 1, and whether this checkout can answer it at all.
 # Every branch of this decision that ends in "no" ends in the signal being
 # WITHHELD, never in a directory being classified dead by default.
 MERGED_AVAILABLE=0
 MERGED_REASON=""
 PROTECTED_TIPS=()
 declare -A merged_verdict=()
 declare -A merged_into=()
 MERGED_INTO=""
 if [ "$LIVENESS_AVAILABLE" = "1" ]; then
  if ! git rev-parse --git-dir >/dev/null 2>&1; then
    MERGED_REASON="not inside a git checkout"
  elif [ "$(git rev-parse --is-shallow-repository 2>/dev/null || echo unknown)" != "false" ]; then
    # In a shallow clone an absent commit is the normal case, so `--is-ancestor`
    # answers about the graph that was fetched rather than the one that exists.
    MERGED_REASON="the checkout is shallow, so a commit missing from it says nothing about ancestry"
  else
    for ref in $PROTECTED_REFS; do
      tip="${remote_tip_of[$ref]:-}"
      [ -n "$tip" ] || continue
      git cat-file -e "${tip}^{commit}" 2>/dev/null || continue
      PROTECTED_TIPS+=("${ref}:${tip}")
    done
    if [ "${#PROTECTED_TIPS[@]}" -gt 0 ]; then
      MERGED_AVAILABLE=1
      echo "liveness: merged-branch detection anchored on ${PROTECTED_TIPS[*]%%:*}"
    else
      MERGED_REASON="none of the protected branch tips (${PROTECTED_REFS:-none configured}) is present in this checkout"
    fi
  fi
  [ "$MERGED_AVAILABLE" = "1" ] || \
    echo "::warning::liveness: ${MERGED_REASON} — merged-but-undeleted branches keep their caches this run"
 fi
 # is_merged_dead <dir-name>
 #
 # True when the branch this directory belongs to is still on origin but every
 # commit it holds is already on a protected branch — a merged PR whose branch
 # the forge did not delete, which the deleted-branch signal above can never
 # see. Enabling delete-on-merge narrows this to the branches merged before it
 # was enabled, the ones its deletion declines (protected, or used by another
 # open PR), and the merges that never ask (an API merge without the flag);
 # see README's eviction section.
 #
 # Memoised per tip because target-<key> and snapshot-<key> share one branch,
 # and because the "cannot tell" warning belongs to the branch rather than to
 # each of its directories.
 is_merged_dead() {
  local name="$1" tip="${live_tip[$1]:-}" entry ref psha
  MERGED_INTO=""
  [ "$MERGED_AVAILABLE" = "1" ] || return 1
  [ -n "$tip" ] || return 1
  case "${merged_verdict[$tip]:-}" in
    dead) MERGED_INTO="${merged_into[$tip]}"; return 0 ;;
    live|unknown) return 1 ;;
  esac
  if ! git cat-file -e "${tip}^{commit}" 2>/dev/null; then
    merged_verdict["$tip"]=unknown
    echo "::warning::prune: ${name}: its branch tip ${tip} is not in this checkout — cannot tell merged from live, keeping it"
    return 1
  fi
  for entry in "${PROTECTED_TIPS[@]}"; do
    ref="${entry%%:*}"; psha="${entry#*:}"
    if git merge-base --is-ancestor "$tip" "$psha" 2>/dev/null; then
      merged_verdict["$tip"]=dead
      merged_into["$tip"]="$ref"
      MERGED_INTO="$ref"
      return 0
    fi
  done
  merged_verdict["$tip"]=live
  return 1
 }
 if [ "$LIVENESS_AVAILABLE" = "1" ]; then
  pruned_any=0
  # Tracked separately so the line below cannot contradict the decline lines
@@ -481,20 +309,12 @@ if [ "$LIVENESS_AVAILABLE" = "1" ]; then
    [ -d "$dir" ] || continue
    name=$(basename "$dir")
    is_protected "$dir" && continue
-    if [ -z "${live_ns[$name]:-}" ]; then
+    [ -n "${live_ns[$name]:-}" ] && continue
      why="no matching branch on origin"
      why_summary="branch no longer exists on origin"
    elif is_merged_dead "$name"; then
      why="merged into ${MERGED_INTO}, whose tip already contains its every commit"
      why_summary="merged into \`${MERGED_INTO}\`"
    else
      continue
    fi
    is_locked "$dir" && { spared_any=1; continue; }
    dir_gb=$(usage_gb "$dir")
    evict_dir "$dir" || { spared_any=1; continue; }
-    echo "::warning::pruned dead-branch cache ${name} (${dir_gb} GB) — ${why}"
+    echo "::warning::pruned dead-branch cache ${name} (${dir_gb} GB) — no matching branch on origin"
-    summary_line "- pruned dead-branch cache \`${name}\` (${dir_gb} GB) — ${why_summary}"
+    summary_line "- pruned dead-branch cache \`${name}\` (${dir_gb} GB) — branch no longer exists on origin"
    pruned_any=1
  done
  if [ "$pruned_any" = "0" ]; then
@@ -509,45 +329,16 @@ else
 fi
 echo
-echo "=== pass 2/3: disk pressure ==="
+echo "=== pass 2/3: disk pressure (threshold: free < ${MIN_FREE_PCT}%) ==="
 read -r TOTAL_KB FREE_KB <<< "$(read_df "$ROOT")"
-PCT_KB=$(( TOTAL_KB * MIN_FREE_PCT / 100 ))
+THRESHOLD_KB=$(( TOTAL_KB * MIN_FREE_PCT / 100 ))
-# The two floors, and which of them governs. They are kept apart all the way
+if [ "$FREE_KB" -ge "$THRESHOLD_KB" ]; then
-# down rather than collapsed here, because falling short of them means
+  echo "cache: $(basename "$OWN_DIR") $(usage_gb "$OWN_DIR") GB | $(report_df host "$FREE_KB" "$TOTAL_KB")"
 # different things: the derived one predicts that the very next step cannot
 # finish, and the percentage one is a hygiene target for the volume.
 REQUIRED_KB="$CLONE_KB"
 GOVERNS="the clone this run is about to make"
 if [ "$PCT_KB" -gt "$REQUIRED_KB" ]; then
  REQUIRED_KB="$PCT_KB"
  GOVERNS="the ${MIN_FREE_PCT}% floor"
 fi
 echo "required: $(gb "$REQUIRED_KB") GB free — ${GOVERNS} (clone $(gb "$CLONE_KB") GB, floor $(gb "$PCT_KB") GB)"
 own_report() {
  if [ -d "$OWN_DIR" ]; then
    echo "cache: $(basename "$OWN_DIR") $(usage_gb "$OWN_DIR") GB | $(report_df host "$1" "$2")"
  else
    # Ordinary now that this pass runs ahead of the seed: on a branch's first
    # run of the day the directory does not exist yet, and reporting 0.0 GB
    # for it would read as an emptied cache.
    echo "cache: $(basename "$OWN_DIR") not seeded yet | $(report_df host "$1" "$2")"
  fi
 }
 if [ "$FREE_KB" -ge "$REQUIRED_KB" ]; then
  own_report "$FREE_KB" "$TOTAL_KB"
  exit 0
 fi
-echo "::warning::$(report_df disk "$FREE_KB" "$TOTAL_KB") < the $(gb "$REQUIRED_KB") GB this run requires"
+echo "::warning::$(report_df disk "$FREE_KB" "$TOTAL_KB") < ${MIN_FREE_PCT}% threshold"
 # What survived the pass, and why, in the order the pass considered them. Read
 # only by the failure report at the bottom: a run that cannot fit its clone is
 # a run whose log has to answer "then what is all that space?" without anyone
 # having to reconstruct the pass by hand.
 KEPT=()
 # A plain loop over a pre-materialised, pre-sorted list rather than a live
 # `find | while` pipeline, so `rm -rf` inside the loop cannot make a running
@@ -555,56 +346,21 @@ KEPT=()
 mapfile -t LRU < <(list_by_lru)
 for dir in "${LRU[@]}"; do
  [ -d "$dir" ] || continue
-  if reason=$(protected_reason "$dir"); then
+  is_protected "$dir" && continue
    KEPT+=("$(basename "$dir") — ${reason}")
    continue
  fi
  read -r TOTAL_KB FREE_KB <<< "$(read_df "$ROOT")"
-  [ "$FREE_KB" -ge "$REQUIRED_KB" ] && break
+  [ "$FREE_KB" -ge "$THRESHOLD_KB" ] && break
-  if is_locked "$dir"; then
+  is_locked "$dir" && continue
    KEPT+=("$(basename "$dir") — held open by a running job")
    continue
  fi
  dir_gb=$(usage_gb "$dir")
-  if ! evict_dir "$dir"; then
+  evict_dir "$dir" || continue
    KEPT+=("$(basename "$dir") — claimed by a job while its eviction was in flight")
    continue
  fi
  echo "::warning::evicted $(basename "$dir") (${dir_gb} GB, LRU under disk pressure)"
  summary_line "- evicted \`$(basename "$dir")\` (${dir_gb} GB, LRU under disk pressure)"
 done
 read -r TOTAL_KB FREE_KB <<< "$(read_df "$ROOT")"
-
+if [ "$FREE_KB" -lt "$THRESHOLD_KB" ]; then
 # Falling short of the DERIVED requirement is a failure, not a warning. The
 # seed step is next, it will clone that source, and it will run out of disk
 # part-way through unsharing the clone's mutable paths — reported against a
 # staging path, with nothing in the message about which cache was holding the
 # space. Failing here says that instead.
 #
 # There is nothing to self-clear on this path and it is not skipped in error:
 # a non-zero requirement means the seed is about to CLONE, which means this
 # run has no own target dir to wipe (seed_clone_source returns nothing when it
 # does), so pass 3 has no candidate. See the header.
 if [ "$FREE_KB" -lt "$CLONE_KB" ]; then
  echo "::error::prune: $(gb "$FREE_KB") GB free after evicting every eligible cache, but seeding from $(basename "$SEED_SRC") needs $(gb "$CLONE_KB") GB — short by $(gb "$(( CLONE_KB - FREE_KB ))") GB"
  summary_line "- **out of disk**: seeding from \`$(basename "$SEED_SRC")\` needs $(gb "$CLONE_KB") GB, $(gb "$FREE_KB") GB free"
  echo "prune: kept, and why:"
  for entry in ${KEPT[@]+"${KEPT[@]}"}; do echo "  ${entry}"; done
  [ "${#KEPT[@]}" -gt 0 ] || echo "  (nothing — the volume holds no cache directories at all)"
  exit 1
 fi
 if [ "$FREE_KB" -lt "$PCT_KB" ]; then
  OWN_GB=$(usage_gb "$OWN_DIR")
  echo "::warning::still under threshold after evicting every eligible sibling; clearing own $(basename "$OWN_DIR") (was ${OWN_GB} GB) — this run pays a cold rebuild"
  summary_line "- **self-clear**: \`$(basename "$OWN_DIR")\` (was ${OWN_GB} GB) wiped — this run pays a cold rebuild"
  # Recreated empty rather than left absent, and that is what keeps this path
  # out of the requirement above: the seed reuses an own target dir that
  # exists, whatever is in it, so a self-cleared run clones nothing and needs
  # no headroom. Leaving it absent would send that run to the base snapshot
  # instead, needing a clone this pass has just spent its last eligible bytes
  # not sizing for.
  rm -rf "$OWN_DIR"
  mkdir -p "$OWN_DIR"
 else
@@ -53,11 +53,9 @@ pass_count=0
 fail() { echo "ASSERTION FAILED: $*" >&2; exit 1; }
 ok() { pass_count=$((pass_count + 1)); echo "PASS: $*"; }
-# rustc REPLACES an `.rlib`/`.rmeta` (writes elsewhere, renames over the path)
+# Cargo and rustc REPLACE an artifact (write elsewhere, rename over the path)
 # rather than truncating it in place, which is exactly why a snapshot may
-# share those inodes with the live target dir it was cloned from. Linker
+# share artifact inodes with the live target dir it was cloned from. The
 # outputs are the exception and are real-copied instead — see
 # `unshare_mutable_paths` in cache-lib.sh. The
 # fixtures here have to model that faithfully — a plain `>` redirect truncates
 # in place and would write straight through the shared inode into the
 # snapshot and every consumer, which is a property of the test fixture, not of
@@ -75,15 +75,6 @@
 #      Asserts BOTH jobs correctly recompile the dependency and succeed.
 set -euo pipefail
 # Every assertion below reads cargo's own words out of a build log
 # (`Compiling libdep`, `Fresh probe`). A CI image that forces colour splices an
 # ANSI reset between the status word and the crate name, at which point every
 # one of those greps silently stops matching and the suite reports the
 # opposite of what happened — observed on gitdan-ci's runner image, where
 # scenario 2 failed while the log it printed plainly showed `Compiling libdep`.
 # Pin the format the assertions are written against.
 export CARGO_TERM_COLOR=never
 script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 restore_mtimes="$script_dir/restore-mtimes.sh"
@@ -131,7 +122,7 @@ assert_log_lacks() {
 # every run — simulate that before each restore-mtimes.sh pass, exactly as
 # CI would see it, so this test exercises the script the same way CI does.
 stamp_checkout_now() {
-  find . -path ./.git -prune -o -type f -print0 | xargs -0 touch
+  find . -path ./.git -prune -o -type f -print | xargs touch
 }
 echo "=== building scratch workspace ==="
@@ -140,11 +131,6 @@ cd "$repo"
 git init -q
 git config user.email test@example.com
 git config user.name "restore-mtimes-selftest"
 # Local to this mktemp'd throwaway repo. Without it the eight commits below
 # inherit the developer's GLOBAL commit.gpgsign, which makes whether this gate
 # passes depend on their gpg agent — observed as a red run caused by a full
 # disk breaking gpg, in a suite that has nothing to say about either.
 git config commit.gpgsign false
 cat > Cargo.toml <<'EOF'
 [workspace]
@@ -64,8 +64,7 @@
 # two refs' fingerprints ever share a directory and this script never has to
 # arbitrate freshness across refs — only within one ref's own history, which
 # is exactly what it is built to do soundly. On a nightly toolchain,
-# CARGO_UNSTABLE_CHECKSUM_FRESHNESS plus CARGO_BUILD_FINGERPRINT=content (both,
+# CARGO_UNSTABLE_CHECKSUM_FRESHNESS is a complementary, stronger guarantee
 # since cargo PR #17382 on 2026-08-22) is a complementary, stronger guarantee
 # (content-addressed rather than mtime-based freshness); this script is not
 # made redundant by it, because directory-form `rerun-if-changed` build-script
 # watches are not covered by it and stable historical mtimes stay cheap
@@ -74,17 +74,6 @@
 #      onto one set of fingerprints. That is the silent stale-reuse bug the
 #      whole scheme exists to prevent, so the failure has to abort the clone
 #      rather than be swallowed.
 #  11. THE CONSUMER'S MARKER ACTUALLY STOPS THE PUBLISHER — reader_lock_acquire
 #      is exercised (not faked, unlike publish-snapshot-selftest.sh's scenario
 #      6) by a real hardlink_clone_into racing a real, concurrent
 #      publish-snapshot.sh republish of the exact snapshot being cloned. Pins
 #      that the publisher OBSERVABLY WAITS on this consumer's marker — its own
 #      log reports entering the drain wait — rather than only that the run
 #      succeeds, which stayed green with the marker call deleted (issue #10).
 #      Kept as its own scenario, not folded into 8a, because 8a already pins
 #      exactly one property (the identity check) for exactly one mutant, and
 #      the suite's one-scenario-one-mutant diagonal across 8a to 8d and 10 is
 #      deliberate.
 set -euo pipefail
 script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 . "$script_dir/cache-lib.sh"
@@ -646,84 +635,5 @@ leftovers=$(find "$root" -maxdepth 1 \( -name '.stage-*' -o -name '.reading-*' \
 ok "no staging or reader-marker scratch left behind"
 rm -f "$scratch/bin/cp"
 echo
 echo "=== 11: the consumer's marker actually stops the publisher ==="
 # hardlink_clone_into's reader_lock_acquire call is exercised here, not
 # faked. publish-snapshot-selftest.sh's scenario 6 stands a hand-written
 # marker file in for "a consumer whose clone outlasts the grace period" — a
 # deliberate simplification that does not need this consumer's clone code at
 # all, so it cannot tell reader_lock_acquire apart from no marker existing.
 # This scenario forces the two real scripts to race on the same snapshot: a
 # consumer hardlink-cloning it, and a publisher republishing it out from
 # under that clone, exactly as 8a does to force the identity check — but what
 # is pinned here is not the consumer's response to the rotation (8a's
 # property), it is that the PUBLISHER, reading the SAME marker this
 # consumer's clone wrote, is observed to have entered its drain wait. Deleting
 # reader_lock_acquire (issue #10) leaves the marker never written: the
 # publisher's live_reader_count sees zero readers on its first check and
 # proceeds straight to reclaiming the rotated generation, silently — the run
 # still succeeds, and nothing about its own outcome says so, only the absence
 # of a line in the publisher's log.
 INTLK=$(cache_key feat/interlock-consumer)
 INTLK_BASE=$(cache_key release/5)
 TAG_INTLK=jobIntlk
 rm -rf "$root/snapshot-$INTLK_BASE" "$root/target-$INTLK_BASE"
 make_tree "$root/snapshot-$INTLK_BASE" intlk-gen1
 make_tree "$root/target-$INTLK_BASE" intlk-gen2
 intlk_gen1_inode=$(stat -c '%i' "$root/snapshot-$INTLK_BASE")
 cat > "$scratch/bin/cp" <<EOF
 #!/usr/bin/env bash
 # Fires once, only on the consumer's own top-level hardlink clone — identified
 # by its destination, the seed's private staging path. Every other cp in the
 # process tree (the unshare copies, and the publisher's own staging clone)
 # falls through to the real one.
 if [ "\${@: -1}" = "$root/.stage-$TAG_INTLK" ] && [ ! -e "$scratch/firedIntlk" ]; then
  : > "$scratch/firedIntlk"
  rc=0; "$real_cp" "\$@" || rc=\$?
  # Concurrently: a real, second publish of the exact snapshot this consumer
  # is cloning — the republish that, without the marker this consumer's clone
  # holds, would reclaim the generation out from under it.
  ( CACHE_READ_GRACE_SECONDS=10 bash "$script_dir/publish-snapshot.sh" "$INTLK_BASE" "$root" pubIntlk \
      > "$scratch/logPubIntlk" 2>&1
    echo \$? > "$scratch/rcPubIntlk" ) &
  # Hand control back only once the swap is on disk, so the identity read
  # immediately after this cp is guaranteed to resolve to the new generation
  # — the same technique 8a uses to force the interleaving rather than hope
  # for it. reader_lock_release does not run until AFTER this script exits,
  # so the marker stays live for the publisher's whole swap-and-scan.
  deadline=\$(( \$(date +%s) + 60 ))
  while [ "\$(stat -c '%i' "$root/snapshot-$INTLK_BASE" 2>/dev/null)" = "$intlk_gen1_inode" ]; do
    [ "\$(date +%s)" -lt "\$deadline" ] || { echo "stub cp: the publisher never swapped the snapshot" >&2; exit 92; }
    sleep 0.05
  done
  exit \$rc
 fi
 exec "$real_cp" "\$@"
 EOF
 chmod +x "$scratch/bin/cp"
 rcIntlk=0
 seed_with_stub "$INTLK" "$INTLK_BASE" "$root" "$TAG_INTLK" > "$scratch/logIntlk" 2>&1 || rcIntlk=$?
 [ -e "$scratch/firedIntlk" ] \
  || fail "the stubbed cp never fired: the consumer never raced the publisher, so this scenario proves nothing"
 ok "the consumer's clone raced a real, concurrent republish of its own source"
 wait_for_file "$scratch/rcPubIntlk" "the publisher never finished"
 [ "$(cat "$scratch/rcPubIntlk")" = "0" ] || { tail -40 "$scratch/logPubIntlk"; fail "publish-snapshot.sh exited non-zero"; }
 [ "$rcIntlk" = "0" ] || { tail -40 "$scratch/logIntlk"; fail "the seed exited non-zero"; }
 ok "both sides of the race completed"
 # The property under test: not that the run succeeded, but that the publisher
 # itself reports having found a live reader and waited on it. This is silent
 # in the consumer's own log and in the run's exit status alike — only the
 # publisher's log carries it.
 grep -q "readers: waiting for 1 in-flight clone(s) of snapshot-${INTLK_BASE}" "$scratch/logPubIntlk" \
  || { tail -40 "$scratch/logPubIntlk"; fail "the publisher never reported waiting on the consumer's reader marker — the interlock did not observably engage"; }
 ok "the publisher observably waited on the consumer's own reader marker before reclaiming the rotated snapshot generation"
 leftovers=$(find "$root" -maxdepth 1 \( -name '.stage-*' -o -name '.reading-*' -o -name '.publish-*' \) -print)
 [ -z "$leftovers" ] || fail "scratch left behind: ${leftovers}"
 ok "no staging, reader-marker or deferred-generation scratch left behind"
 rm -f "$scratch/bin/cp"
 echo
 echo "seed-target-dir-selftest: ${pass_count} assertions passed"
@@ -61,11 +61,10 @@ fi
 #      snapshot already exists.
 #   3. an explicit fallback directory — migration off a pre-existing flat
 #      cache, so the first run under this scheme isn't a needless cold build.
-#
+CANDIDATES=()
-# The list itself lives in cache-lib.sh because prune-cache.sh reads it too:
+[ -n "$BASE_KEY" ] && CANDIDATES+=("$(snapshot_dir_for "$ROOT" "$BASE_KEY"):base snapshot")
-# it runs ahead of this step and has to free enough disk for the clone below,
+CANDIDATES+=("$(snapshot_dir_for "$ROOT" "$OWN_KEY"):own snapshot")
-# which means resolving the same source this loop will pick.
+[ -n "$FALLBACK" ] && CANDIDATES+=("${FALLBACK}:fallback dir")
 mapfile -t CANDIDATES < <(seed_source_candidates "$ROOT" "$OWN_KEY" "$BASE_KEY" "$FALLBACK")
 for entry in "${CANDIDATES[@]}"; do
  src="${entry%%:*}"; label="${entry#*:}"
@@ -13,7 +13,7 @@ script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 FAST=0
 [ "${1:-}" = "--fast" ] && FAST=1
-FIXTURE_TESTS=(cache-root-selftest.sh seed-target-dir-selftest.sh publish-snapshot-selftest.sh prune-cache-selftest.sh)
+FIXTURE_TESTS=(seed-target-dir-selftest.sh publish-snapshot-selftest.sh prune-cache-selftest.sh)
 CARGO_TESTS=(hardlink-clone-selftest.sh restore-mtimes-selftest.sh)
 TESTS=("${FIXTURE_TESTS[@]}")