lex-tick 0.1.16 → 0.1.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94918234bd1b19854887b794867550d1a6252f74ea4ad10dd6009b6df2797c5b
-  data.tar.gz: df175d240f2a5816e9b7be4269aa12880051e1bbe5bdf6f761731cca585b0e10
+  metadata.gz: 86c832a54da11de90ede212d84cfd65a4fed13510e0d4cf7307e3127723fdaf9
+  data.tar.gz: 232d3c7e96e3f9c78d86e3452e2f50429a5c09eee1336643d87b39df5c06a5f2
 SHA512:
-  metadata.gz: 291b85fa4cfe572c00bb279026569c08691daf1233d7900ffe619e6c4f8d15b3cc9241d18f98aa8ef22715a0438a78a1239919181decf4463f8ab26e13c708cc
-  data.tar.gz: 56b3a74946173477cbd2d3d85a6b35ff15cc61472b9065bade72af63dcbdab5a8392ceaf50a54ca7e4397db01142cf6d4ee702786d60d938bbd7fa2ff541f954
+  metadata.gz: 8d8319d73e2fed107c41db9066436b169a469aa3315a1b1bbe08dab283544676711f310e82e537b6c6980cc95f3906043b1d85d308abac57ae10d9b3c4a45585
+  data.tar.gz: 89678c7b0ed29423b3267387f39666031237e0a5eedcd47e7fa033532c4a57db85640f94f839ea453f0f3a03520acec07393b495c80c8d5ff23be217d674f708

data/lib/legion/extensions/tick/client.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'legion/logging'
 require 'legion/extensions/tick/helpers/constants'
 require 'legion/extensions/tick/helpers/state'
 require 'legion/extensions/tick/runners/orchestrator'
@@ -8,6 +9,7 @@ module Legion
   module Extensions
     module Tick
       class Client
+        include Legion::Logging::Helper
         include Runners::Orchestrator
 
         def initialize(mode: :dormant, **)

data/lib/legion/extensions/tick/helpers/constants.rb

@@ -50,6 +50,13 @@ module Legion
             full_active:    PHASES
           }.freeze
 
+          # Only bounded, consumer-facing work belongs in the optional tick schedule.
+          OPTIONAL_PHASES = {
+            global_workspace: { mode: :full_active, after: :gut_instinct, requires: %i[sensory_processing].freeze }.freeze,
+            metacognition:    { mode: :full_active, after: :post_tick_reflection, requires: %i[post_tick_reflection].freeze }.freeze
+          }.freeze
+          INCOMPLETE_PHASE_STATUSES = %i[error failed failure timeout no_handler skipped deferred unavailable no_result].freeze
+
           # Timing constants (in seconds)
           ACTIVE_TIMEOUT                = 300    # seconds without high-salience signal before demotion
           SENTINEL_TIMEOUT              = 3600   # seconds without any signal before demotion to dormant
@@ -90,8 +97,26 @@ module Legion
 
           module_function
 
-          def phases_for_mode(mode)
-            MODE_PHASES.fetch(mode, PHASES)
+          def phases_for_mode(mode, enabled_optional_phases: [])
+            validate_optional_phases(enabled_optional_phases)
+            phases = MODE_PHASES.fetch(mode, PHASES)
+            return phases if enabled_optional_phases.empty?
+
+            phases.each_with_object([]) do |phase, scheduled|
+              scheduled << phase
+              OPTIONAL_PHASES.each do |optional, contract|
+                next unless enabled_optional_phases.include?(optional) && contract[:mode] == mode && contract[:after] == phase
+
+                scheduled << optional
+              end
+            end
+          end
+
+          def validate_optional_phases(phases)
+            raise ArgumentError, 'enabled_optional_phases must be an Array of phase symbols' unless phases.is_a?(Array)
+
+            unsupported = phases.reject { |phase| OPTIONAL_PHASES.key?(phase) }
+            raise ArgumentError, "unsupported optional phases: #{unsupported.inspect}" unless unsupported.empty?
           end
 
           def tick_budget(mode)

