mxup 0.2.0 → 0.3.0

data/lib/mxup/config.rb

@@ -2,6 +2,7 @@
 
 require 'yaml'
 require 'set'
+require_relative 'env_file'
 
 module Mxup
   # Parsed mxup YAML config. Pure data; no tmux or filesystem side effects.
@@ -13,15 +14,29 @@ module Mxup
   # rest of the system (Launcher, Reconciler, StatusView…) never has to know
   # about profiles.
   class Config
-    attr_reader :session, :setup, :windows, :layouts, :layout_names,
-                :profile, :profile_names, :default_profile
+    KNOWN_TOP_LEVEL_KEYS    = %w[session setup root live_env required_env windows layouts profiles default_profile].freeze
+    KNOWN_WINDOW_KEYS       = %w[root command env wait_for live_env commands].freeze
+    KNOWN_LAYOUT_GROUP_KEYS = %w[panes split].freeze
+    KNOWN_PROFILE_KEYS      = %w[setup root layouts live_env windows].freeze
+
+    attr_reader :session, :setup, :root, :windows, :layouts, :layout_names,
+                :profile, :profile_names, :default_profile, :live_env,
+                :live_env_dir, :required_env, :env_file_path
 
     def initialize(path, profile: nil)
       raw = YAML.safe_load(File.read(path), permitted_classes: [Symbol])
+      validate_keys!(raw, KNOWN_TOP_LEVEL_KEYS, 'top level')
       resolve_profile!(raw, profile)
-      @session = raw.fetch('session')
-      @setup   = raw['setup']&.strip
-      @windows = parse_windows(raw.fetch('windows'))
+      @session      = raw.fetch('session')
+      @setup        = raw['setup']&.strip
+      @live_env_dir = config_base_dir(path)
+      @live_env     = parse_live_env(raw['live_env'])
+      @required_env = parse_required_env(raw['required_env'])
+      @env_file_path = env_file_path_for(path)
+      load_env_file_into_env!
+      @root         = resolve_root(raw['root'], path)
+      @windows      = parse_windows(raw.fetch('windows'))
+      validate_window_live_env!
       @layouts, @layout_names = parse_layouts(raw['layouts'])
     end
 
@@ -91,6 +106,8 @@ module Mxup
     def apply_profile_overrides!(raw, override)
       return unless override.is_a?(Hash)
 
+      validate_keys!(override, KNOWN_PROFILE_KEYS, "profile '#{@profile}'")
+
       if override.key?('session')
         raise ArgumentError,
               "Profile '#{@profile}' cannot override 'session'; profiles of the " \
@@ -98,8 +115,15 @@ module Mxup
       end
 
       raw['setup']   = override['setup']   if override.key?('setup')
+      raw['root']    = override['root']    if override.key?('root')
       raw['layouts'] = override['layouts'] if override.key?('layouts')
 
+      if override.key?('live_env')
+        base_le = raw['live_env'] || {}
+        prof_le = override['live_env'] || {}
+        raw['live_env'] = base_le.merge(prof_le)
+      end
+
       removed = []
       (override['windows'] || {}).each do |wname, woverride|
         raw['windows'] ||= {}
@@ -135,11 +159,12 @@ module Mxup
       end
     end
 
-    # Shallow merge with a special case: `env` is itself a hash that should
-    # be merged (so a profile can tweak one key without redeclaring the rest).
+    # Shallow merge with a special case: `env` and `commands` are themselves
+    # hashes that should be merged (so a profile can tweak one key without
+    # redeclaring the rest).
     def merge_window(base, override)
       base.merge(override) do |key, base_val, prof_val|
-        if key == 'env' && base_val.is_a?(Hash) && prof_val.is_a?(Hash)
+        if %w[env commands].include?(key) && base_val.is_a?(Hash) && prof_val.is_a?(Hash)
           base_val.merge(prof_val)
         else
           prof_val
@@ -150,16 +175,165 @@ module Mxup
     def parse_windows(hash)
       hash.map do |name, opts|
         opts ||= {}
+        validate_keys!(opts, KNOWN_WINDOW_KEYS, "window '#{name}'")
         Window.new(
           name:     name,
-          root:     File.expand_path(opts.fetch('root')),
+          root:     resolve_window_root(opts.fetch('root')),
           command:  opts['command']&.strip,
           env:      opts['env'] || {},
-          wait_for: WaitSpec.parse(opts['wait_for'])
+          wait_for: WaitSpec.parse(opts['wait_for']),
+          live_env: Array(opts['live_env']).map(&:to_s),
+          commands: parse_window_commands(opts['commands'], name)
         )
       end
     end
 
