@crvouga/dev-fleet 0.4.0 → 0.5.0

package/ansible/ubuntu/tasks/packages.yml

@@ -1,56 +1,5 @@
 ---
-- name: Create owned APT configuration directory
-  ansible.builtin.file:
-    path: /etc/personal-fleet
-    state: directory
-    owner: root
-    group: root
-    mode: '0755'
-- name: Declare snapshot sources used only for managed package transactions
-  ansible.builtin.copy:
-    dest: /etc/personal-fleet/ubuntu.sources
-    owner: root
-    group: root
-    mode: '0644'
-    backup: true
-    content: |
-      Types: deb
-      URIs: https://snapshot.ubuntu.com/ubuntu/{{ snapshot }}/
-      Suites: resolute resolute-updates resolute-security
-      Components: main universe restricted multiverse
-      Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
-  register: snapshot_sources
-- name: Isolate snapshot selection from unrelated APT operations
-  ansible.builtin.copy:
-    dest: /etc/personal-fleet/apt.conf
-    owner: root
-    group: root
-    mode: '0644'
-    content: |
-      Dir::Etc::sourcelist "/etc/personal-fleet/ubuntu.sources";
-      Dir::Etc::sourceparts "-";
-      DPkg::Lock::Timeout "{{ aptLockTimeoutSeconds }}";
-- name: Inspect immutable snapshot package index
-  ansible.builtin.stat:
-    path: '/var/lib/apt/lists/snapshot.ubuntu.com_ubuntu_{{ snapshot }}_dists_resolute_InRelease'
-  register: snapshot_index
-- name: Fetch signed snapshot indexes after source change or interrupted setup
-  ansible.builtin.apt:
-    update_cache: true
-    cache_valid_time: 0
-    lock_timeout: '{{ aptLockTimeoutSeconds }}'
-  environment:
-    APT_CONFIG: /etc/personal-fleet/apt.conf
-  when: snapshot_sources.changed or not snapshot_index.stat.exists
-- name: Install exact managed packages without downgrading or restarting services
-  ansible.builtin.apt:
-    name: '{{ item.key }}={{ item.value }}'
-    state: present
-    lock_timeout: '{{ aptLockTimeoutSeconds }}'
-    allow_downgrade: false
-    allow_unauthenticated: false
-    fail_on_autoremove: true
-    policy_rc_d: 101
-  environment:
-    APT_CONFIG: /etc/personal-fleet/apt.conf
-  loop: '{{ packages | dict2items }}'
+- ansible.builtin.include_tasks: install.yml
+  vars:
+    install_pins: '{{ packages }}'
+- ansible.builtin.import_tasks: unattended-upgrades.yml

package/ansible/ubuntu/tasks/release.yml

@@ -0,0 +1,25 @@
+---
+# The accepted releases are named once, in policy.json. This selects the
+# entry of the running release and refuses everything else.
+- name: Select the accepted release this machine runs
+  ansible.builtin.set_fact:
+    ubuntu_release: "{{ releases | selectattr('release', 'equalto', ansible_facts.distribution_version) | first | default({}) }}"
+- name: Require an accepted release, its codename and one of its architectures
+  ansible.builtin.assert:
+    that:
+      - ansible_facts.distribution == 'Ubuntu'
+      - ubuntu_release.release is defined
+      - ansible_facts.distribution_release == ubuntu_release.codename
+      - "(ansible_facts.architecture | replace('x86_64', 'amd64') | replace('aarch64', 'arm64')) in ubuntu_release.architectures"
+    fail_msg: UBUNTU_BASELINE_MISMATCH; workers run a release docs/support-matrix.md lists. No distribution upgrade is permitted.
+- name: Pin the packages of this release, its own pins over the common ones
+  ansible.builtin.set_fact:
+    packages: '{{ packages | combine(ubuntu_release.packages | default({})) }}'
+- name: Read the kernel release to tell WSL2 apart from a machine of its own
+  ansible.builtin.slurp:
+    src: /proc/sys/kernel/osrelease
+  register: kernel_release
+- name: Refuse WSL2 by name
+  ansible.builtin.assert:
+    that: not (kernel_release.content | b64decode | lower is search('microsoft|wsl'))
+    fail_msg: WORKER_ENVIRONMENT_UNSUPPORTED; WSL2 is not a worker. Run the worker on a physical or virtual machine of its own (docs/support-matrix.md).

package/ansible/ubuntu/tasks/resources.yml

@@ -49,10 +49,11 @@
     line: /swap.fleet none swap sw 0 0
   when: active_swap.stdout | trim == ''
 
-- name: Install the systemd userspace OOM killer
-  ansible.builtin.apt:
-    name: systemd-oomd
-    state: present
+- name: Install the systemd userspace OOM killer at its pin
+  ansible.builtin.include_tasks: install.yml
+  vars:
+    install_pins:
+      systemd-oomd: "{{ packages['systemd-oomd'] }}"
 - name: Create memory and disk policy directories
   ansible.builtin.file:
     path: '{{ item }}'
@@ -276,7 +277,7 @@
         After=docker.service
         [Service]
         Type=oneshot
