container: exec into a reused per-shape session container instead of a run per step

[mobileoverlord]

Owner: this PR is mine (the fast-rebuilds series), not the feeds series.
Both series push under the same account, so authorship does not distinguish
them.

Every build step was its own docker run --rm. Profiling a no-op avocado build with a PATH shim over docker put 71% of all container time in startup
alone: a run costs ~0.52s before the command begins, an exec into a live
container ~0.045s.

What

Steps whose container shape is identical — image, platform, mounts, devices,
capabilities, container_args — share one detached container per shape, created
on first use and removed at exit. Then the same mechanism is extended to the
eight sites that started containers outside the reusable path.

The worst of those was reading an extension's avocado.yaml out of the SDK
volume. Config composition re-reads every extension discovered so far after each
fetch, so an sdk install on a three-extension project did that 24 times,
each a ~0.52s container start for a ~5ms cat — 12.9s of a 19s command. Also
routed: ext checkout's three volume probes and its docker cp, profiles'
stone-manifest read, save's du and tar, and host_copy, which now
docker cps straight out of a running container instead of creating and
removing one per file. That drops the busybox and alpine dependencies from
those paths in favour of the project's own SDK image, which is local already.
avocado load deliberately keeps busybox: it restores the project's config as
it runs, so the SDK image is not yet known and may not be pulled.

Four things this has to get right

• Shape and environment come from the generated run argv, not the
  caller's env_vars, because the command builder injects AVOCADO_TARGET, the
  host uid/gid and the signing and ext-mount variables itself. A dropped
  AVOCADO_TARGET leaves AVOCADO_PREFIX empty and every stamp lookup silently
  misses — with a plausible-looking error, which is what makes it dangerous.
• The container parks on sleep and runs its mounts as a separate synchronous
  exec. run -d returns when the container starts, not when its command has
  finished, so a step could otherwise exec into a container whose /opt/src was
  not mounted yet. The exec's own prologue omits the mount block; re-running
  bindfs stacks a second mount.
• No blocking work under a shared lock. An earlier revision held one global
  lock across docker ps, docker run -d and the mount exec. install runs
  steps in parallel, so each one parked a tokio worker on that lock; with enough
  of them nothing else could be polled, including the scheduler's select!,
  whose Ctrl-C branch then never fired. The map lock now only hands out a
  per-shape slot; creation happens under that slot's own lock, inside
  block_in_place.
• Teardown covers every exit. Nine call sites reach std::process::exit and
  never return to main, so teardown is registered with atexit, which fires
  for those and for a normal return. A signal skips atexit, so Ctrl-C is
  handled separately: a SIGINT reaper, armed lazily from the moment this process
  first creates a session container and only then — registering a SIGINT
  handler suppresses default termination process-wide, and commands that never
  create one of these (container dev drives its shutdown off the same signal)
  must keep the Ctrl-C they have.

Detached, interactive and named steps keep their own docker run, as does
--runs-on, whose remote path short-circuits before any of this. Any failure to
create or reach a session container falls through to the run that would have
happened anyway, and AVOCADO_NO_SESSION_CONTAINER=1 opts out — the escape
hatch reaches the new path too, giving each caller its own container rather than
being silently ignored.

Results

Measured with a PATH shim over docker, toggled only by the escape hatch:

	per-step run	session containers
no-op build, time in the container tool	13.8s	8.7s
no-op build, wall	11.9s	10.7s
sdk install, 3 remote extensions	31 container starts, 23.3s	6 starts, 9.0s

Wall gains less than container time because steps run concurrently and some
startup was already overlapped — that is the number to plan against.

Ctrl-C, pty-driven at two interrupt points: before, exit -2 leaving two
containers holding the project volume; after, exit 130 within 0.7s leaving none.

Review notes

Two things worth a second pair of eyes rather than trust: this has only been
exercised against Docker on Linux — no podman, no macOS/Windows VM path — and
docker cp out of a running container is a real behaviour change in
host_copy and ext checkout.

[Copilot]

🟡 Changes recommended

It introduces confirmed correctness/operational issues in the new session-container infrastructure (SIGINT reaper arming, blocking exec in async contexts, and PID liveness probing) that should be fixed before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR reduces container startup overhead by introducing per-invocation, per-shape reusable “session containers” and routing multiple previously one-shot container operations through docker exec into those long-lived containers, with teardown on exit/Ctrl-C.

Changes:

• Add SessionContainers registry in utils/container.rs to reuse containers by derived docker run shape and exec steps into them.
• Route various volume-based utilities (host_copy, extension config reads, profiles, save, ext checkout probes/cp) through volume-scoped session containers.
• Add teardown paths (main exit, atexit, Ctrl-C) and update docs/changelog accordingly.

File summaries

File	Description
src/utils/container.rs	Implements session-container registry, shape/env splitting, teardown, and exec routing.
src/utils/host_copy.rs	Switches volume copy-out to docker cp from a running session container.
src/utils/ext_source_reader.rs	Reads extension configs via session container using SDK image when available.
src/utils/config.rs	Passes SDK image into extension discovery for container-based reads.
src/commands/save.rs	Uses volume session container for du and streaming tar.
src/commands/profiles.rs	Reads stone manifest via volume session container exec.
src/commands/ext/checkout.rs	Reuses one volume session container for probes and docker cp.
src/commands/rootfs/image.rs	Updates copy_volume_path_to_host call for new SDK image parameter.
src/commands/kernel/image.rs	Updates copy_volume_path_to_host call for new SDK image parameter.
src/commands/initramfs/image.rs	Updates copy_volume_path_to_host call for new SDK image parameter.
src/utils/stamps.rs	Ensures session containers are torn down on stamp failure exit path.
src/main.rs	Adds normal-exit session container shutdown.
CHANGELOG.md	Documents the new session container behavior and teardown.

Review details

• Files reviewed: 13/13 changed files
• Comments generated: 5
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[mobileoverlord]

@copilot review