Enable cgroup controllers in the parent before creating child cgroups

A child cgroup has no memory.max or cpu.max until the parent lists the
controller in cgroup.subtree_control, and a private cgroup namespace root
starts empty, so every nested-cgroup scenario aborted before reaching the
payload. The launchers now enable the controllers, relocating the leaf
process first where the no-internal-process rule requires it, and a failed
probe drops its layer instead of killing the run.

The unit suite also now runs in CI. It was unreferenced by any workflow
while the end-to-end jobs are red by design, leaving nothing that could
report green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BEZUSri3baWU58Ge1kAVnT

Author: claude

.github/workflows/e2e-linux.yml

@@ -46,7 +46,21 @@ jobs:
                 curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.23.0/kind-linux-amd64
                 chmod +x ./kind
                 sudo mv ./kind /usr/local/bin/kind
-                kind create cluster --wait 120s
+                # Mount the checked-out repo into the node so the pod
+                # KubernetesLauncher schedules can hostPath-mount it in turn
+                # (see tests/e2e/launchers/kubernetes.py) -- without this the
+                # pod's image has no repo, no PYTHONPATH, and no psutil, and
+                # every kind scenario is a permanent infra error.
+                {
+                  echo "kind: Cluster"
+                  echo "apiVersion: kind.x-k8s.io/v1alpha4"
+                  echo "nodes:"
+                  echo "- role: control-plane"
+                  echo "  extraMounts:"
+                  echo "  - hostPath: ${GITHUB_WORKSPACE}"
+                  echo "    containerPath: /host-repo"
+                } > kind-config.yaml
+                kind create cluster --config kind-config.yaml --wait 120s
                 ;;
               kubectl)
                 curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

.github/workflows/e2e.yml

@@ -23,6 +23,26 @@ on:
   workflow_dispatch:
 
 jobs:
+  # The only job in this workflow that is meant to be, and stay, green: the
+  # registry-integrity oracle, the composed-minimum math, the composition/argv
+  # regressions, the CALIBRATION.md-vs-registry cross-check, and the workflow
+  # lint (138+ tests across tests/unit) never depend on a docker/cgroup2/
+  # systemd/Windows/macOS runtime, so they run unconditionally on every push
+  # and PR -- unlike the e2e jobs below, which are expected to be red until
+  # the real sensor implementation lands. This job must never gain
+  # `continue-on-error` or any other soft-fail wrapper: with the e2e jobs
+  # permanently red by design, this is the only signal a broken registry edit
+  # or composition regression has to surface at all.
+  unit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install -e ".[test]"
+      - run: python -m pytest tests/unit -v
+
   emit-matrix:
     runs-on: ubuntu-latest
     outputs:

README.md

@@ -1,2 +1,72 @@
 # cgroups-sensor
