legion-gaia 0.9.38 → 0.9.44

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc703551ee34547621861ff669735ce602151be08dcddcfdf0d704aebcd1bb7f
-  data.tar.gz: 969f9fcf9510ec29b3eee6d0dc1d691d0836528367dbb352074ec0a9b1b9b423
+  metadata.gz: 162def8c335c98ed023f01a4a3a091cc9e6e43a4f965827b2b76b25ea09bbace
+  data.tar.gz: cb877734f54f0b877d74489071f46d06b108ebbb555e754fb920f901de27d5c4
 SHA512:
-  metadata.gz: c134c1b4d190ec7dd315e2c6a734254a3002f60b104f1d6f291cfecab3125bc9cc38d62b5937e10e1e06b0e0313df3a3031b47a640eee363cc30e9a5db06947d
-  data.tar.gz: f46a86969d2d6c16a5b204b08929cb3ddf86b53ca27a42414c1c657487163a0cc0cbdbb7d6f90368402a8b0be09eb9595ee54d3e1b3192bcc81e065897633fd4
+  metadata.gz: aa7c57507b415ff8ad3b7c1136c4c4180bc760082c21850606af1bb3910bea3422bad9af239b4c7a7ccda0b644e3cd6bfc8ea0a948020508786c71bbe572470a
+  data.tar.gz: 5d357170e157577b45eb834496ebc5822c290a063fb5eb6bc235238fbeec38b4609a58268d123478c356cbf7a8865216406f12f456cc244a447959b1fab4ab66

data/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 ## [Unreleased]
 
+## [0.9.44] - 2026-04-02
+
+### Fixed
+- Route Teams webhook traffic through `Legion::Gaia.ingest` so webhook-delivered frames use normal signal normalization, session tracking, and interlocutor observation instead of pushing raw frames into the sensory buffer
+
+## [0.9.43] - 2026-04-02
+
+### Fixed
+- Preserve undelivered proactive intents when pending dispatch stops mid-drain, prevent failed sends from consuming proactive quota, and fail partner-directed dispatches when no partner channel can be resolved
+
+## [0.9.42] - 2026-04-02
+
+### Fixed
+- Keep trackers dirty when Apollo persistence returns a failed upsert response, and avoid advancing the flush timestamp for unsuccessful tracker flushes
+- Refresh repo docs to match the current GAIA version and the 25-phase wiring layout
+
+## [0.9.41] - 2026-04-02
+
+### Fixed
+- Normalize `RouterBridge#route_outbound` delivery results so adapter-reported error hashes remain undelivered instead of being wrapped as successful outbound delivery
+
+## [0.9.40] - 2026-04-02
+
+### Fixed
+- Preserve actual proactive delivery outcomes: `send_message`, `send_to_user`, and `start_conversation` now return failure when adapter or registry delivery reports failure instead of always reporting success
+- Include explicit per-channel `:no_adapter` failures in `send_notification` fanout results instead of silently skipping requested channels
+- Propagate adapter delivery errors through `ChannelRegistry#deliver` so upstream callers can report real delivery outcomes
+
+## [0.9.39] - 2026-04-02
+
+### Added
+- Partner-absence signal queuing: queues an ambient `InputFrame` when `partner_absence_misses` exceeds `ABSENCE_SIGNAL_THRESHOLD` (5), with a 30-minute cooldown (`ABSENCE_SIGNAL_COOLDOWN`) and salience 0.75 to prevent signal flood
+
+### Changed
+- Switch non-API GAIA library logging to `Legion::Logging::Helper`, replacing direct `Legion::Logging.*` calls and legacy `log_*` wrappers with helper-backed `log`
+- Expand `info`, `debug`, and `error` coverage across GAIA runtime booting, routing, proactive delivery, trackers, adapters, and workflow transitions
+- `PhaseWiring` `memory_retrieval` and `prediction_engine` now return `{ skip: true, reason: :idle_no_signals }` when the signals array is empty, skipping expensive phase execution on idle ticks
+- `PhaseWiring` `knowledge_retrieval` now reads `signal[:value]` before falling back to `signal[:content]` for the query text
+- `PhaseWiring` result normalization: `partner_observations` extracted via `partner_observations_from(ctx)` helper instead of direct `ctx.dig` to normalize observation shape
+
+### Fixed
+- Route rescued GAIA library exceptions through `handle_exception` so failures are captured consistently with operation context
+- Update GAIA logging specs to support helper-backed tagged logging and keep the full suite green after the logging uplift
+
 ## [0.9.38] - 2026-04-01
 
 ### Fixed

