Merge pull request #23 from A3S-Lab/feat/pidfd-signaling

feat(executor): signal container init through pidfds

Author: ZhiXiao-Lin

.github/scripts/native-linux-smoke.sh

@@ -10,6 +10,19 @@ sudo apt-get update
 sudo apt-get install --yes busybox-static jq
 cargo build -p a3s-oci-agent -p a3s-oci-cli
 
+features="$("$PWD/target/debug/a3s-oci" features)"
+printf '%s\n' "$features"
+jq --exit-status \
+  '.platform == "linux"
+   and any(
+     .drivers[];
+     .driver == "native-linux"
+     and .status == "available"
+     and .readiness == "probe-only"
+     and .evidence.pidfd_signaling == "true"
+   )' \
+  <<<"$features" >/dev/null
+
 bundle="$runner_temp/a3s-native-bundle"
 bundle_b="$runner_temp/a3s-native-bundle-b"
 work_parent="$runner_temp/a3s-native-work"

README.md

@@ -36,8 +36,9 @@ profile.
 
 The runtime has two execution paths:
 
-- **Native Linux** uses namespaces, mounts, cgroup v2, seccomp, capabilities,
-  and process supervision without requiring KVM.
+- **Native Linux** runs the reviewed namespace and mount profile with
+  PID-reuse-safe process control without requiring KVM. Complete cgroup,
+  seccomp, capability, and supervision enforcement remains a release gate.
 - **Utility VM** hosts the same Linux executor behind an authenticated guest
   agent, using KVM on Linux, HVF on macOS, or WHPX on Windows.
 
@@ -83,9 +84,9 @@ Workload calls require an explicitly supplied launch-ready `RuntimeDriver`.
   monotonic generations, operation IDs, replay, fencing, reconciliation, and
   quarantine, backed by exhaustive durable-write and driver-boundary fault
   matrices
-- **Shared Linux Executor**: Reuse one fail-closed namespace, mount, process,
-  and cleanup implementation directly on Linux and through the guest agent,
-  with independently fenced per-container generations
+- **Shared Linux Executor**: Reuse one fail-closed namespace, mount, pidfd
+  process-control, and cleanup implementation directly on Linux and through
+  the guest agent, with independently fenced per-container generations
 - **Cross-Platform Drivers**: Inspect native Linux, KVM, HVF, and WHPX
   prerequisites without silently weakening requested isolation
 - **Typed SDK and IPC**: Expose an async `Send + Sync` Rust contract with
@@ -422,8 +423,8 @@ The current executor implements a reviewed bootstrap vertical slice:
 - recursively private mount propagation and `pivot_root`;
 - ordered existing-target OCI mounts with bind/rbind and common VFS options;
 - PID-authenticated create/start barrier;
-- credentials, umask, `no_new_privileges`, `execve`, signaling, observation,
-  and scoped cleanup.
+- credentials, umask, `no_new_privileges`, `execve`, PID-reuse-safe pidfd
+  signaling, observation, and scoped cleanup.
 
 Unimplemented OCI fields are rejected instead of ignored. User and time
 namespaces, namespace joins, complete mount semantics, cgroup resources,
@@ -452,9 +453,9 @@ boundary.
 
 | Host | Execution path | Retained evidence | Current readiness |
 | --- | --- | --- | --- |
-| Linux x86_64/aarch64 | Native Linux executor | Real rootful core lifecycle, two-container generation and mutation isolation, plus shutdown cleanup after create, start, and kill without delete; `/dev/kvm` absent and present-but-unusable | Default inventory `probe-only`; explicitly opened development instance `experimental` |
+| Linux x86_64/aarch64 | Native Linux executor | Kernel pidfd signaling probe, real rootful core lifecycle, two-container generation and mutation isolation, plus shutdown cleanup after create, start, and kill without delete; `/dev/kvm` absent and present-but-unusable | Default inventory `probe-only`; explicitly opened development instance `experimental` |
 | Linux x86_64/aarch64 | libkrun + KVM utility VM | Device access, ioctl result, and KVM API version | `probe-only`; VM driver not implemented |