+    # Per-window named commands: { name => shell command }. Each is a one-off
+    # task runnable via `mxup <config> <window>:<name>`. It executes in a copy
+    # of the window's environment (root, setup, live_env, env) with its output
+    # streamed to the calling shell — it does not touch the live tmux pane.
+    def parse_window_commands(raw, window_name)
+      return {} if raw.nil?
+      unless raw.is_a?(Hash)
+        raise ArgumentError,
+              "window '#{window_name}': commands must be a map of NAME => command, " \
+              "got #{raw.class}"
+      end
+
+      raw.each_with_object({}) do |(name, command), acc|
+        if command.nil? || command.to_s.strip.empty?
+          raise ArgumentError,
+                "window '#{window_name}': command '#{name}' must specify a shell command"
+        end
+        acc[name.to_s] = command.to_s.strip
+      end
+    end
+
+    # Top-level live_env: { VAR_NAME => shell command }. The command's stdout
+    # becomes the variable's value; it is re-evaluated on every (re)start and
+    # polled by the watcher, so rotating whatever it reads restarts dependents.
+    # Commands run in the config's base dir (see #live_env_dir), so relative
+    # paths inside them resolve there regardless of a window's own root.
+    def parse_live_env(raw)
+      return {} if raw.nil?
+      unless raw.is_a?(Hash)
+        raise ArgumentError, "live_env must be a map of VAR => command, got #{raw.class}"
+      end
+
+      raw.each_with_object({}) do |(name, command), acc|
+        if command.nil? || command.to_s.strip.empty?
+          raise ArgumentError, "live_env '#{name}' must specify a command"
+        end
+        acc[name.to_s] = command.to_s.strip
+      end
+    end
+
+    # Env vars that must hold a value before `mxup up` will start anything.
+    # Two forms:
+    #   required_env: [DATABASE_URL, API_KEY]          # names only
+    #   required_env: { API_KEY: "from the dashboard" } # name => description
+    # Descriptions (optional) are written as comments into the scaffolded
+    # env file so the user knows what each value is for.
+    def parse_required_env(raw)
+      case raw
+      when nil
+        []
+      when Array
+        raw.map { |name| RequiredVar.new(name: name.to_s, description: nil) }
+      when Hash
+        raw.map do |name, desc|
+          RequiredVar.new(name: name.to_s, description: desc&.to_s&.strip)
+        end
+      else
+        raise ArgumentError,
+              'required_env must be a list of names or a map of NAME => description, ' \
+              "got #{raw.class}"
+      end
+    end
+
+    # The `<config-name>.env` file sits next to the config file itself, so
+    # several configs sharing a directory (e.g. ~/.config/mxup) don't collide.
+    def env_file_path_for(config_path)
+      expanded = File.expand_path(config_path)
+      File.join(File.dirname(expanded), "#{File.basename(expanded, '.*')}.env")
+    end
+
+    def validate_window_live_env!
+      pool = @live_env.keys.to_set
+      @windows.each do |win|
+        win.live_env.each do |var|
+          next if pool.include?(var)
+          raise ArgumentError,
+                "Window '#{win.name}': live_env '#{var}' not declared in top-level live_env"
+        end
+      end
+    end
+
+    # Top-level `root` is resolved relative to the config file's "project
+    # directory" — that's the directory containing the config, except when
+    # the config lives in a project-local `.mxup/` directory, in which case
+    # we use its parent. That way a checked-in `.mxup/dev.yml` can write
+    # `root: .` and mean "the repo root", not "the .mxup/ folder".
+    def resolve_root(raw_root, config_path)
+      return nil unless raw_root
+      expanded = expand_env_vars(raw_root.to_s, 'root')
+      File.expand_path(expanded, config_base_dir(config_path))
+    end
+
+    # Merge the config's `.env` file into the process environment so that
+    # `$VAR` references in `root:` fields resolve from the same place the
+    # `required_env` gate validates — otherwise a value the user filled into
+    # the scaffolded `.env` file would be invisible here (it is only sourced
+    # inside each tmux pane) and root expansion would fail with "not set".
+    #
+    # The live shell environment wins: a var already exported (e.g. via
+    # direnv) is never overwritten. Blank file values are skipped so the
+    # required_env gate can still report them as missing rather than letting
+    # an empty path silently resolve against the wrong base.
+    def load_env_file_into_env!
+      return if @required_env.empty?
+      return unless File.exist?(@env_file_path)
+
+      EnvFile.new(self).parse.each do |key, value|
+        next if value.nil? || value.strip.empty?
+        ENV[key] ||= value
+      end
+    end
+
+    # Substitute $VAR and ${VAR} references from the process environment.
+    # An unset variable is a hard error: silently expanding to "" would
+    # resolve the path against the wrong base, so we fail loudly instead.
+    def expand_env_vars(value, context)
+      value.gsub(/\$\{(\w+)\}|\$(\w+)/) do
+        name = Regexp.last_match(1) || Regexp.last_match(2)
+        ENV[name] || raise(ArgumentError,
+                           "#{context}: environment variable '#{name}' is not set")
+      end
+    end
+
+    def validate_keys!(hash, allowed, context)
+      return unless hash.is_a?(Hash)
+      extra = hash.keys.map(&:to_s) - allowed
+      return if extra.empty?
+      raise ArgumentError,
+            "#{context}: unknown key(s) #{extra.map(&:inspect).join(', ')} " \
+            "(allowed: #{allowed.join(', ')})"
+    end
+
+    def config_base_dir(config_path)
+      dir = File.dirname(File.expand_path(config_path))
+      File.basename(dir) == LOCAL_CONFIG_DIR ? File.dirname(dir) : dir
+    end
+
+    # When the config declares a top-level `root`, relative window roots are
+    # resolved against it. Absolute paths and `~/...` are unaffected because
+    # File.expand_path ignores the base in those cases.
+    def resolve_window_root(window_root)
+      base = @root || Dir.pwd
+      expanded = expand_env_vars(window_root.to_s, 'window root')
+      File.expand_path(expanded, base)
+    end
+
     def parse_layouts(raw)
       return [{}, []] if raw.nil?
 
