yamine 0.20.0 → 0.21.0

data/lib/yamine/cli/system.rb

@@ -8,7 +8,7 @@ module Yamine
       # enable/kickstart/bootout` address it by. Renamed from "dev.ask.local"
       # (an ask-local leftover); the old label is cleared on install so the
       # two never coexist and fight over port 443.
-      LAUNCHD_LABEL = "dev.yamine"
+      LAUNCHD_LABEL = PrivilegedPayload::LAUNCHD_LABEL
       LEGACY_LAUNCHD_LABELS = %w[dev.ask.local].freeze
 
       module_function
@@ -53,20 +53,31 @@ module Yamine
         sub = args.first
         case sub
         when "sync"
-          hostnames = ctx.store.load_routes.map { |r| r["hostname"] }
-          if Hosts.sync(hostnames)
-            puts "Synced #{hostnames.length} hostname(s) to /etc/hosts."
-          elsif !ProxyControl.root? && !hostnames.empty?
-            # /etc/hosts is root-owned; once the root service is
-            # installed the guidance is "run yamine hosts sync" — so
-            # make that command work by re-running it elevated.
-            puts "Writing /etc/hosts needs root — re-running elevated..."
-            state = Certs.state_dir
-            cmd = ["env", "YAMINE_STATE_DIR=#{state}", RbConfig.ruby,
-              ProxyControl.bin_path, "hosts", "sync"]
-            exit(elevate(cmd) ? 0 : 1)
-          else
-            $stderr.puts "Could not write /etc/hosts (try sudo)."
+          store = privileged_store(ctx)
+          hostnames = store.load_routes.map { |r| r["hostname"] }
+          begin
+            tlds = Hosts.default_scope_tlds(store.dir)
+            if Hosts.sync(hostnames, Hosts::PATH, tlds: tlds)
+              puts "Synced #{hostnames.length} hostname(s) to /etc/hosts."
+            elsif !ProxyControl.root? && !hostnames.empty?
+              # /etc/hosts is root-owned; once the root service is
+              # installed the guidance is "run yamine hosts sync" — so
+              # make that command work by re-running it elevated through
+              # the STAGED payload (root-owned, version-independent).
+              # The gem directory is never executed as root here.
+              puts "Writing /etc/hosts needs root — re-running elevated..."
+              unless PrivilegedPayload.staged?
+                $stderr.puts "No staged payload is installed — run once in a terminal: sudo yamine service install"
+                $stderr.puts "  (that stages the root-owned payload; steady-state syncs then work via the grant from `yamine sudoers`)"
+                exit 1
+              end
+              exit(elevate(granted_hosts_sync_argv) ? 0 : 1)
+            else
+              $stderr.puts "Could not write /etc/hosts (try sudo)."
+              exit 1
+            end
+          rescue Error => e
+            $stderr.puts "Error: #{e.message}"
             exit 1
           end
         when "clean"
@@ -107,10 +118,11 @@ module Yamine
             privileged = port < 1024 && !ProxyControl.root?
             if privileged && !ctx.interactive?
               $stderr.puts "Error: proxy is not running and port #{port} needs root."
-              $stderr.puts "  Human: run this once — yamine setup"
-              $stderr.puts "  Agent/CI: pre-provision passwordless sudo once —"
-              $stderr.puts "    yamine sudoers > /tmp/yamine.sudoers"
-              $stderr.puts "    sudo install -o root -g wheel -m 440 /tmp/yamine.sudoers /etc/sudoers.d/yamine"
+              $stderr.puts "  Human: run this once in a terminal — yamine setup (or: sudo yamine service install)"
+              $stderr.puts "  Agent/CI: the 443 service is installed by a human once per machine — it cannot be provisioned passwordlessly."
+              $stderr.puts "    Steady-state hosts sync works via the grant instead:"
+              $stderr.puts "      yamine sudoers > /tmp/yamine.sudoers"
+              $stderr.puts "      sudo install -o root -g wheel -m 440 /tmp/yamine.sudoers /etc/sudoers.d/yamine"
               $stderr.puts "  Or start the proxy by hand: sudo yamine proxy start"
               exit 1
             end
