@crvouga/dev-fleet 0.0.0-stage → 0.2.0

package/bootstrap/doctor.ts

@@ -0,0 +1,234 @@
+import { workerTools } from './worker-tools';
+/** Read-only toolchain checks; no logins, installations or changes to Docker. */
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
+import {
+  AGENT_WORKTREE_ROOTS,
+  globalConfigDir,
+  globalConfigStanding,
+  workspaceRoot,
+  type GlobalConfigStanding,
+} from './global-config';
+
+type Tool = string | { version: string; lazy?: boolean; os?: string[] };
+type Config = {
+  tools: Record<string, Tool>;
+  vars?: { worker_tools?: unknown };
+};
+export type Check = {
+  id: string;
+  status: 'pass' | 'warn' | 'fail';
+  detail: string;
+};
+export type Runner = (command: string[]) => { ok: boolean; output: string };
+const COMMANDS: Record<string, string> = {
+  'npm:@yarnpkg/cli-dist': 'yarn',
+  'npm:vercel': 'vercel',
+  'npm:wrangler': 'wrangler',
+  'aqua:anomalyco/opencode': 'opencode',
+  'docker-cli': 'docker',
+  opentofu: 'tofu',
+  ripgrep: 'rg',
+  rust: 'rustc',
+  'npm:@devcontainers/cli': 'devcontainer',
+  'http:grok': 'grok',
+  'http:antigravity': 'antigravity',
+};
+const VERSION_ARGS: Record<string, string[]> = {
+  go: ['version'],
+  gitleaks: ['version'],
+  kubectl: ['version', '--client=true', '--output=json'],
+  helm: ['version', '--short'],
+};
+const run: Runner = (command) => {
+  const result = spawnSync(command[0]!, command.slice(1), {
+    encoding: 'utf8',
+    timeout: 30_000,
+    windowsHide: true,
+    cwd: tmpdir(),
+  });
+  return {
+    ok: result.status === 0,
+    output: `${result.stdout ?? ''}${result.stderr ?? ''}`.trim(),
+  };
+};
+
+/** mise's `os` names for the platforms it installs a tool on. */
+const MISE_OS: Record<string, string> = {
+  darwin: 'macos',
+  linux: 'linux',
+  win32: 'windows',
+};
+/** Installed on Windows by a native installer (native-aws.ts), not by mise. */
+const NATIVE_WINDOWS = new Set(['aws']);
+
+function unavailable(id: string, tool: Tool, platform: string): boolean {
+  if (typeof tool === 'string' || !tool.os) return false;
+  if (platform === 'win32' && NATIVE_WINDOWS.has(id)) return false;
+  return !tool.os.includes(MISE_OS[platform] ?? platform);
+}
+
+export function toolChecks(
+  tools: Record<string, Tool>,
+  execute: Runner = run,
+  platform: string = process.platform
+): Check[] {
+  const checks: Check[] = [];
+  for (const [id, tool] of Object.entries(tools)) {
+    if (typeof tool !== 'string' && tool.lazy) continue;
+    // A tool pinned only for other platforms has no artifact to verify here.
+    if (unavailable(id, tool, platform)) continue;
+    const version = typeof tool === 'string' ? tool : tool.version;
+    const command = COMMANDS[id] ?? id;
+    const result = execute([command, ...(VERSION_ARGS[id] ?? ['--version'])]);
+    const exact = new RegExp(
+      `(?:^|[^0-9])${version.replaceAll('.', '\\.')}($|(?![0-9]|\\.[0-9]))`
+    );
+    const matches = result.ok && exact.test(result.output);
+    checks.push({
+      id,
+      status: matches ? 'pass' : 'fail',
+      detail: matches
+        ? version
+        : `Expected ${command} ${version}; run dev-fleet tools sync and reopen the shell. Check for competing PATH entries.`,
+    });
+  }
+  for (const command of ['git', 'npm']) {
+    const result = execute([command, '--version']);
+    checks.push({
+      id: command,
+      status: result.ok ? 'pass' : 'fail',
+      detail: result.ok
+        ? result.output
+        : `Missing ${command}; rerun the OS bootstrap.`,
+    });
+  }
+  return checks;
+}
+
+export function dockerChecks(
+  required: boolean,
+  execute: Runner = run
+): Check[] {
+  return [
+    ['docker-engine', ['docker', 'info', '--format', '{{.ServerVersion}}']],
+    ['docker-compose', ['docker', 'compose', 'version']],
+    ['docker-buildx', ['docker', 'buildx', 'version']],
+  ].map(([id, command]) => {
+    const result = execute(command as string[]);
+    return {
+      id: id as string,
+      status: result.ok ? 'pass' : required ? 'fail' : 'warn',
+      detail: result.ok
+        ? result.output
+        : 'Install/start Docker Desktop or Docker Engine with Compose + Buildx. See docs/machine-setup.md.',
+    };
+  });
+}
+
+/** Agent worktree roots must be trusted, or every mise shim fails there. */
+export function worktreeTrustCheck(
+  execute: Runner = run,
+  home: string = homedir()
+): Check {
+  const expand = (path: string) =>
+    path === '~' || path.startsWith('~/') ? home + path.slice(1) : path;
+  const result = execute(['mise', 'settings', 'get', 'trusted_config_paths']);
+  let trusted: string[] = [];
+  try {
+    const parsed: unknown = result.ok ? JSON.parse(result.output) : [];
+    if (Array.isArray(parsed))
+      trusted = parsed.filter((p): p is string => typeof p === 'string');
+  } catch {
+    trusted = [];
+  }
+  const have = new Set(trusted.map(expand));
+  const missing = AGENT_WORKTREE_ROOTS.filter(
+    (root) => !have.has(expand(root))
+  );
+  return {
+    id: 'agent-worktree-trust',
+    status: missing.length ? 'fail' : 'pass',
+    detail: missing.length
+      ? `mise does not trust ${missing.join(', ')}; agent CLIs fail in new worktrees there. Run dev-fleet tools sync.`
+      : AGENT_WORKTREE_ROOTS.join(', '),
+  };
+}
+
+const STANDING: Record<GlobalConfigStanding, string> = {
+  published: 'Published by dev-fleet from this revision.',
+  missing: 'There is no global mise configuration.',
+  replaced:
+    'Another project or tool replaced the global mise configuration dev-fleet publishes.',
+  changed:
+    'The global mise configuration is not the one this revision publishes.',
+};
+
+/** On a fleet machine the global mise configuration belongs to dev-fleet.
+ * When anything else replaced it, its pins and the trusted agent worktree
+ * roots are gone until the next fleet-sync.
+ */
+export function globalConfigCheck(
+  dir?: string,
+  root: string = workspaceRoot
+): Check {
+  let standing: GlobalConfigStanding;
+  try {
+    standing = globalConfigStanding(dir ?? globalConfigDir(), root);
+  } catch {
+    return {
+      id: 'global-mise-config',
+      status: 'fail',
+      detail:
+        'MISE_GLOBAL_CONFIG_FILE moves the global mise configuration away from the one dev-fleet publishes; unset it.',
+    };
+  }
+  return {
+    id: 'global-mise-config',
+    status: standing === 'published' ? 'pass' : 'fail',
+    detail:
+      standing === 'published'
+        ? STANDING[standing]
+        : `${STANDING[standing]} Run fleet-sync; projects pin their own tools in a project mise.toml and never publish a global one.`,
+  };
+}
+
+export function checkMachine(requireDocker = false, worker = false): Check[] {
+  const config = Bun.TOML.parse(
+    readFileSync(join(workspaceRoot, 'mise.toml'), 'utf8')
+  ) as Config;
+  const auth = run(['gh', 'auth', 'status']);
+  return [
+    ...toolChecks(
+      worker
+        ? workerTools(config.tools, config.vars?.worker_tools)
+        : config.tools
+    ),
+    ...dockerChecks(requireDocker),
+    worktreeTrustCheck(),
+    globalConfigCheck(),
+    {
+      id: 'github-auth',
+      status: auth.ok ? 'pass' : 'warn',
+      detail: auth.ok
+        ? 'Authenticated'
+        : 'Run gh auth login, then gh auth setup-git.',
+    },
+  ];
+}
+
+if (import.meta.main) {
+  const checks = checkMachine(
+    process.argv.includes('--docker'),
+    process.argv.includes('--worker')
+  );
+  const ok = checks.every((check) => check.status !== 'fail');
+  if (process.argv.includes('--json'))
+    console.log(JSON.stringify({ ok, checks }, null, 2));
+  else
+    for (const check of checks)
+      console.log(`${check.status.toUpperCase()} ${check.id}: ${check.detail}`);
+  process.exitCode = ok ? 0 : 1;
+}

