[obasilakis]

Closes #2318.

Problem

Docker refuses to create a container whose CPU limit exceeds the host's CPU count (range of CPUs is from 0.01 to 2.00, as there are only 2 CPUs available). The trinity-system template asks for 4 CPUs, so on any 2-CPU host the system agent is never created, and creation fails again on every backend start. A 2-vCPU t3a.large is the default instance type for the AWS Marketplace listing (#3004). A user agent set above the host's CPUs fails the same way.

Fix

services/docker_utils.containers_run — the single seam every agent create and recreate goes through (system agent, crud.py, lifecycle.py) — caps nano_cpus at docker info's NCPU and logs a warning when it does.

Deliberately not capped: the trinity.cpu label. helpers.py's resource drift check compares that label with the DB setting; a capped label would mismatch a DB value of 4 and recreate the agent on every start. The issue suggested capping the label too; this is why it doesn't.

If the host CPU count can't be read, the request passes through unchanged (Docker decides, as before).

Verification

• tests/unit/test_2318_cpu_capped_to_host.py: 4→2 on 2 CPUs, unchanged when it fits, odd host count (8→3), no limit untouched, unreadable host count passes through. Failed before the fix on the two capping cases; passes after. Existing test_docker_utils.py passes.
• Live: on a 2-vCPU EC2 instance (AMI from v1.0.0-aws.1) the backend logged the 400 above. With this file in place and the backend restarted: [#2318] CPU limit 4 exceeds the host's 2 CPUs; capping to 2, then System agent: created; container NanoCpus=2000000000, label trinity.cpu=4.
• Full unit suite locally: the only failures are identical with and without this change (same 24 failed / 2 errors when those files are run on plain dev), from a local Python 3.11 environment; CI runs 3.13.

🤖 Generated with Claude Code

[github-actions]

⚠️ Nightly unit-suite found regressions when this PR is merged into dev (3 of 3 seeds).

Regression details (head_sha: `0292f04d26bad918fd521d2ecc2f1acd6115735c`)

Seed 12345

Backend unit-suite regression diff

Per-XML totals

Side	Path	Total	Pass	Fail	Error	Skip
base	junit-base-pr3184-12345.xml	21069	21031	0	0	38
head	junit-head-pr3184-12345.xml	21070	21031	0	1	38

❌ New failures introduced by HEAD (1)

Tests failing under HEAD that did not fail under BASE in any seed:

• [E] test_2318_cpu_capped_to_host

Legend: [F] = assertion failure, [E] = collection or fixture error.
Identity = (classname, name, kind); union taken across all input XMLs.

---

Seed 67890

Backend unit-suite regression diff

Per-XML totals

Side	Path	Total	Pass	Fail	Error	Skip
base	junit-base-pr3184-67890.xml	21069	21031	0	0	38
head	junit-head-pr3184-67890.xml	21070	21031	0	1	38

❌ New failures introduced by HEAD (1)

Tests failing under HEAD that did not fail under BASE in any seed:

• [E] test_2318_cpu_capped_to_host

Legend: [F] = assertion failure, [E] = collection or fixture error.
Identity = (classname, name, kind); union taken across all input XMLs.

---

Seed 99999

Backend unit-suite regression diff

Per-XML totals

Side	Path	Total	Pass	Fail	Error	Skip
base	junit-base-pr3184-99999.xml	21069	21031	0	0	38
head	junit-head-pr3184-99999.xml	21070	21031	0	1	38

❌ New failures introduced by HEAD (1)

Tests failing under HEAD that did not fail under BASE in any seed:

• [E] test_2318_cpu_capped_to_host

Legend: [F] = assertion failure, [E] = collection or fixture error.
Identity = (classname, name, kind); union taken across all input XMLs.

Reproduce locally: git merge dev && ( cd tests && python -m pytest unit/ -m "not slow" -p randomly --randomly-seed=12345 )

[vybe]

merge-train (2026-10-04): on today's train. Two commits pushed to this branch, both mechanical:

• 11950b153: tests/unit/test_2318_cpu_capped_to_host.py imported get_docker_utils from test_docker_utils by bare name. tests/unit is not on sys.path, so the file failed at collection (ModuleNotFoundError: No module named 'test_docker_utils'). That was the red regression diff and the nightly's [E] test_2318_cpu_capped_to_host. I added the path preamble the other sibling-importing unit tests use (test_2392_effect_guard_fail_closed.py, test_3185_a2a_credential_kind.py). No assertion changed.
• a068b4bfd: merged dev (16 commits behind, no conflicts).

Checked before pushing:

• The six tests pass, alone and under -n 2 --dist loadfile -p randomly --randomly-seed=12345 alongside test_docker_utils.py.
• With the _cap_nano_cpus_to_host(kwargs) call removed, the two capping cases (4→2, 8→3) go red, so the tests execute the fix.
• All three create paths reach the cap through containers_run: crud.py, lifecycle.py and system_agent_service.py (the trinity-system case from bug: trinity-system agent can never be created on hosts with fewer than 4 CPUs — template cpu:"4" passed to Docker unclamped #2318).

It merges once Tier 1 is green on the new head.

[vybe]

merge-train: validated on 2026-10-04. The tests drive containers_run and go red without the cap; all three create paths reach it. Tier 1 is green on a068b4b after the mechanical import fix.