fix(core): carry the image's declared Env into the OCI bundle

[Lupus]

Closes #222

The reported axis is a red herring

izba exec <sandbox> -- cat /etc/os-release failed with crun's not found in $PATH while absolute paths worked. The issue framed this as ubuntu-vs-alpine. It is not: I pulled both raw config blobs and ubuntu:24.04 and alpine:3.20 declare a byte-identical PATH in identically-shaped OCI configs (both OCI index -> OCI manifest -> OCI config media types).

The real axis is cache vintage. Any image whose cache entry predates crun support breaks this way, on any distro.

Root cause, hop by hop

1. ImageStore::is_cached keys only on rootfs.erofs — it never checks config.json.
2. An image dir written by a pre-crun izba has the layers and no config blob, so it counts as fully cached. (All three entries in my local data root are exactly that shape.)
3. The self-heal in ensure_image only runs on the registry path — the local-tag fast path returns before it, and izba start on an existing sandbox never calls ensure_image at all.
4. load_config -> Ok(None).
5. sandbox::start accepted that silently (the old comment said so verbatim).
6. generate_spec's cfg.and_then(..).unwrap_or_default() -> empty image env, so oci/config.json's process.env shipped with no PATH.
7. crun clearenv()s, seeds an exec from exactly that env (merge_env = true), then resolves the binary with getenv("PATH") — NULL. Hence the error.

izba's design comment at exec.rs:283 is correct and is preserved. crun does apply the image's PATH; izba must not guess a default. The bundle simply had nothing to apply. No default PATH is injected anywhere in this PR.

Changes

• ImageStore::is_complete (rootfs and config.json). ensure_image's local-tag fast path now gates on it, so a config-less entry falls through to the registry path where the cheap self-heal already lives, instead of short-circuiting past it.
• require_image_config — sandbox::start fails loudly and actionably instead of silently building an env-less container. The distinction that matters: config absent = "we don't know the image's env" (a defect); config present but declaring no Env = "the image declares none" (oci-archive:, FROM scratch) and is passed through untouched.
• Fixtures seed COMPLETE cache entries — the shape ensure_image guarantees. The fixture image declares a deliberately implausible PATH so a propagation assertion cannot pass by coincidentally matching a guessed default.
• exec_collect_env — the integration suite injected PATH=STD_PATH into every exec and no call site could override it, so it would have passed even if the guest delivered an env-less container. Tests can now send an empty env, like the real CLI does.

Acceptance criteria

AC	Status
1. bare cat/sh/ls succeed on ubuntu:24.04	non_alpine_image_bare_commands_resolve_via_the_images_declared_path (KVM)
2. observed PATH == image's declared PATH, not a hardcoded expectation	asserted against the image's own OCI config read back from the image store, both host-side (start_propagates_the_images_declared_path_into_the_bundle) and in-VM (printenv PATH)
3. no default PATH injected; guard at exec.rs:890 still passes	yes — plus a new matching guard on the ssh path
4. at least one non-alpine e2e	ubuntu:24.04, the first non-Alpine-family sandbox rootfs in the suite
5. izba ssh / restricted login shell checked	same crun exec, same container-definition env — identical exposure, fixed by the same host-side change, now guarded by ssh_session_crun_argv_never_injects_a_path

Verification

All six workspace gates green locally: cargo test --workspace (1382 in izba-core alone, 0 failed), clippy --workspace --all-targets -D warnings, fmt --check, izba-init musl (static-pie confirmed), windows-gnu check + clippy.

The host-side propagation test was verified non-vacuous by sabotage: with the image config forced to None it fails with process.env containing only the six trust-CA vars and no PATH — a verbatim reproduction of #222.

The new integration test is KVM-gated and e2e.yml does not run on PRs, so I am dispatching it manually on this branch; local artifacts here predate the crun/kernel work and would fail for unrelated reasons.

Note for review

start now refuses a sandbox whose image cache entry has no config.json. That is deliberate — such a sandbox is already broken (every bare command fails) — but it does turn a silent degradation into a hard error at start, so it is the judgement call most worth a second opinion. The alternative considered was self-healing at start via a manifest fetch, rejected because it would make izba start network-dependent.

🤖 Generated with Claude Code

Greptile Summary

This revision carries the image’s declared environment into generated OCI bundles and rejects legacy cache entries whose image configuration is unavailable.

• Adds an explicit complete-cache predicate while preserving local-tag precedence.
• Requires image configuration during sandbox startup and provides non-destructive recovery guidance.
• Seeds complete image fixtures and adds host-side and KVM-gated PATH propagation coverage.
• Adds guards ensuring exec and SSH paths do not inject a default PATH.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
crates/izba-core/src/image/mod.rs	Preserves local-tag precedence for cached entries while documenting that missing runtime configuration is rejected during startup.
crates/izba-core/src/image/store.rs	Adds is_complete to distinguish rootfs-only legacy entries from cache entries containing runtime configuration.
crates/izba-core/src/sandbox.rs	Requires cached image configuration before generating the OCI bundle and propagates the image’s declared environment.
crates/izba-core/tests/integration.rs	Adds caller-controlled exec environments and KVM-gated coverage for bare-command resolution through the image-declared PATH.
crates/izba-init/src/ssh.rs	Adds a regression guard confirming SSH sessions do not inject their own PATH.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Start sandbox] --> B[Load cached image config]
  B -->|Present| C[Generate OCI bundle]
  C --> D[Copy image Env into process.env]
  D --> E[crun exec resolves bare commands using image PATH]
  B -->|Missing| F[Fail startup with cache-repair guidance]

Loading

_{Reviews (3): Last reviewed commit: "fix(core): keep local-tag precedence and..." | Re-trigger Greptile}

Context used (3)

• Knowledge Base — Image pipeline
• Knowledge Base — Sandbox lifecycle
• Knowledge Base — Guest init (izba-init)

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
98.6% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud