rubik 0.1.0

data/lib/rubik/orchestrator/shell_deps.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Orchestrator
+    # Narrow façade over Loop for the extracted collaborators (Plan 87 E-1,
+    # carrying Plan 86 D-5). Collaborators reach loop-held state only through
+    # this object instead of poking `@loop` directly (Law of Demeter).
+    #
+    # Design notes:
+    # - Reads are forwarded, not re-declared: capability queries such as
+    #   `deps.respond_to?(:safe_config)` must keep the exact semantics the
+    #   collaborators rely on with minimal test doubles (some doubles do not
+    #   define every accessor), so the surface is forwarded through
+    #   respond_to_missing?/method_missing guarded by the declared SURFACE.
+    # - Writes are an explicit command surface: history rebinding and the
+    #   counter/flag mutations become named methods instead of leaking
+    #   Loop's attr_accessors.
+    # - `loop_instance` exists for the turn-result contract only: result
+    #   hashes carry the loop object itself so the shell can drive
+    #   `continue_loop` afterwards.
+    class ShellDeps
+      # Read surface: symbols collaborators consume from Loop at call time.
+      SURFACE = [
+        :history, :activity, :config, :shell, :buffer_manager, :lsp_manager,
+        :tool_registry, :provider, :budget_manager, :on_step,
+        :step_count, :max_steps, :warn_at_ratio, :context_limit, :max_output_tokens,
+        :total_tokens, :invalid_tool_count, :last_turn_streamed,
+        :context_warning_emitted, :safe_config,
+        :goal_mode?, :goal_wait, :subagent_notice_inbox, :runtime_manager
+      ].freeze
+
+      # Collaborator constructor shim: accepts an already-built façade or a
+      # bare loop (test doubles) and wraps the latter.
+      def self.wrap(loop_or_deps)
+        loop_or_deps.is_a?(ShellDeps) ? loop_or_deps : ShellDeps.new(loop_or_deps)
+      end
+
+      def initialize(loop)
+        @loop = loop
+      end
+
+      # Turn-result contract (see class comment): the underlying Loop object.
+      def loop_instance
+        @loop
+      end
+
+      # ── Command surface ───────────────────────────────────────────────
+      # compact_history is pure and returns a new array, so the history
+      # reference itself must be rebound on Loop (BudgetManager compaction).
+      def replace_history!(new_history)
+        @loop.history = new_history
+      end
+
+      def reset_invalid_tools!
+        @loop.invalid_tool_count = 0
+      end
+
+      def record_invalid_tool!
+        @loop.invalid_tool_count += 1
+      end
+
+      def mark_last_turn_streamed!(streamed)
+        @loop.last_turn_streamed = streamed
+      end
+
+      def flag_context_warning!
+        @loop.context_warning_emitted = true
+      end
+
+      def emergency_compact_and_notify!(reason)
+        @loop.emergency_compact_and_notify!(reason)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        (SURFACE.include?(name) && @loop.respond_to?(name, include_private)) || super
+      end
+
+      def method_missing(name, *, &)
+        return @loop.public_send(name, *, &) if SURFACE.include?(name) && @loop.respond_to?(name)
+
+        super
+      end
+    end
+  end
+end

