@sebastienrousseau/dotfiles 0.2.501 → 0.2.502

package/scripts/dot/commands/agents.sh

@@ -0,0 +1,325 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# shellcheck shell=bash
+#
+# scripts/dot/commands/agents.sh
+#
+# `dot agents` — multi-harness AI agent configuration manager.
+#
+# Closes the #1 competitive gap identified in HARD_AUDIT_2026:
+# every other dotfiles framework either targets one AI tool or
+# requires hand-maintenance of N parallel config files. This command
+# keeps CLAUDE.md (canonical) and AGENTS.md (cross-harness standard)
+# in sync, plus stubs the Cursor/Codex tool-specific formats.
+#
+# Subcommands:
+#   render   Regenerate AGENTS.md and tool-specific stubs from CLAUDE.md.
+#   check    Verify AGENTS.md tracks CLAUDE.md (exit 0 in sync, 1 drifted).
+#   list     Show which harnesses are recognised + their target paths.
+#
+# Reads:  CLAUDE.md (repo root) — the canonical agent context.
+# Writes: AGENTS.md, .cursor/rules/dotfiles.mdc, .codex/config.toml
+#         (only when invoked with `render`).
+
+set -euo pipefail
+
+# shellcheck disable=SC1091
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../lib/ui.sh"
+source "$SCRIPT_DIR/../lib/utils.sh"
+
+_agents_repo_root() {
+  # Resolve the chezmoi source dir (where CLAUDE.md/AGENTS.md live).
+  # We REQUIRE the resolved dir to contain `.chezmoidata.toml` so a
+  # user running `dot agents render` from inside some other git
+  # checkout doesn't accidentally write CLAUDE.md/AGENTS.md/.cursor/
+  # /.codex/ into that repo. Round-2 audit C-finding.
+  #
+  # On a CI runner `chezmoi source-path` may return a default path
+  # like `$HOME/.local/share/chezmoi` that doesn't exist on disk —
+  # we treat that as "not a match" and fall through to git, rather
+  # than accepting the wrong candidate.
+  local candidate=""
+  if command -v chezmoi >/dev/null 2>&1; then
+    candidate="$(chezmoi source-path 2>/dev/null || true)"
+    if [[ -n "$candidate" && ! -f "$candidate/.chezmoidata.toml" ]]; then
+      candidate=""
+    fi
+  fi
+  if [[ -z "$candidate" ]]; then
+    candidate="$(git -C "$PWD" rev-parse --show-toplevel 2>/dev/null || true)"
+  fi
+  if [[ -z "$candidate" ]] || [[ ! -f "$candidate/.chezmoidata.toml" ]]; then
+    return 1
+  fi
+  printf '%s\n' "$candidate"
+}
+
+_agents_canonical() {
+  printf "%s/CLAUDE.md" "$(_agents_repo_root)"
+}
+
+_agents_targets() {
+  # printed one-per-line: <harness>\t<path-relative-to-repo-root>
+  # Closes the round-2 audit gap #3 — harness parity with
+  # TonyCasey/ai-dotfiles-manager (who covers 9 surfaces; we now
+  # cover 12 to maintain a margin).
+  local root
+  root="$(_agents_repo_root)"
+  cat <<EOF
+agents-md	$root/AGENTS.md
+cursor	$root/.cursor/rules/dotfiles.mdc
+codex	$root/.codex/config.toml
+windsurf	$root/.windsurf/rules.md
+zed	$root/.zed/agent-config.toml
+roo	$root/.roo/rules.md
+cline	$root/.clinerules
+aider	$root/.aider.conf.yml
+continue	$root/.continuerc.json
+jules	$root/.jules/system.md
+gemini	$root/.gemini/GEMINI.md
+EOF
+}
+
+# Strip the leading HTML comment header (everything up to the first blank
+# line after the `-->`), the H1 title line (which differs by design
+# between CLAUDE.md / AGENTS.md), and the trailing cross-reference
+# block. Leaves the comparable content body.
+_agents_body() {
+  local file="$1"
+  awk '
+    BEGIN { in_header = 0; saw_close = 0; emit = 0 }
+    /^<!--/ && NR <= 5 { in_header = 1; next }
+    in_header && /-->/ { in_header = 0; saw_close = 1; next }
+    in_header { next }
+    saw_close && /^$/ && !emit { emit = 1; next }
+    saw_close && emit { print }
+    !saw_close { emit = 1; print }
+  ' "$file" |
+    # Drop the H1 (`# CLAUDE.md ...` or `# AGENTS.md ...`) and the
+    # trailing "Need richer context?" footer if present.
+    awk '
+      /^# (CLAUDE|AGENTS)\.md/ { next }
+      /^---$/ { trailer = 1; next }
+      trailer && /^\*\*Need richer context\?\*\*/ { next }
+      trailer && NF == 0 { next }
+      { trailer = 0; print }
+    '
+}
+
+cmd_agents() {
+  local subcommand="${1:-list}"
+  shift || true
+
+  case "$subcommand" in
+    list)
+      ui_header "Agent harness targets"
+      echo ""
+      ui_table_begin "Harness" "Target Path" "Status"
+      while IFS=$'\t' read -r harness path; do
+        if [[ -f "$path" ]]; then
+          ui_table_add "$harness" "$path" "rendered"
+        else
+          ui_table_add "$harness" "$path" "not yet rendered"
+        fi
+      done < <(_agents_targets)
+      ui_table_end
+      ;;
+    check)
+      local claude_md agents_md
+      claude_md="$(_agents_canonical)"
+      agents_md="$(_agents_repo_root)/AGENTS.md"
+      if [[ ! -f "$claude_md" ]]; then
+        ui_err "CLAUDE.md" "not found at $claude_md"
+        return 2
+      fi
+      if [[ ! -f "$agents_md" ]]; then
+        ui_warn "AGENTS.md" "missing — run 'dot agents render'"
+        return 1
+      fi
+      # Diff the bodies (header comments differ by design).
+      # `--ignore-blank-lines` so the trailing newline from the footer
+      # block doesn't false-positive as drift.
+      if diff -q --ignore-blank-lines <(_agents_body "$claude_md") <(_agents_body "$agents_md") >/dev/null 2>&1; then
+        ui_ok "AGENTS.md" "in sync with CLAUDE.md"
+        return 0
+      fi
+      ui_warn "AGENTS.md" "drifted from CLAUDE.md — run 'dot agents render'"
+      return 1
+      ;;
+    render)
+      local claude_md root
+      claude_md="$(_agents_canonical)"
+      root="$(_agents_repo_root)"
+      [[ -f "$claude_md" ]] || {
+        ui_err "CLAUDE.md" "not found at $claude_md"
+        return 2
+      }
+
+      # 1. AGENTS.md — body of CLAUDE.md + AGENTS.md cross-reference header.
+      local agents_md="$root/AGENTS.md"
+      {
+        cat <<'HEADER'
+<!--
+  AGENTS.md — Cross-harness AI agent guidelines for this repository.
+
+  This file follows the AGENTS.md standard (originated by OpenAI in
+  August 2025, stewarded since December 2025 by the Linux Foundation
+  Agentic AI Foundation). Native readers: Codex CLI, GitHub Copilot,
+  Cursor, Windsurf, Amp, Devin, and a growing list of other agents.
+
+  Canonical source: CLAUDE.md (Claude Code uses CLAUDE.md natively).
+  This file is kept in sync via `dot agents render`. Edit CLAUDE.md
+  first; do not hand-edit AGENTS.md.
+-->
+
+HEADER
+        # Replace the title line so the rendered file declares its
+        # purpose, but pass everything else through unchanged.
+        _agents_body "$claude_md" | sed '1s/^# CLAUDE\.md.*/# AGENTS.md — AI Assistant Guidelines/'
+        cat <<'FOOTER'
+
+---
+
+**Need richer context?** This file is the cross-harness summary. Claude Code reads the full canonical version from [`CLAUDE.md`](./CLAUDE.md). Both files are kept in sync via `dot agents render`.
+FOOTER
+      } >"$agents_md"
+      chmod 0644 "$agents_md" 2>/dev/null || true
+      ui_ok "AGENTS.md" "rendered → $agents_md"
+
+      # 2. Cursor rules — MDC format, points at CLAUDE.md/AGENTS.md.
+      local cursor_dir="$root/.cursor/rules"
+      mkdir -p "$cursor_dir"
+      cat >"$cursor_dir/dotfiles.mdc" <<'MDC'
+---
+description: Repo conventions for the dotfiles project (sourced from CLAUDE.md/AGENTS.md)
+globs:
+  - "**/*"
+alwaysApply: true
+---
+
+See `AGENTS.md` and `CLAUDE.md` in the repository root for the full
+project conventions, repository layout, testing, and CI policy. This
+Cursor rule file exists so Cursor's rule engine picks up the same
+context; do not duplicate content here — keep CLAUDE.md canonical.
+MDC
+      chmod 0644 "$cursor_dir/dotfiles.mdc" 2>/dev/null || true
+      ui_ok "Cursor" "rendered → $cursor_dir/dotfiles.mdc"
+
+      # 3. Codex CLI config stub — declares the AGENTS.md path.
+      local codex_dir="$root/.codex"
+      mkdir -p "$codex_dir"
+      cat >"$codex_dir/config.toml" <<'TOML'
+# Codex CLI config — points at the AGENTS.md cross-harness context.
+# Codex reads AGENTS.md natively; this file is a project-scoped pin so
+# the CLI prefers the in-repo guidance over any global default.
+project_context = "AGENTS.md"
+TOML
+      chmod 0644 "$codex_dir/config.toml" 2>/dev/null || true
+      ui_ok "Codex" "rendered → $codex_dir/config.toml"
+
+      # 4-11. Per-harness rules files. All eight emitters reuse the
+      # same body extracted from CLAUDE.md so a single edit propagates
+      # consistently. The header differs per harness so each tool sees
+      # syntax it expects (front-matter style, comment block, etc.).
+      _agents_render_markdown_with_header() {
+        local _path="$1" _harness="$2" _header="$3"
+        mkdir -p "$(dirname "$_path")"
+        {
+          printf '%s\n\n' "$_header"
+          _agents_body "$claude_md"
+          # Heredoc instead of printf — Codacy/shellcheck flags
+          # printf-with-backticks-in-single-quotes (SC2016) as
+          # ambiguous even when the backticks are literal Markdown.
+          cat <<'FOOTER'
+
+---
+
+**Canonical source:** [`CLAUDE.md`](./CLAUDE.md) — keep in sync via `dot agents render`.
+FOOTER
+        } >"$_path"
+        chmod 0644 "$_path" 2>/dev/null || true
+        ui_ok "$_harness" "rendered → $_path"
+      }
+
+      # 4. Windsurf — looks for `.windsurf/rules.md`.
+      _agents_render_markdown_with_header "$root/.windsurf/rules.md" \
+        "Windsurf" "# Windsurf project rules
+
+These rules govern Cascade and the Windsurf agent inside this repository."
+
+      # 5. Roo — looks for `.roo/rules.md`.
+      _agents_render_markdown_with_header "$root/.roo/rules.md" \
+        "Roo" "# Roo project rules"
+
+      # 6. Cline — looks for `.clinerules` (no extension).
+      _agents_render_markdown_with_header "$root/.clinerules" \
+        "Cline" "# Cline workspace rules"
+
+      # 7. Jules — looks for `.jules/system.md`.
+      _agents_render_markdown_with_header "$root/.jules/system.md" \
+        "Jules" "# Jules system prompt"
+
+      # 8. Gemini — looks for `.gemini/GEMINI.md`.
+      _agents_render_markdown_with_header "$root/.gemini/GEMINI.md" \
+        "Gemini" "# Gemini agent rules"
+
+      # 9. Zed — config pointer (TOML).
+      local zed_dir="$root/.zed"
+      mkdir -p "$zed_dir"
+      cat >"$zed_dir/agent-config.toml" <<'TOML'
+# Zed agent config — points at AGENTS.md for the cross-harness body.
+# Zed reads this file when its agent mode is enabled; the actual rule
+# body lives in AGENTS.md (which `dot agents render` keeps current).
+agent_context = "AGENTS.md"
+TOML
+      chmod 0644 "$zed_dir/agent-config.toml" 2>/dev/null || true
+      ui_ok "Zed" "rendered → $zed_dir/agent-config.toml"
+
+      # 10. Aider — YAML pointer to AGENTS.md / CLAUDE.md.
+      cat >"$root/.aider.conf.yml" <<'YML'
+# Aider config — surfaces the cross-harness context bundle.
+# Aider's `--read` flag pulls in AGENTS.md / CLAUDE.md per session.
+read:
+  - AGENTS.md
+  - CLAUDE.md
+YML
+      chmod 0644 "$root/.aider.conf.yml" 2>/dev/null || true
+      ui_ok "Aider" "rendered → $root/.aider.conf.yml"
+
+      # 11. Continue — JSON pointer used by VS Code / JetBrains plugin.
+      cat >"$root/.continuerc.json" <<'JSON'
+{
+  "_comment": "Continue config pointer — see AGENTS.md for the full body.",
+  "systemMessage": "Apply the rules in AGENTS.md (canonical source: CLAUDE.md). Run `dot agents render` if the two drift."
+}
+JSON
+      chmod 0644 "$root/.continuerc.json" 2>/dev/null || true
+      ui_ok "Continue" "rendered → $root/.continuerc.json"
+
+      ui_info "Hint" "commit AGENTS.md alongside CLAUDE.md changes (or add to your pre-commit hook)"
+      ;;
+    --help | -h | help)
+      cat <<EOF
+Usage: dot agents <subcommand>
+
+Subcommands:
+  list     Show which agent harnesses are recognised and their target paths
+  check    Verify AGENTS.md tracks CLAUDE.md (exit 0 in sync, 1 drifted)
+  render   Regenerate AGENTS.md + 10 harness-specific files from CLAUDE.md
+
+CLAUDE.md is the canonical source. AGENTS.md follows the cross-harness
+standard read by Codex, Copilot, Cursor, Windsurf, Amp, and Devin.
+
+Harnesses covered by 'render':
+  agents-md, cursor, codex, windsurf, zed, roo, cline,
+  aider, continue, jules, gemini.
+EOF
+      ;;
+    *)
+      ui_err "Unknown subcommand" "$subcommand"
+      echo "Run 'dot agents --help' for usage." >&2
+      return 1
+      ;;
+  esac
+}

