@crvouga/dev-fleet 0.3.0 → 0.5.0

package/bootstrap/worker-tools.ts

@@ -1,3 +1,7 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
 /** A worker installs only this declared subset; every version still comes from mise.lock. */
 export function workerTools<T>(
   tools: Record<string, T>,
@@ -22,3 +26,117 @@ export function workerTools<T>(
     selected.map((key: string) => [key, tools[key]!])
   ) as Record<string, T>;
 }
+
+/** Named tool sets a fleet adds to its workers on top of the base set
+ * (`worker_tools`). Each is `worker_profile_<name>` under [vars] in
+ * mise.toml; every version still comes from mise.lock.
+ */
+export const TOOL_PROFILES = ['web', 'go', 'rust', 'jvm'] as const;
+export type ToolProfile = (typeof TOOL_PROFILES)[number];
+
+/** What a fleet configuration adds to one worker's base tools: profiles and
+ * single tools, each already pinned in mise.toml.
+ */
+export interface ToolSelection {
+  profiles: string[];
+  tools: string[];
+}
+export const NO_SELECTION: ToolSelection = { profiles: [], tools: [] };
+
+const list = (value: unknown): string[] =>
+  Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === 'string')
+    : [];
+const record = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** The selection a fleet configuration makes for one worker: the fleet-wide
+ * `worker.toolProfiles` and `worker.tools`, plus that worker's own
+ * `toolProfiles`. Read from the plain document, so the bootstrap needs no
+ * fleet code.
+ */
+export function workerSelection(
+  definition: unknown,
+  node?: string
+): ToolSelection {
+  if (!record(definition)) return NO_SELECTION;
+  const policy = record(definition['worker']) ? definition['worker'] : {};
+  const workers: unknown[] = Array.isArray(definition['workers'])
+    ? definition['workers']
+    : [];
+  const own = workers
+    .filter(record)
+    .filter((entry) => node !== undefined && entry['id'] === node)
+    .flatMap((entry) => list(entry['toolProfiles']));
+  return {
+    profiles: [...new Set([...list(policy['toolProfiles']), ...own])],
+    tools: [...new Set(list(policy['tools']))],
+  };
+}
+
+/** The selection of the fleet configuration fleet-sync installed on this
+ * machine; none when there is no configuration yet.
+ */
+export function installedSelection(
+  node: string | undefined,
+  home: string = homedir()
+): ToolSelection {
+  const path = join(home, '.config/dev-fleet/fleet.json');
+  if (!existsSync(path)) return NO_SELECTION;
+  try {
+    return workerSelection(JSON.parse(readFileSync(path, 'utf8')), node);
+  } catch {
+    return NO_SELECTION;
+  }
+}
+
+/** The tools of one worker: the base set, then each selected profile's, then
+ * the single tools, in that order and each once. A profile mise.toml does not
+ * declare, or a tool it does not pin, is refused.
+ */
+export function workerToolset<T>(
+  tools: Record<string, T>,
+  vars: Record<string, unknown>,
+  selection: ToolSelection = NO_SELECTION
+): Record<string, T> {
+  const names = (value: unknown) =>
+    typeof value === 'string' ? value.split(',').filter(Boolean) : [];
+  const base = names(vars['worker_tools']);
+  const added = selection.profiles.flatMap((profile) => {
+    const declared = vars[`worker_profile_${profile}`];
+    if (typeof declared !== 'string' || !declared)
+      throw new Error(
+        `Unknown worker tool profile "${profile}". Choose from ${TOOL_PROFILES.join(', ')}.`
+      );
+    return names(declared);
+  });
+  for (const tool of selection.tools)
+    if (!Object.hasOwn(tools, tool))
+      throw new Error(
+        `The worker tool "${tool}" has no pin in dev-fleet's mise.toml. Ask for it in an issue.`
+      );
+  return workerTools(tools, [
+    ...new Set([...base, ...added, ...selection.tools]),
+  ]);
+}
+
+/** `--profiles web,go --tools fd` for the doctor and the setup. */
+export function selectionArguments(selection: ToolSelection): string[] {
+  return [
+    ...(selection.profiles.length
+      ? ['--profiles', selection.profiles.join(',')]
+      : []),
+    ...(selection.tools.length ? ['--tools', selection.tools.join(',')] : []),
+  ];
+}
+
+/** The selection named by `--profiles` and `--tools`. */
+export function parseSelectionArguments(argv: string[]): ToolSelection {
+  const value = (flag: string) => {
+    const index = argv.indexOf(flag);
+    return index < 0
+      ? []
+      : (argv[index + 1] ?? '').split(',').filter((item) => item.length > 0);
+  };
+  return { profiles: value('--profiles'), tools: value('--tools') };
+}

