Add OCI runtime surface and compat test fixtures

Make `oci run` work against real public images (alpine, busybox,
python, ruby, debian) and lock the surface down with end-to-end
fixtures.

Runtime surface:

- writable clone-rootfs DoD: the per-run rootfs is writable
  out of the box, so guests that mutate /tmp, /var, /run work
  unchanged
- runtime files injection: /etc/resolv.conf, /etc/hosts,
  /etc/hostname populated from the host into the clone-rootfs
- /dev/full and /dev/console emulation in the syscall layer
- /proc surface: cgroup, hostname, comm, statm entries that
  glibc startup and procps tooling read
- image-config `User` symbolic resolution: name and name:group
  forms looked up against the guest /etc/passwd and /etc/group
  before falling back to numeric
- `oci run` walks the image index to the linux/arm64 leaf manifest
  (Phase 3 fix; previously fed the top-level index to the
  config-loader and crashed on multi-arch images)

Bug fixes uncovered by cold-cache runs:

- layer apply no longer rejects the root tar entry "./"
- unpack stages files via copyfile(2) with COPYFILE_CLONE fallback
  so cross-volume unpack (store on internal SSD, sysroot on the
  APFS sparsebundle) succeeds
- tar reader handles PAX 'x' / 'g' extended-header `path` and
  `linkpath` records (busybox and python:alpine layers use them)

Compat tests:

- `tests/test-oci-compat.sh` shell smoke (in-tree fixtures)
- `OCI_COMPAT_TEST=1` heavy mode that provisions a scratch
  sparsebundle and drives three fixtures end-to-end:
  alpine-shaped, busybox-shaped hardlink dispatch, two-layer
  whiteout
- `OCI_FETCH_ONLINE=1` alpine:3 end-to-end smoke (opt-in;
  requires network)

`ELFUSE_OCI_PROGRESS=plain` env disables the pull progress
in-place CSI redraw for terminals that don't honor cursor-up
escapes (issue surfaced on legacy Terminal.app panes).

Documentation: `docs/oci.md` Phase 4 runtime surface and
libc-adjacent envelope notes (what guests can / can't expect
from the synthetic /etc, /dev, /proc).

Author: Max042004

Makefile

@@ -91,7 +91,9 @@ SRCS := \
     oci/unpack.c \
     oci/rebuild-cache.c \
     oci/runspec.c \
+    oci/user-lookup.c \
     oci/path-resolve.c \
+    oci/runtime-files.c \
     oci/run.c
 
 SRCS := $(addprefix src/,$(SRCS))
@@ -303,11 +305,19 @@ $(BUILD_DIR)/test-oci-tar: $(BUILD_DIR)/test-oci-tar.o $(BUILD_DIR)/oci/tar.o |
 	@echo "  LD      $@"
 	$(Q)$(CC) $(CFLAGS) -o $@ $^
 
-## Build the OCI runspec unit test (native macOS, no HVF). Pure-data
-## merge of image-config runtime block + CLI overrides; the test feeds
-## oci_image_runtime_t literals directly through oci_runspec_build with
-## no filesystem or libcurl dependency.
-$(BUILD_DIR)/test-oci-runspec: $(BUILD_DIR)/test-oci-runspec.o $(BUILD_DIR)/oci/runspec.o | $(BUILD_DIR)
+## Build the OCI runspec unit test (native macOS, no HVF). Merges
+## image-config runtime block + CLI overrides; the rootfs-driven
+## symbolic-User cases write /etc/passwd and /etc/group fixtures under
+## /tmp, so the link island pulls in oci/user-lookup.o.
+$(BUILD_DIR)/test-oci-runspec: $(BUILD_DIR)/test-oci-runspec.o $(BUILD_DIR)/oci/runspec.o $(BUILD_DIR)/oci/user-lookup.o | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^
+
+## Build the OCI User-field resolver unit test (native macOS, no HVF).
+## Pure C; the test builds scratch /tmp rootfses with synthetic
+## /etc/passwd / /etc/group and drives oci_user_lookup across the seven
+## OCI image-spec User shapes plus the policy edges.
+$(BUILD_DIR)/test-oci-user: $(BUILD_DIR)/test-oci-user.o $(BUILD_DIR)/oci/user-lookup.o | $(BUILD_DIR)
 	@echo "  LD      $@"
 	$(Q)$(CC) $(CFLAGS) -o $@ $^
 
