hyperprobe-agent 1.2.27.pre.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0fc98f264e7d9cd4fe3c902f686ba8e6b95e7c6f272126d4b6a811400f0eff39
+  data.tar.gz: 67b10ac7149644e1a4644693e016b31b48dc8f6892fcc9c1c5e360e5604495a5
+SHA512:
+  metadata.gz: 44c3a8718c1df4b1b843f9320b4deb3237ab722af67128cb38670c80ebf1bb74e2a6a5f81ebb7d9b5d4f12af92b1ea43b6abcc13ec01f6a4a3f34500cf42006f
+  data.tar.gz: 47e7bb3084e5700db38c353cf351046c7082abf417ab30a41350270c72329194b89cceba596df0cdc9cd53d0f40c3e05cc02ef712290895b9e1d302f39360f69

data/LICENSE

@@ -0,0 +1,13 @@
+Hyperprobe Proprietary License
+
+Copyright (c) 2026 Hyperprobe. All rights reserved.
+
+This software and its associated documentation are proprietary to Hyperprobe.
+No permission is granted to use, copy, modify, distribute, sublicense, or
+create derivative works except as expressly authorized under a written
+commercial license agreement with Hyperprobe.
+
+A valid commercial license from Hyperprobe is required to operate this
+software.
+
+For licensing inquiries, visit https://hyperprobe.co/.

data/README.md