data/lib/rubik/orchestrator/step_executor.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+require_relative "finish_message_selector"
+require_relative "auto_apply"
+require_relative "tool_call_id"
+require_relative "tool_history"
+require_relative "tool_circuit_breaker"
+require_relative "maestro_gate"
+require_relative "lsp_feedback"
+
+module Rubik
+  module Orchestrator
+    # Dispatches a single normalized tool call against the registry (Plan 54
+    # D-6). The executor is a stateless collaborator: every piece of loop
+    # state (history, counters, shell wiring, streamed flag) physically stays
+    # on Loop and is reached through the ShellDeps façade (Plan 87 E-1), so
+    # send-based tests and the res[:streamed] contract keep working unchanged.
+    class StepExecutor
+      include MaestroGate
+
+      ERROR_PREFIXES = [
+        "-- ",
+        "Error:",
+        "Error ",
+        "Usage:",
+        "Pre-flight verification failed",
+        "Bilinmeyen komut",
+        "Failed",
+        "Security blocked",
+        "Command error",
+        "[EXIT ",
+        "Test run [FAILED]",
+        "Lint [FAILED]",
+        "[CONFLICT]",
+        "[CONFLICT "
+      ].freeze
+
+      # Plan 87 E-1: state is reached through the ShellDeps façade. Accepts a
+      # bare loop for compatibility with existing test doubles (wrapped).
+      def initialize(loop_or_deps)
+        @deps = ShellDeps.wrap(loop_or_deps)
+      end
+
+      def execute_single_tool_call(tool_call, text_resp, auto_apply_mode = nil)
+        tool_name = tool_call["tool"] || tool_call[:tool]
+        tool_args = tool_call["args"] || tool_call[:args] || {}
+        call_id = tool_call["id"] || tool_call[:id] || ToolCallId.mint(@deps.step_count, unique: true)
+
+        tool_instance = @deps.respond_to?(:tool_registry) && @deps.tool_registry ? @deps.tool_registry.get(tool_name) : nil
+        canonical_name = tool_instance ? tool_instance.name : tool_name.to_s.downcase
+
+        # Auto-apply buffer before running tests or shell commands on disk if
+        # configured (decision: AutoApply; explicit mode = test injection seam)
+        if AutoApply.apply?(@deps.config, trigger: :pre_execution, tool: canonical_name, mode: auto_apply_mode) && @deps.buffer_manager&.dirty?
+          applied = AutoApply.apply_and_sync(@deps.buffer_manager, @deps.shell)
+          @deps.on_step&.call(type: :auto_apply, reason: "pre_execution", files: applied, step: @deps.step_count, max_steps: @deps.max_steps)
+        end
+
+        return handle_finish_tool(tool_args, text_resp, auto_apply_mode) if canonical_name == "finish"
+
+        # Maestro gate: maestro'nun doğrudan yürütme araçları reddedilir
+        # (detay ve config semantics: maestro_gate.rb).
+        if maestro_gate_blocks?(canonical_name, tool_args)
+          maestro_refusal(canonical_name, tool_name, call_id)
+          nil
+        elsif tool_instance
+          execute_registered_tool(tool_instance, tool_name, tool_args, call_id, auto_apply_mode)
+          nil
+        else
+          handle_invalid_tool(tool_name, call_id)
+        end
+      end
+
+      def handle_finish_tool(tool_args, text_resp, auto_apply_mode = nil)
+        if AutoApply.apply?(@deps.config, trigger: :finish, mode: auto_apply_mode) && @deps.buffer_manager&.dirty?
+          applied = AutoApply.apply_and_sync(@deps.buffer_manager, @deps.shell)
+          @deps.on_step&.call(type: :auto_apply, reason: "finish", files: applied, step: @deps.step_count, max_steps: @deps.max_steps)
+        end
+
+        clean_text_resp = clean_llm_text(text_resp)
+        tool_msg = (tool_args["message"] || tool_args[:message]).to_s.strip
+
+        # Review Finding 5: message-selection heuristic extracted to
+        # FinishMessageSelector (documented, named constants, unit-pinned).
+        final_msg = FinishMessageSelector.select(clean_text_resp, tool_msg)
+
+        # Plan 61: the marker must know where the content went — streamed
+        # turns already printed it above, batch turns render right below.
+        @deps.on_step&.call(type: :finish, message: final_msg, streamed: @deps.last_turn_streamed == true,
+                            step: @deps.step_count, max_steps: @deps.max_steps)
+        # streamed must reflect the FINISHING turn's reality: its text may
+        # have been streamed as chunks before the finish call. A hardcoded
+        # false made the free-text render treat an already-printed answer as
+        # unprinted and print it a second time.
+        { ok: true, output: final_msg, steps: @deps.step_count, tokens: @deps.total_tokens,
+          streamed: @deps.last_turn_streamed == true, loop_instance: @deps.loop_instance }
+      end
+
+      def execute_registered_tool(tool_instance, tool_name, tool_args, call_id, auto_apply_mode = nil)
+        @deps.on_step&.call(type: :tool_call, tool: tool_name, args: tool_args, step: @deps.step_count, max_steps: @deps.max_steps, call_id: call_id)
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        # Opt-in circuit breaker (G19): when enabled and the circuit for this
+        # tool is open, raise into the normal error-result plumbing below so
+        # the loop sees a regular failed tool result without executing the
+        # wedged backend again. Disabled by default.
+        breaker = circuit_breaker_for
+        blocked_by_circuit = breaker && !breaker.allow?(tool_instance.name)
+
+        tool_result = begin
+          if blocked_by_circuit
+            raise ToolCircuitBreaker::CircuitOpenError,
+                  "circuit open for '#{tool_instance.name}' — repeated failures; waiting out the cooldown before retrying"
+          end
+
+          raw_output = tool_instance.execute(tool_args)
+          t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          dur = ((t1 - t0) * 1000).round(1)
+
+          max_chars = @deps.shell&.config&.fetch("tools.max_output_chars", 12_000) || 12_000
+          max_lines = @deps.shell&.config&.fetch("tools.max_output_lines", 300) || 300
+          trunc_strat = @deps.shell&.config&.fetch("tools.truncation_strategy", "head_tail") || "head_tail"
+
+          if raw_output.is_a?(Rubik::Tools::Result)
+            trunc_res = Rubik::Tools::Truncator.truncate(raw_output.output, max_chars: max_chars, max_lines: max_lines, strategy: trunc_strat)
+            effective_dur = raw_output.duration_ms.positive? ? raw_output.duration_ms : dur
+            first_line = raw_output.output.lines.first.to_s.strip
+            first_line = nil if first_line.empty?
+            Rubik::Tools::Result.new(
+              tool_name: raw_output.tool_name.to_s.empty? ? tool_name : raw_output.tool_name,
+              call_id: raw_output.call_id.to_s.empty? ? call_id : raw_output.call_id,
+              status: raw_output.status,
+              error: raw_output.error || (raw_output.error? ? first_line : nil),
+              exit_code: raw_output.exit_code,
+              output: trunc_res[:text],
+              duration_ms: effective_dur,
+              truncated: raw_output.truncated || trunc_res[:truncated],
+              metadata: raw_output.metadata
+            )
+          elsif raw_output.respond_to?(:status) && raw_output.respond_to?(:output)
+            out_str = raw_output.output.to_s
+            trunc_res = Rubik::Tools::Truncator.truncate(out_str, max_chars: max_chars, max_lines: max_lines, strategy: trunc_strat)
+            st = raw_output.status.to_sym
+            first_line = out_str.lines.first.to_s.strip
+            first_line = nil if first_line.empty?
+            err = (raw_output.respond_to?(:error) && raw_output.error) || (st == :error ? first_line : nil)
+            Rubik::Tools::Result.new(
+              tool_name: tool_name,
+              call_id: call_id,
+              status: st,
+              error: err,
+              output: trunc_res[:text],
+              duration_ms: dur,
+              truncated: trunc_res[:truncated]
+            )
+          else
+            out_str = raw_output.to_s
+            trunc_res = Rubik::Tools::Truncator.truncate(out_str, max_chars: max_chars, max_lines: max_lines, strategy: trunc_strat)
+
+            is_err = if raw_output.respond_to?(:error?)
+                       raw_output.error?
+                     elsif raw_output.respond_to?(:failed?)
+                       raw_output.failed?
+                     elsif raw_output.is_a?(String)
+                       ERROR_PREFIXES.any? { |pfx| raw_output.start_with?(pfx) }
+                     else
+                       false
+                     end
+
+            first_line = out_str.lines.first.to_s.strip
+            first_line = nil if first_line.empty?
+
+            Rubik::Tools::Result.new(
+              tool_name: tool_name,
+              call_id: call_id,
+              status: is_err ? :error : :ok,
+              error: is_err ? first_line : nil,
+              output: trunc_res[:text],
+              duration_ms: dur,
+              truncated: trunc_res[:truncated]
+            )
+          end
+        rescue StandardError => e
+          t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          dur = ((t1 - t0) * 1000).round(1)
+          err_msg = "Error executing tool '#{tool_name}': #{e.class} - #{e.message}"
+          Rubik::Tools::Result.new(
+            tool_name: tool_name,
+            call_id: call_id,
+            status: :error,
+            error: e.message,
+            output: err_msg,
+            duration_ms: dur
+          )
+        end
+
+        # always-mode flush after every tool — was historically silent; the
+        # post_tool event makes the disk write visible like every other apply
+        if breaker && !blocked_by_circuit
+          if tool_result.status == :ok
+            breaker.record_success(tool_instance.name)
+          else
+            breaker.record_failure(tool_instance.name)
+          end
+        end
+
+        if AutoApply.apply?(@deps.config, trigger: :post_tool, mode: auto_apply_mode) && @deps.buffer_manager&.dirty?
+          applied = AutoApply.apply_and_sync(@deps.buffer_manager, @deps.shell)
+          @deps.on_step&.call(type: :auto_apply, reason: "post_tool", files: applied, step: @deps.step_count, max_steps: @deps.max_steps)
+        end
+
+        # Real-time LSP In-Buffer Diagnostics feedback loop (Plan 56 D-5,
+        # extracted to LspFeedback for the line budget).
+        tool_result = LspFeedback.refresh(deps: @deps, tool_instance: tool_instance,
+                                          tool_args: tool_args, tool_result: tool_result)
+
+        # Ekrana-bas sözleşmesi (storage-show-surface planı A): display
+        # çıktısı tam içerikle kullanıcıya :user_output olarak akar; model,
+        # history ve :tool_result özeti yalnız stub görür. Event birincil
+        # teslimat olduğu için onsuz stub yalan olur — kaynak yoksa warn.
+        if raw_output.respond_to?(:user_display?) && raw_output.user_display? && tool_result.status == :ok
+          sink = @deps.respond_to?(:on_step) ? @deps.on_step : nil
+          if sink
+            sink.call(type: :user_output, content: raw_output.to_s, label: raw_output.display_stub,
+                      step: @deps.step_count, max_steps: @deps.max_steps)
+          else
+            warn("[show_file] no :user_output sink wired — display content dropped: #{raw_output.display_stub}")
+          end
+          tool_result = Rubik::Tools::Result.new(tool_name: tool_name, call_id: call_id, status: :ok,
+                                                 output: raw_output.display_stub, duration_ms: tool_result.duration_ms)
+        end
+
+        @deps.on_step&.call(
+          type: :tool_result,
+          tool: tool_name,
+          output: tool_result.output,
+          status: tool_result.status,
+          duration_ms: tool_result.duration_ms,
+          step: @deps.step_count,
+          max_steps: @deps.max_steps,
+          call_id: call_id,
+          line_count: tool_result.output.to_s.lines.size,
+          byte_size: tool_result.output.to_s.bytesize,
+          tokens: @deps.total_tokens
+        )
+
+        Rubik::Orchestrator::ToolHistory.write(@deps.history, tool_call_id: call_id, tool_name: tool_name,
+                                                              status: tool_result.status, duration_ms: tool_result.duration_ms,
+                                                              content: tool_result.to_xml)
+        @deps.activity.record(tool_name, tool_args, tool_result.status) if @deps.respond_to?(:activity)
+        @deps.reset_invalid_tools!
+        tool_result
+      end
+
+      def handle_invalid_tool(tool_name, call_id)
+        @deps.record_invalid_tool!
+        @deps.activity.record(tool_name, {}, :error) if @deps.respond_to?(:activity)
+        if @deps.invalid_tool_count >= 2
+          return { ok: false, error: "Repeated invalid tool call '#{tool_name}'", steps: @deps.step_count,
+                   tokens: @deps.total_tokens, loop_instance: @deps.loop_instance }
+        end
+
+        registry = @deps.respond_to?(:tool_registry) && @deps.tool_registry
+        all_tool_names = registry ? registry.list.map(&:name) : []
+        all_lookup_names = if registry
+                             (registry.list.map(&:name) + (registry.respond_to?(:aliases_map) ? registry.aliases_map.keys : [])).uniq
+                           else
+                             []
+                           end
+
+        matched_candidates = Rubik::Tools::FuzzyMatcher.best_matches(tool_name, all_lookup_names)
+        candidate_tools = matched_candidates.map { |c| registry&.get(c)&.name || c }.uniq
+        diagnostic_msg = Rubik::Tools::DiagnosticReporter.render_unknown_tool(tool_name, candidate_tools: candidate_tools, all_tools: all_tool_names)
+
+        err_result = Rubik::Tools::Result.new(
+          tool_name: tool_name,
+          call_id: call_id,
+          status: :error,
+          error: "Tool '#{tool_name}' does not exist.",
+          output: diagnostic_msg,
+          duration_ms: 0.0
+        )
+        Rubik::Orchestrator::ToolHistory.write(@deps.history, tool_call_id: call_id, tool_name: tool_name,
+                                                              status: :error, duration_ms: 0.0, content: err_result.to_xml)
+        nil
+      end
+
+      private
+
+      # G19: one breaker per executor, built from the first enabled config
+      # sighting. Threshold/cooldown changes via live !config set are picked
+      # up on the next executor instantiation — acceptable for an opt-in
+      # guard (the executor is rebuilt per loop).
+      def circuit_breaker_for
+        return @circuit_breaker if @circuit_breaker
+
+        settings = @deps.shell&.config&.fetch("tools.circuit_breaker", nil)
+        return nil unless settings.is_a?(Hash) && settings["enabled"]
+
+        @circuit_breaker = ToolCircuitBreaker.new(
+          threshold: settings.fetch("threshold", 5),
+          cooldown_seconds: settings.fetch("cooldown_seconds", 60)
+        )
+      end
+
+      def clean_llm_text(text)
+        str = text.to_s.strip
+        return "" if str.empty?
+
+        # If whole text is raw JSON tool call e.g. {"tool": "finish", "args": {...}}
+        if str.start_with?("{") && str.end_with?("}")
+          parsed = begin
+            JSON.parse(str)
+          rescue JSON::ParserError
+            nil
+          end
+          return "" if parsed.is_a?(Hash) && (parsed.key?("tool") || parsed.key?(:tool))
+          # A {...} envelope that failed to parse is itself a malformed tool
+          # call; swallow it to "" rather than leaking the raw text as content.
+          return "" if parsed.nil?
+        end
+
+        # Strip ```json ... ``` blocks
+        str.gsub(/```(?:json)?\s*\{.*?\}\s*```/m, "").strip
+      end
+    end
+  end
+end