data/lib/legion/extensions/tick/helpers/state.rb

@@ -6,7 +6,7 @@ module Legion
       module Helpers
         class State
           attr_reader :mode, :tick_count, :last_signal_at, :last_high_salience_at, :last_dream_completed_at,
-                      :phase_results, :current_phase, :mode_history
+                      :last_dream_deferred_at, :phase_results, :current_phase, :mode_history
 
           def initialize(mode: :dormant)
             @mode = mode
@@ -14,6 +14,7 @@ module Legion
             @last_signal_at = nil
             @last_high_salience_at = nil
             @last_dream_completed_at = nil
+            @last_dream_deferred_at = nil
             @phase_results = {}
             @current_phase = nil
             @mode_history = [{ mode: mode, at: Time.now.utc }]
@@ -49,6 +50,10 @@ module Legion
             @last_dream_completed_at = Time.now.utc
           end
 
+          def record_dream_deferred
+            @last_dream_deferred_at = Time.now.utc
+          end
+
           def seconds_since_signal
             return 0.0 unless @last_signal_at
 
@@ -67,6 +72,12 @@ module Legion
             Time.now.utc - @last_dream_completed_at
           end
 
+          def seconds_since_dream_deferred
+            return Float::INFINITY unless @last_dream_deferred_at
+
+            Time.now.utc - @last_dream_deferred_at
+          end
+
           def to_h
             {
               mode:                    @mode,
@@ -75,6 +86,7 @@ module Legion
               last_signal_at:          @last_signal_at,
               last_high_salience_at:   @last_high_salience_at,
               last_dream_completed_at: @last_dream_completed_at,
+              last_dream_deferred_at:  @last_dream_deferred_at,
               phases_completed:        @phase_results.keys
             }
           end

data/lib/legion/extensions/tick/runners/orchestrator.rb

@@ -12,16 +12,19 @@ module Legion
             false
           end
 
-          def execute_tick(signals: [], phase_handlers: {}, **context)
+          def execute_tick(signals: [], phase_handlers: {}, enabled_optional_phases: [], **context)
+            Helpers::Constants.validate_optional_phases(enabled_optional_phases)
             if defined?(Legion::Telemetry::OpenInference)
               state = tick_state
               Legion::Telemetry::OpenInference.agent_span(
                 name: "tick-#{state.tick_count + 1}", mode: state.mode,
-                phase_count: Helpers::Constants.phases_for_mode(state.mode).size,
+                phase_count: Helpers::Constants.phases_for_mode(state.mode, enabled_optional_phases: enabled_optional_phases).size,
                 budget_ms: (Helpers::Constants.tick_budget(state.mode) * 1000).round
-              ) { |_span| execute_tick_impl(signals: signals, phase_handlers: phase_handlers, **context) }
+              ) do |_span|
+                execute_tick_impl(signals: signals, phase_handlers: phase_handlers, enabled_optional_phases: enabled_optional_phases, **context)
+              end
             else
-              execute_tick_impl(signals: signals, phase_handlers: phase_handlers, **context)
+              execute_tick_impl(signals: signals, phase_handlers: phase_handlers, enabled_optional_phases: enabled_optional_phases, **context)
             end
           end
 
@@ -42,7 +45,9 @@ module Legion
 
             new_mode = case state.mode
                        when :dormant
-                         if signals.any?
+                         if has_human || max_salience >= Helpers::Constants::HIGH_SALIENCE_THRESHOLD
+                           :full_active
+                         elsif signals.any?
                            :sentinel
                          elsif state.seconds_since_signal >= Helpers::Constants::DREAM_IDLE_THRESHOLD && dream_backoff_elapsed?(state)
                            :dormant_active
@@ -51,7 +56,7 @@ module Legion
                          end
                        when :dormant_active
                          if max_salience >= Helpers::Constants::HIGH_SALIENCE_THRESHOLD || has_human
-                           :sentinel
+                           :full_active
                          elsif dream_complete
                            state.record_dream_completed
                            :dormant