data/CLAUDE.md

@@ -3,7 +3,7 @@
 **Repository Level 3 Documentation**
 - **Parent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
 - **GitHub**: https://github.com/LegionIO/legion-gaia
-- **Version**: 0.9.26
+- **Version**: 0.9.44
 
 ## Purpose
 

data/README.md

@@ -2,7 +2,7 @@
 
 Cognitive coordination layer for the LegionIO framework. GAIA is the mind that inhabits the Legion body.
 
-**Version**: 0.9.26
+**Version**: 0.9.44
 
 GAIA sits on top of LegionIO's infrastructure and coordinates all agentic subordinate functions. It drives the tick cycle, manages extension discovery and wiring, and provides the channel abstraction for multi-interface communication.
 
@@ -23,7 +23,7 @@ Legion::Gaia.ingest                      OutputRouter -> NotificationGate -> Ren
     v                                        |
 SensoryBuffer -----> Heartbeat (1s) --> Cognitive Pipeline
                          |
-                    PhaseWiring (24 phases)
+                    PhaseWiring (25 phases)
                          |
                     Registry -> RunnerHost(s)
                          |
@@ -102,11 +102,11 @@ gaia:
 
 ## Cognitive Phases
 
-GAIA wires 24 phases across two cycles:
+GAIA wires 25 phases across two cycles:
 
 **Active Tick (16 phases):** sensory processing, emotional evaluation, memory retrieval, knowledge retrieval, identity entropy check, working memory integration, procedural check, prediction engine, mesh interface, social cognition, theory of mind, gut instinct, action selection, memory consolidation, homeostasis regulation, post-tick reflection.
 
-**Dream Cycle (8 phases):** memory audit, association walk, contradiction resolution, agenda formation, consolidation commit, knowledge promotion, dream reflection, dream narration.
+**Dream Cycle (9 phases):** memory audit, association walk, contradiction resolution, agenda formation, consolidation commit, knowledge promotion, dream reflection, partner reflection, dream narration.
 
 ## Channel Adapters
 

data/legion-gaia.gemspec

@@ -28,7 +28,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency 'base64'
   spec.add_dependency 'legion-json', '>= 1.2.0'
-  spec.add_dependency 'legion-logging', '>= 1.2.8'
+  spec.add_dependency 'legion-logging', '>= 1.5.0'
   spec.add_dependency 'legion-settings', '>= 1.3.12'
   spec.add_dependency 'openssl'
 

data/lib/legion/gaia/advisory.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
+require 'legion/logging/helper'
+
 module Legion
   module Gaia
     module Advisory
+      extend Legion::Logging::Helper
+
       module_function
 
       # Fast in-memory advisory. NEVER makes LLM calls.
@@ -15,9 +19,13 @@ module Legion
         advisory[:valence] = Gaia.last_valences if Gaia.last_valences
         merge_tick_data!(advisory, Gaia.registry&.tick_host&.last_tick_result)
         merge_observer_data!(advisory, caller)
-        advisory.compact
+        result = advisory.compact
+        if result.any?
+          log.info("GAIA advisory generated conversation_id=#{conversation_id} keys=#{result.keys.join(',')}")
+        end
+        result
       rescue StandardError => e