-        ExecStart=/usr/bin/python3 -I -B {{ disk_gc_source.stat.path }} --home {{ development_home }} --path / --path {{ development_home }} --idle-days {{ resourceSafety.diskGcIdleDays }} --pressure-mib {{ resourceSafety.diskGcPressureMiB }} --pressure-inode-percent {{ resourceSafety.inodeWarnFreePercent }} --pressure-idle-hours {{ resourceSafety.diskGcPressureIdleHours }} --docker-age-hours {{ resourceSafety.diskGcDockerAgeHours }} --pressure-docker-age-hours {{ resourceSafety.diskGcPressureDockerAgeHours }}{% for cache in resourceSafety.diskGcPressureCaches %} --pressure-cache {{ cache }}{% endfor %}
+        ExecStart=/usr/bin/python3 -I -B {{ disk_gc_source.stat.path }} --home {{ development_home }} --path / --path {{ development_home }} --idle-days {{ resourceSafety.diskGcIdleDays }} --pressure-mib {{ resourceSafety.diskGcPressureMiB }} --pressure-inode-percent {{ resourceSafety.inodeWarnFreePercent }} --pressure-idle-hours {{ resourceSafety.diskGcPressureIdleHours }} --docker-age-hours {{ resourceSafety.diskGcDockerAgeHours }} --pressure-docker-age-hours {{ resourceSafety.diskGcPressureDockerAgeHours }}{% for cache in resourceSafety.diskGcPressureCaches %} --pressure-cache {{ cache }}{% endfor %}{% for root in resourceSafety.diskGcWorktreeRoots %} --worktree-root {{ root }}{% endfor %} --worktree-idle-days {{ resourceSafety.diskGcWorktreeIdleDays }}{% for cache, mib in resourceSafety.diskGcCacheCapsMiB.items() %} --cache-cap {{ cache }}={{ mib }}{% endfor %} --keep-newest /var/cache/personal-fleet={{ resourceSafety.diskGcPackagesKept }} --mise {{ development_home }}/.local/bin/mise --user {{ development_user }}
 
         TimeoutStartSec=2h
         Nice=19

package/ansible/ubuntu/tasks/snapshot.yml

@@ -0,0 +1,50 @@
+---
+# The snapshot every managed package comes from, separate from the system's
+# own sources. Included before any pinned package is installed; a second
+# inclusion in one run changes nothing.
+- name: Create owned APT configuration directory
+  ansible.builtin.file:
+    path: /etc/personal-fleet
+    state: directory
+    owner: root
+    group: root
+    mode: '0755'
+- name: Declare snapshot sources used only for managed package transactions
+  ansible.builtin.copy:
+    dest: /etc/personal-fleet/ubuntu.sources
+    owner: root
+    group: root
+    mode: '0644'
+    backup: true
+    content: |
+      Types: deb
+      URIs: https://snapshot.ubuntu.com/ubuntu/{{ snapshot }}/
+      Suites: {{ ubuntu_release.codename }} {{ ubuntu_release.codename }}-updates {{ ubuntu_release.codename }}-security
+      Components: main universe restricted multiverse
+      Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
+  register: snapshot_sources
+# Fetching the snapshot indexes must leave the indexes of the system's own
+# sources in place: the system's APT and unattended upgrades still use them.
+- name: Isolate snapshot selection from unrelated APT operations
+  ansible.builtin.copy:
+    dest: /etc/personal-fleet/apt.conf
+    owner: root
+    group: root
+    mode: '0644'
+    content: |
+      Dir::Etc::sourcelist "/etc/personal-fleet/ubuntu.sources";
+      Dir::Etc::sourceparts "-";
+      APT::Get::List-Cleanup "false";
+      DPkg::Lock::Timeout "{{ aptLockTimeoutSeconds }}";
+- name: Inspect immutable snapshot package index
+  ansible.builtin.stat:
+    path: '/var/lib/apt/lists/snapshot.ubuntu.com_ubuntu_{{ snapshot }}_dists_{{ ubuntu_release.codename }}_InRelease'
+  register: snapshot_index
+- name: Fetch signed snapshot indexes after source change or interrupted setup
+  ansible.builtin.apt:
+    update_cache: true
+    cache_valid_time: 0
+    lock_timeout: '{{ aptLockTimeoutSeconds }}'
+  environment:
+    APT_CONFIG: /etc/personal-fleet/apt.conf
+  when: snapshot_sources.changed or not snapshot_index.stat.exists

package/ansible/ubuntu/tasks/unattended-upgrades.yml

@@ -0,0 +1,24 @@
+---
+# Ubuntu installs security updates by itself, and they keep flowing: a pin is
+# a minimum, never a hold. What runs unattended is declared here so it is
+# known: security updates only, never a reboot, never a removal. The fleet's
+# own file sorts after the package's 50unattended-upgrades and replaces its
+# origins.
+- name: Declare which updates Ubuntu installs unattended
+  ansible.builtin.copy:
+    dest: /etc/apt/apt.conf.d/52personal-fleet-unattended-upgrades
+    owner: root
+    group: root
+    mode: '0644'
+    content: |
+      // Managed by personal Fleet: unattended upgrades
+      APT::Periodic::Update-Package-Lists "1";
+      APT::Periodic::Unattended-Upgrade "1";
+      #clear Unattended-Upgrade::Allowed-Origins;
+      #clear Unattended-Upgrade::Origins-Pattern;
+      Unattended-Upgrade::Allowed-Origins {
+        "${distro_id}:${distro_codename}-security";
+      };
+      Unattended-Upgrade::Automatic-Reboot "false";
+      Unattended-Upgrade::Remove-Unused-Dependencies "false";
+      Unattended-Upgrade::Remove-New-Unused-Dependencies "false";