-Utility functions to measure resource limits from cgroups in scenarios where psutils is not sufficient.
+
+Utility functions to measure the resource limits actually enforced on the
+current process, in scenarios where `psutil` is not sufficient (it reports
+host capacity, not a cgroup limit, a container `--memory`/`--cpus` flag, a
+POSIX rlimit, or a Windows Job Object).
+
+## Public contract
+
+```python
+from cgroups_sensor import measure_max_available_memory, measure_max_available_cpu
+
+measure_max_available_memory()  # -> int, bytes
+measure_max_available_cpu()     # -> int, millicores (1000 == one full core)
+```
+
+- **`measure_max_available_memory()`** returns the maximum memory, in bytes,
+  this process may use.
+- **`measure_max_available_cpu()`** returns the maximum CPU this process may
+  use, in integer **millicores** -- one full CPU core is `1000`; a `0.5`-core
+  quota (e.g. Docker's `--cpus=0.5`) is `500`.
+- **`0` means "no mechanism is actually enforcing a ceiling on this process
+  right now"** -- never host capacity, never `None`, never "unknown".
+- When more than one mechanism constrains the same process at once (an
+  rlimit, a cgroup, and a container flag can all apply simultaneously), both
+  helpers report the **minimum** of the ceilings actually being enforced --
+  the real, effective ceiling the OS applies, not merely the innermost
+  mechanism or the last one applied.
+
+This contract is final and will not change when the implementation behind it
+does.
+
+## Current status: placeholder implementation
+
+The two functions above are implemented today as thin `psutil`-only
+placeholders (see `src/cgroups_sensor/__init__.py`) -- they are **not** yet
+cgroup/rlimit/Job-Object-aware. They are expected to return the wrong number
+for most container/cgroup/systemd/Kubernetes/Windows-Job-Object scenarios,
+because `psutil` itself reports host-scoped values in those cases. That gap
+is intentional and is exactly what `tests/e2e` exists to make visible, not to
+paper over -- do not read a passing placeholder value as evidence the real
+sensor is done.
+
+## Test suite
+
+- **`tests/unit`** -- fast, dependency-light tests of the scenario registry,
+  the composed-expected-value math, launcher argv construction, and workflow
+  generation. These never touch a real cgroup/docker/Windows API and run on
+  any machine: `python -m pytest tests/unit`.
+- **`tests/e2e`** -- an end-to-end matrix that imposes real OS-level resource
+  limits (rlimits, cgroups, `systemd-run --scope`, `docker`/`podman run`,
+  Kubernetes pods, Windows Job Objects, Windows containers) across
+  Linux/macOS/Windows GitHub-hosted runners, measures both helpers under each
+  limit, and asserts the real, composed ceiling. This suite is **expected to
+  be red** against the current placeholder implementation -- see "Current
+  status" above -- and stays red until the real sensor lands. It only
+  executes meaningfully on a matching GitHub-hosted runner; running it
+  locally mostly produces skips (`pytest tests/e2e --collect-only` is the
+  right way to sanity-check it outside CI).
+- **`tests/e2e/CALIBRATION.md`** is the durable record of which memory
+  scenarios' expected values were validated, before being committed, by a
+  one-time build-time over-allocation experiment (never shipped as running
+  code) -- see that file for the per-scenario evidence.
+
+## CI
+
+`.github/workflows/e2e.yml` dispatches: a `unit` job (always green, runs
+`tests/unit` on every push/PR) plus a matrix generated from the scenario
+registry (`tests/e2e/scenarios.py --emit-matrix`), routed to one reusable
+workflow per runner family (`e2e-linux.yml`, `e2e-macos.yml`,
+`e2e-windows.yml`). Adding a scenario is a one-row registry edit; no workflow
+file needs to change.

tests/e2e/CALIBRATION.md

@@ -17,16 +17,14 @@ OOM-kill (the cgroup-style signature) or an in-process refusal --
 `MemoryError` on Linux/macOS, `ERROR_NOT_ENOUGH_MEMORY`/commit failure on
 Windows -- (the rlimit/Job-Object-style signature).
 
-**What could and could not be calibrated in this build environment**, per the
-orchestrator's pre-dispatch feasibility probe and my own follow-up
-experiments: `RLIMIT_AS` genuinely binds in this sandbox (a plain
-`setrlimit(2)` call, no cgroup2/docker/systemd/Windows/macOS needed) and was
-exercised directly. Every mechanism requiring cgroup v2, a docker/podman
-daemon, systemd as PID 1, a Kubernetes/kind cluster, a Windows host, or a
-macOS host could **not** be exercised here (this build environment: Linux,
-`/sys/fs/cgroup` is a tmpfs not cgroup2, no docker daemon, systemd is not PID
-1) and is marked UNVALIDATED with the specific missing prerequisite, never
-fabricated.
+**What could and could not be calibrated in this build environment**: `RLIMIT_AS`
+genuinely binds in this sandbox (a plain `setrlimit(2)` call, no
+cgroup2/docker/systemd/Windows/macOS needed) and was exercised directly.
+Every mechanism requiring cgroup v2, a docker/podman daemon, systemd as PID
+1, a Kubernetes/kind cluster, a Windows host, or a macOS host could **not** be
+exercised here (this build environment: Linux, `/sys/fs/cgroup` is a tmpfs
+not cgroup2, no docker daemon, systemd is not PID 1) and is marked
+UNVALIDATED with the specific missing prerequisite, never fabricated.
 
 ## Calibration table
 
@@ -42,7 +40,7 @@ fabricated.
 | `linux-podman-memory` | `167,772,160` B (160 MiB) if the needs-probe delegation check passes, else `0` | UNVALIDATED | No podman binary / no docker-equivalent daemon in this sandbox. |
 | `linux-kubernetes-memory` | `201,326,592` B (192 MiB) if the needs-probe delegation check passes, else `0` | UNVALIDATED | No docker daemon, so no kind cluster is startable here. |
 | `linux-stacked-outer-cgroup-tighter` | `134,217,728` B (128 MiB, the outer cgroup layer) | UNVALIDATED as a composed scenario | Its `RLIMIT_AS` (256 MiB) layer alone shares the mechanism validated above, but the *composed* expectation is governed by the tighter cgroup layer, which cannot be exercised here (no cgroup2). The whole scenario's calibration therefore cannot be completed in this environment. |
-| `linux-triple-stack-container-tightest` | `536,870,912` B (512 MiB, the docker layer) if the nested-cgroup probe passes | UNVALIDATED | Requires docker `--privileged --cgroupns=private` plus a writable nested cgroup2; neither is available here. |
+| `linux-triple-stack-container-tightest` | `536,870,912` B (512 MiB, the docker layer, unconditionally -- it is the tightest of the three layers regardless of whether the nested-cgroup probe passes, per `test_composition.py::test_all_triple_stack_variants_agree_when_probe_omitted_entirely`) | UNVALIDATED | Requires docker `--privileged --cgroupns=private` plus a writable nested cgroup2; neither is available here. |
 | `linux-triple-stack-nested-cgroup-tightest` | `536,870,912` B (512 MiB, the nested-cgroup layer) if its probe passes, else `805,306,368` B (768 MiB, the rlimit layer) | UNVALIDATED | Same as above. |
 | `linux-triple-stack-rlimit-tightest` | `536,870,912` B (512 MiB, the rlimit layer, unconditionally) | UNVALIDATED as a composed scenario | The rlimit layer's own mechanism is the one validated above, but the composed scenario as a whole (docker + nested cgroup context) cannot be exercised here. |
 | `macos-rlimit-as-memory` | `314,572,800` B (300 MiB), `setrlimit(RLIMIT_AS)` on macOS | UNVALIDATED | Requires a macOS host; this sandbox is Linux. The underlying POSIX `setrlimit`/`getrlimit(RLIMIT_AS)` semantics are the same call validated on Linux above, but that is supporting context, not equivalent evidence -- macOS's own allocator/kernel behavior was not independently exercised. |

tests/e2e/conftest.py

@@ -10,7 +10,7 @@
 
 import os
 
-from tests.e2e.test_e2e import _SUMMARY_ROWS
+from tests.e2e.reporting import SUMMARY_ROWS
 
 
 def _render_markdown_table(rows: list[dict]) -> str:
@@ -29,8 +29,8 @@ def _render_markdown_table(rows: list[dict]) -> str:
 
 def pytest_sessionfinish(session, exitstatus) -> None:  # noqa: ARG001
     summary_path = os.environ.get("GITHUB_STEP_SUMMARY")
-    if not summary_path or not _SUMMARY_ROWS:
+    if not summary_path or not SUMMARY_ROWS:
         return
     with open(summary_path, "a", encoding="utf-8") as fh:
         fh.write("\n## cgroups-sensor e2e scenario results\n\n")
-        fh.write(_render_markdown_table(_SUMMARY_ROWS))
+        fh.write(_render_markdown_table(SUMMARY_ROWS))

tests/e2e/inner.py

@@ -24,6 +24,10 @@
 
 SENTINEL = "CGROUPS_SENSOR_RESULT::"
 
+_JobObjectExtendedLimitInformation = 9
+_JobObjectCpuRateControlInformation = 15
+_JOB_OBJECT_LIMIT_JOB_MEMORY = 0x00000200
+
 
 def _rlimits() -> dict:
     try:
@@ -70,8 +74,33 @@ def _read_text(path: str) -> str | None:
         return None
 
 
+def _cgroup_ancestors(cgroup_root: str, own_path: str) -> list[dict]:
+    """Every cgroup directory from this process's own cgroup up to (and
+    including) the root, each with its own ``memory.max``/``cpu.max`` read
+    back. A layer may be imposed on an *ancestor* of the process's own
+    leaf cgroup (e.g. a container's own cgroup, one level above a nested
+    cgroup created inside it) -- walking the whole chain and exact-matching
+    a declared value against any level is what lets the structural check
+    find "the nearest ancestor that carries the value" instead of only ever
+    looking at this process's own immediate cgroup.
+    """
+    ancestors: list[dict] = []
+    parts = [p for p in own_path.strip("/").split("/") if p]
+    for depth in range(len(parts), -1, -1):
+        rel = "/".join(parts[:depth])
+        base = os.path.join(cgroup_root, rel) if rel else cgroup_root
+        ancestors.append(
+            {
+                "path": base,
+                "memory_max": _read_text(os.path.join(base, "memory.max")),
+                "cpu_max": _read_text(os.path.join(base, "cpu.max")),
+            }
+        )
+    return ancestors
+
+
 def _cgroup_facts() -> dict:
-    facts: dict = {"version": None, "memory_max": None, "cpu_max": None, "controllers": None}
+    facts: dict = {"version": None, "memory_max": None, "cpu_max": None, "controllers": None, "ancestors": []}
     cgroup_root = "/sys/fs/cgroup"
     if not os.path.isdir(cgroup_root):
         return facts
@@ -82,12 +111,85 @@ def _cgroup_facts() -> dict:
         facts["memory_max"] = _read_text(os.path.join(base, "memory.max"))
         facts["cpu_max"] = _read_text(os.path.join(base, "cpu.max"))
         facts["controllers"] = _read_text(os.path.join(base, "cgroup.controllers"))
+        facts["ancestors"] = _cgroup_ancestors(cgroup_root, own_path)
     elif os.path.isdir(os.path.join(cgroup_root, "memory")):
         facts["version"] = 1
         facts["memory_max"] = _read_text(os.path.join(cgroup_root, "memory", "memory.limit_in_bytes"))
     return facts
 
 
+def _query_job_object_limits() -> dict:
+    """Read back the *actual* limit state of the Job Object this process is
+    in via ``QueryInformationJobObject`` -- not just whether it is in *some*
+    job (``IsProcessInJob``, which says nothing about what, if anything, that
+    job enforces). Pure ``ctypes`` (no pywin32 dependency for the payload
+    itself, which may run inside a bare container image with no pywin32
+    installed): the struct layouts below are stable, decades-old Win32 ABI,
+    unaffected by which Python/OS build is running.
+    """
+    import ctypes
+
+    class _IoCounters(ctypes.Structure):
+        _fields_ = [
+            ("ReadOperationCount", ctypes.c_ulonglong),
+            ("WriteOperationCount", ctypes.c_ulonglong),
+            ("OtherOperationCount", ctypes.c_ulonglong),
+            ("ReadTransferCount", ctypes.c_ulonglong),
+            ("WriteTransferCount", ctypes.c_ulonglong),
+            ("OtherTransferCount", ctypes.c_ulonglong),
+        ]
+
+    class _BasicLimitInformation(ctypes.Structure):
+        _fields_ = [
+            ("PerProcessUserTimeLimit", ctypes.c_int64),
+            ("PerJobUserTimeLimit", ctypes.c_int64),
+            ("LimitFlags", ctypes.c_uint32),
+            ("MinimumWorkingSetSize", ctypes.c_size_t),
+            ("MaximumWorkingSetSize", ctypes.c_size_t),
+            ("ActiveProcessLimit", ctypes.c_uint32),
+            ("Affinity", ctypes.c_void_p),
+            ("PriorityClass", ctypes.c_uint32),
+            ("SchedulingClass", ctypes.c_uint32),
+        ]
+
+    class _ExtendedLimitInformation(ctypes.Structure):
+        _fields_ = [
+            ("BasicLimitInformation", _BasicLimitInformation),
+            ("IoInfo", _IoCounters),
+            ("ProcessMemoryLimit", ctypes.c_size_t),
+            ("JobMemoryLimit", ctypes.c_size_t),
+            ("PeakProcessMemoryUsed", ctypes.c_size_t),
+            ("PeakJobMemoryUsed", ctypes.c_size_t),
+        ]
+
+    class _CpuRateControlInformation(ctypes.Structure):
+        _fields_ = [("ControlFlags", ctypes.c_uint32), ("CpuRate", ctypes.c_uint32)]
+
+    kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
+    facts: dict = {}
+
+    ext_info = _ExtendedLimitInformation()
+    # QueryInformationJobObject accepts a NULL job handle to mean "the job
+    # associated with the calling process" -- no separate handle needed here.
+    ok = kernel32.QueryInformationJobObject(
+        None, _JobObjectExtendedLimitInformation, ctypes.byref(ext_info), ctypes.sizeof(ext_info), None,
+    )
+    if ok:
+        limit_flags = ext_info.BasicLimitInformation.LimitFlags
+        facts["memory_limit_flag_set"] = bool(limit_flags & _JOB_OBJECT_LIMIT_JOB_MEMORY)
+        facts["job_memory_limit"] = int(ext_info.JobMemoryLimit)
+
+    cpu_info = _CpuRateControlInformation()
+    ok = kernel32.QueryInformationJobObject(
+        None, _JobObjectCpuRateControlInformation, ctypes.byref(cpu_info), ctypes.sizeof(cpu_info), None,
+    )
+    if ok:
+        facts["cpu_rate_control_flags"] = int(cpu_info.ControlFlags)
+        facts["cpu_rate"] = int(cpu_info.CpuRate)
+
+    return facts
+
+
 def _windows_job_facts() -> dict:
     if platform.system() != "Windows":
         return {"in_job_object": None}
@@ -99,7 +201,10 @@ def _windows_job_facts() -> dict:
         ok = kernel32.IsProcessInJob(kernel32.GetCurrentProcess(), None, ctypes.byref(result))
         if not ok:
             return {"in_job_object": None, "error": "IsProcessInJob call failed"}
-        return {"in_job_object": bool(result.value)}
+        facts: dict = {"in_job_object": bool(result.value)}
+        if facts["in_job_object"]:
+            facts.update(_query_job_object_limits())
+        return facts
     except Exception as exc:  # pragma: no cover - Windows-only path
         return {"in_job_object": None, "error": str(exc)}
 
@@ -111,6 +216,7 @@ def gather_platform_facts() -> dict:
         "pid": os.getpid(),
         "rlimits": _rlimits(),
         "cpu_affinity": _cpu_affinity(),
+        "os_cpu_count": os.cpu_count(),
         "cgroup": _cgroup_facts(),
         "windows_job": _windows_job_facts(),
     }