-        Legion::Logging.warn("GAIA advisory failed: #{e.message}") if defined?(Legion::Logging)
+        handle_exception(e, level: :warn, operation: 'gaia.advisory.advise', conversation_id: conversation_id)
         nil
       end
 

data/lib/legion/gaia/audit_observer.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 require 'singleton'
+require 'legion/logging/helper'
 
 module Legion
   module Gaia
     class AuditObserver
       include Singleton
+      include Legion::Logging::Helper
 
       def initialize
         @user_prefs = {}
@@ -22,8 +24,13 @@ module Legion
           record_tool_patterns(event)
           record_quality(event)
         end
+        identity = event.dig(:caller, :requested_by, :identity)
+        log.debug(
+          'AuditObserver processed event ' \
+          "identity=#{identity || 'unknown'} tools=#{Array(event[:tools_used]).size}"
+        )
       rescue StandardError => e
-        Legion::Logging.warn("audit observer error: #{e.message}") if defined?(Legion::Logging)
+        handle_exception(e, level: :warn, operation: 'gaia.audit_observer.process_event')
       end
 
       def user_preferences(identity)

data/lib/legion/gaia/bond_registry.rb

@@ -1,14 +1,19 @@
 # frozen_string_literal: true
 
+require 'legion/logging/helper'
+
 module Legion
   module Gaia
     module BondRegistry
+      extend Legion::Logging::Helper
+
       module_function
 
       def register(identity, role:, priority: :normal)
         @bonds ||= {}
         @bonds[identity.to_s] = { identity: identity.to_s, role: role.to_sym, priority: priority.to_sym,
                                   since: Time.now.utc }
+        log.info("BondRegistry registered identity=#{identity} role=#{role} priority=#{priority}")
       end
 
       def partner?(identity)
@@ -41,12 +46,14 @@ module Legion
 
           identities.each { |id| register(id, role: :partner, priority: priority) }
         end
+        log.info("BondRegistry hydrated entries=#{result[:results].size}")
       rescue StandardError => e
-        Legion::Logging.warn "BondRegistry hydration failed: #{e.message}" if defined?(Legion::Logging)
+        handle_exception(e, level: :warn, operation: 'gaia.bond_registry.hydrate_from_apollo')
       end
 
       def reset!
         @bonds = {}
+        log.debug('BondRegistry reset')
       end
 
       def extract_identity_keys(content)

data/lib/legion/gaia/channel_registry.rb

@@ -40,12 +40,13 @@ module Legion
 
       def deliver(output_frame)
         adapter = adapter_for(output_frame.channel_id)
-        return { delivered: false, reason: :no_adapter } unless adapter
-        return { delivered: false, reason: :adapter_stopped } unless adapter.started?
+        return { delivered: false, reason: :no_adapter, channel_id: output_frame.channel_id } unless adapter
+        unless adapter.started?
+          return { delivered: false, reason: :adapter_stopped, channel_id: output_frame.channel_id }
+        end
 
         rendered = adapter.translate_outbound(output_frame)
-        adapter.deliver(rendered)
-        { delivered: true, channel_id: output_frame.channel_id }
+        normalize_delivery_result(adapter.deliver(rendered), channel_id: output_frame.channel_id)
       end
 
       def start_all
@@ -55,6 +56,19 @@ module Legion
       def stop_all
         @mutex.synchronize { @adapters.each_value(&:stop) }
       end
+
+      private
+
+      def normalize_delivery_result(result, channel_id:)
+        return { delivered: false, reason: :adapter_returned_false, channel_id: channel_id } if result == false
+        return { delivered: true, channel_id: channel_id } unless result.is_a?(Hash)
+
+        normalized = result.dup
+        normalized[:channel_id] ||= channel_id
+        normalized[:delivered] = false if normalized[:error] && !normalized.key?(:delivered)
+        normalized[:delivered] = true unless normalized.key?(:delivered)
+        normalized
+      end
     end
   end
 end