package/bootstrap/fleet-remote-bootstrap.sh

@@ -2,14 +2,17 @@
 # Executed over strict SSH from the selected verified Git revision. stdin is
 # one line holding the base64 fleet configuration (empty when there is none),
 # then the base64 Git bundle (nothing in cached mode). All executable content
-# remains in this tracked source.
+# remains in this tracked source. The Ubuntu releases workers may run are
+# named once, in ansible/ubuntu/policy.json; the manager passes them in.
 set -eu
 umask 077
 revision=$1
 bundle_sha=$2
 node=$3
 source_mode=${4:-transfer}
+releases=${5:-}
 case "$source_mode" in cached|transfer) ;; *) exit 2;; esac
+case "$releases" in *[!0-9.\ ]*|'') exit 2;; esac
 case "$revision" in *[!a-f0-9]*|'') exit 2;; esac
 [ "${#revision}" = 40 ] || exit 2
 case "$bundle_sha" in *[!a-f0-9]*|'') exit 2;; esac
@@ -26,7 +29,8 @@ remedy() {
   case "$1" in
     FLEET_REMOTE_LOCKED) echo 'Another fleet operation holds this machine. Wait for it to finish; rerun fleet-sync afterwards. Never remove the lock while its holder runs.';;
     ROOT_DEVELOPMENT_USER_REJECTED) echo 'Connect as the non-root developer account the fleet configuration names.';;
-    UBUNTU_BASELINE_MISMATCH|UBUNTU_ARCHITECTURE_UNSUPPORTED|MACOS_BASELINE_MISMATCH|MACOS_ARCHITECTURE_UNSUPPORTED|PLATFORM_UNSUPPORTED) echo 'Workers run Ubuntu 26.04 on x86_64 or aarch64. Reinstall the machine; fleet-sync never upgrades an operating system.';;
+    UBUNTU_BASELINE_MISMATCH|UBUNTU_ARCHITECTURE_UNSUPPORTED|PLATFORM_UNSUPPORTED) echo 'Workers run an Ubuntu release docs/support-matrix.md lists, on x86_64 or aarch64. Reinstall the machine; fleet-sync never upgrades an operating system.';;
+    WORKER_ENVIRONMENT_UNSUPPORTED) echo 'WSL2 is not a worker. Run the worker on a physical or virtual machine of its own (docs/support-matrix.md).';;
     FLEET_STATE_PATH_UNSAFE) echo 'A fleet state directory under ~/.local/share/personal is a symbolic link. Replace it with a real directory.';;
     BOOTSTRAP_CAPACITY_UNVERIFIED|BOOTSTRAP_DISK_CAPACITY_REQUIRED) echo 'Free at least 2 GiB and 50000 inodes on the home file system, then rerun fleet-sync.';;
     SOURCE_DIGEST_MISMATCH) echo 'The bundle changed in transit. Rerun fleet-sync; if it repeats, check the SSH route.';;
@@ -37,8 +41,6 @@ remedy() {
     APT_DISK_FULL) echo 'Package installation ran out of disk space. Free space under /var and /usr, then rerun fleet-sync.';;
     DPKG_INTERRUPTED) echo 'An earlier package installation that fleet-sync did not start was interrupted. Run sudo dpkg --configure -a once no package process is running, then rerun fleet-sync.';;
     APT_UPDATE_FAILED|APT_INSTALL_FAILED) echo 'Run sudo apt-get update and install the bootstrap packages by hand to see the error, then rerun fleet-sync.';;
-    XCODE_COMMAND_LINE_TOOLS_REQUIRED) echo 'Install the Xcode Command Line Tools (xcode-select --install), then rerun fleet-sync.';;
-    BOOTSTRAP_LOCK_TOOL_REQUIRED) echo 'Install python3 so the operation lock can be taken, then rerun fleet-sync.';;
     SOURCE_CACHE_CHANGED|SOURCE_STATUS_FAILED|SOURCE_CHECKOUT_CONFLICT) echo 'The fleet-owned checkout of this revision holds changes fleet-sync did not make. Inspect and remove that revisions directory, then rerun fleet-sync.';;
     CONFIGURATION_INSTALL_FAILED) echo 'The fleet configuration could not be written under ~/.config/dev-fleet. Check that directory, then rerun fleet-sync.';;
     TOOLCHAIN_*) echo 'The pinned toolchain did not converge. Rerun fleet-sync; it resumes where it stopped. If it repeats, run devfleet fleet-status --node for this worker.';;
@@ -64,22 +66,14 @@ trap '' HUP
 trap 'exit 1' INT TERM
 # No shell startup assumptions, and no implicit root development user.
 [ "$(id -u)" != 0 ] || die ROOT_DEVELOPMENT_USER_REJECTED