@@ -0,0 +1,157 @@
+# HyperProbe Ruby Agent
+
+Production-grade, non-breaking live debugger and telemetry agent for Ruby and JRuby applications.
+
+## Overview
+
+The HyperProbe Ruby Agent allows developers to set non-breaking live probes (snapshots, logs, counters, metrics, and durations) in production environments without pausing execution or modifying source code.
+
+## Key Features
+
+- **Snapshots**: Capture local variables across stack frames and evaluate watch expressions without pausing threads.
+- **Dynamic Logs**: Evaluate log templates (`${var}`) in context, with optional stdout emission and full value redaction.
+- **Metrics & Counters**: Measure event counts, custom expressions, and block/loop durations.
+- **Safety Shield**: Continuous thread lag monitoring and pause duration budgets with automated circuit breaker shedding (`GREEN`/`YELLOW`/`RED`).
+- **Quota Governance**: Token bucket rate limiting for hits per second and network bandwidth.
+- **Distributed Tracing**: Integrations with OpenTelemetry, Datadog (`ddtrace`), New Relic (`newrelic_rpm`), Elastic APM, and custom trace getters.
+- **Multi-Process & Serverless**: Native support for Puma/Unicorn worker forking and AWS Lambda execution.
+- **JRuby on JVM**: First-class JRuby support with native JVM HTTP/2 gRPC transport and hybrid Java object serialization.
+
+## Runtime Compatibility
+
+| Platform | Supported Versions | Prerequisites |
+| :--- | :--- | :--- |
+| **Standard Ruby (CRuby / MRI)** | **Ruby 3.0, 3.1, 3.2, 3.3, 3.4, 4.0+** | None (Zero launch flags needed) |
+| **JRuby (Ruby on JVM)** | **JRuby 9.3+, 9.4+, 10.x+** | **Java 11+** and `JRUBY_OPTS="--debug"` |
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'hyperprobe-agent'
+```
+
+And run:
+
+```bash
+bundle install
+```
+
+## Quickstart
+
+Create a dedicated `hyperprobe.rb` file in your application root:
+
+```ruby
+# hyperprobe.rb
+require 'hyperprobe'
+
+HyperProbe.start(
+  service_id: '<service-uuid-from-dashboard>',
+  environment: ENV['HYPERPROBE_ENVIRONMENT'] || 'production',
+  broker_url: 'https://logger.app.hyperprobe.co',
+  commit_sha: ENV['GIT_COMMIT']
+)
+```
+
+Require it as early as possible in your application entrypoint (e.g. `app.rb`, `server.rb`, `config/environment.rb`):
+
+```ruby
+# app.rb
+require_relative 'hyperprobe'
+
+# ... start your web server / application ...
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+| :--- | :--- | :--- |
+| `HYPERPROBE_SERVICE_ID` | Unique UUID for the service | (Required) |
+| `HYPERPROBE_ENVIRONMENT` | Deployment environment (`production`, `staging`, etc.) | (Required) |
+| `HYPERPROBE_BROKER_URL` | gRPC Broker endpoint | (Required) |
+| `GIT_COMMIT` / `HYPERPROBE_COMMIT_SHA` | Current deployment commit SHA | (Required) |
+| `HYPERPROBE_DISABLED` | Set to `YES` to disable the agent | `NO` |
+| `HYPERPROBE_SYNC_INTERVAL_MS` | Probe synchronization interval | `60000` |
+| `HYPERPROBE_FLUSH_INTERVAL_MS` | Telemetry batch flush interval | `1000` |
+| `HYPERPROBE_HITS_PER_SEC` | Maximum probe hits evaluated per second | `10` |
+| `HYPERPROBE_BANDWIDTH_KB_PER_SEC` | Maximum telemetry bandwidth in KB/s | `1024` |
+| `HYPERPROBE_MAX_LAG_MS` | Safety threshold for thread lag | `50` |
+| `HYPERPROBE_PAUSE_BUDGET_MS` | Maximum probe execution pause per second | `15` |
+| `HYPERPROBE_REDACT_KEYS` | Comma-separated list of sensitive key patterns | `password,secret,token,...` |
+| `HYPERPROBE_REDACT_VALUES` | Comma-separated list of sensitive value regexes | `""` |
+
+---
+
+## ☕ JRuby Support (Ruby on the JVM)
+
+HyperProbe provides native, first-class support for JRuby applications running on the JVM.
+
+### Prerequisites for JRuby
+1. **JRuby Version**: JRuby 9.3+, 9.4+, or 10.x+.
+2. **Java Runtime**: Java 11, 17, 21, or 25+.
+3. **Debug Flag**: The JVM must be launched with `--debug` or `JRUBY_OPTS="--debug"`.
+
+### Why is `--debug` Required on JRuby?
+JRuby's JIT (Just-In-Time) compiler aggressively optimizes hot methods into raw JVM bytecode, stripping out line-level checkpoints and local variable names by default.
+
+Running with `--debug` instructs JRuby's JVM compiler to:
+* Retain line-by-line tracing checkpoints so probes trigger reliably on every execution.
+* Preserve local variable tables in memory for snapshot capture.
+
+> **Pre-Flight Protection**: If JRuby is started without `--debug`, HyperProbe detects this at startup, logs an informative error message, and safely aborts initialization without attaching hooks or degrading performance.
+
+### How to Run JRuby with HyperProbe
+
+#### 1. In Docker / Kubernetes
+Add the environment variable in your `Dockerfile` or Deployment manifest:
+```dockerfile
+ENV JRUBY_OPTS="--debug"
+```
+
+#### 2. Command Line / Local
+Launch JRuby with the `--debug` flag:
+```bash
+jruby --debug app.rb
+# or:
+JRUBY_OPTS="--debug" jruby app.rb
+```
+
+### JRuby Architecture Highlights
+* **Zero C-Extensions**: On JRuby, HyperProbe automatically uses Java's built-in `java.net.http.HttpClient` (HTTP/2) for gRPC communication to the Logger. No native compilation or C-extensions are required.
+* **Hybrid Object Serialization**: Automatically detects and serializes both native Ruby objects and Java collections (`java.util.Map`, `java.util.List`, `java.util.Set`, and Java POJOs).
+* **Multi-Threaded Safety**: Thread-safe synchronization across parallel JVM worker threads.
+
+---
+
+## Puma / Unicorn Multi-Worker Integration
+
+When using multi-worker servers like Puma or Unicorn in cluster mode on CRuby:
+
+```ruby
+# config/puma.rb
+on_worker_boot do
+  HyperProbe.after_fork
+end
+```
+
+*(Note: On JRuby, Puma runs in multi-threaded mode on the JVM without process forking, so `after_fork` is not required).*
+
+---
+
+## AWS Lambda Integration
+
+```ruby
+require 'hyperprobe'
+
+handler = ->(event:, context:) {
+  # Handler logic
+  { statusCode: 200, body: "OK" }
+}
+
+exports.handler = HyperProbe.wrap_lambda(
+  service_id: '<service-uuid>',
+  environment: 'production',
+  broker_url: 'https://logger.app.hyperprobe.co'
+) { |event:, context:| handler.call(event: event, context: context) }
+```

data/lib/hyperprobe/agent.rb

