From 452c0840e1b933f3163ac066b2f16a7ac423ed26 Mon Sep 17 00:00:00 2001
From: Joseph Mearman <joseph@mearman.co.uk>
Date: Tue, 20 Oct 2026 11:14:28 +0100
Subject: [PATCH 1/3] feat(cluster): derive the container runtime from the
 Docker context

A filter that tells Colima, Docker Desktop and any other runtime apart from
the Docker context the role drives, and which Colima profile a context
belongs to, with the runtime and profile overridable for hosts whose context
does not say. It refuses a profile that names another VM than the context,
and any profile name that is not a valid Lima instance name.
---
 plugins/filter/container_runtime.py  | 74 ++++++++++++++++++++++
 tests/unit/test_container_runtime.py | 91 ++++++++++++++++++++++++++++
 2 files changed, 165 insertions(+)
 create mode 100644 plugins/filter/container_runtime.py
 create mode 100644 tests/unit/test_container_runtime.py

diff --git a/plugins/filter/container_runtime.py b/plugins/filter/container_runtime.py
new file mode 100644
index 0000000..79e6ddb
--- /dev/null
+++ b/plugins/filter/container_runtime.py
@@ -0,0 +1,74 @@
+"""Filter the github_runner_cluster role uses to tell which container runtime a macOS host's Docker context belongs to, and so whether the role can start that runtime itself."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ansible.errors import AnsibleFilterError
+
+RUNTIME_CHOICES = ("auto", "colima", "docker_desktop", "other")
+# Colima names the Docker context of its default profile "colima" and any other profile's "colima-<profile>".
+COLIMA_CONTEXT = "colima"
+COLIMA_DEFAULT_PROFILE = "default"
+# Docker Desktop's own context for its Linux engine.
+DOCKER_DESKTOP_CONTEXTS = ("desktop-linux",)
+# Lima's rule for an instance name, which is what a Colima profile becomes. It also keeps the value free of every character that would need escaping in a launchd property list or on a command line.
+PROFILE_PATTERN = re.compile(r"^[A-Za-z0-9]+([._-][A-Za-z0-9]+)*$")
+
+
+def _text(name: str, value: Any) -> str:
+    if value is None:
+        return ""
+    if not isinstance(value, str):
+        raise AnsibleFilterError(f"{name} must be a string, not {type(value).__name__}: {value!r}.")
+    return value.strip()
+
+
+def _colima_profile_of(context: str) -> str | None:
+    """Return the Colima profile a Docker context belongs to, or None when it is not a Colima context."""
+    if context == COLIMA_CONTEXT:
+        return COLIMA_DEFAULT_PROFILE
+    prefix = COLIMA_CONTEXT + "-"
+    if context.startswith(prefix) and len(context) > len(prefix):
+        return context[len(prefix) :]
+    return None
+
+
+def cluster_container_runtime(context: Any, requested: Any = "auto", colima_profile: Any = "") -> dict[str, str]:
+    """Work out which container runtime a macOS host's Docker daemon belongs to.
+
+    The role calls it only for a macOS host, the only kind it starts a runtime on. ``auto`` takes the runtime from the Docker context the role drives: a Colima context (``colima`` or ``colima-<profile>``) is Colima and ``desktop-linux`` is Docker Desktop, and anything else (including no context because ``DOCKER_HOST`` is set) is ``other``.
+
+    :param context: the Docker context the role drives, or an empty value for none. :param requested: ``auto``, ``colima``, ``docker_desktop`` or ``other``. :param colima_profile: the Colima profile to start, or an empty value to take it from the context (``default`` when the context names none).
+    :returns: ``{"kind": "colima" | "docker_desktop" | "other", "colima_profile": <profile, empty unless kind is colima>}``.
+    :raises AnsibleFilterError: if a value is not a string, ``requested`` is not one of the choices, the profile is not a valid Colima profile name, or it names another profile than the Colima context the role drives.
+    """
+    docker_context = _text("The Docker context", context)
+    choice = _text("The container runtime", requested) or "auto"
+    profile = _text("The Colima profile", colima_profile)
+    if choice not in RUNTIME_CHOICES:
+        raise AnsibleFilterError(f"The container runtime must be one of {', '.join(RUNTIME_CHOICES)}, not {choice!r}.")
+    if profile and not PROFILE_PATTERN.match(profile):
+        raise AnsibleFilterError(f"The Colima profile {profile!r} is not a valid profile name: use letters and digits, separated by single dots, hyphens or underscores.")
+    context_profile = _colima_profile_of(docker_context)
+    if choice == "auto":
+        if context_profile is not None:
+            choice = "colima"
+        elif docker_context in DOCKER_DESKTOP_CONTEXTS:
+            choice = "docker_desktop"
+        else:
+            choice = "other"
+    if choice != "colima":
+        return {"kind": choice, "colima_profile": ""}
+    if profile and context_profile is not None and profile != context_profile:
+        raise AnsibleFilterError(f"The Colima profile {profile!r} is not the one the Docker context {docker_context!r} belongs to ({context_profile!r}); the role would start one VM and drive another.")
+    return {"kind": "colima", "colima_profile": profile or context_profile or COLIMA_DEFAULT_PROFILE}
+
+
+class FilterModule:
+    """Registers the container runtime filter with Ansible."""
+
+    def filters(self) -> dict[str, Any]:
+        """Return the filters this plugin provides."""
+        return {"cluster_container_runtime": cluster_container_runtime}
diff --git a/tests/unit/test_container_runtime.py b/tests/unit/test_container_runtime.py
new file mode 100644
index 0000000..8eb7690
--- /dev/null
+++ b/tests/unit/test_container_runtime.py
@@ -0,0 +1,91 @@
+"""Tests for the filter that tells which container runtime a macOS host's Docker context belongs to."""
+
+from __future__ import annotations
+
+import importlib.util
+import unittest
+from pathlib import Path
+
+PLUGIN = Path(__file__).resolve().parents[2] / "plugins" / "filter" / "container_runtime.py"
+_spec = importlib.util.spec_from_file_location("container_runtime_filters", PLUGIN)
+assert _spec is not None and _spec.loader is not None
+container_runtime = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(container_runtime)
+
+runtime = container_runtime.cluster_container_runtime
+
+
+class AutoDetectionTest(unittest.TestCase):
+    def test_the_default_colima_context_is_the_default_profile(self) -> None:
+        self.assertEqual(runtime("colima"), {"kind": "colima", "colima_profile": "default"})
+
+    def test_another_profile_s_context_names_the_profile(self) -> None:
+        self.assertEqual(runtime("colima-example"), {"kind": "colima", "colima_profile": "example"})
+        self.assertEqual(runtime("colima-build-2", "auto"), {"kind": "colima", "colima_profile": "build-2"})
+
+    def test_docker_desktop_s_context_is_docker_desktop(self) -> None:
+        self.assertEqual(runtime("desktop-linux"), {"kind": "docker_desktop", "colima_profile": ""})
+
+    def test_any_other_context_or_none_is_another_runtime(self) -> None:
+        for context in ("default", "orbstack", "colimas", "colima-", "", None, "  "):
+            with self.subTest(context=context):
+                self.assertEqual(runtime(context), {"kind": "other", "colima_profile": ""})
+
+    def test_surrounding_whitespace_is_not_part_of_the_name(self) -> None:
+        self.assertEqual(runtime(" colima-example\n"), {"kind": "colima", "colima_profile": "example"})
+
+
+class RequestedRuntimeTest(unittest.TestCase):
+    def test_colima_can_be_named_for_a_context_that_does_not_say(self) -> None:
+        self.assertEqual(runtime("", "colima"), {"kind": "colima", "colima_profile": "default"})
+        self.assertEqual(runtime("orbstack", "colima", "example"), {"kind": "colima", "colima_profile": "example"})
+
+    def test_a_named_runtime_wins_over_the_context(self) -> None:
+        self.assertEqual(runtime("colima", "docker_desktop"), {"kind": "docker_desktop", "colima_profile": ""})
+        self.assertEqual(runtime("colima", "other"), {"kind": "other", "colima_profile": ""})
+        self.assertEqual(runtime("desktop-linux", "colima"), {"kind": "colima", "colima_profile": "default"})
+
+    def test_only_colima_has_a_profile(self) -> None:
+        self.assertEqual(runtime("desktop-linux", "docker_desktop", "example"), {"kind": "docker_desktop", "colima_profile": ""})
+
+    def test_a_profile_that_agrees_with_the_context_is_accepted(self) -> None:
+        self.assertEqual(runtime("colima-example", "auto", "example"), {"kind": "colima", "colima_profile": "example"})
+        self.assertEqual(runtime("colima", "colima", "default"), {"kind": "colima", "colima_profile": "default"})
+
+    def test_a_profile_that_names_another_vm_than_the_context_is_an_error(self) -> None:
+        for context, profile in (("colima-example", "other"), ("colima", "example"), ("colima-example", "default")):
+            with self.subTest(context=context, profile=profile), self.assertRaises(container_runtime.AnsibleFilterError):
+                runtime(context, "auto", profile)
+
+
+class InvalidInputTest(unittest.TestCase):
+    def test_an_unknown_runtime_is_an_error(self) -> None:
+        for value in ("docker-desktop", "podman", "COLIMA"):
+            with self.subTest(value=value), self.assertRaises(container_runtime.AnsibleFilterError):
+                runtime("colima", value)
+
+    def test_an_empty_runtime_is_auto(self) -> None:
+        self.assertEqual(runtime("colima", ""), runtime("colima", "auto"))
+        self.assertEqual(runtime("colima", None), runtime("colima", "auto"))
+
+    def test_a_profile_that_is_not_a_lima_instance_name_is_an_error(self) -> None:
+        for profile in ("a b", "-x", "x-", "a--b", "a/b", "a&b", "a<b", "x\n--help", "../x", "a'b", 'a"b'):
+            with self.subTest(profile=profile), self.assertRaises(container_runtime.AnsibleFilterError):
+                runtime("colima", "colima", profile)
+
+    def test_a_profile_may_use_single_separators(self) -> None:
+        for profile in ("a", "A1", "build-2", "build_2", "build.2", "a-b.c_d"):
+            with self.subTest(profile=profile):
+                self.assertEqual(runtime("", "colima", profile), {"kind": "colima", "colima_profile": profile})
+
+    def test_a_value_that_is_not_a_string_is_an_error(self) -> None:
+        for args in ((["colima"],), ("colima", ["auto"]), ("colima", "colima", 3)):
+            with self.subTest(args=args), self.assertRaises(container_runtime.AnsibleFilterError):
+                runtime(*args)
+
+    def test_the_filter_is_registered(self) -> None:
+        self.assertIs(container_runtime.FilterModule().filters()["cluster_container_runtime"], runtime)
+
+
+if __name__ == "__main__":
+    unittest.main()