-| macOS arm64 | libkrun + HVF utility VM | Direct HVF VM create/destroy, checksum-pinned context lifecycle, authenticated static arm64 guest agent, fixed and two-container OCI lifecycles, and no-delete cleanup after create, start, and kill | `probe-only`; complete enforcement and recovery pending |
+| macOS arm64 | libkrun + HVF utility VM | Direct HVF VM create/destroy, checksum-pinned context lifecycle, authenticated static arm64 guest agent, pidfd-backed fixed and two-container OCI lifecycles, and no-delete cleanup after create, start, and kill | `probe-only`; complete enforcement and recovery pending |
 | Windows x86_64 | libkrun + WHPX utility VM | Partition, context, guest command, authenticated agent, and fixed OCI core lifecycle | `probe-only`; complete enforcement and recovery pending |
 
 Linux installation, feature inspection, and the native SDK path must work when
@@ -475,7 +476,7 @@ flowchart TB
     native["Native Linux<br/>NativeLinuxDriver · experimental opt-in"]
     utility["Utility VM host · qualification path<br/>isolated a3s-oci-krun-shim → libkrun<br/>KVM · HVF · WHPX"]
     agent["A3S Linux guest<br/>authenticated AF_VSOCK → a3s-oci-agent"]
-    executor["Shared LinuxExecutor<br/>namespaces · mounts · PID 1 · process lifecycle"]
+    executor["Shared LinuxExecutor<br/>namespaces · mounts · PID 1 · pidfd process control"]
 
     consumers --> control --> selection
     control <--> state
@@ -538,6 +539,9 @@ Security-sensitive platform controls include:
   natural zero exit, worker reap, and marker cleanup;
 - private `0700` macOS agent directories and `0600` Unix sockets, with
   `LOCAL_PEERPID` plus direct shim-child verification before token negotiation;
+- retained pidfds for every authenticated init PID, with all lifecycle and
+  cleanup signals delivered through the descriptor rather than a reused
+  numeric PID;
 - isolated macOS shim process groups so timeout and failure cleanup terminate
   both the public shim and its VM worker;
 - shared Windows/macOS fixed-lifecycle evidence with exact mutation replay,
@@ -578,11 +582,13 @@ Platform CI covers:
 
 - the 237-point durable commit matrix and all 12 `RuntimeDriver` call
   boundaries on Linux, macOS, and Windows;
-- Ubuntu x86_64 native lifecycle and three-phase no-delete cleanup without KVM;
-- Ubuntu aarch64 native lifecycle and three-phase no-delete cleanup without KVM;
+- Ubuntu x86_64 native pidfd probe, lifecycle, multi-container isolation, and
+  three-phase no-delete cleanup without KVM;
+- Ubuntu aarch64 native pidfd probe, lifecycle, multi-container isolation, and
+  three-phase no-delete cleanup without KVM;
 - macOS HVF, isolated libkrun context, guest-marker, authenticated-agent,
-  fixed OCI lifecycle, three-phase no-delete cleanup, and missing-entitlement
-  fail-closed gates;
+  pidfd-backed fixed and multi-container OCI lifecycles, three-phase no-delete
+  cleanup, and missing-entitlement fail-closed gates;
 - Windows WHPX and libkrun context gates;
 - static x86_64 and aarch64 musl guest-agent output.
 

ROADMAP.md

@@ -38,8 +38,8 @@ Completed:
 - pure OCI lifecycle transition contract;
 - versioned driver status, readiness, isolation, and evidence;
 - secure WHPX DLL loading and hypervisor capability probe;
-- native Linux namespace and cgroup v2 prerequisite reporting that does not
-  touch `/dev/kvm`;
+- native Linux namespace, cgroup v2, and pidfd signaling prerequisite
+  reporting that does not touch `/dev/kvm`;
 - Linux KVM device, access, ioctl, and API-version reporting without libkrun
   initialization;
 - Apple Silicon and Hypervisor.framework capability reporting through a
@@ -86,7 +86,7 @@ Completed:
   and domainname, recursively private mount propagation, ordered
   existing-target OCI mounts, `pivot_root`, authenticated host-visible PID
   reporting, exact-generation state, bounded typed init rejection reporting,
-  session idempotency, signaling, and cleanup;
+  session idempotency, retained pidfd signaling, and cleanup;
 - real WHPX fixed-bundle create/state/start/kill/delete evidence, including
   exact mutation retries, pre-start non-execution, running and stopped
   observation, marker verification, post-delete NotFound, and nominal leak
@@ -289,6 +289,10 @@ then may HVF become `experimental`.
   and authenticate its host-visible PID before the created barrier.
 - [x] Prove executor shutdown cleanup without delete after successful create,
   start, and kill through native Linux and the macOS utility-VM path.