@@ -100,15 +105,14 @@ module Legion
 
             previous = tick_state.mode
             tick_state.transition_to(mode)
-            @mode_forced      = true
-            @force_expires_at = Time.now.utc + Helpers::Constants.tick_budget(mode).clamp(0, Helpers::Constants::MAX_TICK_DURATION)
-            log.info "[tick] mode forced: #{previous} -> #{mode} (protected until #{@force_expires_at})"
+            @mode_forced = true
+            log.info "[tick] mode forced: #{previous} -> #{mode}"
             { mode: mode }
           end
 
           private
 
-          def execute_tick_impl(signals:, phase_handlers:, **context)
+          def execute_tick_impl(signals:, phase_handlers:, enabled_optional_phases:, **context)
             state = tick_state
             state.increment_tick
 
@@ -122,15 +126,14 @@ module Legion
             # @mode_forced is set by set_mode and cleared here so the force lasts exactly one cycle.
             if @mode_forced
               log.debug "[tick] ##{state.tick_count} skipping mode evaluation (mode forced to #{state.mode})"
-              @mode_forced      = false
-              @force_expires_at = nil
+              @mode_forced = false
             else
               evaluate_mode_transition(signals: signals)
             end
 
-            phases = Helpers::Constants.phases_for_mode(state.mode)
+            phases = Helpers::Constants.phases_for_mode(state.mode, enabled_optional_phases: enabled_optional_phases)
             budget = Helpers::Constants.tick_budget(state.mode)