From efe23ef9c5abd0d24ca44371637d1055fc937b78 Mon Sep 17 00:00:00 2001
From: Joseph Mearman <joseph@mearman.co.uk>
Date: Tue, 20 Oct 2026 11:14:44 +0100
Subject: [PATCH 2/3] feat(cluster): start Colima at login on macOS hosts and
 check the runtime

A reboot leaves a Mac's container runtime stopped, so the node's k3s
container never comes back and a cluster that loses two such hosts loses
quorum. On a macOS host whose Docker context is Colima, the role now starts
the profile if it is stopped, installs a per-user launchd agent that starts
it at every login with a PATH naming both Homebrew prefixes, and loads the
agent into the connecting user's login session. Docker Desktop cannot be
started by the role, so there the start-at-login setting is documented.

The runtime tasks run before anything reads the daemon, and end checks after
the Compose project is started assert that the runtime answers and the
node's k3s container is running, so a converge of a rebooted host repairs it
or fails with a message that says what to do. Linux hosts are not touched,
and --check and --diff show what would change without starting anything.
github_runner_cluster_runtime_autostart turns the whole thing off.

The node's container name is now derived once as
github_runner_cluster_node_container and shared with the running-version
check.
---
 README.md                                     |   2 +-
 roles/github_runner_cluster/README.md         |  27 ++
 roles/github_runner_cluster/defaults/main.yml |  15 +
 .../tasks/end_checks.yml                      |  34 ++
 roles/github_runner_cluster/tasks/main.yml    |  13 +
 .../tasks/running_version.yml                 |   5 +-
 roles/github_runner_cluster/tasks/runtime.yml | 120 +++++
 .../tasks/runtime_probe.yml                   |  15 +
 .../templates/colima-launchd.plist.j2         |  33 ++
 tests/runtime_autostart/render_plist.yml      |  20 +
 tests/runtime_autostart/run.yml               |  20 +
 tests/unit/test_runtime_autostart.py          | 437 ++++++++++++++++++
 12 files changed, 736 insertions(+), 5 deletions(-)
 create mode 100644 roles/github_runner_cluster/tasks/end_checks.yml
 create mode 100644 roles/github_runner_cluster/tasks/runtime.yml
 create mode 100644 roles/github_runner_cluster/tasks/runtime_probe.yml
 create mode 100644 roles/github_runner_cluster/templates/colima-launchd.plist.j2
 create mode 100644 tests/runtime_autostart/render_plist.yml
 create mode 100644 tests/runtime_autostart/run.yml
 create mode 100644 tests/unit/test_runtime_autostart.py

