feat: surface the terminating reason (timeout/signal/kill) through the C ABI and SDKs (#131)

sandlock_result_exit_code flattens Signal/Killed/Timeout to -1, so a caller can't
tell a timeout from a signal from a normal exit. Add a systemd-style reason
taxonomy — deliberately WITHOUT an oom-kill reason: Linux bottoms both a timeout
and an OOM kill out in SIGKILL, and telling OOM apart needs cgroup v2
memory.events introspection, so KILLED (SIGKILL, no recoverable number) and
TIMEOUT (sandlock-enforced) are the honest split we can report.

- C ABI: `sandlock_exit_reason` enum { EXITED, SIGNALED, KILLED, TIMEOUT }
  (#[repr(u32)]) + `sandlock_result_reason`/`_signal` and the dry-run pair.
- Python: `ExitReason` IntEnum + `Result.reason`/`.signal` (and DryRunResult),
  wired into every native-result path (run/wait/spawn/reduce/Process.wait/
  Pipeline/GatherPipeline/dry_run); the fragile `exit_code == -1` timeout
  heuristic is replaced by `reason == TIMEOUT`. reason defaults to None on the
  error paths that never produced a native result.
- Go: `ExitReason` + `Result.Reason`/`.Signal` via readResult and DryRun.
- Tests: Python + Go cover exited/timeout/signaled(SIGTERM)/killed(SIGKILL);
  a Rust FFI unit test pins all four ExitStatus variants incl. KILLED and the
  null-result contract.

Author: dzerik

crates/sandlock-ffi/cbindgen.toml

@@ -73,6 +73,7 @@ exclude = [
 # than the verbose SANDLOCK_EXCEPTION_POLICY_T_* / SANDLOCK_ACTION_KIND_T_*.
 "sandlock_exception_policy_t" = "sandlock_exception"
 "sandlock_action_kind_t" = "sandlock_action"
+"sandlock_exit_reason_t" = "sandlock_exit_reason"
 
 [enum]
 rename_variants = "ScreamingSnakeCase"

crates/sandlock-ffi/include/sandlock.h

@@ -34,6 +34,39 @@ typedef struct sandlock_handler_t sandlock_handler_t;
  */
 #define SANDLOCK_INJECT_NO_CLOEXEC (1 << 1)
 
+/**
+ * Why a sandboxed process terminated. `EXITED` carries an exit code
+ * (`sandlock_result_exit_code`); `SIGNALED` carries the signal number
+ * (`sandlock_result_signal`). Linux bottoms both a timeout and an OOM kill out
+ * in `SIGKILL`, so there is no distinct OOM reason: a timeout sandlock enforced
+ * is `TIMEOUT`, any other kill is `KILLED`.
+ */
+enum sandlock_exit_reason
+#ifdef __cplusplus
+  : uint32_t
+#endif // __cplusplus
+ {
+  /**
+   * Exited normally with a code (`sandlock_result_exit_code`).
+   */
+  SANDLOCK_EXIT_REASON_EXITED = 0,
+  /**
+   * Terminated by a signal (`sandlock_result_signal`).
+   */
+  SANDLOCK_EXIT_REASON_SIGNALED = 1,
+  /**
+   * Killed with no recoverable signal number.
+   */
+  SANDLOCK_EXIT_REASON_KILLED = 2,
+  /**
+   * Killed by sandlock because it exceeded its timeout.
+   */
+  SANDLOCK_EXIT_REASON_TIMEOUT = 3,
+};
+#ifndef __cplusplus
+typedef uint32_t sandlock_exit_reason;
+#endif // __cplusplus
+
 /**
  * Tag distinguishing payload variants of `sandlock_action_out_t`.
  */
@@ -807,6 +840,25 @@ int sandlock_run_interactive(const sandlock_sandbox_t *policy,
  */
 int sandlock_result_exit_code(const sandlock_result_t *r);
 
+/**
+ * Terminating reason (normal exit / signal / kill / timeout). Pair with
+ * `sandlock_result_exit_code` (for `EXITED`) and `sandlock_result_signal`
+ * (for `SIGNALED`). Returns `KILLED` for a null result.
+ *
+ * # Safety
+ * `r` must be null or a valid result pointer.
+ */
+sandlock_exit_reason sandlock_result_reason(const sandlock_result_t *r);
+
+/**
+ * Signal number for a `SIGNALED` result, or `-1` for any other reason
+ * (including a null result).
+ *
+ * # Safety
+ * `r` must be null or a valid result pointer.
+ */
+int sandlock_result_signal(const sandlock_result_t *r);
+
 /**
  * # Safety
  * `r` must be null or a valid result pointer.
@@ -882,6 +934,24 @@ sandlock_dry_run_result_t *sandlock_dry_run(const sandlock_sandbox_t *policy,
  */
 int sandlock_dry_run_result_exit_code(const sandlock_dry_run_result_t *r);
 
+/**
+ * Terminating reason of a dry-run result (parity with
+ * `sandlock_result_reason`). Returns `KILLED` for a null result.
+ *
+ * # Safety
+ * `r` must be null or a valid dry-run result pointer.
+ */
+sandlock_exit_reason sandlock_dry_run_result_reason(const sandlock_dry_run_result_t *r);
+
+/**
+ * Signal number for a `SIGNALED` dry-run result, or `-1` otherwise (parity
+ * with `sandlock_result_signal`).
+ *
+ * # Safety
+ * `r` must be null or a valid dry-run result pointer.
+ */
+int sandlock_dry_run_result_signal(const sandlock_dry_run_result_t *r);
+
 /**
  * Check if the dry-run result indicates success.
  *

crates/sandlock-ffi/src/lib.rs

@@ -10,7 +10,7 @@ use std::time::Duration;
 
 use sandlock_core::pipeline::Stage;
 use sandlock_core::sandbox::{BranchAction, ByteSize, SandboxBuilder};
-use sandlock_core::{Protection, RunResult, Sandbox, StdioMode};
+use sandlock_core::{ExitStatus, Protection, RunResult, Sandbox, StdioMode};
 
 pub mod handler;
 pub mod notif_repr;
@@ -1425,6 +1425,43 @@ pub unsafe extern "C" fn sandlock_run_interactive(
 // Result accessors
 // ----------------------------------------------------------------
 
+/// Why a sandboxed process terminated. `EXITED` carries an exit code
+/// (`sandlock_result_exit_code`); `SIGNALED` carries the signal number
+/// (`sandlock_result_signal`). Linux bottoms both a timeout and an OOM kill out
+/// in `SIGKILL`, so there is no distinct OOM reason: a timeout sandlock enforced
+/// is `TIMEOUT`, any other kill is `KILLED`.
+// `#[repr(u32)]` (not `#[repr(C)]`) pins the discriminant to a `uint32_t`,
+// matching the sibling FFI enums and the Go (`uint32`) / Python (`c_uint`)
+// bindings; a bare C enum's width is implementation-defined (`-fshort-enums`).
+#[allow(non_camel_case_types)]
+#[repr(u32)]
+pub enum sandlock_exit_reason_t {
+    /// Exited normally with a code (`sandlock_result_exit_code`).
+    Exited = 0,
+    /// Terminated by a signal (`sandlock_result_signal`).
+    Signaled = 1,
+    /// Killed with no recoverable signal number.
+    Killed = 2,
+    /// Killed by sandlock because it exceeded its timeout.
+    Timeout = 3,
+}
+
+fn exit_reason(status: &ExitStatus) -> sandlock_exit_reason_t {
+    match status {
+        ExitStatus::Code(_) => sandlock_exit_reason_t::Exited,
+        ExitStatus::Signal(_) => sandlock_exit_reason_t::Signaled,
+        ExitStatus::Killed => sandlock_exit_reason_t::Killed,
+        ExitStatus::Timeout => sandlock_exit_reason_t::Timeout,
+    }
+}
+
+fn exit_signal(status: &ExitStatus) -> c_int {
+    match status {
+        ExitStatus::Signal(n) => *n,
+        _ => -1,
+    }
+}
+
 /// # Safety
 /// `r` must be null or a valid result pointer.
 #[no_mangle]
@@ -1435,6 +1472,35 @@ pub unsafe extern "C" fn sandlock_result_exit_code(r: *const sandlock_result_t)
     (*r)._private.code().unwrap_or(-1)
 }
 
+/// Terminating reason (normal exit / signal / kill / timeout). Pair with
+/// `sandlock_result_exit_code` (for `EXITED`) and `sandlock_result_signal`
+/// (for `SIGNALED`). Returns `KILLED` for a null result.
+///
+/// # Safety
+/// `r` must be null or a valid result pointer.
+#[no_mangle]
+pub unsafe extern "C" fn sandlock_result_reason(
+    r: *const sandlock_result_t,
+) -> sandlock_exit_reason_t {
+    if r.is_null() {
+        return sandlock_exit_reason_t::Killed;
+    }
+    exit_reason(&(*r)._private.exit_status)
+}
+
+/// Signal number for a `SIGNALED` result, or `-1` for any other reason
+/// (including a null result).
+///
+/// # Safety
+/// `r` must be null or a valid result pointer.
+#[no_mangle]
+pub unsafe extern "C" fn sandlock_result_signal(r: *const sandlock_result_t) -> c_int {
+    if r.is_null() {
+        return -1;
+    }
+    exit_signal(&(*r)._private.exit_status)
+}
+
 /// # Safety
 /// `r` must be null or a valid result pointer.
 #[no_mangle]
@@ -1615,6 +1681,36 @@ pub unsafe extern "C" fn sandlock_dry_run_result_exit_code(
     (*r)._private.run_result.code().unwrap_or(-1) as c_int
 }
 
+/// Terminating reason of a dry-run result (parity with
+/// `sandlock_result_reason`). Returns `KILLED` for a null result.
+///
+/// # Safety
+/// `r` must be null or a valid dry-run result pointer.
+#[no_mangle]
+pub unsafe extern "C" fn sandlock_dry_run_result_reason(
+    r: *const sandlock_dry_run_result_t,
+) -> sandlock_exit_reason_t {
+    if r.is_null() {
+        return sandlock_exit_reason_t::Killed;
+    }
+    exit_reason(&(*r)._private.run_result.exit_status)
+}
+
+/// Signal number for a `SIGNALED` dry-run result, or `-1` otherwise (parity
+/// with `sandlock_result_signal`).
+///
+/// # Safety
+/// `r` must be null or a valid dry-run result pointer.
+#[no_mangle]
+pub unsafe extern "C" fn sandlock_dry_run_result_signal(
+    r: *const sandlock_dry_run_result_t,
+) -> c_int {
+    if r.is_null() {
+        return -1;
+    }
+    exit_signal(&(*r)._private.run_result.exit_status)
+}
+
 /// Check if the dry-run result indicates success.
 ///
 /// # Safety
@@ -2737,6 +2833,42 @@ mod tests {
     use super::policy_ret_to_verdict;
     use sandlock_core::policy_fn::Verdict;
 
+    use super::{
+        exit_reason, exit_signal, sandlock_dry_run_result_reason, sandlock_dry_run_result_signal,
+        sandlock_exit_reason_t, sandlock_result_reason, sandlock_result_signal,
+    };
+    use sandlock_core::ExitStatus;
+
+    #[test]
+    fn exit_reason_maps_every_exit_status() {
+        assert!(matches!(exit_reason(&ExitStatus::Code(0)), sandlock_exit_reason_t::Exited));
+        assert!(matches!(exit_reason(&ExitStatus::Signal(15)), sandlock_exit_reason_t::Signaled));
+        // SIGKILL folds into Killed in core, so KILLED is a distinct reason with
+        // no recoverable signal — the "systemd-style minus oom-kill" boundary.
+        assert!(matches!(exit_reason(&ExitStatus::Killed), sandlock_exit_reason_t::Killed));
+        assert!(matches!(exit_reason(&ExitStatus::Timeout), sandlock_exit_reason_t::Timeout));
+        assert_eq!(exit_signal(&ExitStatus::Signal(15)), 15);
+        for s in [ExitStatus::Code(7), ExitStatus::Killed, ExitStatus::Timeout] {
+            assert_eq!(exit_signal(&s), -1, "only Signal(n) yields a number");
+        }
+    }
+
+    #[test]
+    fn null_result_reason_is_killed_and_signal_minus_one() {
+        unsafe {
+            assert!(matches!(
+                sandlock_result_reason(std::ptr::null()),
+                sandlock_exit_reason_t::Killed
+            ));
+            assert_eq!(sandlock_result_signal(std::ptr::null()), -1);
+            assert!(matches!(
+                sandlock_dry_run_result_reason(std::ptr::null()),
+                sandlock_exit_reason_t::Killed
+            ));
+            assert_eq!(sandlock_dry_run_result_signal(std::ptr::null()), -1);
+        }
+    }
+
     #[test]
     fn policy_ret_maps_documented_values() {
         assert_eq!(policy_ret_to_verdict(0), Verdict::Allow);

go/sandbox.go

@@ -277,12 +277,31 @@ type Sandbox struct {
 	PolicyFn PolicyFunc
 }
 
+// ExitReason is why a sandboxed process terminated. It mirrors the C
+// sandlock_exit_reason enum. Linux bottoms both a timeout and an OOM kill out in
+// SIGKILL, so there is no distinct OOM reason: a timeout sandlock enforced is
+// ReasonTimeout, any other kill is ReasonKilled.
+type ExitReason uint32
+
+const (
+	// ReasonExited: exited normally with a code (Result.ExitCode).
+	ReasonExited ExitReason = 0
+	// ReasonSignaled: terminated by a signal (Result.Signal).
+	ReasonSignaled ExitReason = 1
+	// ReasonKilled: killed with no recoverable signal number.
+	ReasonKilled ExitReason = 2
+	// ReasonTimeout: killed by sandlock because it exceeded its timeout.
+	ReasonTimeout ExitReason = 3
+)
+
 // Result is the outcome of a captured run.
 type Result struct {
-	ExitCode int    // process exit code, or -1 if terminated abnormally
-	Success  bool   // true when the process exited 0
-	Stdout   []byte // captured standard output
-	Stderr   []byte // captured standard error
+	ExitCode int        // process exit code, or -1 if terminated abnormally
+	Reason   ExitReason // why the process terminated (exit / signal / kill / timeout)
+	Signal   int        // signal number for a ReasonSignaled result, else -1
+	Success  bool       // true when the process exited 0
+	Stdout   []byte     // captured standard output
+	Stderr   []byte     // captured standard error
 }
 
 // StdioMode selects how one of a Popen'd process's standard streams is wired.

go/sandlock_linux.go

@@ -589,6 +589,8 @@ func timeoutMs(ctx context.Context) C.uint64_t {
 func readResult(r *C.sandlock_result_t) *Result {
 	res := &Result{
 		ExitCode: int(C.sandlock_result_exit_code(r)),
+		Reason:   ExitReason(C.sandlock_result_reason(r)),
+		Signal:   int(C.sandlock_result_signal(r)),
 		Success:  bool(C.sandlock_result_success(r)),
 	}
 	res.Stdout = readBytes(r, true)
@@ -717,6 +719,8 @@ func (s *Sandbox) DryRun(ctx context.Context, cmd ...string) (*DryRunResult, err
 
 	out := &DryRunResult{Result: Result{
 		ExitCode: int(C.sandlock_dry_run_result_exit_code(r)),
+		Reason:   ExitReason(C.sandlock_dry_run_result_reason(r)),
+		Signal:   int(C.sandlock_dry_run_result_signal(r)),
 		Success:  bool(C.sandlock_dry_run_result_success(r)),
 	}}
 	var n C.uintptr_t

go/sandlock_linux_test.go

@@ -80,6 +80,60 @@ func TestRunExitCode(t *testing.T) {
 	}
 }
 
+// TestExitReason pins the #131 terminating-reason surface across the four
+// ExitStatus variants. SIGKILL folds into ReasonKilled in core (no signal
+// number), distinct from a catchable signal (ReasonSignaled + number); a context
+// deadline enforced by sandlock is ReasonTimeout.
+func TestExitReason(t *testing.T) {
+	requireLandlock(t)
+
+	t.Run("exited", func(t *testing.T) {
+		sb := &sandlock.Sandbox{FSReadable: rootfs}
+		res, err := sb.Run(context.Background(), "sh", "-c", "exit 7")
+		if err != nil {
+			t.Fatalf("Run: %v", err)
+		}
+		if res.Reason != sandlock.ReasonExited || res.ExitCode != 7 || res.Signal != -1 {
+			t.Fatalf("got reason=%d exit=%d signal=%d, want Exited/7/-1", res.Reason, res.ExitCode, res.Signal)
+		}
+	})
+
+	t.Run("timeout", func(t *testing.T) {
+		sb := &sandlock.Sandbox{FSReadable: rootfs}
+		ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+		defer cancel()
+		res, err := sb.Run(ctx, "sleep", "60")
+		if err != nil {
+			t.Fatalf("Run: %v", err)
+		}
+		if res.Reason != sandlock.ReasonTimeout || res.Success {
+			t.Fatalf("got reason=%d success=%v, want ReasonTimeout / not success", res.Reason, res.Success)
+		}
+	})
+
+	t.Run("signaled", func(t *testing.T) {
+		sb := &sandlock.Sandbox{FSReadable: rootfs}
+		res, err := sb.Run(context.Background(), "sh", "-c", "kill -TERM $$")
+		if err != nil {
+			t.Fatalf("Run: %v", err)
+		}
+		if res.Reason != sandlock.ReasonSignaled || res.Signal != 15 {
+			t.Fatalf("got reason=%d signal=%d, want ReasonSignaled/15", res.Reason, res.Signal)
+		}
+	})
+
+	t.Run("killed", func(t *testing.T) {
+		sb := &sandlock.Sandbox{FSReadable: rootfs}
+		res, err := sb.Run(context.Background(), "sh", "-c", "kill -KILL $$")
+		if err != nil {
+			t.Fatalf("Run: %v", err)
+		}
+		if res.Reason != sandlock.ReasonKilled || res.Signal != -1 {
+			t.Fatalf("got reason=%d signal=%d, want ReasonKilled/-1", res.Reason, res.Signal)
+		}
+	})
+}
+
 func TestRunEmptyCommand(t *testing.T) {
 	sb := &sandlock.Sandbox{}
 	if _, err := sb.Run(context.Background()); err == nil {

python/src/sandlock/__init__.py

@@ -7,7 +7,7 @@
 
 from ._version import __version__
 from ._sdk import (
-    Stage, Pipeline, Result, SyscallEvent, PolicyContext, Checkpoint, SkippedFd,
+    Stage, Pipeline, Result, ExitReason, SyscallEvent, PolicyContext, Checkpoint, SkippedFd,
     NamedStage, Gather, GatherPipeline,
     Protection,
     landlock_abi_version, min_landlock_abi, confine,
@@ -40,6 +40,7 @@
     "Stage",
     "Pipeline",
     "Result",
+    "ExitReason",
     "SyscallEvent",
     "PolicyContext",
     "Checkpoint",