@@ -206,29 +218,67 @@ module Yamine
         when "install" then exit(service_install(ctx, args) ? 0 : 1)
         when "uninstall" then exit(service_uninstall(ctx) ? 0 : 1)
         when "status" then service_status(ctx)
-        else raise Error, "Usage: yamine service [install|uninstall|status]"
+        when "stage" then exit(service_stage(ctx, args) ? 0 : 1)
+        else raise Error, "Usage: yamine service [install|uninstall|status|stage]"
         end
       end
 
-      # Print the scoped passwordless-sudo rules that let `service install`
-      # (and only it) run without a prompt. The service re-execs the whole
-      # gem under sudo, so the safe NOPASSWD grants exactly the gem path +
-      # subcommand for the current user — never a bare interpreter. This is
-      # how agents and repeat machines get clean :443 without a TTY.
+      # The exact argv sudo runs for each passwordless grant rule.
+      # Single source of truth: `sudoers` prints these and the
+      # elevation call sites invoke them byte-identical. sudo matches
+      # the command path plus every concatenated argument and strips
+      # no `env` prefix, so any drift here — an env wrapper, a
+      # reordered flag, an unescaped space — silently disables the
+      # grant and `sudo -n` fails with "a password is required". The
+      # parity test pins both sides to these arrays. Evaluated per
+      # call (not constants): the staged path honors
+      # YAMINE_PRIVILEGED_ROOT.
+      def granted_hosts_sync_argv
+        [RbConfig.ruby, PrivilegedPayload.bin_path, "hosts", "sync"]
+      end
+
+      def granted_uninstall_argv
+        [RbConfig.ruby, PrivilegedPayload.bin_path, "service", "uninstall", "--internal"]
+      end
+
+      # sudoers splits a command spec on unescaped spaces, so a staged
+      # path containing one ("/Library/Application Support/...") must
+      # be escaped or the rule can never match anything.
+      def sudoers_escape(word)
+        word.to_s.gsub(" ", "\\ ")
+      end
+
+      # Print the scoped passwordless-sudo rules for steady-state agent
+      # work. The grant pins the ROOT-OWNED staged payload at its
+      # version-independent path — never the user-writable gem
+      # directory — and keeps only what can never introduce or modify
+      # root-executed code: the data-only `hosts sync` (hostnames
+      # strictly validated inside the managed /etc/hosts block) and
+      # `service uninstall` (which only deletes yamine's own files).
+      # Installing or upgrading the staged payload stages user-writable
+      # source into root-owned paths, so it stays a human-authorized
+      # interactive sudo and is deliberately NOT in this grant.
+      #
+      # Re-run after upgrading if your /etc/sudoers.d/yamine still pins
+      # a version-stamped gem path: those rules go stale every release.
+      # This output never does.
       #
       #   macOS: sudo install -o root -g wheel -m 440 <(yamine sudoers) /etc/sudoers.d/yamine
       #   Linux: sudo install -o root -g root -m 440 <(yamine sudoers) /etc/sudoers.d/yamine
       def sudoers(_ctx, _args)
         require "etc"
-        ruby = RbConfig.ruby
-        bin = ProxyControl.bin_path
         user = ENV.fetch("USER", Etc.getlogin)
+        rules = [granted_hosts_sync_argv, granted_uninstall_argv].map do |argv|
+          "#{user} ALL=(root) NOPASSWD: #{argv.map { |w| sudoers_escape(w) }.join(" ")}"
+        end
         puts <<~SUDOERS