package/scripts/dot/commands/aliases.sh

@@ -40,11 +40,11 @@ cmd_aliases() {
     list)
       ui_header "Aliases"
       echo ""
-      printf "  %-18s %-42s %s\n" "Name" "Value" "Source"
-      echo "  $(printf '%.18s' '------------------') $(printf '%.42s' '------------------------------------------') -------------------------"
-      emit_alias_manifest | sort -t $'\t' -k1,1 | while IFS=$'\t' read -r name value file line; do
-        printf "  %-18s %-42s %s:%s\n" "$name" "${value:0:42}" "${file##*/}" "$line"
-      done
+      ui_table_begin "Name" "Value" "Source"
+      while IFS=$'\t' read -r name value file line; do
+        ui_table_add "$name" "${value:0:60}" "${file##*/}:$line"
+      done < <(emit_alias_manifest | sort -t $'\t' -k1,1)
+      ui_table_end
       ;;
     search)
       local query="${1:-}"
@@ -60,9 +60,11 @@ cmd_aliases() {
         ui_warn "No matches" "$query"
         return 1
       fi
-      printf "%s\n" "$results" | while IFS=$'\t' read -r name value file line; do
-        printf "  %-18s %-42s %s:%s\n" "$name" "${value:0:42}" "$file" "$line"
-      done
+      ui_table_begin "Name" "Value" "Source"
+      while IFS=$'\t' read -r name value file line; do
+        ui_table_add "$name" "${value:0:60}" "$file:$line"
+      done <<<"$results"
+      ui_table_end
       ;;
     why)
       local alias_name="${1:-}"

