Why

Until now the local platform stack was effectively a singleton: one database, one
set of ports, one build directory, one flowctl profile per machine. That's fine
when you're the only thing running, but it makes parallel work painful. Spin up a
second checkout to QA a fix while a soak test runs in the first, and the two
stacks fight over the same ports and the same Postgres. In practice you had to
tear one down before bringing the other up — and with multiple people (or agents)
sharing a dev VM, you were constantly stepping on each other.

This change makes a local stack belong to a checkout rather than to the machine.
Every clone and every git worktree gets its own fully isolated platform — its own
database, etcd, brokers, reactors, ports, build artifacts, and flowctl profile —
so any number of them can run side by side without coordination.

What it feels like to use

The whole point is that you don't think about isolation. You work in a checkout,
and everything scopes to it automatically:

mise run local:stack        # bring up this checkout's stack
mise run local:stack-info   # ports, units, and ready-to-paste commands for *this* stack

stack-info is the one thing to remember: it prints the ports and commands for
wherever you happen to be, so you never compute a port or pick a name. Under the
hood each checkout claims a small integer index and derives everything from it,
but as a developer you mostly just see that things don't collide.

A few niceties fall out of this:

• flowctl just works. Inside a checkout, bare flowctl targets that
  checkout's stack — no --profile flag to remember, and no chance of
  accidentally driving the wrong stack.
• Common variables are ambient. FLOW_PG_URL, FLOW_CLUSTER, the
  FLOW_PORT_* set, and friends are already in your environment when you run
  through mise, so psql "$FLOW_PG_URL" and the like do the right thing.
• Builds are shared per stack, not globally. Each checkout has its own target
  directory, so rebuilds in one worktree don't invalidate another's cache.
• Teardown is scoped. local:stop tears down just the stack you're in and
  leaves everyone else running.

Lifecycle: stop is cheap, deleting the worktree is the release

Stopping and releasing are deliberately different actions:

• local:stop is a stack-scoped guillotine — it stops this stack's units and
  wipes its runtime state, but keeps its registry slot, its build cache, and
  its Supabase volumes, so a later start is instant.

• Releasing a slot happens when you delete the checkout. A deleted checkout
  directory is the one and only signal that frees a slot and its artifacts.
  Just remove the worktree when you're done:

  git worktree remove ../feature-x   # (or plain rm -rf) — that's the release

A garbage collector reclaims deleted checkouts in the background — stopping their
orphaned units, then freeing the slot, build target, state dir, and Supabase
volumes. It runs automatically at natural joints (local:stack and
local:stop), so starting or stopping a stack anywhere cleans up worktrees you've
removed. You can also run it on demand:

mise run local:stack-prune   # reclaim slots of deleted checkouts (idempotent)

This also means a registry full of removed checkouts heals itself instead of
dead-ending on "no free index": the new-checkout allocation path reaps gone
entries before it looks for a free slot.

A note on mise

Because stack identity now comes from the checkout, mise is the mandatory entry
point — it's what makes the per-checkout variables ambient. Running tasks and
tests through mise (mise run ..., mise exec -- ...) always has the right
environment. Outside mise, wrap once with eval "$(mise run local:stack-env)".
Scripts and tests fail loudly rather than silently defaulting if the environment
is missing, so you find out immediately instead of debugging a mystery stack.

In the same spirit, dekaf --local now fails loud when no endpoint is given:
local-stack ports are dynamic so there is no compiled local default, and clap
would otherwise fall through to the production defaults — pointing a local anon
token at prod. mise run local:data-plane supplies the right endpoints; run it
that way, or pass API_ENDPOINT/AGENT_ENDPOINT explicitly.

local/README.md is the full reference for how this is wired together.

Keeping the disk in check on dev VMs

Per-checkout isolation has a cost: every checkout gets its own
~/cargo-target/<name>/, each 20–60G, and they overlap heavily — the same crates
compiled in worktree after worktree. On a shared dev VM with several checkouts
that adds up fast.

So on dev VMs, ~/cargo-target is now backed by a compressed,
self-deduplicating btrfs filesystem on a sparse loopback image sized to 50% of
the disk:

• zstd:3 transparent compression (~3.2× measured on real artifacts).
• A 10-minute duperemove + fstrim timer that collapses extents shared
  across checkouts and punches the freed space back into the sparse image —
  near-total dedupe for same-commit worktrees, and ~26% of logical bytes even
  across divergent branches (extent-level dedupe shares blocks of differing files
  too). Net: many divergent checkouts fit in a fraction of their raw footprint.
• The Go build cache moves onto the filesystem, since Go stores it uncompressed
  and it compresses well. sccache stays at its default ~/.cache/sccache: it
  already compresses its own entries, so it would gain nothing under the
  compress-force mount (and can't be excluded from it).

It's set up by bootstrap:cargo-target-fs, invoked from vm:create-post before
anything builds. The task is idempotent and Linux-only, and it never migrates an
existing plain-dir ~/cargo-target (VMs are disposable, make a new one).

QA

Exercised end to end: full bring-up, tenant provisioning, a soak test with all
verification checks passing, isolation spot-checks across concurrent stacks, and
scoped teardown.

The slot-reclaim lifecycle was driven directly against a live stack:

• Reaper unit coverage — its guards (empty/short name), prefix-safety
  (alpha doesn't touch alpha-2), exact-suffix volume matching (flow doesn't
  reap flow-2), and registry rewrite (including the all-gone empty case) all
  hold.
• Reclaim, end to end — allocated a throwaway worktree a slot, planted its
  build target, state dir, and a Supabase volume, deleted the worktree, and
  confirmed local:stack-prune reclaimed exactly that entry (slot, target, state,
  volume) while a concurrently-running stack was left completely untouched. The
  freed index was then immediately reused by a new checkout.
• Auto-reap at joints — confirmed local:stack and local:stop reclaim
  deleted checkouts, and that local:stop retains the current stack's slot, build
  cache, and Supabase volumes for an instant restart.
• dekaf --local guard — verified it bails with an actionable message when
  API_ENDPOINT/AGENT_ENDPOINT are missing, and starts cleanly on the
  local:data-plane happy path.