rubik 0.1.0

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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative "notices"
+
+module Rubik
+  module Orchestrator
+    module Subagent
+      # THE render seam: (lifecycle state, facts) -> text, one direction,
+      # no reverse writes. Pure — no locks, no IO, no instance state; the
+      # only require is the notices vocabulary leaf. Every state->text
+      # spelling for an Instance's own lifecycle (state_note, the
+      # manage_subagents status/wait guidance) and the manage_subagents
+      # action vocabulary (schema enum, dispatch keys, help list, error
+      # text) projects from here, so the drift between them is
+      # unexpressable: the session-review bug class (B3 stale placeholder,
+      # B4 grants-blind halt wording) existed because narration was
+      # hand-STORED beside state instead of derived from it.
+      module Narration
+        module_function
+
+        # --- instance-state narration (the only home of state->text) ---
+
+        # The pause/halt story for a lifecycle state, computed on demand.
+        # state is an Instance::TRANSITIONS key; silent states (live or
+        # settled runs) yield nil — :completed narrates via its real
+        # :result, plain :failed via :last_error, so nothing is invented.
+        # paused_after_s is the recorded wait fact (Instance#pause_facts)
+        # feeding the halt wording's "within Ns" clause.
+        def state_note(state, grants_received: 0, max_steps: nil, last_error: nil, paused_after_s: nil)
+          case state.to_sym
+          when :waiting_budget
+            "Paused awaiting budget expansion from the maestro."
+          when :budget_exhausted
+            if grants_received.positive?
+              # B4: after a consumed grant the halt must say no FURTHER
+              # expansion arrived — "not received" read as a lost grant.
+              "#{Notices.budget_exhausted_line(max_steps)} No further budget expansion arrived " \
+                "within #{paused_after_s ? "#{paused_after_s}s" : 'the wait timeout'} " \
+                "(#{grants_received} grant(s) were received and consumed earlier)."
+            else
+              "#{Notices.budget_exhausted_line(max_steps)} Budget expansion was not received from the maestro."
+            end
+          when :paused_error
+            "Paused awaiting error recovery: #{last_error}"
+          when :waiting_input
+            "Asked the maestro a clarifying question; blocked awaiting the answer."
+          when :failed
+            "Subagent halted after #{paused_after_s}s in paused_error state: #{last_error}" if paused_after_s
+          end
+        end
+
+        # manage_subagents status/wait channel: blocked states get the exact
+        # recovery action, a mid-flight worker gets the poll discipline. All
+        # other states yield nil (no story).
+        def guidance(state, id:, max_steps:, step: nil, uptime: nil)
+          case state.to_sym
+          when :waiting_input
+            "Subagent asked a question and is BLOCKED awaiting your answer. Reply via send_message(recipient: '#{id}', message: '<your answer>')."
+          when :waiting_budget
+            Notices.budget_paused_line(id, max_steps)
+          when :budget_exhausted
+            Notices.budget_exhausted_line(max_steps)
+          when :paused_error
+            "Subagent paused on provider/network error. Call manage_subagents(action: 'resume', conversation_id: '#{id}') to retry."
+          when :running
+            # The poll-discipline story needs the live facts; callers without
+            # them (wait rows, plain state dispatch) get nil = no story —
+            # this guidance channel was budget-states-only before the seam.
+            if step && uptime
+              "Subagent is actively working (step #{step}/#{max_steps}, #{uptime.round(1)}s uptime). " \
+                "DO NOT poll 'status' in a loop! Call #{Notices.wait_any_hint} to block until completion, " \
+                "or simply stop calling tools to receive reactive wakeup."
+            end
+          end
+        end
+
+        # The nil-provider fast path's terminal stub (a legitimate outcome:
+        # no provider, no story beyond the echo of the task itself).
+        def completed_stub_line(id, role, prompt)
+          "Subagent [#{id}] (#{role}) completed task successfully: #{prompt.slice(0, 80)}"
+        end
+
+        # --- manage_subagents action vocabulary (single declaration) ---
+
+        # One canonical row per action; model-facing aliases ride along.
+        # The schema enum, the dispatch canonicalization, the description's
+        # action list, and the unknown-action error are ALL projections of
+        # this table — adding an action means adding a row, nothing else.
+        Action = Struct.new(:canonical, :aliases, :param, keyword_init: true)
+
+        ACTION_SPECS = [
+          Action.new(canonical: "list", aliases: []),
+          Action.new(canonical: "status", aliases: [], param: "conversation_id"),
+          Action.new(canonical: "wait", aliases: [], param: "conversation_ids"),
+          Action.new(canonical: "transcript", aliases: [], param: "conversation_id"),
+          Action.new(canonical: "extend_budget", aliases: ["grant_steps", "extend"], param: "conversation_id"),
+          Action.new(canonical: "resume", aliases: ["retry"], param: "conversation_id"),
+          Action.new(canonical: "redeploy", aliases: [], param: "conversation_id"),
+          Action.new(canonical: "reap", aliases: ["clean"]),
+          Action.new(canonical: "kill", aliases: [], param: "conversation_ids"),
+          Action.new(canonical: "kill_all", aliases: ["killall"])
+        ].freeze
+
+        CANONICAL_NAMES = ACTION_SPECS.map(&:canonical).freeze
+
+        # Model-facing vocabulary: canonical names plus their aliases (the
+        # schema enum previously drifted from dispatch by missing "killall").
+        SCHEMA_ACTIONS = ACTION_SPECS.flat_map { |spec| [spec.canonical, *spec.aliases] }.freeze
+
+        CANONICAL_LOOKUP = ACTION_SPECS.flat_map { |spec| [spec.canonical, *spec.aliases].map { |token| [token, spec.canonical] } }.to_h.freeze
+
+        # Alias-resolving dispatch key; nil = unknown action.
+        def canonical_action(token)
+          token && CANONICAL_LOOKUP[token.to_s.downcase.strip]
+        end
+
+        # Rendered canonical list for the tool description (order-stable, so
+        # TOOLS.md generation stays byte-identical).
+        def quoted_canonical_list
+          CANONICAL_NAMES.map { |name| "'#{name}'" }.join(", ")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require_relative "../../platform"
+require_relative "budget"
+
+module Rubik
+  module Orchestrator
+    module Subagent
+      # THE single vocabulary home for subagent notices: event names and
+      # payloads enter, two channel renderings leave (user channel: REPL
+      # hints allowed; model channel: tool-oriented).
+      module Notices
+        module_function
+
+        # Bus event names
+        COMPLETED_EVENT = :subagent_completed
+        BUDGET_EXHAUSTED_EVENT = :subagent_budget_exhausted
+        COMPACTED_EVENT = :subagent_context_compacted
+        AUTO_APPLY_FAILED_EVENT = :subagent_auto_apply_failed
+        ERROR_PAUSED_EVENT = :subagent_error_paused
+        QUESTION_EVENT = :subagent_question
+        MESSAGE_EVENT = :subagent_message_to_parent
+
+        # Bus event name -> normalized notice kind.
+        EVENTS = {
+          COMPLETED_EVENT => :completed,
+          BUDGET_EXHAUSTED_EVENT => :budget_exhausted,
+          COMPACTED_EVENT => :context_compacted,
+          AUTO_APPLY_FAILED_EVENT => :auto_apply_failed,
+          ERROR_PAUSED_EVENT => :error_paused,
+          QUESTION_EVENT => :question
+        }.freeze
+
+        # Sessizlik (§4.3): bu roller notice ÜRETMEZ, yalnız dmesg'e düşer (Distiller + Context Pruner).
+        SILENT_ROLES = ["Vakanüvis Distiller", "Context Pruner"].freeze
+
+        # Dmesg-plane emission metadata (bug-llm-timeout-observability): every
+        # subagent-plane event lands in the ring under subsystem :subagent with
+        # an operational-weight severity, so dmesg(level:/subsystem:) surfaces
+        # a stalled subagent. MESSAGE_EVENT routes here too (a :message notice
+        # via handle_parent_message, not normalize).
+        SUBSYSTEM = :subagent
+
+        SEVERITIES = {
+          COMPLETED_EVENT => :info,
+          BUDGET_EXHAUSTED_EVENT => :warn,
+          COMPACTED_EVENT => :info,
+          AUTO_APPLY_FAILED_EVENT => :warn,
+          ERROR_PAUSED_EVENT => :err,
+          QUESTION_EVENT => :notice,
+          MESSAGE_EVENT => :info
+        }.freeze
+
+        # The one emission door: severity and subsystem are decided HERE,
+        # never re-derived at call sites. Nil bus = the old `&.emit` skip;
+        # a bus lacking #emit still raises loud; a legacy 2-arity emit gets
+        # a plain 2-arg call (severity metadata best-effort, delivery
+        # load-bearing). `fallback:` flips a raise into a stderr warn (the
+        # AutoApply.report_failure pattern) for load-bearing event sites.
+        def emit(bus, event_name, payload, fallback: nil)
+          return if bus.nil?
+
+          emit_it = lambda {
+            m = bus.method(:emit)
+            kw = { subsystem: SUBSYSTEM, level: SEVERITIES.fetch(event_name, :info) }
+            if m.parameters.any? { |p| [:key, :keyrest].include?(p.first) }
+              m.call(event_name, payload, **kw)
+            else
+              m.call(event_name, payload)
+            end
+          }
+          emit_it.call
+        rescue StandardError => e
+          raise if fallback.nil?
+
+          warn("#{fallback} (#{e.class}: #{e.message})")
+        end
+
+        def normalize(event_name, payload)
+          return nil if SILENT_ROLES.include?(payload[:role].to_s)
+
+          kind = EVENTS[event_name.to_sym]
+          return nil unless kind
+
+          notice = { kind: kind, id: payload[:id].to_s, role: payload[:role].to_s,
+                     state: payload[:state].to_s, max_steps: payload[:max_steps] }
+          raw_err = payload[:error] || payload[:reason]
+          # Q-timeout marker rides AFTER the cap (#97): truncation can never eat it.
+          if kind == :question && notice[:state] == "question_timed_out"
+            notice[:reason] = "#{raw_err.to_s.slice(0, 230)} [timed out unanswered after #{payload[:timeout]}s — proceeding on its own judgment]"
+          elsif [:context_compacted, :auto_apply_failed, :error_paused, :question].include?(kind)
+            notice[:reason] = raw_err.to_s.slice(0, kind == :question ? 300 : 120)
+          end
+          notice[:timeout] = payload[:timeout] if kind == :question
+          # B11: grant/step markers make repeated pauses distinguishable.
+          if kind == :budget_exhausted
+            notice[:grants] = payload[:grants].to_i if payload[:grants].to_i.positive?
+            notice[:step] = payload[:step].to_i if payload[:step].to_i.positive?
+          end
+          notice
+        end
+
+        def user_line(notice)
+          case notice[:kind]
+          when :context_compacted
+            detail = notice[:reason].to_s.empty? ? "" : " (#{notice[:reason]})"
+            "🧹 [Subagent Compacted] [#{notice[:id]}] '#{notice[:role]}' recovered from a provider context-limit error by compacting its own history; work continues#{detail}."
+          when :auto_apply_failed
+            "⚠️ [Subagent Auto-Apply] [#{notice[:id]}] '#{notice[:role]}' could not auto-apply its buffer (#{notice[:reason]}). Changes remain unapplied."
+          when :budget_exhausted
+            grants = notice[:grants].to_i
+            step = notice[:step]
+            cyc = " again (after #{grants} grant(s) consumed#{", at step #{step}" if step})" if grants.positive?
+            "⚠️ [Subagent Paused] [#{notice[:id]}] '#{notice[:role]}' reached step budget#{cyc} " \
+              "(#{notice[:max_steps]} steps). Run '!subagents extend #{notice[:id]}' to resume."
+          when :error_paused
+            "⚠️ [Subagent Paused] [#{notice[:id]}] '#{notice[:role]}' paused due to provider/network error (#{notice[:reason]}). Run '!subagents resume #{notice[:id]}' to retry."
+          when :message
+            "💬 [Message from #{notice[:id]}] #{notice[:reason]}"
+          when :question
+            badge = notice[:state] == "question_timed_out" ? "⌛ [Question timed out] [#{notice[:id]}]" : "❓ [Question from #{notice[:id]}]"
+            "#{badge} '#{notice[:role]}': #{notice[:reason]}"
+          when :task
+            badge = notice[:state] == "completed" ? "⚡ [Task Done]" : "❌ [Task Failed]"
+            "#{badge} [#{notice[:id]}] - #{notice[:state].to_s.upcase}"
+          else
+            case notice[:state]
+            when "budget_exhausted"
+              "🛑 [Subagent Budget Exhausted] [#{notice[:id]}] '#{notice[:role]}' - BUDGET_EXHAUSTED (task incomplete)"
+            when "failed"
+              "❌ [Subagent Failed] [#{notice[:id]}] '#{notice[:role]}' - FAILED. Call manage_subagents(action: 'status', conversation_id: '#{notice[:id]}') for the error."
+            when "completed"
+              "⚡ [Subagent Completed] [#{notice[:id]}] '#{notice[:role]}' - COMPLETED"
+            else
+              "🏁 [Subagent Finished] [#{notice[:id]}] '#{notice[:role]}' - #{notice[:state].to_s.upcase}"
+            end
+          end
+        end
+
+        def model_element(notice)
+          attrs = { kind: notice[:kind], id: notice[:id], role: notice[:role], state: notice[:state] }
+          attrs[:max_steps] = notice[:max_steps] if notice[:kind] == :budget_exhausted
+          reason_kinds = [:context_compacted, :auto_apply_failed, :error_paused, :message, :task, :question]
+          attrs[:reason] = notice[:reason] if reason_kinds.include?(notice[:kind]) && !notice[:reason].to_s.empty?
+          attrs[:timeout] = notice[:timeout] if notice[:kind] == :question && notice[:timeout]
+          attrs[:guidance] = guidance_for(notice)
+          rendered = attrs.map { |k, v| %(#{k}="#{Rubik::Platform.xml_escape(v)}") }.join(" ")
+          "<notification #{rendered} />"
+        end
+
+        def history_block(notices)
+          elements = notices.map { |n| "  #{model_element(n)}" }.join("\n")
+          "<subagent_notifications>\n#{elements}\n</subagent_notifications>"
+        end
+
+        # Event-channel guidance (notice-kind keyed); instance-state narration lives in Narration.
+        def guidance_for(notice)
+          case notice[:kind]
+          when :task
+            "Inspect task output via manage_task(action: 'logs', task_id: '#{notice[:id]}')."
+          when :context_compacted
+            "No action needed: the subagent recovered automatically; its history was compacted, so early details may be summarized."
+          when :auto_apply_failed
+            "Auto-apply failed; changes remain unapplied. Apply via the apply_buffer tool."
+          when :budget_exhausted
+            "Resume via #{extend_budget_hint(notice[:id])} or kill it with action: 'kill'."
+          when :error_paused
+            "Subagent paused on network error. Resume via #{resume_hint(notice[:id])} or kill with action: 'kill'."
+          when :message
+            "Message from subagent. Respond or grant steps via send_message(recipient: '#{notice[:id]}', message: '...')."
+          when :question
+            answered = "No answer is needed anymore: it timed out and the subagent proceeded on its own judgment. " \
+                       "A late send_message(recipient: '#{notice[:id]}') lands as a regular message."
+            blocking = "Answer NOW via send_message(recipient: '#{notice[:id]}', message: '<your answer>') — " \
+                       "the subagent is blocked waiting (#{notice[:timeout] || 300}s timeout)."
+            notice[:state] == "question_timed_out" ? answered : blocking
+          else
+            if notice[:state] == "budget_exhausted"
+              budget_exhausted_line(notice[:max_steps])
+            else
+              "Retrieve the full result with #{wait_hint(notice[:id])}."
+            end
+          end
+        end
+
+        def budget_paused_line(id, max_steps) = "Subagent reached step budget (#{max_steps} steps) and paused. Call #{extend_budget_hint(id)} to resume."
+
+        def budget_exhausted_line(max_steps = nil)
+          count = max_steps ? " (#{max_steps} steps)" : ""
+          "Subagent reached step budget#{count} and halted: task was NOT completed. Inspect transcript or spawn a new subagent."
+        end
+
+        DEFAULT_WAIT_TIMEOUT = 30
+
+        def render_ids(ids) = "[#{Array(ids).map { |id| "'#{id}'" }.join(', ')}]"
+
+        def wait_hint(ids, timeout: DEFAULT_WAIT_TIMEOUT) = "manage_subagents(action: 'wait', conversation_ids: #{render_ids(ids)}, timeout: #{timeout})"
+
+        def wait_any_hint(timeout: DEFAULT_WAIT_TIMEOUT) = "manage_subagents(action: 'wait', timeout: #{timeout})"
+
+        def wait_hint_template = "manage_subagents(action: 'wait', conversation_ids: [...], timeout: #{DEFAULT_WAIT_TIMEOUT})"
+
+        def extend_budget_hint(id, steps: Budget::DEFAULT_GRANT_STEPS) = "manage_subagents(action: 'extend_budget', conversation_id: '#{id}', steps: #{steps})"
+
+        def resume_hint(id) = "manage_subagents(action: 'resume', conversation_id: '#{id}')"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Orchestrator
+    module Subagent
+      # The ask-maestro bridge for the ask_question tool's subagent plane.
+      # Flips the instance to :waiting_input, announces the question on the
+      # event bus (REASON carries the full display text incl. options —
+      # Notices needs no question-specific plumbing), then polls the shared
+      # inbox for the maestro's send_message reply. The worker thread is the ONLY
+      # inbox drainer (drain_inbox_into_history runs between steps) and it is
+      # blocked inside the tool here, so the pop cannot race a drain.
+      # Polling (not a cond var) follows the Supervisor#wait_for precedent:
+      # kill hard-kills the thread, so perfect signaling is not required.
+      module Questioner
+        DEFAULT_QUESTION_TIMEOUT = 300
+
+        # Returns the answer String, :unavailable (no bus / wrong state —
+        # nobody can ever answer, so blocking would be wrong), or nil when
+        # unanswered (timeout or kill).
+        def ask_init0(question_text, options: [], timeout: nil)
+          return :unavailable unless @event_bus
+
+          # Drain pending steers into history FIRST (same discipline as the
+          # step top): a pre-question inbox message was NOT sent to a
+          # question-waiting subagent and must not pose as its answer.
+          drain_inbox_into_history
+          reason = Array(options).empty? ? question_text.to_s : "#{question_text} (options: #{Array(options).join(' / ')})"
+          payload = { id: @id, role: @role, state: :waiting_input,
+                      reason: reason, timeout: question_timeout(timeout) }
+          @monitor.synchronize do
+            return :unavailable unless executing?
+
+            transition!(:waiting_input)
+            @unit&.sync_state!
+          end
+          answer = nil
+          begin
+            # Emit OUTSIDE the monitor (budget-pause discipline): synchronous
+            # bus dispatch finishes before the poll starts, so the answer can
+            # never land before we begin waiting for it.
+            Notices.emit(@event_bus, Notices::QUESTION_EVENT, payload)
+            deadline = Time.now + payload[:timeout]
+            until answer
+              @monitor.synchronize { answer = @inbox.pop(true)&.text unless @inbox.empty? }
+              break if Time.now >= deadline || !(awaiting_human? || executing?)
+
+              sleep 0.1
+            end
+          ensure
+            # Guarded restore (also covers a raise or Thread#kill mid-wait):
+            # grant_budget! or kill may have legitimately moved the state on.
+            @monitor.synchronize do
+              transition!(:running) if awaiting_human?
+              @unit&.sync_state!
+            end
+          end
+          if answer.nil? && Time.now >= deadline
+            # The subagent-side timeout escalation ("proceed with your best
+            # judgment") is invisible to the maestro — it woke nobody. The
+            # timed-out notice re-surfaces the dead-end on the next wake so a
+            # late answer becomes a conscious choice, not a shot into a void
+            # the asker already left (issue #97 finding 4). The human-readable
+            # marker is appended by Notices.normalize AFTER its reason cap, so
+            # it can never be truncated away; here the state alone carries it.
+            Notices.emit(@event_bus, Notices::QUESTION_EVENT, payload.merge(state: :question_timed_out))
+          end
+          answer
+        end
+
+        def question_timeout(override = nil)
+          return override.to_f if override&.to_f&.positive?
+
+          (@config.respond_to?(:fetch) ? @config.fetch("subagents.question_timeout", DEFAULT_QUESTION_TIMEOUT) : DEFAULT_QUESTION_TIMEOUT) ||
+            DEFAULT_QUESTION_TIMEOUT
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "../../platform"
+
+module Rubik
+  module Orchestrator
+    module Subagent
+      # Özenli tasfiye (diligent reaping): işi biten subagent'lar grace
+      # süresi sonunda mezar taşına (tombstone) taşınır — bellekteki
+      # history serbest bırakılır, dayanıklı transcript ve storage indeksi
+      # kalır, status sorgulanabilir. :budget_exhausted / :paused_error
+      # ASLA reap edilmez: thread canlıdır (condvar park), resume hakları
+      # bozulmaz.
+      module Reaper
+        def archived? = !!@archived
+
+        # History yalnız transcript diske DURABLY yazıldıysa silinir —
+        # dosya yoksa reap sonraki süpürmeye kalır (yarım tasfiye yok).
+        def archive!
+          @monitor.synchronize do
+            return false unless File.exist?(@transcript_uri.to_s)
+
+            @history.replace([])
+            @archived = true
+            true
+          end
+        end
+      end
+
+      # Supervisor düzlemi: tombstone haritası + otomatik/force süpürme.
+      # Tombstone'lar get/list üzerinden sorgulanabilir kalır; wait_for
+      # bilinçli olarak yalnız @instances'e bakar (reap edilen zaten
+      # notice ile duyurulmuş, sonucu transcriptte).
+      module ReaperSupervisor
+        def reap_finished!(force: false)
+          dropped_steering = []
+          reaped = @monitor.synchronize do
+            grace = reap_grace_seconds
+            reaped = []
+            @instances.each do |id, inst|
+              next unless inst.respond_to?(:terminal_and_settled?) && inst.terminal_and_settled?
+              next unless force || (grace && inst.ended_at && Time.now - inst.ended_at >= grace)
+              next unless inst.archive!
+
+              dropped_steering << id if inst.respond_to?(:pending_redeploy_messages?) && inst.pending_redeploy_messages?
+              (@finished ||= {})[id] = inst
+              reaped << id
+            end
+            reaped.each { |id| @instances.delete(id) }
+            evict_overflow!
+            reaped
+          end
+          # OUTSIDE the supervisor monitor (emit/logging discipline): queued
+          # steering that died with the instance instead of a redeploy — the
+          # send_message :queued reply discloses this, but the loss must be
+          # observable (issue #55 3.2).
+          Platform.debug_warn("[Reaper] reaped with undelivered queued steering: #{dropped_steering.join(', ')}") unless dropped_steering.empty?
+          reaped
+        end
+
+        private
+
+        # reap_orphans gövdesinden çağrılır (handle_subagent_completion'ın
+        # hazır kancası) — disposed kabukları at, sonra grace dolanları
+        # tombstone'la. Tamamen sessiz bir oturumda SON biten subagent
+        # hiçbir tamamlanma tetikleyicisi bulamaz: sınırlı kalıntı, force
+        # ile elle reap edilebilir.
+        def sweep_disposed_and_finished
+          @instances.delete_if { |_k, v| v.disposed? }
+          reap_finished!
+        end
+
+        def reap_grace_seconds
+          raw = @config.respond_to?(:fetch) ? @config.fetch("subagents.reap_finished_after", 300) : 300
+          raw = 300 if raw.nil?
+          raw.to_f <= 0 ? nil : raw.to_f
+        end
+
+        def tombstone_limit
+          raw = @config.respond_to?(:fetch) ? @config.fetch("subagents.tombstone_limit", 25) : 25
+          raw = 25 if raw.nil?
+          raw.to_i
+        end
+
+        # FIFO taşma: en eski mezar taşı evict edilir ve cleanup ile
+        # :disposed'a çekilir (ctx zaten dispose'lu; cleanup no-op güvenli).
+        def evict_overflow!
+          return unless @finished
+
+          while @finished.size > tombstone_limit
+            _id, inst = @finished.shift
+            inst&.cleanup
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Orchestrator
+    module Subagent
+      # Transient network/provider error detection, backoff retries, and
+      # pause-on-error coordination for autonomous subagents (Plan 101).
+      module Resilience
+        DEFAULT_NETWORK_RETRIES = 3
+        DEFAULT_BACKOFF_BASE = 0.5
+        DEFAULT_ERROR_WAIT_TIMEOUT = 300
+
+        TRANSIENT_PATTERN = Regexp.union(
+          /5\d{2}|server_error|engine[-_]core error|rate[-_]limit|too many requests/i,
+          /read timeout|timeout|closed stream|closed socket/i,
+          /connection reset|connection refused|broken pipe/i
+        )
+
+        module_function
+
+        def transient_error?(err)
+          return false unless err.is_a?(StandardError)
+
+          msg = err.message.to_s
+          return true if msg.match?(TRANSIENT_PATTERN)
+          return true if defined?(Rubik::LLM::RateLimitError) && err.is_a?(Rubik::LLM::RateLimitError)
+          return true if defined?(Rubik::LLM::ClientError) && err.is_a?(Rubik::LLM::ClientError) && msg.match?(TRANSIENT_PATTERN)
+
+          transient_exception_class?(err)
+        end
+
+        def transient_exception_class?(err)
+          name = err.class.name.to_s
+          name.include?("Timeout") ||
+            name.include?("Socket") ||
+            name.include?("ECONNRESET") ||
+            name.include?("ECONNREFUSED") ||
+            name.include?("EPIPE") ||
+            name.include?("EOFError")
+        end
+
+        def retry_transient(config: nil, gate: nil, max_retries: nil, backoff_base: nil, on_retry: nil, &block)
+          retries_limit = max_retries ||
+                          (config.respond_to?(:fetch) && config.fetch("subagents.network_retry_count", nil)) ||
+                          DEFAULT_NETWORK_RETRIES
+          base_delay = backoff_base ||
+                       (config.respond_to?(:fetch) && config.fetch("subagents.network_backoff_base", nil)) ||
+                       DEFAULT_BACKOFF_BASE
+
+          attempt = 0
+          begin
+            attempt += 1
+            if gate
+              gate.synchronize(&block)
+            else
+              block.call
+            end
+          rescue StandardError => e
+            raise e unless attempt <= retries_limit.to_i && transient_error?(e)
+
+            delay = base_delay.to_f * (2**(attempt - 1)) * (0.8 + (0.4 * rand))
+            on_retry&.call(attempt, retries_limit.to_i, delay, e)
+            sleep(delay)
+            retry
+          end
+        end
+      end
+    end
+  end
+end