dash 4.1.3 → 4.2.0

data/lib/dash/cli/autoscale.rb

@@ -0,0 +1,312 @@
+# `dash autoscale`: the controller that holds each scheduled or signalled role at its target
+# (Dash::Autoscale::Controller), and the commands that read what it decided and why. The
+# controller's state lives on one host - `autoscale.controller`, or the primary host
+# without it - so every operator's checkout reads the same heartbeat, decisions and pauses.
+class Dash::Cli::Autoscale < Dash::Cli::Base
+  MINIMUM_INTERVAL = 5
+  LOCK_WAIT_INTERVAL = 5
+
+  # `run` is a Thor reserved word, so the method has another name.
+  map "run" => :start_controller
+
+  desc "run", "Run the autoscale controller: every interval, scale each role with a scale/schedule or scale/signal toward its target through dash scale set"
+  option :once, type: :boolean, default: false, desc: "Run one tick and exit (for cron)"
+  option :dry_run, type: :boolean, default: false, desc: "Decide and print, without acting or writing any state"
+  option :interval, type: :numeric, desc: "Seconds between ticks (default autoscale/interval)"
+  option :metrics_port, type: :numeric, desc: "Serve Prometheus metrics on this port at /metrics"
+  option :metrics_bind, default: "127.0.0.1", desc: "Address the metrics endpoint binds"
+  option :record, desc: "Append every tick's decisions, with their inputs, to this local JSONL file"
+  option :takeover, type: :boolean, default: false, desc: "Start even while another controller's heartbeat is alive (it stops at its next tick)"
+  def start_controller
+    raise ArgumentError, "dash autoscale run works on whole roles: narrow it with --roles, not --hosts or --primary" if options[:hosts] || options[:primary]
+
+    controller = Dash::Autoscale::Controller.new(cli: self, dry_run: options[:dry_run], takeover: options[:takeover], interval: tick_interval,
+      mode: options[:once] ? "once" : "loop", recorder: (Dash::Autoscale::Recorder.new(options[:record]) if options[:record]))
+    pre_connect_if_required
+
+    options[:once] ? run_once(controller) : run_loop(controller)
+  end
+
+  desc "explain ROLE", "Evaluate ROLE as the controller's next tick would, with every input, without acting"
+  option :json, type: :boolean, default: false, desc: "Print the evaluation as JSON"
+  def explain(role_name)
+    role = scaled_role(role_name)
+    explain = -> { Dash::Diagnostics::AutoscaleExplain.new(role: role).to_h }
+
+    if options[:json]
+      puts_json(&explain)
+    else
+      pre_connect_if_required
+      print_explain(DASH.with_verbosity(:error) { explain.call })
+    end
+  end
+
+  desc "signal ROLE", "Read one live sample of ROLE's scale/signal and of each scale/hold_when guard, from this machine"
+  option :json, type: :boolean, default: false, desc: "Print the sample as JSON"
+  def signal(role_name)
+    role = scaled_role(role_name)
+    sample = -> { Dash::Diagnostics::AutoscaleSignal.new(role: role).to_h }
+
+    if options[:json]
+      puts_json(&sample)
+    else
+      # A source with `via:` is reached through an SSH tunnel.
+      pre_connect_if_required
+      print_signal(sample.call)
+    end
+  end
+
+  desc "simulate", "Replay a dash autoscale run --record file with deploy.yml's thresholds now: every simulated action, and a summary per role"
+  option :samples, required: true, desc: "The --record file (JSONL, one tick per line) to replay"
+  option :json, type: :boolean, default: false, desc: "Print the simulation as JSON"
+  def simulate
+    raise ArgumentError, "No such file: #{options[:samples]}" unless File.file?(options[:samples])
+
+    simulation = Dash::Autoscale::Simulation.new(path: options[:samples], config: DASH.config, roles: DASH.specific_roles&.map(&:name)).run
+    options[:json] ? puts(JSON.pretty_generate(simulation)) : print_simulation(simulation)
+  end
+
+  desc "history [ROLE]", "Show the controller's last decisions (of ROLE, or of every role)"
+  option :lines, type: :numeric, default: Dash::Diagnostics::AutoscaleDecisions::DEFAULT_LINES, desc: "How many decisions"
+  option :json, type: :boolean, default: false, desc: "Print the decisions as JSON"
+  def history(role_name = nil)
+    role = scaled_role(role_name).name if role_name
+    history = -> { Dash::Diagnostics::AutoscaleDecisions.new(roles: ([ role ] if role), lines: options[:lines]).to_h }
+
+    if options[:json]
+      puts_json(&history)
+    else
+      pre_connect_if_required
+      print_history(DASH.with_verbosity(:error) { history.call })
+    end
+  end
+
+  desc "status", "Show which controller runs, when it last ticked, and the paused roles"
+  option :json, type: :boolean, default: false, desc: "Print the status as JSON"
+  def status
+    status = -> { Dash::Diagnostics::ControllerStatus.new.to_h }
+
+    if options[:json]
+      puts_json(&status)
+    else
+      pre_connect_if_required
+      print_status(DASH.with_verbosity(:error) { status.call })
+    end
+  end
+
+  desc "pause ROLE", "Stop the controller from scaling ROLE, for good or --for a while (resume ROLE lifts it)"
+  option :for, desc: "How long: seconds, or a number followed by s, m, h or d (30m, 2h, 1d)"
+  def pause(role_name)
+    role = scaled_role(role_name)
+    now = Time.now.utc
+    ends_at = options[:for] ? now + pause_duration(options[:for]) : :indefinite
+    pause = Dash::Autoscale::Pause.new(ends_at: ends_at, by: performer, at: now)
+    until_text = pause.indefinite? ? "until resumed" : "until #{Dash::Autoscale::Timestamp.dump(ends_at)}"
+
+    on(Dash::Autoscale::StateStore.host) do
+      store = Dash::Autoscale::StateStore.new(self)
+      store.ensure_directory
+      store.write_pause(role.name, pause.to_h)
+    end
+    audit "Paused autoscaling of #{role} #{until_text}"
+
+    say "Paused autoscaling of #{role} #{until_text}", :magenta
+  end
+
+  desc "resume ROLE", "Let the controller scale ROLE again"
+  def resume(role_name)
+    role = scaled_role(role_name)
+
+    on(Dash::Autoscale::StateStore.host) do
+      Dash::Autoscale::StateStore.new(self).remove_pause(role.name)
+    end
+    audit "Resumed autoscaling of #{role}"
+
+    say "Resumed autoscaling of #{role}", :magenta
+  end
+
+  # What Dash::Autoscale::Controller asks of the CLI.
+  no_commands do
+    # A fresh deploy.yml every tick, as `dash mcp` reads one per question, with the run's
+    # --roles applied again (reconfigure drops them).
+    def reconfigure!
+      roles = options[:roles]&.split(",")
+      DASH.reconfigure(config_file: Pathname.new(File.expand_path(options[:config_file])), destination: options[:destination], explicit_roles: roles)
+      DASH.specific_roles = roles
+    end
+
+    # `dash scale set ROLE COUNT`, waiting up to autoscale/lock_wait_timeout for the deploy
+    # lock. The invocation is reset even when it fails, or Thor would skip the next one.
+    def invoke_scale_set(role, count)
+      with_lock_wait do
+        invoke "dash:cli:scale:set", [ role.name, count.to_s ], scale_options
+      ensure
+        reset_invocation(Dash::Cli::Scale)
+      end
+    end
+
+    def replace_member(role, member, count:)
+      with_lock_wait do
+        Dash::Cli::Scale.new([], scale_options, invocations: { Dash::Cli::Scale => [ "set" ] }).replace_unreachable(role, member, count: count)
+      end
+    end
+
+    def report(message, color = nil)
+      say message, color
+    end
+  end
+
+  private
+    # A signal during the tick lets it finish (a join in flight included), then it exits.
+    def run_once(controller)
+      trapping_signals(controller) do
+        controller.start
+        controller.tick
+      end
+    ensure
+      controller.release
+    end
+
+    def run_loop(controller)
+      server = Dash::Autoscale::MetricsServer.new(controller.metrics, bind: options[:metrics_bind], port: options[:metrics_port]).start if options[:metrics_port]
+      say "Serving autoscale metrics on http://#{options[:metrics_bind]}:#{server.port}/metrics", :magenta if server
+      say "Autoscale controller #{controller.id}#{" (dry run)" if options[:dry_run]} ticking every #{controller.interval}s", :magenta
+
+      trapping_signals(controller) { controller.run }
+    ensure
+      server&.stop
+    end
+
+    # TERM and INT only ask the controller to stop: the tick in progress, and a join in it, finish.
+    def trapping_signals(controller)
+      previous = %w[ TERM INT ].to_h { |signal| [ signal, trap(signal) { controller.stop! } ] }
+      yield
+    ensure
+      previous&.each { |signal, handler| trap(signal, handler || "DEFAULT") }
+    end
+
+    def tick_interval
+      return unless options[:interval]
+
+      interval = Integer(options[:interval].to_s, 10, exception: false)
+      if interval.nil? || interval < MINIMUM_INTERVAL
+        raise ArgumentError, "--interval must be a whole number of seconds, at least #{MINIMUM_INTERVAL}, not #{options[:interval]}"
+      end
+
+      interval
+    end
+
+    def with_lock_wait
+      saved = [ DASH.lock_wait, DASH.lock_wait_timeout, DASH.lock_wait_interval ]
+      DASH.lock_wait, DASH.lock_wait_timeout, DASH.lock_wait_interval = true, DASH.config.autoscale.lock_wait_timeout, LOCK_WAIT_INTERVAL
+      yield
+    ensure
+      DASH.lock_wait, DASH.lock_wait_timeout, DASH.lock_wait_interval = saved
+    end
+
+    def scale_options
+      options.slice("config_file", "destination", "skip_hooks", "verbose", "quiet")
+    end
+
+    def scaled_role(role_name)
+      role = DASH.config.role(role_name) || raise(ArgumentError, "No role named #{role_name}, expected one of #{DASH.config.roles.map(&:name).join(", ")}")
+      raise ArgumentError, "#{role} has no scale, so the autoscale controller never touches it" unless role.scaled?
+
+      role
+    end
+
+    def pause_duration(value)
+      seconds = Dash::Autoscale::Duration.parse(value)
+      raise ArgumentError, "--for must be longer than 0 seconds" unless seconds.positive?
+
+      seconds
+    end
+
+    def performer
+      Dash::Git.user_name.presence || ENV["USER"] || "unknown"
+    end
+
+    # On the primary host, where `dash audit` reads, wherever the state lives.
+    def audit(line)
+      on(DASH.config.primary_role.baseline_hosts.first) { execute *DASH.auditor.record(line), verbosity: :debug }
+    end
+
+    def print_explain(explain)
+      decision = explain[:decision]
+      say "#{decision[:role]}: #{decision[:action]} #{decision[:from].inspect} -> #{decision[:to].inspect} (#{decision[:reasons].join(", ")})"
+      say "  not controlled: it has no scale/schedule or scale/signal, so dash autoscale run leaves it alone", :yellow unless explain[:controlled]
+      say "  error: #{decision[:error]}", :red if decision[:error]
+      say "  eligible at: #{decision[:eligible_at]}" if decision[:eligible_at]
+      decision[:inputs].each { |name, value| say "  #{name}: #{value.to_json}" unless value.nil? || value == [] || value == {} }
+      say "  state on #{explain[:state_host]} could not be read (#{explain[:state_error]}), evaluated without it", :yellow if explain[:state_error]
+    end
+
+    def print_signal(sample)
+      return say(sample[:message], :yellow) unless sample[:configured]
+
+      signal, band = sample[:signal], sample[:band]
+      if signal[:error] || signal[:value].nil?
+        say "#{sample[:role]}: #{signal[:source]} could not be read from #{sample[:from]}: #{signal[:error] || "no value"}", :red
+      else
+        position = sample[:position] == "inside" ? "inside the band" : "#{sample[:position]} the band"
+        say "#{sample[:role]}: #{signal[:source]} #{signal[:value]}, #{position} (up above #{band[:up_above]} for #{band[:up_for]}s, " \
+          "down below #{band[:down_below]} for #{band[:down_for]}s), read from #{sample[:from]} in #{signal[:latency_ms]}ms"
+      end
+
+      sample[:guards].each do |guard|
+        name = "hold_when/#{guard[:index]} #{guard[:source]}"
+        reading = guard[:value].nil? ? "#{name}: #{guard[:error] || "no value"}" : "#{name} #{guard[:value]}#{" > #{guard[:above]}" if guard[:holding]}"
+        say "  #{reading}#{", holding a scale-out" if guard[:holding]} (#{guard[:latency_ms]}ms)", (:yellow if guard[:holding])
+      end
+    end
+
+    def print_simulation(simulation)
+      simulation[:roles].each do |role|
+        say "#{role[:role]}: #{role[:ticks]} #{"tick".pluralize(role[:ticks])}, #{role[:replayed]} replayed"
+        role[:actions].each { |action| say "  #{action[:at]} #{action[:summary]}" }
+        say "  simulated: #{simulation_summary(role[:simulated])}"
+        say "  recorded:  #{simulation_summary(role[:recorded])}"
+        if role[:not_replayable].positive?
+          say "  #{role[:not_replayable]} #{"tick".pluralize(role[:not_replayable])} not replayable: recorded without a signal (before Phase 3), or not evaluated", :yellow
+        end
+        say "  #{role[:unrecorded_guards]} hold_when #{"guard".pluralize(role[:unrecorded_guards])} not in the recording, left out", :yellow if role[:unrecorded_guards]
+      end
+
+      say "No role in #{simulation[:file]} to replay", :yellow if simulation[:roles].empty?
+      simulation[:skipped].each { |skipped| say "#{skipped[:role]}: skipped, #{skipped[:reason]}", :yellow }
+      simulation[:errors].each { |error| say "line #{error[:line]}: #{error[:error]}", :red }
+    end
+
+    def simulation_summary(summary)
+      return "no tick replayed" if summary[:peak].nil?
+
+      "#{summary[:scale_outs]} #{"scale-out".pluralize(summary[:scale_outs])}, #{summary[:scale_ins]} #{"scale-in".pluralize(summary[:scale_ins])}, " \
+        "peak #{summary[:peak]}, minimum #{summary[:minimum]}, #{summary[:container_seconds]} container-seconds"
+    end
+
+    def print_history(history)
+      return say("Could not read the decision log on #{history[:host]}: #{history[:error]}", :red) if history[:error]
+      return say("No autoscale decisions logged yet") if history[:decisions].empty?
+
+      history[:decisions].each do |decision|
+        counts = decision["action"] == "replace_member" ? decision.dig("inputs", "replace") : "#{decision["from"].inspect} -> #{decision["to"].inspect}"
+        error = " - #{decision["error"]}" if decision["error"]
+        say "#{decision["at"]}  #{decision["role"]}: #{decision["action"]} #{counts} (#{decision["reasons"].to_a.join(", ")})#{error}", (:red if error)
+      end
+    end
+
+    def print_status(status)
+      return say("Could not read the controller state on #{status[:state_host]}: #{status[:error]}", :red) if status[:error]
+
+      if (controller = status[:controller])
+        tick = controller[:age_seconds] ? "last tick #{controller[:age_seconds]}s ago" : "no tick yet"
+        say "Controller #{controller[:controller_id]} on #{controller[:hostname]} (pid #{controller[:pid]}, dash #{controller[:version]}, #{controller[:mode]}): " \
+          "#{controller[:status]}, #{tick}", controller[:status] == "running" ? :green : :yellow
+      else
+        say "No autoscale controller has run for this app", :yellow
+      end
+
+      say "Scheduled roles: #{status[:roles].any? ? status[:roles].join(", ") : "none"}"
+      status[:pauses].each { |pause| say "#{pause[:role]} paused #{pause[:until] == "indefinite" ? "until resumed" : "until #{pause[:until]}"} by #{pause[:by]}", :yellow }
+    end
+end

data/lib/dash/cli/base.rb

@@ -103,9 +103,10 @@ module Dash::Cli
       # Process-scoped rather than commander-scoped: Dash::Cli::Alias::Command
       # resets DASH and re-enters Dash::Cli::Main.start, so an aliased command
       # builds a second commander and would otherwise warn twice. `dash migrate`
-      # is exempt - telling an operator to run the command they are running is noise.
+      # is exempt - telling an operator to run the command they are running is noise - and
+      # so is `dash mcp`, whose stdout is the protocol.
       def warn_on_legacy_project_directory(command_name)
-        return if command_name == "migrate"
+        return if %w[ migrate mcp ].include?(command_name)
         return if Dash::Cli::Base.legacy_project_directory_warned
         return unless Dash::ProjectDirectory.legacy?
 
@@ -129,7 +130,9 @@ module Dash::Cli
           commander.configure \
             config_file: Pathname.new(File.expand_path(options[:config_file])),
             destination: options[:destination],
-            version: options[:version]
+            version: options[:version],
+            explicit_hosts: options[:hosts]&.split(","),
+            explicit_roles: options[:roles]&.split(",")
 
           commander.specific_hosts    = options[:hosts]&.split(",")
           commander.specific_roles    = options[:roles]&.split(",")
@@ -544,6 +547,15 @@ module Dash::Cli
         super
       end
 
+      # A diagnostic as pure JSON on stdout, returned too. capture_with_info logs every command
+      # it runs at info, onto stdout, so the capture runs at :error - a `| jq` must see only the JSON.
+      def puts_json(ssh: true)
+        DASH.with_verbosity(:error) do
+          pre_connect_if_required if ssh
+          yield.tap { |snapshot| puts JSON.pretty_generate(snapshot) }
+        end
+      end
+
       def pre_connect_if_required
         if !DASH.connected?
           run_hook "pre-connect", secrets: true unless options[:skip_hooks]

data/lib/dash/cli/lock.rb

@@ -1,8 +1,13 @@
 class Dash::Cli::Lock < Dash::Cli::Base
   desc "status", "Report lock status"
   option :server, type: :boolean, default: false, desc: "Report the shared server lock instead of the deploy lock"
+  option :json, type: :boolean, default: false, desc: "Print the deploy lock status as JSON"
   def status
-    if options[:server]
+    if options[:json]
+      raise ArgumentError, "--json reports the deploy lock; it cannot be combined with --server" if options[:server]
+
+      puts_json { Dash::Diagnostics::Lock.new.to_h }
+    elsif options[:server]
       report_server_lock_status
     else
       handle_missing_lock do

data/lib/dash/cli/main.rb

@@ -151,7 +151,10 @@ class Dash::Cli::Main < Dash::Cli::Base
   end
 
   desc "audit", "Show audit log from servers"
+  option :json, type: :boolean, default: false, desc: "Print the audit log as JSON, parsed per line"
   def audit
+    return puts_json { Dash::Diagnostics::Audit.new.to_h } if options[:json]
+
     quiet = options[:quiet]
     on(DASH.hosts) do |host|
       puts_by_host host, capture_with_info(*DASH.auditor.reveal), quiet: quiet
@@ -159,7 +162,10 @@ class Dash::Cli::Main < Dash::Cli::Base
   end
 
   desc "config", "Show combined config (including secrets!)"
+  option :json, type: :boolean, default: false, desc: "Print the config and its topology (roles, hosts, proxies) as JSON"
   def config
+    return puts_json(ssh: false) { Dash::Diagnostics::Config.new.to_h } if options[:json]
+
     run_locally do
       puts Dash::Utils.redacted(DASH.config.to_h).to_yaml
     end
@@ -177,12 +183,15 @@ class Dash::Cli::Main < Dash::Cli::Base
     puts "No documentation found for #{section}"
   end
 
-  desc "doctor", "Diagnose deploy readiness of servers, registry, proxy, ports, DNS, certificates, and per-role readiness gates"
+  desc "doctor", "Diagnose deploy readiness of servers, registry, proxy, ports, DNS, certificates, per-role readiness gates, and proxy drift"
+  option :json, type: :boolean, default: false, desc: "Print the results as JSON (exits 1 when a check fails)"
   def doctor
+    return doctor_json if options[:json]
+
     say "Running readiness checks...", :magenta
-    pre_connect_if_required
+    doctor_pre_connect
 
-    doctor = Dash::Cli::Doctor.new
+    doctor = Dash::Diagnostics::Doctor.new
     doctor.run
 
     print_doctor_report doctor.results
@@ -194,6 +203,18 @@ class Dash::Cli::Main < Dash::Cli::Base
     end
   end
 
+  desc "mcp", "Serve read-only diagnostics to an AI agent over stdio (Model Context Protocol)"
+  option :allow_logs, type: :boolean, default: false, desc: "Enable the logs tool (container logs can carry personal data; or DASH_MCP_ALLOW_LOGS=true)"
+  def mcp
+    protocol = Dash::Mcp.reserve_stdout!
+    Dash::Mcp.load!
+    Dash::Mcp::Runner.authorize!(ENV)
+    DASH.verbosity = :error
+    pre_connect_if_required
+
+    Dash::Mcp::Runner.run(mcp_session, output: protocol)
+  end
+
   desc "init", "Create config stub in config/deploy.yml and secrets stub in .dash"
   option :bundle, type: :boolean, default: false, desc: "Add dash to the Gemfile and create a bin/dash binstub"
   def init
@@ -301,6 +322,9 @@ class Dash::Cli::Main < Dash::Cli::Base
   desc "app", "Manage application"
   subcommand "app", Dash::Cli::App
 
+  desc "autoscale", "Run the autoscale controller, and read what it decided"
+  subcommand "autoscale", Dash::Cli::Autoscale
+
   desc "build", "Build application image"
   subcommand "build", Dash::Cli::Build
 
@@ -319,6 +343,9 @@ class Dash::Cli::Main < Dash::Cli::Base
   desc "registry", "Login and -out of the image registry"
   subcommand "registry", Dash::Cli::Registry
 
+  desc "scale", "Change how many containers of a role run, without a deploy"
+  subcommand "scale", Dash::Cli::Scale
+
   desc "secrets", "Helpers for extracting secrets"
   subcommand "secrets", Dash::Cli::Secrets
 
@@ -352,10 +379,34 @@ class Dash::Cli::Main < Dash::Cli::Base
       { "version" => DASH.config.version }.merge(base_options)
     end
 
+    # Pure JSON on stdout, so the failure is the exit status rather than an ERROR line.
+    # The pre-connect hook is handed every host, and with the pool unreadable those are
+    # unknown. The doctor carries on without it and reports the pool failure itself.
+    # `--json` keeps stdout for the JSON, so it says so on stderr.
+    def doctor_pre_connect(json: false)
+      pre_connect_if_required
+    rescue Dash::Autoscale::ProviderError => e
+      message = "Skipped the pre-connect hook, the hosts are unknown: #{e.message}"
+      json ? warn(message) : say(message, :yellow)
+    end
+
+    def doctor_json
+      DASH.with_verbosity(:error) { doctor_pre_connect(json: true) }
+      exit 1 unless puts_json(ssh: false) { Dash::Diagnostics::Doctor.new.to_h }[:successful]
+    end
+
+    # The scope the operator started `dash mcp` with is the ceiling for every question.
+    def mcp_session
+      Dash::Mcp::Session.new(
+        config_file: Pathname.new(File.expand_path(options[:config_file])), destination: options[:destination], version: options[:version],
+        hosts: options[:primary] ? [ DASH.primary_host ] : options[:hosts]&.split(","), roles: options[:roles]&.split(","),
+        allow_logs: Dash::Mcp::Runner.allow_logs?(options[:allow_logs], ENV), redactor: Dash::Diagnostics::Redactor.for(DASH.config))
+    end
+
     def print_doctor_report(results)
       results.group_by(&:title).each do |title, rows|
         say title
-        rows.each { |row| say "  #{row}", Dash::Cli::Doctor::STATUS_COLORS[row.status] }
+        rows.each { |row| say "  #{row}", Dash::Diagnostics::Doctor::STATUS_COLORS[row.status] }
       end
     end
 
@@ -377,14 +428,32 @@ class Dash::Cli::Main < Dash::Cli::Base
 
       say "Deploying #{config.service}#{" to #{config.destination}" if config.destination} (version #{config.abbreviated_version})", :magenta
       config.roles.each do |role|
-        hosts = "#{role.hosts.count} #{"host".pluralize(role.hosts.count)} (#{role.hosts.join(", ")})"
-        say "  #{role.name}: #{hosts} — readiness: #{role.readiness_description}", (:yellow if role.readiness_source == :none)
+        replicas = " #{role.replicas}" if role.replicas.scalable?
+        say "  #{role.name}: #{banner_hosts(role)}#{replicas} — readiness: #{role.readiness_description}", (:yellow if role.readiness_source == :none)
       end
       say "  proxy: #{config.proxy_hosts.join(", ")}" if config.proxy_hosts.any?
       if config.proxy.load_balancing?
-        reason = " (auto-enabled: primary role #{config.primary_role.name} has #{config.primary_role.hosts.count} hosts)" unless config.proxy.loadbalancer.present?
-        say "  loadbalancer: #{config.proxy.effective_loadbalancer}#{reason}"
+        say "  loadbalancer: #{config.proxy.effective_loadbalancer}#{loadbalancer_reason(config) unless config.proxy.loadbalancer.present?}"
       end
       say "  timeouts: deploy #{config.deploy_timeout}s, drain #{config.drain_timeout}s, readiness delay #{config.readiness_delay}s"
     end
+
+    def banner_hosts(role)
+      baseline = role.baseline_hosts
+      hosts = "#{baseline.count} #{"host".pluralize(baseline.count)} (#{baseline.join(", ")})"
+      return hosts unless role.scaled?
+
+      active = role.active_members.map(&:host)
+      "#{hosts} + #{active.count} of #{role.members.count} members active#{" (#{active.join(", ")})" if active.any?}"
+    end
+
+    def loadbalancer_reason(config)
+      primary = config.primary_role
+
+      if primary.running_proxy? && primary.baseline_hosts.count > 1
+        " (auto-enabled: primary role #{primary.name} has #{primary.baseline_hosts.count} hosts)"
+      elsif (scaled = config.scaled_roles.find(&:running_proxy?))
+        " (auto-enabled: role #{scaled.name} scales across hosts)"
+      end
+    end
 end

data/lib/dash/cli/proxy/inspection.rb

@@ -0,0 +1,52 @@
+# `dash proxy services` and `dash proxy drift`: the read-only questions about what the
+# proxies route, kept out of the proxy command file that boots, reboots and manages them.
+# The JSON is the diagnostic's own `to_h`; the rest here is the table an operator reads.
+module Dash::Cli::Proxy::Inspection
+  extend ActiveSupport::Concern
+
+  included do
+    desc "services", "Show what dash-proxy routes for this deploy on each proxy host (and the load balancer)"
+    option :json, type: :boolean, default: false, desc: "Print the services as JSON"
+    def services
+      return puts_json { Dash::Diagnostics::ProxyServices.new.to_h } if options[:json]
+
+      pre_connect_if_required
+      puts services_lines(Dash::Diagnostics::ProxyServices.new.to_h)
+    end
+
+    desc "drift", "Compare the running containers with the proxy and load balancer targets"
+    option :json, type: :boolean, default: false, desc: "Print the drift as JSON"
+    def drift
+      return puts_json { Dash::Diagnostics::Drift.take.to_h } if options[:json]
+
+      pre_connect_if_required
+      puts drift_lines(Dash::Diagnostics::Drift.take.to_h)
+    end
+  end
+
+  private
+    def services_lines(snapshot)
+      proxies = snapshot[:hosts].flat_map { |host| host_services_lines("Proxy", host) }
+      proxies + (snapshot[:loadbalancer] ? host_services_lines("Loadbalancer", snapshot[:loadbalancer]) : [])
+    end
+
+    def drift_lines(snapshot)
+      if snapshot[:consistent]
+        [ "No drift: proxy targets match the running containers" ]
+      else
+        snapshot[:drift].map { |entry| "#{entry[:code]} #{entry[:host] || entry[:role]}: #{entry[:detail]}" } +
+          Array(snapshot[:unread]).map { |host| "unread #{host[:host]}: could not read #{host[:source]} (#{host[:error]})" }
+      end
+    end
+
+    def host_services_lines(type, host)
+      return [ "#{type} Host: #{host[:host]}", "  ERROR #{host[:error]}" ] if host[:error]
+
+      services = host[:services].map do |name, service|
+        targets = Array(service["targets"]).presence || service["target"].to_s.split(",")
+        "  #{name} #{service["host"].presence || "*"} -> #{targets.join(", ").presence || "no targets"}#{" (#{service["state"]})" if service["state"]}"
+      end
+
+      [ "#{type} Host: #{host[:host]}", *services.presence || [ "  no services" ] ]
+    end
+end

data/lib/dash/cli/proxy/loadbalancer_deploy.rb

@@ -0,0 +1,20 @@
+# Points the load balancer at a target list: every host of every proxied role by default.
+# `dash proxy loadbalancer deploy` and `dash scale set` share it, so a member leaving the
+# pool is the same deploy with that host left out - dash-proxy replaces the whole list,
+# draining the hosts that are no longer on it. Runs inside `on(<load balancer host>)`.
+class Dash::Cli::Proxy::LoadbalancerDeploy
+  attr_reader :host, :sshkit
+  delegate :execute, :info, to: :sshkit
+
+  def initialize(host, sshkit, targets: DASH.loadbalancer_config.target_hosts)
+    @host = host
+    @sshkit = sshkit
+    @targets = targets
+  end
+
+  def run
+    Dash::Cli::Proxy::LoadbalancerClaim.new(host, sshkit).claim_service
+    info "Deploying to loadbalancer on #{host} with targets: #{@targets.join(', ')}"
+    execute *DASH.loadbalancer.deploy(targets: @targets)
+  end
+end

data/lib/dash/cli/proxy/loadbalancer_reboot.rb

@@ -96,7 +96,7 @@ class Dash::Cli::Proxy::LoadbalancerReboot
     # `list --json` returns {"services": {"<name>": ...}} - exact key
     # membership, same as the per-host proxy reboot's verification.
     def verify_service
-      listed = JSON.parse(capture_with_info(*DASH.loadbalancer.list(json: true))).fetch("services", {}).keys
+      listed = Dash::Commands::Proxy::Services.parse(capture_with_info(*DASH.loadbalancer.list(json: true))).keys
 
       unless listed.include?(DASH.config.service)
         raise Dash::Cli::BootError, "the load balancer on #{host} is missing service #{DASH.config.service} after reboot"

data/lib/dash/cli/proxy/reboot.rb

@@ -143,16 +143,11 @@ class Dash::Cli::Proxy::Reboot
       registered_services = []
 
       DASH.roles_on(host).select(&:running_proxy?).each do |role|
-        app = DASH.app(role: role, host: host)
-
-        version = capture_with_info(*app.current_running_version, raise_on_non_zero_exit: false).strip.presence
-        next unless version
-
-        endpoint = capture_with_info(*app.container_id_for_version(version, only_running: true), raise_on_non_zero_exit: false).strip.presence
-        next unless endpoint
+        endpoints = Dash::Cli::App::RunningTargets.new(sshkit, role: role, host: host).container_ids(only_running: true)
+        next if endpoints.empty?
 
         info "Re-registering #{role.container_prefix} with dash-proxy on #{host}..."
-        execute *app.deploy(target: endpoint)
+        execute *DASH.app(role: role, host: host).deploy(targets: endpoints)
         registered_services << role.container_prefix
       end
 
@@ -177,7 +172,7 @@ class Dash::Cli::Proxy::Reboot
     def verify_services(registered_services)
       return if registered_services.empty?
 
-      listed = JSON.parse(capture_with_info(*proxy.list(json: true))).fetch("services", {}).keys
+      listed = Dash::Commands::Proxy::Services.parse(capture_with_info(*proxy.list(json: true))).keys
       missing = registered_services - listed
 
       if missing.any?