@@ -175,6 +349,8 @@ module Mxup
 
         groups_hash.each do |group_name, group_opts|
           group_opts ||= {}
+          validate_keys!(group_opts, KNOWN_LAYOUT_GROUP_KEYS,
+                         "layout '#{layout_name}' group '#{group_name}'")
           pane_names = Array(group_opts['panes'])
 
           pane_names.each do |pn|
@@ -203,12 +379,15 @@ module Mxup
     end
   end
 
-  Window    = Struct.new(:name, :root, :command, :env, :wait_for, keyword_init: true)
-  PaneGroup = Struct.new(:name, :window_names, :split,           keyword_init: true)
+  Window      = Struct.new(:name, :root, :command, :env, :wait_for, :live_env, :commands, keyword_init: true)
+  PaneGroup   = Struct.new(:name, :window_names, :split,           keyword_init: true)
+  RequiredVar = Struct.new(:name, :description,                    keyword_init: true)
 
   # A readiness check attached to a window.
   WaitSpec = Struct.new(:type, :target, :timeout, :interval, :label, keyword_init: true) do
     CHECK_TYPES = %w[tcp http path script].freeze
+    OPTION_KEYS = %w[timeout interval label].freeze
+    ALLOWED_KEYS = (CHECK_TYPES + OPTION_KEYS).freeze
 
     def self.parse(raw)
       case raw
@@ -217,6 +396,12 @@ module Mxup
       when String
         new(type: :tcp, target: raw, timeout: nil, interval: 2, label: raw)
       when Hash
+        extra = raw.keys.map(&:to_s) - ALLOWED_KEYS
+        unless extra.empty?
+          raise ArgumentError,
+                "wait_for: unknown key(s) #{extra.map(&:inspect).join(', ')} " \
+                "(allowed: #{ALLOWED_KEYS.join(', ')})"
+        end
         found = CHECK_TYPES & raw.keys
         unless found.size == 1
           raise ArgumentError,