package/scripts/dot/commands/core.sh

@@ -77,13 +77,19 @@ cmd_diff() {
 }
 
 cmd_status() {
-  local out
-  out="$(chezmoi status "$@" || true)"
+  local out rc=0
+  # Capture chezmoi's stderr too so an actual tool failure surfaces
+  # to the user instead of being indistinguishable from a clean tree.
+  out="$(chezmoi status "$@" 2>&1)" || rc=$?
+  ui_header "Dotfiles Status"
+  if [[ "$rc" -ne 0 ]]; then
+    ui_err "chezmoi" "exited $rc"
+    [[ -n "$out" ]] && printf "%s\n" "$out"
+    return "$rc"
+  fi
   if [[ -z "$out" ]]; then
-    ui_header "Dotfiles Status"
     ui_ok "Clean" "no local drift detected"
   else
-    ui_header "Dotfiles Status"
     printf "%s\n" "$out"
   fi
 }

package/scripts/dot/commands/fleet.sh

@@ -291,10 +291,21 @@ cmd_fleet_namespace() {
       local data_file
       data_file="$(resolve_source_dir)/.chezmoidata.toml"
       if grep -q "^namespace = " "$data_file" 2>/dev/null; then
-        if sed --version >/dev/null 2>&1; then
-          sed -i "s/^namespace = \".*\"/namespace = \"$new_ns\"/" "$data_file"
+        # Atomic write: render into a tempfile + mv so concurrent
+        # `dot fleet namespace set` callers can't corrupt the TOML.
+        # Avoids `sed -i` portability dance (GNU `-i` vs BSD `-i ''`).
+        local _tmp
+        _tmp="$(mktemp "${data_file}.XXXXXX")" || die "Cannot create tempfile"
+        # Explicit if/else instead of A && B || C — the latter (SC2015)
+        # silently runs C when B itself fails, masking real mv errors.
+        if sed "s/^namespace = \".*\"/namespace = \"$new_ns\"/" "$data_file" >"$_tmp"; then
+          if ! mv "$_tmp" "$data_file"; then
+            rm -f "$_tmp"
+            die "Failed to commit namespace update"
+          fi
         else
-          sed -i '' "s/^namespace = \".*\"/namespace = \"$new_ns\"/" "$data_file"
+          rm -f "$_tmp"
+          die "Failed to render namespace update"
         fi
       fi
       ui_ok "Namespace" "Set to '$new_ns'. Run 'dot sync' to apply."
@@ -349,6 +360,266 @@ cmd_fleet_enforce() {
   esac
 }
 
+_fleet_hosts_file() {
+  printf '%s\n' "${DOTFILES_FLEET_HOSTS:-$HOME/.config/dotfiles/fleet.toml}"
+}
+
+# Parse the hosts file. Format:
+#   [hosts.laptop]
+#   ssh = "user@laptop.local"
+#   profile = "workstation"
+#
+# Echoes one record per line: "<name>\t<ssh-target>\t<profile>".
+_fleet_hosts_iter() {
+  local f
+  f="$(_fleet_hosts_file)"
+  [[ -f "$f" ]] || return 0
+  awk '
+    BEGIN { name = ""; ssh = ""; profile = "" }
+    /^\[hosts\./ {
+      if (name != "") { printf "%s\t%s\t%s\n", name, ssh, profile }
+      gsub(/[\[\]]/, "", $0); sub(/^hosts\./, "", $0); name = $0
+      ssh = ""; profile = ""
+      next
+    }
+    /^ssh[[:space:]]*=/    { sub(/^ssh[[:space:]]*=[[:space:]]*/, ""); gsub(/"/, ""); ssh = $0; next }
+    /^profile[[:space:]]*=/ { sub(/^profile[[:space:]]*=[[:space:]]*/, ""); gsub(/"/, ""); profile = $0; next }
+    END {
+      if (name != "") { printf "%s\t%s\t%s\n", name, ssh, profile }
+    }
+  ' "$f"
+}
+
+# SSH-based "dot fleet apply" — push the local dotfiles state out to
+# each registered host. The §3 hero-feature: nobody else owns the
+# "Ansible for personal devices" niche.
+cmd_fleet_apply() {
+  local dry_run=0 only_host="" cmd="" jobs=4 verify_hosts=0
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --dry-run | -n)
+        dry_run=1
+        shift
+        ;;
+      --verify-hosts)
+        # Pre-flight check that every host already has a known_hosts
+        # entry, closing the TOFU window before any SSH connection.
+        # R3 audit N4. Without this, accept-new is the default and a
+        # first-connection MITM can seed an attacker key.
+        verify_hosts=1
+        shift
+        ;;
+      --host)
+        only_host="$2"
+        shift 2
+        ;;
+      --cmd)
+        cmd="$2"
+        shift 2
+        ;;
+      --jobs | -j)
+        jobs="$2"
+        shift 2
+        ;;
+      --help | -h)
+        cat <<EOF
+Usage: dot fleet apply [--host <name>] [--cmd <shell>] [--dry-run] [--jobs <n>]
+
+Push dotfiles state to every host registered in:
+  ${DOTFILES_FLEET_HOSTS:-\$HOME/.config/dotfiles/fleet.toml}
+
+Format of fleet.toml:
+  [hosts.laptop]
+  ssh     = "user@laptop.local"
+  profile = "workstation"
+
+Hostnames are validated against [A-Za-z0-9._@:+/-]+ before any SSH
+fan-out; invalid entries abort the apply.
+
+First-time SSH connections use StrictHostKeyChecking=accept-new (TOFU).
+If your threat model requires no TOFU window, pre-populate
+~/.ssh/known_hosts before running this command.
+
+Behavior:
+  By default each host runs:  dot sync && dot doctor --quiet
+  Override with --cmd "<shell>" to run an arbitrary command on every
+  host (e.g. --cmd "uptime").
+
+  WARNING: --cmd is the trust boundary. Whatever string you pass
+  executes on every remote host with the credentials your SSH key
+  carries. Verify the command before running.
+
+Flags:
+  --host <name>      Apply to a single host only.
+  --cmd <shell>      Run a custom command instead of 'dot sync'.
+  --dry-run, -n      Print resolved hosts + planned command; don't SSH.
+  --jobs <n>         Parallelism (default 4).
+  --verify-hosts     Refuse to open any SSH connection unless every
+                     target host already has a key in ~/.ssh/known_hosts.
+                     Use when your threat model excludes the TOFU window.
+EOF
+        return 0
+        ;;
+      *)
+        ui_err "Unknown arg" "$1"
+        return 1
+        ;;
+    esac
+  done
+
+  local hosts_file
+  hosts_file="$(_fleet_hosts_file)"
+  if [[ ! -f "$hosts_file" ]]; then
+    ui_err "Fleet" "no hosts file at $hosts_file"
+    ui_info "Hint" "create it with stanzas like '[hosts.laptop]\\nssh = \"user@laptop.local\"'"
+    return 1
+  fi
+
+  local entries
+  entries="$(_fleet_hosts_iter)"
+  if [[ -z "$entries" ]]; then
+    ui_err "Fleet" "hosts file is empty: $hosts_file"
+    return 1
+  fi
+  if [[ -n "$only_host" ]]; then
+    entries="$(printf '%s\n' "$entries" | awk -F'\t' -v h="$only_host" '$1 == h')"
+    [[ -n "$entries" ]] || {
+      ui_err "Fleet" "host not found: $only_host"
+      return 1
+    }
+  fi
+
+  local default_cmd='dot sync && dot doctor --quiet'
+  local effective_cmd="${cmd:-$default_cmd}"
+
+  ui_header "Fleet apply"
+  ui_info "Hosts file" "$hosts_file"
+  ui_info "Command" "$effective_cmd"
+  ui_info "Parallel" "$jobs"
+
+  if [[ "$dry_run" -eq 1 ]]; then
+    printf '%s\n' "$entries" | while IFS=$'\t' read -r name ssh profile; do
+      ui_info "$name" "$ssh  profile=$profile  cmd=$effective_cmd"
+    done
+    ui_ok "Dry-run" "no SSH connections opened"
+    return 0
+  fi
+
+  if ! command -v ssh >/dev/null 2>&1; then
+    ui_err "ssh" "not installed"
+    return 127
+  fi
+
+  local total=0 ok=0 fail=0
+  local tmpdir
+  # `-t` template includes PID + random, so two concurrent `dot fleet
+  # apply` invocations from the same user can't collide on $tmpdir.
+  tmpdir="$(mktemp -d -t dotfiles-fleet.XXXXXX)"
+  # Capture tmpdir's value at trap-definition time (via the eval-on-
+  # define `printf -v`), NOT at trap-fire time. A naive
+  # `trap 'rm -rf "$tmpdir"' RETURN` is unsafe under set -u because
+  # `local tmpdir` is destroyed before the RETURN trap evaluates.
+  # The SC2064 warning ("Use single quotes, otherwise this expands now
+  # rather than when signalled") is exactly the behaviour we want here —
+  # we explicitly want eager expansion. Suppress per-line.
+  local _cleanup
+  printf -v _cleanup 'rm -rf %q' "$tmpdir"
+  # shellcheck disable=SC2064
+  trap "$_cleanup" RETURN
+
+  # Validate every hostname against a conservative regex BEFORE fan-out.
+  # `user@host:port` characters only — refuses single quotes, backticks,
+  # `$()`, semicolons, spaces, any shell metacharacter. Closes the
+  # round-2 audit's hostname-injection finding.
+  while IFS=$'\t' read -r name ssh profile; do
+    [[ -n "$name" ]] || continue
+    if [[ ! "$ssh" =~ ^[a-zA-Z0-9._@:+/-]+$ ]]; then
+      ui_err "$name" "invalid ssh target ($ssh) — only [a-zA-Z0-9._@:+/-] allowed"
+      return 1
+    fi
+  done <<<"$entries"
+
+  # --verify-hosts: refuse the apply when any target host is missing
+  # from ~/.ssh/known_hosts. Closes the R3 audit N4 TOFU-window gap.
+  if ((verify_hosts == 1)); then
+    local known_hosts="${HOME}/.ssh/known_hosts"
+    if [[ ! -f "$known_hosts" ]]; then
+      ui_err "verify-hosts" "no $known_hosts — populate before --verify-hosts"
+      return 1
+    fi
+    local unknown_count=0
+    while IFS=$'\t' read -r name ssh profile; do
+      [[ -n "$name" && -n "$ssh" ]] || continue
+      # Strip `user@` prefix and `:port` suffix for the lookup.
+      local hostpart="${ssh#*@}"
+      hostpart="${hostpart%%:*}"
+      if ! ssh-keygen -F "$hostpart" -f "$known_hosts" >/dev/null 2>&1; then
+        ui_err "$name" "no known_hosts entry for $hostpart — would TOFU on first connect"
+        unknown_count=$((unknown_count + 1))
+      fi
+    done <<<"$entries"
+    if ((unknown_count > 0)); then
+      ui_err "verify-hosts" "$unknown_count host(s) missing from known_hosts — aborting"
+      return 1
+    fi
+    ui_ok "verify-hosts" "all hosts found in known_hosts"
+  fi
+
+  # Run one SSH per host, parallelised via background jobs with a
+  # semaphore. We DO NOT use `xargs -d` because that flag is GNU-only
+  # and the §3 hero feature must work on macOS BSD xargs too. Also
+  # avoids embedding `{}` substitution into a `bash -c` (the previous
+  # implementation had a quoting hazard around TOML hostnames).
+  _fleet_apply_one() {
+    local _name="$1" _ssh="$2" _cmd="$3" _tmp="$4"
+    if ssh -o BatchMode=yes -o ConnectTimeout=10 \
+      -o StrictHostKeyChecking=accept-new \
+      "$_ssh" "$_cmd" </dev/null \
+      >"$_tmp/$_name.out" 2>"$_tmp/$_name.err"; then
+      printf 'ok\n' >"$_tmp/$_name.status"
+    else
+      printf 'fail %d\n' "$?" >"$_tmp/$_name.status"
+    fi
+  }
+
+  local running=0
+  while IFS=$'\t' read -r name ssh profile; do
+    [[ -n "$name" && -n "$ssh" ]] || continue
+    total=$((total + 1))
+    while ((running >= jobs)); do
+      wait -n 2>/dev/null || break
+      running=$((running - 1))
+    done
+    _fleet_apply_one "$name" "$ssh" "$effective_cmd" "$tmpdir" &
+    running=$((running + 1))
+  done <<<"$entries"
+  wait
+
+  # `while < <(printf ...)` instead of `printf ... | while` — the
+  # pipe form runs the loop body in a subshell, so the ok/fail
+  # counters never propagate back to the parent. Caught by
+  # tests/unit/fleet/test_fleet_apply_mocked_ssh.sh which exercised
+  # the full apply path (the dry-run test missed this).
+  while IFS=$'\t' read -r name ssh profile; do
+    [[ -n "$name" ]] || continue
+    if [[ -s "$tmpdir/$name.status" ]] && head -1 "$tmpdir/$name.status" | grep -q '^ok'; then
+      ui_ok "$name" "$ssh"
+      ok=$((ok + 1))
+    else
+      local err_summary=""
+      [[ -s "$tmpdir/$name.err" ]] && err_summary=" — $(head -1 "$tmpdir/$name.err")"
+      ui_err "$name" "$ssh${err_summary}"
+      fail=$((fail + 1))
+    fi
+    local _evt_status="unknown"
+    [[ -s "$tmpdir/$name.status" ]] && _evt_status="$(head -1 "$tmpdir/$name.status")"
+    _fleet_emit_event "apply" "$_evt_status" "host=$name" "cmd=$effective_cmd"
+  done < <(printf '%s\n' "$entries")
+
+  ui_info "Summary" "$ok ok / $fail failed / $total total"
+  [[ "$fail" -eq 0 ]]
+}
+
 cmd_fleet() {
   local subcommand="${1:-status}"
   if [[ "${1:-}" == --* ]] || [[ -z "${1:-}" ]]; then
@@ -373,6 +644,9 @@ cmd_fleet() {
     enforce)
       cmd_fleet_enforce "$@"
       ;;
+    apply | push)
+      cmd_fleet_apply "$@"
+      ;;
     *)
       ui_header "Fleet Commands"
       echo ""
@@ -383,6 +657,7 @@ cmd_fleet() {
       ui_ok "events" "Show recent fleet events"
       ui_ok "namespace" "Show or set the active namespace"
       ui_ok "enforce" "Show or set RBAC enforcement mode (advisory|strict)"
+      ui_ok "apply" "SSH out to every host in fleet.toml and run 'dot sync'"
       ;;
   esac
 }