tests/e2e/launchers/base.py

@@ -71,10 +71,31 @@ class Launcher(ABC):
     #: needs-probe layer.
     probe_key: str | None = None
 
+    #: Set by a launcher whose structural probe can only be evaluated from
+    #: inside the same execution context the payload itself runs in (e.g. a
+    #: probe that must run inside a container's own mount/cgroup namespace,
+    #: not from the outside). When set, the harness never calls `probe()` for
+    #: this launcher; instead it checks whether this exact string appears in
+    #: the combined stdout+stderr of the same invocation that ran the payload
+    #: (see `probe_passed_in_output`). None (the default) means the probe is
+    #: evaluated the ordinary way, via a standalone `probe()` call before the
+    #: payload runs.
+    probe_marker: str | None = None
+
     def probe(self) -> ProbeResult:
-        """Structural presence/binding check. Default: nothing to probe."""
+        """Structural presence/binding check, called standalone before the
+        payload runs. Only called when `probe_marker` is None -- a launcher
+        that sets `probe_marker` reports its probe result in-band instead (see
+        `probe_passed_in_output`) and does not need to override this. Default:
+        nothing to probe."""
         return ProbeResult(True, "no structural probe required for this layer type")
 
+    def probe_passed_in_output(self, combined_output: str) -> bool:
+        """Whether an in-band probe (`probe_marker` set) reported success,
+        judged from the combined stdout+stderr of the same run that executed
+        the payload. Only meaningful when `probe_marker` is not None."""
+        return self.probe_marker is not None and self.probe_marker in combined_output
+
     @abstractmethod
     def run(self, inner_argv: Sequence[str]) -> RunResult:
         """Execute inner_argv under this layer's constraint and capture output."""