yatfa 1.0.88 → 1.0.90

package/lib/yatfa_agent/agent.rb

@@ -1,150 +1,18 @@
 # frozen_string_literal: true
 
+require_relative "container"
+require_relative "command_builder"
+require_relative "interaction"
+
 module YatfaAgent
+  # Agent orchestrator.
+  # Coordinates Container, CommandBuilder, and Interaction modules to run and attach agents.
+  # Sub-modules are mixed in via extend so their methods are available as Agent.xxx
+  # and test stubs (define_singleton_method) intercept internal calls correctly.
   module Agent
-    # Check if container is currently running
-    def self.container_running?(container_name)
-      result = IO.popen(["docker", "ps", "--filter", "name=^#{container_name}$", "--format", "{{.Names}}"], err: File::NULL, &:read).strip
-      !result.empty?
-    end
-
-    # Check if container exists (running or stopped)
-    def self.container_exists?(container_name)
-      result = IO.popen(["docker", "ps", "-a", "--filter", "name=^#{container_name}$", "--format", "{{.Names}}"], err: File::NULL, &:read).strip
-      !result.empty?
-    end
-
-    # Get container creation time
-    def self.container_creation_time(container_name)
-      result = IO.popen(["docker", "inspect", "--format", "{{.Created}}", container_name], err: File::NULL, &:read).strip
-      return nil if result.empty?
-      Time.parse(result)
-    rescue ArgumentError
-      nil
-    end
-
-    def self.format_time(t)
-      t.strftime("%H:%M")
-    end
-
-    # Prompt user for input with a default value
-    def self.prompt(message, default: nil, options: nil)
-      loop do
-        print message
-        input = $stdin.gets&.strip&.downcase || ""
-
-        # Handle default on empty input
-        if input.empty? && default
-          return default
-        end
-
-        # If options specified, validate input
-        if options
-          valid = options.any? { |opt| opt.downcase == input || opt.downcase.start_with?(input) }
-          if valid
-            # Return the full option that matches
-            return options.find { |opt| opt.downcase.start_with?(input) }
-          end
-          puts "   Invalid option. Please choose: #{options.join('/')}"
-        else
-          return input
-        end
-      end
-    end
-
-    # Check if running in non-interactive mode
-    def self.non_interactive?
-      !$stdin.tty? || ENV['YATFA_NO_PROMPT'] == '1' || ARGV.include?('--no-prompt') || ARGV.include?('-d')
-    end
-
-    # Handle running container: prompt user for action
-    def self.handle_running_container(agent_type, container_name, config, agent_configs)
-      puts "⚠️  #{agent_type} agent is already running (#{container_name})"
-
-      # Check if container was created before last deploy
-      deploy_manifest = File.join(File.dirname(__FILE__), '..', '..', 'deploy', '.deploy-manifest.json')
-      version_file = File.join(File.dirname(__FILE__), '..', '..', 'VERSION')
-      stale = false
-
-      if File.exist?(version_file)
-        current_version = File.read(version_file).strip
-        container_version = IO.popen(["docker", "exec", container_name, "printenv", "YATFA_VERSION_NUM"], err: File::NULL, &:read).strip
-        if !container_version.empty? && container_version != current_version
-          puts "   🆕 New version deployed (container: #{container_version}, current: #{current_version})"
-          stale = true
-        end
-      elsif File.exist?(deploy_manifest)
-        deploy_time = File.mtime(deploy_manifest)
-        container_created = container_creation_time(container_name)
-        if container_created && container_created < deploy_time
-          puts "   🆕 New deploy detected (container from #{format_time(container_created)}, deploy at #{format_time(deploy_time)})"
-          stale = true
-        end
-      end
-
-      puts ""
-
-      if non_interactive?
-        puts "   Running in non-interactive mode. Run 'npx yatfa #{agent_type}' to attach, or stop the container first."
-        puts "   docker stop #{container_name}"
-        exit 0
-      end
-
-      default_choice = stale ? "R" : "A"
-      choice = prompt("   [A]ttach / [R]estart / [C]ancel? [#{default_choice == 'R' ? 'a/R/c' : 'A/r/c'}]: ", default: default_choice, options: %w[A R C])
-
-      case choice
-      when "A"
-        puts ""
-        attach(agent_type, config, agent_configs)
-      when "R"
-        puts ""
-        puts "🔄 Stopping existing container..."
-        system("docker", "stop", container_name, err: File::NULL, out: File::NULL)
-        system("docker", "rm", "-f", container_name, err: File::NULL, out: File::NULL)
-        return true # Continue with start
-      when "C"
-        puts "   Cancelled."
-        exit 0
-      end
-    end
-
-    # Banner file is no longer generated on the host.
-    # System prompt is generated inside the container by setup-agent.rb
-    # using AGENT_TYPE and REPOSITORIES_CONTEXT env vars.
-
-    # Handle stopped container: prompt user for action
-    def self.handle_stopped_container(agent_type, container_name, config, agent_configs)
-      puts "⚠️  #{agent_type} agent container exists but is stopped (#{container_name})"
-      puts ""
-
-      if non_interactive?
-        puts "   Non-interactive mode: starting existing container."
-        system("docker", "start", container_name, out: File::NULL)
-        puts "✅ Agent started in background"
-        prompt_to_attach(agent_type, container_name, config, agent_configs)
-        exit 0
-      end
-
-      choice = prompt("   [S]tart existing / [R]ecreate / [C]ancel? [S/r/c]: ", default: "S", options: %w[S R C])
-
-      case choice
-      when "S"
-        puts ""
-        puts "🔄 Starting existing container..."
-        system("docker", "start", container_name, out: File::NULL)
-        puts "✅ Agent started in background"
-        prompt_to_attach(agent_type, container_name, config, agent_configs)
-        exit 0
-      when "R"
-        puts ""
-        puts "🔄 Removing stopped container..."
-        system("docker", "rm", "-f", container_name, err: File::NULL, out: File::NULL)
-      when "C"
-        puts "   Cancelled."
-        exit 0
-      end
-    end
+    extend Container
+    extend CommandBuilder
+    extend Interaction
 
     def self.run(agent_type, config, agent_configs)
       unless agent_configs.keys.include?(agent_type)