@@ -325,10 +335,18 @@ $(BUILD_DIR)/test-oci-path-resolve: $(BUILD_DIR)/test-oci-path-resolve.o $(BUILD
 ## the test ships an in-file elfuse_launch stub that aborts when called,
 ## and every case installs a launch hook via oci_run_set_launch_for_testing
 ## before invoking oci_run, so the real VM bring-up never runs from a test.
-$(BUILD_DIR)/test-oci-run: $(BUILD_DIR)/test-oci-run.o $(BUILD_DIR)/oci/run.o $(BUILD_DIR)/oci/runspec.o $(BUILD_DIR)/oci/path-resolve.o $(BUILD_DIR)/oci/unpack.o $(BUILD_DIR)/oci/volume.o $(BUILD_DIR)/oci/volume-list.o $(BUILD_DIR)/oci/clone-rootfs.o $(BUILD_DIR)/oci/layer-apply.o $(BUILD_DIR)/oci/layer-meta.o $(BUILD_DIR)/oci/origin-meta.o $(BUILD_DIR)/oci/decompress.o $(BUILD_DIR)/oci/tar.o $(BUILD_DIR)/oci/store.o $(BUILD_DIR)/oci/blob-store.o $(BUILD_DIR)/oci/digest.o $(BUILD_DIR)/oci/digest-set.o $(BUILD_DIR)/oci/manifest.o $(BUILD_DIR)/oci/media-type.o $(BUILD_DIR)/oci/ref.o $(BUILD_DIR)/core/sysroot.o $(BUILD_DIR)/debug/log.o $(CJSON_OBJ) $(ZSTD_OBJS) | $(BUILD_DIR)
+$(BUILD_DIR)/test-oci-run: $(BUILD_DIR)/test-oci-run.o $(BUILD_DIR)/oci/run.o $(BUILD_DIR)/oci/runspec.o $(BUILD_DIR)/oci/user-lookup.o $(BUILD_DIR)/oci/path-resolve.o $(BUILD_DIR)/oci/runtime-files.o $(BUILD_DIR)/oci/unpack.o $(BUILD_DIR)/oci/volume.o $(BUILD_DIR)/oci/volume-list.o $(BUILD_DIR)/oci/clone-rootfs.o $(BUILD_DIR)/oci/layer-apply.o $(BUILD_DIR)/oci/layer-meta.o $(BUILD_DIR)/oci/origin-meta.o $(BUILD_DIR)/oci/decompress.o $(BUILD_DIR)/oci/tar.o $(BUILD_DIR)/oci/store.o $(BUILD_DIR)/oci/blob-store.o $(BUILD_DIR)/oci/digest.o $(BUILD_DIR)/oci/digest-set.o $(BUILD_DIR)/oci/manifest.o $(BUILD_DIR)/oci/media-type.o $(BUILD_DIR)/oci/ref.o $(BUILD_DIR)/core/sysroot.o $(BUILD_DIR)/debug/log.o $(CJSON_OBJ) $(ZSTD_OBJS) | $(BUILD_DIR)
 	@echo "  LD      $@"
 	$(Q)$(CC) $(CFLAGS) -o $@ $^ -lz
 
+## Build the OCI runtime-files injection unit test (native macOS, no HVF).
+## Pure C; the test drives oci_runtime_files_inject against scratch
+## /tmp/elfuse-rf-* run directories and verifies the synthesised
+## /etc/{resolv.conf,hosts,hostname} content.
+$(BUILD_DIR)/test-oci-runtime-files: $(BUILD_DIR)/test-oci-runtime-files.o $(BUILD_DIR)/oci/runtime-files.o | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^
+
 ## Build the OCI fixture builder (Phase 3 compat tests). Standalone tool
 ## that synthesises a complete OCI store from uncompressed-tar layers
 ## plus image-config flags. Used by tests/test-oci-compat.sh and

docs/usage.md

@@ -166,11 +166,16 @@ Image-provided `DYLD_*` entries pass through (the guest ignores them).
 
 ### User and WorkingDir
 
-`User` accepts numeric `UID` or `UID:GID` only. Symbolic users (`User
-nginx`) are rejected with a deterministic Phase 4 pointer message;
-static `/etc/passwd` parsing waits for Phase 4 along with the rest of
-the NSS resolution work. `--user UID` alone defaults GID to the same
-value.
+`User` accepts seven shapes: the empty string (no override), a numeric
+`UID`, `UID:GID`, a symbolic `name`, `name:group`, `uid:group`, or
+`name:gid`. Symbolic forms read `/etc/passwd` and `/etc/group` from
+the cloned rootfs. A token made entirely of ASCII digits is always
+parsed numerically, even when a same-named account ships in the image
+(this matches runc semantics, so an image that happens to carry a
+`1234` account does not capture `--user 1234`). When the symbolic
+form names an account the unpacked layers do not actually carry,
+lookup fails closed; `elfuse` never silently falls back to root.
+`--user UID` alone defaults GID to the same value.
 
 `WorkingDir` must be absolute and free of `..` segments. If neither the
 image nor the CLI sets it, the guest starts in `/`. The directory is
@@ -180,12 +185,93 @@ selects credentials).
 
 ### Scope guardrails
 
