Add OCI image support - #191

An OCI image front end needs to set the guest identity, working
directory, and environment without patching the runtime; the new
flags map onto launch_args_t fields and `elfuse-oci run` drives
exactly this interface.

The --user identity is staged before bring-up (proc_set_initial_ids)
so the auxv AT_UID/AT_GID snapshot taken by build_linux_stack matches
what getuid()/getgid() later report. --workdir rejects non-absolute
paths up front instead of silently resolving them against the host
cwd, and is applied by elfuse_launch after the casefold probe so the
translation sees the sysroot's real case behavior. --env/--clear-env
build the guest environment with env(1) semantics: KEY=VAL sets,
bare KEY inherits from the host environ, --clear-env starts empty;
with neither flag given envp stays NULL and the host environ is used
unchanged.

The new heap resources join main()'s shared goto unwind: envp,
workdir, and the raw --env override array are released at the single
cleanup label on every exit path.

elfuse-oci is a standalone Go binary that owns the OCI image pipeline;
elfuse itself stays a pure Linux syscall-to-Darwin runtime with no OCI
commands. This first slice is the acquisition half: an OCI image-layout
store plus the pull and inspect commands, built on go-containerregistry
($ELFUSE_OCI_STORE or ~/.local/share/elfuse/oci by default).

The store is a spec-shape image layout other tools can read, with a
refs.json pin table mapping references to manifest digests. An exclusive
flock serializes refs.json/index.json updates so concurrent pulls cannot
lose pins (the cold-store bootstrap of oci-layout and index.json runs
under the same lock, double-checked so a warm store skips it), pin
persistence syncs the temp file and directory around the rename, and a
nil-object refs.json is rejected as corrupt instead of treated as empty.
addImage distinguishes genuinely-absent from unreadable descriptors by
scanning index membership, so store corruption surfaces rather than
duplicating entries. digestFor returns a distinct errNotPulled for a
missing ref so later callers can tell "not pulled" from "store broken".

Two helpers keep the plumbing in one place: every subcommand opens the
store through commonFlags.openResolvedStore (resolve the store path,
then open the layout), and store.withLock scopes lock-held sections; pin
and addImage wrap their load-modify-save cycles in it so a critical
section cannot leak its lock on an error path.

pull resolves the requested platform (default linux/arm64) and validates
--platform shape up front; inspect prints the manifest and config
summary (or --json) and propagates digest/size and writer errors instead
of reporting partial output as success.

Credentials come from the ambient default keychain, but its resolution
is time-bounded: it shells out to whatever helper the Docker config
names, and go-containerregistry drops the context around that exec, so a
wedged helper would otherwise hang the pull with no output. A wrapper
keychain caps the wait and fails with an explanation and the
DOCKER_CONFIG escape hatch instead; a progress line is printed before
the pull so it is never silent.

Tests cover the pin table, store locking, error kinds, flag parsing, and
the command dispatch, with cranePull as a swappable seam so no test
touches the network.

Apply a stored image's layers into a rootfs directory, whiteouts and
all, so `unpack` (and later `run`) can materialize a filesystem tree
from the store without any external tool.

Layer application is hardened against hostile archives: extraction is
bounded by os.Root so no entry, symlink, or hardlink escapes the
destination; member names and hard-link targets archived absolute
(GNU tar -P builders) are applied root-relative, as other OCI
consumers do; parent components are Lstat'd and a symlinked or non-dir
intermediate is replaced with a real directory (containerd/Docker
behavior); opaque whiteouts clear through a real directory only, are
order-independent within a layer, and an invalid bare .wh. entry
fails extraction instead of deleting its parent; a directory entry
replaces a lower-layer non-directory. File bodies are bounded by the
tar header size and short bodies are an error, and permissions are
finalized with an explicit chmod so the host umask cannot skew modes.