data/lib/rubik/orchestrator/stream_manager.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative "../llm/chunk_assembler"
+require_relative "provider_recovery"
+
+module Rubik
+  module Orchestrator
+    # Streaming request execution and chunk-to-response assembly (Plan 54
+    # D-6). Stateless collaborator over Loop-held state. Overflow recovery
+    # (retry-once after emergency compaction; Interrupt, not being a
+    # StandardError, escapes to the shell's console restoration) lives in
+    # ProviderRecovery — this class keeps the chunk pipeline and keeps ALL
+    # per-attempt state inside the recovered block.
+    class StreamManager
+      # Plan 87 E-1: state is reached through the ShellDeps façade. Accepts a
+      # bare loop for compatibility with existing test doubles (wrapped).
+      def initialize(loop_or_deps)
+        @deps = ShellDeps.wrap(loop_or_deps)
+      end
+
+      def execute_streaming_request(opts)
+        # Recovery policy lives in ProviderRecovery; the block owns ALL
+        # per-attempt state. `retry` re-yields the block, so a failed
+        # attempt's accumulated chunks can never pollute the retried
+        # response (the Candidate 03 fix). The config guard mirrors
+        # #process_stream_chunk: bare test doubles may not expose config.
+        ProviderRecovery.with_recovery(
+          config: @deps.respond_to?(:config) ? @deps.config : nil,
+          compact: ->(reason) { @deps.emergency_compact_and_notify!(reason) }
+        ) do
+          accumulated_chunks = []
+          streamed_text = false
+          res = @deps.provider.stream_chat(@deps.history, opts) do |chunk|
+            accumulated_chunks << chunk
+            streamed_text = true if process_stream_chunk(chunk)
+          end
+
+          if res.is_a?(Enumerator) && accumulated_chunks.empty?
+            res.each do |chunk|
+              accumulated_chunks << chunk
+              streamed_text = true if process_stream_chunk(chunk)
+            end
+          end
+
+          @deps.on_step&.call(type: :chunk_end, step: @deps.step_count, max_steps: @deps.max_steps) if streamed_text
+          @deps.mark_last_turn_streamed!(streamed_text)
+          build_response_from_chunks(accumulated_chunks, streamed_text: streamed_text)
+        end
+      end
+
+      def build_response_from_chunks(accumulated_chunks, streamed_text: false)
+        # Plan 61 D-4: assembly moved to Rubik::LLM::ChunkAssembler (shared
+        # with BaseProvider#complete); this delegate keeps the historical
+        # call signature for tests and any external consumers.
+        Rubik::LLM::ChunkAssembler.build(
+          accumulated_chunks,
+          streamed: streamed_text == true,
+          estimate_history: -> { @deps.budget_manager.estimate_tokens_from_history },
+          estimate_text: ->(t) { @deps.provider.respond_to?(:estimate_tokens) ? @deps.provider.estimate_tokens(t) : nil },
+          on_malformed_args: lambda { |tool_name, fragment|
+            @deps.on_step&.call(
+              type: :malformed_tool_args, tool: tool_name,
+              fragment: fragment.to_s[0, 200],
+              step: @deps.step_count, max_steps: @deps.max_steps
+            )
+          }
+        )
+      end
+
+      # Forwards HTTPClient retry notifications to the shell's on_step channel
+      # as :llm_retry step_info so the REPL prints live retry lines instead of
+      # appearing frozen. Custom providers that ignore opts[:on_retry] simply
+      # produce no retry output. Loop state is read at invocation time.
+      def llm_retry_notifier
+        lambda do |attempt, max, reason|
+          @deps.on_step&.call(type: :llm_retry, attempt: attempt, max: max, reason: reason,
+                              step: @deps.step_count, max_steps: @deps.max_steps)
+        end
+      end
+
+      private
+
+      # One chunk, both delivery forms (stream block + Enumerator replay):
+      # resolve the reasoning-capture knob, forward deltas as step events,
+      # and report whether a text delta was emitted (drives streamed_text
+      # and chunk_end).
+      def process_stream_chunk(chunk)
+        capture_reasoning = if @deps.respond_to?(:safe_config)
+                              @deps.safe_config("llm.capture_reasoning", true) != false
+                            elsif @deps.respond_to?(:config) && @deps.config.respond_to?(:fetch)
+                              @deps.config.fetch("llm.capture_reasoning", true) != false
+                            else
+                              true
+                            end
+        if capture_reasoning &&
+           chunk.respond_to?(:reasoning_delta?) && chunk.reasoning_delta? && !chunk.reasoning_delta.to_s.empty?
+          @deps.on_step&.call(
+            type: :llm_thought_delta,
+            delta: chunk.reasoning_delta,
+            step: @deps.step_count,
+            max_steps: @deps.max_steps
+          )
+        end
+        emitted_text = false
+        if chunk.text_delta? && !chunk.text_delta.to_s.empty?
+          emitted_text = true
+          @deps.on_step&.call(
+            type: :chunk,
+            delta: chunk.text_delta,
+            step: @deps.step_count,
+            max_steps: @deps.max_steps
+          )
+        end
+        emitted_text
+      end
+    end
+  end
+end