-# Ubuntu 26.04 is the accepted worker platform; macOS 14+ follows the same
-# phases best effort with launchd instead of systemd.
-platform=$(uname -s)
-case "$platform" in
-  Linux)
-    # shellcheck source=/dev/null
-    . /etc/os-release
-    [ "$ID" = ubuntu ] && [ "$VERSION_ID" = 26.04 ] || die UBUNTU_BASELINE_MISMATCH
-    case "$(uname -m)" in x86_64|aarch64) ;; *) die UBUNTU_ARCHITECTURE_UNSUPPORTED;; esac ;;
-  Darwin)
-    major=$(sw_vers -productVersion | cut -d. -f1)
-    case "$major" in ''|*[!0-9]*) die MACOS_BASELINE_MISMATCH;; esac
-    [ "$major" -ge 14 ] || die MACOS_BASELINE_MISMATCH
-    case "$(uname -m)" in arm64|x86_64) ;; *) die MACOS_ARCHITECTURE_UNSUPPORTED;; esac ;;
-  *) die PLATFORM_UNSUPPORTED;;
-esac
+# Workers are the Ubuntu releases the policy accepts (docs/support-matrix.md).
+[ "$(uname -s)" = Linux ] || die PLATFORM_UNSUPPORTED
+# shellcheck source=/dev/null
+. /etc/os-release
+[ "$ID" = ubuntu ] || die UBUNTU_BASELINE_MISMATCH
+case " $releases " in *" $VERSION_ID "*) ;; *) die UBUNTU_BASELINE_MISMATCH;; esac
+case "$(uname -m)" in x86_64|aarch64) ;; *) die UBUNTU_ARCHITECTURE_UNSUPPORTED;; esac
+! grep -qiE 'microsoft|wsl' /proc/sys/kernel/osrelease 2>/dev/null || die WORKER_ENVIRONMENT_UNSUPPORTED
 root="$HOME/.local/share/personal/fleet"
 # Refuse symlinked state roots rather than allowing writes through them.
 for path in "$HOME/.local" "$HOME/.local/share" "$HOME/.local/share/personal" "$root"; do
@@ -89,14 +83,8 @@ mkdir -p "$root"
 phase=lock
 [ ! -L "$root/remote-operation.lock" ] || exit 1
 exec 9>"$root/remote-operation.lock"
-# macOS has no flock(1); lock the same descriptor through fcntl. The lock
-# follows this shell's open descriptor and is released when it exits.
-if command -v flock >/dev/null 2>&1; then
-  flock -n 9 || die FLEET_REMOTE_LOCKED
-else
-  command -v python3 >/dev/null 2>&1 || die BOOTSTRAP_LOCK_TOOL_REQUIRED
-  python3 -c 'import fcntl; fcntl.flock(9, fcntl.LOCK_EX | fcntl.LOCK_NB)' 9>&9 || die FLEET_REMOTE_LOCKED
-fi
+# The lock follows this shell's open descriptor and is released when it exits.
+flock -n 9 || die FLEET_REMOTE_LOCKED
 # The operation record: a manager that lost its session reads it to follow
 # this operation to its end instead of starting another (see
 # src/remote-operation.ts). The result of the last operation is beside it.
@@ -132,14 +120,9 @@ if [ "$source_mode" = transfer ]; then
 bundle=$(mktemp "$root/source.XXXXXX")
 # Leave no executable payload copies; this temporary file is only Git data.
 base64 -d >"$bundle"
-if command -v sha256sum >/dev/null 2>&1; then
-  printf '%s  %s\n' "$bundle_sha" "$bundle" | sha256sum -c - >/dev/null 2>&1 || die SOURCE_DIGEST_MISMATCH
-else
-  [ "$(shasum -a 256 "$bundle" | cut -d' ' -f1)" = "$bundle_sha" ] || die SOURCE_DIGEST_MISMATCH
-fi
+printf '%s  %s\n' "$bundle_sha" "$bundle" | sha256sum -c - >/dev/null 2>&1 || die SOURCE_DIGEST_MISMATCH
 fi
 phase=prerequisites
-if [ "$platform" = Linux ]; then
 missing=''
 for package in git curl ca-certificates unzip xz-utils build-essential python3 ansible-core; do
   dpkg-query -W -f='${db:Status-Status}' "$package" 2>/dev/null | grep -qx installed || missing="$missing $package"
@@ -171,12 +154,6 @@ if [ -n "$missing" ]; then
   rm -f -- "$pending" "$apt_log"
   apt_log=''
 fi
-else
-  # Apple Command Line Tools provide git and python3; Ansible runs through the
-  # pinned uv tool runner installed by the shared mise toolchain below.
-  xcode-select -p >/dev/null 2>&1 || die XCODE_COMMAND_LINE_TOOLS_REQUIRED
-  command -v git >/dev/null 2>&1 || die XCODE_COMMAND_LINE_TOOLS_REQUIRED
-fi
 phase=source-verification
 deployment="$root/revisions/$revision"
 [ ! -L "$root/revisions" ] && [ ! -L "$deployment" ] || exit 1
@@ -235,7 +212,7 @@ else
   toolchain_warm=''
   rm -f -- "$status_file" "$ready_file"
 fi
-if command -v timeout >/dev/null 2>&1; then bounded='timeout 1800'; else bounded=''; fi
+bounded='timeout 1800'
 # shellcheck disable=SC2086
 if [ -z "$toolchain_warm" ] && ! $bounded bash bootstrap/bootstrap.sh --worker --node "$node" --non-interactive --status-file "$status_file" >/dev/null 2>&1; then
   tool_phase=$(sed -n 's/.*"phase":"\([a-z0-9-]*\)".*/\1/p' "$status_file" 2>/dev/null) || tool_phase=''

package/docs/consumer-setup.md