-            start_time = Time.now.utc
+            start_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
             ctx = {
               budget:         budget,
               start_time:     start_time,
@@ -141,18 +144,26 @@ module Legion
             results = run_phases(phases, state, ctx)
             finish_dream_cycle(state, phases, results)
 
-            total_elapsed = Time.now.utc - start_time
+            total_elapsed = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - start_time
             skipped = phases - results.keys
             log_tick_complete(state, results, phases, total_elapsed, skipped)
 
             {
-              tick_number:     state.tick_count,
-              mode:            state.mode,
-              phases_executed: results.keys,
-              phases_skipped:  skipped,
-              results:         results,
-              elapsed:         total_elapsed
+              tick_number:      state.tick_count,
+              mode:             state.mode,
+              phases_scheduled: phases,
+              phases_executed:  results.keys,
+              phases_skipped:   skipped,
+              results:          results,
+              elapsed:          total_elapsed
             }
+          rescue StandardError => e
+            log.error "[tick] execution failed: #{e.class}: #{e.message}"
+            if state.mode == :dormant_active
+              state.record_dream_deferred
+              state.transition_to(:dormant)
+            end
+            raise
           end
 
           def run_phases(phases, state, ctx)
@@ -161,7 +172,7 @@ module Legion
             start_time = ctx[:start_time]
             log.debug "[tick] ##{state.tick_count} running #{phases.size} phases with #{budget}s budget"
             phases.each do |phase|
-              elapsed = Time.now.utc - start_time
+              elapsed = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - start_time
               if elapsed >= budget
                 log.debug "[tick] ##{state.tick_count} budget exhausted at #{elapsed.round(3)}s, skipping remaining phases"
                 break
@@ -175,14 +186,35 @@ module Legion
           end
 
           def run_single_phase(phase, handler, state, signals, results, **context)
-            phase_start = Time.now.utc
-            result = handler ? handler.call(state: state, signals: signals, prior_results: results, **context) : { status: :no_handler }
-            phase_elapsed = ((Time.now.utc - phase_start) * 1000).round(1)
+            unavailable = optional_phase_unavailable(phase, handler, results)
+
+            phase_start = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+            result = unavailable || if handler
+                                      handler.call(state: state, signals: signals, prior_results: results, **context)
+                                    else
+                                      { status: :no_handler }
+                                    end
+            phase_elapsed = ((::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - phase_start) * 1000).round(1)
             status = result.is_a?(Hash) ? (result[:status] || :ok) : :ok
             log.debug "[tick] ##{state.tick_count} phase=#{phase} status=#{status} (#{phase_elapsed}ms)"
             result
           end
 
+          def optional_phase_unavailable(phase, handler, results)
+            contract = Helpers::Constants::OPTIONAL_PHASES[phase]
+            return unless contract
+            return { status: :unavailable, reason: :missing_handler } unless handler
+
+            missing = contract[:requires].select do |dependency|
+              result = results[dependency]
+              !result.is_a?(Hash) || result.empty? || result[:success] == false ||
+                Helpers::Constants::INCOMPLETE_PHASE_STATUSES.include?(result[:status])
+            end
+            return if missing.empty?
+
+            { status: :deferred, reason: :missing_prerequisites, phases: missing }
+          end
+
           def log_tick_complete(state, results, phases, total_elapsed, skipped)
             skipped_suffix = skipped.empty? ? '' : " skipped=#{skipped}"
             log.debug "[tick] ##{state.tick_count} complete | mode=#{state.mode} " \
@@ -196,19 +228,26 @@ module Legion
 
             skipped = phases - results.keys
             failed = failed_dream_phases(results)
-            state.record_dream_completed
             state.transition_to(:dormant)
             if skipped.empty? && failed.empty?
+              state.record_dream_completed
               log.info '[tick] dream cycle complete; backing off to dormant'
             else
+              state.record_dream_deferred
               log.info "[tick] dream cycle deferred; backing off to dormant skipped=#{skipped} failed=#{failed}"
             end
           end
 
           def failed_dream_phases(results)
             results.each_with_object([]) do |(phase, result), failed|
-              status = result.is_a?(Hash) ? result[:status] : nil
-              failed << phase if %i[error failed failure timeout].include?(status)
+              unless result.is_a?(Hash) && !result.empty?
+                failed << phase
+                next
+              end
+
+              status = result[:status]
+              incomplete = Helpers::Constants::INCOMPLETE_PHASE_STATUSES.include?(status)
+              failed << phase if incomplete || result[:success] == false
             end
           end
 
@@ -223,7 +262,8 @@ module Legion
           end
 
           def dream_backoff_elapsed?(state)
-            state.seconds_since_dream_completed >= Helpers::Constants::DREAM_BACKOFF_INTERVAL
+            state.seconds_since_dream_completed >= Helpers::Constants::DREAM_BACKOFF_INTERVAL &&
+              state.seconds_since_dream_deferred >= Helpers::Constants::DREAM_BACKOFF_INTERVAL
           end
 
           def tick_state

data/lib/legion/extensions/tick/version.rb

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Tick
-      VERSION = '0.1.16'
+      VERSION = '0.1.18'
     end
   end
 end

data/spec/legion/extensions/tick/client_spec.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'open3'
 require 'legion/extensions/tick/client'
 
 RSpec.describe Legion::Extensions::Tick::Client do
@@ -16,9 +17,18 @@ RSpec.describe Legion::Extensions::Tick::Client do
     expect(client.tick_status[:mode]).to eq(:sentinel)
   end
 
-  it 'runs a full active tick with all 16 phases' do
-    client = described_class.new(mode: :full_active)
-    result = client.execute_tick(signals: [{ salience: 0.9, source_type: :human_direct }])
-    expect(result[:phases_executed].size).to eq(16)
+  it 'executes standalone without the framework or its test helper supplying logging' do
+    script = <<~RUBY
+      require 'legion/extensions/tick/client'
+      result = Legion::Extensions::Tick::Client.new.execute_tick(
+        phase_handlers: { memory_consolidation: ->(**) { { consolidated: true } } }
+      )
+      abort 'consolidation did not execute' unless result.dig(:results, :memory_consolidation, :consolidated)
+      puts 'standalone consolidation completed'
+    RUBY
+    output, status = Open3.capture2e(RbConfig.ruby, '-Ilib', '-e', script)
+
+    expect(status.success?).to be(true), output
+    expect(output).to include('standalone consolidation completed')
   end
 end

data/spec/legion/extensions/tick/helpers/constants_spec.rb

@@ -12,11 +12,6 @@ RSpec.describe Legion::Extensions::Tick::Helpers::Constants do
       expect(phases.size).to eq(5)
       expect(phases).to include(:sensory_processing, :memory_retrieval)
     end
-
-    it 'returns all 16 phases for full_active' do
-      phases = described_class.phases_for_mode(:full_active)
-      expect(phases.size).to eq(16)
-    end
   end
 
   describe '.tick_budget' do
@@ -33,10 +28,6 @@ RSpec.describe Legion::Extensions::Tick::Helpers::Constants do
     end
   end
 
-  it 'defines exactly 16 phases' do
-    expect(described_class::PHASES.size).to eq(16)
-  end
-
   it 'defines phase budgets for all active phases' do
     described_class::PHASES.each do |phase|
       expect(described_class::PHASE_BUDGETS).to have_key(phase)
@@ -47,17 +38,9 @@ RSpec.describe Legion::Extensions::Tick::Helpers::Constants do
     it 'includes dormant_active' do
       expect(described_class::MODES).to include(:dormant_active)
     end
-
-    it 'has exactly 4 modes' do
-      expect(described_class::MODES.size).to eq(4)
-    end
   end
 
   describe 'DREAM_PHASES' do
-    it 'defines 10 dream phases' do
-      expect(described_class::DREAM_PHASES.size).to eq(10)
-    end
-
     it 'includes partner_reflection' do
       expect(described_class::DREAM_PHASES).to include(:partner_reflection)
     end
@@ -91,22 +74,4 @@ RSpec.describe Legion::Extensions::Tick::Helpers::Constants do
       expect(described_class.tick_budget(:dormant_active)).to eq(described_class::DREAM_TICK_BUDGET)
     end
   end
-
-  describe 'dream thresholds' do
-    it 'defines DREAM_IDLE_THRESHOLD as 1800' do
-      expect(described_class::DREAM_IDLE_THRESHOLD).to eq(1800)
-    end
-
-    it 'defines SENTINEL_TO_DREAM_THRESHOLD as 600' do
-      expect(described_class::SENTINEL_TO_DREAM_THRESHOLD).to eq(600)
-    end
-
-    it 'defines DREAM_BACKOFF_INTERVAL as 1800' do
-      expect(described_class::DREAM_BACKOFF_INTERVAL).to eq(1800)
-    end
-
-    it 'defines DREAM_TICK_BUDGET as finite' do
-      expect(described_class::DREAM_TICK_BUDGET).to eq(5.0)
-    end
-  end
 end

data/spec/legion/extensions/tick/runners/orchestrator_spec.rb

@@ -12,6 +12,10 @@ RSpec.describe Legion::Extensions::Tick::Runners::Orchestrator do
   end
 
   describe '#execute_tick' do
+    let(:dream_handlers) do
+      Legion::Extensions::Tick::Helpers::Constants::DREAM_PHASES.to_h { |phase| [phase, ->(**) { { status: :ok } }] }
+    end
+
     before do
       allow(client.send(:tick_state)).to receive(:seconds_since_signal).and_return(60.0)
     end
@@ -28,35 +32,6 @@ RSpec.describe Legion::Extensions::Tick::Runners::Orchestrator do
       expect(r2[:tick_number]).to eq(r1[:tick_number] + 1)
     end
 
-    it 'uses phase handlers when provided' do
-      handler_called = false
-      handlers = {
-        memory_consolidation: lambda { |**|
-          handler_called = true
-          { status: :ok }
-        }
-      }
-      client.execute_tick(phase_handlers: handlers)
-      expect(handler_called).to be true
-    end
-
-    it 'passes extra execution context through to phase handlers' do
-      seen = nil
-      handlers = {
-        memory_consolidation: lambda { |partner_observations: nil, **|
-          seen = partner_observations
-          { status: :ok }
-        }
-      }
-
-      client.execute_tick(
-        phase_handlers:       handlers,
-        partner_observations: [{ identity: 'partner-1' }]
-      )
-
-      expect(seen).to eq([{ identity: 'partner-1' }])
-    end
-
     it 'reports no_handler for unhandled phases' do
       result = client.execute_tick
       expect(result[:results][:memory_consolidation][:status]).to eq(:no_handler)
@@ -68,10 +43,46 @@ RSpec.describe Legion::Extensions::Tick::Runners::Orchestrator do
       expect(result[:mode]).to eq(:sentinel)
     end
 
+    it 'runs action selection for the first human signal without a second signal' do
+      result = client.execute_tick(
+        signals:        [{ source_type: :human_direct, salience: 0.1 }],
+        phase_handlers: { action_selection: ->(**) { { status: :selected } } }
+      )
+
+      expect(result[:mode]).to eq(:full_active)
+      expect(result[:results][:action_selection]).to eq(status: :selected)
+      expect(client.execute_tick[:mode]).to eq(:full_active)
+    end
+
+    it 'promotes a dormant agent immediately for a high-salience non-human signal' do
+      result = client.execute_tick(signals: [{ source_type: :sensor, salience: 0.9 }])
+
+      expect(result[:mode]).to eq(:full_active)
+      expect(result[:phases_executed]).to include(:action_selection)
+    end
+
+    it 'interrupts a dream with full processing for a low-salience human signal' do
+      dreaming_client = Legion::Extensions::Tick::Client.new(mode: :dormant_active)
+      result = dreaming_client.execute_tick(signals: [{ source_type: :human_direct, salience: 0.1 }])
+
+      expect(result[:mode]).to eq(:full_active)
+      expect(result[:phases_executed]).to include(:action_selection)
+      expect(result[:phases_executed]).not_to include(:dream_narration)
+      expect(dreaming_client.tick_status[:last_dream_completed_at]).to be_nil
+    end
+
+    it 'honors a forced mode for one tick before allowing human promotion' do
+      client.set_mode(mode: :sentinel)
+      signals = [{ source_type: :human_direct, salience: 0.1 }]
+
+      expect(client.execute_tick(signals: signals)[:phases_executed]).not_to include(:action_selection)
+      expect(client.execute_tick(signals: signals)[:phases_executed]).to include(:action_selection)
+    end
+
     it 'completes one dormant_active dream cycle and backs off to dormant' do
       client.set_mode(mode: :dormant_active)
 
-      result = client.execute_tick
+      result = client.execute_tick(phase_handlers: dream_handlers)
 
       expect(result[:phases_executed]).to eq(Legion::Extensions::Tick::Helpers::Constants::DREAM_PHASES)
       expect(result[:mode]).to eq(:dormant)
@@ -83,7 +94,7 @@ RSpec.describe Legion::Extensions::Tick::Runners::Orchestrator do
       allow(state).to receive(:seconds_since_signal).and_return(1801.0)
 
       client.set_mode(mode: :dormant_active)
-      client.execute_tick
+      client.execute_tick(phase_handlers: dream_handlers)
       result = client.execute_tick
 
       expect(result[:mode]).to eq(:dormant)
@@ -94,14 +105,13 @@ RSpec.describe Legion::Extensions::Tick::Runners::Orchestrator do
       client.set_mode(mode: :dormant_active)
 
       result = client.execute_tick(
-        phase_handlers: {
-          dream_narration: ->(**) { { status: :error } }
-        }
+        phase_handlers: dream_handlers.merge(dream_narration: ->(**) { { status: :error } })
       )
 
       expect(result[:mode]).to eq(:dormant)
       expect(result[:results][:dream_narration][:status]).to eq(:error)
-      expect(client.tick_status[:last_dream_completed_at]).not_to be_nil
+      expect(client.tick_status[:last_dream_completed_at]).to be_nil
+      expect(client.tick_status[:last_dream_deferred_at]).not_to be_nil
     end
 
     it 'backs off to dormant when the dream tick budget is exhausted before all phases run' do
@@ -115,12 +125,156 @@ RSpec.describe Legion::Extensions::Tick::Runners::Orchestrator do
       expect(result[:mode]).to eq(:dormant)
       expect(result[:phases_executed]).to be_empty
       expect(result[:phases_skipped]).to eq(constants::DREAM_PHASES)
-      expect(client.tick_status[:last_dream_completed_at]).not_to be_nil
+      expect(client.tick_status[:last_dream_completed_at]).to be_nil
+      expect(client.tick_status[:last_dream_deferred_at]).not_to be_nil
+    end
+
+    it 'backs off an unhandled dream without claiming completion' do
+      state = client.send(:tick_state)
+      allow(state).to receive(:seconds_since_signal).and_return(1801.0)
+      client.set_mode(mode: :dormant_active)
+
+      client.execute_tick
+      expect(client.tick_status[:last_dream_completed_at]).to be_nil
+      expect(client.execute_tick[:phases_executed]).to eq([:memory_consolidation])
+    end
+
+    it 'does not claim completion when a handler reports unsuccessful work without a status' do
+      client.set_mode(mode: :dormant_active)
+      client.execute_tick(phase_handlers: dream_handlers.merge(dream_narration: ->(**) { { success: false } }))
+
+      expect(client.tick_status[:last_dream_completed_at]).to be_nil
+      expect(client.tick_status[:last_dream_deferred_at]).not_to be_nil
+    end
+
+    it 'does not immediately replay earlier dream effects when a later handler raises' do
+      allow(client.send(:tick_state)).to receive(:seconds_since_signal).and_return(1801.0)
+      effects = []
+      handlers = dream_handlers.merge(
+        memory_audit:     ->(**) { effects << :audit },
+        association_walk: ->(**) { raise 'association failure' }
+      )
+      client.set_mode(mode: :dormant_active)
+
+      expect { client.execute_tick(phase_handlers: handlers) }.to raise_error('association failure')
+      expect(client.tick_status[:last_dream_completed_at]).to be_nil
+      client.execute_tick(phase_handlers: handlers)
+      expect(effects).to eq([:audit])
+    end
+
+    it 'keeps budget accounting independent of backwards wall-clock adjustments' do
+      allow(Time).to receive(:now).and_return(Time.utc(2026, 10, 29))
+      result = client.execute_tick(phase_handlers: {
+                                     memory_consolidation: lambda { |**|
+                                       allow(Time).to receive(:now).and_return(Time.utc(2026, 10, 28))
+                                       { status: :ok }
+                                     }
+                                   })
+
+      expect(result[:elapsed]).to be >= 0.0
+      expect(result[:elapsed]).to be < 1.0
+    end
+
+    it 'does not count an empty dream result as a completed cycle' do
+      client.set_mode(mode: :dormant_active)
+      client.execute_tick(phase_handlers: dream_handlers.merge(memory_audit: ->(**) {}))
+
+      expect(client.tick_status[:last_dream_completed_at]).to be_nil
+      expect(client.tick_status[:last_dream_deferred_at]).not_to be_nil
+    end
+  end
+
+  describe 'optional phase scheduling' do
+    let(:signals) { [{ source_type: :human_direct, salience: 0.1 }] }
+
+    it 'does not activate optional work merely because a handler is available' do
+      effects = []
+      client.execute_tick(signals: signals, phase_handlers: { metacognition: ->(**) { effects << :snapshot } })
+
+      expect(effects).to be_empty
+    end
+
+    it 'makes workspace selection available to the subsequent action decision' do
+      handlers = {
+        sensory_processing: ->(**) { { candidates: [{ content: 'urgent request', salience: 0.9 }] } },
+        global_workspace:   lambda { |prior_results:, **|
+          { selected: prior_results[:sensory_processing][:candidates].max_by { |candidate| candidate[:salience] } }
+        },
+        action_selection:   ->(prior_results:, **) { { decision: prior_results.dig(:global_workspace, :selected, :content) } }
+      }
+      result = client.execute_tick(signals: signals, phase_handlers: handlers, enabled_optional_phases: [:global_workspace])
+
+      expect(result.dig(:results, :action_selection, :decision)).to eq('urgent request')
+    end
+
+    it 'runs metacognition once after reflection even if the opt-in is repeated' do
+      observations = []
+      handlers = {
+        post_tick_reflection: ->(**) { { cognitive_health: 0.8 } },
+        metacognition:        lambda { |prior_results:, **|
+          observations << prior_results.dig(:post_tick_reflection, :cognitive_health)
+          { status: :completed }
+        }
+      }
+      client.execute_tick(signals: signals, phase_handlers: handlers, enabled_optional_phases: %i[metacognition metacognition])
+
+      expect(observations).to eq([0.8])
+    end
+
+    it 'does not run full-active optional work during a forced sentinel tick' do
+      effects = []
+      client.set_mode(mode: :sentinel)
+      result = client.execute_tick(signals: signals, enabled_optional_phases: [:metacognition],
+                                   phase_handlers: { metacognition: ->(**) { effects << :snapshot } })
+
+      expect(effects).to be_empty
+      expect(result[:phases_scheduled]).not_to include(:metacognition)
+    end
+
+    it 'reports an unavailable optional capability when its handler is absent' do
+      result = client.execute_tick(signals: signals, enabled_optional_phases: [:metacognition])
+
+      expect(result.dig(:results, :metacognition)).to include(status: :unavailable, reason: :missing_handler)
+    end
+
+    it 'defers optional work rather than consuming a failed prerequisite' do
+      effects = []
+      result = client.execute_tick(
+        signals: signals, enabled_optional_phases: [:metacognition],
+        phase_handlers: {
+          post_tick_reflection: ->(**) { { success: false } },
+          metacognition:        ->(**) { effects << :snapshot }
+        }
+      )
+
+      expect(effects).to be_empty
+      expect(result.dig(:results, :metacognition)).to include(status: :deferred, phases: [:post_tick_reflection])
+    end
+
+    it 'rejects unknown phase names before advancing tick state' do
+      expect { client.execute_tick(enabled_optional_phases: [:dream_cycle]) }.to raise_error(ArgumentError)
+      expect(client.tick_status[:tick_count]).to eq(0)
+    end
+
+    it 'rejects a scalar opt-in instead of silently ignoring it' do
+      expect { client.execute_tick(enabled_optional_phases: :metacognition) }.to raise_error(ArgumentError)
+      expect(client.tick_status[:tick_count]).to eq(0)
+    end
+
+    it 'reports budget-skipped optional work without invoking it' do
+      allow(Legion::Extensions::Tick::Helpers::Constants).to receive(:tick_budget).and_return(0.0)
+      effects = []
+      result = client.execute_tick(signals: signals, enabled_optional_phases: [:metacognition],
+                                   phase_handlers: { metacognition: ->(**) { effects << :snapshot } })
+
+      expect(effects).to be_empty
+      expect(result[:phases_skipped]).to include(:metacognition)
+      expect(result[:results]).not_to have_key(:metacognition)
     end
   end
 
   describe '#evaluate_mode_transition' do
-    it 'promotes dormant to sentinel on any signal' do
+    it 'promotes dormant to sentinel on a low-salience non-human signal' do
       result = client.evaluate_mode_transition(signals: [{ salience: 0.1 }])
       expect(result[:transitioned]).to be true
       expect(result[:new_mode]).to eq(:sentinel)
@@ -176,11 +330,11 @@ RSpec.describe Legion::Extensions::Tick::Runners::Orchestrator do
         expect(result[:new_mode]).to eq(:sentinel)
       end
 
-      it 'transitions dormant_active -> sentinel on high-salience signal' do
+      it 'transitions dormant_active -> full_active on high-salience signal' do
         client.set_mode(mode: :dormant_active)
         result = client.evaluate_mode_transition(signals: [{ salience: 0.9 }])
         expect(result[:transitioned]).to be true
-        expect(result[:new_mode]).to eq(:sentinel)
+        expect(result[:new_mode]).to eq(:full_active)
       end
 
       it 'transitions dormant_active -> dormant when dream_complete: true with no signals' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-tick
 version: !ruby/object:Gem::Version
-  version: 0.1.16
+  version: 0.1.18
 platform: ruby
 authors:
 - Esity