data/lib/legion/gaia/channels/slack_adapter.rb

@@ -3,12 +3,15 @@
 require 'json'
 require 'net/http'
 require 'uri'
+require 'legion/logging/helper'
 require_relative 'slack/signing_verifier'
 
 module Legion
   module Gaia
     module Channels
       class SlackAdapter < ChannelAdapter
+        include Legion::Logging::Helper
+
         CAPABILITIES = %i[rich_text threads reactions mentions file_attachment].freeze
 
         attr_reader :signing_secret, :bot_token
@@ -58,6 +61,10 @@ module Legion
 
         def deliver(rendered_content, webhook: nil)
           target_webhook = webhook || @default_webhook
+          log.info(
+            'SlackAdapter delivering ' \
+            "mode=#{@bot_token && !target_webhook ? 'api' : 'webhook'} channel=#{channel_id}"
+          )
           return deliver_via_api(rendered_content) if @bot_token && !target_webhook
 
           deliver_via_webhook(rendered_content, target_webhook)
@@ -72,6 +79,7 @@ module Legion
 
           channel = dm_result[:channel_id]
           rendered = translate_outbound(output_frame).merge(channel: channel)
+          log.info("SlackAdapter proactive delivery user_id=#{user_id} channel=#{channel}")
           deliver_via_api_to_channel(rendered)
         end
 
@@ -85,9 +93,11 @@ module Legion
           )
           return result if result.is_a?(Hash) && result[:error]
 
-          { channel_id: result[:channel_id] || result['channel']&.dig('id') || result['channel'] }
+          channel_id = result[:channel_id] || result['channel']&.dig('id') || result['channel']
+          log.info("SlackAdapter opened DM user_id=#{user_id} channel=#{channel_id}")
+          { channel_id: channel_id }
         rescue StandardError => e
-          Legion::Logging.warn("SlackAdapter open_dm failed: #{e.message}") if defined?(Legion::Logging)
+          handle_exception(e, level: :warn, operation: 'gaia.channels.slack_adapter.open_dm', user_id: user_id)
           { error: :open_dm_failed, message: e.message }
         end
 
@@ -122,11 +132,13 @@ module Legion
 
         def deliver_via_webhook(content, webhook)
           unless slack_runner_available?
+            log.error('SlackAdapter deliver_via_webhook failed error=slack_runner_not_available')
             return { error: :slack_runner_not_available,
                      message: 'lex-slack Chat runner not loaded' }
           end
 
           message = content.is_a?(Hash) ? content[:text] : content.to_s
+          log.info("SlackAdapter delivering via webhook message_length=#{message.length}")
           Legion::Extensions::Slack::Runners::Chat.send(message: message, webhook: webhook)
         end
 
@@ -137,6 +149,8 @@ module Legion
           channel = (content.is_a?(Hash) && content[:channel]) || @channel_id.to_s
           post_to_slack_api(channel: channel, text: text)
         rescue StandardError => e
+          handle_exception(e, level: :warn, operation: 'gaia.channels.slack_adapter.deliver_via_api',
+                              channel: channel)
           { error: :network_error, message: e.message }
         end
 
@@ -154,22 +168,28 @@ module Legion
           parsed = ::JSON.parse(response.body, symbolize_names: true)
 
           if parsed[:ok]
+            log.info("SlackAdapter delivered via API channel=#{channel}")
             { delivered: true, ts: parsed[:ts] }
           else
+            log.error("SlackAdapter API delivery failed channel=#{channel} error=#{parsed[:error] || :unknown_error}")
             { error: parsed[:error] || :unknown_error }
           end
         rescue StandardError => e
+          handle_exception(e, level: :warn, operation: 'gaia.channels.slack_adapter.post_to_slack_api',
+                              channel: channel)
           { error: :network_error, message: e.message }
         end
 
         def deliver_via_api_to_channel(content)
           unless slack_runner_available?