+- [x] Open and retain a pidfd for every authenticated init process, reject
+  kernels without `pidfd_open` and `pidfd_send_signal`, and deliver lifecycle
+  and cleanup signals without a numeric-PID reuse race. Prove the path through
+  native Linux and the macOS utility VM.
 - [ ] Namespace creation for user and time namespaces, plus joining existing
   namespaces.
 - [ ] Mount-target creation, rootfs propagation overrides, idmapped and
@@ -298,7 +302,7 @@ then may HVF become `experimental`.
   priority, affinity, `no_new_privileges`, LSMs, and seccomp.
 - [ ] cgroup v2 CPU, memory, pids, I/O, hugepage, RDMA, device, and unified
   resource enforcement.
-- [ ] Init supervision, zombie reaping, pidfd signaling, exec, and wait.
+- [ ] Init supervision, zombie reaping, exec, and wait.
 - [ ] Ordered hooks with OCI state on stdin.
 - [ ] Backpressured stdin/stdout/stderr, PTY, resize, signals, and output
   cursors.
@@ -309,8 +313,8 @@ and recovery suites in the Windows guest and on native Linux.
 
 ### R4 — Native Linux Without KVM
 
-- [x] Report native namespace and cgroup v2 prerequisites without opening
-  `/dev/kvm` or initializing libkrun.
+- [x] Report native namespace, cgroup v2, and pidfd signaling prerequisites
+  without opening `/dev/kvm` or initializing libkrun.
 - [x] Report optional KVM absence, permission failure, ioctl failure, and API
   version independently from native readiness.
 - [x] Add the native Linux driver without linking or initializing libkrun.

crates/agent/src/executor/mod.rs

@@ -4,6 +4,7 @@ mod mount;
 #[cfg(test)]
 mod mount_tests;
 mod pid;
+mod pidfd;
 mod plan;
 #[cfg(test)]
 mod plan_tests;
@@ -24,13 +25,15 @@ use tokio::io::AsyncWriteExt;
 use tokio::sync::Mutex;
 
 use crate::AGENT_VERSION;
+use pidfd::SignalOutcome;
 use plan::InitPlan;
 use process::PreparedProcess;
 use state::{
     ContainerKey, ContainerRecord, ExecutorState, MutationKind, RecordedOutcome, RecordedRequest,
 };
 
 pub(crate) use init::run_container_init_if_requested;
+pub(crate) use pidfd::verify_support as verify_pidfd_support;
 
 const DEFAULT_RUNTIME_PARENT: &str = "/run";
 const MAX_OPERATION_RECORDS: usize = 4_096;
@@ -70,6 +73,7 @@ impl LinuxExecutor {
                 "the Linux executor must run as root",
             ));
         }
+        pidfd::verify_support()?;
         let parent = runtime_parent.as_ref();
         if !parent.is_absolute() {
             return Err(executor_error(
@@ -340,8 +344,10 @@ impl LinuxExecutor {
                 "cannot signal a stopped container",
             ));
         }
-        record.process.signal(request.signal.get())?;
-        record.refresh()?;
+        match record.process.signal(request.signal.get())? {
+            SignalOutcome::Delivered => record.refresh()?,
+            SignalOutcome::Exited => record.status = ContainerState::Stopped,
+        }
         record.state()
     }
 
@@ -363,16 +369,17 @@ impl LinuxExecutor {
                 )
             })?;
             record.refresh()?;
-            if record.status != ContainerState::Stopped {
-                if request.mode == DeleteMode::StoppedOnly {
-                    return Err(executor_error(
-                        ErrorCode::FailedPrecondition,
-                        "stopped-only delete requires a stopped container",
-                    ));
-                }
-                record.process.force_stop().await?;
-                record.status = ContainerState::Stopped;
+            if record.status != ContainerState::Stopped && request.mode == DeleteMode::StoppedOnly {
+                return Err(executor_error(
+                    ErrorCode::FailedPrecondition,
+                    "stopped-only delete requires a stopped container",
+                ));
             }
+            // Even an already-stopped init may have an authenticated wrapper
+            // that has not completed its final wait yet. Always reap that
+            // wrapper before releasing the runtime directory.
+            record.process.force_stop().await?;
+            record.status = ContainerState::Stopped;
             record.runtime_directory.clone()
         };
         remove_container_directory(&self.runtime_root, &runtime_directory).await?;