-          # yamine: let #{user} install/run the privileged proxy on port 443
-          # without a password prompt. Scoped to yamine's own service
-          # re-exec — the gem path above, not a bare interpreter.
-          #{user} ALL=(root) NOPASSWD: #{ruby} #{bin} service install --internal
-          #{user} ALL=(root) NOPASSWD: #{ruby} #{bin} service uninstall --internal
+          # yamine: steady-state passwordless rules for #{user}. The staged
+          # payload below is root-owned at a version-independent path, so
+          # these rules survive gem upgrades — re-run `yamine sudoers` once
+          # if your installed file still pins a version-stamped gem path.
+          # Service install/upgrade is deliberately absent: staging new
+          # root-executed code needs an interactive sudo (Touch ID).
+          #{rules.join("\n")}
         SUDOERS
       end
 
@@ -238,11 +288,12 @@ module Yamine
       # routes registered by unprivileged CLIs are shared. The root half
       # can also write /etc/hosts.
       #
-      # Non-interactive runs (agents, CI) use `sudo -n`: never prompts,
-      # succeeds only when the scoped NOPASSWD grant from `yamine
-      # sudoers` is installed, and fails fast with guidance otherwise.
-      # Interactive runs use plain sudo (one password, then the service
-      # is installed for good).
+      # Staging user-writable source into root-owned paths is never
+      # passwordless: non-interactive runs (agents, CI) fail fast
+      # pointing at the human step, because the grant from `yamine
+      # sudoers` deliberately covers no install rule. Interactive runs
+      # use plain sudo (one Touch ID tap), then the service is installed
+      # for good.
       #
       # Returns true when the service is installed. No exit here: the
       # bare `service install` CLI exits in `service`, while `setup`
@@ -251,18 +302,32 @@ module Yamine
         if ProxyControl.root?
           install_service!(ctx)
         elsif args.include?("--internal")
-          raise Error, "`service install --internal` is the root half of the sudo re-exec — run `yamine service install`"
+          raise Error, "`service install --internal` is the root half of the sudo re-exec — run `sudo yamine service install` in a terminal"
+        elsif !ctx.interactive?
+          $stderr.puts "service install stages root-executed code, so it needs an interactive sudo (one Touch ID tap) — it is deliberately not covered by the passwordless grant."
+          $stderr.puts "  Human: run in a terminal — sudo yamine service install"
+          $stderr.puts "  Agents: the 443 service is installed by a human once per machine; steady-state hosts sync works via the grant — yamine sudoers"
+          false
         else
           puts "Installing system service (sudo required)..."
