feat(scratch): one cache lineage per branch, seeded on a switch

[raphaelvigee]

Fourth of four (stack #408), on top of #412. The first three made a scratch cache
work; this one makes it survive branch switching.

The problem

With one lineage per slot, git checkout feat-x silently hands the arriving
branch whatever cache state the departing one left, then hands it back mutated.
Every switch degrades both. It is the same event as a PR job running against a
shared cache, and it wants the same answer.

One lineage per branch, with a fallback

scratch:
  scope: ${git:branch}       # the lineage this run writes to
  restoreScopes: [master]    # what it may read from when its own is empty
  seedOnFork: true

Reads try the current scope, then each fallback in order. Writes only ever go to
scope — never to a fallback, not even the one just seeded from. That asymmetry
is the whole of the isolation: a PR build cannot advance the cache its base builds
from, and a broken experiment on a branch cannot corrupt the one you go back to.

A new lineage is seeded from its fallback rather than starting cold, so a
branch switch costs a copy instead of a rebuild.

${git:branch}

Expanded by the engine, reading .git/HEAD directly rather than shelling out —
this runs on every engine construction, and a subprocess for one line of a file
that is always there is not worth it, nor is requiring git on PATH.

Outside a checkout, or on a detached HEAD, it resolves to the empty scope: one
shared lineage, today's behaviour. A cache policy must never be the reason a build
cannot start.

Scopes are sanitized to a single path component, because branch names routinely
contain / and a raw one would nest an extra level and make two branches collide
the moment one is a path prefix of another.

Seeding is the only copy in the design

Once per (slot, scope), amortized over every later build on that branch, and
measured against a cold rebuild rather than against nothing.

It defaults on, because scoping without it just makes every branch switch cold —
worse than not scoping at all. seedOnFork: false turns it off for a large slot on
a filesystem with no reflink. A reflink would make this near-free on APFS/btrfs and
is the obvious next step, but it is a per-platform optimization and this has to be
correct everywhere first.

A failed seed is a cold cache and never a failed build, per the scratch contract,
and leaves no partial tree behind for the next run to mistake for a warm one.
copy_tree recreates symlinks rather than following them, so a slot that has
acquired a link to somewhere else does not duplicate that somewhere else into the
new scope.

Compatibility

Defaults are unchanged. scope is empty, so a workspace that configures
nothing keeps the single lineage it has today, in the same directory layout. No
proto change, no ABI bump.

One live question for you: should scope default to ${git:branch}? On is
what makes switching branches worth anything; it also multiplies a developer's
cache by branch count and makes the seed copy a routine cost. Left off here
because it is a policy call, not an implementation one.

Tests

17 unit + 2 e2e. The e2e pair is the story end to end — build on master, switch
to feat and see master's work, switch back and confirm the branch's writes
never reached master — plus the seedOnFork: false path.

---

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}