data/lib/mxup/env_file.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Mxup
+  # Reads, validates, and scaffolds the `<config-name>.env` file that supplies
+  # values for the config's `required_env` vars.
+  #
+  # The file is a plain dotenv-style `KEY=value` list. `mxup up` checks every
+  # declared required var has a non-empty value here before starting anything;
+  # the values themselves reach each window because the launcher script sources
+  # this file (see Launcher#build_script).
+  class EnvFile
+    def initialize(config)
+      @config = config
+      @path   = config.env_file_path
+    end
+
+    # Required vars that are still missing a value (key absent, or value blank).
+    def missing
+      values = parse
+      @config.required_env.reject { |rv| present?(values[rv.name]) }
+    end
+
+    # Create the file, or append entries for any required vars not yet present
+    # as keys. Existing content and values are preserved. Returns the path.
+    def scaffold!
+      existing = File.exist?(@path) ? File.read(@path) : nil
+      existing = nil if existing && existing.strip.empty?
+
+      present_keys = parse(existing || '').keys
+      additions    = @config.required_env.reject { |rv| present_keys.include?(rv.name) }
+      return @path if additions.empty? && existing
+
+      parts = []
+      parts << if existing
+                 existing.rstrip
+               else
+                 "# Required environment variables for mxup.\n" \
+                 '# Fill in the values below, then re-run `mxup up`.'
+               end
+      additions.each do |rv|
+        block = []
+        block << "# #{rv.description}" if rv.description && !rv.description.empty?
+        block << "#{rv.name}="
+        parts << block.join("\n")
+      end
+
+      File.write(@path, parts.join("\n\n") + "\n")
+      @path
+    end
+
+    # Parse the file (or a given string) into a { KEY => value } hash. Blank
+    # lines and `#` comments are skipped; surrounding quotes are stripped.
+    def parse(contents = nil)
+      contents ||= File.exist?(@path) ? File.read(@path) : ''
+      contents.each_line.each_with_object({}) do |line, acc|
+        line = line.strip
+        next if line.empty? || line.start_with?('#')
+
+        key, sep, value = line.partition('=')
+        next if sep.empty? || key.strip.empty?
+
+        acc[key.strip] = unquote(value.strip)
+      end
+    end
+
+    private
+
+    def present?(value)
+      !value.nil? && !value.strip.empty?
+    end
+
+    def unquote(value)
+      if value.length >= 2 &&
+         ((value.start_with?('"') && value.end_with?('"')) ||
+          (value.start_with?("'") && value.end_with?("'")))
+        value[1..-2]
+      else
+        value
+      end
+    end
+  end
+end

data/lib/mxup/launcher.rb

@@ -52,31 +52,33 @@ module Mxup
     # Build (but don't write) the shell text for a window's launcher script.
     # Exposed for inspection/tests; production callers use #write_all.
     def build_script(window)
-      sections = []
-      sections << "# mxup launcher for #{window.name}"
-      sections << "cd #{Shellwords.escape(window.root)}"
-
-      if @config.setup && !@config.setup.empty?
-        sections << ''
-        @config.setup.split("\n").each { |l| sections << l }
-      end
-
-      if window.wait_for
-        sections << ''
-        sections.concat(build_wait_block(window.wait_for))
-      end
-
-      if window.env.any?
-        sections << ''
-        window.env.each { |k, v| sections << "export #{k}=#{Shellwords.escape(v)}" }
-      end
-
-      if window.command && !window.command.empty?
-        sections << ''
-        sections << window.command
-      end
+      compose(
+        ["# mxup launcher for #{window.name}"],
+        cd_lines(window),
+        required_env_lines,
+        setup_lines,
+        wait_lines(window),
+        live_env_lines(window),
+        env_lines(window),
+        command_lines(window.command)
+      )
+    end
 
-      sections.join("\n") + "\n"
+    # Build the shell text for one of a window's named `commands`. It mirrors
+    # the launcher's environment (root, required_env, setup, live_env, env) but
+    # runs the given one-off command instead of the window's main command, and
+    # omits the wait_for readiness gate (that guards the long-running command,
+    # not arbitrary tasks). Meant to be run as a subprocess, not sent to tmux.
+    def build_command_script(window, command)
+      compose(
+        ["# mxup command for #{window.name}"],
+        cd_lines(window),
+        required_env_lines,
+        setup_lines,
+        live_env_lines(window),
+        env_lines(window),
+        command_lines(command)
+      )
     end
 
     # Shell snippet (array of lines) implementing a wait_for check.
@@ -111,10 +113,68 @@ module Mxup
 
     private
 