@@ -190,37 +58,6 @@ module YatfaAgent
       end
     end
 
-    # Prompt user to attach after starting a new agent
-    def self.prompt_to_attach(agent_type, container_name, config, agent_configs)
-      if non_interactive?
-        # Non-interactive: just print helpful info
-        puts "   Logs:   docker logs -f #{container_name}"
-        puts "   Stop:   docker stop #{container_name}"
-        puts "   Attach: docker exec -it #{container_name} tmux attach -t agent"
-        return
-      end
-
-      choice = prompt("   Agent started. Attach to session? [Y/n]: ", default: "Y", options: %w[Y N])
-
-      if choice == "Y"
-        puts ""
-        # Wait briefly for container to initialize
-        print "   Waiting for agent to initialize"
-        5.times do
-          print "."
-          sleep 1
-        end
-        puts ""
-        attach(agent_type, config, agent_configs)
-      else
-        puts ""
-        puts "   Agent is running in background."
-        puts "   Logs:   docker logs -f #{container_name}"
-        puts "   Stop:   docker stop #{container_name}"
-        puts "   Attach: docker exec -it #{container_name} tmux attach -t agent"
-      end
-    end
-
     def self.attach(agent_type, config, agent_configs)
       unless agent_configs.keys.include?(agent_type)
         puts "❌ Unknown agent type: #{agent_type}"
@@ -240,7 +77,7 @@ module YatfaAgent
       end
 
       puts "📎 Attaching to #{agent_type} agent..."
-      
+
       user = detect_agent_user(container_name)
       puts "   User: #{user}"
 
@@ -282,204 +119,5 @@ module YatfaAgent
       # Must run as agent user since tmux server runs under that user
       exec("docker", "exec", "-it", "-u", user, container_name, "tmux", "attach", "-t", "agent")
     end