-- Symbolic `User` -> Phase 4 (NSS / static `/etc/passwd` resolution)
-- `/etc/resolv.conf`, `/etc/hosts`, `/dev/*`, `/proc/*` synthesis -> Phase 4
 - Auto-pull on `run` miss -> never; `elfuse oci pull` must run first
 - Network policy, `docker run -p`-style port mapping -> later phases
 - Live `docker exec`-style attach -> never
 
+### Runtime host-truth surface
+
+`elfuse oci run` runs the guest against a freshly cloned per-run
+rootfs and a small set of synthesized host-truth files. The rootfs
+is produced by APFS `clonefile(2)` against the unpacked image
+layers, so the first guest write to any path triggers copy-on-write
+in APFS without touching the original image. The clone is removed at
+guest exit unless `--keep` is set; nothing is ever pushed back to
+the on-disk image, and concurrent `oci run` invocations against the
+same image are isolated.
+
+Three `/etc` files are overwritten in the clone before the guest
+starts. Any pre-existing symlink (the common case is
+`/etc/resolv.conf -> /run/systemd/resolve/stub-resolv.conf`) is
+unlinked first so it does not dangle inside the guest:
+
+| File | Source |
+|--|--|
+| `/etc/resolv.conf` | `nameserver` lines harvested from `scutil --dns`; falls back to `8.8.8.8` and `1.1.1.1` on any scutil failure |
+| `/etc/hosts` | fixed 5-line block: `localhost`, the ip6-loopback aliases, ip6 link-local multicast, and `127.0.0.1 host.elfuse.internal` |
+| `/etc/hostname` | literal string `elfuse` |
+
+The following pseudo-filesystem paths are synthesized by the host-side
+openat interceptor and do not need to exist inside the rootfs:
+
+| Path | Behavior |
+|--|--|
+| `/dev/null`, `/dev/zero`, `/dev/random`, `/dev/urandom`, `/dev/tty` | redirected to the host device of the same name |
+| `/dev/full` | reads zero-fill, writes of any non-zero length return `ENOSPC` |
+| `/dev/console` | mirrored from the controlling tty when present (macOS reserves the real `/dev/console` for the kernel) |
+| other `/dev/*` | `ENOENT` |
+| `/proc/cpuinfo`, `/proc/meminfo`, `/proc/version` | derived from host sysctl |
+| `/proc/self/{maps,exe,status,stat,comm,statm,cgroup}` | synthesized; `cgroup` reports the canonical `0::/` (elfuse runs outside any cgroup hierarchy) |
+| `/proc/sys/kernel/{ostype,osrelease,hostname}` | tracks the cached `uname` fields (`Linux`, `6.17.0-20-generic`, `elfuse`) |
+
+### Libc-adjacent compatibility
+
+`elfuse` does not patch libc-adjacent payload (NSS modules, time-zone
+data, locale data, character-set converters, dynamic-linker cache)
+inside the guest. Each item below names the contract `elfuse` honors
+and the failure mode an image hits when it does not ship the
+matching files.
+
+- **`/etc/nsswitch.conf`** is read by the guest's libc, not by
+  `elfuse`. Only the `files` and `dns` backends actually function:
+  `files` resolves through `/etc/{passwd,group,hosts}` in the cloned
+  rootfs, and `dns` resolves through host `getaddrinfo` via the
+  synthesized `/etc/resolv.conf`. Backends such as `systemd`, `sss`,
+  or `ldap` need their NSS shared object plus a matching daemon,
+  neither of which `elfuse` provides.
+- **NSS shared objects** (`libnss_systemd.so`, `libnss_sss.so`,
+  `libnss_ldap.so`, ...) are `dlopen`'d by guest libc against its own
+  loader. `elfuse` never injects NSS modules: they are aarch64-linux
+  ELF objects against guest libc, so the macOS host has no way to
+  load them, and the guest can only `dlopen` the modules its image
+  already carries.
+- **tzdata** (`/usr/share/zoneinfo`, `/etc/localtime`, `/etc/timezone`)
+  ships with the image. `elfuse` does not transcode macOS
+  `/var/db/timezone/zoneinfo` into the tzdata format; if the image is
+  missing the needed zone, glibc / musl fall back to UTC. The `TZ`
+  environment variable is honored as-is and is not rewritten by the
+  Env merge policy.
+- **`/usr/lib/locale/locale-archive`** is not regenerated. glibc
+  images without a built archive (or the matching `<lang>.UTF-8/`
+  directory) fall back to the `C` locale; locale-aware sort / printf
+  / strcoll outputs ASCII order. musl images do not use the archive
+  and are unaffected.
+- **`/usr/lib/<triple>/gconv/`** modules and the `gconv-modules`
+  index ship with the image. Missing modules surface as `EILSEQ` from
+  `iconv` / glibc's character-set conversion; this most often shows
+  up when an image ships a stripped glibc layer.
+- **`ld.so.cache`** is not rebuilt. The guest dynamic linker reads
+  whatever cache the image carries; missing entries fall through to
+  the linker's library-path search, which is the normal slow path.
+
+Common workloads and the symptom-to-workaround mapping:
+
+| Symptom | Trigger | Workaround |
+|--|--|--|
+| `getaddrinfo` returns `EAI_AGAIN` or an empty result | `/etc/nsswitch.conf` lists a backend (`systemd`, `sss`, ...) that needs a daemon | use a distro whose `nsswitch.conf` is `files dns` (alpine ships this by default; debian needs the file edited) |
+| `date`, `strftime` show UTC instead of the expected zone | the image does not contain `/usr/share/zoneinfo/<Zone>` | install tzdata in the image (`apk add tzdata` / `apt install tzdata`), or pass `-e TZ=UTC` to acknowledge UTC |
+| `sort`, `printf`, `strcoll` collate in ASCII order | the image is missing `/usr/lib/locale/locale-archive` or the matching `<lang>.UTF-8/` directory | accept the C-locale fallback, run `locale-gen` during the image build, or use a musl-based image (alpine), which does not depend on the archive |
+
 ## Guest Compatibility Model
 
 `elfuse` is designed for Linux user-space workloads, not for booting a Linux

