This may be that I'm not using things right: I can't find any document that explains the differences between inactivating, freezing and decommissioning a host.

If I go through the following steps:

1. Mark a host inactive (via POST /api/inactive).
2. Stop the mesos-agent on it.
3. Start a new instance of mesos-agent on it (I'm using a Docker container to run Mesos, so I think it gets a new slave ID, but I'm not 100% sure).
4. Mark the host active again (via DELETE /api/inactive).

Then the slave remains in the decommissioned state and won't run any tasks.

My goal is to be able to prevent new tasks running on a slave (so that once existing tasks die we can reboot/do maintenance on it - we use only on-demand tasks with finite lifetime), and later allow tasks to run on it again (possibly after doing maintenance on it). I've been using "inactive" rather than "freeze" because the former API works on hostnames, which means it can be set even if the mesos-agent isn't running at the time. But let me know what you advise for that.