+    # Join the section line-arrays into one script. Each helper returns [] when
+    # its section is absent, or a leading '' followed by its lines when present,
+    # so blank-line separators fall out naturally.
+    def compose(*sections)
+      sections.flatten(1).join("\n") + "\n"
+    end
+
+    def cd_lines(window)
+      ["cd #{Shellwords.escape(window.root)}"]
+    end
+
+    # Required env vars: source the (already-validated) env file so every
+    # window inherits the values. Done before setup/command so they can
+    # reference them. `set -a` auto-exports each assignment to children.
+    def required_env_lines
+      return [] unless @config.required_env.any?
+      path = Shellwords.escape(@config.env_file_path)
+      ['', "set -a; [ -f #{path} ] && . #{path}; set +a"]
+    end
+
+    def setup_lines
+      return [] unless @config.setup && !@config.setup.empty?
+      ['', *@config.setup.split("\n")]
+    end
+
+    def wait_lines(window)
+      return [] unless window.wait_for
+      ['', *build_wait_block(window.wait_for)]
+    end
+
+    def live_env_lines(window)
+      return [] unless window.live_env.any?
+      dir = Shellwords.escape(@config.live_env_dir)
+      exports = window.live_env.map do |var|
+        command = @config.live_env.fetch(var)
+        # This launcher is sourced by the pane's interactive shell (often
+        # zsh), whose quoting/word-splitting rules differ from sh's. Rather
+        # than embed the raw command — and have that shell mangle its quotes —
+        # ship it as an opaque base64 blob and decode+run it under a fixed
+        # `sh`. Only [A-Za-z0-9+/=] ever travels through the outer shell.
+        encoded = [command].pack('m0')
+        %(export #{var}="$({ cd #{dir} && echo #{encoded} | base64 -d | sh; } 2>/dev/null)")
+      end
+      ['', *exports]
+    end
+
+    def env_lines(window)
+      return [] unless window.env.any?
+      ['', *window.env.map { |k, v| "export #{k}=#{Shellwords.escape(v)}" }]
+    end
+
+    def command_lines(command)
+      return [] unless command && !command.empty?
+      ['', command]
+    end
+
     def content?(window)
-      (@config.setup && !@config.setup.empty?) ||
+      @config.required_env.any? ||
+        (@config.setup && !@config.setup.empty?) ||
         window.wait_for ||
         window.env.any? ||
+        window.live_env.any? ||
         (window.command && !window.command.empty?)
     end
 

data/lib/mxup/reconciler.rb

@@ -220,6 +220,13 @@ module Mxup
       group.window_names.drop(1).each_with_index do |wn, i|
         win = @config.window_by_name(wn)
         Tmux.split_window(@session, group.name, win.root, target_pane: i)
+        # Re-tile after every split. Splitting always halves the most recent
+        # pane, so without rebalancing the panes pile into an ever-shrinking
+        # region; past ~4 panes tmux refuses the split as the target is too
+        # small. The skipped pane then surfaces downstream as the confusing
+        # "can't find pane N" error. Re-tiling keeps every pane large enough
+        # to split again.
+        Tmux.select_layout(@session, group.name, 'tiled')
       end
 
       Tmux.select_layout(@session, group.name, group.split)

data/lib/mxup/runner.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'fileutils'
+require 'rbconfig'
+
 module Mxup
   # Public programmatic API. Composes the focused helpers — nothing here
   # should contain real business logic, only wiring and delegation.
@@ -29,7 +32,10 @@ module Mxup
 
     def up
       handle_profile_switch
+      require_env!
       reconciler.up
+      ensure_watcher unless @dry_run
+      $stdout.puts "Attach with: tmux attach -t #{@session}" unless @dry_run
     end
 
     def status(lines:)
@@ -47,6 +53,7 @@ module Mxup
         return
       end
 
+      stop_watcher
       graceful_stop.call
       Tmux.kill_session(@session)
       launcher.cleanup
@@ -97,8 +104,73 @@ module Mxup
                       force: force, quiet: quiet)
     end
 
+    # Run a window's named command (`mxup <config> <window>:<name>`) in a copy
+    # of that window's environment, streaming its output to the calling shell
+    # and exiting with its return code. Does not touch the live tmux pane, so
+    # it works whether or not the session is up.
+    def run_command(window_name, command_name)
+      win = @config.window_by_name(window_name) ||
+            abort("Window '#{window_name}' not found in config.")
+
+      command = win.commands[command_name] || abort(unknown_command_message(win, command_name))
+
+      script = launcher.build_command_script(win, command)
+
+      if @dry_run
+        $stdout.puts "[dry-run] Would run #{window_name}:#{command_name} in #{win.root}:"
+        $stdout.puts command
+        return
+      end
+
+      exit(run_script(script))
+    end
+
     private
 