@@ -0,0 +1,438 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'uri'
+require 'thread'
+require_relative 'version'
+require_relative 'core/quota'
+require_relative 'core/safety'
+require_relative 'core/serializer'
+require_relative 'core/evaluator'
+require_relative 'core/trace_extractor'
+require_relative 'core/monitoring_engine'
+require_relative 'core/broker'
+
+module HyperProbe
+  UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.freeze
+
+  class Agent
+    attr_reader :options, :agent_id, :owner_pid, :is_shutdown, :active_probes, :global_config, :quota_manager, :safety_monitor, :broker_client, :engine
+
+    def initialize(options = {})
+      @options = (options || {}).dup
+      @owner_pid = Process.pid
+      @agent_id = SecureRandom.uuid
+      @is_shutdown = false
+      @is_agent_disabled = false
+      @stop_event = ConditionVariable.new
+      @mutex = Monitor.new # Reentrant mutex in Ruby
+
+      @log = Core::Logger.get_logger('hyperprobe:agent')
+      @log_broker = Core::Logger.get_logger('hyperprobe:broker')
+      @log_safety = Core::Logger.get_logger('hyperprobe:safety')
+      @log_stats = Core::Logger.get_logger('hyperprobe:stats')
+
+      parse_configuration
+
+      @quota_manager = Core::QuotaManager.new(@hits_per_sec, @bandwidth_kb_per_sec * 1024)
+      @safety_monitor = Core::SafetyMonitor.new(
+        method(:handle_health_change),
+        max_lag_ms: @max_lag_ms,
+        pause_budget_ms: @pause_budget_ms,
+        is_ephemeral_lambda: @is_ephemeral_lambda
+      )
+
+      @broker_client = Core::BrokerClient.new(
+        broker_url: @broker_url,
+        service_id: @service_id,
+        environment: @environment,
+        commit_sha: @commit_sha,
+        agent_id: @agent_id,
+        agent_version: VERSION,
+        rpc_timeout_sec: @rpc_timeout_sec,
+        enable_keep_alive: @enable_keep_alive
+      )
+
+      @telemetry_queue = Queue.new
+      @active_probes = {}
+      @local_hits = {}
+      @cooldown_timer = nil
+
+      @engine = Core::MonitoringEngine.new(
+        @quota_manager,
+        @safety_monitor,
+        method(:handle_capture),
+        @options[:set_trace_id]
+      )
+      @engine.set_global_config(@global_config)
+
+      @sync_thread = nil
+      @flush_thread = nil
+      @stats_thread = nil
+
+      if @is_ephemeral_lambda
+        @log.debug 'Running in Ephemeral AWS Lambda Mode.'
+      else
+        @safety_monitor.start
+        start_background_loops
+        sync_with_broker
+      end
+
+      @log.info "Agent started for #{@service_id} in #{@environment} (v#{VERSION})"
+    end
+
+    def agent_disabled?
+      @is_agent_disabled
+    end
+
+    def telemetry_queue_length
+      @telemetry_queue.size
+    end
+
+    def force_sync(timeout_sec = nil)
+      return if @is_shutdown || @is_agent_disabled
+
+      sync_with_broker(timeout_sec)
+    end
+
+    def force_flush(timeout_sec = nil)
+      return if @is_shutdown || @is_agent_disabled
+
+      flush_telemetry(timeout_sec)
+    end
+
+    def shutdown
+      @mutex.synchronize do
+        return if @is_shutdown
+
+        @is_shutdown = true
+      end
+
+      @safety_monitor&.stop
+      @engine&.close
+      @cooldown_timer&.exit if @cooldown_timer&.alive?
+      @broker_client&.shutdown
+
+      [@sync_thread, @flush_thread, @stats_thread].compact.each do |t|
+        t.kill if t.alive? && t != Thread.current
+        t.join(1.0) rescue nil
+      end
+    end
+
+    def after_fork
+      return if defined?(JRUBY_VERSION)
+
+      @mutex.synchronize do
+        return if @is_shutdown
+
+        @owner_pid = Process.pid
+        @agent_id = SecureRandom.uuid
+
+        # Reset queues and client for new process
+        @telemetry_queue = Queue.new
+        @broker_client = Core::BrokerClient.new(
+          broker_url: @broker_url,
+          service_id: @service_id,
+          environment: @environment,
+          commit_sha: @commit_sha,
+          agent_id: @agent_id,
+          agent_version: VERSION,
+          rpc_timeout_sec: @rpc_timeout_sec,
+          enable_keep_alive: @enable_keep_alive
+        )
+
+        @safety_monitor.start
+        start_background_loops
+        sync_with_broker
+      end
+    end
+
+    private
+
+    def parse_configuration
+      @service_id = get_opt(:service_id, :serviceId) || ENV['HYPERPROBE_SERVICE_ID']
+      @environment = get_opt(:environment) || ENV['HYPERPROBE_ENVIRONMENT']
+      @broker_url = get_opt(:broker_url, :brokerUrl) || ENV['HYPERPROBE_BROKER_URL']
+      @commit_sha = get_opt(:commit_sha, :commitSha) || ENV['GIT_COMMIT'] || ENV['HYPERPROBE_COMMIT_SHA']
+
+      @sync_interval_sec = ((get_opt(:sync_interval_ms, :syncIntervalMs) || parse_env_int('HYPERPROBE_SYNC_INTERVAL_MS', 60_000)).to_f / 1000.0)
+      @flush_interval_sec = ((get_opt(:flush_interval_ms, :flushIntervalMs) || parse_env_int('HYPERPROBE_FLUSH_INTERVAL_MS', 1000)).to_f / 1000.0)
+      @max_queue_size = get_opt(:max_queue_size, :maxQueueSize) || parse_env_int('HYPERPROBE_MAX_QUEUE_SIZE', 100)
+      @cooldown_sec = get_opt(:cooldown_sec, :cooldownSec) || parse_env_int('HYPERPROBE_COOLDOWN_SEC', 10)
+
+      @hits_per_sec = get_opt(:hits_per_sec, :hitsPerSec) || parse_env_int('HYPERPROBE_HITS_PER_SEC', 10)
+      @bandwidth_kb_per_sec = get_opt(:bandwidth_kb_per_sec, :bandwidthKbPerSec) || parse_env_int('HYPERPROBE_BANDWIDTH_KB_PER_SEC', 1024)
+      @max_lag_ms = (get_opt(:max_lag_ms, :maxLagMs) || parse_env_int('HYPERPROBE_MAX_LAG_MS', 50)).to_f
+      @pause_budget_ms = (get_opt(:pause_budget_ms, :pauseBudgetMs) || parse_env_int('HYPERPROBE_PAUSE_BUDGET_MS', 15)).to_f
+      @rpc_timeout_sec = (get_opt(:rpc_timeout_sec, :rpcTimeoutSec) || parse_env_int('HYPERPROBE_RPC_TIMEOUT_SEC', 10)).to_f
+
+      is_aws_lambda = !ENV['AWS_LAMBDA_FUNCTION_NAME'].nil?
+      is_local_emulator = ENV['IS_OFFLINE'] == 'true' || ENV['AWS_SAM_LOCAL'] == 'true'
+      @is_ephemeral_lambda = (get_opt(:is_lambda, :isLambda) || is_aws_lambda) && !is_local_emulator
+      enable_keep_alive_opt = get_opt(:enable_keep_alive, :enableKeepAlive)
+      @enable_keep_alive = enable_keep_alive_opt.nil? ? !@is_ephemeral_lambda : enable_keep_alive_opt
+
+      redact_keys_raw = get_opt(:redact_keys, :redactKeys) || (ENV['HYPERPROBE_REDACT_KEYS'] ? ENV['HYPERPROBE_REDACT_KEYS'].split(',') : %w[password secret token authorization cookie key signature])
+      redact_values_raw = get_opt(:redact_values, :redactValues) || (ENV['HYPERPROBE_REDACT_VALUES'] ? ENV['HYPERPROBE_REDACT_VALUES'].split(',') : [])
+
+      @global_config = {
+        redact_keys: Array(redact_keys_raw).map(&:to_s).map(&:strip).reject(&:empty?),
+        redact_values: Array(redact_values_raw).map(&:to_s).map(&:strip).reject(&:empty?),
+        max_object_depth: get_opt(:max_object_depth, :maxObjectDepth) || parse_env_int('HYPERPROBE_MAX_OBJECT_DEPTH', 3),
+        max_array_length: get_opt(:max_array_length, :maxArrayLength) || parse_env_int('HYPERPROBE_MAX_ARRAY_LENGTH', 3),
+        stack_frame_depth: get_opt(:stack_frame_depth, :stackFrameDepth) || parse_env_int('HYPERPROBE_STACK_FRAME_DEPTH', 3),
+        max_object_properties: get_opt(:max_object_properties, :maxObjectProperties) || parse_env_int('HYPERPROBE_MAX_OBJECT_PROPERTIES', 50),
+        max_string_length: get_opt(:max_string_length, :maxStringLength) || parse_env_int('HYPERPROBE_MAX_STRING_LENGTH', 1024)
+      }
+    end
+
+    def get_opt(*keys)
+      keys.each do |k|
+        return @options[k] if @options.key?(k)
+        return @options[k.to_s] if @options.key?(k.to_s)
+      end
+      nil
+    end
+
+    def parse_env_int(key, default_val)
+      val = ENV[key]
+      return default_val if val.nil? || val.strip.empty?
+
+      val.to_i rescue default_val
+    end
+
+    def start_background_loops
+      @sync_thread = Thread.new { sync_loop }
+      @sync_thread.name = 'hyperprobe-sync' if @sync_thread.respond_to?(:name=)
+
+      @flush_thread = Thread.new { flush_loop }
+      @flush_thread.name = 'hyperprobe-flush' if @flush_thread.respond_to?(:name=)
+
+      @stats_thread = Thread.new { stats_loop }
+      @stats_thread.name = 'hyperprobe-stats' if @stats_thread.respond_to?(:name=)
+    end
+
+    def sync_loop
+      until @is_shutdown
+        sleep @sync_interval_sec
+        break if @is_shutdown
+
+        begin
+          sync_with_broker
+        rescue StandardError => e
+          # Silently handle transient sync error
+        end
+      end
+    end
+
+    def sync_with_broker(timeout_sec = nil)
+      return if @is_shutdown
+
+      @log_broker.debug "sync_with_broker started #{timeout_sec ? "with timeout #{timeout_sec}" : ''}"
+      response = @broker_client.get_probes(timeout_sec)
+      return unless response
+
+      @log_broker.debug "sync_with_broker: got #{response.probes.length} probes from broker"
+
+      # Dynamic global config updates from broker
+      if response.global_config
+        gc = response.global_config
+        @mutex.synchronize do
+          @global_config[:redact_keys] = gc.redact_keys.to_a unless gc.redact_keys.empty?
+          @global_config[:redact_values] = gc.redact_values.to_a unless gc.redact_values.empty?
+          @global_config[:max_object_depth] = gc.max_object_depth if gc.max_object_depth.positive?
+          @global_config[:max_array_length] = gc.max_array_length if gc.max_array_length.positive?
+          @global_config[:stack_frame_depth] = gc.stack_frame_depth if gc.stack_frame_depth.positive?
+          @global_config[:max_object_properties] = gc.max_object_properties if gc.max_object_properties.positive?
+          @global_config[:max_string_length] = gc.max_string_length if gc.max_string_length.positive?
+        end
+        @engine.set_global_config(@global_config)
+      end
+
+      server_probes = response.probes.to_a
+      server_probe_ids = server_probes.map(&:id)
+
+      to_apply = []
+      now_ms = (Time.now.to_f * 1000).to_i
+
+      @mutex.synchronize do
+        # Clean stale local probes
+        @active_probes.delete_if { |pid, _| !server_probe_ids.include?(pid) }
+        @local_hits.delete_if { |pid, _| !server_probe_ids.include?(pid) }
+
+        server_probes.each do |probe|
+          hits = @local_hits[probe.id] || 0
+          is_expired = probe.expiry_time.positive? && probe.expiry_time <= now_ms
+
+          if hits < probe.hit_limit && !is_expired
+            to_apply << probe
+            @active_probes[probe.id] = probe
+          else
+            @active_probes.delete(probe.id)
+          end
+        end
+      end
+
+      @log_broker.debug "Found #{to_apply.length} active probes to apply locally"
+      @engine.set_probes(to_apply)
+      true
+    rescue StandardError => e
+      @log_broker.error("Failed to sync with broker: #{e.message}", e)
+      false
+    end
+
+    def flush_loop
+      until @is_shutdown
+        sleep @flush_interval_sec
+        break if @is_shutdown
+
+        begin
+          flush_telemetry
+        rescue StandardError => e
+          # Silently handle flush loop error
+        end
+      end
+    end
+
+    def flush_telemetry(timeout_sec = nil)
+      return if @is_shutdown || @telemetry_queue.empty?
+
+      batch = []
+      until @telemetry_queue.empty?
+        begin
+          batch << @telemetry_queue.pop(true)
+        rescue ThreadError
+          break
+        end
+      end
+
+      return if batch.empty?
+
+      @log_broker.info "Flushing #{batch.length} telemetry events to broker..."
+
+      begin
+        events = batch.map { |item| item[:event] }
+        finished_probe_ids = @broker_client.report_telemetry(events, timeout_sec)
+
+        @log_broker.info "Successfully flushed #{batch.length} telemetry events to broker"
+
+        # Commit bandwidth reservations
+        batch.each do |item|
+          item[:reservation]&.commit
+        end
+
+        # Handle globally finished probes
+        if finished_probe_ids && !finished_probe_ids.empty?
+          changed = false
+          @mutex.synchronize do
+            finished_probe_ids.each do |pid|
+              if @active_probes.key?(pid)
+                @active_probes.delete(pid)
+                changed = true
+              end
+            end
+          end
+          @engine.set_probes(@active_probes.values) if changed
+        end
+      rescue StandardError => e
+        @log_broker.error("Failed to flush telemetry: #{e.message}", e)
+        # On flush failure, re-queue events up to max capacity
+        batch.each do |item|
+          item[:reservation]&.release
+          if @telemetry_queue.size < @max_queue_size
+            @telemetry_queue.push(item)
+          end
+        end
+      end
+    end
+
+    def stats_loop
+      until @is_shutdown
+        sleep 5.0
+        break if @is_shutdown
+
+        begin
+          stats = @engine.get_stats
+          if stats[:hits].positive? || stats[:skips].positive?
+            @log_stats.info "Probes Hit: #{stats[:hits]}, Probes Skipped: #{stats[:skips]}"
+          end
+        rescue StandardError
+          # Ignore stats error
+        end
+      end
+    end
+
+    def handle_capture(event)
+      return if @is_shutdown || @is_agent_disabled
+
+      probe_id = event[:probe_id]
+      @log.debug "Captured event for probe #{probe_id}"
+      probe = nil
+      hits = 0
+
+      @mutex.synchronize do
+        probe = @active_probes[probe_id]
+        return unless probe
+
+        hits = (@local_hits[probe_id] || 0) + 1
+        @local_hits[probe_id] = hits
+      end
+
+      # Reserve bandwidth
+      event_size = @broker_client.estimate_event_size(event)
+      reservation = @quota_manager.reserve_bandwidth(event_size)
+      unless reservation
+        @log.debug "Bandwidth quota exceeded; dropping event for probe #{probe_id}"
+        return
+      end
+
+      # Admission to telemetry queue
+      item = { event: event, reservation: reservation }
+      if @telemetry_queue.size < @max_queue_size
+        @telemetry_queue.push(item)
+      else
+        @log.debug "Telemetry queue full. Dropping event for probe #{probe_id}"
+        reservation.release
+      end
+
+      # Enforce hitLimit fuse
+      hit_limit = probe.respond_to?(:hit_limit) ? probe.hit_limit : probe[:hit_limit]
+      if hits >= hit_limit
+        remaining_probes = nil
+        @mutex.synchronize do
+          @active_probes.delete(probe_id)
+          remaining_probes = @active_probes.values
+        end
+        @engine.set_probes(remaining_probes)
+      end
+    end
+
+    def handle_health_change(health, reason = nil)
+      return if @is_shutdown
+
+      case health
+      when Core::AgentHealth::RED
+        @log_safety.error "Safety Shield Triggered: RED Status. #{reason || ''}"
+        @engine.suspend
+
+        @cooldown_timer&.exit if @cooldown_timer&.alive?
+        cooldown_duration = @cooldown_sec
+        @cooldown_timer = Thread.new do
+          @log_safety.info "Cooldown period started (#{cooldown_duration}s)..."
+          sleep cooldown_duration
+          if @safety_monitor.get_health == Core::AgentHealth::GREEN
+            @log_safety.info "Cooldown period ended. Resuming instrumentation..."
+            @engine.resume
+          end
+        end
+      when Core::AgentHealth::YELLOW
+        @log_safety.warn "Safety Warning: YELLOW Status (Moderate Overhead). #{reason || ''}"
+      when Core::AgentHealth::GREEN
+        @log_safety.info "Status back to GREEN. #{reason || ''}"
+        if @engine.is_suspended && (!@cooldown_timer || !@cooldown_timer.alive?)
+          @engine.resume
+        end
+      end
+    end
+  end
+end