@@ -153,35 +153,35 @@ npx devfleet fleet-state --example > fleet.json
 Then replace every placeholder. Each field, from
 [`schema/fleet.schema.json`](../schema/fleet.schema.json):
 
-| Field                                                 | Value                                                                                                              |
-| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `version`                                             | `3`                                                                                                                |
-| `source.repository`                                   | `https://github.com/crvouga/dev-fleet.git`, or your fork if you publish one. Machines only accept code from it.    |
-| `state`                                               | `{ "bucket", "endpoint"?, "region"?, "prefix"? }` or `{ "directory": "/absolute/path" }`. Never credentials.       |
-| `secrets`                                             | See [secrets](#secrets).                                                                                           |
-| `manager.id`                                          | A short lowercase id, `^[a-z][a-z0-9-]{0,62}$`, e.g. `manager-mac`.                                                |
-| `manager.os`                                          | `"macOS"`                                                                                                          |
-| `manager.network.tailscaleName`                       | The manager's MagicDNS name: `tailscale status --json` → `.Self.DNSName` without the trailing dot.                 |
-| `manager.network.user`                                | The manager's login name (`id -un`).                                                                               |
-| `manager.neverSleepOnPower`                           | `true` (workers depend on the manager's services).                                                                 |
-| `workers[].id`                                        | A short lowercase id. The **first** worker is the canary: a new revision must pass there before the others get it. |
-| `workers[].ssh`                                       | The worker's alias in the manager's `~/.ssh/config`.                                                               |
-| `workers[].os`                                        | `"linux"`                                                                                                          |
-| `workers[].network.tailscaleName`                     | The worker's MagicDNS name (from `tailscale status --json` → `.Peer[].DNSName` on the manager).                    |
-| `workers[].network.sshPort`                           | `22` unless the worker's sshd listens elsewhere.                                                                   |
-| `workers[].network.user`                              | The worker account (`ssh WORKER_ALIAS id -un`).                                                                    |
-| `workers[].network.t3Port`                            | `3773`                                                                                                             |
-| `services.proxy.endpoint`                             | The public HTTPS origin of the CLI proxy, e.g. `https://cli-proxy.example.com`.                                    |
-| `services.monitoring.hubPort`                         | `8443`                                                                                                             |
-| `services.monitoring.publicUrl`                       | The public HTTPS origin of the monitoring dashboard.                                                               |
-| `services.monitoring.managerAccount`                  | The email of the monitoring account the manager enrolls machines with.                                             |
-| `services.monitoring.viewerAccount`                   | The email of the read-only account visitors are signed in as.                                                      |
-| `ubuntu`                                              | `{ "release": "26.04", "architectures": ["amd64", "arm64"] }` (fixed).                                             |
-| `worker.requiredCapabilities`                         | Normally all of `github`, `vault`, `t3`, `toolchain`, `workstation`, `worker`.                                     |
-| `worker.githubLogin`                                  | The GitHub login every worker must be signed in as.                                                                |
-| `worker.vaultUser`                                    | The Vault user each worker's token is issued for.                                                                  |
-| `worker.toolchain`, `agentProfile`                    | `"mise.lock"`, `"proxy"` (fixed).                                                                                  |
-| `worker.unattendedSudo`, `persistentT3`, `neverSleep` | `true` (fixed policy).                                                                                             |
+| Field                                                 | Value                                                                                                                |
+| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `version`                                             | `3`                                                                                                                  |
+| `source.repository`                                   | `https://github.com/crvouga/dev-fleet.git`, or your fork if you publish one. Machines only accept code from it.      |
+| `state`                                               | `{ "bucket", "endpoint"?, "region"?, "prefix"? }` or `{ "directory": "/absolute/path" }`. Never credentials.         |
+| `secrets`                                             | See [secrets](#secrets).                                                                                             |
+| `manager.id`                                          | A short lowercase id, `^[a-z][a-z0-9-]{0,62}$`, e.g. `manager-mac`.                                                  |
+| `manager.os`                                          | `"macOS"`                                                                                                            |
+| `manager.network.tailscaleName`                       | The manager's MagicDNS name: `tailscale status --json` → `.Self.DNSName` without the trailing dot.                   |
+| `manager.network.user`                                | The manager's login name (`id -un`).                                                                                 |
+| `manager.neverSleepOnPower`                           | `true` (workers depend on the manager's services).                                                                   |
+| `workers[].id`                                        | A short lowercase id. The **first** worker is the canary: a new revision must pass there before the others get it.   |
+| `workers[].ssh`                                       | The worker's alias in the manager's `~/.ssh/config`.                                                                 |
+| `workers[].os`                                        | `"linux"`                                                                                                            |
+| `workers[].network.tailscaleName`                     | The worker's MagicDNS name (from `tailscale status --json` → `.Peer[].DNSName` on the manager).                      |
+| `workers[].network.sshPort`                           | `22` unless the worker's sshd listens elsewhere.                                                                     |
+| `workers[].network.user`                              | The worker account (`ssh WORKER_ALIAS id -un`).                                                                      |
+| `workers[].network.t3Port`                            | `3773`                                                                                                               |
+| `services.proxy.endpoint`                             | The public HTTPS origin of the CLI proxy, e.g. `https://cli-proxy.example.com`.                                      |
+| `services.monitoring.hubPort`                         | `8443`                                                                                                               |
+| `services.monitoring.publicUrl`                       | The public HTTPS origin of the monitoring dashboard.                                                                 |
+| `services.monitoring.managerAccount`                  | The email of the monitoring account the manager enrolls machines with.                                               |
+| `services.monitoring.viewerAccount`                   | The email of the read-only account visitors are signed in as.                                                        |
+| `ubuntu`                                              | `{ "release": "26.04", "architectures": ["amd64", "arm64"] }`: a release of the [support matrix](support-matrix.md). |
+| `worker.requiredCapabilities`                         | Normally all of `github`, `vault`, `t3`, `toolchain`, `workstation`, `worker`.                                       |
+| `worker.githubLogin`                                  | The GitHub login every worker must be signed in as.                                                                  |
+| `worker.vaultUser`                                    | The Vault user each worker's token is issued for.                                                                    |
+| `worker.toolchain`, `agentProfile`                    | `"mise.lock"`, `"proxy"` (fixed).                                                                                    |
+| `worker.unattendedSudo`, `persistentT3`, `neverSleep` | `true` (fixed policy).                                                                                               |
 
 Use the same values in every place they repeat. Validate before going on:
 
@@ -352,7 +352,9 @@ Read `summary` and `remedy.action` of the failing check. The common ones:
 | `TAILSCALE_NODE_OFFLINE`                  | The worker is off or off the tailnet. It is listed and skipped; others continue.                                              |
 | `TAILSCALE_DEVICE_REPLACED`               | The tailnet device behind a worker changed. Nothing is written to it until the human confirms the replacement.                |
 | `SUDO_AUTHORIZATION_REQUIRED`             | The worker account cannot use sudo without a password. Run the first sync interactively.                                      |
-| `UBUNTU_BASELINE_MISMATCH`                | The worker is not Ubuntu 26.04.                                                                                               |
+| `UBUNTU_BASELINE_MISMATCH`                | The worker is not an Ubuntu release the [support matrix](support-matrix.md) lists.                                            |
+| `WORKER_ENVIRONMENT_UNSUPPORTED`          | The worker is WSL2 or a container. Use a physical or virtual machine of its own.                                              |
+| `PACKAGE_NEWER_THAN_PIN` (warning)        | Ubuntu's security updates moved a pinned package past its pin. It is kept; the pin is a minimum.                              |
 | `ROOT_DEVELOPMENT_USER_REJECTED`          | The worker's SSH user is root. Use a normal account with sudo.                                                                |
 | `BOOTSTRAP_DISK_CAPACITY_REQUIRED`        | Less than 2 GiB free (or too few inodes) where the fleet keeps its files on the worker.                                       |
 | `FLEET_REMOTE_LOCKED`                     | Another operation is running on that worker. Wait and run again.                                                              |

package/docs/declared.md

@@ -47,11 +47,10 @@ stays in the playbook: the playbook is its declaration.
   launchd job from TypeScript and has never worked from the published package.
   It should become a playbook.
 - **The rest of a worker's packages.** Only the packages in `policy.json` are
-  exact. `systemd-oomd` and the T3 desktop libraries are installed at whatever
-  version the machine's own archive holds, and the machine's own updates move
-  everything else. Pinning them needs every worker on the snapshot with its
-  own updates off, so security fixes arrive only when the snapshot moves. That
-  is a policy choice, not a missing line.
+  pinned. The T3 desktop libraries are installed at whatever version the
+  machine's own archive holds, and Ubuntu's security updates move everything
+  else, pinned packages included: a pin is a minimum
+  ([worker contract](worker-contract.md#package-pins-and-security-updates)).
 - **What a worker needs before Ansible exists.** `fleet-remote-bootstrap.sh`
   installs Git, curl, CA certificates, Python and `ansible-core` from the
   machine's own archive (the snapshot is HTTPS, and a new machine has no CA

package/docs/runbooks.md

@@ -8,29 +8,26 @@ person (a login, an approval, a choice) is marked **needs a person**.
 `features/rules/runbooks.feature` fails when a code in the source has no
 entry here, or a `devfleet` command quoted in the documents does not exist.
 
-There are 241 codes; 31 need a person.
+There are 238 codes; 29 need a person.
 
 ## Bootstrap of a new or returning worker
 
 - **Meaning:** The remote bootstrap (`bootstrap/fleet-remote-bootstrap.sh`) stopped before node convergence. It reports the phase and the code, never its output.
 - **Confirm:** Run `devfleet fleet-sync --dry-run` and read the `bootstrap:*` check of the worker; `ssh WORKER` and look under `~/.local/share/personal/fleet`.
 - **Fix:** Follow the remedy the check prints, then run `devfleet fleet-sync`. The bootstrap resumes where it stopped.
-- **Escalate:** A platform or architecture code means the machine must be reinstalled: Ubuntu 26.04 on x86_64 or aarch64.
+- **Escalate:** A platform or architecture code means the machine must be reinstalled with a release [the support matrix](support-matrix.md) lists, on a machine of its own.
 
 - `BOOTSTRAP_CAPACITY_UNVERIFIED`: bootstrap capacity unverified.
 - `BOOTSTRAP_DISK_CAPACITY_REQUIRED`: bootstrap disk capacity required.
-- `BOOTSTRAP_LOCK_TOOL_REQUIRED`: bootstrap lock tool required.
 - `CONFIGURATION_INSTALL_FAILED`: configuration install failed.
 - `FLEET_APPROVED_BOOTSTRAP_UNAVAILABLE`: fleet approved bootstrap unavailable.
 - `FLEET_STATE_PATH_UNSAFE`: fleet state path unsafe.
-- `MACOS_ARCHITECTURE_UNSUPPORTED`: macos architecture unsupported. **Needs a person.**
-- `MACOS_BASELINE_MISMATCH`: macos baseline mismatch. **Needs a person.**
 - `PLATFORM_UNSUPPORTED`: platform unsupported. **Needs a person.**
 - `REMOTE_BOOTSTRAP_EVIDENCE_INVALID`: remote bootstrap evidence invalid.
 - `REMOTE_BOOTSTRAP_EXIT_FAILED`: remote bootstrap exit failed.
 - `ROOT_DEVELOPMENT_USER_REJECTED`: root development user rejected.
 - `UBUNTU_ARCHITECTURE_UNSUPPORTED`: ubuntu architecture unsupported. **Needs a person.**
-- `XCODE_COMMAND_LINE_TOOLS_REQUIRED`: xcode command line tools required. **Needs a person.**
+- `WORKER_ENVIRONMENT_UNSUPPORTED`: worker environment unsupported: a container or WSL2. **Needs a person.**
 
 ## Ubuntu packages
 

package/docs/support-matrix.md

@@ -0,0 +1,36 @@
+# Support matrix
+
+Which platforms dev-fleet runs on, in which role, and what happens to the
+rest. The default is one macOS manager and Ubuntu workers treated as cattle.
+
+- **supported**: converged, measured and tested on every pull request.
+- **best effort**: works and is not tested as a fleet role.
+- **refused**: stopped with the named reason before anything is installed.
+
+<!-- Generated by `bun src/machine/support-matrix.ts` from ansible/macos/policy.json, ansible/ubuntu/policy.json and ansible/platforms.json; features/rules/support-matrix.feature fails when it differs. -->
+
+| Role           | Platform  | Versions            | Architectures   | Status      | Note                                                                                      |
+| -------------- | --------- | ------------------- | --------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| manager        | macOS     | 14 or newer         | arm64, x86_64   | supported   | ansible/macos/policy.json                                                                 |
+| worker         | Ubuntu    | 26.04 (resolute)    | amd64, arm64    | supported   | ansible/ubuntu/policy.json; a machine of its own, physical or virtual                     |
+| manager        | any other | any                 | any             | refused     | The fleet configuration accepts only a macOS manager.                                     |
+| worker         | Ubuntu    | any other release   | any             | refused     | UBUNTU_BASELINE_MISMATCH                                                                  |
+| worker         | Ubuntu    | an accepted release | any other       | refused     | UBUNTU_BASELINE_MISMATCH                                                                  |
+| worker         | Debian    | any                 | any             | refused     | UBUNTU_BASELINE_MISMATCH                                                                  |
+| worker         | macOS     | any                 | any             | refused     | The fleet configuration accepts only Linux workers.                                       |
+| worker         | Windows   | any                 | any             | refused     | The fleet configuration accepts only Linux workers.                                       |
+| worker         | WSL2      | any                 | any             | refused     | WORKER_ENVIRONMENT_UNSUPPORTED                                                            |
+| worker         | container | any                 | any             | refused     | WORKER_ENVIRONMENT_UNSUPPORTED                                                            |
+| toolchain only | macOS     | any                 | arm64, x86_64   | best effort | No fleet role: devfleet bootstrap installs the pinned tools (docs/machine-setup.md).      |
+| toolchain only | Linux     | any                 | x86_64, aarch64 | best effort | No fleet role: devfleet bootstrap installs the pinned tools (docs/machine-setup.md).      |
+| toolchain only | WSL2      | any                 | x86_64          | best effort | Treated as Linux: devfleet bootstrap installs the pinned tools (docs/machine-setup.md).   |
+| toolchain only | Windows   | any                 | x64             | best effort | No fleet role: bootstrap/bootstrap.ps1 installs the pinned tools (docs/machine-setup.md). |
+| toolchain only | Alpine    | any                 | any             | refused     | musl: the pinned mise build needs glibc.                                                  |
+
+A worker is refused by the first check that can tell: the fleet configuration
+refuses a worker that is not Linux, the platform probe refuses another
+release, CPU or environment (`ubuntu:release`, `platform:environment`), and
+the bootstrap and the Ubuntu baseline refuse them again on the machine.
+
+Supporting another platform means adding it to the policy that names it, with
+its package pins, a fresh-box job and its row here.

package/docs/ubuntu-sync.md

@@ -61,10 +61,9 @@ resolve enrolled fleet
 
 Bare invocation selects every canonical Linux and macOS node. It does not mean
 “this computer,” and the manager is not implicitly a deployment target. Its own
-node is targeted only if explicitly declared in Fleet membership. Ubuntu 26.04 is
-the accepted worker platform; a node declared `"os": "macOS"` runs the same phases
-best effort through `ansible/macos` (see the platform matrix below).
-Windows machines stay declared for diagnostics and are never converged.
+node is targeted only if explicitly declared in Fleet membership. Workers are the
+Ubuntu releases the [support matrix](support-matrix.md) lists; it also says what
+is refused (macOS and Windows workers, WSL2, containers) and why.
 `--node ID` filters troubleshooting/rollout. `--all` is an explicit spelling of the
 default. Neither flag authorizes managing arbitrary Tailscale peers.
 
@@ -217,9 +216,12 @@ provider configuration: agent profiles are applied by `fleet-sync`. See
 
 ## Ubuntu and remote-work safety
 
-The declared common baseline is Ubuntu **26.04 LTS**, amd64/arm64. Other releases
-receive `UBUNTU_BASELINE_MISMATCH`; there is no automatic release upgrade or
-package downgrade. Fleet audits release, packages, service state and dpkg
+The accepted releases are named once, in `ansible/ubuntu/policy.json`, and
+listed in the [support matrix](support-matrix.md). Other releases receive
+`UBUNTU_BASELINE_MISMATCH`, and WSL2 and containers
+`WORKER_ENVIRONMENT_UNSUPPORTED`; there is no automatic release upgrade or
+package downgrade. Package pins are minimums: see the
+[worker contract](worker-contract.md#package-pins-and-security-updates). Fleet audits release, packages, service state and dpkg
 consistency, declares snapshot sources for managed transactions, and pins its
 selected APT packages. Unrelated applications and package sources are preserved.
 

package/docs/worker-contract.md

@@ -12,7 +12,8 @@ devfleet fleet-status --workers
 ```
 
 The manager needs Node/npm, Git, SSH, Tailscale, and its own authorized T3 link.
-Initially each Ubuntu 26.04 worker (or best-effort macOS 14+ node) needs a
+Initially each worker (an Ubuntu release the [support matrix](support-matrix.md)
+lists) needs a
 designated non-root account, trusted SSH access and administrator authorization. Standard Ubuntu cloud-image users
 already commonly have noninteractive sudo; otherwise establish the repository's
 `authorize-sudo.sh` policy once during administrator enrollment. Routine commands
@@ -39,6 +40,32 @@ HEAD. Private rosters contain connection paths and identities, not weaker policy
 | No routine password prompts        | Verified BatchMode SSH, `sudo -n`, source-owned NOPASSWD policy; missing initial authorization is a failure                                                                                                |
 | Keep service authorization alive   | Native service credentials stay per-node; Vault self-renewal timer and GitHub recovery from authorized Vault credentials; expiring T3 links are reported before expiry                                     |
 
+## Package pins and security updates
+
+A pin in `ansible/ubuntu/policy.json` is a **minimum**, never a hold. Ubuntu
+keeps installing security updates by itself, and a worker is not turned red by
+one:
+
+- The Ubuntu baseline installs a pinned package from the snapshot only when it
+  is absent or older than its pin, and never downgrades
+  (`ansible/ubuntu/tasks/install.yml`; every pinned package, `systemd-oomd`
+  included, goes through it).
+- What Ubuntu installs unattended is declared in
+  `/etc/apt/apt.conf.d/52personal-fleet-unattended-upgrades`: security updates
+  only, no automatic reboot, no removals.
+- `worker:package:NAME` passes at the pin, **warns** with
+  `PACKAGE_NEWER_THAN_PIN` above it, and fails with `PACKAGE_BELOW_PIN` below
+  it or when the package is missing. A warning does not block convergence or
+  readiness; it says the pin can be raised when the snapshot moves.
+- Tailscale follows the same rule: a newer Tailscale is kept; an older one
+  stops with `TAILSCALE_UPGRADE_PENDING`, because upgrading an active VPN can
+  drop SSH.
+
+A package run cut off by a power loss is finished by the next sync: the
+baseline waits for the APT lock, runs `dpkg --configure -a` once (bounded to
+ten minutes) and audits again; only a database still inconsistent stops with
+`APT_STATE_BROKEN`.
+
 Health does not mutate configuration, renew tokens, log in, install software, or
 make billable inference requests. It audits the immutable desired worker deployment,
 not an unrelated developer branch. Every declared worker must be enrolled and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/dev-fleet",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Keeps a set of development machines in sync: one manager and many workers",
   "license": "MIT",
   "repository": "github:crvouga/dev-fleet",
@@ -72,5 +72,5 @@
   "engines": {
     "node": ">=22"
   },
-  "gitHead": "f2813f818b062ed53335afbeee8f67de3b3ac4d4"
+  "gitHead": "620b8de05d662b4dc9072457580ca4b4eab54242"
 }

package/schema/check-ids.json

@@ -174,10 +174,6 @@
       "id": "login:*",
       "meaning": "A native per-machine login is in place."
     },
-    {
-      "id": "macos:release",
-      "meaning": "The manager runs a supported macOS release."
-    },
     {
       "id": "manager:docker",
       "meaning": "The manager runs the pinned Docker Desktop."
@@ -202,6 +198,10 @@
       "id": "notify:configured",
       "meaning": "Every notification target fleet.json names has its address available as a secret."
     },
+    {
+      "id": "platform:environment",
+      "meaning": "The worker runs on a physical or virtual machine of its own, not in a container or WSL2."
+    },
     {
       "id": "platform:unsupported",
       "meaning": "The machine runs a supported operating system."
@@ -486,6 +486,10 @@
       "id": "worker:github-principal",
       "meaning": "The worker's GitHub login is the declared account."
     },
+    {
+      "id": "worker:package:*",
+      "meaning": "The pinned Ubuntu package is installed at or past its pin."
+    },
     {
       "id": "worker:power-loss-recovery",
       "meaning": "The worker powers on after AC loss."