-          state = Certs.state_dir
-          cmd = ["env", "YAMINE_STATE_DIR=#{state}",
-            RbConfig.ruby, ProxyControl.bin_path,
+          # No `env` prefix: nothing crosses the sudo boundary, and no
+          # grant rule needs to match this — the human sudo prompts.
+          # The root half derives the invoking user's state dir from
+          # SUDO_USER (see privileged_store).
+          cmd = [RbConfig.ruby, ProxyControl.bin_path,
             "service", "install", "--internal"]
           elevate(cmd)
         end
       end
 
       def install_service!(ctx)
+        # Stage first, register second: a staging failure raises before
+        # any unit exists, so a failed install can never leave a unit
+        # pointing at an unverified payload — and the running daemon
+        # (legacy or current) keeps serving untouched.
+        store = privileged_store(ctx)
+        version = PrivilegedPayload.stage!(state_dir: store.dir)
+        puts "    Staged privileged payload v#{version} (#{PrivilegedPayload.root_dir})."
         case RUBY_PLATFORM
         when /darwin/ then install_launchd(ctx)
         when /linux/ then install_systemd
@@ -272,27 +337,68 @@ module Yamine
         # far while elevated — Safari works the moment setup finishes
         # (Chrome resolves *.localhost natively).
         sync_hosts_from_routes(ctx)
+        print_interpreter_note
         true
       end
 
+      # The interpreter caveat, said out loud at every install: the unit
+      # runs a user-writable Ruby (no root-owned Ruby >= 3.2 exists on
+      # this machine), so the payload being root-owned is necessary but
+      # not sufficient. Never papered over.
+      # Root half of the sudo-daemon staging step (`service stage
+      # --internal`): create the root-owned payload from the running gem
+      # source. Invoked only under an already human-authorized sudo —
+      # the --no-service fallback's prompt, or an explicit admin sudo —
+      # which is what authorizes running the gem source once to mint the
+      # payload the daemon then runs. Never granted, never passwordless.
+      def service_stage(ctx, args)
+        unless ProxyControl.root? && args.include?("--internal")
+          raise Error, "`service stage --internal` is the root half of the sudo-daemon staging step — run `yamine setup --no-service` or `sudo yamine service install`"
+        end
+        store = privileged_store(ctx)
+        version = PrivilegedPayload.stage!(state_dir: store.dir)
+        puts "Staged privileged payload v#{version} (#{PrivilegedPayload.root_dir})."
+        print_interpreter_note
+        true
+      end
+
+      def print_interpreter_note
+        ruby = PrivilegedPayload.ruby_info
+        return unless ruby[:writable]
+
+        puts "    NOTE: the service runs #{ruby[:path]}, which is user-writable —"
+        puts "    only the staged payload above is root-owned. See README (port 443) for the residual risk."
+      end
+
       def sync_hosts_from_routes(ctx)
-        hostnames = ctx.store.load_routes.map { |r| r["hostname"] }
+        store = privileged_store(ctx)
+        hostnames = store.load_routes.map { |r| r["hostname"] }
         if hostnames.empty?
           puts "    No routes registered yet — hosts sync will happen on the next boot."
         elsif Yamine::Hosts.synced?(hostnames)
           puts "    /etc/hosts already lists #{hostnames.length} hostname(s)."
-        elsif Yamine::Hosts.sync(hostnames)
-          puts "    Synced #{hostnames.length} hostname(s) to /etc/hosts."
         else
-          warn "    could not write /etc/hosts (run `sudo yamine hosts sync` later)"
+          begin
+            if Yamine::Hosts.sync(hostnames, Yamine::Hosts::PATH,
+              tlds: Yamine::Hosts.default_scope_tlds(store.dir))
+              puts "    Synced #{hostnames.length} hostname(s) to /etc/hosts."
+            else
+              warn "    could not write /etc/hosts (run `sudo yamine hosts sync` later)"
+            end
+          rescue Error => e
+            warn "    hosts sync skipped: #{e.message}"
+          end
         end
       end
 
       # Run a privileged command via sudo. Interactive: plain sudo (one
-      # prompt). Non-interactive: `sudo -n` — no prompt ever; requires the
-      # NOPASSWD grant from `yamine sudoers`. On failure prints the
+      # prompt). Non-interactive: `sudo -n` — no prompt ever; requires
+      # the NOPASSWD grant from `yamine sudoers`. On failure prints the
       # provisioning hint so agents/CI know exactly what to install.
-      def elevate(cmd)
+      # The :grant hint names the passwordless rules (hosts sync,
+      # uninstall); :human points at the interactive install step, for
+      # commands no grant will ever cover.
+      def elevate(cmd, hint: :grant)
         interactive = $stdin.tty? && ENV["CI"].nil?
         sudo_args = interactive ? ["sudo"] : ["sudo", "-n"]
         ok = Command.run(*sudo_args, *cmd)
@@ -304,6 +410,9 @@ module Yamine
         # runs, where a missing NOPASSWD rule is the usual cause.
         if interactive
           $stderr.puts "sudo failed — re-run `yamine setup` to try again."
+        elsif hint == :human
+          $stderr.puts "sudo failed — this step needs an interactive sudo (one Touch ID tap)."
+          $stderr.puts "  Human: run in a terminal — sudo yamine service install"
         else
           $stderr.puts "sudo failed — install the scoped grant once:"
           $stderr.puts "  yamine sudoers > /tmp/yamine.sudoers"
@@ -324,12 +433,42 @@ module Yamine
         Certs.home
       end
 
-      def install_launchd(ctx)
+      # The invoking user's state dir inside the root half of a sudo
+      # re-exec. Nothing crosses the sudo boundary (no `env` prefix, no
+      # SETENV — which would let RUBYOPT/RUBYLIB smuggle code into the
+      # root process): sudo sets SUDO_USER itself, while env_reset makes
+      # HOME root's, so HOME alone is not enough. Same SUDO_USER
+      # precedent as user_home_for_service; unprivileged resolution
+      # (Certs.state_dir) is untouched.
+      def invoking_state_dir
+        File.join(user_home_for_service, ".yamine")
+      end
+
+      # The store a root half acts on. As root without an explicit dir,
+      # ctx.store would resolve through root's HOME — but the invoking
+      # user's routes live under their own dir, so derive it from
+      # SUDO_USER instead. An explicit dir survives only when a human
+      # passed it through sudo deliberately (env_reset strips it
+      # otherwise); honor that so custom state dirs keep working.
+      # Unprivileged runs keep ctx.store untouched.
+      def privileged_store(ctx)
+        return ctx.store unless ProxyControl.root?
+
+        env_dir = ENV["YAMINE_STATE_DIR"]
+        return ctx.store if env_dir && !env_dir.empty?
+
+        RouteStore.new(invoking_state_dir, on_warning: ->(m) { warn m })
+      end
+
+      def install_launchd(ctx, dir = "/Library/LaunchDaemons")
         require "etc"
         home = user_home_for_service
         state_dir = ENV["YAMINE_STATE_DIR"] || File.join(home, ".yamine")
-        dir = "/Library/LaunchDaemons"
-        FileUtils.mkdir_p(dir)
+        # The unit references ONLY the root-owned staged payload — never
+        # the user-writable gem directory it was staged from. (The
+        # interpreter stays RbConfig.ruby: no root-owned Ruby >= 3.2
+        # exists, so that residual risk is reported, not hidden.)
+        payload_bin = PrivilegedPayload.bin_path
         plist = <<~PLIST
           <?xml version="1.0" encoding="UTF-8"?>
           <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -339,7 +478,7 @@ module Yamine
             <key>ProgramArguments</key>
             <array>
               <string>#{RbConfig.ruby}</string>
-              <string>#{ProxyControl.bin_path}</string>
+              <string>#{payload_bin}</string>
               <string>proxy</string><string>start</string><string>--foreground</string>
               <string>--port</string><string>#{ProxyControl::DEFAULT_TLS_PORT}</string>
             </array>
@@ -354,6 +493,7 @@ module Yamine
           </plist>
         PLIST
         remove_legacy_launchd(dir)
+        FileUtils.mkdir_p(dir)
         path = File.join(dir, "#{LAUNCHD_LABEL}.plist")
         File.write(path, plist)
         File.chmod(0o644, path)
@@ -369,6 +509,7 @@ module Yamine
         puts "    Registering the launchd service on port 443..."
         launchctl_bootstrap(path)
         puts "Installed root LaunchDaemon on port 443 (state: #{state_dir})."
+        puts "    Payload: #{payload_bin} (root-owned, version-independent)."
       end
 
       # True when the trust store covers the CA this machine should be
@@ -444,7 +585,8 @@ module Yamine
       end
 
       # Pure unit-file builder (testable without root). Binds 80/443 at
-      # boot; the proxy runs with the invoking user's state dir.
+      # boot; the proxy runs with the invoking user's state dir. The
+      # payload is the root-owned staged path — never the gem directory.
       def systemd_unit
         home = user_home_for_service
         state_dir = ENV["YAMINE_STATE_DIR"] || File.join(home, ".yamine")
@@ -454,7 +596,7 @@ module Yamine
           After=network.target
 
           [Service]
-          ExecStart=#{RbConfig.ruby} #{ProxyControl.bin_path} proxy start --foreground --port #{ProxyControl::DEFAULT_TLS_PORT}
+          ExecStart=#{RbConfig.ruby} #{PrivilegedPayload.bin_path} proxy start --foreground --port #{ProxyControl::DEFAULT_TLS_PORT}
           Environment=YAMINE_STATE_DIR=#{state_dir}
           Environment=HOME=#{home}
 
@@ -466,8 +608,7 @@ module Yamine
       # Install + start the systemd unit (mirrors portless). We are root
       # here (sudo re-exec). The unit is written root-owned, then enabled
       # and started.
-      def install_systemd
-        unit_path = "/etc/systemd/system/yamine.service"
+      def install_systemd(unit_path = "/etc/systemd/system/yamine.service")
         File.write(unit_path, systemd_unit)
         File.chmod(0o644, unit_path)
         File.chown(0, 0, unit_path) if Process.uid.zero?
@@ -475,36 +616,59 @@ module Yamine
         Command.run("systemctl", "daemon-reload") or raise Error, "systemctl daemon-reload failed"
         Command.run("systemctl", "enable", "--now", "yamine") or raise Error, "systemctl enable failed"
         puts "Installed systemd service yamine on port 443."
+        puts "    Payload: #{PrivilegedPayload.bin_path} (root-owned, version-independent)."
       end
 
       def service_uninstall(ctx)
         if !ProxyControl.root?
-          puts "Removing system service (sudo required)..."
-          state = Certs.state_dir
-          cmd = ["env", "YAMINE_STATE_DIR=#{state}",
-            RbConfig.ruby, ProxyControl.bin_path, "service", "uninstall", "--internal"]
-          return elevate(cmd)
+          if PrivilegedPayload.staged?
+            # The grant covers exactly this argv: the root-owned staged
+            # payload removing yamine's own files. Passwordless-capable.
+            puts "Removing system service (sudo required)..."
+            return elevate(granted_uninstall_argv)
+          elsif !ctx.interactive?
+            $stderr.puts "No staged payload is installed, so uninstall needs an interactive sudo."
+            $stderr.puts "  Human: run in a terminal — sudo yamine service uninstall"
+            return false
+          else
+            # Legacy cleanup: no staged payload, but a legacy unit may
+            # still be installed. Human sudo only — no grant covers the
+            # gem path anymore, and nothing crosses the sudo boundary.
+            puts "Removing system service (sudo required)..."
+            cmd = [RbConfig.ruby, ProxyControl.bin_path, "service", "uninstall", "--internal"]
+            return elevate(cmd, hint: :human)
+          end
         end
         case RUBY_PLATFORM
         when /darwin/
-          path = "/Library/LaunchDaemons/#{LAUNCHD_LABEL}.plist"
-          launchctl_bootout(path) if File.file?(path)
-          FileUtils.rm_f(path)
-          # Also clear any pre-rename service, so uninstall leaves no root
-          # proxy behind on a machine upgraded from an older yamine.
-          remove_legacy_launchd
-          puts "Removed root LaunchDaemon."
+          uninstall_launchd
         when /linux/
-          Command.run("systemctl", "disable", "--now", "yamine")
-          Command.run("systemctl", "daemon-reload")
-          FileUtils.rm_f("/etc/systemd/system/yamine.service")
-          puts "Removed systemd service yamine."
+          uninstall_systemd
         else
           raise Error, "Service uninstall not supported on #{RUBY_PLATFORM}"
         end
+        PrivilegedPayload.remove_payload!
+        puts "Removed staged payload (#{PrivilegedPayload.root_dir})."
         true
       end
 
+      def uninstall_launchd(dir = "/Library/LaunchDaemons")
+        path = File.join(dir, "#{LAUNCHD_LABEL}.plist")
+        launchctl_bootout(path) if File.file?(path)
+        FileUtils.rm_f(path)
+        # Also clear any pre-rename service, so uninstall leaves no root
+        # proxy behind on a machine upgraded from an older yamine.
+        remove_legacy_launchd(dir)
+        puts "Removed root LaunchDaemon."
+      end
+
+      def uninstall_systemd(unit_path = "/etc/systemd/system/yamine.service")
+        Command.run("systemctl", "disable", "--now", "yamine")
+        Command.run("systemctl", "daemon-reload")
+        FileUtils.rm_f(unit_path)
+        puts "Removed systemd service yamine."
+      end
+
       def service_status(ctx)
         port = ProxyControl.proxy_port(ctx.store)
         if port.nil? || !ProxyControl.listening?(port)
@@ -594,6 +758,8 @@ module Yamine
               (no separate GUI authorization popup).
               --no-service: trust the CA at user level, then run a sudo
               daemon instead (no boot persistence; ephemeral machines).
+              The daemon runs the staged root-owned payload, staging it
+              first under the same sudo when missing.
 
             Both finish by syncing /etc/hosts and verifying with doctor.
           HELP
@@ -640,8 +806,13 @@ module Yamine
           # The root service install already synced under elevation; a
           # plain re-run must not fail rewriting /etc/hosts unprivileged
           # when the block is already in place.
-          unless Yamine::Hosts.synced?(hostnames) || Yamine::Hosts.sync(hostnames)
-            abort_setup("Could not write /etc/hosts.",
+          begin
+            unless Yamine::Hosts.synced?(hostnames) || Yamine::Hosts.sync(hostnames)
+              abort_setup("Could not write /etc/hosts.",
+                "Run `sudo yamine hosts sync`, then re-run `yamine setup`.")
+            end
+          rescue Error => e
+            abort_setup("Could not sync /etc/hosts: #{e.message}",
               "Run `sudo yamine hosts sync`, then re-run `yamine setup`.")
           end
         end
@@ -671,12 +842,15 @@ module Yamine
       end
 
       # The two ways to get a privileged proxy on 443: a human runs setup
-      # once (interactive sudo), or an agent/CI image is pre-provisioned
-      # with the scoped NOPASSWD rules from `yamine sudoers`.
+      # once (interactive sudo), or the machine already has the root
+      # service and agents keep its hosts entries fresh through the
+      # passwordless hosts-sync grant from `yamine sudoers`. Service
+      # install itself is never passwordless.
       def privileged_port_hint
         [
-          "Human: run this once — yamine setup",
-          "Agent/CI: pre-provision passwordless sudo once —",
+          "Human: run this once in a terminal — yamine setup (or: sudo yamine service install)",
+          "Agent/CI: the 443 service is installed by a human once per machine;",
+          "  steady-state hosts sync works via the grant instead —",
           "  yamine sudoers > /tmp/yamine.sudoers",
           "  sudo install -o root -g wheel -m 440 /tmp/yamine.sudoers /etc/sudoers.d/yamine"
         ]
@@ -699,7 +873,8 @@ module Yamine
         port, tls = 443, true
         unless ctx.interactive?
           warn "    no TTY available for the sudo prompt."
-          warn "    Agent/CI: pre-provision passwordless sudo once —"
+          warn "    A human installs the 443 service once per machine (yamine setup in a terminal);"
+          warn "    steady-state hosts sync works via the grant instead:"
           warn "      yamine sudoers > /tmp/yamine.sudoers"
           warn "      sudo install -o root -g wheel -m 440 /tmp/yamine.sudoers /etc/sudoers.d/yamine"
           return false
@@ -869,8 +1044,12 @@ module Yamine
         # is the common case and must stay silent: warning there sent
         # people to a sudo write for a file that needed nothing.
         hostnames = ctx.store.load_routes.map { |r| r["hostname"] }
-        unless hostnames.empty? || Yamine::Hosts.synced?(hostnames) || Hosts.sync(hostnames)
-          warn "Warning: could not write /etc/hosts (try sudo yamine hosts sync)."
+        begin
+          unless hostnames.empty? || Yamine::Hosts.synced?(hostnames) || Hosts.sync(hostnames)
+            warn "Warning: could not write /etc/hosts (try sudo yamine hosts sync)."
+          end
+        rescue Error => e
+          warn "Warning: #{e.message}"
         end
       end
       # yamine kamal <variant> [--app myapp] [--domain preview.example.com]

data/lib/yamine/cli/worktree.rb

@@ -668,7 +668,12 @@ module Yamine
       def resync_hosts(ctx)
         ctx.store.prune_stale
         hostnames = ctx.store.load_routes.map { |r| r["hostname"] }
-        return if Hosts.sync(hostnames)
+        begin
+          return if Hosts.sync(hostnames)
+        rescue Error => e
+          warn "Warning: #{e.message}"
+          return
+        end
 
         warn "Warning: could not update /etc/hosts (try sudo yamine hosts sync)."
       end

data/lib/yamine/cli.rb

@@ -99,7 +99,7 @@ module Yamine
           yamine skills install           Install yamine skill into ~/.agents/skills/ (or --local)
           yamine proxy start|stop       Control the proxy
           yamine service install|status|uninstall   OS startup service
-          yamine sudoers                Print scoped passwordless-sudo rules for port 443
+          yamine sudoers                Print scoped passwordless-sudo rules for steady-state hosts sync
           yamine hosts sync|clean       Manage /etc/hosts entries
           yamine kamal <variant>        Preview-deploy snippet for Kamal
           yamine stop                   Stop this app's backend + routes

data/lib/yamine/doctor.rb

@@ -35,6 +35,7 @@ module Yamine
       checks << check_ca
       checks << check_ca_bundle
       checks << check_serving_ca(port, tls: tls)
+      checks << check_service
       checks
     end
 
@@ -277,6 +278,71 @@ module Yamine
       0
     end
 
+    # The privileged service: what runs as root on port 443.
+    #
+    # Three states. A legacy unit — payload inside a user home or a
+    # version-stamped gem directory — keeps working, so it warns (never
+    # fails) with the exact migration. A staged unit whose tree fails
+    # ownership verification FAILS: user-writable code running as root
+    # is the hole this check exists to close. Version skew between the
+    # staged payload and this CLI warns. The interpreter is always
+    # reported truthfully when a service exists: there is no root-owned
+    # Ruby new enough for the gem, so the daemon runs a user-writable
+    # interpreter and that residual risk stays visible.
+    def check_service
+      unless PrivilegedPayload.service_unit_present?
+        return Check.new(name: "service", ok: true,
+          message: "no privileged service installed — skipped")
+      end
+
+      ref = PrivilegedPayload.installed_payload_ref
+      if ref.nil?
+        return Check.new(name: "service", ok: true, warn: true,
+          message: "a privileged unit is installed but its payload path is unreadable" \
+            " — re-install it: sudo yamine service install")
+      end
+
+      if PrivilegedPayload.legacy_ref?(ref)
+        return Check.new(name: "service", ok: true, warn: true,
+          message: "the privileged service runs a user-writable legacy payload (#{ref}) — " \
+            "migrate it: sudo yamine service install")
+      end
+
+      problems = []
+      warnings = []
+      begin
+        PrivilegedPayload.verify!
+      rescue Error => e
+        problems << "#{e.message} — re-install it: sudo yamine service install"
+      end
+
+      staged = PrivilegedPayload.staged_version
+      if staged.nil?
+        warnings << "the service points at the staged payload but no staged version is recorded" \
+          " — re-install it: sudo yamine service install"
+      elsif staged != Yamine::VERSION
+        warnings << "the staged payload is v#{staged}, this CLI is v#{Yamine::VERSION}" \
+          " — re-install it: sudo yamine service install"
+      end
+
+      ruby = PrivilegedPayload.ruby_info
+      if ruby[:writable]
+        warnings << "the service interpreter #{ruby[:path]} is user-writable — " \
+          "anything that can write it changes what runs as root; only the payload above is root-owned " \
+          "(no root-owned Ruby >= 3.2 exists on this machine, so this residual risk stays until one does)"
+      end
+
+      if problems.empty? && warnings.empty?
+        Check.new(name: "service", ok: true,
+          message: "staged payload v#{staged} (#{PrivilegedPayload.bin_path})")
+      elsif problems.empty?
+        Check.new(name: "service", ok: true, warn: true, message: warnings.join("; "))
+      else
+        Check.new(name: "service", ok: false,
+          message: (problems + warnings).join("; "))
+      end
+    end
+
     def print(checks, out: $stdout, json: false)
       if json
         require "json"