data/lib/rubik/orchestrator/subagent/activation.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Orchestrator
+    module Subagent
+      # Birth choreography for EVERY subagent run — spawn and redeploy alike.
+      # Extracted from supervisor.rb/reuse.rb to keep both under their
+      # module-hygiene caps (the messaging.rb precedent) and, more
+      # importantly, to make the unit-registration ORDERING RULE structural
+      # instead of comment-enforced: the kernel unit is registered BEFORE
+      # start_async at both sites, with a birth state DERIVED from instance
+      # state — a unit minted while the instance is settled (the redeploy
+      # entry: completed/failed) falls back to :pending, so it can never be
+      # born dead. start_async's own @unit&.sync_state! is then the single
+      # promotion edge (pending -> active), exactly as for fresh spawns.
+      # The old dead-born trap made reap_dead_kernel_units! dispose the LIVE
+      # child ctx, silently killing the ask_question channel of the
+      # redeployed run (pinned by test_redeploy_registers_fresh_unit_without_state_error).
+      module ActivationSupervisor
+        # Call UNDER the supervisor monitor (both birth sites already ran
+        # start_async under it — the worker is parked before spawn returns).
+        # Order is load-bearing: coeffect provides first (coeffect resolution
+        # happens at execute time, but a start_async completion must never
+        # race an unprovided asker), unit registration second (pre-start, so
+        # the kernel board sees a live unit), start_async last.
+        def activate_instance!(inst, child_ctx:)
+          # ask_question'ın subagent düzlemi: instance kendi child ctx'ine
+          # asker olarak publish edilir.
+          child_ctx&.provide(Rubik::Coeffects::SUBAGENT_QUESTION_ASKER, inst)
+          # send_message atfı: subagent→maestro mesajları gerçek gönderen
+          # id'siyle taşır (coeffect yoksa root default'u yanlış atfı yapar).
+          child_ctx&.provide(Rubik::Coeffects::SUBAGENT_SENDER_ID, inst.id)
+          eff_init = @init || (@root_context.respond_to?(:get) && Rubik::Coeffects.get(@root_context, Rubik::Coeffects::INIT))
+          eff_init&.register(Kernel::SubagentUnit.new(inst, context: child_ctx, birth_state: unit_birth_state(inst)))
+          inst.start_async { |completed_inst| handle_subagent_completion(completed_inst) }
+          inst
+        end
+
+        # Child-ctx mint + the one degrade warning. A root context without
+        # #extend (duck-type host) cannot carry the question/sender
+        # coeffects — the degradation is made visible, never silent.
+        def extend_root_context!(origin)
+          child_ctx = @root_context.respond_to?(:extend) ? @root_context.extend : nil
+          Rubik::Log.warn(:orchestrator, "subagent #{origin}: root context lacks #extend — no child ctx; subagent planes degrade") unless child_ctx
+          child_ctx
+        end
+
+        private
+
+        # The registration-order rule, DERIVED FROM INSTANCE STATE: a unit is
+        # born with a LIVE kernel state, never a terminal one. If the
+        # instance's current state maps through STATE_MAP into a terminal
+        # unit state (the redeploy entry: completed/failed), mint :pending
+        # instead — start_async's own @unit&.sync_state! (instance.rb) is
+        # then the single promotion edge. A born-:pending unit settling
+        # forward is a legal Unit#transition_to! edge; a born-terminal unit
+        # is frozen forever (sync_state! no-ops on dead).
+        def unit_birth_state(inst)
+          derived = Kernel::SubagentUnit::STATE_MAP.fetch(inst.state)
+          Kernel::Unit::TERMINAL_STATES.include?(derived) ? :pending : derived
+        end
+      end
+    end
+  end
+end