kento-core 1.6.0.dev1__tar.gz → 1.6.0.dev3__tar.gz

{kento_core-1.6.0.dev1/src/kento_core.egg-info → kento_core-1.6.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kento-core
-Version: 1.6.0.dev1
+Version: 1.6.0.dev3
 Summary: Kento core library — compose OCI images into LXC/VM system containers (importable engine)
 License-Expression: GPL-3.0-only
 Requires-Python: >=3.11

{kento_core-1.6.0.dev1 → kento_core-1.6.0.dev3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kento-core"
-version = "1.6.0.dev1"
+version = "1.6.0.dev3"
 description = "Kento core library — compose OCI images into LXC/VM system containers (importable engine)"
 requires-python = ">=3.11"
 license = "GPL-3.0-only"

{kento_core-1.6.0.dev1 → kento_core-1.6.0.dev3}/src/kento/__init__.py

@@ -24,31 +24,37 @@ LXC_BASE = Path("/var/lib/lxc")
 VM_BASE = Path("/var/lib/kento/vm")
 
 _NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]*$")
-_NAME_MAX_LEN = 63
 
 
 def validate_name(name: str, *, what: str = "instance name") -> None:
     """Reject names that would enable injection or path traversal.
 
     Accepts: ASCII alphanumerics plus `_`, `.`, `-`. Must start with
-    alphanumeric. Max 63 chars (matches Linux HOST_NAME_MAX constraint).
+    alphanumeric. Max MAX_INSTANCE_NAME (64) chars -- the name becomes the
+    guest hostname (HOST_NAME_MAX) and is the last otherwise-uncapped
+    contributor to the overlay mount-options budget (see layers.py).
     Rejects: empty, whitespace, shell metacharacters, `/`, `..`, NUL.
 
     Raises ValidationError on rejection. what is used in the message for
     context (e.g. "instance name", "auto-generated name").
     """
+    from kento.defaults import MAX_INSTANCE_NAME
+
     if not isinstance(name, str) or not name:
         raise ValidationError(f"{what} cannot be empty")
-    if len(name) > _NAME_MAX_LEN:
+    if len(name) > MAX_INSTANCE_NAME:
         raise ValidationError(
-            f"{what} too long ({len(name)} chars, max {_NAME_MAX_LEN}): {name!r}"
+            f"{what} {name!r} is {len(name)} characters; the maximum is "
+            f"{MAX_INSTANCE_NAME} (it becomes the guest hostname and bounds "
+            f"the overlay mount options)."
         )
     if "\x00" in name:
         raise ValidationError(f"{what} contains NUL byte: {name!r}")
     if not _NAME_RE.match(name):
         raise ValidationError(
             f"invalid {what}: {name!r}. Names must start with a letter "
-            f"or digit and contain only [A-Za-z0-9_.-] (max {_NAME_MAX_LEN} chars)."
+            f"or digit and contain only [A-Za-z0-9_.-] "
+            f"(max {MAX_INSTANCE_NAME} chars)."
         )
 
 

{kento_core-1.6.0.dev1 → kento_core-1.6.0.dev3}/src/kento/create.py

@@ -9,14 +9,14 @@ from pathlib import Path
 from kento import (LXC_BASE, VM_BASE, _scan_namespace, next_instance_name,
                    require_root, sanitize_image_name, upper_base, validate_name)
 from kento.cloudinit import detect_cloudinit, write_seed
-from kento.defaults import (LXC_TTY, LXC_MOUNT_AUTO, LXC_MOUNT_AUTO_NESTING,
-                            LXC_ARG_DENYLIST, PVE_ARG_DENYLIST,
-                            QEMU_ARG_DENYLIST)
+from kento.defaults import (APPARMOR_SYSTEMD_RULES, LXC_TTY, LXC_MOUNT_AUTO,
+                            LXC_MOUNT_AUTO_NESTING, LXC_ARG_DENYLIST,
+                            PVE_ARG_DENYLIST, QEMU_ARG_DENYLIST)
 from kento.errors import (InstanceExistsError, ModeError, StateError,
                           SubprocessError, ValidationError)
 from kento.hook import write_hook
 from kento.inject import write_inject
-from kento.layers import resolve_layers
+from kento.layers import resolve_image_id, resolve_layers
 from kento.locking import kento_lock
 
 logger = logging.getLogger("kento")
@@ -384,8 +384,14 @@ def generate_config(name: str, lxc_dir: Path, *, bridge: str | None = None,
                 "    enforce the host/container boundary; in-kernel MAC confinement off)."
             )
         lines.append(f"lxc.apparmor.profile = {profile}")
-        lines.append("lxc.apparmor.allow_nesting = 1")
         lines.append("lxc.apparmor.allow_incomplete = 1")
+        # Narrow AppArmor grant for modern systemd (replaces the old broad
+        # allow_nesting=1). Only valid with a generated profile, and only needed
+        # when nesting is off -- with --allow-nesting, nesting.conf already sets
+        # allow_nesting=1. The unconfined escape hatch needs nothing (permits all).
+        if profile == "generated" and not nesting:
+            for rule in APPARMOR_SYSTEMD_RULES:
+                lines.append(f"lxc.apparmor.raw = {rule}")
         # Unprivileged plain-LXC: map container UID/GID 0 onto an unprivileged
         # host range (100000:65536). The actual rootfs idmap is done per-layer
         # by kento's hook (kento-hook): for each lowerdir, the hook creates an
@@ -706,6 +712,15 @@ def create(image: str, *, name: str | None = None, bridge: str | None = None,
     # is needed here.
     layers = resolve_layers(image)
 
+    # Fail closed on an over-deep overlay BEFORE any filesystem side effect.
+    # The kernel caps classic mount(2) options at one 4096-byte page; an image
+    # with more than MAX_OVERLAY_LAYERS layers would overrun it and be silently
+    # truncated, failing the overlay mount with cryptic errors. The layer-count
+    # cap is checked here (zero side effects); the exact-byte backstop runs once
+    # state_dir is known (below). See layers.preflight_overlay_layers.
+    from kento.layers import preflight_overlay_layers
+    preflight_overlay_layers(layers)
+
     # detect_cloudinit() does filesystem I/O over every layer. ``layers`` is
     # resolved once and never reassigned, so probe once and reuse the boolean
     # at all three decision sites below (cloudinit-mode precondition, the
@@ -837,8 +852,21 @@ def create(image: str, *, name: str | None = None, bridge: str | None = None,
         (state_dir / "upper").mkdir(exist_ok=True)
         (state_dir / "work").mkdir(exist_ok=True)
 
+        # Byte backstop: now that state_dir (hence upper/work paths) is known,
+        # assert the exact overlay options string can't truncate. Runs before
+        # any hook/config/PVE state is generated; a violation rolls back via
+        # the undos registered above. See preflight_overlay_layers.
+        preflight_overlay_layers(layers, state_dir)
+
         # Write image reference, layer paths, state dir, mode, and name
         (container_dir / "kento-image").write_text(image + "\n")
+        # Record the resolved content-ID alongside the (floating) tag so a
+        # later scrub/diagnose can detect when the tag has moved to a new
+        # image. Skip if it can't be resolved (older podman) — drift detection
+        # simply degrades to a no-op for that guest.
+        _img_id = resolve_image_id(image)
+        if _img_id:
+            (container_dir / "kento-image-id").write_text(_img_id + "\n")
         (container_dir / "kento-layers").write_text(layers + "\n")
         (container_dir / "kento-state").write_text(str(state_dir) + "\n")
         (container_dir / "kento-mode").write_text(mode + "\n")

{kento_core-1.6.0.dev1 → kento_core-1.6.0.dev3}/src/kento/defaults.py

@@ -2,14 +2,68 @@
 
 from pathlib import Path
 
+# --- Overlay layer cap ---
+# Docker overlay2 parity. The kernel caps classic mount(2) options at one
+# 4096-byte page; an over-deep lowerdir overruns it and the kernel SILENTLY
+# TRUNCATES, corrupting upperdir/workdir and failing the overlay mount. kento
+# mounts from short l/<short> symlinks + chdir (like Docker/podman) to stay
+# small, and fails closed at create above this many layers rather than letting
+# the kernel truncate. Lift once the new mount API (fsconfig, what
+# LIBMOUNT_FORCE_MOUNT2 targets) is reliably available — it has no single-page
+# limit (currently a silent no-op on some util-linux/kernel combos).
+MAX_OVERLAY_LAYERS = 128
+
+# The single-page mount(2) options limit. We compute the exact options string
+# kento will emit and refuse to hand the kernel anything that could truncate,
+# leaving a 16-byte safety margin. With the l/<short> short-link form the 128
+# cap keeps us far under this; the byte check is a backstop for pathological
+# state-dir / name lengths.
+OVERLAY_OPTS_PAGE_LIMIT = 4096
+
+# Maximum instance-name length. The name flows into STATE_DIR (e.g.
+# /var/lib/kento/vm/<name>), which is the upperdir/workdir of the overlay
+# mount-options string -- the last otherwise-uncapped contributor to that
+# budget (the layer count + byte backstop above cap the rest). It also becomes
+# the guest hostname, so HOST_NAME_MAX (64) is the natural ceiling.
+MAX_INSTANCE_NAME = 64  # HOST_NAME_MAX; the name becomes the guest hostname, and
+                        # bounds the overlay mount-options budget (see layers.py)
+
 # --- LXC defaults ---
 LXC_TTY = 2
 LXC_MOUNT_AUTO = "proc:mixed sys:mixed cgroup:mixed"
 LXC_MOUNT_AUTO_NESTING = "proc:rw sys:rw cgroup:rw"
 LXC_NESTING = False
 
+# AppArmor rules that let modern systemd (256+) boot inside an LXC guest. systemd
+# sandboxes its own core units (networkd, resolved, logind, journald, ...) with
+# PrivateUsers=/PrivateMounts=, which create a user namespace and do bind/move/
+# remount/pivot_root mounts. AppArmor 4.x (Debian 13 / kernel 6.x) mediates
+# userns_create and these mounts; the LXC-generated profile denies them by default,
+# so the guest comes up network-dead. These rules grant exactly that bounded
+# sandboxing vocabulary -- narrower than allow_nesting (no nested-container peer
+# rules, no raw proc/sys). Injected via lxc.apparmor.raw, which is only honored with
+# a generated profile. Validated clean on droste-loom + kanibako-lxc (Debian 13,
+# systemd 257) on a real PVE host.
+APPARMOR_SYSTEMD_RULES = ("userns,", "mount,", "umount,", "pivot_root,", "mqueue,")
+
+# --- PVE-LXC defaults ---
+# PVE has no "unlimited" memory sentinel: it rejects `memory: 0` and
+# `memory: max` at schema validation, and it silently backfills its 512 MiB
+# schema default whenever the `memory:` field is omitted -- then enforces that
+# 512 MiB host-side on the container cgroup (confirmed live on PVE 9.1.6: an
+# empty conf yields memory.max = 536870912). So an omitted field is NOT
+# unlimited on pve-lxc; it is a surprise 512 MiB cap (real-world OOM-kills).
+# This value is PVE's schema ceiling (2^44 - 1 MiB, "signed int max"); it is
+# accepted by pct, and the resulting byte value exceeds the cgroup's
+# representable maximum so the kernel clamps memory.max to the literal string
+# `max` -- i.e. truly unlimited. Chosen over detecting host RAM deliberately,
+# so the value survives PVE cluster live-migration / extreme hosts (a host-RAM
+# value baked in at create time could under-cap after the container migrates
+# to a smaller node).
+PVE_LXC_UNLIMITED_MEMORY_MB = 17592186044415
+
 # --- VM defaults ---
-VM_MEMORY = 512          # MB
+VM_MEMORY = 1024         # MB
 VM_CORES = 1
 VM_KVM = True
 VM_MACHINE = "q35"

{kento_core-1.6.0.dev1 → kento_core-1.6.0.dev3}/src/kento/diagnose.py

@@ -26,9 +26,10 @@ from kento import (LXC_BASE, VM_BASE, InstanceNotFoundError, _scan_namespace,
                    is_running, pve_config_exists, read_mode, validate_name)
 from kento.cloudinit import detect_cloudinit
 from kento.create import _apparmor_active, _apparmor_parser_present
-from kento.images import _guest_names, _holds
+from kento.images import _guest_names, _hold_image_ids, _holds
 from kento.info import _read_meta
 from kento.pve import _kento_recorded_vmids, is_pve, next_vmid
+from kento.reconcile import _is_orphan, _orphan_vmid
 
 logger = logging.getLogger("kento")
 
@@ -164,6 +165,72 @@ def _check_stale_holds():
     return findings
 
 
+def _short_id(image_id):
+    """First 12 hex chars of an image id, stripping any ``sha256:`` prefix."""
+    s = image_id.strip()
+    if s.startswith("sha256:"):
+        s = s[len("sha256:"):]
+    return s[:12]
+
+
+def _check_hold_drift():
+    """Image-hold / guest image-ID drift (host). READ ONLY.
+
+    For each guest that exists AND has a hold, compare the hold's pinned
+    content-ID (its ``io.kento.hold-image-id`` label) against the guest's
+    recorded ``kento-image-id`` file. A mismatch means the image tag moved
+    since the hold was created (e.g. a re-pull) and a scrub is needed to
+    re-pin. Legacy guests/holds missing either value are skipped silently
+    (no noise). Never mutates.
+    """
+    try:
+        guests = _guest_names()
+        hold_ids = _hold_image_ids()
+    except (PermissionError, OSError):
+        return [_finding("hold", "info", "host",
+                         "could not enumerate image-hold pins (podman/root?)",
+                         None)]
+
+    # Map guest display name -> its recorded kento-image-id (when present).
+    guest_image_ids: dict[str, str] = {}
+    for base in (LXC_BASE, VM_BASE):
+        if not base.is_dir():
+            continue
+        for image_file in base.glob("*/kento-image"):
+            container_dir = image_file.parent
+            try:
+                name_file = container_dir / "kento-name"
+                gname = (name_file.read_text().strip()
+                         if name_file.is_file() else container_dir.name)
+                id_file = container_dir / "kento-image-id"
+                if id_file.is_file():
+                    guest_image_ids[gname] = id_file.read_text().strip()
+            except (PermissionError, OSError):
+                continue
+
+    findings = []
+    drift = 0
+    for n in sorted(guests):
+        pinned = hold_ids.get(n, "")
+        guest_id = guest_image_ids.get(n, "")
+        if not pinned or not guest_id:
+            # Legacy / pre-fix guest or hold (missing label or file) — skip.
+            continue
+        if pinned != guest_id:
+            drift += 1
+            findings.append(_finding(
+                "hold", "warn", "host",
+                f"image hold for '{n}' pins {_short_id(pinned)} but guest "
+                f"runs {_short_id(guest_id)} — run 'kento scrub {n}' to "
+                f"re-pin",
+                f"kento scrub {n}"))
+    if drift == 0:
+        findings.append(_finding(
+            "hold", "ok", "host",
+            "image holds are pinned to their guests' current images", None))
+    return findings
+
+
 def _check_vmid_health():
     """VMID allocation health (host, pve only).
 
@@ -204,7 +271,8 @@ def _check_vmid_health():
             f"{len(reserved_orphans)} recorded vmid(s) are reserved by "
             f"orphaned kento state and will not be reassigned: "
             f"{', '.join(str(v) for v in reserved_orphans)}",
-            "kento destroy -f <name> for the orphan(s), then re-check")]
+            "kento adopt <name> to heal, or kento destroy -f <name> to "
+            "discard, the orphan(s), then re-check")]
     return [_finding("vmid", "info", "host",
                      f"next free vmid is {nxt}; "
                      f"{len(recorded)} vmid(s) recorded by kento", None)]
@@ -216,18 +284,17 @@ def _check_vmid_health():
 def _check_orphan(container_dir, mode, display):
     """Orphan check (pve modes): state present but PVE .conf gone.
 
-    Same logic list.list_containers uses: pve-lxc uses the dir name as the
-    vmid; pve-vm reads kento-vmid.
+    Detection is shared with list.list_containers via reconcile._is_orphan
+    (pve-lxc uses the dir name as the vmid; pve-vm reads kento-vmid). The
+    diagnose-bound pve_config_exists is passed in so the predicate probes
+    through the same name diagnose's tests patch.
     """
     if mode not in ("pve", "pve-vm"):
         return []
-    if mode == "pve":
-        check_vmid = container_dir.name
-    else:
-        check_vmid = _read_meta(container_dir, "kento-vmid")
-    try:
-        gone = check_vmid is None or not pve_config_exists(check_vmid, mode)
-    except (PermissionError, OSError):
+    check_vmid = _orphan_vmid(container_dir, mode)
+    gone = _is_orphan(container_dir, mode, pve_config_exists)
+    if gone is None:
+        # Indeterminate config probe (PermissionError/OSError).
         return [_finding("orphan", "info", display,
                          "could not check PVE config (needs root?)", None)]
     if gone:
@@ -235,7 +302,8 @@ def _check_orphan(container_dir, mode, display):
             "orphan", "warn", display,
             f"instance '{display}' has kento state but its PVE config "
             f"(vmid {check_vmid or '?'}) is gone — orphaned",
-            f"kento destroy -f {display}")]
+            f"kento adopt {display} to heal it, or "
+            f"kento destroy -f {display} to discard it")]
     return [_finding("orphan", "ok", display,
                      f"PVE config present (vmid {check_vmid})", None)]
 
@@ -456,6 +524,7 @@ def run_diagnostics(name=None):
     # Host-level checks run regardless of name.
     checks.extend(_check_apparmor())
     checks.extend(_check_stale_holds())
+    checks.extend(_check_hold_drift())
     checks.extend(_check_vmid_health())
 
     for container_dir, mode, display in instances:

{kento_core-1.6.0.dev1 → kento_core-1.6.0.dev3}/src/kento/hook.py

@@ -10,13 +10,26 @@ def generate_hook(container_dir: Path, layers: str, name: str,
     """Return a hook script with baked-in paths for a container.
 
     state_dir is where upper/work live. Defaults to container_dir if not given.
+
+    LAYERS is baked in chdir-relative ``l/<short>`` form (Docker/podman
+    parity) so a deeply layered image's overlay mount(2) options stay under
+    the kernel's 4096-byte page limit. OVERLAY_BASE is the podman overlay
+    store root; the pre-start mount cd's into it inside a subshell so the
+    chdir never leaks to inject.sh / later steps. If the short form can't be
+    derived, to_overlay_lowerdir falls back to absolute layers and
+    OVERLAY_BASE is "/" (a harmless no-op cd).
     """
+    from kento.layers import to_overlay_lowerdir
     sd = state_dir or container_dir
+    overlay_base, rel_layers = to_overlay_lowerdir(str(layers))
+    if not overlay_base:
+        overlay_base = "/"
     return (_TEMPLATE
             .replace("@@NAME@@", str(name))
             .replace("@@CONTAINER_DIR@@", str(container_dir))
             .replace("@@STATE_DIR@@", str(sd))
-            .replace("@@LAYERS@@", str(layers)))
+            .replace("@@OVERLAY_BASE@@", overlay_base)
+            .replace("@@LAYERS@@", rel_layers))
 
 
 def write_hook(container_dir: Path, layers: str, name: str,

{kento_core-1.6.0.dev1 → kento_core-1.6.0.dev3}/src/kento/hook.sh

@@ -4,6 +4,7 @@ set -eu
 NAME="@@NAME@@"
 CONTAINER_DIR="@@CONTAINER_DIR@@"
 STATE_DIR="@@STATE_DIR@@"
+OVERLAY_BASE="@@OVERLAY_BASE@@"
 LAYERS="@@LAYERS@@"
 HOOK_TYPE="${LXC_HOOK_TYPE:-$3}"
 
@@ -221,17 +222,6 @@ WORKER_EOF
 
 case "$HOOK_TYPE" in
     pre-start|pre-mount|mount)
-        # Validate layer paths still exist (image may have changed)
-        IFS=:
-        for dir in $LAYERS; do
-            if [ ! -d "$dir" ]; then
-                echo "kento-hook: error: layer path missing: $dir" >&2
-                echo "kento-hook: image may have changed. Run: kento scrub $NAME" >&2
-                exit 1
-            fi
-        done
-        unset IFS
-
         # pre-mount (PVE privileged): mount at lxc.rootfs.path source so LXC picks it up
         # pre-start (PVE unprivileged): the only hook in the host INITIAL ns as
         #   real root — pre-mount/mount run in the child userns where idmapped
@@ -243,6 +233,28 @@ case "$HOOK_TYPE" in
         mkdir -p "$STATE_DIR/upper" "$STATE_DIR/work" "$ROOTFS"
         export LIBMOUNT_FORCE_MOUNT2=always
 
+        # Validate layers + mount inside a SUBSHELL that cd's into the podman
+        # overlay store root. LAYERS is in chdir-relative l/<short> form
+        # (Docker/podman parity) so the mount(2) options stay under the
+        # kernel's 4096-byte page limit. The subshell scopes the chdir so it
+        # never leaks to inject.sh / later hook phases (which use absolute
+        # paths). Both the privileged and unprivileged paths resolve the
+        # relative $LAYERS against this cwd; idmap targets / upper / work stay
+        # absolute and so are unaffected by the cwd.
+        (
+        cd "$OVERLAY_BASE" || { echo "kento-hook: error: overlay base missing: $OVERLAY_BASE" >&2; exit 1; }
+
+        # Validate layer paths still exist (image may have changed)
+        IFS=:
+        for dir in $LAYERS; do
+            if [ ! -d "$dir" ]; then
+                echo "kento-hook: error: layer path missing: $dir" >&2
+                echo "kento-hook: image may have changed. Run: kento scrub $NAME" >&2
+                exit 1
+            fi
+        done
+        unset IFS
+
         if [ -f "$CONTAINER_DIR/kento-unprivileged" ]; then
             # ---------------------------------------------------------------------------
             # Unprivileged (per-layer idmap) path — mainline kernel 5.19+, util-linux 2.40+
@@ -354,13 +366,17 @@ case "$HOOK_TYPE" in
                     "$ROOTFS"
             fi
         else
-            # Privileged path — unchanged.
+            # Privileged path. lowerdir is the relative l/<short> form,
+            # resolved against the cwd ($OVERLAY_BASE) set above.
             mount -t overlay overlay \
                 -o "lowerdir=$LAYERS,upperdir=$STATE_DIR/upper,workdir=$STATE_DIR/work" \
                 "$ROOTFS"
         fi
+        ) || { echo "kento-hook: error: overlay mount failed" >&2; exit 1; }
 
-        # Guest config injection — shared with VM / PVE-VM modes.
+        # Guest config injection — shared with VM / PVE-VM modes. Runs with the
+        # ORIGINAL cwd (the mount subshell's chdir did not leak); $ROOTFS and
+        # $CONTAINER_DIR are absolute.
         sh "$CONTAINER_DIR/kento-inject.sh" "$ROOTFS" "$CONTAINER_DIR"
         ;;
     start-host)

{kento_core-1.6.0.dev1 → kento_core-1.6.0.dev3}/src/kento/images.py

@@ -97,6 +97,36 @@ def _holds() -> list[tuple[str, str]]:
     return holds
 
 
+def _hold_image_ids() -> dict[str, str]:
+    """Map each held-for guest name -> the hold's pinned content-ID label.
+
+    Separate query from ``_holds()`` (whose (name, image) shape prune/list
+    depend on) so those callers are untouched. Only entries carrying a
+    non-empty ``io.kento.hold-image-id`` label are returned; legacy holds
+    created before the label existed are simply absent from the map.
+    """
+    result = subprocess.run(
+        [*_podman_cmd(), "ps", "-a",
+         "--filter", "label=io.kento.hold-for",
+         "--format",
+         '{{.Label "io.kento.hold-for"}}\t{{.Label "io.kento.hold-image-id"}}'],
+        capture_output=True, text=True,
+    )
+    ids: dict[str, str] = {}
+    if result.returncode != 0:
+        return ids
+    for line in result.stdout.splitlines():
+        line = line.rstrip("\n")
+        if not line.strip():
+            continue
+        parts = line.split("\t")
+        held_for = parts[0].strip()
+        image_id = parts[1].strip() if len(parts) > 1 else ""
+        if held_for and image_id and image_id != "<no value>":
+            ids[held_for] = image_id
+    return ids
+
+
 def list_images(in_use_only: bool = False) -> str:
     """List kento-managed images (read-only).
 
@@ -142,7 +172,7 @@ def list_images(in_use_only: bool = False) -> str:
     return "\n".join(lines)
 
 
-def prune(yes: bool = False) -> str:
+def prune(yes: bool = False) -> tuple[str, int]:
     """Safe GC of orphaned kento hold containers and the images they freed.
 
     DRY-RUN by default. Removes only holds whose guest no longer exists,
@@ -150,7 +180,13 @@ def prune(yes: bool = False) -> str:
     no surviving guest. Never removes a hold whose guest exists; never
     prunes all images.
 
-    Returns the user-facing plan/summary text as a string (no trailing newline).
+    Returns ``(summary_text, failed_count)`` where ``summary_text`` is the
+    user-facing plan/summary (no trailing newline) and ``failed_count`` is
+    the number of candidate images podman refused to remove. Because every
+    candidate is, by construction, an image with no surviving guest ref and
+    no surviving-hold ref, a removal failure is meaningful (an external
+    non-kento reference or a kento-accounting miss) — the CLI exits
+    non-zero on a non-zero count, mirroring ``diagnose``.
     """
     guest_names = _guest_names()
     refs = _guest_image_refs()  # image -> guests still present
@@ -162,7 +198,7 @@ def prune(yes: bool = False) -> str:
                  if name in guest_names]
 
     if not orphaned:
-        return "Nothing to prune."
+        return "Nothing to prune.", 0
 
     # Images still pinned by a surviving (non-orphaned) hold must not be
     # removed. Likewise, images referenced by any guest must not be removed.
@@ -186,7 +222,7 @@ def prune(yes: bool = False) -> str:
         else:
             lines.append("  Images then eligible for removal: (none)")
         lines.append("Run 'kento prune --yes' to remove them.")
-        return "\n".join(lines)
+        return "\n".join(lines), 0
 
     removed_holds = 0
     for name, _image in orphaned:
@@ -194,6 +230,7 @@ def prune(yes: bool = False) -> str:
         removed_holds += 1
 
     removed_images = 0
+    failures: list[tuple[str, str]] = []
     for image in candidate_images:
         result = subprocess.run(
             [*_podman_cmd(), "image", "rm", image],
@@ -202,9 +239,19 @@ def prune(yes: bool = False) -> str:
         if result.returncode == 0:
             removed_images += 1
         else:
-            # podman refuses if the image is still in use — that is the
-            # intended safety net, so we tolerate the failure and report.
+            # Every candidate had no surviving guest ref and no surviving
+            # hold ref, so a refusal here is meaningful — an external
+            # non-kento reference or a kento-accounting miss. Surface it.
             msg = (result.stderr or result.stdout or "").strip()
             logger.warning("skipped image %s: %s", image, msg)
+            failures.append((image, msg))
 
-    return f"Removed {removed_holds} orphaned hold(s), {removed_images} image(s)."
+    lines = [f"Removed {removed_holds} orphaned hold(s), {removed_images} image(s)."]
+    if failures:
+        lines.append(
+            f"Failed to remove {len(failures)} image(s) "
+            "(still referenced or accounting mismatch):"
+        )
+        for image, reason in failures:
+            lines.append(f"  {image}: {reason}")
+    return "\n".join(lines), len(failures)