setuid/setgid/sticky bits are re-applied where the host allows it, and
degrade gracefully where it does not. An unprivileged chmod that sets
setuid/setgid is rejected with EPERM on macOS when the unpacked file's
inherited group is one the invoking user is not in (a new file takes
its parent directory's group under BSD semantics, e.g. wheel under
/tmp, not the tar's root/shadow owner). Since the rootfs is owned by
the invoking user those bits could not be honored at runtime there
anyway, so they are dropped with a warning naming the lost bit rather
than aborting the whole unpack, which is what lets Debian-family
images and their shadow suite (chage, passwd, ...) unpack at all.
Reported at
sysprog21#191 (comment)

Unpack stages into a temp sibling directory and renames into the
final cache path (keyed by manifest digest under <store>/rootfs/), so
a concurrent reader never observes a partial tree and the loser of a
rename race adopts the winner's complete one. A failed unpack removes
only what it created.

Tests drive whiteouts, opaque ordering, parent-symlink replacement,
hardlink identity, exact-size reads, mode preservation, the special-
bit degrade decision, and the staged-rename semantics over synthetic
layer tarballs.

run is the last pipeline stage: resolve the image config into a concrete
runspec, materialize the rootfs, and exec the existing `elfuse --sysroot
<rootfs> ...` positional launch path, reusing elfuse's HVF bring-up,
shebang, and dynamic-linker plumbing rather than reinventing guest
launch. elfuse is located as a sibling binary ($ELFUSE_BIN overrides for
tests) and replaced via exec so the shell reaps the same pid and
terminal signals reach the guest directly.

The runspec resolves Entrypoint/Cmd/Env/User/WorkingDir with the usual
precedence (--entrypoint drops image Cmd; --env and --clear-env follow
env(1) semantics; --workdir must be guest-absolute). A PATH is
guaranteed: when neither the image config nor --env supplies one,
Docker's conventional default is appended, so a guest whose image omits
PATH still has a search path after the --clear-env launch. A relative
path command resolves against the working directory and a bare name
against the merged PATH inside the image rootfs, following Docker's
exec-form rules (elfuse resolves the initial ELF before applying
--workdir and does no PATH lookup, so the launcher must); a config-only
image WorkingDir no layer ships is created at run time, as runc does. A
symbolic --user or image User is resolved against the image's own
/etc/passwd and /etc/group through os.Root-bounded, no-follow opens, so
a crafted rootfs cannot redirect resolution to host account files.

run auto-pulls only when the ref is genuinely absent (errNotPulled) and
surfaces store corruption instead of masking it behind a network pull;
an explicit --platform must match the pinned image so a ref pulled for
another architecture is not silently launched. Before exec, host-truth
/etc/{resolv.conf,hosts,hostname} are injected into the rootfs through
the same os.Root bounds.

Tests cover runspec resolution and precedence, symbolic user lookup,
runtime-file injection, and the exec argv shape via the execElfuseForRun
seam and a subprocess exec probe.

A plain directory rootfs on the default case-insensitive APFS volume
folds Linux filenames that differ only by case. Default runs now use
a case-sensitive APFS sparsebundle per pinned manifest digest, with a
per-run clonefile COW rootfs so guest writes never mutate the warm
base tree and repeated runs skip the unpack.

Liveness and lifecycle transitions are decided by per-digest advisory
flocks in the bundle directory (bundlelock.go), not by pids or
directory scans: every live run holds run.lock shared from before the
volume is attached until guest exit, so a killed run cannot leak
liveness, and attach.lock serializes provisioning (always acquired
before run.lock, making the exclusive-to-shared downgrade in
provision race-free). Provisioning reuses a mount a live run still
holds and only force-detaches one proven stale by an exclusive
run.lock probe, so a second run of the same digest can never rip the
rootfs out from under a live guest. --keep clones carry an
.elfuse-keep marker so sweeps preserve them.

The plain-rootfs path remains available with --plain-rootfs, and the
non-Darwin stub keeps elfuse-oci buildable for
pull/inspect/unpack tests on Linux.

Darwin tests drive runCaseSensitive through seams for provisioning,
clonefile, spawn, cleanup, and exit, and cover sparsebundle
provisioning, mount/detach, attach-failure teardown, and the lock
protocol with a fake hdiutil; the mount-probe and force-detach hooks
are function variables so tests need no real disk images.

The spawn path intercepts SIGHUP alongside INT/TERM/QUIT and installs
the handler before the child starts, so a hangup or an early signal
still flows through the forward/reap/teardown path. elfuse is invoked
with a "--" separator before the guest command, so an image
Entrypoint beginning with "-" cannot steer the host launcher. hdiutil
attach failures keep stderr in the error message (stdout stays clean
for the plist parse), and the parsed mount path is XML-entity-decoded
so a store path containing "&" or quotes still round-trips.

Add list/images, rmi, and prune on top of the OCI image-layout store.
rmi and prune use reachability GC: shared manifests, configs, and layers
stay on disk while any remaining ref reaches them.

Cache cleanup handles plain rootfs caches and macOS sparsebundle caches
through platform-specific seams, with safety rules for active workloads:
a prune without --all never touches a still-pinned digest's cache, and a
cache a live run still uses is never reclaimed. Liveness is the same
flock discipline on both cache kinds: the bundle's run.lock, and for the
plain digest-keyed rootfs a sibling <hex>.lock that a run holds shared
from before the existence probe until guest exit. The plain run path
execs elfuse in place, so the lock descriptor is made exec-survivable:
the kernel releases it exactly when the elfuse process exits, SIGKILL
included. prune takes each lock exclusively non-blocking and skips busy
caches (dry runs never advertise them); rmi refuses a busy cache even
with --force, before any pin or descriptor is touched. The lock is a
sibling of the cache dir, not inside it, because the dir is the guest's
/ and its existence is unpackImage's atomic-rename publication signal.

prune's GC sweep and list's snapshot run under the store lock, closing
the windows where a concurrent pull's fresh blobs could be reclaimed
before their descriptor lands or a listing could observe a half-removed
ref. prune scopes its GC-plus-cache sweep with store.withLock and drops
the lock before the reporting output; list and rmi keep the explicit
acquire-and-defer because their entire body is the critical section, so
a closure would only add indentation. list reports the full
os/arch/variant platform.

Two corrections to the unpack path come with the locking, because both
are what the lock discipline needs to be true. unpackImage now takes the
caller's already-resolved image rather than re-resolving a ref: the
caller keys the cache by the digest it resolved, so a re-resolution
could observe a different pin from a concurrent repull and fill digest
A's cache with image B's content. resolveImageForUse pairs the
resolution with the digest lock, which is why the fix lands here rather
than in the commit that introduced unpackImage. Layer application also
tracks the ancestors of each entry, so an opaque whiteout arriving after
an implicit parent directory no longer clears content the same layer
just added.

Tests cover reachability GC (shared blobs, stale temp blobs, digest
prefixes), the prune and rmi busy semantics for both cache kinds (live
holder, stale lock file, dry-run visibility), lock survival across the
exec boundary (FD_CLOEXEC clearing plus a child-process flock-lifetime
proxy), which runs hold the lock at exec time, and end-to-end command
wrappers over pull/run/list/rmi/prune. The darwin cache sweep is driven
through the isMountPointFn and detachForce seams with
reapSweepableClones deciding the reap set, so the sweep is testable
without real disk images.

The on-disk store is the contract: pulls must produce a valid OCI
image-layout that other tools can read and that agrees with registry
truth on the manifest digest. Conformance tests pin the layout shape,
and scripts/oci-interop.sh cross-checks the store with crane, skopeo,
and umoci.

CI splits by runner capability: a Linux job runs the pure-Go store
paths (pull, unpack, inspect, lifecycle) without Hypervisor.framework,
a hosted macOS job builds and tests the darwin sparsebundle code and
drives a run-less pull/inspect/list/rmi/prune lifecycle smoke, and the
self-hosted release leg boots guests end to end under HVF: the
alpine:3 default-entrypoint smoke plus a full pull -> inspect -> list
-> run -> rmi -> prune lifecycle that runs python:3.12-slim with an
--entrypoint override and asserts the teardown half of the lifecycle.

The lifecycle teardown covers all three reclamation guardrails: a
plain rmi reclaims the cold cache with the image, run --keep output
refuses rmi without --force, and a live --plain-rootfs guest parked
in sleep pins its cache; prune --cache --all must skip it and rmi
must refuse until the guest exits, the only end-to-end exercise of
the run-lock descriptor riding through the exec into elfuse.

Cover the two-binary model in README and docs: usage.md documents the
elfuse-oci commands and flags, testing.md the offline/CI
validation split, internals.md the host-literal path fallback
semantics, and oci-design.md records the design rationale (the C/Go
boundary, the image-layout store with its refs.json pin table, layer
application, run paths, and lifecycle GC), plus an explicit
scope-and-limitations accounting of which OCI features are and are
not implemented.

oci-design.md also records the concurrency model: store metadata is
lock-serialized, per-digest sparsebundle state is coordinated by the
attach.lock/run.lock pair, and the plain digest-keyed rootfs cache is
guarded by a sibling per-digest lock a run holds across the exec into
elfuse, so prune skips and rmi refuses a cache a live guest still
uses. usage.md notes the resolv.conf fallback nameserver and its
split-DNS implication.

README states the positioning up front: OCI images are consumed as a
distribution vehicle for Linux root filesystems, replacing hand-built
--sysroot trees, and the non-isolation limitations (host-path
fallback, shared network identity, PID space, and clock) are called
out explicitly rather than implied.

Issue sysprog21#224 profiled five real images (python:3.12-slim, node:22-alpine,
golang:1.23-alpine, eclipse-temurin:21, gcc:14). Add one CI job per
image that boots the image under HVF via `elfuse-oci run` and drives
that image's operations, so a change that breaks any of them is caught
on the PR rather than by hand.