+            log.error('SlackAdapter deliver_via_api_to_channel failed error=slack_runner_not_available')
             return { error: :slack_runner_not_available,
                      message: 'lex-slack Chat runner not loaded' }
           end
 
           message = content.is_a?(Hash) ? content[:text] : content.to_s
           channel = content.is_a?(Hash) ? content[:channel] : nil
+          log.info("SlackAdapter sending proactive API message channel=#{channel}")
           Legion::Extensions::Slack::Runners::Chat.send(
             message: message,
             channel: channel,

data/lib/legion/gaia/channels/teams/bot_framework_auth.rb

@@ -4,12 +4,15 @@ require 'net/http'
 require 'uri'
 require 'openssl'
 require 'base64'
+require 'legion/logging/helper'
 
 module Legion
   module Gaia
     module Channels
       module Teams
         module BotFrameworkAuth
+          extend Legion::Logging::Helper
+
           OPENID_METADATA_URL = 'https://login.botframework.com/v1/.well-known/openidconfiguration'
           BOT_FRAMEWORK_ISSUER = 'https://api.botframework.com'
           EMULATOR_ISSUER = 'https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/'
@@ -66,9 +69,7 @@ module Legion
             decoded = Base64.urlsafe_decode64(padded)
             ::JSON.parse(decoded)
           rescue StandardError => e
-            if defined?(Legion::Logging)
-              Legion::Logging.debug("BotFrameworkAuth JWT segment decode failed: #{e.message}")
-            end
+            handle_exception(e, level: :debug, operation: 'gaia.channels.teams.bot_framework_auth.decode_jwt_segment')
             nil
           end
 

data/lib/legion/gaia/channels/teams/webhook_handler.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
+require 'legion/logging/helper'
+
 module Legion
   module Gaia
     module Channels
       module Teams
         class WebhookHandler
+          include Legion::Logging::Helper
+
           attr_reader :adapter
 
           def initialize(adapter)
@@ -22,6 +26,7 @@ module Legion
             end
 
             activity_type = activity['type'] || activity[:type]
+            log.info("WebhookHandler received activity_type=#{activity_type}")
             case activity_type
             when 'message' then handle_message(activity)
             when 'conversationUpdate' then handle_conversation_update(activity)
@@ -37,6 +42,7 @@ module Legion
             return error_response(:translate_failed, 'Could not translate activity') unless frame
 
             Legion::Gaia.ingest(frame) if Legion::Gaia.respond_to?(:ingest)
+            log.info("WebhookHandler ingested frame_id=#{frame.id}")
             success_response(:message_ingested, frame.id)
           end
 
@@ -68,7 +74,7 @@ module Legion
 
             ::JSON.parse(body)
           rescue StandardError => e
-            Legion::Logging.debug("WebhookHandler activity parse failed: #{e.message}") if defined?(Legion::Logging)
+            handle_exception(e, level: :debug, operation: 'gaia.channels.teams.webhook_handler.parse_activity')
             nil
           end
 

data/lib/legion/gaia/channels/teams_adapter.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'legion/logging/helper'
 require_relative 'teams/bot_framework_auth'
 require_relative 'teams/conversation_store'
 require_relative 'teams/webhook_handler'
@@ -8,6 +9,8 @@ module Legion
   module Gaia
     module Channels
       class TeamsAdapter < ChannelAdapter
+        include Legion::Logging::Helper
+
         CAPABILITIES = %i[rich_text adaptive_cards proactive_messaging mobile desktop mentions].freeze
         MOBILE_CAPABILITIES = %i[rich_text adaptive_cards mobile mentions].freeze
         DESKTOP_CAPABILITIES = %i[rich_text adaptive_cards desktop mentions file_attachment].freeze
@@ -33,6 +36,7 @@ module Legion
 
         def update_presence_status(status)
           @last_presence_status = status
+          log.info("TeamsAdapter presence updated status=#{status}")
         end
 
         def translate_inbound(activity)
@@ -44,6 +48,7 @@ module Legion
           text = strip_mention(text, activity)
 
           conversation_store.store_from_activity(activity)
+          log.debug("TeamsAdapter translated inbound activity_id=#{activity['id'] || activity[:id]}")
 
           InputFrame.new(
             content: text.strip,
@@ -75,8 +80,12 @@ module Legion
         def deliver(rendered_content, conversation_id: nil)
           resolved_id = conversation_id || @default_conversation_id
           ref = resolved_id && conversation_store.lookup(resolved_id)
-          return { error: :no_conversation_reference } unless ref
+          unless ref
+            log.error("TeamsAdapter deliver failed conversation_id=#{resolved_id} error=no_conversation_reference")
+            return { error: :no_conversation_reference }
+          end
 
+          log.info("TeamsAdapter delivering conversation_id=#{ref.conversation_id}")
           deliver_via_bot(rendered_content, ref)
         end
 
@@ -88,6 +97,7 @@ module Legion
           return conversation_id if conversation_id.is_a?(Hash) && conversation_id[:error]
 
           rendered = translate_outbound(output_frame)
+          log.info("TeamsAdapter proactive delivery user_id=#{user_id} conversation_id=#{conversation_id}")
           deliver(rendered, conversation_id: conversation_id)
         end
 
@@ -113,11 +123,11 @@ module Legion
             service_url: service_url,
             tenant_id: resolved_tenant
           )
+          log.info("TeamsAdapter created proactive conversation user_id=#{user_id} conversation_id=#{conversation_id}")
           conversation_id
         rescue StandardError => e
-          if defined?(Legion::Logging)
-            Legion::Logging.warn("TeamsAdapter create_proactive_conversation failed: #{e.message}")
-          end
+          handle_exception(e, level: :warn, operation: 'gaia.channels.teams_adapter.create_proactive_conversation',
+                              user_id: user_id, tenant_id: resolved_tenant)
           { error: :create_conversation_failed, message: e.message }
         end
 
@@ -187,16 +197,19 @@ module Legion
 
         def deliver_via_bot(rendered_content, ref)
           unless bot_runner_available?
+            log.error('TeamsAdapter deliver_via_bot failed error=bot_runner_not_available')
             return { error: :bot_runner_not_available,
                      message: 'lex-microsoft_teams Bot runner not loaded' }
           end
 
           bot = Legion::Extensions::MicrosoftTeams::Client.new
           if rendered_content.is_a?(Hash) && rendered_content[:type] == 'adaptive_card'
+            log.info("TeamsAdapter sending adaptive card conversation_id=#{ref.conversation_id}")
             bot.send_card(service_url: ref.service_url, conversation_id: ref.conversation_id,
                           card: rendered_content[:card])
           else
             text = rendered_content.is_a?(Hash) ? rendered_content[:text] : rendered_content.to_s
+            log.info("TeamsAdapter sending text conversation_id=#{ref.conversation_id}")
             bot.send_text(service_url: ref.service_url, conversation_id: ref.conversation_id,
                           text: text)
           end
@@ -208,7 +221,13 @@ module Legion
 
         def resolve_proactive_conversation(user_id)
           existing = conversation_store.conversations_for_user(user_id)
-          return existing.first.conversation_id unless existing.empty?
+          unless existing.empty?
+            log.debug(
+              'TeamsAdapter reused proactive conversation ' \
+              "user_id=#{user_id} conversation_id=#{existing.first.conversation_id}"
+            )
+            return existing.first.conversation_id
+          end
 
           create_proactive_conversation(user_id: user_id)
         end

data/lib/legion/gaia/logging.rb

@@ -1,21 +1,11 @@
 # frozen_string_literal: true
 
+require 'legion/logging/helper'
+
 module Legion
   module Gaia
     module Logging
-      private
-
-      def log_debug(msg)
-        Legion::Logging.debug(msg) if Legion.const_defined?(:Logging, false)
-      end
-
-      def log_info(msg)
-        Legion::Logging.info(msg) if Legion.const_defined?(:Logging, false)
-      end
-
-      def log_warn(msg)
-        Legion::Logging.warn(msg) if Legion.const_defined?(:Logging, false)
-      end
+      include Legion::Logging::Helper
     end
   end
 end

data/lib/legion/gaia/notification_gate/schedule_evaluator.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
+require 'legion/logging/helper'
+
 module Legion
   module Gaia
     class NotificationGate
       class ScheduleEvaluator
+        include Legion::Logging::Helper
+
         DAY_NAMES = %w[sun mon tue wed thu fri sat].freeze
 
         # Standard (non-DST) offsets for known IANA zone names.
@@ -104,7 +108,9 @@ module Legion
           abs_h = hours.abs.to_i
           abs_m = ((hours.abs % 1) * 60).round
           format('%<sign>s%<h>02d:%<m>02d', sign: sign, h: abs_h, m: abs_m)
-        rescue StandardError
+        rescue StandardError => e
+          handle_exception(e, level: :debug, operation: 'gaia.notification_gate.schedule_evaluator.tzinfo_offset',
+                              timezone: timezone)
           nil
         end
 

data/lib/legion/gaia/offline_handler.rb

@@ -1,14 +1,22 @@
 # frozen_string_literal: true
 
+require 'legion/logging/helper'
+
 module Legion
   module Gaia
     module OfflineHandler
+      extend Legion::Logging::Helper
+
       DEFAULT_OFFLINE_MESSAGE = 'The agent is currently offline. Your message has been queued.'
 
       class << self
         def handle_offline_delivery(input_frame, worker_id:)
           queue_message(input_frame, worker_id)
           notify_sender(input_frame)
+          log.info(
+            'OfflineHandler queued ' \
+            "frame_id=#{input_frame.respond_to?(:id) ? input_frame.id : 'unknown'} worker_id=#{worker_id}"
+          )
           { queued: true, worker_id: worker_id }
         end
 
@@ -21,6 +29,7 @@ module Legion
 
         def record_presence(worker_id)
           presence_store[worker_id] = { last_seen: Time.now }
+          log.debug("OfflineHandler recorded presence worker_id=#{worker_id}")
         end
 
         def pending_count(worker_id)
@@ -28,7 +37,9 @@ module Legion
         end
 
         def drain_pending(worker_id)
-          pending_store.delete(worker_id) || []
+          drained = pending_store.delete(worker_id) || []
+          log.info("OfflineHandler drained pending worker_id=#{worker_id} count=#{drained.size}") if drained.any?
+          drained
         end
 
         def reset!
@@ -56,8 +67,10 @@ module Legion
             session_continuity_id: frame.respond_to?(:session_continuity_id) ? frame.session_continuity_id : nil
           )
           registry.deliver(output)
+          log.info("OfflineHandler notified sender frame_id=#{output.id} channel=#{frame.channel_id}")
         rescue StandardError => e
-          Legion::Logging.warn("OfflineHandler notify_sender failed: #{e.message}") if defined?(Legion::Logging)
+          handle_exception(e, level: :warn, operation: 'gaia.offline_handler.notify_sender',
+                              channel_id: frame.respond_to?(:channel_id) ? frame.channel_id : nil)
           nil
         end
 
@@ -68,9 +81,7 @@ module Legion
             60
           end
         rescue StandardError => e
-          if defined?(Legion::Logging)
-            Legion::Logging.debug("OfflineHandler offline_threshold settings unavailable, using default: #{e.message}")
-          end
+          handle_exception(e, level: :debug, operation: 'gaia.offline_handler.offline_threshold')
           60
         end