mk/tests.mk

@@ -14,7 +14,8 @@
         test-oci-tar test-oci-decompress test-oci-meta \
         test-oci-origin \
         test-oci-layer-apply test-oci-volume test-oci-clone \
-        test-oci-unpack test-oci-runspec test-oci-path-resolve \
+        test-oci-unpack test-oci-runspec test-oci-user test-oci-path-resolve \
+        test-oci-runtime-files \
         test-oci-run test-oci-compat oci-fixture-builder \
         test-sysroot-rename \
         test-case-collision test-case-collision-fallback test-sysroot-create-paths \
@@ -88,8 +89,12 @@ check: $(ELFUSE_BIN) $(TEST_DEPS) check-syscall-coverage
 	@$(MAKE) --no-print-directory test-oci-unpack
 	@printf "\n$(BLUE)━━━ OCI runspec resolver unit tests ━━━$(RESET)\n"
 	@$(MAKE) --no-print-directory test-oci-runspec
+	@printf "\n$(BLUE)━━━ OCI User-field resolver unit tests ━━━$(RESET)\n"
+	@$(MAKE) --no-print-directory test-oci-user
 	@printf "\n$(BLUE)━━━ OCI path-resolve unit tests ━━━$(RESET)\n"
 	@$(MAKE) --no-print-directory test-oci-path-resolve
+	@printf "\n$(BLUE)━━━ OCI runtime-files injection unit tests ━━━$(RESET)\n"
+	@$(MAKE) --no-print-directory test-oci-runtime-files
 	@printf "\n$(BLUE)━━━ OCI run orchestrator unit tests ━━━$(RESET)\n"
 	@$(MAKE) --no-print-directory test-oci-run
 	@printf "\n$(BLUE)━━━ OCI compat shell smoke ━━━$(RESET)\n"
@@ -200,19 +205,36 @@ test-oci-unpack: $(BUILD_DIR)/test-oci-unpack
 	@$(BUILD_DIR)/test-oci-unpack
 
 ## Run the OCI runspec resolver unit tests (native, no HVF, no network).
-## Pure data: feeds hand-built oci_image_runtime_t literals plus synthetic
-## CLI flags through oci_runspec_build and asserts argv / envp / uid / cwd
-## outputs against the Phase 3 override matrix and Env policy.
+## Feeds hand-built oci_image_runtime_t literals plus synthetic CLI flags
+## through oci_runspec_build and asserts argv / envp / uid / cwd outputs
+## against the Phase 3 override matrix and Env policy. Phase 4 symbolic
+## User cases write scratch /tmp rootfses for /etc/passwd lookup.
 test-oci-runspec: $(BUILD_DIR)/test-oci-runspec
 	@$(BUILD_DIR)/test-oci-runspec
 