A shared driver, scripts/ci/oci-workload.sh <key>, maps each key to its
image and guest workload under scripts/ci/workloads/ and asserts a
per-image sentinel token:

- python: a single-threaded SQLite insert plus an aggregate query, a
  small file write/read/checksum fan-out, and a JSON round-trip.
- node: in-guest compute (fs/crypto/zlib/JSON) plus an HTTP server the
  job reaches over the host loopback; elfuse maps guest sockets to host
  sockets and does no network-namespace isolation, so a guest bound to
  127.0.0.1 is reachable host-side.
- go: gofmt over a tree of misformatted fixtures the workload writes
  itself, asserting the file set it names, the bytes it produces, and
  that a second pass names nothing. The toolchain binaries are Go
  programs, so this drives the runtime's own scheduler and raw syscalls;
  it compiles nothing, because the guest compiler dies on SIGHUP before
  finishing a package.
- jvm: javac + java exercising collections, file I/O, SHA-256, an
  8-thread pool, and a subprocess.
- c: a small multi-file make project plus a heavier single translation
  unit compiled with gcc -O1.

The go and python lanes stay inside the runtime's current limits;
heavier variants that stress those limits, including an in-guest Go
build, are submitted separately.

The jobs run only on self-hosted Apple Silicon because `run` needs
Hypervisor.framework. They share a composite action that fetches the
elfuse binary from build-macos and builds elfuse-oci, and each keeps a
warm per-key store on the runner's persistent disk so only the first run
pulls over the network. gcc:14 and eclipse-temurin:21 ship the shadow
suite, so those jobs also exercise the unpack setuid/setgid degrade end
to end.

The existing python workload moves under scripts/ci/workloads/;
oci-lifecycle.sh follows the new path.

The run smoke proves an image boots and computes; these checks cross
the guest-execution seams it does not. A pathname AF_UNIX socket is
bound inside a guest-created directory with a getsockname round-trip:
the runtime translates sun_path into the sysroot on the way in and
must reverse-map it on the way out, and the sparsebundle clone's deep
host path additionally forces the over-length shortening indirection.
A cold-provision boot (blobs cloned into an ephemeral store with the
cs/ bundles dropped, so no network) must report the unpack, and the
following warm re-attach of the same digest must boot without
unpacking again. A dynamically linked from-image binary runs under an
explicit entrypoint so PT_INTERP and its shared-object closure must
resolve inside the rootfs.

Wired as a runtime-macos Release-leg step beside the run smoke,
sharing its warm store (python:3.12-slim joins alpine and debian
there).