-
-    private
-
-    def self.build_docker_command(container_name, agent_type, config, agent_config, agent_def, remote_version: nil)
-      docker_cmd = [
-        "docker", "run", "-d",
-        "--name", container_name,
-        "--network", "host",
-        "--restart", "unless-stopped",
-        "--tmpfs", "/rails/tmp",
-        "--tmpfs", "/rails/log"
-      ]
-
-      # Inject current version for staleness detection
-      version_file = File.join(File.dirname(__FILE__), '..', '..', 'VERSION')
-      if File.exist?(version_file)
-        version = File.read(version_file).strip
-        docker_cmd += ["-e", "YATFA_VERSION_NUM=#{version}"] unless version.empty?
-      end
-
-      # Add yatfa.version label for updater daemon to detect stale containers
-      # Uses version number from remote version.json (already fetched by build_image)
-      if remote_version
-        docker_cmd += ["--label", "yatfa.version=#{remote_version}"]
-      end
-
-      # Store project root as a label so the updater daemon can find
-      # Dockerfile.sandbox and yatfa.env.rb without reverse-engineering from mounts.
-      docker_cmd += ["--label", "yatfa.project-root=#{Dir.pwd}"]
-
-      # Inject custom environment variables from config
-      # Merge global env with agent-specific env (agent-specific takes precedence)
-      merged_env = {}
-      merged_env.merge!(config["env"]) if config["env"]
-      merged_env.merge!(agent_config["env"]) if agent_config["env"]
-
-      if merged_env.any?
-        merged_env.each do |k, v|
-          docker_cmd += ["-e", "#{k}=#{v}"]
-        end
-        global_count = config["env"]&.size || 0
-        agent_count = agent_config["env"]&.size || 0
-        if agent_count > 0
-          puts "🌿 Injected #{global_count} global + #{agent_count} agent-specific env vars"
-        else
-          puts "🌿 Injected #{global_count} custom env vars from config"
-        end
-      end
-
-      if agent_type == "claw"
-        # Claw-specific Docker command setup
-        docker_cmd += [
-          "-e", "AGENT_TYPE=#{agent_type}",
-          "-e", "YATFA_VERSION=main"
-        ]
-
-        # Add persistence volume for OpenClaw config and data (scoped per container)
-        docker_cmd += ["-v", "#{container_name}-openclaw-data:/home/yatfa/.openclaw"]
-
-        # Auto-inject telegram_bot_token as env var so users don't need to duplicate in env block
-        if agent_config["telegram_bot_token"]
-          docker_cmd += ["-e", "OPENCLAW_TELEGRAM_BOT_TOKEN=#{agent_config['telegram_bot_token']}"]
-        end
-
-        # Pass YATFA_URL if configured (optional for claw)
-        if config["yatfa_url"]
-          docker_cmd += ["-e", "YATFA_URL=#{config['yatfa_url']}"]
-          docker_cmd += ["-e", "YATFA_API_URL=#{config['yatfa_url']}/api/v1"]
-        end
-
-        # Pass MCP API key if configured (for future MCP integration)
-        if agent_config["mcp_api_key"]
-          docker_cmd += ["-e", "YATFA_API_KEY=#{agent_config['mcp_api_key']}"]
-        end
-
-        add_development_mounts!(docker_cmd)
-      else
-        # Standard agent setup (worker, planner, reviewer, researcher)
-        docker_cmd += [
-          "-e", "YATFA_VERSION=main",
-          "-e", "SKILLS=#{agent_def[:skills]&.join(',')}",
-          "-e", "AGENT_TYPE=#{agent_type}",
-          "-e", "YATFA_URL=#{YatfaAgent::Config.yatfa_url(config)}",
-          "-e", "YATFA_API_KEY=#{agent_config['mcp_api_key']}"
-        ]
-
-        add_github_auth!(docker_cmd, config)
-        add_git_config!(docker_cmd, config)
-        add_repository_mounts!(docker_cmd, config)
-        add_development_mounts!(docker_cmd)
-      end
-
-      local_setup_dir = File.join(File.dirname(__FILE__), "..", "..", "setup")
-
-      if File.directory?(local_setup_dir)
-        docker_cmd += [Config.image_name(config), "ruby", "/tmp/setup/setup-agent.rb"]
-      else
-        docker_cmd += [Config.image_name(config)]
-      end
-
-      docker_cmd
-    end
-
-    def self.add_github_auth!(docker_cmd, config)
-      github = config["github"] || {}
-
-      # New method: GitHub authentication is handled by the backend
-      # Agents get tokens via YATFA_API_KEY using the /github/token endpoint
-      # No GitHub credentials need to be passed into the container
-
-      # Deprecation warning for old GitHub App config
-      if github["method"] == "app" || github["app_client_id"] || github["app_installation_id"]
-        puts "⚠️  Warning: GitHub App configuration in yatfa.env.rb is deprecated"
-        puts "   GitHub credentials are now managed centrally in the Rails backend"
-        puts "   You can remove the 'github' section from yatfa.env.rb"
-        puts "   The backend will use its own GitHub App credentials to generate tokens"
-      end
-
-      # Optional: Support GH_TOKEN fallback for development/testing
-      if github["token"]
-        docker_cmd.concat(["-e", "GH_TOKEN=#{github['token']}"])
-        puts "🔑 Using GitHub token authentication (fallback mode)"
-      else
-        puts "✅ GitHub authentication will be handled by backend (YATFA_API_KEY)"
-      end
-    end
-
-    def self.add_git_config!(docker_cmd, config)
-      return unless (git_config = config["git"])
-      
-      docker_cmd.concat(["-e", "GIT_USER_NAME=#{git_config['user_name']}"]) if git_config["user_name"]
-      docker_cmd.concat(["-e", "GIT_USER_EMAIL=#{git_config['user_email']}"]) if git_config["user_email"]
-    end
-
-    def self.add_repository_mounts!(docker_cmd, config)
-      return unless config["repositories"].is_a?(Array) && config["repositories"].any?
-
-      puts "📚 Configuring #{config['repositories'].count} repositories..."
-
-      # Build REPOSITORIES_CONTEXT for sessionstart hook (format: "name:path,name:path")
-      sorted_repos = config["repositories"].sort_by { |r| r["position"] || 0 }
-      repos_context = sorted_repos.map do |repo|
-        repo_name = repo["name"]
-        sandbox_path = repo["path_in_sandbox"] || "/workspace/#{repo_name}"
-        "#{repo_name}:#{sandbox_path}"
-      end.join(",")
-
-      docker_cmd.concat(["-e", "REPOSITORIES_CONTEXT=#{repos_context}"])
-
-      # Pass repository config via environment variables for container to clone
-      repo_config_json = sorted_repos.to_json
-      docker_cmd.concat(["-e", "REPOSITORIES_CONFIG=#{repo_config_json}"])
-
-      sorted_repos.each do |repo|
-        repo_name = repo["name"]
-        sandbox_path = repo["path_in_sandbox"] || "/workspace/#{repo_name}"
-        puts "   - #{repo_name}: #{sandbox_path} (will be cloned in container)"
-      end
-    end
-
-    def self.add_development_mounts!(docker_cmd)
-      # Check for local setup/ directory (for development)
-      setup_dir = File.join(File.dirname(__FILE__), "..", "..", "setup")
-
-      if File.directory?(setup_dir)
-        puts "🔧 Using local setup/ for development"
-        docker_cmd.concat(["-v", "#{File.expand_path(setup_dir)}:/tmp/setup:ro"])
-      end
-    end
-
-    def self.detect_agent_user(container_name)
-      # Determine the user to attach as
-      # Robust method: find the user running the agent process (tmux or bridge)
-      user = `docker exec #{container_name} ps aux | grep "[a]gent-bridge-tmux" | awk '{print $1}' | head -n 1`.strip
-      
-      if user.empty?
-        user = `docker exec #{container_name} ps aux | grep "[t]mux new-session" | awk '{print $1}' | head -n 1`.strip
-      end
-
-      if user.empty?
-        # Fallback to previous heuristic
-        detected_user = `docker exec #{container_name} whoami 2>/dev/null`.strip
-        if detected_user == "root" || detected_user.empty?
-          uid = Process.uid
-          mapped_user = `docker exec #{container_name} getent passwd #{uid} | cut -d: -f1`.strip
-          user = mapped_user unless mapped_user.empty?
-        else
-          user = detected_user
-        end
-      end
-      
-      if user.empty?
-        # Final Fallback
-        user = "rails"
-        puts "⚠️  Could not detect agent user, defaulting to '#{user}'"
-      end
-      
-      user
-    end
   end
 end