+## Run the OCI User-field resolver unit tests (native, no HVF, no network).
+## Phase 4 F4.7: validates oci_user_lookup against scratch rootfses
+## carrying synthetic /etc/passwd / /etc/group; covers the seven OCI
+## image-spec User shapes plus the policy edges (digit-name collision,
+## missing passwd, name-not-found, invalid characters).
+test-oci-user: $(BUILD_DIR)/test-oci-user
+	@$(BUILD_DIR)/test-oci-user
+
 ## Run the OCI guest PATH resolver unit tests (native, no HVF, no network).
 ## Builds a fake sysroot tree under /tmp and drives oci_path_resolve
 ## against it: PATH search, symlink-follow, escape-symlink skip,
 ## EACCES on noexec, ENOENT diagnostics with searched-dirs list.
 test-oci-path-resolve: $(BUILD_DIR)/test-oci-path-resolve
 	@$(BUILD_DIR)/test-oci-path-resolve
 
+## Run the OCI runtime-files injection unit tests (native, no HVF, no network).
+## Phase 4 F4.2 / F4.3: validates oci_runtime_files_inject against scratch
+## run directories, covering fresh-/etc creation, symlink overwrite,
+## regular-file overwrite, and the synthesised /etc/{resolv.conf,
+## hosts, hostname} content.
+test-oci-runtime-files: $(BUILD_DIR)/test-oci-runtime-files
+	@$(BUILD_DIR)/test-oci-runtime-files
+
 ## Run the OCI run orchestrator unit tests (native, no HVF, no network).
 ## Covers oci_cli_run argument parsing plus oci_run early-failure
 ## paths against a case-insensitive volume; the launch backend is

src/oci/cli.c

@@ -70,6 +70,10 @@ static int print_usage(FILE *out)
         "                        re-fetch missing layer blobs\n"
         "  -q, --quiet           Suppress per-blob progress output\n"
         "\n"
+        "Env: ELFUSE_OCI_PROGRESS=plain disables the in-place TTY\n"
+        "     redraw (use when the terminal mis-handles CSI cursor-up;\n"
+        "     prints one summary line per blob on completion).\n"
+        "\n"
         "Policy: optional policy.json controls per-registry insecure /\n"
         "        ca_bundle / auth_file. Read from $ELFUSE_POLICY_FILE >\n"
         "        $XDG_CONFIG_HOME/elfuse/policy.json >\n"

src/oci/layer-apply.c

@@ -527,6 +527,16 @@ static int layer_apply_impl(oci_tar_reader_t *r,
         while (gp[0] == '/')
             gp++;
 
+        /* Root-directory tar entry: docker/buildkit emit "./" as the
+         * first entry of a layer; the DIR-type trailing-slash strip
+         * upstream collapses it to ".". The unpack root already
+         * exists by the time the assembler enters this loop, so the
+         * root entry has no work to drive. Skip empty paths the same
+         * way for archives that record a zero-length root name.
+         */
+        if (gp[0] == '\0' || (gp[0] == '.' && gp[1] == '\0'))
+            continue;
+
         if (mode == APPLY_MODE_OVERLAY) {
             if (e.is_opaque_whiteout) {
                 oci_tar_entry_t e2 = e;

src/oci/pull.c

@@ -150,6 +150,20 @@ static int pull_progress_init(pull_progress_t *pp, FILE *fp,
     memset(pp, 0, sizeof(*pp));
     pp->fp = fp;
     pp->is_tty = fp != NULL && isatty(fileno(fp));
+    /* ELFUSE_OCI_PROGRESS=plain (or =lines, =off) forces the
+     * line-per-completion path even on a real TTY. Some terminal panes
+     * (notably embedded ones that emulate a pty without honoring CSI
+     * cursor-up) leave the in-place redraw stacking copies down the
+     * screen instead of rewriting the active rows; the env override
+     * gives the operator a stable opt-out without touching code.
+     */
+    if (pp->is_tty) {
+        const char *override = getenv("ELFUSE_OCI_PROGRESS");
+        if (override
+            && (!strcmp(override, "plain") || !strcmp(override, "lines")
+                || !strcmp(override, "off")))
+            pp->is_tty = false;
+    }
 
     size_t cap = 1 + n_layers;
     pp->slots = calloc(cap, sizeof(*pp->slots));