package/bootstrap/fleet-manager-run.sh

@@ -0,0 +1,103 @@
+#!/bin/sh
+# Every fleet-sync on the manager runs through this, whether started there or
+# handed off from a worker over strict SSH. Runs fleet-sync from a clean,
+# fleet-owned checkout of the exact approved revision, so the result never
+# depends on the working tree it was started in (uncommitted edits, another
+# branch, a removed worktree). Checkouts are reused when warm and pruned to the
+# three most recent plus the one T3's providers launch from. Never touches the
+# human's working tree.
+set -eu
+revision=$1
+shift
+case "$revision" in *[!a-f0-9]*|'') exit 2;; esac
+[ "${#revision}" = 40 ] || exit 2
+say() { printf 'fleet-sync (manager): %s\n' "$1" >&2; }
+# A preview (--dry-run) changes nothing outside dev-fleet's own disposable
+# caches: it never publishes the global mise configuration, never edits shell
+# profiles and never prunes run checkouts. Only an apply does.
+preview=false
+for arg in "$@"; do [ "$arg" != --dry-run ] || preview=true; done
+# mise is installed here by the toolchain step below; a login shell is not
+# required to find it.
+export PATH="$HOME/.local/bin:$PATH"
+fleet="$HOME/.local/share/personal/fleet"
+# The repository to take the revision from. Nobody keeps a clone of dev-fleet:
+# fleet-sync names the one it prepared, and a hand-off (which names none) uses
+# the manager's own copy of the source repository, or the checkout the devfleet
+# launcher is linked into.
+repo=${DEVFLEET_REPO:-}
+if [ -z "$repo" ] && git -C "$fleet/manager/source" rev-parse --git-dir >/dev/null 2>&1; then
+  repo="$fleet/manager/source"
+fi
+if [ -z "$repo" ]; then
+  launcher=$(command -v devfleet) || { say 'this manager has no copy of the source yet; run fleet-sync once on the manager itself, from the project that holds your fleet.json.'; exit 3; }
+  repo=$(dirname "$(readlink -f "$launcher")")
+fi
+repo=$(git -C "$repo" rev-parse --show-toplevel) || { say 'cannot read the source repository on the manager; run fleet-sync once on the manager itself to fetch it again.'; exit 3; }
+runs="$fleet/manager-runs"
+dir="$runs/$revision"
+ready() {
+  [ "$(git -C "$dir" rev-parse HEAD 2>/dev/null)" = "$revision" ] &&
+    [ -z "$(git -C "$dir" status --porcelain 2>/dev/null)" ]
+}
+if ! ready; then
+  git -C "$repo" cat-file -e "$revision^{commit}" 2>/dev/null || git -C "$repo" fetch --quiet origin || true
+  git -C "$repo" cat-file -e "$revision^{commit}" 2>/dev/null || git -C "$repo" fetch --quiet --no-tags origin "$revision" || true
+  git -C "$repo" cat-file -e "$revision^{commit}" 2>/dev/null || { say "revision $revision is neither on the manager nor on origin; push it first."; exit 4; }
+  mkdir -p "$runs"
+  chmod 700 "$runs"
+  # A fleet-owned, disposable run checkout: recreate it when stale or dirty.
+  if [ -e "$dir" ]; then git -C "$repo" worktree remove --force "$dir" 2>/dev/null || rm -rf -- "$dir"; fi
+  git -C "$repo" worktree prune
+  git -C "$repo" worktree add --quiet --detach "$dir" "$revision"
+fi
+touch "$dir"
+cd "$dir"
+mise trust --quiet "$dir" >/dev/null 2>&1 || true
+# The manager runs the same locked toolchain (and so the same agent versions)
+# as every worker: publish this revision's global config, install it and the
+# frozen dependencies. Warm: the toolchain is skipped when the same inputs
+# (tool pins, locks, setup code) were installed within a day, so a revision
+# that changes none of them only installs its own dependencies.
+# Stamp and log sit beside the checkout: inside it they would make it dirty.
+stamp="$runs/toolchain-ready"
+log="$runs/$revision.setup.log"
+key=$(git rev-parse HEAD:mise.toml HEAD:mise.lock HEAD:.mise HEAD:bun.lock HEAD:package.json HEAD:bootstrap 2>/dev/null | tr '\n' ' ')
+[ -n "$key" ] || key=$revision
+failed() {
+  tail -n 20 "$log" >&2
+  say "toolchain or dependency install failed in the run checkout; full log: $log"
+  exit 5
+}
+if [ "$preview" = true ]; then
+  # The revision's own locked Bun is enough to preview; mise keeps it beside
+  # its other versions without making it the global one.
+  command -v mise >/dev/null 2>&1 || { say 'this manager has no toolchain yet, so a preview cannot run; fleet-sync without --dry-run installs it.'; exit 6; }
+  mise install --locked bun >"$log" 2>&1 || failed
+elif [ "$(cat "$stamp" 2>/dev/null)" != "$key" ] || [ -z "$(find "$stamp" -mmin -1440 2>/dev/null)" ]; then
+  rm -f -- "$stamp"
+  # The toolchain bootstrap installs the pinned mise first when the manager
+  # has none (or another version), so Git is all a new manager needs.
+  bash bootstrap/bootstrap.sh --tools-only >"$log" 2>&1 || failed
+  printf '%s' "$key" >"$stamp"
+fi
+if [ ! -d node_modules ]; then
+  mise exec --locked bun -- bun install --frozen-lockfile --silent >>"$log" 2>&1 || failed
+fi
+# Keep the three most recent run checkouts (names are commit SHAs) and the
+# applied one: fleet/current points at it and T3's providers launch from there.
+# A preview leaves them for the next apply to prune.
+if [ "$preview" = false ]; then
+  applied=$(basename "$(readlink "$(dirname "$runs")/current" 2>/dev/null || true)")
+  # shellcheck disable=SC2012
+  for old in $(ls -1td "$runs"/*/ | tail -n +4); do
+    [ "$(basename "$old")" != "$applied" ] || continue
+    # A checkout made from another repository (an earlier clone) is not this
+    # repository's worktree: remove the directory itself.
+    git -C "$repo" worktree remove --force "$old" 2>/dev/null || rm -rf -- "$old"
+    rm -f -- "${old%/}.setup.log"
+  done
+  git -C "$repo" worktree prune
+fi
+export PERSONAL_WORKSPACE="$dir" PERSONAL_FLEET_RUN_CHECKOUT="$revision"
+exec mise exec --locked bun -- bun src/cli/cli.ts fleet-sync --revision "$revision" "$@"

package/bootstrap/fleet-remote-bootstrap.sh

@@ -0,0 +1,258 @@
+#!/bin/sh
+# 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.
+set -eu
+umask 077
+revision=$1
+bundle_sha=$2
+node=$3
+source_mode=${4:-transfer}
+case "$source_mode" in cached|transfer) ;; *) 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
+[ "${#bundle_sha}" = 64 ] || exit 2
+case "$node" in *[!a-z0-9-]*|'') exit 2;; esac
+phase=bootstrap
+bundle=''
+code=0
+apt_log=''
+failure_code=REMOTE_BOOTSTRAP_INCOMPLETE
+die() { failure_code=$1; exit 1; }
+# One remedy per failure: what the operator does next. Never raw output.
+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.';;
+    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.';;
+    SUDO_AUTHORIZATION_REQUIRED) echo 'Grant the developer account passwordless sudo, or run fleet-sync interactively once to authorize it.';;
+    APT_LOCK_CONTENDED) echo 'Another package operation held the APT lock past the bounded wait. Let it finish (it is never killed), then rerun fleet-sync.';;
+    APT_DNS_UNAVAILABLE) echo 'The worker cannot resolve the Ubuntu archive. Restore its DNS, then rerun fleet-sync.';;
+    APT_REPOSITORY_UNAVAILABLE) echo 'The Ubuntu archive could not be reached. Check the network or archive status, then rerun fleet-sync.';;
+    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 doctor on the worker.';;
+    *) echo 'Inspect the remote operation lock and rerun the approved revision. No success receipt advanced.';;
+  esac
+}
+# Names an APT failure by the fixed messages of the pinned Ubuntu release.
+apt_failure() {
+  if grep -q 'Could not get lock' "$apt_log" 2>/dev/null; then die APT_LOCK_CONTENDED
+  elif grep -q 'No space left on device' "$apt_log" 2>/dev/null; then die APT_DISK_FULL
+  elif grep -qE 'Temporary failure resolving|Could not resolve' "$apt_log" 2>/dev/null; then die APT_DNS_UNAVAILABLE
+  elif grep -qE 'Failed to fetch|Unable to connect|Connection failed|Unable to locate package' "$apt_log" 2>/dev/null; then die APT_REPOSITORY_UNAVAILABLE
+  elif grep -q 'dpkg was interrupted' "$apt_log" 2>/dev/null; then die DPKG_INTERRUPTED
+  else die "$1"
+  fi
+}
+fail() {
+  printf '{"version":1,"checks":[{"id":"bootstrap:%s","status":"fail","summary":"%s","remedy":{"action":"%s"}}]}\n' "$phase" "$failure_code" "$(remedy "$failure_code")"
+}
+trap 'code=$?; [ -z "$bundle" ] || rm -f -- "$bundle"; [ -z "$apt_log" ] || rm -f -- "$apt_log"; if [ "$code" != 0 ]; then fail; fi' EXIT
+# Preserve the lock holder if its SSH channel disappears mid-install.
+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
+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
+  [ ! -L "$path" ] || die FLEET_STATE_PATH_UNSAFE
+done
+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
+printf '{"version":1,"pid":%s,"revision":"%s","node":"%s"}\n' "$$" "$revision" "$node" >"$root/remote-operation.json"
+# The fleet configuration is installed under the lock, so two overlapping
+# runs never write it at once. It holds no secret.
+phase='configuration-install'
+IFS= read -r configuration || configuration=''
+if [ -n "$configuration" ]; then
+  config_dir="$HOME/.config/dev-fleet"
+  mkdir -p "$config_dir" || die CONFIGURATION_INSTALL_FAILED
+  printf '%s' "$configuration" | base64 -d >"$config_dir/fleet.json.new" || die CONFIGURATION_INSTALL_FAILED
+  mv "$config_dir/fleet.json.new" "$config_dir/fleet.json" || die CONFIGURATION_INSTALL_FAILED
+fi
+phase=resources
+# A bootstrap floor protects source transfer and minimal prerequisites. The
+# Workstation baseline subsequently enforces its stricter declared capacity.
+free_kib=$(df -Pk "$root" | awk 'END {print $4}')
+free_inodes=$(df -Pi "$root" | awk 'END {print $4}')
+case "$free_kib:$free_inodes" in *[!0-9:]*|:*|*:) die BOOTSTRAP_CAPACITY_UNVERIFIED;; esac
+[ "$free_kib" -ge 2097152 ] && [ "$free_inodes" -ge 50000 ] || die BOOTSTRAP_DISK_CAPACITY_REQUIRED
+phase=source-transfer
+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
+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"
+done
+if [ -n "$missing" ]; then
+  sudo -n true >/dev/null 2>&1 || die SUDO_AUTHORIZATION_REQUIRED
+  # APT's own messages, in a private file read only for fixed patterns and
+  # removed on exit: they tell a held lock, DNS, an unreachable archive and a
+  # full disk apart. Nothing of them is reported.
+  apt_log=$(mktemp "$root/apt.XXXXXX")
+  pending="$root/prerequisites-pending"
+  # An installation this script started and that was interrupted (the shell
+  # killed, the machine powered off) leaves dpkg half-configured. Finishing
+  # our own transaction is safe; one fleet-sync did not start is reported.
+  # dpkg reads its database lock even to audit, which needs root.
+  if [ -n "$(sudo -n dpkg --audit 2>/dev/null)" ]; then
+    [ -f "$pending" ] || die DPKG_INTERRUPTED
+    # shellcheck disable=SC2024
+    sudo -n timeout 600 env DEBIAN_FRONTEND=noninteractive LC_ALL=C dpkg --configure -a >"$apt_log" 2>&1 || apt_failure APT_INSTALL_FAILED
+  fi
+  : >"$pending"
+  # The log belongs to the developer account; sudo only runs the command.
+  # shellcheck disable=SC2024
+  # Never remove APT locks or kill package processes. Timeout keeps genuine
+  # transactions bounded; Ubuntu archive signatures/TLS remain enabled.
+  sudo -n timeout 300 env LC_ALL=C apt-get -o DPkg::Lock::Timeout=120 update >"$apt_log" 2>&1 || apt_failure APT_UPDATE_FAILED
+  # shellcheck disable=SC2086,SC2024
+  sudo -n timeout 600 env DEBIAN_FRONTEND=noninteractive LC_ALL=C apt-get -o DPkg::Lock::Timeout=120 --no-install-recommends install -y $missing >>"$apt_log" 2>&1 || apt_failure APT_INSTALL_FAILED
+  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
+mkdir -p "$deployment"
+if [ ! -e "$deployment/.git" ]; then
+  [ -z "$(ls -A "$deployment")" ] || exit 1
+  git -C "$deployment" init -q >/dev/null 2>&1 || exit 1
+fi
+# An interrupted initial fetch or checkout leaves a repository without a
+# commit, possibly with some of the revision's files written. Resume only
+# that state: every file present must be a file of the revision, so the
+# checkout may write over it. An existing commit or other work is never reset.
+if ! git -C "$deployment" rev-parse --verify HEAD >/dev/null 2>&1; then
+  [ "$source_mode" = transfer ] || die SOURCE_CACHE_CHANGED
+  [ "$(git -C "$deployment" rev-parse --show-toplevel)" = "$deployment" ] || exit 1
+  # The bundle holds this commit without its history: declare the checkout
+  # shallow at it so Git accepts a commit whose parents are absent.
+  printf '%s\n' "$revision" >"$deployment/.git/shallow"
+  git -C "$deployment" fetch --no-tags "$bundle" "$revision" >/dev/null 2>&1 || exit 1
+  present=$(mktemp "$root/present.XXXXXX")
+  expected=$(mktemp "$root/expected.XXXXXX")
+  git -C "$deployment" -c core.quotePath=false ls-files --others | LC_ALL=C sort >"$present" || { rm -f -- "$present" "$expected"; die SOURCE_STATUS_FAILED; }
+  git -C "$deployment" -c core.quotePath=false ls-tree -r --name-only "$revision" | LC_ALL=C sort >"$expected" || { rm -f -- "$present" "$expected"; die SOURCE_STATUS_FAILED; }
+  foreign=$(LC_ALL=C comm -23 "$present" "$expected")
+  rm -f -- "$present" "$expected"
+  [ -z "$foreign" ] || die SOURCE_CHECKOUT_CONFLICT
+  git -C "$deployment" checkout --force --detach "$revision" >/dev/null 2>&1 || exit 1
+fi
+[ -z "$bundle" ] || rm -f "$bundle"
+bundle=''
+[ "$(git -C "$deployment" rev-parse HEAD)" = "$revision" ] || exit 1
+[ "$(git -C "$deployment" rev-parse --show-toplevel)" = "$deployment" ] || exit 1
+clean=$(git -C "$deployment" status --porcelain) || die SOURCE_STATUS_FAILED
+[ -z "$clean" ] || die SOURCE_CHECKOUT_CONFLICT
+phase=toolchain
+cd "$deployment"
+export PATH="$HOME/.local/bin:$HOME/.local/share/mise/shims:/usr/local/bin:/usr/bin:/bin"
+status_file="$root/toolchain-status.json"
+ready_file="$root/toolchain-ready"
+[ ! -L "$status_file" ] && [ ! -L "$ready_file" ] || die FLEET_STATE_PATH_UNSAFE
+# Warm: the same toolchain inputs (tool pins, locks and the setup code itself)
+# passed within a day, so a revision that changes none of them skips the full
+# setup. Changed inputs, a failure or an older stamp run it; agent versions
+# are still checked (and reinstalled on drift) by node convergence.
+toolchain_key=$(git rev-parse HEAD:mise.toml HEAD:mise.lock HEAD:.mise HEAD:bun.lock HEAD:package.json HEAD:bootstrap 2>/dev/null | tr '\n' ' ')
+[ -n "$toolchain_key" ] || toolchain_key=$revision
+if [ "$(cat "$ready_file" 2>/dev/null)" = "$toolchain_key" ] && [ -n "$(find "$ready_file" -mmin -1440 2>/dev/null)" ]; then
+  toolchain_warm=1
+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
+# shellcheck disable=SC2086
+if [ -z "$toolchain_warm" ] && ! $bounded bash bootstrap/bootstrap.sh --worker --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=''
+  case "$tool_phase" in
+    managed-config) die TOOLCHAIN_CONFIG_CONFLICT;;
+    mise) die TOOLCHAIN_MISE_FAILED;;
+    aws) die TOOLCHAIN_AWS_FAILED;;
+    t3) die TOOLCHAIN_T3_FAILED;;
+    global-config|shell) die TOOLCHAIN_PATH_CONFIGURATION_FAILED;;
+    dependencies) die TOOLCHAIN_FROZEN_DEPENDENCIES_FAILED;;
+    *) die TOOLCHAIN_CONVERGENCE_FAILED;;
+  esac
+fi
+# A new revision's checkout still needs its own (cached, frozen) dependencies.
+if [ -n "$toolchain_warm" ] && [ ! -d node_modules ]; then
+  # shellcheck disable=SC2086
+  $bounded mise exec --locked bun -- bun install --frozen-lockfile >/dev/null 2>&1 || die TOOLCHAIN_FROZEN_DEPENDENCIES_FAILED
+fi
+[ -n "$toolchain_warm" ] || printf '%s' "$toolchain_key" >"$ready_file"
+# Every synced revision is a full checkout with its own dependencies (about
+# 1 GB). Keep this one, the one T3's providers launch from and the two most
+# recently used others; the rest would slowly fill the disk.
+phase=cleanup
+touch "$deployment"
+applied=$(basename "$(readlink "$root/current" 2>/dev/null || true)")
+kept=0
+# shellcheck disable=SC2012
+for old in $(ls -1t "$root/revisions"); do
+  case "$old" in *[!a-f0-9]*) continue;; esac
+  [ "${#old}" = 40 ] || continue
+  [ "$old" != "$revision" ] && [ "$old" != "$applied" ] || continue
+  kept=$((kept + 1))
+  [ "$kept" -gt 2 ] || continue
+  rm -rf -- "${root:?}/revisions/$old" || true
+done
+phase=configuration
+trap - EXIT INT TERM
+exec mise exec --locked bun -- bun src/node-converge.ts "$node" "$revision"