package/cliproxy/README.md

@@ -150,7 +150,7 @@ devfleet cliproxy inference messages EXACT_CLAUDE_MODEL_ID
 
 **Account routing.** Credential files are the only list of accounts. `ops declared` (run by every fleet-sync) gives each Claude, Codex and Antigravity credential the model prefix `<type>-<email>` through the proxy's management API (`scripts/accounts.py`; a credential file is never edited directly). A request for `<type>-<email>/<model>` is served only by that account, and `/v1/models` lists those ids, which is how every fleet node discovers the accounts to offer in T3. Nothing in Git names an account.
 
-Unprefixed routing is **fill-first** (`routing.strategy: fill-first`): one account serves until its quota is exhausted and it cools down, then the next account, with session affinity keeping a session on its account while available and bounded retries across eligible accounts for the requested model. `cliproxy apply` requires this policy and the host monitor reports drift; see [Multi-account routing](docs/model-health.md#multi-account-routing-fill-first) for applying it to a running proxy. Automatic preview-model switching is disabled. No model aliases are configured: clients use the upstream model ids exactly as `/v1/models` lists them. [`models.json`](models.json) declares the model ids that are health-checked (`claude-opus-5-5`, `claude-sonnet-5-5`, `gpt-6-astra`, `gpt-6.1-sol`), and the checks fail loudly when one is not served. Usage statistics are enabled but are not a durable billing ledger. Available quota details depend on the provider.
+Unprefixed routing is **fill-first** (`routing.strategy: fill-first`): one account serves until its quota is exhausted and it cools down, then the next account, with session affinity keeping a session on its account while available and bounded retries across eligible accounts for the requested model. `cliproxy apply` requires this policy and the host monitor reports drift; see [Multi-account routing](docs/model-health.md#multi-account-routing-fill-first) for applying it to a running proxy. Automatic preview-model switching is disabled. The only model aliases are the ones `config.template.yaml` declares under `oauth.model-alias` (`ops` applies them and waits until `/v1/models` serves them); every other model id is the upstream id exactly as `/v1/models` lists it. [`models.json`](models.json) declares the model ids that are health-checked (`claude-opus-5-5`, `claude-sonnet-5-5`, `gpt-6-astra`, `gpt-6.1-sol`), and the checks fail loudly when one is not served. Usage statistics are enabled but are not a durable billing ledger. Available quota details depend on the provider.
 
 ## Fleet clients: macOS, Ubuntu and Windows/WSL
 

package/cliproxy/compose.yaml

@@ -3,6 +3,10 @@ services:
   proxy:
     image: ${CLI_PROXY_IMAGE:?image must be pinned}
     restart: unless-stopped
+    # Docker restarts a proxy that exits; the container watchdog on the
+    # manager restarts one that stays unhealthy.
+    labels:
+      dev.devfleet.watchdog: restart
     user: '${CLIPROXY_UID:-1000}:${CLIPROXY_GID:-1000}'
     working_dir: /state
     command: ['/CLIProxyAPI/CLIProxyAPI', '-config', '/state/config.yaml']

package/cliproxy/scripts/checkpoint.py

@@ -68,7 +68,7 @@ def validate(root):
         raise ValueError("Provider cache directory missing")
     for path in (state / "runtime/auths").iterdir():
         if path.name == "kv.db" and path.is_file() and path.stat().st_size > 0:
-            continue  # Opaque upstream bbolt state, captured while the process is stopped.
+            continue  # Opaque upstream bbolt state, copied while the proxy runs (see capture).
         # .json: provider credential; .cds: upstream per-account cooldown
         # records (JSON object, no credential), kept so limits survive moves.
         if path.suffix not in (".json", ".cds") or not path.is_file():

package/docs/authentication.md

@@ -0,0 +1,90 @@
+# Authentication and accounts
+
+Where each credential dev-fleet uses lives, who can read it, how it reaches
+each node, how it rotates and what happens when it fails. The three tables
+are generated from the code; `features/rules/authentication.feature` fails
+when one is out of date (`DEVFLEET_UPDATE_DOCS=1 bun test features/rules`
+rewrites them).
+
+## Where credentials live
+
+| Credential                          | Lives in                                                                                                                      | Read by                                          |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| The fleet's secrets (table below)   | The provider `secrets` names in `fleet.json`                                                                                  | The node that needs it, through `src/secrets.ts` |
+| The bucket's two keys               | The environment of the `devfleet` command; `~/.config/dev-fleet/bucket.json` (0600) on the manager after `fleet-state --init` | The manager only                                 |
+| A node's Vault token                | That node's own Vault session (`~/.vault-token`)                                                                              | That node only; never copied                     |
+| A node's GitHub login               | `gh`'s own store on that node                                                                                                 | `gh`, and git through its credential helper      |
+| Provider accounts (Claude, Codex …) | The CLI proxy's store on the manager                                                                                          | The proxy; nodes hold only the proxy client key  |
+| Tailscale and T3 pairing            | Each machine, signed in by a person                                                                                           | That machine                                     |
+
+## How they reach each node
+
+- **Vault.** A person logs each machine in once (`fleet-sync` asks on the
+  manager and passes the password to the worker over SSH on standard input).
+  From then on the worker's `personal-worker-auth` timer renews its own token
+  (`bootstrap/worker-auth.ts`). Nothing renders provider configuration from
+  Vault on a worker: agent profiles come from `fleet-sync`.
+- **GitHub.** The same job restores the declared account (`worker.githubLogin`)
+  with the GitHub service token it reads from its own Vault session
+  (`bootstrap/worker-github.ts`, on standard input, never argv). `fleet-sync`
+  makes `gh` git's credential helper and writes the declared identity
+  (`git` in `fleet.json`, `ansible/github/git.yml`) on every node.
+- **The proxy client key** is read by each node from its own secrets provider
+  whenever a launcher starts an agent.
+- **The monitoring hub's backup storage keys** are read on the manager by
+  `fleet-sync` and handed to the hub's playbook in a private variables file.
+
+## Rotation and failure
+
+Rotate a secret where the provider keeps it; the next read uses it, nothing
+caches it. A Vault token that is not renewed expires: `worker:vault-renewal`
+fails and the fix is one login of that machine. A GitHub token that stops
+working fails `auth:github` and `worker:git-push-auth`; store the new one in
+Vault and the worker restores itself within ten minutes. During a proxy
+outage agents on workers wait: no worker is configured for native clients.
+Every failure code is in [the runbooks](runbooks.md).
+
+## The fleet's secrets
+
+<!-- generated: secrets -->
+
+| Secret                         | Required                     | `env` provider variable                        | `file` provider file                                       |
+| ------------------------------ | ---------------------------- | ---------------------------------------------- | ---------------------------------------------------------- |
+| `proxy-client-key`             | yes                          | `DEVFLEET_SECRET_PROXY_CLIENT_KEY`             | `~/.config/dev-fleet/secrets/proxy-client-key`             |
+| `monitoring-account-password`  | yes                          | `DEVFLEET_SECRET_MONITORING_ACCOUNT_PASSWORD`  | `~/.config/dev-fleet/secrets/monitoring-account-password`  |
+| `monitoring-tunnel-token`      | yes                          | `DEVFLEET_SECRET_MONITORING_TUNNEL_TOKEN`      | `~/.config/dev-fleet/secrets/monitoring-tunnel-token`      |
+| `proxy-tunnel-token`           | yes                          | `DEVFLEET_SECRET_PROXY_TUNNEL_TOKEN`           | `~/.config/dev-fleet/secrets/proxy-tunnel-token`           |
+| `monitoring-backup-access-key` | when its feature is declared | `DEVFLEET_SECRET_MONITORING_BACKUP_ACCESS_KEY` | `~/.config/dev-fleet/secrets/monitoring-backup-access-key` |
+| `monitoring-backup-secret-key` | when its feature is declared | `DEVFLEET_SECRET_MONITORING_BACKUP_SECRET_KEY` | `~/.config/dev-fleet/secrets/monitoring-backup-secret-key` |
+| `notify-webhook-url`           | when its feature is declared | `DEVFLEET_SECRET_NOTIFY_WEBHOOK_URL`           | `~/.config/dev-fleet/secrets/notify-webhook-url`           |
+| `notify-ntfy-url`              | when its feature is declared | `DEVFLEET_SECRET_NOTIFY_NTFY_URL`              | `~/.config/dev-fleet/secrets/notify-ntfy-url`              |
+
+<!-- end: secrets -->
+
+## Checks of credentials
+
+<!-- generated: checks -->
+
+| Check                         | Measured in                                |
+| ----------------------------- | ------------------------------------------ |
+| `auth:vault`                  | `src/cli/fleet-sync-vault.ts`              |
+| `worker:git-identity`         | `src/git-identity.ts`                      |
+| `worker:git-push-auth`        | `src/definition.ts`, `src/git-identity.ts` |
+| `worker:github-principal`     | `src/worker-access-checks.ts`              |
+| `worker:proxy-authentication` | `src/worker-access-checks.ts`              |
+| `worker:vault-renewal`        | `src/worker-access-checks.ts`              |
+
+<!-- end: checks -->
+
+## Timers
+
+<!-- generated: timers -->
+
+| Timer                            | Declared in                            | Schedule                              |
+| -------------------------------- | -------------------------------------- | ------------------------------------- |
+| `personal-fleet-disk-gc.timer`   | `ansible/ubuntu/tasks/resources.yml`   | OnBootSec=10min, OnCalendar=hourly    |
+| `personal-worker-auth.timer`     | `ansible/ubuntu/tasks/credentials.yml` | OnBootSec=2min, OnUnitActiveSec=10min |
+| `personal-worker-recovery.timer` | `ansible/ubuntu/tasks/recovery.yml`    | OnBootSec=1min, OnUnitActiveSec=1min  |
+| `personal-worker-recovery.timer` | `ansible/ubuntu/tasks/recovery.yml`    | OnBootSec=5min, OnUnitActiveSec=15min |
+
+<!-- end: timers -->

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

@@ -31,6 +31,8 @@ may only shrink.
 | Ansible on a worker                           | `ansible-core` in `ansible/ubuntu/policy.json`                                                      | Exact version                                                        | `ansible/ubuntu/tasks/packages.yml`                       | `package:ansible-core`                       |
 | The CLI proxy                                 | `cliproxy/compose.yaml`, `image.lock.json`, `requirements.lock`, `launchd/`, `config.template.yaml` | Image digests; hashed Python dependencies                            | `devfleet cliproxy install`, and `fleet-sync` after it    | The proxy's audit                            |
 | Agent profiles and T3 providers               | `agents/registry.json`, `agents/t3.json`                                                            | The commit                                                           | `fleet-sync`                                              | Profile receipts; the plan after every apply |
+| Worker time service                           | `ansible/ubuntu/tasks/services.yml`, offsets in `clock` in `ansible/ubuntu/policy.json`             | The commit                                                           | `fleet-sync`                                              | `worker:clock`                               |
+| The manager's container watchdog              | `ansible/monitoring/container-watchdog.py`, `containerWatchdog` in `ansible/macos/policy.json`      | The commit                                                           | `fleet-sync` (`hub-darwin.yml`)                           | `manager:container-watchdog`                 |
 | Docker Desktop on the manager                 | `docker_desktop_*` under `[vars]` in `mise.toml`                                                    | Version and build                                                    | You                                                       | `manager:docker` (warns)                     |
 | CI                                            | `.github/workflows/`                                                                                | Each action at a commit; tools from `mise.lock`                      | GitHub                                                    | `features/rules/`                            |
 
@@ -45,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/machine-setup.md

@@ -181,19 +181,21 @@ wrangler login
 railway login
 ```
 
-Only sign into providers the task actually needs. Git identity is personal:
-set `git config --global user.name` and `git config --global user.email` after
-confirming the desired name/email. Do not guess an email or overwrite an existing
-identity. Enable Git LFS hooks when needed with `git lfs install`.
+Only sign into providers the task actually needs. On fleet machines the Git
+identity and the GitHub credential helper come from the `git` block of
+`fleet.json`: `fleet-sync` writes them in `~/.config/git/config` and checks
+them as `worker:git-identity` and `worker:git-push-auth`. Elsewhere set `git
+config --global user.name` and `user.email` after confirming them; do not guess
+an email or overwrite an existing identity. Enable Git LFS hooks when needed with `git lfs install`.
 
 Optional existing workstation/agent settings:
 
 ```sh
 sh bootstrap/install-launcher.sh
-personal workstation doctor
+devfleet fleet-status --local
 # Only for tasks needing the workspace's managed secrets:
 vault login --method=userpass username=example-user
-personal workstation sync
+devfleet fleet-sync
 ```
 
 The machine bootstrap installs tools/dependencies only. `personal:install` additionally
@@ -231,7 +233,7 @@ The manifest installs the **Docker client**. Containers also require a local or
 remote Docker engine, Compose v2 and Buildx plugins. These cannot be installed as
 one identical unprivileged binary on all OSes.
 
-- **macOS:** run `personal workstation tools docker-setup` to install the pinned,
+- **macOS:** run `bash bootstrap/docker-desktop.sh` to install the pinned,
   checksum-verified Docker Desktop bundle from this repository and open it.
   Complete its first-run agreement/setup in the app. Repeated invocation reuses
   an existing installation. The shared mise Docker client remains in use.
@@ -280,11 +282,11 @@ mise install --locked bun
 mise exec --locked bun -- bun bootstrap/setup.ts
 ```
 
-For an installed workstation CLI, `personal workstation update` pulls with a clean-tree/fast-forward
-guard, refreshes the toolchain/global config and frozen dependencies, and runs the
-existing workstation convergence. `personal workstation tools sync` reapplies tool pins/global config
-without pulling or touching project dependencies; `personal workstation tools check --json` verifies
-them. Sync is explicit; Git commits do not silently update other machines.
+On fleet machines `devfleet fleet-sync` refreshes the toolchain, the global
+configuration and frozen dependencies; `mise exec --locked bun -- bun
+bootstrap/setup.ts --tools-only` reapplies tool pins and the global
+configuration without touching project dependencies, and `bun
+bootstrap/doctor.ts --json` verifies them. Sync is explicit; Git commits do not silently update other machines.
 
 For multiple development computers, use [the fleet package](operations.md):
 `devfleet fleet-node-add` registers an existing SSH alias in a local roster,
@@ -395,6 +397,14 @@ It installs the `vars.worker_tools` subset from `mise.toml`, with versions and
 artifacts taken from the same `mise.lock`; native T3 and Ubuntu Docker/service
 policy remain source-pinned. `bun bootstrap/doctor.ts --worker --docker --json`
 checks that profile. It does not require unrelated cloud CLIs on workers.
+
+Tool profiles add locked tool sets on top of it: `worker.toolProfiles` in
+`fleet.json` (fleet-wide) or `toolProfiles` on one worker selects `web` (pnpm,
+Deno, Yarn and headless Chromium for browser tests), `go`, `rust` (with CMake
+and Ninja) or `jvm` (Temurin), each a `worker_profile_<name>` under `[vars]` in
+`mise.toml`. `worker.tools` adds single tools dev-fleet already pins. The setup
+installs them (`--node` reads the installed configuration) and the doctor
+checks each as `tool:<name>` (`--profiles`, `--tools`).
 The source-owned `worker-auth.ts` timer renews the worker's existing Vault token
 and can restore the declared GitHub account from its authorized Vault service
 credential, without copying another machine's login directory.