+    def unknown_command_message(win, command_name)
+      available = win.commands.keys
+      list = available.empty? ? '(none defined)' : available.join(', ')
+      "Window '#{win.name}' has no command '#{command_name}'. Available: #{list}"
+    end
+
+    # Execute a generated script through the user's shell, inheriting stdio so
+    # output streams live to the caller. Returns the child's exit status.
+    def run_script(script)
+      shell = ENV['SHELL'] || '/bin/sh'
+      system(shell, '-c', script)
+      $?.exitstatus || 1
+    end
+
+    # --- required env gate -------------------------------------------------
+
+    # Before `up` does anything, every var declared in `required_env` must have
+    # a non-empty value in the config's `.env` file. If some are missing, write
+    # (or extend) a template so the user has something to fill in, then abort
+    # with instructions. Under --dry-run we only report — no file is written.
+    def require_env!
+      return if @config.required_env.empty?
+
+      env_file = EnvFile.new(@config)
+      missing  = env_file.missing
+      return if missing.empty?
+
+      if @dry_run
+        names = missing.map(&:name).join(', ')
+        $stdout.puts "[dry-run] Required env not set: #{names} (#{@config.env_file_path})"
+        return
+      end
+
+      env_file.scaffold!
+      details = missing.map do |rv|
+        rv.description ? "  #{rv.name} — #{rv.description}" : "  #{rv.name}"
+      end
+      abort <<~MSG.chomp
+        Missing required environment variable(s):
+        #{details.join("\n")}
+        Fill in the values in #{@config.env_file_path}, then re-run `mxup up`.
+      MSG
+    end
+
     # --- profile switching -------------------------------------------------
 
     # Before `up` runs, make sure we aren't stepping on a different profile
@@ -141,12 +213,8 @@ module Mxup
       end
       # Two C-c's handle both "foreground is command" and "foreground is a
       # sub-prompt waiting on input"; the sleep gives the shell time to redraw.
-      delay = Runner.interrupt_delay
-      Tmux.send_interrupt(@session, target_ref)
-      sleep delay
-      Tmux.send_interrupt(@session, target_ref)
-      sleep delay
-      Tmux.send_keys(@session, target_ref, launcher.command_for(win))
+      Restarter.restart(@session, target_ref, launcher.command_for(win),
+                        interrupt_delay: Runner.interrupt_delay)
       $stdout.puts "  #{win.name}: restarted"
     end
 
@@ -186,6 +254,65 @@ module Mxup
       end
     end
 
+    # --- watcher supervisor -----------------------------------------------
+
+    # Start a background `mxup watch` if the config declares any live_env
+    # vars. Always tear down any prior watcher first — its in-memory config
+    # may be stale (e.g. the user edited the YAML before re-running `up`).
+    def ensure_watcher
+      return if @config.live_env.empty?
+
+      stop_watcher
+      log_path = Watcher.log_path(@session)
+      pid_path = Watcher.pid_path(@session)
+      FileUtils.mkdir_p(File.dirname(log_path))
+
+      pid = Process.spawn(*watcher_command,
+                          [:out, :err] => [log_path, 'a'],
+                          pgroup: true)
+      Process.detach(pid)
+      File.write(pid_path, "#{pid}\n")
+      $stdout.puts "Watcher started (pid #{pid}, watching #{@config.live_env.size} command(s))."
+    end
+
+    def stop_watcher
+      pid_path = Watcher.pid_path(@session)
+      return unless File.exist?(pid_path)
+
+      pid = File.read(pid_path).strip.to_i
+      if pid > 0 && watcher_alive?(pid)
+        begin
+          Process.kill(:TERM, pid)
+        rescue Errno::ESRCH, Errno::EPERM
+          # already gone
+        end
+      end
+      File.delete(pid_path) if File.exist?(pid_path)
+      state = Watcher.state_path(@session)
+      File.delete(state) if File.exist?(state)
+    end
+
+    def watcher_alive?(pid)
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH, Errno::EPERM
+      false
+    end
+
+    def watcher_command
+      cmd = mxup_executable + ['watch', @session]
+      cmd.concat(['-p', @config.profile]) if @config.profile
+      cmd
+    end
+
+    def mxup_executable
+      # Re-invoke this same Ruby + same gem entry point so a child watcher
+      # runs the exact code that started it (important when the user runs
+      # mxup from a checkout rather than the installed gem).
+      bin = File.expand_path('../../bin/mxup', __dir__)
+      File.exist?(bin) ? [RbConfig.ruby, bin] : ['mxup']
+    end
+
     # --- lazily-built collaborators ---------------------------------------
 
     def resolver