package/lib/yatfa_agent/command_builder.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "json"
+
+module YatfaAgent
+  # Docker command assembly.
+  # Mixed into Agent via extend — methods become available as Agent.xxx.
+  # Responsible for building the full `docker run` command with all flags, env vars, and mounts.
+  module CommandBuilder
+    def build_docker_command(container_name, agent_type, config, agent_config, agent_def, remote_version: nil)
+      docker_cmd = [
+        "docker", "run", "-d",
+        "--name", container_name,
+        "--network", "host",
+        "--restart", "unless-stopped",
+        "--tmpfs", "/rails/tmp",
+        "--tmpfs", "/rails/log"
+      ]
+
+      # Inject current version for staleness detection
+      version_file = File.join(File.dirname(__FILE__), '..', '..', 'VERSION')
+      if File.exist?(version_file)
+        version = File.read(version_file).strip
+        docker_cmd += ["-e", "YATFA_VERSION_NUM=#{version}"] unless version.empty?
+      end
+
+      # Add yatfa.version label for updater daemon to detect stale containers
+      # Uses version number from remote version.json (already fetched by build_image)
+      if remote_version
+        docker_cmd += ["--label", "yatfa.version=#{remote_version}"]
+      end
+
+      # Store project root as a label so the updater daemon can find
+      # Dockerfile.sandbox and yatfa.env.rb without reverse-engineering from mounts.
+      docker_cmd += ["--label", "yatfa.project-root=#{Dir.pwd}"]
+
+      # Inject custom environment variables from config
+      # Merge global env with agent-specific env (agent-specific takes precedence)
+      merged_env = {}
+      merged_env.merge!(config["env"]) if config["env"]
+      merged_env.merge!(agent_config["env"]) if agent_config["env"]
+
+      if merged_env.any?
+        merged_env.each do |k, v|
+          docker_cmd += ["-e", "#{k}=#{v}"]
+        end
+        global_count = config["env"]&.size || 0
+        agent_count = agent_config["env"]&.size || 0
+        if agent_count > 0
+          puts "🌿 Injected #{global_count} global + #{agent_count} agent-specific env vars"
+        else
+          puts "🌿 Injected #{global_count} custom env vars from config"
+        end
+      end
+
+      if agent_type == "claw"
+        # Claw-specific Docker command setup
+        docker_cmd += [
+          "-e", "AGENT_TYPE=#{agent_type}",
+          "-e", "YATFA_VERSION=main"
+        ]
+
+        # Add persistence volume for OpenClaw config and data (scoped per container)
+        docker_cmd += ["-v", "#{container_name}-openclaw-data:/home/yatfa/.openclaw"]
+
+        # Auto-inject telegram_bot_token as env var so users don't need to duplicate in env block
+        if agent_config["telegram_bot_token"]
+          docker_cmd += ["-e", "OPENCLAW_TELEGRAM_BOT_TOKEN=#{agent_config['telegram_bot_token']}"]
+        end
+
+        # Pass YATFA_URL if configured (optional for claw)
+        if config["yatfa_url"]
+          docker_cmd += ["-e", "YATFA_URL=#{config['yatfa_url']}"]
+          docker_cmd += ["-e", "YATFA_API_URL=#{config['yatfa_url']}/api/v1"]
+        end
+
+        # Pass MCP API key if configured (for future MCP integration)
+        if agent_config["mcp_api_key"]
+          docker_cmd += ["-e", "YATFA_API_KEY=#{agent_config['mcp_api_key']}"]
+        end
+
+      else
+        # Standard agent setup (worker, planner, reviewer, researcher)
+        docker_cmd += [
+          "-e", "YATFA_VERSION=main",
+          "-e", "SKILLS=#{agent_def[:skills]&.join(',')}",
+          "-e", "AGENT_TYPE=#{agent_type}",
+          "-e", "YATFA_URL=#{YatfaAgent::Config.yatfa_url(config)}",
+          "-e", "YATFA_API_KEY=#{agent_config['mcp_api_key']}"
+        ]
+
+        add_github_auth!(docker_cmd, config)
+        add_git_config!(docker_cmd, config)
+        add_repository_mounts!(docker_cmd, config)
+      end
+
+      docker_cmd += [Config.image_name(config)]
+
+      docker_cmd
+    end
+
+    def add_github_auth!(docker_cmd, config)
+      github = config["github"] || {}
+
+      # New method: GitHub authentication is handled by the backend
+      # Agents get tokens via YATFA_API_KEY using the /github/token endpoint
+      # No GitHub credentials need to be passed into the container
+
+      # Deprecation warning for old GitHub App config
+      if github["method"] == "app" || github["app_client_id"] || github["app_installation_id"]
+        puts "⚠️  Warning: GitHub App configuration in yatfa.env.rb is deprecated"
+        puts "   GitHub credentials are now managed centrally in the Rails backend"
+        puts "   You can remove the 'github' section from yatfa.env.rb"
+        puts "   The backend will use its own GitHub App credentials to generate tokens"
+      end
+
+      # Optional: Support GH_TOKEN fallback for development/testing
+      if github["token"]
+        docker_cmd.concat(["-e", "GH_TOKEN=#{github['token']}"])
+        puts "🔑 Using GitHub token authentication (fallback mode)"
+      else
+        puts "✅ GitHub authentication will be handled by backend (YATFA_API_KEY)"
+      end
+    end
+
+    def add_git_config!(docker_cmd, config)
+      return unless (git_config = config["git"])
+
+      docker_cmd.concat(["-e", "GIT_USER_NAME=#{git_config['user_name']}"]) if git_config["user_name"]
+      docker_cmd.concat(["-e", "GIT_USER_EMAIL=#{git_config['user_email']}"]) if git_config["user_email"]
+    end
+
+    def add_repository_mounts!(docker_cmd, config)
+      return unless config["repositories"].is_a?(Array) && config["repositories"].any?
+
+      puts "📚 Configuring #{config['repositories'].count} repositories..."
+
+      # Build REPOSITORIES_CONTEXT for sessionstart hook (format: "name:path,name:path")
+      sorted_repos = config["repositories"].sort_by { |r| r["position"] || 0 }
+      repos_context = sorted_repos.map do |repo|
+        repo_name = repo["name"]
+        sandbox_path = repo["path_in_sandbox"] || "/workspace/#{repo_name}"
+        "#{repo_name}:#{sandbox_path}"
+      end.join(",")
+
+      docker_cmd.concat(["-e", "REPOSITORIES_CONTEXT=#{repos_context}"])
+
+      # Pass repository config via environment variables for container to clone
+      repo_config_json = sorted_repos.to_json
+      docker_cmd.concat(["-e", "REPOSITORIES_CONFIG=#{repo_config_json}"])
+
+      sorted_repos.each do |repo|
+        repo_name = repo["name"]
+        sandbox_path = repo["path_in_sandbox"] || "/workspace/#{repo_name}"
+        puts "   - #{repo_name}: #{sandbox_path} (will be cloned in container)"
+      end
+    end
+  end
+end