diff --git a/README.md b/README.md
index 9937b52..ad6c1f3 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@
 
 There are two ways to deploy. A fleet's hosts are managed from a control machine with Ansible, from the fleet's own inventory (see [Ansible](#ansible) below). `bootstrap.sh`, described here, brings up a single machine from a checkout of this repository without a control node or inventory. It runs the same Ansible role against the machine itself, so both paths deploy identically.
 
-Prerequisites on the host: Docker (or Colima) with the Compose plugin, any release but 2.37.1 to 2.38.x (the cluster role refuses those; see Docker Compose versions in `roles/github_runner_cluster/README.md`), `python3`, `jq`, `openssl`, and `gh`. On macOS, the playbook installs `helm`, `kubectl` and Docker through Homebrew itself. Elsewhere, install `helm` and `kubectl` from the host's package manager first.
+Prerequisites on the host: Docker (or Colima) with the Compose plugin, any release but 2.37.1 to 2.38.x (the cluster role refuses those; see Docker Compose versions in `roles/github_runner_cluster/README.md`), `python3`, `jq`, `openssl`, and `gh`. On macOS, the playbook installs `helm`, `kubectl` and Docker through Homebrew itself, and the cluster role starts a Colima host's profile at every login and fails unless the runtime is up (Docker Desktop needs its own start-at-login setting; see Container runtime at login in `roles/github_runner_cluster/README.md`). Elsewhere, install `helm` and `kubectl` from the host's package manager first.
 
 1. **Create a GitHub App** on the organisation with **Self-hosted runners: read & write** permission, and install it on the organisation. `playbooks/github_app_setup.yml` does this through GitHub's manifest flow (see `roles/github_runner_arc/README.md`).
 2. **Configure the environment.** Copy `.env.bootstrap.example` to `.env.bootstrap` and fill in the following (the file's own comments cover the rest, such as joining an existing cluster or running as an agent):
diff --git a/roles/github_runner_cluster/README.md b/roles/github_runner_cluster/README.md
index f5ac7f4..8f2fe37 100644
--- a/roles/github_runner_cluster/README.md
+++ b/roles/github_runner_cluster/README.md
@@ -56,6 +56,30 @@ By default the role drives whichever Docker daemon the host's current Docker con
 
 Set `github_runner_cluster_docker_context` in the host's variables to pin the context by name (`colima` in that example) on any host with more than one engine. Every `community.docker` module call in the role then passes it as `cli_context`, and every `docker` command the role runs (Compose, `exec`, `inspect`, `volume`, image pulls, and the commands in `playbooks/recover_in_cluster_mesh.yml` and `playbooks/promote_headscale_standby.yml`) runs with `DOCKER_CONTEXT` set to it, so the modules and the CLI always reach the same daemon. The role checks the pin before it touches the host and fails if the context does not exist there, or if `DOCKER_HOST` is also set, since the two would name the daemon in conflicting ways. It never creates a context and never changes the host's current context; `docker context show` on the host reads the same before and after a run. The Headscale tasks that act on another host (the `headscale_hosted` server and standby, and the promotion playbook) use that host's own value. Run `docker context show` on each host to see what it currently points at before choosing a value.
 
+## Container runtime at login (macOS)
+
+On a Mac the container runtime is a Linux VM (Colima, or Docker Desktop) that stays stopped after a reboot until something starts it. The node's k3s container has `restart: unless-stopped`, so it comes back by itself once the runtime does, but a host whose runtime never starts never rejoins the cluster. With three servers, two such hosts leave the cluster without quorum and no runner pods anywhere. Only macOS hosts are affected by any of this: the role does nothing about the runtime on a Linux host, where Docker is a system service.
+
+Which runtime a Mac runs is taken from the Docker context the role drives (see [Docker contexts](#docker-contexts)): `colima`, or `colima-<profile>` for another profile, is Colima, and `desktop-linux` is Docker Desktop. `github_runner_cluster_runtime` says so explicitly for a host whose context does not tell, for example one that uses `DOCKER_HOST`, and `github_runner_cluster_colima_profile` names the profile to start when the context does not.
+
+**Colima.** With `github_runner_cluster_runtime_autostart` on (the default, which acts on Colima hosts only), the role:
+
+- starts the profile if it is stopped, with `colima start --profile <profile> --activate=false`, so the profile does not make its context the host's current one;
+- installs a launchd agent, `com.exadev.github-runner.colima.<profile>`, as `~/Library/LaunchAgents/<label>.plist` of the user Ansible connects to, which runs the same command at every login with a `PATH` that names both Homebrew prefixes (`github_runner_cluster_runtime_path`), since launchd gives an agent only the system `PATH` and Colima starts `limactl` and `docker` from the one it has; and
+- loads the agent into that user's login session. A user with no login session on the host (nobody has logged in at the console since the last boot) cannot have an agent loaded, so the role installs the file, says so, and leaves launchd to load it at the next login.
+
+The role never uses `become` for this: a LaunchAgent belongs to the user whose login session loads it, and Colima's VM runs as that user. Changing a definition unloads the agent before loading the new one; a rerun with nothing changed touches neither the agent nor the VM, and `--check --diff` shows the property list that would be written. With the variable off, the role installs nothing and leaves an agent from an earlier run as it is.
+
+A Mac still has to log in for the agent to run: a launch agent starts with the user's login session, not with the machine. A host that should recover from a reboot unattended needs automatic login for that user (System Settings > Users & Groups).
+
+**Docker Desktop.** The role cannot start Docker Desktop. Turn on Settings > General > Start Docker Desktop when you sign in to your computer on each such host (https://docs.docker.com/desktop/settings-and-maintenance/settings/), and give it the same automatic login. If it is not running when the role runs, the run fails with that message.
+
+**End checks.** On every macOS host the role checks, before anything reads the daemon and again after it has started the node's Compose project, that the runtime answers (`docker info` through the host's Docker context), and after starting the project that the node's k3s container (`github-runner-k3s`, or `github-runner-k3s-agent` on an agent) is running. A converge of a host that rebooted therefore repairs a stopped Colima or fails with a message that says what to do, and never reports success over a node that is not up. A `--check` run does not fail on a stopped runtime or container it has not started.
+
+A Colima VM that starts after a reboot is a restarted VM, so the `br_netfilter` note under Non-obvious behaviour in the repository README applies to it: pods can lose cluster service IPs until that module is loaded in the VM.
+
+This is the role's whole scope: it never moves a host between Colima and Docker Desktop.
+
 ## Mesh providers
 
 `github_runner_cluster_mesh` picks the provider. Each one lives in `tasks/mesh/<provider>.yml` and publishes the same facts, so nothing else in the role depends on which is in use:
@@ -138,6 +162,7 @@ Each site is its own cluster: its own inventory group, bootstrap server and mesh
 - `github_runner_cluster_node_taints`: Kubernetes taints (`key=value:Effect`, no spaces) the host's node registers with, empty by default. `NoSchedule` keeps pods without a matching toleration off it and `NoExecute` also evicts the ones already there. k3s applies them on every registration, so they come back if the node object is deleted, which a taint set with `kubectl` does not.
 - Per-host overrides: `github_runner_cluster_node_role` (`server` or `agent`), `github_runner_cluster_bootstrap` (true picks the bootstrap host, false excludes a host), `github_runner_cluster_server_url` (join this server instead, for a cluster whose servers are outside the inventory), `github_runner_cluster_tls_sans`, `github_runner_cluster_node_address`. The run fails if the result has an even number of servers, no servers, or more than one bootstrap host.
 - `github_runner_cluster_docker_context` (default empty): pins the Docker context this host's node runs in (see [Docker contexts](#docker-contexts)).
+- `github_runner_cluster_runtime_autostart` (default true), `github_runner_cluster_runtime` (default `auto`; `colima`, `docker_desktop` or `other`), `github_runner_cluster_colima_profile` (default empty, taken from the Docker context), `github_runner_cluster_runtime_path` (default both Homebrew prefixes and the system directories): on a macOS host, start Colima at login through a launchd agent and check the runtime (see [Container runtime at login](#container-runtime-at-login-macos)).
 - `github_runner_cluster_compose_files`: extra Compose files for the host's k3s project, merged after `docker-compose.yml`, as paths relative to `github_runner_cluster_dir` or absolute. Several nodes on one Docker host each need their own `github_runner_cluster_dir` and `github_runner_cluster_compose_project`.
 - `github_runner_cluster_wait_for_nodes`: wait for every node to be Ready afterwards, clearing stale node-password registrations if a node fails to rejoin (installs the kubernetes Python client through `github_runner_k8s_client`).
 
@@ -180,3 +205,5 @@ or read from 1Password by adding `exadev.github_runner.github_runner_secrets_one
 `tests/litestream/run.sh` runs the `headscale_hosted` provider with Litestream and a warm standby against an S3-compatible store on this machine's Docker, registers a real Tailscale client, promotes the standby and checks that users, nodes and pre-auth keys survive, that the client reconnects and that the promoted server keeps replicating. It also checks that `headscale_in_cluster` refuses to run without Litestream. `.github/workflows/litestream.yml` runs it on pull requests that touch the Headscale providers.
 
 `tests/mesh/run.sh` brings up three k3s nodes in Docker on one machine and joins them through Headscale with this role, for the `headscale_hosted` and `headscale_in_cluster` providers, and checks the `headscale_existing` policy check against a real server. Each cluster scenario runs the role a second time and fails if any node container restarted. The `compose_faulty` scenario checks the role refuses a Compose release that has that fault. With `GRTEST_PIN_CONTEXT=1` the cluster scenarios pin `github_runner_cluster_docker_context` while the current Docker context the playbooks see points at a socket that does not exist, so any docker call that ignored the pin fails, and they check the current context is unchanged afterwards; `tests/litestream/run.sh` takes the same setting for the Headscale hosts it delegates to and the promotion playbook. The `context_checks` scenario checks the role refuses a pinned context that does not exist, and one set alongside `DOCKER_HOST`, before writing anything. `.github/workflows/mesh-integration.yml` runs them on pull requests that touch the role, the hosted scenario on 2.39.0, the first fixed release, as well as on a current one.
+
+`tests/unit/test_runtime_autostart.py` covers the [container runtime tasks](#container-runtime-at-login-macos) without a Mac: it renders the launchd agent through `tests/runtime_autostart/render_plist.yml`, and runs `tasks/runtime.yml` and `tasks/end_checks.yml` through the role against stand-ins for `docker`, `colima`, `launchctl` and `plutil` on `PATH`. It checks the variable defaults, that Linux hosts are left alone, that a second run changes nothing, that `--check` writes and starts nothing, and that each way the runtime or the node's container can be down fails with its message. `tests/unit/test_container_runtime.py` covers the filter that works out the runtime from the Docker context. Nothing there touches a real Colima, launchd or Docker Desktop, so loading the agent into a real login session at a real reboot is the part only a run on a Mac can show.
diff --git a/roles/github_runner_cluster/defaults/main.yml b/roles/github_runner_cluster/defaults/main.yml
index c53e30b..dedb035 100644
--- a/roles/github_runner_cluster/defaults/main.yml
+++ b/roles/github_runner_cluster/defaults/main.yml
@@ -124,6 +124,21 @@ github_runner_cluster_compose_file_list: >-
 github_runner_cluster_docker_context: ""
 # The node's k3s container, as docker-compose.yml names it. The headscale_in_cluster provider runs commands inside it; override it only alongside an extra Compose file that renames the container.
 github_runner_cluster_container_name: github-runner-k3s
+# The node's k3s container as this host runs it: the server's, or the agent's, which docker-compose.yml names differently. Derived, never set directly.
+github_runner_cluster_node_container: "{{ github_runner_cluster_container_name if github_runner_cluster_effective_node_role == 'server' else 'github-runner-k3s-agent' }}"
+
+# macOS hosts only (Linux hosts are never touched): whether the role makes the container runtime come back after a reboot. On a Colima host it installs a per-user launchd agent that starts the Colima profile at login, loads it, and starts the profile at once if it is stopped. true (the default) does that for Colima hosts and nothing for the others: the role cannot start Docker Desktop, whose start-at-login setting is documented in the README. false installs nothing and leaves an agent from an earlier run as it is. Either way the end checks fail unless the runtime is up and the node's container is running.
+github_runner_cluster_runtime_autostart: true
+# Which container runtime a macOS host runs: auto takes it from the Docker context the role drives (colima or colima-<profile> is Colima, desktop-linux is Docker Desktop, anything else is other), colima, docker_desktop and other say so for a host whose context does not tell (DOCKER_HOST set, a context with another name).
+github_runner_cluster_runtime: auto
+# The Colima profile to start. Empty takes it from the Docker context (colima is the default profile, colima-<profile> another) and falls back to the default profile when the context names none.
+github_runner_cluster_colima_profile: ""
+# The PATH the agent runs colima with, and the role runs colima and docker with on a macOS host: both Homebrew prefixes (Apple Silicon and Intel), since launchd gives an agent only the system PATH and colima starts limactl and docker from the one it is given.
+github_runner_cluster_runtime_path: "/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin"
+# Derived, never set directly: the agent's launchd label, one per Colima profile.
+github_runner_cluster_runtime_launchd_label: "com.exadev.github-runner.colima.{{ github_runner_cluster_effective_runtime.colima_profile }}"
+# Derived, never set directly: where the agent's property list lives, in the connecting user's own LaunchAgents directory.
+github_runner_cluster_runtime_agent_plist: "{{ ansible_facts['env']['HOME'] }}/Library/LaunchAgents/{{ github_runner_cluster_runtime_launchd_label }}.plist"
 
 # The directory on the target host the role manages as this host's Compose project: it copies the collection's docker-compose.yml and k3s/ build context there, templates .env there, and k3s writes the kubeconfig to its kubeconfig/ subdirectory. Needs no checkout of anything on the host. The default reads HOME from the target's gathered facts, so it is the connecting user's home on that host, not the control node's.
 github_runner_cluster_dir: "{{ ansible_facts['env']['HOME'] }}/{{ github_runner_cluster_dir_name }}"
diff --git a/roles/github_runner_cluster/tasks/end_checks.yml b/roles/github_runner_cluster/tasks/end_checks.yml
new file mode 100644
index 0000000..b37784b
--- /dev/null
+++ b/roles/github_runner_cluster/tasks/end_checks.yml
@@ -0,0 +1,34 @@
+---
+# macOS hosts only. The checks that close a run on a host that reboots: the container runtime answers and the node's k3s container is running, so a converge that leaves either down fails here instead of reporting success. Needs runtime.yml to have run, and goes after the Compose project is started.
+
+- name: Read whether the container runtime is up
+  ansible.builtin.include_tasks: runtime_probe.yml
+
+- name: Fail unless the container runtime is up
+  ansible.builtin.fail:
+    msg: "{{ github_runner_cluster_runtime_down_message }}"
+  when:
+    - not github_runner_cluster_runtime_up | bool
+    - not ansible_check_mode
+
+- name: Read the state of this node's k3s container
+  # docker ps rather than docker inspect, so that a container that does not exist reads as no state at all and fails below with the message, not with docker's own.
+  ansible.builtin.command:
+    argv: [docker, ps, --all, --filter, "name=^/{{ github_runner_cluster_node_container }}$", --format, "{{ '{{' }}.State{{ '}}' }}"]
+  environment: "{{ github_runner_cluster_runtime_environment }}"
+  register: github_runner_cluster_node_container_state
+  changed_when: false
+  check_mode: false
+  # Not answering is a failure above, except under --check, where a runtime this run would have started is still down.
+  when: github_runner_cluster_runtime_up | bool
+
+- name: Fail unless this node's k3s container is running
+  ansible.builtin.fail:
+    msg: >-
+      The k3s container {{ github_runner_cluster_node_container }} on {{ inventory_hostname }} is not running (its state is
+      {{ github_runner_cluster_node_container_state.stdout | trim | default('absent', true) }}). Read its output with
+      `docker logs {{ github_runner_cluster_node_container }}` on the host.
+  when:
+    - github_runner_cluster_runtime_up | bool
+    - github_runner_cluster_node_container_state.stdout | trim != 'running'
+    - not ansible_check_mode
diff --git a/roles/github_runner_cluster/tasks/main.yml b/roles/github_runner_cluster/tasks/main.yml
index 2d57220..a3e1c8c 100644
--- a/roles/github_runner_cluster/tasks/main.yml
+++ b/roles/github_runner_cluster/tasks/main.yml
@@ -5,6 +5,11 @@
   # First, so that a pinned context that does not exist, or one set alongside DOCKER_HOST, stops the run before anything touches the host.
   ansible.builtin.include_tasks: docker_context.yml
 
+- name: Make the container runtime come back after a reboot, and check it is up
+  # macOS only: the runtime is Colima or Docker Desktop there, a Linux VM that stays stopped after a reboot until something starts it, while Linux hosts run Docker as a system service. Before anything reads the daemon, since the version checks below fail on one that is down. See tasks/runtime.yml.
+  ansible.builtin.include_tasks: runtime.yml
+  when: ansible_facts['os_family'] == 'Darwin'
+
 - name: Read this host's Docker Compose version
   # Before anything that runs Compose (the mesh providers start Compose projects too), for the check below. The CLI plugin's own version, which no Docker context or daemon changes; it still runs with the pinned context, like every docker command in the role. Read-only, so it runs under --check as well.
   ansible.builtin.command: docker compose version --short
@@ -108,6 +113,10 @@
         files: "{{ github_runner_cluster_compose_file_list if github_runner_cluster_compose_file_list | length > 1 else omit }}"
         state: present
 
+    - name: Check the runtime and this node's container are up
+      ansible.builtin.include_tasks: end_checks.yml
+      when: ansible_facts['os_family'] == 'Darwin'
+
 - name: Join as a k3s agent
   when: github_runner_cluster_effective_node_role == "agent"
   block:
@@ -127,6 +136,10 @@
         files: "{{ github_runner_cluster_compose_file_list if github_runner_cluster_compose_file_list | length > 1 else omit }}"
         state: present
 
+    - name: Check the runtime and this node's container are up
+      ansible.builtin.include_tasks: end_checks.yml
+      when: ansible_facts['os_family'] == 'Darwin'
+
     - name: End the role here, since an agent host has no API of its own to wait on
       ansible.builtin.meta: end_role
 
diff --git a/roles/github_runner_cluster/tasks/running_version.yml b/roles/github_runner_cluster/tasks/running_version.yml
index 47d08fd..42a0d20 100644
--- a/roles/github_runner_cluster/tasks/running_version.yml
+++ b/roles/github_runner_cluster/tasks/running_version.yml
@@ -16,10 +16,7 @@
     if [ "$state" = running ]; then
       docker exec "$container" k3s --version
     fi
-  environment: "{{ github_runner_cluster_docker_cli_environment | combine({'container': github_runner_cluster_running_container}) }}"
-  vars:
-    github_runner_cluster_running_container: >-
-      {{ github_runner_cluster_container_name if github_runner_cluster_effective_node_role == 'server' else 'github-runner-k3s-agent' }}
+  environment: "{{ github_runner_cluster_docker_cli_environment | combine({'container': github_runner_cluster_node_container}) }}"
   register: github_runner_cluster_running_own
   changed_when: false
   check_mode: false
diff --git a/roles/github_runner_cluster/tasks/runtime.yml b/roles/github_runner_cluster/tasks/runtime.yml
new file mode 100644
index 0000000..6467b77
--- /dev/null
+++ b/roles/github_runner_cluster/tasks/runtime.yml
@@ -0,0 +1,120 @@
+---
+# macOS hosts only (main.yml includes it nowhere else). Makes the container runtime come back after a reboot, and stops the run, with a message that says what to do, when the runtime is not up. The node's own container already restarts with the runtime (restart: unless-stopped in docker-compose.yml), so the runtime is the only thing a reboot leaves stopped.
+#
+# On a Colima host with github_runner_cluster_runtime_autostart on, it starts the profile if it is stopped, installs a per-user launchd agent that starts it at every login (a property list in the connecting user's ~/Library/LaunchAgents) and loads that agent into the user's login session. Docker Desktop cannot be started by the role, so there it only checks. The agent runs as the connecting user and the role never uses become for it, since a LaunchAgent belongs to the user whose login session loads it.
+#
+# Publishes github_runner_cluster_effective_runtime ({kind, colima_profile}), github_runner_cluster_runtime_environment (what docker and colima run with), github_runner_cluster_runtime_down_message and github_runner_cluster_runtime_up, for end_checks.yml.
+
+- name: Work out which container runtime this host runs
+  ansible.builtin.set_fact:
+    github_runner_cluster_effective_runtime: >-
+      {{ github_runner_cluster_docker_cli_context
+         | exadev.github_runner.cluster_container_runtime(github_runner_cluster_runtime, github_runner_cluster_colima_profile) }}
+
+- name: Publish the environment and the failure message the runtime tasks use
+  ansible.builtin.set_fact:
+    # The PATH is what the agent gets too, so a run that works here is the run the agent repeats at login.
+    github_runner_cluster_runtime_environment: >-
+      {{ github_runner_cluster_docker_cli_environment | combine({'PATH': github_runner_cluster_runtime_path}) }}
+    github_runner_cluster_runtime_down_message: >-
+      {{
+        {
+          'colima': 'Colima profile ' ~ github_runner_cluster_effective_runtime.colima_profile ~ ' is not running on ' ~ inventory_hostname ~ '. Start it with `colima start --profile ' ~ github_runner_cluster_effective_runtime.colima_profile ~ '`, or leave github_runner_cluster_runtime_autostart on so this role starts it and keeps it starting at login.',
+          'docker_desktop': 'Docker Desktop is not running on ' ~ inventory_hostname ~ ', and this role cannot start it. Open Docker Desktop, and turn on Settings > General > Start Docker Desktop when you sign in to your computer so that it comes back after a reboot.',
+          'other': 'The container runtime is not running on ' ~ inventory_hostname ~ ' (`docker info` failed). Start it, and set it to start at login so that it comes back after a reboot.'
+        }[github_runner_cluster_effective_runtime.kind]
+      }}
+
+- name: Read whether the container runtime is up
+  ansible.builtin.include_tasks: runtime_probe.yml
+
+- name: Keep a Colima profile running across reboots
+  when:
+    - github_runner_cluster_effective_runtime.kind == 'colima'
+    - github_runner_cluster_runtime_autostart | bool
+  block:
+    - name: Start the Colima profile if it is stopped
+      # --activate=false keeps the profile from making its Docker context the host's current one, which the role promises never to change (see Docker contexts in the README). Starting a profile that already runs would do nothing, but this only runs when the runtime did not answer. Skipped under --check, which reports the start as skipped, not as a failure.
+      ansible.builtin.command:
+        argv: [colima, start, --profile, "{{ github_runner_cluster_effective_runtime.colima_profile }}", --activate=false]
+      environment: "{{ github_runner_cluster_runtime_environment }}"
+      changed_when: true
+      when: not github_runner_cluster_runtime_up | bool
+
+    - name: Create the connecting user's LaunchAgents directory
+      ansible.builtin.file:
+        path: "{{ ansible_facts['env']['HOME'] }}/Library/LaunchAgents"
+        state: directory
+        mode: "0755"
+
+    - name: Install the launchd agent that starts the Colima profile at login
+      # The label is per profile, so two profiles on one host get two agents. plutil rejects a malformed property list before it replaces the installed one, since launchd would otherwise fail to load the agent at the next login with nobody watching. The task's environment gives plutil the same PATH as the agent.
+      ansible.builtin.template:
+        src: colima-launchd.plist.j2
+        dest: "{{ github_runner_cluster_runtime_agent_plist }}"
+        mode: "0644"
+        validate: plutil -lint %s
+      environment: "{{ github_runner_cluster_runtime_environment }}"
+      register: github_runner_cluster_runtime_agent
+
+    - name: Read whether the user has a login session to load the agent into
+      # gui/<uid> exists only while that user is logged in at the console. Without it the agent cannot be loaded now, and launchd loads it at the next login, which is all it is for.
+      ansible.builtin.command:
+        argv: [launchctl, print, "gui/{{ ansible_facts['user_uid'] }}"]
+      environment: "{{ github_runner_cluster_runtime_environment }}"
+      register: github_runner_cluster_runtime_session
+      changed_when: false
+      failed_when: false
+      check_mode: false
+
+    - name: Read whether the agent is loaded
+      ansible.builtin.command:
+        argv: [launchctl, print, "gui/{{ ansible_facts['user_uid'] }}/{{ github_runner_cluster_runtime_launchd_label }}"]
+      environment: "{{ github_runner_cluster_runtime_environment }}"
+      register: github_runner_cluster_runtime_loaded
+      changed_when: false
+      failed_when: false
+      check_mode: false
+
+    - name: Unload the agent so that its new definition is read
+      # launchd keeps the definition it loaded, whatever the file says now.
+      ansible.builtin.command:
+        argv: [launchctl, bootout, "gui/{{ ansible_facts['user_uid'] }}/{{ github_runner_cluster_runtime_launchd_label }}"]
+      environment: "{{ github_runner_cluster_runtime_environment }}"
+      changed_when: true
+      when:
+        - github_runner_cluster_runtime_agent is changed
+        - github_runner_cluster_runtime_session.rc == 0
+        - github_runner_cluster_runtime_loaded.rc == 0
+
+    - name: Load the agent into the user's login session
+      # Loading runs it once (RunAtLoad), which finds the profile already started above and does nothing.
+      ansible.builtin.command:
+        argv:
+          - launchctl
+          - bootstrap
+          - "gui/{{ ansible_facts['user_uid'] }}"
+          - "{{ github_runner_cluster_runtime_agent_plist }}"
+      environment: "{{ github_runner_cluster_runtime_environment }}"
+      changed_when: true
+      when:
+        - github_runner_cluster_runtime_session.rc == 0
+        - github_runner_cluster_runtime_loaded.rc != 0 or github_runner_cluster_runtime_agent is changed
+
+    - name: Say that the agent waits for the next login
+      ansible.builtin.debug:
+        msg: >-
+          The connecting user has no login session on {{ inventory_hostname }}, so launchd cannot load
+          {{ github_runner_cluster_runtime_launchd_label }} now. It is installed and loads at the next login.
+      when: github_runner_cluster_runtime_session.rc != 0
+
+    - name: Read whether the container runtime is up now
+      ansible.builtin.include_tasks: runtime_probe.yml
+
+- name: Fail unless the container runtime is up
+  # Not under --check: a check run that would have started the runtime has not started it, so the runtime still being down is no verdict on the host.
+  ansible.builtin.fail:
+    msg: "{{ github_runner_cluster_runtime_down_message }}"
+  when:
+    - not github_runner_cluster_runtime_up | bool
+    - not ansible_check_mode
diff --git a/roles/github_runner_cluster/tasks/runtime_probe.yml b/roles/github_runner_cluster/tasks/runtime_probe.yml
new file mode 100644
index 0000000..92ec41b
--- /dev/null
+++ b/roles/github_runner_cluster/tasks/runtime_probe.yml
@@ -0,0 +1,15 @@
+---
+# Reads whether the container runtime this host's Docker context points at answers, and publishes github_runner_cluster_runtime_up. Read-only, so it runs under --check too. Needs github_runner_cluster_runtime_environment from runtime.yml. A daemon that is down is an answer here, not a failure: the callers decide what to do about it.
+
+- name: Read whether the container runtime answers
+  ansible.builtin.command:
+    argv: [docker, info, --format, "{{ '{{' }}.ServerVersion{{ '}}' }}"]
+  environment: "{{ github_runner_cluster_runtime_environment }}"
+  register: github_runner_cluster_runtime_probe
+  changed_when: false
+  failed_when: false
+  check_mode: false
+
+- name: Publish whether the container runtime answers
+  ansible.builtin.set_fact:
+    github_runner_cluster_runtime_up: "{{ github_runner_cluster_runtime_probe.rc == 0 }}"
diff --git a/roles/github_runner_cluster/templates/colima-launchd.plist.j2 b/roles/github_runner_cluster/templates/colima-launchd.plist.j2
new file mode 100644
index 0000000..673b246
--- /dev/null
+++ b/roles/github_runner_cluster/templates/colima-launchd.plist.j2
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!-- Managed by the github_runner_cluster role of the exadev.github_runner collection: changes are overwritten on its next run. Starts the Colima profile at login; starting a profile that already runs does nothing. -->
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>{{ github_runner_cluster_runtime_launchd_label | e }}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/bin/env</string>
+    <string>colima</string>
+    <string>start</string>
+    <string>--profile</string>
+    <string>{{ github_runner_cluster_effective_runtime.colima_profile | e }}</string>
+    <string>--activate=false</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>{{ github_runner_cluster_runtime_path | e }}</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>AbandonProcessGroup</key>
+  <true/>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <key>StandardOutPath</key>
+  <string>{{ ansible_facts['env']['HOME'] | e }}/Library/Logs/{{ github_runner_cluster_runtime_launchd_label | e }}.log</string>
+  <key>StandardErrorPath</key>
+  <string>{{ ansible_facts['env']['HOME'] | e }}/Library/Logs/{{ github_runner_cluster_runtime_launchd_label | e }}.log</string>
+</dict>
+</plist>
diff --git a/tests/runtime_autostart/render_plist.yml b/tests/runtime_autostart/render_plist.yml
new file mode 100644
index 0000000..0ba1bf9
--- /dev/null
+++ b/tests/runtime_autostart/render_plist.yml
@@ -0,0 +1,20 @@
+# Renders the cluster role's launchd agent for a Colima profile (templates/colima-launchd.plist.j2) with the role's defaults, the runtime the role works out from a Docker context, and a home directory, writing it to plist_output, for tests/unit/test_runtime_autostart.py. Role variables are passed as extra variables, which outrank the defaults file loaded here.
+- name: Render the Colima launchd agent
+  hosts: localhost
+  connection: local
+  gather_facts: false
+  vars_files:
+    - ../../roles/github_runner_cluster/defaults/main.yml
+  vars:
+    docker_context: colima
+    ansible_facts:
+      env:
+        HOME: /Users/example
+    github_runner_cluster_effective_runtime: >-
+      {{ docker_context | exadev.github_runner.cluster_container_runtime(github_runner_cluster_runtime, github_runner_cluster_colima_profile) }}
+  tasks:
+    - name: Write the property list
+      ansible.builtin.copy:
+        content: "{{ lookup('ansible.builtin.template', playbook_dir ~ '/../../roles/github_runner_cluster/templates/colima-launchd.plist.j2') }}"
+        dest: "{{ plist_output }}"
+        mode: "0644"
diff --git a/tests/runtime_autostart/run.yml b/tests/runtime_autostart/run.yml
new file mode 100644
index 0000000..f8f5ad3
--- /dev/null
+++ b/tests/runtime_autostart/run.yml
@@ -0,0 +1,20 @@
+# Runs the cluster role's runtime tasks (runtime.yml, then end_checks.yml, or one of them) through the role itself, as tasks/main.yml includes them on a macOS host, for tests/unit/test_runtime_autostart.py. The host's facts are stood in for by extra variables (runtime_os_family, runtime_uid, runtime_home), and the docker, colima, launchctl and plutil it calls are the test's stubs on PATH. The condition is the one tasks/main.yml puts on both includes, which the test checks is still there.
+- name: Run the cluster role's runtime tasks
+  hosts: all
+  connection: local
+  gather_facts: false
+  tasks:
+    - name: Stand in for the host's facts
+      ansible.builtin.set_fact:
+        ansible_facts:
+          os_family: "{{ runtime_os_family }}"
+          user_uid: "{{ runtime_uid }}"
+          env:
+            HOME: "{{ runtime_home }}"
+
+    - name: Include the role's tasks
+      ansible.builtin.include_role:
+        name: exadev.github_runner.github_runner_cluster
+        tasks_from: "{{ item }}"
+      loop: "{{ (runtime_tasks | default('runtime,end_checks')).split(',') | map('regex_replace', '$', '.yml') | list }}"
+      when: ansible_facts['os_family'] == 'Darwin'
diff --git a/tests/unit/test_runtime_autostart.py b/tests/unit/test_runtime_autostart.py
new file mode 100644
index 0000000..983113c
--- /dev/null
+++ b/tests/unit/test_runtime_autostart.py
@@ -0,0 +1,437 @@
+"""Tests for how the cluster role keeps a macOS host's container runtime running across reboots: the launchd agent template (tests/runtime_autostart/render_plist.yml), the variable defaults, the macOS-only guard in tasks/main.yml, and tasks/runtime.yml and tasks/end_checks.yml run through the role (tests/runtime_autostart/run.yml) against stand-ins for docker, colima, launchctl and plutil."""
+
+from __future__ import annotations
+
+import json
+import os
+import plistlib
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[2]
+ROLE = ROOT / "roles" / "github_runner_cluster"
+RENDER = ROOT / "tests" / "runtime_autostart" / "render_plist.yml"
+RUN = ROOT / "tests" / "runtime_autostart" / "run.yml"
+ANSIBLE_PLAYBOOK = os.environ.get("ANSIBLE_PLAYBOOK", "ansible-playbook")
+DEFAULTS: dict[str, Any] = yaml.safe_load((ROLE / "defaults" / "main.yml").read_text())
+UID = 501
+HOME = "/Users/example"
+DARWIN_ONLY = "ansible_facts['os_family'] == 'Darwin'"
+
+
+def ansible_env() -> dict[str, str]:
+    return {**os.environ, "ANSIBLE_COLLECTIONS_PATH": str(ROOT / "playbooks" / "collections"), "ANSIBLE_LOCALHOST_WARNING": "false", "ANSIBLE_INVENTORY_UNPARSED_WARNING": "false", "ANSIBLE_RETRY_FILES_ENABLED": "false"}
+
+
+def render_plist(**role_vars: Any) -> bytes:
+    """Render the launchd agent with ansible-playbook and return the property list."""
+    with tempfile.TemporaryDirectory() as work:
+        output = Path(work) / "agent.plist"
+        extra = Path(work) / "extra.json"
+        extra.write_text(json.dumps({"plist_output": str(output), **role_vars}))
+        subprocess.run([ANSIBLE_PLAYBOOK, str(RENDER), "-e", f"@{extra}"], check=True, env=ansible_env(), cwd=work, capture_output=True, text=True)
+        return output.read_bytes()
+
+
+class DefaultsTest(unittest.TestCase):
+    def test_the_autostart_is_on_and_the_runtime_is_taken_from_the_docker_context(self) -> None:
+        self.assertIs(DEFAULTS["github_runner_cluster_runtime_autostart"], True)
+        self.assertEqual(DEFAULTS["github_runner_cluster_runtime"], "auto")
+        self.assertEqual(DEFAULTS["github_runner_cluster_colima_profile"], "")
+
+    def test_the_path_names_both_homebrew_prefixes_and_the_system_directories(self) -> None:
+        entries = DEFAULTS["github_runner_cluster_runtime_path"].split(":")
+        for prefix in ("/opt/homebrew", "/usr/local"):
+            self.assertIn(f"{prefix}/bin", entries)
+            self.assertIn(f"{prefix}/sbin", entries)
+        for system in ("/usr/bin", "/bin", "/usr/sbin", "/sbin"):
+            self.assertIn(system, entries)
+
+    def test_the_agent_is_per_profile_and_lives_in_the_connecting_users_launch_agents(self) -> None:
+        self.assertIn("{{ github_runner_cluster_effective_runtime.colima_profile }}", DEFAULTS["github_runner_cluster_runtime_launchd_label"])
+        plist = DEFAULTS["github_runner_cluster_runtime_agent_plist"]
+        self.assertTrue(plist.startswith("{{ ansible_facts['env']['HOME'] }}/Library/LaunchAgents/"))
+        self.assertTrue(plist.endswith("{{ github_runner_cluster_runtime_launchd_label }}.plist"))
+
+    def test_the_node_container_follows_the_node_s_role(self) -> None:
+        template = DEFAULTS["github_runner_cluster_node_container"]
+        self.assertIn("github_runner_cluster_container_name", template)
+        self.assertIn("'github-runner-k3s-agent'", template)
+
+    def test_every_new_variable_is_in_the_readme(self) -> None:
+        readme = (ROLE / "README.md").read_text()
+        for name in ("github_runner_cluster_runtime_autostart", "github_runner_cluster_runtime", "github_runner_cluster_colima_profile", "github_runner_cluster_runtime_path"):
+            with self.subTest(name=name):
+                self.assertIn(f"`{name}`", readme)
+
+
+class GuardTest(unittest.TestCase):
+    def test_both_includes_run_on_macos_only(self) -> None:
+        tasks = yaml.safe_load((ROLE / "tasks" / "main.yml").read_text())
+        blocks = [task for task in tasks if "block" in task]
+        everything = tasks + [inner for block in blocks for inner in block["block"]]
+        for tasks_file in ("runtime.yml", "end_checks.yml"):
+            includes = [task for task in everything if task.get("ansible.builtin.include_tasks") == tasks_file]
+            with self.subTest(tasks_file=tasks_file):
+                self.assertTrue(includes)
+                for include in includes:
+                    self.assertEqual(include["when"], DARWIN_ONLY)
+
+    def test_the_runtime_is_up_before_anything_reads_the_daemon(self) -> None:
+        tasks = yaml.safe_load((ROLE / "tasks" / "main.yml").read_text())
+        order = [task.get("ansible.builtin.include_tasks") or task.get("ansible.builtin.command") for task in tasks]
+        self.assertLess(order.index("runtime.yml"), order.index("versions.yml"))
+        self.assertLess(order.index("runtime.yml"), order.index("running_version.yml"))
+        self.assertLess(order.index("docker_context.yml"), order.index("runtime.yml"))
+
+    def test_the_end_checks_follow_the_compose_start_on_servers_and_agents(self) -> None:
+        tasks = yaml.safe_load((ROLE / "tasks" / "main.yml").read_text())
+        for role in ("server", "agent"):
+            [block] = [task for task in tasks if "block" in task and task.get("when") == f'github_runner_cluster_effective_node_role == "{role}"']
+            steps = [step.get("ansible.builtin.include_tasks") or ("compose" if "community.docker.docker_compose_v2" in step else None) for step in block["block"]]
+            with self.subTest(role=role):
+                self.assertLess(steps.index("compose"), steps.index("end_checks.yml"))
+
+
+class PlistTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.document = render_plist()
+        cls.plist = plistlib.loads(cls.document)
+
+    def test_it_starts_the_default_profile_without_changing_the_current_docker_context(self) -> None:
+        self.assertEqual(self.plist["ProgramArguments"], ["/usr/bin/env", "colima", "start", "--profile", "default", "--activate=false"])
+
+    def test_it_runs_once_at_login(self) -> None:
+        self.assertIs(self.plist["RunAtLoad"], True)
+        self.assertNotIn("KeepAlive", self.plist)
+
+    def test_the_vm_outlives_the_job_that_started_it(self) -> None:
+        # colima start returns once the VM is up, leaving lima's host agent running; launchd kills what a finished job leaves in its process group unless told to abandon it.
+        self.assertIs(self.plist["AbandonProcessGroup"], True)
+
+    def test_the_path_is_the_roles_with_both_homebrew_prefixes(self) -> None:
+        self.assertEqual(self.plist["EnvironmentVariables"], {"PATH": DEFAULTS["github_runner_cluster_runtime_path"]})
+
+    def test_the_label_names_the_profile_and_the_log_is_in_the_users_logs(self) -> None:
+        self.assertEqual(self.plist["Label"], "com.exadev.github-runner.colima.default")
+        self.assertEqual(self.plist["StandardOutPath"], f"{HOME}/Library/Logs/com.exadev.github-runner.colima.default.log")
+        self.assertEqual(self.plist["StandardErrorPath"], self.plist["StandardOutPath"])
+
+    def test_another_profile_gets_its_own_label_and_argument(self) -> None:
+        plist = plistlib.loads(render_plist(docker_context="colima-example"))
+        self.assertEqual(plist["Label"], "com.exadev.github-runner.colima.example")
+        self.assertEqual(plist["ProgramArguments"][3:5], ["--profile", "example"])
+
+    def test_a_profile_set_for_a_context_that_does_not_say_is_used(self) -> None:
+        plist = plistlib.loads(render_plist(docker_context="", github_runner_cluster_runtime="colima", github_runner_cluster_colima_profile="build"))
+        self.assertEqual((plist["Label"], plist["ProgramArguments"][4]), ("com.exadev.github-runner.colima.build", "build"))
+
+    def test_a_path_with_markup_characters_is_escaped_not_injected(self) -> None:
+        path = "/opt/a&b:/opt/<c>:/usr/bin"
+        document = render_plist(github_runner_cluster_runtime_path=path)
+        self.assertEqual(plistlib.loads(document)["EnvironmentVariables"]["PATH"], path)
+        self.assertNotIn(b"a&b", document)
+
+    @unittest.skipUnless(shutil.which("plutil"), "plutil is not installed")
+    def test_plutil_accepts_it(self) -> None:
+        with tempfile.NamedTemporaryFile(suffix=".plist") as handle:
+            handle.write(self.document)
+            handle.flush()
+            result = subprocess.run(["plutil", "-lint", handle.name], capture_output=True, text=True, check=False)
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+
+    def test_the_comment_cannot_end_the_document_early(self) -> None:
+        # A double hyphen inside an XML comment is not well formed.
+        comment = re.search(rb"<!--(.*?)-->", self.document, re.DOTALL)
+        assert comment is not None
+        self.assertNotIn(b"--", comment.group(1))
+
+
+# Stands in for docker, colima, launchctl and plutil, which are all this one script under four names. State is files in $RUNTIME_STUB: runtime-up (the Docker daemon answers), session (the user has a login session), loaded (the agent is loaded), <container>.state (what docker ps prints), colima-start-fails; every call is appended to calls.log with the Docker context it ran with.
+STUB = """#!{python}
+import os, sys
+stub = os.environ["RUNTIME_STUB"]
+name = os.path.basename(sys.argv[0])
+args = sys.argv[1:]
+with open(os.path.join(stub, "calls.log"), "a") as log:
+    log.write(os.environ.get("DOCKER_CONTEXT", "-") + " " + name + " " + " ".join(args) + "\\n")
+def exists(file):
+    return os.path.exists(os.path.join(stub, file))
+def touch(file):
+    open(os.path.join(stub, file), "w").close()
+if name == "docker":
+    if not exists("runtime-up"):
+        sys.exit("Cannot connect to the Docker daemon")
+    if args[0] == "info":
+        print("27.0.0")
+    elif args[0] == "ps":
+        container = args[args.index("--filter") + 1].removeprefix("name=^/").removesuffix("$")
+        if exists(container + ".state"):
+            print(open(os.path.join(stub, container + ".state")).read(), end="")
+    else:
+        sys.exit("unexpected docker call: " + " ".join(args))
+elif name == "colima":
+    if args[0] != "start" or args[-1] != "--activate=false":
+        sys.exit("unexpected colima call: " + " ".join(args))
+    if exists("colima-start-fails"):
+        sys.exit("colima: the VM did not start")
+    touch("runtime-up")
+elif name == "launchctl":
+    if args[0] == "print":
+        sys.exit(0 if exists("loaded" if args[1].count("/") == 2 else "session") else 113)
+    elif args[0] == "bootstrap":
+        if not os.path.exists(args[2]):
+            sys.exit("Bootstrap failed: no such plist")
+        touch("loaded")
+    elif args[0] == "bootout":
+        os.remove(os.path.join(stub, "loaded"))
+    else:
+        sys.exit("unexpected launchctl call: " + " ".join(args))
+elif name == "plutil":
+    if args[0] != "-lint" or b"<plist" not in open(args[1], "rb").read():
+        sys.exit("plutil: not a property list")
+else:
+    sys.exit("unexpected stand-in: " + name)
+"""
+
+
+def failed_task(stdout: str) -> str | None:
+    """Return the name of the task whose header last precedes a "fatal:" line in ansible-playbook's output, or None when nothing failed."""
+    task = None
+    for line in stdout.splitlines():
+        header = re.match(r"TASK \[(?:[^:\]]+ : )?(.*)\] \*+$", line)
+        if header:
+            task = header.group(1)
+        elif line.startswith("fatal: "):
+            return task
+    return None
+
+
+@unittest.skipIf(shutil.which(ANSIBLE_PLAYBOOK) is None, "ansible-playbook is not installed")
+class RoleTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.work = Path(tempfile.mkdtemp())
+        self.addCleanup(shutil.rmtree, self.work)
+        self.stub = self.work / "stub"
+        self.home = self.work / "home"
+        self.stub.mkdir()
+        self.home.mkdir()
+        self.bin = self.work / "bin"
+        self.bin.mkdir()
+        for name in ("docker", "colima", "launchctl", "plutil"):
+            tool = self.bin / name
+            tool.write_text(STUB.format(python=sys.executable))
+            tool.chmod(0o755)
+        self.plist = self.home / "Library" / "LaunchAgents" / "com.exadev.github-runner.colima.default.plist"
+        # What `docker ps` prints for the node's container once the runtime answers; the end checks need it running.
+        (self.stub / "github-runner-k3s.state").write_text("running")
+
+    def state(self, *flags: str) -> None:
+        for flag in flags:
+            (self.stub / flag).write_text("")
+
+    def run_role(self, *extra: str, tasks: str = "runtime,end_checks", context: str = "colima", os_family: str = "Darwin", **variables: Any) -> subprocess.CompletedProcess[str]:
+        host = {
+            "runtime_os_family": os_family,
+            "runtime_uid": UID,
+            "runtime_home": str(self.home),
+            "runtime_tasks": tasks,
+            "github_runner_cluster_docker_cli_context": context,
+            "github_runner_cluster_docker_cli_environment": {"DOCKER_CONTEXT": context} if context else {},
+            "github_runner_cluster_effective_node_role": "server",
+            "github_runner_cluster_runtime_path": f"{self.bin}{os.pathsep}/usr/bin{os.pathsep}/bin",
+            **variables,
+        }
+        inventory = self.work / "inventory.yml"
+        inventory.write_text(yaml.safe_dump({"all": {"hosts": {"node1": host}}}))
+        # The stand-ins come first on the playbook's own PATH as well as the tasks', so a tool a task runs without the role's PATH still cannot reach this machine's real launchd, Colima or Docker.
+        env = ansible_env() | {"RUNTIME_STUB": str(self.stub), "PATH": f"{self.bin}{os.pathsep}{os.environ['PATH']}"}
+        return subprocess.run([ANSIBLE_PLAYBOOK, "-i", str(inventory), str(RUN), *extra], capture_output=True, text=True, check=False, env=env, cwd=self.work)
+
+    def calls(self) -> list[str]:
+        log = self.stub / "calls.log"
+        return log.read_text().splitlines() if log.exists() else []
+
+    def changes(self) -> list[str]:
+        return [call for call in self.calls() if re.match(r"\S+ (colima|launchctl (bootstrap|bootout))", call)]
+
+    def recap(self, result: subprocess.CompletedProcess[str]) -> dict[str, int]:
+        match = re.search(r"node1\s+: ok=(\d+)\s+changed=(\d+)\s+unreachable=(\d+)\s+failed=(\d+)", result.stdout)
+        assert match is not None, result.stdout + result.stderr
+        return dict(zip(("ok", "changed", "unreachable", "failed"), map(int, match.groups())))
+
+    def test_a_stopped_colima_is_started_and_the_agent_installed_and_loaded(self) -> None:
+        self.state("session")
+        result = self.run_role()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual(self.changes(), ["colima colima start --profile default --activate=false".replace("colima colima", "colima colima"), f"colima launchctl bootstrap gui/{UID} {self.plist}"])
+        self.assertEqual(plistlib.loads(self.plist.read_bytes())["ProgramArguments"][3:5], ["--profile", "default"])
+        self.assertEqual(self.plist.stat().st_mode & 0o777, 0o644)
+        self.assertTrue((self.stub / "loaded").exists())
+
+    def test_every_docker_call_uses_the_hosts_docker_context(self) -> None:
+        self.state("session")
+        self.run_role(context="colima-example")
+        docker_calls = [call for call in self.calls() if " docker " in call]
+        self.assertTrue(docker_calls)
+        self.assertTrue(all(call.startswith("colima-example ") for call in docker_calls), docker_calls)
+        self.assertIn("colima-example colima start --profile example --activate=false", self.calls())
+
+    def test_a_second_run_changes_nothing(self) -> None:
+        self.state("session")
+        self.run_role()
+        before = self.calls()
+        result = self.run_role()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual(self.recap(result)["changed"], 0, result.stdout)
+        self.assertEqual([call for call in self.calls()[len(before) :] if not re.match(r"\S+ (docker (info|ps)|launchctl print)", call)], [])
+        self.assertNotIn("bootstrap", " ".join(self.calls()[len(before) :]))
+
+    def test_a_running_runtime_is_not_started_again_but_still_gets_the_agent(self) -> None:
+        self.state("session", "runtime-up")
+        result = self.run_role()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual(self.changes(), [f"colima launchctl bootstrap gui/{UID} {self.plist}"])
+        self.assertTrue(self.plist.exists())
+
+    def test_a_changed_definition_is_unloaded_before_it_is_loaded(self) -> None:
+        self.state("session")
+        self.run_role()
+        self.plist.write_text(self.plist.read_text().replace("start", "stop"))
+        before = len(self.changes())
+        result = self.run_role()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual(self.changes()[before:], [f"colima launchctl bootout gui/{UID}/com.exadev.github-runner.colima.default", f"colima launchctl bootstrap gui/{UID} {self.plist}"])
+        self.assertIn("<string>start</string>", self.plist.read_text())
+
+    def test_without_a_login_session_the_agent_is_installed_and_left_for_the_next_login(self) -> None:
+        result = self.run_role()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertTrue(self.plist.exists())
+        self.assertNotIn("bootstrap", " ".join(self.calls()))
+        self.assertIn("loads at the next login", result.stdout)
+
+    def test_a_malformed_property_list_never_replaces_the_installed_one(self) -> None:
+        self.state("session")
+        self.run_role()
+        installed = self.plist.read_bytes()
+        (self.bin / "plutil").write_text("#!/bin/sh\nexit 1\n")
+        result = self.run_role("-e", "github_runner_cluster_runtime_path=" + f"{self.bin}{os.pathsep}/usr/bin{os.pathsep}/bin{os.pathsep}/changed")
+        self.assertNotEqual(result.returncode, 0)
+        self.assertEqual(self.plist.read_bytes(), installed)
+
+    def test_a_colima_that_will_not_start_fails_the_run_at_that_task(self) -> None:
+        self.state("session", "colima-start-fails")
+        result = self.run_role()
+        self.assertNotEqual(result.returncode, 0)
+        self.assertEqual(failed_task(result.stdout), "Start the Colima profile if it is stopped")
+        self.assertFalse(self.plist.exists())
+
+    def test_autostart_off_installs_nothing_and_a_stopped_runtime_fails_with_the_fix(self) -> None:
+        self.state("session")
+        result = self.run_role(github_runner_cluster_runtime_autostart=False)
+        self.assertNotEqual(result.returncode, 0)
+        self.assertEqual(failed_task(result.stdout), "Fail unless the container runtime is up")
+        self.assertIn("Colima profile default is not running on node1. Start it with `colima start --profile default`", result.stdout)
+        self.assertEqual(self.changes(), [])
+        self.assertFalse(self.plist.exists())
+
+    def test_autostart_off_with_a_running_runtime_passes(self) -> None:
+        self.state("runtime-up")
+        result = self.run_role(github_runner_cluster_runtime_autostart=False)
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual(self.changes(), [])
+
+    def test_docker_desktop_is_never_started_and_a_stopped_one_says_which_setting_to_turn_on(self) -> None:
+        self.state("session")
+        result = self.run_role(context="desktop-linux")
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("Docker Desktop is not running on node1, and this role cannot start it", result.stdout)
+        self.assertIn("Settings > General > Start Docker Desktop when you sign in to your computer", result.stdout)
+        self.assertEqual(self.changes(), [])
+        self.assertFalse(self.plist.parent.exists())
+
+    def test_a_running_docker_desktop_installs_nothing(self) -> None:
+        self.state("session", "runtime-up")
+        result = self.run_role(context="desktop-linux")
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual(self.changes(), [])
+        self.assertFalse(self.plist.parent.exists())
+
+    def test_another_runtime_is_only_checked(self) -> None:
+        result = self.run_role(context="orbstack")
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("The container runtime is not running on node1", result.stdout)
+        self.assertEqual(self.changes(), [])
+
+    def test_a_linux_host_is_not_touched(self) -> None:
+        result = self.run_role(os_family="Debian")
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual(self.calls(), [])
+        self.assertFalse((self.home / "Library").exists())
+
+    def test_check_mode_starts_and_installs_nothing_and_does_not_fail_on_a_stopped_runtime(self) -> None:
+        self.state("session")
+        result = self.run_role("--check", "--diff")
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual(self.changes(), [])
+        self.assertFalse(self.plist.exists())
+        self.assertIn("com.exadev.github-runner.colima.default", result.stdout, "the diff shows the property list")
+
+    def test_check_mode_reports_a_changed_definition(self) -> None:
+        self.state("session")
+        self.run_role()
+        self.plist.write_text(self.plist.read_text().replace("start", "stop"))
+        result = self.run_role("--check", "--diff")
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertGreater(self.recap(result)["changed"], 0)
+        self.assertIn("stop", self.plist.read_text())
+
+    def test_the_end_checks_pass_with_the_runtime_up_and_the_container_running(self) -> None:
+        self.state("runtime-up")
+        result = self.run_role(github_runner_cluster_runtime_autostart=False)
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+
+    def test_the_end_checks_fail_when_the_container_is_not_running(self) -> None:
+        self.state("runtime-up")
+        for state in ("exited", "restarting", ""):
+            with self.subTest(state=state):
+                (self.stub / "github-runner-k3s.state").write_text(state)
+                result = self.run_role(github_runner_cluster_runtime_autostart=False)
+                self.assertNotEqual(result.returncode, 0)
+                self.assertEqual(failed_task(result.stdout), "Fail unless this node's k3s container is running")
+                self.assertIn("The k3s container github-runner-k3s on node1 is", result.stdout)
+                self.assertIn("docker logs github-runner-k3s", result.stdout)
+
+    def test_the_end_checks_catch_a_runtime_that_went_down_during_the_run(self) -> None:
+        result = self.run_role(tasks="end_checks", github_runner_cluster_runtime_autostart=False, github_runner_cluster_effective_runtime={"kind": "colima", "colima_profile": "default"}, github_runner_cluster_runtime_environment={"PATH": f"{self.bin}{os.pathsep}/usr/bin{os.pathsep}/bin", "DOCKER_CONTEXT": "colima"}, github_runner_cluster_runtime_down_message="the runtime is down")
+        self.assertNotEqual(result.returncode, 0)
+        self.assertEqual(failed_task(result.stdout), "Fail unless the container runtime is up")
+        self.assertIn("the runtime is down", result.stdout)
+
+    def test_an_agent_host_is_checked_for_the_agent_container(self) -> None:
+        self.state("runtime-up")
+        result = self.run_role(github_runner_cluster_runtime_autostart=False, github_runner_cluster_effective_node_role="agent")
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("The k3s container github-runner-k3s-agent on node1 is", result.stdout)
+        (self.stub / "github-runner-k3s-agent.state").write_text("running")
+        self.assertEqual(self.run_role(github_runner_cluster_runtime_autostart=False, github_runner_cluster_effective_node_role="agent").returncode, 0)
+
+    def test_a_container_renamed_by_an_extra_compose_file_is_the_one_checked(self) -> None:
+        self.state("runtime-up")
+        (self.stub / "example-k3s.state").write_text("running")
+        result = self.run_role(github_runner_cluster_runtime_autostart=False, github_runner_cluster_container_name="example-k3s")
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+
+
+if __name__ == "__main__":
+    unittest.main()

From 4fa42dc4c3f64b04f1a72feb4fb8570febd006e6 Mon Sep 17 00:00:00 2001
From: Joseph Mearman <joseph@mearman.co.uk>
Date: Tue, 20 Oct 2026 11:54:25 +0100
Subject: [PATCH 3/3] fix(cluster): read the host's operating system instead of
 assuming gathered facts

The macOS conditions read os_family from ansible_facts, which a play with
gather_facts: false does not have, so the role failed on every host of such
a play right after its first tasks. The role now reads the kernel name with
the platform subset of setup when the caller has not gathered it, and the
runtime tasks gather the connecting user and environment they use the same
way. The conditions test the kernel name, Darwin, instead of the OS family.
---
 roles/github_runner_cluster/README.md         |  2 +-
 roles/github_runner_cluster/tasks/host_os.yml | 10 ++++
 roles/github_runner_cluster/tasks/main.yml    | 10 ++--
 roles/github_runner_cluster/tasks/runtime.yml | 10 ++++
 tests/runtime_autostart/host_os.yml           | 15 ++++++
 tests/runtime_autostart/run.yml               |  6 +--
 tests/unit/test_runtime_autostart.py          | 48 +++++++++++++++++--
 7 files changed, 90 insertions(+), 11 deletions(-)
 create mode 100644 roles/github_runner_cluster/tasks/host_os.yml
 create mode 100644 tests/runtime_autostart/host_os.yml

diff --git a/roles/github_runner_cluster/README.md b/roles/github_runner_cluster/README.md
index 8f2fe37..89cac7e 100644
--- a/roles/github_runner_cluster/README.md
+++ b/roles/github_runner_cluster/README.md
@@ -68,7 +68,7 @@ Which runtime a Mac runs is taken from the Docker context the role drives (see [
 - installs a launchd agent, `com.exadev.github-runner.colima.<profile>`, as `~/Library/LaunchAgents/<label>.plist` of the user Ansible connects to, which runs the same command at every login with a `PATH` that names both Homebrew prefixes (`github_runner_cluster_runtime_path`), since launchd gives an agent only the system `PATH` and Colima starts `limactl` and `docker` from the one it has; and
 - loads the agent into that user's login session. A user with no login session on the host (nobody has logged in at the console since the last boot) cannot have an agent loaded, so the role installs the file, says so, and leaves launchd to load it at the next login.
 
-The role never uses `become` for this: a LaunchAgent belongs to the user whose login session loads it, and Colima's VM runs as that user. Changing a definition unloads the agent before loading the new one; a rerun with nothing changed touches neither the agent nor the VM, and `--check --diff` shows the property list that would be written. With the variable off, the role installs nothing and leaves an agent from an earlier run as it is.
+The role reads what it needs to tell a Mac from another host (the kernel name) and to name the agent (the connecting user's id and home directory) with minimal `setup` subsets of its own when the caller has not gathered them, so a play with `gather_facts: false` works. The role never uses `become` for this: a LaunchAgent belongs to the user whose login session loads it, and Colima's VM runs as that user. Changing a definition unloads the agent before loading the new one; a rerun with nothing changed touches neither the agent nor the VM, and `--check --diff` shows the property list that would be written. With the variable off, the role installs nothing and leaves an agent from an earlier run as it is.
 
 A Mac still has to log in for the agent to run: a launch agent starts with the user's login session, not with the machine. A host that should recover from a reboot unattended needs automatic login for that user (System Settings > Users & Groups).
 
diff --git a/roles/github_runner_cluster/tasks/host_os.yml b/roles/github_runner_cluster/tasks/host_os.yml
new file mode 100644
index 0000000..d81aafe
--- /dev/null
+++ b/roles/github_runner_cluster/tasks/host_os.yml
@@ -0,0 +1,10 @@
+---
+# Makes ansible_facts['system'], the kernel name (Darwin on a Mac), available to the conditions that decide whether a host is a Mac, whatever the caller gathered. A play with gather_facts: false (the integration tests', or a caller that gathers only what it needs) leaves ansible_facts without it, and a condition that read an absent fact would fail the run on every host. Only the platform subset is read, the cheapest that holds it, and not at all when the caller already gathered it. Read-only, so it runs under --check too.
+
+- name: Read which operating system this host runs
+  ansible.builtin.setup:
+    gather_subset:
+      - "!all"
+      - "!min"
+      - platform
+  when: "'system' not in ansible_facts"
diff --git a/roles/github_runner_cluster/tasks/main.yml b/roles/github_runner_cluster/tasks/main.yml
index a3e1c8c..0c1f5a1 100644
--- a/roles/github_runner_cluster/tasks/main.yml
+++ b/roles/github_runner_cluster/tasks/main.yml
@@ -5,10 +5,14 @@
   # First, so that a pinned context that does not exist, or one set alongside DOCKER_HOST, stops the run before anything touches the host.
   ansible.builtin.include_tasks: docker_context.yml
 
+- name: Read which operating system this host runs
+  # Before the macOS conditions below, which cannot assume the caller gathered facts.
+  ansible.builtin.include_tasks: host_os.yml
+
 - name: Make the container runtime come back after a reboot, and check it is up
   # macOS only: the runtime is Colima or Docker Desktop there, a Linux VM that stays stopped after a reboot until something starts it, while Linux hosts run Docker as a system service. Before anything reads the daemon, since the version checks below fail on one that is down. See tasks/runtime.yml.
   ansible.builtin.include_tasks: runtime.yml
-  when: ansible_facts['os_family'] == 'Darwin'
+  when: ansible_facts['system'] == 'Darwin'
 
 - name: Read this host's Docker Compose version
   # Before anything that runs Compose (the mesh providers start Compose projects too), for the check below. The CLI plugin's own version, which no Docker context or daemon changes; it still runs with the pinned context, like every docker command in the role. Read-only, so it runs under --check as well.
@@ -115,7 +119,7 @@
 
     - name: Check the runtime and this node's container are up
       ansible.builtin.include_tasks: end_checks.yml
-      when: ansible_facts['os_family'] == 'Darwin'
+      when: ansible_facts['system'] == 'Darwin'
 
 - name: Join as a k3s agent
   when: github_runner_cluster_effective_node_role == "agent"
@@ -138,7 +142,7 @@
 
     - name: Check the runtime and this node's container are up
       ansible.builtin.include_tasks: end_checks.yml
-      when: ansible_facts['os_family'] == 'Darwin'
+      when: ansible_facts['system'] == 'Darwin'
 
     - name: End the role here, since an agent host has no API of its own to wait on
       ansible.builtin.meta: end_role
diff --git a/roles/github_runner_cluster/tasks/runtime.yml b/roles/github_runner_cluster/tasks/runtime.yml
index 6467b77..ea1ddb3 100644
--- a/roles/github_runner_cluster/tasks/runtime.yml
+++ b/roles/github_runner_cluster/tasks/runtime.yml
@@ -5,6 +5,16 @@
 #
 # Publishes github_runner_cluster_effective_runtime ({kind, colima_profile}), github_runner_cluster_runtime_environment (what docker and colima run with), github_runner_cluster_runtime_down_message and github_runner_cluster_runtime_up, for end_checks.yml.
 
+- name: Read the connecting user and its environment
+  # The user id the launchd domain is named after and the home directory the agent lives in. A caller that gathered facts already has both; one that did not (host_os.yml reads only the platform) gets just these two subsets.
+  ansible.builtin.setup:
+    gather_subset:
+      - "!all"
+      - "!min"
+      - user
+      - env
+  when: "'user_uid' not in ansible_facts or 'env' not in ansible_facts"
+
 - name: Work out which container runtime this host runs
   ansible.builtin.set_fact:
     github_runner_cluster_effective_runtime: >-
diff --git a/tests/runtime_autostart/host_os.yml b/tests/runtime_autostart/host_os.yml
new file mode 100644
index 0000000..3a09b19
--- /dev/null
+++ b/tests/runtime_autostart/host_os.yml
@@ -0,0 +1,15 @@
+# Evaluates the condition tasks/main.yml puts on the macOS includes in a play that gathers no facts at all, as the mesh integration tests' plays do, after the role's own host_os.yml tasks (unless read_host_os is false, which shows what the condition does without them), for tests/unit/test_runtime_autostart.py. The condition is the one the test checks tasks/main.yml still uses.
+- name: Evaluate the macOS condition without gathered facts
+  hosts: localhost
+  connection: local
+  gather_facts: false
+  tasks:
+    - name: Read the operating system, as tasks/main.yml does
+      ansible.builtin.include_role:
+        name: exadev.github_runner.github_runner_cluster
+        tasks_from: host_os
+      when: read_host_os | default(true) | bool
+
+    - name: Evaluate the condition
+      ansible.builtin.debug:
+        msg: "mac={{ ansible_facts['system'] == 'Darwin' }}"
diff --git a/tests/runtime_autostart/run.yml b/tests/runtime_autostart/run.yml
index f8f5ad3..79059b3 100644
--- a/tests/runtime_autostart/run.yml
+++ b/tests/runtime_autostart/run.yml
@@ -1,4 +1,4 @@
-# Runs the cluster role's runtime tasks (runtime.yml, then end_checks.yml, or one of them) through the role itself, as tasks/main.yml includes them on a macOS host, for tests/unit/test_runtime_autostart.py. The host's facts are stood in for by extra variables (runtime_os_family, runtime_uid, runtime_home), and the docker, colima, launchctl and plutil it calls are the test's stubs on PATH. The condition is the one tasks/main.yml puts on both includes, which the test checks is still there.
+# Runs the cluster role's runtime tasks (runtime.yml, then end_checks.yml, or one of them) through the role itself, as tasks/main.yml includes them on a macOS host, for tests/unit/test_runtime_autostart.py. The host's facts are stood in for by extra variables (runtime_system, runtime_uid, runtime_home), and the docker, colima, launchctl and plutil it calls are the test's stubs on PATH. The condition is the one tasks/main.yml puts on both includes, which the test checks is still there.
 - name: Run the cluster role's runtime tasks
   hosts: all
   connection: local
@@ -7,7 +7,7 @@
     - name: Stand in for the host's facts
       ansible.builtin.set_fact:
         ansible_facts:
-          os_family: "{{ runtime_os_family }}"
+          system: "{{ runtime_system }}"
           user_uid: "{{ runtime_uid }}"
           env:
             HOME: "{{ runtime_home }}"
@@ -17,4 +17,4 @@
         name: exadev.github_runner.github_runner_cluster
         tasks_from: "{{ item }}"
       loop: "{{ (runtime_tasks | default('runtime,end_checks')).split(',') | map('regex_replace', '$', '.yml') | list }}"
-      when: ansible_facts['os_family'] == 'Darwin'
+      when: ansible_facts['system'] == 'Darwin'
diff --git a/tests/unit/test_runtime_autostart.py b/tests/unit/test_runtime_autostart.py
index 983113c..ef2f018 100644
--- a/tests/unit/test_runtime_autostart.py
+++ b/tests/unit/test_runtime_autostart.py
@@ -4,6 +4,7 @@
 
 import json
 import os
+import platform
 import plistlib
 import re
 import shutil
@@ -20,11 +21,12 @@
 ROLE = ROOT / "roles" / "github_runner_cluster"
 RENDER = ROOT / "tests" / "runtime_autostart" / "render_plist.yml"
 RUN = ROOT / "tests" / "runtime_autostart" / "run.yml"
+HOST_OS = ROOT / "tests" / "runtime_autostart" / "host_os.yml"
 ANSIBLE_PLAYBOOK = os.environ.get("ANSIBLE_PLAYBOOK", "ansible-playbook")
 DEFAULTS: dict[str, Any] = yaml.safe_load((ROLE / "defaults" / "main.yml").read_text())
 UID = 501
 HOME = "/Users/example"
-DARWIN_ONLY = "ansible_facts['os_family'] == 'Darwin'"
+DARWIN_ONLY = "ansible_facts['system'] == 'Darwin'"
 
 
 def ansible_env() -> dict[str, str]:
@@ -85,6 +87,20 @@ def test_both_includes_run_on_macos_only(self) -> None:
                 for include in includes:
                     self.assertEqual(include["when"], DARWIN_ONLY)
 
+    def test_the_operating_system_is_read_before_either_condition_uses_it(self) -> None:
+        tasks = yaml.safe_load((ROLE / "tasks" / "main.yml").read_text())
+        order = [task.get("ansible.builtin.include_tasks") for task in tasks]
+        self.assertLess(order.index("host_os.yml"), order.index("runtime.yml"))
+        self.assertNotIn("when", tasks[order.index("host_os.yml")])
+
+    def test_the_runtime_tasks_gather_the_user_and_environment_they_use_when_the_caller_did_not(self) -> None:
+        tasks = yaml.safe_load((ROLE / "tasks" / "runtime.yml").read_text())
+        gather = tasks[0]["ansible.builtin.setup"]
+        self.assertEqual(gather["gather_subset"], ["!all", "!min", "user", "env"])
+        self.assertEqual(tasks[0]["when"], "'user_uid' not in ansible_facts or 'env' not in ansible_facts")
+        used = (ROLE / "tasks" / "runtime.yml").read_text() + (ROLE / "defaults" / "main.yml").read_text()
+        self.assertEqual(set(re.findall(r"ansible_facts\['(\w+)'\]", used)) - {"system"}, {"user_uid", "env"})
+
     def test_the_runtime_is_up_before_anything_reads_the_daemon(self) -> None:
         tasks = yaml.safe_load((ROLE / "tasks" / "main.yml").read_text())
         order = [task.get("ansible.builtin.include_tasks") or task.get("ansible.builtin.command") for task in tasks]
@@ -101,6 +117,30 @@ def test_the_end_checks_follow_the_compose_start_on_servers_and_agents(self) ->
                 self.assertLess(steps.index("compose"), steps.index("end_checks.yml"))
 
 
+@unittest.skipIf(shutil.which(ANSIBLE_PLAYBOOK) is None, "ansible-playbook is not installed")
+class NoGatheredFactsTest(unittest.TestCase):
+    """The mesh integration tests' plays gather no facts, so the macOS condition must not depend on any the caller gathered."""
+
+    def run_play(self, *extra: str) -> subprocess.CompletedProcess[str]:
+        with tempfile.TemporaryDirectory() as work:
+            return subprocess.run([ANSIBLE_PLAYBOOK, str(HOST_OS), *extra], capture_output=True, text=True, check=False, env=ansible_env(), cwd=work)
+
+    def test_the_play_uses_the_condition_main_yml_uses(self) -> None:
+        play = yaml.safe_load(HOST_OS.read_text())[0]
+        self.assertIn(DARWIN_ONLY, play["tasks"][1]["ansible.builtin.debug"]["msg"])
+
+    def test_the_condition_evaluates_after_the_role_reads_the_operating_system(self) -> None:
+        result = self.run_play()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertIn(f"mac={platform.system() == 'Darwin'}", result.stdout)
+
+    def test_the_same_play_fails_without_those_tasks(self) -> None:
+        # What every mesh scenario hit before the role read the operating system itself.
+        result = self.run_play("-e", "read_host_os=false")
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("has no attribute 'system'", result.stdout + result.stderr)
+
+
 class PlistTest(unittest.TestCase):
     @classmethod
     def setUpClass(cls) -> None:
@@ -239,9 +279,9 @@ def state(self, *flags: str) -> None:
         for flag in flags:
             (self.stub / flag).write_text("")
 
-    def run_role(self, *extra: str, tasks: str = "runtime,end_checks", context: str = "colima", os_family: str = "Darwin", **variables: Any) -> subprocess.CompletedProcess[str]:
+    def run_role(self, *extra: str, tasks: str = "runtime,end_checks", context: str = "colima", system: str = "Darwin", **variables: Any) -> subprocess.CompletedProcess[str]:
         host = {
-            "runtime_os_family": os_family,
+            "runtime_system": system,
             "runtime_uid": UID,
             "runtime_home": str(self.home),
             "runtime_tasks": tasks,
@@ -374,7 +414,7 @@ def test_another_runtime_is_only_checked(self) -> None:
         self.assertEqual(self.changes(), [])
 
     def test_a_linux_host_is_not_touched(self) -> None:
-        result = self.run_role(os_family="Debian")
+        result = self.run_role(system="Linux")
         self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
         self.assertEqual(self.calls(), [])
         self.assertFalse((self.home / "Library").exists())