superkick 0.1.0

data/lib/superkick/control/server.rb

@@ -0,0 +1,1271 @@
+# frozen_string_literal: true
+
+require "socket"
+require "fileutils"
+require "base64"
+require "securerandom"
+require_relative "reply"
+
+module Superkick
+  module Control
+    # Unix socket server — the control plane's main endpoint.
+    # One thread per connection (connections are short-lived request/response).
+    #
+    # Commands are dispatched dynamically to cmd_<command> private methods.
+    class Server
+      def initialize(store:, injector:, supervisor:, notification_dispatcher:, buffer_client: nil, config: Superkick.config,
+        agent_spawner: nil, approval_store: nil, budget_checker: nil, team_log_store: nil,
+        team_artifact_store: nil, server: nil, attach_relay_store: nil)
+        @store = store
+        @injector = injector
+        @supervisor = supervisor
+        @config = config
+        @buffer_client = buffer_client || Buffer.client_from(store:, config:)
+        @agent_spawner = agent_spawner
+        @approval_store = approval_store
+        @budget_checker = budget_checker
+        @team_log_store = team_log_store
+        @team_artifact_store = team_artifact_store
+        @server = server
+        @notification_dispatcher = notification_dispatcher
+        @attach_relay_store = attach_relay_store
+        @accept_thread = nil
+      end
+
+      def start
+        unless @server
+          FileUtils.rm_f(@config.socket_path)
+          FileUtils.mkdir_p(File.dirname(@config.socket_path))
+          @server = UNIXServer.new(@config.socket_path)
+        end
+        @accept_thread = Thread.new { accept_loop }
+        self
+      end
+
+      def stop
+        begin
+          @server&.close
+        rescue IOError, Errno::EBADF
+          nil
+        end
+        begin
+          @accept_thread&.kill
+        rescue ThreadError
+          nil
+        end
+        FileUtils.rm_f(@config.socket_path)
+      end
+
+      private
+
+      def accept_loop
+        loop do
+          connection = @server.accept
+          Thread.new(connection) { handle(it) }
+        rescue IOError, Errno::EBADF
+          break
+        rescue => e
+          Superkick.logger.error("control_server") { "Control::Server accept error: #{e.message}\n#{e.backtrace.first(5).join("\n")}" }
+        end
+      end
+
+      def handle(raw_connection)
+        connection = Superkick::Connection.new(raw_connection)
+        request = connection.receive_message
+        unless request
+          connection.close
+          return
+        end
+
+        connection.reply(dispatch(request) || {})
+      rescue => e
+        Superkick.logger.error("control_server") { "Control::Server dispatch error: #{e.message}\n#{e.backtrace.first(5).join("\n")}" }
+        begin
+          connection&.error(e.message)
+        rescue IOError, Errno::EPIPE, Errno::ENOTCONN
+          nil
+        end
+      ensure
+        connection&.close
+      end
+
+      def dispatch(request)
+        method_name = "cmd_#{request[:command].tr("-", "_")}"
+        unless respond_to?(method_name, true)
+          raise "Unknown command: #{request[:command]}"
+        end
+        send(method_name, request)
+      end
+
+      def cmd_ping(_req)
+        {version: Superkick::VERSION}
+      end
+
+      def cmd_register(req)
+        agent_id = req[:agent_id]
+        yaml_monitors = @config.monitors || {}
+        @store.add(agent_id, monitors: yaml_monitors)
+
+        # Store the agent's working directory for monitor config resolution.
+        if req[:working_dir]
+          agent = @store.get(agent_id)
+          agent&.set_working_dir(req[:working_dir])
+        end
+
+        # Human team member joining via --team flag
+        if req[:team_id]
+          agent = @store.get(agent_id)
+          if agent
+            agent.set_team(team_id: req[:team_id], team_role: :member)
+            agent.set_role(req[:role]) if req[:role]
+
+            if req[:team_log] != false
+              agent.set_monitor_config(:team_log, {type: :team_log, team_id: req[:team_id]})
+              @supervisor.enqueue(:add_monitor, agent_id:, monitor_name: :team_log)
+            end
+
+            dispatch_notification(
+              event: {event_type: :agent_spawned, monitor_type: :system, monitor_name: :system,
+                      team_id: req[:team_id]},
+              agent_id:,
+              message: "#{agent_id} joined the team"
+            )
+          end
+        end
+
+        # Build environment request from all registered probes.
+        environment_request = collect_environment_actions
+        {agent_id:, environment_request:}
+      end
+
+      def cmd_register_environment(req)
+        agent_id = req[:agent_id]
+        environment = req[:environment] || {}
+
+        agent = @store.get(agent_id)
+        return {agent_id:} unless agent
+
+        agent.set_environment(environment)
+
+        # Run server-side probes with the environment snapshot.
+        probe_monitors = Monitor.detect_all(environment:)
+        yaml_monitors = agent.monitors || {}
+
+        # YAML is the base; probe-detected configs overlay per-name.
+        merged = yaml_monitors.merge(probe_monitors) { |_name, yaml_config, probe_config|
+          yaml_config.merge(probe_config)
+        }
+
+        # Replace monitors with the merged set.
+        merged.each { |name, config| agent.set_monitor_config(name, config) }
+
+        @supervisor.enqueue(:register, agent_id:)
+        {agent_id:}
+      end
+
+      def cmd_unregister(req)
+        agent_id = req[:agent_id]
+
+        # Dispatch lifecycle notification when a team member leaves
+        agent = @store.get(agent_id)
+        if agent&.team_id && agent&.team_role == :member
+          dispatch_notification(
+            event: {event_type: :agent_terminated, monitor_type: :system, monitor_name: :system,
+                    team_id: agent.team_id},
+            agent_id:,
+            message: "#{agent_id} left the team"
+          )
+        end
+
+        @supervisor.enqueue(:unregister, agent_id:)
+        @store.remove(agent_id)
+        @agent_spawner&.agent_ended(agent_id)
+        nil
+      end
+
+      def cmd_list_agents(req)
+        source = if req[:team_id]
+          @store.team(req[:team_id])
+        else
+          @store.to_a
+        end
+        source = source.select { it.spawn_info } if req[:spawned_only]
+
+        agents = source.map { serialize_agent(it) }
+        {agents:}
+      end
+
+      def cmd_list_teams(_req)
+        teams = {}
+        @store.each do |agent|
+          next unless agent.team_id
+          entry = teams[agent.team_id] ||= {team_id: agent.team_id, agent_count: 0}
+          entry[:agent_count] += 1
+          if agent.team_role == :lead
+            entry[:lead_agent_id] = agent.id
+          end
+        end
+        {teams: teams.values}
+      end
+
+      def cmd_register_buffer(req)
+        agent_id = req[:agent_id]
+        agent = @store.get(agent_id)
+        agent&.attach_path(:buffer_socket_path, @config.buffer_socket_path(agent_id))
+        agent&.attach_path(:output_log_path, req[:output_log_path]) if req[:output_log_path]
+        agent&.attach_path(:recording_path, req[:recording_path]) if req[:recording_path]
+        Superkick.logger.info("control_server") { "Buffer socket registered for #{agent_id}" }
+        nil
+      end
+
+      def cmd_unregister_buffer(req)
+        @store.get(req[:agent_id])&.detach_path(:buffer_socket_path)
+        nil
+      end
+
+      def cmd_register_attach(req)
+        agent_id = req[:agent_id]
+        @store.get(agent_id)&.attach_path(:attach_socket_path, @config.attach_socket_path(agent_id))
+        Superkick.logger.info("control_server") { "Attach socket registered for #{agent_id}" }
+        nil
+      end
+
+      def cmd_unregister_attach(req)
+        @store.get(req[:agent_id])&.detach_path(:attach_socket_path)
+        nil
+      end
+
+      def cmd_has_buffer(req)
+        {has_buffer: !@store.get(req[:agent_id])&.buffer_socket_path.nil?}
+      end
+
+      def cmd_get_output_log_path(req)
+        agent_id = req[:agent_id]
+        agent = @store.get(agent_id)
+        raise "Agent not found: #{agent_id}" unless agent
+        {path: agent.output_log_path}
+      end
+
+      def cmd_get_input_buffer(req)
+        proxy_buffer(req[:agent_id], "get")
+      end
+
+      def cmd_clear_input_buffer(req)
+        proxy_buffer(req[:agent_id], "clear")
+      end
+
+      def cmd_guards_active(req)
+        proxy_buffer(req[:agent_id], "guards_active")
+      end
+
+      def cmd_inject_input(req)
+        proxy_buffer(req[:agent_id], "inject", data: req[:data])
+      end
+
+      def cmd_injection_result(req)
+        agent_id = req[:agent_id]
+        id = req[:id]
+        status = req[:status]&.to_sym
+
+        case status
+        when :injected
+          agent = @store.get(agent_id)
+          agent&.set_last_notified
+
+          dispatch_notification(
+            event: {event_type: :injection_completed, monitor_type: :system, monitor_name: :injection_queue},
+            agent_id:,
+            message: "Injection #{id} delivered to #{agent_id}"
+          )
+        when :expired, :superseded, :dropped
+          Superkick.logger.debug("injection") { "Injection #{id} #{status} for #{agent_id}" }
+        end
+
+        nil
+      end
+
+      def cmd_attach_event(req)
+        agent_id = req[:agent_id]
+        event_type = req[:event_type]&.to_sym
+        reason = req[:reason]
+
+        valid_events = %i[attach_promoted attach_demoted attach_idle_timeout attach_force_takeover]
+        return unless valid_events.include?(event_type)
+
+        dispatch_notification(
+          event: {event_type:, monitor_type: :attach, monitor_name: :attach},
+          agent_id:,
+          message: reason || "Attach event #{event_type} for #{agent_id}"
+        )
+
+        nil
+      end
+
+      def cmd_add_monitor(req)
+        agent_id = req[:agent_id]
+        name = req[:monitor_name]
+        config = req[:config] || {}
+        monitor_type = config[:type] || name
+        raise_if_privileged!(name, monitor_type, action: "add")
+        @store.get(agent_id)&.set_monitor_config(name, config)
+        @supervisor.enqueue(:add_monitor, agent_id:, monitor_name: name)
+        nil
+      end
+
+      def cmd_remove_monitor(req)
+        agent_id = req[:agent_id]
+        name = req[:monitor_name]
+        agent = @store.get(agent_id)
+        existing_config = agent&.monitor_config(name) || {}
+        monitor_type = existing_config[:type] || name
+        raise_if_privileged!(name, monitor_type, action: "remove")
+        @supervisor.enqueue(:remove_monitor, agent_id:, monitor_name: name)
+        agent&.remove_monitor(name)
+        nil
+      end
+
+      def cmd_list_monitors(req)
+        agent_id = req[:agent_id]
+        agent = @store.get(agent_id)
+        raise "Agent not found: #{agent_id}" unless agent
+
+        monitors = agent.monitors.reject { |name, config| monitor_hidden?(name, config) }
+          .map { |name, config| {name:, type: config[:type] || name} }
+
+        {monitors:}
+      end
+
+      def cmd_restart_monitors(req)
+        @supervisor.enqueue(:restart_monitors, agent_id: req[:agent_id])
+        nil
+      end
+
+      # -- Notifier management --------------------------------------------------
+
+      def cmd_add_notifier(req)
+        agent_id = req[:agent_id]
+        name = req[:notifier_name]&.to_sym
+        config = req[:config] || {}
+        notifier_type = config[:type] || name
+        raise_if_notifier_privileged!(name, notifier_type, action: "add")
+        agent = @store.get(agent_id)
+        raise "Agent not found: #{agent_id}" unless agent
+        agent.set_notifier_config(name, config)
+        @notification_dispatcher.add_agent_notifier(agent_id, name)
+        nil
+      end
+
+      def cmd_remove_notifier(req)
+        agent_id = req[:agent_id]
+        name = req[:notifier_name]&.to_sym
+        agent = @store.get(agent_id)
+        raise "Agent not found: #{agent_id}" unless agent
+        existing_config = agent.notifier_config(name) || {}
+        notifier_type = existing_config[:type] || name
+        raise_if_notifier_privileged!(name, notifier_type, action: "remove")
+        @notification_dispatcher.remove_agent_notifier(agent_id, name)
+        agent.remove_notifier(name)
+        nil
+      end
+
+      def cmd_list_notifiers(req)
+        agent_id = req[:agent_id]
+        agent = @store.get(agent_id)
+        raise "Agent not found: #{agent_id}" unless agent
+
+        notifiers = agent.notifiers.reject { |name, config| notifier_hidden?(name, config) }
+          .map { |name, config| {name:, type: config[:type] || name} }
+
+        {notifiers:}
+      end
+
+      def cmd_get_privileged_notifiers(_req)
+        {
+          names: @config.notifications.select { |n| n.is_a?(Hash) && n[:privileged] == true && n[:name] }.map { it[:name].to_sym },
+          types: @config.notification_privileged_types
+        }
+      end
+
+      # -- Discovery -----------------------------------------------------------
+
+      def cmd_discover_monitors(req)
+        monitors = Monitor.registered.each_with_object([]) do |(type, klass), list|
+          next if monitor_type_hidden?(type)
+
+          probe_klass = klass.probe_class
+          entry = {
+            type: type.to_s,
+            description: klass.description,
+            required_config: klass.required_config,
+            event_types: klass.event_types
+          }
+
+          if probe_klass
+            entry[:probe] = {
+              description: probe_klass.respond_to?(:description) ? probe_klass.description : nil
+            }
+          end
+
+          list << entry
+        end
+
+        result = {available_monitors: monitors}
+
+        # Include probe-detected configs from the agent's stored environment
+        agent_id = req[:agent_id]
+        if agent_id
+          agent = @store.get(agent_id)
+          if agent&.environment
+            detected = Monitor.detect_all(environment: agent.environment)
+            detected = filter_privileged_detected(detected)
+            result[:detected] = detected unless detected.empty?
+          end
+        end
+
+        result
+      end
+
+      def cmd_discover_goals(_req)
+        goals = Goal.registered.each_with_object([]) do |(type, klass), list|
+          entry = {type: type.to_s}
+          entry[:description] = klass.description if klass.description
+          entry[:required_config] = klass.required_config unless klass.required_config.empty?
+          list << entry
+        end
+
+        {available_goals: goals}
+      end
+
+      def cmd_discover_notifiers(_req)
+        privileged_types = @config.notification_privileged_types || []
+
+        notifiers = Notifier.registered.each_with_object([]) do |(type, klass), list|
+          next if privileged_types.include?(type.to_sym)
+
+          entry = {type: type.to_s}
+          entry[:description] = klass.description if klass.respond_to?(:description) && klass.description
+          entry[:stateful] = true if klass.method_defined?(:stateful?) && klass.new(state_store: nil).stateful?
+          list << entry
+        rescue => e
+          Superkick.logger.debug("control") { "Error probing notifier #{type}: #{e.message}" }
+          list << {type: type.to_s}
+        end
+
+        {available_notifiers: notifiers}
+      end
+
+      # -- Agent claim/unclaim -------------------------------------------------
+
+      def cmd_claim_agent(req)
+        agent_id = req[:agent_id]
+        agent = @store.get(agent_id)
+        raise "Agent not found: #{agent_id}" unless agent
+        raise "Not a spawned agent" unless agent.spawn_info
+        raise "Agent already claimed" if agent.claimed?
+
+        agent.claim!
+        @supervisor.pause_goal_checker(agent_id)
+
+        dispatch_notification(
+          event: {event_type: :agent_claimed, monitor_type: :spawner,
+                  monitor_name: agent.spawn_info[:spawner_name] || :system},
+          agent_id:,
+          message: "Agent #{agent_id} claimed by user"
+        )
+        nil
+      end
+
+      def cmd_unclaim_agent(req)
+        agent_id = req[:agent_id]
+        agent = @store.get(agent_id)
+        raise "Agent not found: #{agent_id}" unless agent
+        raise "Agent is not claimed" unless agent.claimed?
+
+        agent.unclaim!
+        @supervisor.resume_goal_checker(agent_id)
+
+        dispatch_notification(
+          event: {event_type: :agent_unclaimed, monitor_type: :spawner,
+                  monitor_name: agent.spawn_info&.dig(:spawner_name) || :system},
+          agent_id:,
+          message: "Agent #{agent_id} released to autonomous operation"
+        )
+        nil
+      end
+
+      # -- Spawner management --------------------------------------------------
+
+      def cmd_list_spawners(_req)
+        {spawners: @supervisor.spawner_status}
+      end
+
+      def cmd_stop_spawner(req)
+        name = req[:spawner_name]&.to_sym
+        raise "Missing spawner_name" unless name
+        @supervisor.stop_spawner(name)
+        nil
+      end
+
+      def cmd_start_spawner(req)
+        name = req[:spawner_name]&.to_sym
+        raise "Missing spawner_name" unless name
+        config = @config.spawners[name]
+        raise "Unknown spawner: #{name}" unless config
+        @supervisor.enqueue(:start_spawner, monitor_name: name, config:)
+        nil
+      end
+
+      def cmd_terminate_agent(req)
+        agent_id = req[:agent_id]
+        agent = @store.get(agent_id)
+        raise "Agent not found: #{agent_id}" unless agent
+        raise "Not a spawned agent" unless agent.spawn_info
+        raise "No agent spawner available" unless @agent_spawner
+
+        spawner_name = agent.spawn_info[:spawner_name]
+        @agent_spawner.terminate(agent_id)
+
+        dispatch_notification(
+          event: {event_type: :agent_terminated, monitor_type: :spawner, monitor_name: spawner_name || :system},
+          agent_id:,
+          message: "Agent #{agent_id} manually terminated"
+        )
+        nil
+      end
+
+      def cmd_signal_goal(req)
+        agent_id = req[:agent_id]
+        status = req[:status]&.to_sym
+        raise "Missing agent_id" unless agent_id
+        raise "Missing status" unless status
+        raise "Invalid status: #{status}" unless %i[completed failed errored in_progress].include?(status)
+
+        agent = @store.get(agent_id)
+        raise "Agent not found: #{agent_id}" unless agent
+
+        agent.set_goal_status(status)
+        agent.set_goal_summary(req[:summary]) if req[:summary]
+        @supervisor.signal_goal(agent_id, status)
+
+        # Fire agent_blocked notification when AI signals errored status
+        if status == :errored && agent.spawn_info
+          spawner_name = agent.spawn_info[:spawner_name]
+          dispatch_notification(
+            event: {event_type: :agent_blocked, monitor_type: :spawner, monitor_name: spawner_name || :system},
+            agent_id:,
+            message: "Agent #{agent_id} needs help (signaled errored)"
+          )
+        end
+
+        Superkick.logger.info("control_server") { "Agent #{agent_id} signaled: #{status}" }
+        nil
+      end
+
+      # -- Approval gates ------------------------------------------------------
+
+      def cmd_list_approvals(_req)
+        raise "No approval store available" unless @approval_store
+
+        approvals = @approval_store.list.map do |entry|
+          {
+            id: entry[:id],
+            agent_id: entry[:agent_id],
+            spawner_name: entry[:spawner_config][:name],
+            event_type: entry[:event][:event_type].to_s,
+            created_at: entry[:created_at]
+          }
+        end
+        {approvals:}
+      end
+
+      def cmd_approve(req)
+        approval_id = req[:approval_id]
+        raise "Missing approval_id" unless approval_id
+        raise "No approval store available" unless @approval_store
+        raise "No agent spawner available" unless @agent_spawner
+
+        entry = @approval_store.take(approval_id)
+        raise "No pending approval: #{approval_id}" unless entry
+
+        result = @agent_spawner.spawn(event: entry[:event], spawner_config: entry[:spawner_config])
+        {status: result[:status], agent_id: result[:agent_id]}
+      end
+
+      def cmd_reject(req)
+        approval_id = req[:approval_id]
+        raise "Missing approval_id" unless approval_id
+        raise "No approval store available" unless @approval_store
+
+        reason = req[:reason]
+        entry = @approval_store.reject(approval_id, reason:)
+        raise "No pending approval: #{approval_id}" unless entry
+
+        detail = reason ? " (#{reason})" : ""
+        Superkick.logger.info("control_server") { "Rejected spawn approval: #{approval_id}#{detail}" }
+        nil
+      end
+
+      def cmd_clear_rejection(req)
+        approval_id = req[:approval_id]
+        raise "Missing approval_id" unless approval_id
+        raise "No approval store available" unless @approval_store
+
+        @approval_store.clear_rejection(approval_id)
+        Superkick.logger.info("control_server") { "Cleared rejection: #{approval_id}" }
+        nil
+      end
+
+      def cmd_clear_all_rejections(_req)
+        raise "No approval store available" unless @approval_store
+
+        @approval_store.clear_all_rejections
+        Superkick.logger.info("control_server") { "Cleared all rejections" }
+        nil
+      end
+
+      def cmd_list_rejections(_req)
+        raise "No approval store available" unless @approval_store
+
+        {rejections: @approval_store.rejections}
+      end
+
+      # -- Cost tracking -------------------------------------------------------
+
+      def cmd_report_cost(req)
+        agent = @store.get(req[:agent_id])
+        raise "Agent not found" unless agent
+
+        source = req[:source]&.to_sym || :unknown
+
+        if source == :mcp_report
+          # MCP reports cumulative totals — compute delta
+          prev = agent.cost.to_h
+          delta_in = (req[:tokens_in] || 0) - prev[:total_tokens_in]
+          delta_out = (req[:tokens_out] || 0) - prev[:total_tokens_out]
+          delta_usd = (req[:cost_usd] || 0.0) - prev[:total_cost_usd]
+
+          # Only record positive deltas (avoid negative corrections)
+          agent.cost.record(
+            tokens_in: [delta_in, 0].max,
+            tokens_out: [delta_out, 0].max,
+            cost_usd: [delta_usd, 0.0].max,
+            source:
+          )
+        else
+          # PTY scrape reports incremental samples
+          agent.cost.record(
+            tokens_in: req[:tokens_in] || 0,
+            tokens_out: req[:tokens_out] || 0,
+            cost_usd: req[:cost_usd] || 0.0,
+            source:
+          )
+        end
+
+        check_budget(agent)
+        nil
+      end
+
+      def cmd_get_agent_cost(req)
+        agent = @store.get(req[:agent_id])
+        raise "Agent not found: #{req[:agent_id]}" unless agent
+
+        agent.cost.to_h
+      end
+
+      def cmd_get_cost_summary(_req)
+        agents = []
+        @store.each do |agent|
+          cost_data = agent.cost.to_h
+          next if cost_data[:total_tokens_in] == 0 && cost_data[:total_cost_usd] == 0
+
+          entry = {agent_id: agent.id, cost: cost_data}
+          entry[:spawner_name] = agent.spawn_info[:spawner_name] if agent.spawn_info
+          entry[:goal_status] = agent.goal_status if agent.goal_status
+          agents << entry
+        end
+        {agents:}
+      end
+
+      # -- Team operations -----------------------------------------------------
+
+      def cmd_post_update(req)
+        agent_id = req[:agent_id]
+        agent = @store.get(agent_id)
+        raise "Agent not found: #{agent_id}" unless agent
+
+        if req[:target_agent_id]
+          # Directed message — validate same team, inject into target
+          raise "Agent is not on a team" unless agent.team_id
+
+          target = @store.get(req[:target_agent_id])
+          raise "Target not found: #{req[:target_agent_id]}" unless target
+          raise "Target is not on the same team" unless target.team_id == agent.team_id
+
+          injection_event = {
+            event_type: :teammate_message,
+            monitor_type: :team_log,
+            monitor_name: :team_log,
+            sender_agent_id: agent_id,
+            sender_role: agent.team_role.to_s,
+            message: req[:message],
+            time: Time.now.strftime("%H:%M:%S"),
+            injection_priority: :high,
+            injection_ttl: 900
+          }
+          @injector.inject(agent_id: req[:target_agent_id], event: injection_event)
+
+          dispatch_notification(
+            event: {event_type: :teammate_message, monitor_type: :team, monitor_name: :team,
+                    target_agent_id: req[:target_agent_id], team_id: agent.team_id},
+            agent_id:,
+            message: "#{agent_id} sent message to #{req[:target_agent_id]}: #{req[:message].slice(0, 100)}"
+          )
+        else
+          # Broadcast update
+          event_type = (req[:kind]&.to_sym == :blocker) ? :teammate_blocker : :agent_update
+          dispatch_notification(
+            event: {event_type:, monitor_type: :agent, monitor_name: :agent,
+                    kind: req[:kind]&.to_sym, team_id: agent.team_id},
+            agent_id:,
+            message: req[:message]
+          )
+        end
+
+        nil
+      end
+
+      def cmd_post_team_message(req)
+        team_id = req[:team_id]
+        raise "Missing team_id" unless team_id
+        raise "Missing message" unless req[:message]
+
+        members = @store.team(team_id)
+        raise "No agents found for team: #{team_id}" if members.empty?
+
+        # Inject the message into every agent on the team
+        members.each do |agent|
+          injection_event = {
+            event_type: :teammate_message,
+            monitor_type: :team_log,
+            monitor_name: :team_log,
+            sender_agent_id: "operator",
+            sender_role: "operator",
+            message: req[:message],
+            time: Time.now.strftime("%H:%M:%S"),
+            injection_priority: :high,
+            injection_ttl: 900
+          }
+          @injector.inject(agent_id: agent.id, event: injection_event)
+        end
+
+        # Write to team log so it's visible in `team watch`
+        if @team_log_store
+          log = @team_log_store.get(team_id)
+          log.append(
+            agent_id: "operator",
+            agent_role: :operator,
+            category: :message,
+            message: req[:message]
+          )
+        end
+
+        {delivered_to: members.size}
+      end
+
+      def cmd_team_status(req)
+        team_id = req[:team_id]
+        unless team_id
+          agent_id = req[:agent_id]
+          agent = @store.get(agent_id)
+          raise "Agent not found: #{agent_id}" unless agent
+          raise "Agent is not on a team" unless agent.team_id
+          team_id = agent.team_id
+        end
+        raise "No team log store available" unless @team_log_store
+        log = @team_log_store.get(team_id)
+
+        teammates = @store.team(team_id).map do |a|
+          entry = {agent_id: a.id, team_role: a.team_role, goal_status: a.goal_status}
+          entry[:role] = a.role if a.role
+          entry
+        end
+
+        result = {team_id:, teammates:}
+
+        if log
+          if req[:full_log]
+            result[:entries] = log.entries(since: req[:since]).map(&:to_h)
+          else
+            summary = log.summary
+            result[:latest] = summary[:latest_by_agent].map(&:to_h)
+            result[:unresolved_blockers] = summary[:unresolved_blockers].map(&:to_h)
+          end
+        end
+
+        result
+      end
+
+      def cmd_list_teammates(req)
+        agent_id = req[:agent_id]
+        agent = @store.get(agent_id)
+        raise "Agent not found: #{agent_id}" unless agent
+        raise "Agent is not on a team" unless agent.team_id
+
+        teammates = @store.team(agent.team_id).map do |a|
+          entry = {agent_id: a.id, team_role: a.team_role, goal_status: a.goal_status}
+          entry[:role] = a.role if a.role
+          entry[:claimed_at] = a.claimed_at if a.claimed_at
+
+          if @team_log_store
+            log = @team_log_store.get(agent.team_id)
+            if log
+              latest = log.entries.select { it.agent_id == a.id }.last
+              entry[:latest_update] = latest.to_h if latest
+            end
+          end
+
+          entry
+        end
+
+        {team_id: agent.team_id, teammates:}
+      end
+
+      def cmd_spawn_worker(req)
+        agent_id = req[:agent_id]
+        raise "Missing agent_id" unless agent_id
+        raise "No agent spawner available" unless @agent_spawner
+
+        agent = @store.get(agent_id)
+        raise "Agent not found: #{agent_id}" unless agent
+        raise "Agent is not on a team" unless agent.team_id
+
+        team_id = agent.team_id
+        repository_name = req[:repository]
+        task = req[:task]
+        agent_suffix = req[:agent_suffix]
+        raise "Missing repository" unless repository_name
+        raise "Missing task" unless task
+        raise "Missing agent_suffix" unless agent_suffix
+
+        # Enforce max_workers_per_team
+        current_workers = @store.team(team_id).count { it.team_role == :worker }
+        max_workers = @config.max_workers_per_team
+        raise "Team worker limit reached (#{max_workers})" if current_workers >= max_workers
+
+        # Validate repository exists in source
+        repository = @config.repository_source.find_by_name(repository_name)
+        raise "Unknown repository: #{repository_name}" unless repository
+
+        worker_id = "#{team_id}-#{agent_suffix}"
+        raise "Agent #{worker_id} already exists" if @store.has?(worker_id)
+
+        # Build worker event
+        goal_config = req[:goal] || {type: :agent_signal}
+        goal_config[:type] = goal_config[:type].to_sym if goal_config[:type]
+
+        worker_event = {
+          event_type: :worker_spawned,
+          agent_id: worker_id,
+          team_id:,
+          team_role: :worker,
+          role: req[:role],
+          lead_agent_id: agent_id,
+          repository_name: repository_name.to_s,
+          task:,
+          depends_on: req[:depends_on]
+        }
+
+        # Auto-attach team_log monitor; lead-provided monitors merge on top
+        auto_monitors = {team_log: {type: :team_log, team_id:}}
+        explicit_monitors = req[:monitors] || {}
+        worker_event[:_spawn_monitors] = auto_monitors.merge(explicit_monitors)
+
+        # Forward notifiers from the lead
+        worker_event[:_spawn_notifiers] = req[:notifiers] if req[:notifiers]&.any?
+
+        # Add monitor names to template context (names only, no config/secrets)
+        all_monitor_names = worker_event[:_spawn_monitors].keys.map(&:to_s)
+        worker_event[:monitor_names] = all_monitor_names
+
+        # Determine spawner config for the worker
+        spawner_config = build_worker_spawner_config(agent, repository, goal_config)
+
+        result = @agent_spawner.spawn(event: worker_event, spawner_config:)
+
+        if result[:status] == :spawned
+          dispatch_notification(
+            event: {event_type: :worker_spawned, monitor_type: :team, monitor_name: :team,
+                    team_id:, repository_name:},
+            agent_id: worker_id,
+            message: "Worker #{worker_id} spawned for repository #{repository_name} by #{agent_id}"
+          )
+        end
+
+        {status: result[:status], agent_id: worker_id}
+      end
+
+      def cmd_spawn_worker_by_team(req)
+        team_id = req[:team_id]
+        raise "Missing team_id" unless team_id
+        raise "No agent spawner available" unless @agent_spawner
+
+        # Find the team lead (or any team member) to derive spawner config
+        team_agents = @store.team(team_id)
+        raise "No agents found for team: #{team_id}" if team_agents.empty?
+        lead_agent = team_agents.find { it.team_role == :lead } || team_agents.first
+
+        repository_name = req[:repository]
+        task = req[:task]
+        raise "Missing repository" unless repository_name
+        raise "Missing task" unless task
+
+        # Enforce max_workers_per_team
+        current_workers = team_agents.count { it.team_role == :worker }
+        max_workers = @config.max_workers_per_team
+        raise "Team worker limit reached (#{max_workers})" if current_workers >= max_workers
+
+        # Validate repository exists in source
+        repository = @config.repository_source.find_by_name(repository_name)
+        raise "Unknown repository: #{repository_name}" unless repository
+
+        # Generate agent ID from role + random suffix
+        worker_id = generate_worker_id(team_id, req[:role])
+        raise "Agent #{worker_id} already exists" if @store.has?(worker_id)
+
+        # Build worker event
+        goal_config = req[:goal] || {type: :agent_signal}
+        goal_config[:type] = goal_config[:type].to_sym if goal_config[:type]
+
+        worker_event = {
+          event_type: :worker_spawned,
+          agent_id: worker_id,
+          team_id:,
+          team_role: :worker,
+          role: req[:role],
+          lead_agent_id: lead_agent.id,
+          repository_name: repository_name.to_s,
+          task:,
+          depends_on: req[:depends_on]
+        }
+
+        # Auto-attach team_log monitor; merge user-provided monitors on top
+        spawn_monitors = {team_log: {type: :team_log, team_id:}}
+        if req[:monitors].is_a?(Hash)
+          req[:monitors].each { |k, v| spawn_monitors[k.to_sym] = v }
+        end
+        worker_event[:_spawn_monitors] = spawn_monitors
+
+        # Attach user-provided notifiers
+        if req[:notifiers].is_a?(Hash)
+          spawn_notifiers = {}
+          req[:notifiers].each { |k, v| spawn_notifiers[k.to_sym] = v }
+          worker_event[:_spawn_notifiers] = spawn_notifiers
+        end
+
+        spawner_config = build_worker_spawner_config(lead_agent, repository, goal_config)
+        result = @agent_spawner.spawn(event: worker_event, spawner_config:)
+
+        if result[:status] == :spawned
+          dispatch_notification(
+            event: {event_type: :worker_spawned, monitor_type: :team, monitor_name: :team,
+                    team_id:, repository_name:},
+            agent_id: worker_id,
+            message: "Worker #{worker_id} spawned for repository #{repository_name} via CLI"
+          )
+        end
+
+        {status: result[:status], agent_id: worker_id}
+      end
+
+      # -- Repository discovery ------------------------------------------------
+
+      def cmd_discover_repositories(_req)
+        source = @config.repository_source
+        repositories = source.repositories.map do |name, repository|
+          entry = {name: name.to_s}
+          entry[:dependencies] = repository.dependencies if repository.dependencies.any?
+          entry[:path] = repository.path if repository.path
+          entry[:url] = repository.url if repository.url
+          entry[:version_control] = repository.version_control if repository.version_control
+          entry
+        end
+        {repositories:}
+      end
+
+      # -- Team artifacts ------------------------------------------------------
+
+      def cmd_publish_artifact(req)
+        agent_id = req[:agent_id]
+        agent = @store.get(agent_id)
+        raise "Agent not found: #{agent_id}" unless agent
+        raise "Agent is not on a team" unless agent.team_id
+        raise "No artifact store available" unless @team_artifact_store
+        raise "Missing name" unless req[:name]
+        raise "Missing content" unless req[:content]
+
+        artifact = @team_artifact_store.publish(
+          team_id: agent.team_id,
+          author: agent_id,
+          name: req[:name],
+          content: req[:content]
+        )
+
+        dispatch_notification(
+          event: {event_type: :artifact_published, monitor_type: :agent, monitor_name: :agent,
+                  artifact_name: req[:name], team_id: agent.team_id},
+          agent_id:,
+          message: "Published artifact: #{req[:name]}"
+        )
+
+        {name: artifact.name, author: artifact.author, updated_at: artifact.updated_at}
+      end
+
+      def cmd_read_artifact(req)
+        agent_id = req[:agent_id]
+        agent = @store.get(agent_id)
+        raise "Agent not found: #{agent_id}" unless agent
+        raise "Agent is not on a team" unless agent.team_id
+        raise "No artifact store available" unless @team_artifact_store
+        raise "Missing author" unless req[:author]
+        raise "Missing name" unless req[:name]
+
+        artifact = @team_artifact_store.get(
+          team_id: agent.team_id,
+          author: req[:author],
+          name: req[:name]
+        )
+        raise "Artifact not found: #{req[:author]}/#{req[:name]}" unless artifact
+
+        {name: artifact.name, author: artifact.author, content: artifact.content,
+         created_at: artifact.created_at, updated_at: artifact.updated_at}
+      end
+
+      def cmd_list_artifacts(req)
+        agent_id = req[:agent_id]
+        agent = @store.get(agent_id)
+        raise "Agent not found: #{agent_id}" unless agent
+        raise "Agent is not on a team" unless agent.team_id
+        raise "No artifact store available" unless @team_artifact_store
+
+        artifacts = @team_artifact_store.list(
+          team_id: agent.team_id,
+          author: req[:author]
+        )
+        {artifacts:}
+      end
+
+      # -- Team artifacts (by team_id, for CLI) ---------------------------------
+
+      def cmd_list_team_artifacts(req)
+        team_id = req[:team_id]
+        raise "Missing team_id" unless team_id
+        raise "No artifact store available" unless @team_artifact_store
+
+        artifacts = @team_artifact_store.list(
+          team_id:,
+          author: req[:author]
+        )
+        {artifacts:}
+      end
+
+      def cmd_read_team_artifact(req)
+        team_id = req[:team_id]
+        raise "Missing team_id" unless team_id
+        raise "No artifact store available" unless @team_artifact_store
+        raise "Missing author" unless req[:author]
+        raise "Missing name" unless req[:name]
+
+        artifact = @team_artifact_store.get(
+          team_id:,
+          author: req[:author],
+          name: req[:name]
+        )
+        raise "Artifact not found: #{req[:author]}/#{req[:name]}" unless artifact
+
+        {name: artifact.name, author: artifact.author, content: artifact.content,
+         created_at: artifact.created_at, updated_at: artifact.updated_at}
+      end
+
+      # -- Privileged monitor queries ------------------------------------------
+
+      def cmd_get_privileged_monitors(_req)
+        {
+          names: @config.monitors.select { |_, config| config.is_a?(Hash) && config[:privileged] == true }.keys,
+          types: @config.privileged_types
+        }
+      end
+
+      def serialize_agent(agent)
+        visible = agent.monitors.reject { |name, config| monitor_hidden?(name, config) }
+        hash = {
+          agent_id: agent.id,
+          registered_at: agent.registered_at,
+          last_notified: agent.last_notified_at,
+          monitor_count: visible.size,
+          has_buffer: !agent.buffer_socket_path.nil?,
+          has_output_log: !agent.output_log_path.nil?,
+          has_attach: !agent.attach_socket_path.nil?,
+          output_log_path: agent.output_log_path,
+          recording_path: agent.recording_path
+        }
+        hash[:spawn_info] = agent.spawn_info if agent.spawn_info
+        hash[:goal_status] = agent.goal_status if agent.goal_status
+        hash[:claimed_at] = agent.claimed_at if agent.claimed_at
+        hash[:team_id] = agent.team_id if agent.team_id
+        hash[:team_role] = agent.team_role if agent.team_role
+        hash[:role] = agent.role if agent.role
+        cost_data = agent.cost.to_h
+        hash[:cost] = cost_data if cost_data[:total_tokens_in] > 0 || cost_data[:total_cost_usd] > 0
+        hash
+      end
+
+      # Returns true when a monitor should be hidden from AI-facing responses.
+      def monitor_hidden?(name, config)
+        monitor_type = config.is_a?(Hash) ? (config[:type] || name) : name
+        @config.monitor_privileged?(name) || @config.type_privileged?(monitor_type)
+      end
+
+      def monitor_type_hidden?(type)
+        @config.type_privileged?(type)
+      end
+
+      def collect_environment_actions
+        Monitor.all_environment_actions
+      end
+
+      def filter_privileged_detected(detected)
+        priv_names = @config.monitors.select { |_, config| config.is_a?(Hash) && config[:privileged] == true }.keys
+        priv_types = @config.privileged_types || []
+        detected.reject do |name, config|
+          monitor_type = config.is_a?(Hash) ? (config[:type] || name) : name
+          priv_names.include?(name) || priv_types.include?(monitor_type.to_sym)
+        end
+      end
+
+      def raise_if_privileged!(name, type, action:)
+        configuration = @config
+
+        if configuration.monitor_privileged?(name)
+          raise "Cannot #{action} monitor '#{name}': it is a privileged monitor (protected by name)"
+        end
+
+        if configuration.type_privileged?(type)
+          raise "Cannot #{action} monitor '#{name}' (type '#{type}'): monitors of type '#{type}' are privileged (protected by type)"
+        end
+      end
+
+      # Returns true when a notifier should be hidden from AI-facing responses.
+      def notifier_hidden?(name, config)
+        notifier_type = config.is_a?(Hash) ? (config[:type] || name) : name
+        @config.notifier_privileged?(name) || @config.notifier_type_privileged?(notifier_type)
+      end
+
+      def raise_if_notifier_privileged!(name, type, action:)
+        configuration = @config
+
+        if configuration.notifier_privileged?(name)
+          raise "Cannot #{action} notifier '#{name}': it is a privileged notifier (protected by name)"
+        end
+
+        if configuration.notifier_type_privileged?(type)
+          raise "Cannot #{action} notifier '#{name}' (type '#{type}'): notifiers of type '#{type}' are privileged (protected by type)"
+        end
+      end
+
+      def check_budget(agent)
+        return unless @budget_checker
+
+        violations = @budget_checker.check(agent)
+        return if violations.empty?
+
+        violations.each do |v|
+          case v[:action]
+          when :warning
+            notify_budget(:budget_warning, agent, v)
+          when :exceeded
+            notify_budget(:budget_exceeded, agent, v)
+            enforce_budget(agent, v) if hard_enforcement?(agent)
+          end
+        end
+      end
+
+      def notify_budget(event_type, agent, violation)
+        dispatch_notification(
+          event: {
+            event_type:,
+            monitor_type: :cost,
+            monitor_name: :budget,
+            budget: violation[:budget],
+            spent: violation[:spent].round(2)
+          },
+          agent_id: agent.id,
+          message: "Agent #{agent.id} #{violation[:level]} budget: " \
+                   "$#{violation[:spent].round(2)} / $#{violation[:budget]} " \
+                   "(#{violation[:action]})"
+        )
+      end
+
+      def hard_enforcement?(agent)
+        return false unless agent.spawn_info
+        spawner_name = agent.spawn_info[:spawner_name]&.to_sym
+        @config.spawners.dig(spawner_name, :budget, :enforce)&.to_s == "hard"
+      end
+
+      def enforce_budget(agent, violation)
+        case violation[:level]
+        when :agent
+          @agent_spawner&.terminate(agent.id)
+        when :spawner
+          spawner_name = agent.spawn_info[:spawner_name]&.to_sym
+          @supervisor.stop_spawner(spawner_name) if spawner_name
+        when :global
+          @config.spawners.each_key { @supervisor.stop_spawner(it) }
+        end
+      end
+
+      def build_worker_spawner_config(lead_agent, repository, goal_config)
+        spawner_name = lead_agent.spawn_info&.dig(:spawner_name)
+        spawner_cfg = spawner_name ? (@config.spawners[spawner_name.to_sym] || {}) : {}
+        worker_cfg = spawner_cfg.dig(:team, :worker) || {}
+
+        # Resolve driver: team.worker.driver merged on top of spawner driver
+        driver = Driver.merge_driver(spawner_cfg[:driver], worker_cfg[:driver])
+        max_duration = worker_cfg[:max_duration] || spawner_cfg[:max_duration]
+
+        config = {
+          name: spawner_name,
+          driver:,
+          repository: repository.name.to_s,
+          goal: goal_config,
+          prompt_template: "team/worker_kickoff"
+        }
+        config[:max_duration] = max_duration if max_duration
+        config[:budget] = worker_cfg[:budget] if worker_cfg[:budget]
+        config
+      end
+
+      # Forward a buffer command to the agent via the buffer client.
+      def proxy_buffer(agent_id, command, **extra_params)
+        response = @buffer_client.request(agent_id, command, **extra_params.compact)
+        raise response[:error] if response && response[:ok] == false && response[:error]
+
+        response
+      end
+
+      def generate_worker_id(team_id, role)
+        suffix = if role
+          slugified = role.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|-\z/, "")[0, 20]
+          random = SecureRandom.hex(3)
+          "#{slugified}-#{random}"
+        else
+          SecureRandom.hex(3)
+        end
+        "#{team_id}-#{suffix}"
+      end
+
+      def dispatch_notification(...)
+        @notification_dispatcher.dispatch(...)
+      end
+    end
+  end
+end