package/lib/yatfa_agent/container.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "time"
+
+module YatfaAgent
+  # Container state queries and user detection.
+  # Mixed into Agent via extend — methods become available as Agent.xxx.
+  module Container
+    # Check if container is currently running
+    def container_running?(container_name)
+      result = IO.popen(["docker", "ps", "--filter", "name=^#{container_name}$", "--format", "{{.Names}}"], err: File::NULL, &:read).strip
+      !result.empty?
+    end
+
+    # Check if container exists (running or stopped)
+    def container_exists?(container_name)
+      result = IO.popen(["docker", "ps", "-a", "--filter", "name=^#{container_name}$", "--format", "{{.Names}}"], err: File::NULL, &:read).strip
+      !result.empty?
+    end
+
+    # Get container creation time
+    def container_creation_time(container_name)
+      result = IO.popen(["docker", "inspect", "--format", "{{.Created}}", container_name], err: File::NULL, &:read).strip
+      return nil if result.empty?
+      Time.parse(result)
+    rescue ArgumentError
+      nil
+    end
+
+    def format_time(t)
+      t.strftime("%H:%M")
+    end
+
+    # Detect the user running the agent process inside the container
+    def detect_agent_user(container_name)
+      # Determine the user to attach as
+      # Robust method: find the user running the agent process (tmux or bridge)
+      user = `docker exec #{container_name} ps aux | grep "[a]gent-bridge-tmux" | awk '{print $1}' | head -n 1`.strip
+
+      if user.empty?
+        user = `docker exec #{container_name} ps aux | grep "[t]mux new-session" | awk '{print $1}' | head -n 1`.strip
+      end
+
+      if user.empty?
+        # Fallback to previous heuristic
+        detected_user = `docker exec #{container_name} whoami 2>/dev/null`.strip
+        if detected_user == "root" || detected_user.empty?
+          uid = Process.uid
+          mapped_user = `docker exec #{container_name} getent passwd #{uid} | cut -d: -f1`.strip
+          user = mapped_user unless mapped_user.empty?
+        else
+          user = detected_user
+        end
+      end
+
+      if user.empty?
+        # Final Fallback
+        user = "rails"
+        puts "⚠️  Could not detect agent user, defaulting to '#{user}'"
+      end
+
+      user
+    end
+  end
+end