rubik 0.1.0

data/lib/rubik/repl/service_catalog.rb

@@ -0,0 +1,374 @@
+# frozen_string_literal: true
+
+require_relative "../coeffects"
+require_relative "../event_bus" unless defined?(Rubik::EventBus)
+require_relative "../orchestrator/subagent/supervisor"
+require_relative "../runtime/service_definition"
+
+module Rubik
+  module REPL
+    # The ONE ordered, declarative catalog of everything Composition builds
+    # and the Shell publishes (architecture-review Candidate 05). Entry order
+    # IS construction order — the historical Shell#initialize sequence, which
+    # is load-bearing: the shared guard is built BEFORE every consumer
+    # (buffer, mcp, sandbox runner, task manager) so they all share the same
+    # instance; runtime_manager precedes task_manager / skills / mcp, which
+    # wire into its context; buffer precedes the subagent supervisor.
+    #
+    #   owns   : the entries (builders, provide keys, optional/reader flags,
+    #            inject hooks) and the load-time derivations — Parts struct
+    #            members, shell reader names, the build fold, wire provide rows
+    #   leaves : key STRINGS and legacy aliases (Rubik::Coeffects SSOT —
+    #            entries reference the constants); shell-identity phases
+    #            (register shims, tool registry, UI, LLM route — lifecycle.rb);
+    #            override-kwarg resolution and root resolution (composition.rb);
+    #            tool-layer fallback defaults (Tools::Services)
+    #
+    # Adding a runtime service = its file + barrel require + a Coeffects key
+    # constant + ONE entry here. Parts members, the Shell ivar, the public
+    # reader and the wire provide all derive from that entry at load time;
+    # test_service_catalog.rb locks catalog <-> Parts <-> readers <->
+    # provides <-> Coeffects consistency so the derivation cannot drift.
+    module ServiceCatalog
+      # The fold scope: root inputs, caller-supplied overrides, and hash
+      # access to already-constructed entries. Service constants referenced
+      # inside builders resolve lazily (at fold time), so catalog load order
+      # carries no construction coupling.
+      class Scope
+        attr_reader :root_dir, :built
+
+        def initialize(root_dir:, overrides:)
+          @root_dir = root_dir
+          @overrides = overrides
+          @built = {}
+        end
+
+        def override_for(name)
+          @overrides[name]
+        end
+
+        def store(name, instance)
+          @built[name] = instance
+        end
+
+        # Forward-reference guard: a builder reaching for a service the fold
+        # has not produced yet fails here, loudly, instead of silently
+        # threading nil downstream. Overrides are visible immediately (an
+        # injected part IS the value its entry will adopt).
+        def [](name)
+          return @built[name] if @built.key?(name)
+          return @overrides[name] if @overrides.key?(name)
+
+          raise KeyError, "ServiceCatalog: :#{name} is not constructed yet — ordered later in the catalog (or missing)"
+        end
+
+        # instance_variable_get (not the home_dir reader) is kept verbatim
+        # from the pre-catalog Shell#initialize: it tolerates duck-typed
+        # configs without the reader.
+        def home_dir
+          @home_dir ||= self[:config]&.instance_variable_get(:@home_dir) || ENV.fetch("HOME", nil)
+        end
+      end
+
+      DEFINITION = Rubik::Runtime::ServiceDefinition
+
+      ENTRIES = [
+        DEFINITION.new(
+          name: :config,
+          builder: ->(s) { Rubik::Config.new(root_dir: s.root_dir) },
+          provide: Rubik::Coeffects::CONFIG
+        ),
+        DEFINITION.new(
+          name: :dmesg,
+          builder: ->(_s) { Rubik::Kernel::Dmesg.new },
+          provide: Rubik::Coeffects::DMESG
+        ),
+        DEFINITION.new(
+          name: :dispatcher,
+          builder: ->(s) { Rubik::Kernel::Dispatcher.new(dmesg: s[:dmesg]) },
+          provide: Rubik::Coeffects::DISPATCHER,
+          after_inject: lambda do |values, _parts, _injected|
+            dispatcher = values.fetch(:dispatcher)
+            values[:runtime_manager]&.context&.on_dispose { dispatcher.stop }
+          end
+        ),
+        DEFINITION.new(
+          name: :event_bus,
+          builder: ->(s) { Rubik::EventBus.new(dispatcher: s[:dispatcher]) },
+          provide: Rubik::Coeffects::EVENTS,
+          after_build: ->(s) { s[:config].event_bus = s[:event_bus] if s[:config].respond_to?(:event_bus=) }
+        ),
+        DEFINITION.new(name: :extra_roots, input: true,
+                       builder: ->(s) { Array(s[:config].fetch("workspace.additional_roots", [])).compact }),
+        DEFINITION.new(name: :allowed_ext_dirs, input: true,
+                       builder: ->(s) { Array(s[:config].fetch("workspace.allowed_external_dirs", [])).compact }),
+        DEFINITION.new(name: :allow_ext_writes, input: true,
+                       builder: ->(s) { s[:config].fetch("workspace.allow_external_writes", false) || false }),
+        # The ONE operator-policy guard (security.*) — built BEFORE every
+        # consumer below (buffer, mcp, sandbox runner, task manager) so they
+        # all share this instance. Live in-place mutation from !allow-cmd /
+        # !config (repl/config_wiring.rb) then reaches every verification
+        # path in the same session without restarts.
+        DEFINITION.new(
+          name: :guard,
+          builder: ->(s) { Rubik::Security::Guard.for_config(s[:config]) },
+          provide: Rubik::Coeffects::GUARD
+        ),
+        DEFINITION.new(
+          name: :buffer_manager,
+          builder: lambda do |s|
+            Rubik::Buffer::Manager.new(
+              root_dir: s.root_dir, additional_roots: s[:extra_roots],
+              allowed_external_dirs: s[:allowed_ext_dirs], allow_external_writes: s[:allow_ext_writes],
+              event_bus: s[:event_bus], config: s[:config], guard: s[:guard]
+            )
+          end,
+          provide: Rubik::Coeffects::BUFFER_MANAGER,
+          after_inject: lambda do |values, parts, injected_buffer|
+            next unless injected_buffer
+
+            # Injected-buffer post-wiring runs only on the buffer_manager
+            # kwarg route, where Composition did not own the manager's config.
+            bm = values.fetch(:buffer_manager)
+            (parts.extra_roots || []).each { |r| bm.add_root(r) }
+            (parts.allowed_ext_dirs || []).each { |d| bm.add_allowed_dir(d) if bm.respond_to?(:add_allowed_dir) }
+            bm.allow_external_writes = parts.allow_ext_writes if bm.respond_to?(:allow_external_writes=)
+          end
+        ),
+        DEFINITION.new(
+          name: :snapshot_store,
+          builder: lambda do |s|
+            Rubik::Buffer::SnapshotStore.new(storage_dir: File.join(s.home_dir, ".rubik", "snapshots",
+                                                                    File.basename(s.root_dir)))
+          end,
+          provide: Rubik::Coeffects::SNAPSHOT_STORE
+        ),
+        DEFINITION.new(
+          name: :cache_store,
+          builder: ->(s) { Rubik::AST::CacheStore.new(root_dir: s.root_dir, home_dir: s.home_dir) }
+        ),
+        DEFINITION.new(
+          name: :ast_graph,
+          # Provided into the context later, by Runtime::ASTService (Shell
+          # phase 4) — not by wire_runtime_context.
+          builder: ->(_s) { Rubik::AST::Graph.new },
+          # Sync load: cache is small (no bodies), symbols instantly
+          # available; the expensive walk/extract stays in the background
+          # warm-up phase.
+          after_inject: lambda do |values, _parts, _injected|
+            values.fetch(:ast_graph).load_from_cache(values.fetch(:cache_store))
+          end
+        ),
+        # Provided into the context later, by Runtime::IndexService (Shell
+        # phase 4) — not by wire_runtime_context.
+        DEFINITION.new(
+          name: :context_index,
+          builder: lambda do |s|
+            includes = Array(s[:config]&.fetch("context.include", [])).compact
+            excludes = Array(s[:config]&.fetch("context.exclude", [])).compact
+            Rubik::Context::Index.new(
+              root_dir: s.root_dir,
+              additional_roots: (s[:config].fetch("workspace.auto_index_additional", true) ? s[:extra_roots] : []),
+              includes: includes,
+              excludes: excludes,
+              native: s[:config]&.fetch("tools.native")
+            )
+          end
+        ),
+        DEFINITION.new(
+          name: :recorder,
+          # Absorb (storage.absorb_artifacts, default true): yeni oturumlar
+          # storage köküne yazılır — worktree .rubik/'sü temiz kalır; okuma
+          # tarafı (Session::Manager) her iki konumu da tarar.
+          builder: lambda { |s|
+            Rubik::Session::Recorder.new(root_dir: s.root_dir, home_dir: s.home_dir,
+                                         sessions_dir: Rubik::Storage::Layout.sessions_dir_for(s.root_dir, s[:config]))
+          }
+        ),
+        DEFINITION.new(
+          name: :adapter_registry,
+          builder: ->(_s) { Rubik::Adapter::Registry.new },
+          provide: Rubik::Coeffects::ADAPTER_REGISTRY
+        ),
+        DEFINITION.new(name: :llm_registry, builder: ->(s) { Rubik::LLM::Registry.new(s[:config]) }),
+        DEFINITION.new(
+          name: :router,
+          builder: ->(s) { Rubik::LLM::Router.new(config: s[:config], registry: s[:llm_registry]) },
+          provide: Rubik::Coeffects::ROUTER
+        ),
+        # The context owner every later entry wires into; provided to tools
+        # by constructor injection, never as a coeffect.
+        DEFINITION.new(name: :runtime_manager, builder: ->(_s) { Rubik::Runtime::Manager.new }),
+        DEFINITION.new(name: :overlay_storage,
+                       builder: ->(s) { Rubik::Runtime::OverlayStorage.new(root_dir: s.root_dir, home_dir: s.home_dir, guard: s[:guard]) }),
+        DEFINITION.new(
+          name: :lsp_manager,
+          builder: ->(s) { Rubik::LSP::Manager.new(config: s[:config], root_dir: s.root_dir) },
+          provide: Rubik::Coeffects::LSP_MANAGER,
+          after_inject: lambda do |values, _parts, _injected|
+            lsp = values.fetch(:lsp_manager)
+            values[:runtime_manager]&.context&.on_dispose { lsp&.stop_all }
+          end,
+          optional: true
+        ),
+        DEFINITION.new(
+          name: :mcp_manager,
+          builder: lambda do |s|
+            Rubik::MCP::Manager.new(config: s[:config], root_dir: s.root_dir,
+                                    runtime_manager: s[:runtime_manager], guard: s[:guard])
+          end,
+          provide: Rubik::Coeffects::MCP_MANAGER,
+          after_inject: lambda do |values, _parts, _injected|
+            mcp = values.fetch(:mcp_manager)
+            values[:runtime_manager]&.context&.on_dispose { mcp&.stop_all }
+          end,
+          optional: true
+        ),
+        DEFINITION.new(
+          name: :skill_manager,
+          builder: lambda do |s|
+            Rubik::Skills::Manager.new(config: s[:config], root_dir: s.root_dir, home_dir: s.home_dir,
+                                       runtime_context: s[:runtime_manager].context)
+          end,
+          provide: Rubik::Coeffects::SKILL_MANAGER,
+          optional: true
+        ),
+        # Provide key deliberately differs from the member name: third
+        # parties resolve "sandbox" (ctx.require / Coeffects bridge).
+        DEFINITION.new(
+          name: :sandbox_runner,
+          builder: lambda do |s|
+            Rubik::Sandbox::Runner.new(root_dir: s.root_dir, config: s[:config],
+                                       allowed_external_dirs: s[:allowed_ext_dirs], guard: s[:guard])
+          end,
+          provide: Rubik::Coeffects::SANDBOX_RUNNER
+        ),
+        DEFINITION.new(
+          name: :plugin_manager,
+          builder: ->(_s) { Rubik::Plugin::Manager.new },
+          provide: Rubik::Coeffects::PLUGIN_MANAGER,
+          reader: false
+        ),
+        DEFINITION.new(
+          name: :plugin_storage,
+          builder: lambda do |s|
+            defined?(Rubik::Plugin::Storage) ? Rubik::Plugin::Storage.new(root_dir: s.root_dir, home_dir: s.home_dir) : nil
+          end,
+          provide: Rubik::Coeffects::PLUGIN_STORAGE,
+          provide_from: :parts,
+          assign_ivar: false
+        ),
+        DEFINITION.new(
+          name: :task_manager,
+          builder: lambda do |s|
+            Rubik::Runtime::TaskManager.new(guard: s[:guard], context: s[:runtime_manager].context, root_dir: s.root_dir)
+          end,
+          provide: Rubik::Coeffects::TASK_MANAGER,
+          optional: true
+        ),
+        DEFINITION.new(
+          name: :subagent_supervisor,
+          builder: lambda do |s|
+            Rubik::Orchestrator::Subagent::Supervisor.new(
+              root_context: s[:runtime_manager].context,
+              buffer_manager: s[:buffer_manager],
+              tool_registry: nil,
+              provider: nil,
+              router: s[:router],
+              config: s[:config],
+              root_dir: s.root_dir,
+              event_bus: s[:event_bus]
+            )
+          end,
+          provide: Rubik::Coeffects::SUBAGENT_SUPERVISOR,
+          optional: true
+        ),
+        DEFINITION.new(
+          name: :init,
+          builder: lambda do |s|
+            Rubik::Kernel::Init.new(
+              context: s[:runtime_manager]&.context,
+              dmesg: s[:dmesg],
+              dispatcher: s[:dispatcher]
+            )
+          end,
+          provide: Rubik::Coeffects::INIT,
+          after_inject: lambda do |values, _parts, _injected|
+            init = values.fetch(:init)
+            values[:runtime_manager]&.context&.on_dispose { init.stop }
+            values[:task_manager].init = init if values[:task_manager].respond_to?(:init=)
+            values[:subagent_supervisor].init = init if values[:subagent_supervisor].respond_to?(:init=)
+          end
+        ),
+        # The shell identity itself — provided at wire time, never built.
+        DEFINITION.new(
+          name: :shell,
+          parts_member: false,
+          builder: nil,
+          provide: Rubik::Coeffects::SHELL,
+          provide_from: :self
+        )
+      ].each(&:freeze).freeze
+
+      class << self
+        def member_names
+          ENTRIES.reject { |e| e.parts_member == false }.map(&:name)
+        end
+
+        def parts_struct
+          Struct.new(*member_names, keyword_init: true)
+        end
+
+        def injectable
+          ENTRIES.select(&:injectable?)
+        end
+
+        def reader_names
+          ENTRIES.select(&:expose_reader?).map(&:name)
+        end
+
+        def provided
+          ENTRIES.select(&:provided?)
+        end
+
+        def wire_after_inject(values, parts = nil, injected_buffer: false)
+          rm = values[:runtime_manager]
+          unless rm&.instance_variable_get(:@_catalog_after_injected)
+            rm&.instance_variable_set(:@_catalog_after_injected, true)
+            injectable.each { |e| e.after_inject&.call(values, parts, injected_buffer) }
+          end
+          injectable.find { |e| e.name == :buffer_manager }&.after_inject&.call(values, parts, true) if injected_buffer
+        end
+
+        # The construction fold. Caller-supplied overrides (config, event_bus,
+        # buffer_manager, snapshot_store kwargs) adopt their entry verbatim;
+        # everything else runs its builder with the scope. after_build hooks
+        # run per-entry (the config.event_bus cross-wire).
+        def build(scope)
+          ENTRIES.each do |entry|
+            next if entry.parts_member == false
+
+            scope.store(entry.name, scope.override_for(entry.name) || entry.builder&.call(scope))
+            entry.after_build&.call(scope)
+          end
+          wire_after_inject(scope.built)
+          scope.built
+        end
+
+        # Wire provide rows, in catalog order. Order is inert at wire time:
+        # the runtime manager holds zero registered fibers until phase 4
+        # (register_runtime_services) and phase 3 (load_plugins) run — every
+        # reconcile_all inside Manager#provide iterates an empty fiber map.
+        def wire_rows(shell, parts)
+          provided.to_h do |entry|
+            [entry.provide, case entry.provide_from
+                            when :ivar  then shell.instance_variable_get(:"@#{entry.name}")
+                            when :parts then parts.respond_to?(entry.name) ? parts[entry.name] : nil
+                            when :self  then shell
+                            end]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubik/repl/setup_factories.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Rubik
+  module REPL
+    # Öneri 3 (Kademe 3): Shell'den ayrılan kurulum fabrikaları. build_tool_registry
+    # default araç kaydını enjekte edilen alt sistemlerle kurar; orchestrator_loop
+    # aktif loop fiber'ını erişir (yoksa / farklı opts ile yeniden kurar);
+    # build_orchestrator_loop route/provider çözümlemesiyle LoopService.build_loop
+    # fabrikasını çalıştırır.
+    # Durum Shell'de yaşar (@buffer_manager, @context_index, @ast_graph,
+    # @adapter_registry, @guard, @sandbox_runner, @overlay_storage,
+    # @runtime_manager, @lsp_manager, @config, @router); mixin yalnızca
+    # fabrika politikasını kodlar.
+    module SetupFactories
+      # Öneri 3 (Kademe 3): build_tool_registry / orchestrator_loop /
+      # build_orchestrator_loop, lib/rubik/repl/setup_factories.rb mixin'ine
+      # taşındı (araç kaydı kurulumu ve orchestrator loop fabrikaları).
+
+      def build_tool_registry
+        # Service slots (guard, adapters, ast, tasks, sandbox, supervisor)
+        # resolve through Tools::Services' triple chain — the wire phase
+        # already provided the session's own instances. context_index stays
+        # an explicit override: RunTestsTool consumes the RAW kwarg for
+        # language detection, which must be the session's index on this
+        # path (a nil silently defaults every project to the ruby adapter).
+        Rubik::Tools::Registry.build_default(
+          buffer_manager: @buffer_manager, context_index: @context_index,
+          shell: self, runtime_manager: @runtime_manager,
+          overlay_storage: @overlay_storage, lsp_manager: @lsp_manager,
+          config: @config, root_dir: Dir.pwd
+        )
+      end
+
+      def orchestrator_loop(opts = {})
+        fiber = @runtime_manager&.fibers&.[]("orchestrator_loop")
+        return fiber.instance if fiber && fiber.state == :active && fiber.instance && opts.empty?
+
+        build_orchestrator_loop(opts)
+      end
+
+      def build_orchestrator_loop(opts = {})
+        routed = if opts[:provider]
+                   nil
+                 else
+                   begin
+                     @router.route(task_type: opts[:task_type] || :auto, prompt: opts[:prompt])
+                   rescue => e
+                     Rubik::Platform.debug_warn("orchestrator loop route unavailable (coeffect fallback): #{e.class}: #{e.message}")
+                     nil
+                   end
+                 end
+        provider = opts[:provider] || routed&.fetch(:provider, nil) ||
+                   (@runtime_manager&.context.respond_to?(:get) ? Rubik::Coeffects.get(@runtime_manager.context, Rubik::Coeffects::LLM_CLIENT) : nil)
+        return nil unless provider
+
+        merged = opts.merge(
+          provider: provider,
+          model: opts[:model] || routed&.fetch(:model, nil),
+          context_limit: opts[:context_limit] || routed&.fetch(:context_limit, nil),
+          max_output_tokens: opts[:max_output_tokens] || routed&.fetch(:max_output_tokens, nil)
+        )
+        Rubik::Runtime::LoopService.build_loop(@runtime_manager&.context, shell: self, config: merged)
+      end
+    end
+  end
+end

data/lib/rubik/repl/shell.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require "reline"
+require "stringio"
+require_relative "command_parser"
+require_relative "command_context"
+require_relative "composition"
+require_relative "../coeffects"
+require_relative "hooks"
+require_relative "commands"
+require_relative "config_wiring"
+require_relative "tee_io"
+require_relative "interrupt_handler"
+require_relative "confirmations"
+require_relative "presentation"
+require_relative "turn_recorder"
+require_relative "lifecycle"
+require_relative "input_loop"
+require_relative "input_execution"
+require_relative "paste_support"
+require_relative "setup_factories"
+require_relative "ast_warmup"
+require_relative "../runtime"
+
+module Rubik
+  module REPL
+    class Shell
+      include Confirmations
+      include Presentation
+      include TurnRecorder
+      include Lifecycle
+      include InputLoop
+      include InputExecution
+      include PasteSupport
+      include SetupFactories
+      include AstWarmup
+
+      attr_accessor :output, :conversation_history, :conversation_route_stamp,
+                    :active_loop, :agent_caller, :terminal_guard
+      # Shell-owned readers (lifecycle state, not composed services).
+      attr_reader :commands, :hooks, :tool_registry, :input, :reline, :ui_theme,
+                  :ui_renderer, :config_cleanups, :indexer_thread
+      # Composed-service readers derive from the ServiceCatalog SSOT
+      # (Candidate 05): adding a service = Coeffects key + catalog entry,
+      # and the reader follows the entry. Guarded by test_service_catalog.
+      attr_reader(*ServiceCatalog.reader_names)
+
+      # Plan 63 Faz B/C: subsystem construction lives in Composition.build; the
+      # shell keeps only phased coordination below (inject → invariant → wire →
+      # register → sync → warm-up). initialize stays a ~15-line orchestrator.
+      def initialize(config: nil, event_bus: nil, buffer_manager: nil, snapshot_store: nil, output: $stdout, input: $stdin, reline: Reline, root_dir: nil,
+                     parts: nil, terminal_guard: nil)
+        parts ||= Composition.build(config: config, root_dir: root_dir, event_bus: event_bus,
+                                    buffer_manager: buffer_manager, snapshot_store: snapshot_store)
+        inject_parts(parts, injected_buffer: !buffer_manager.nil?)
+        @output = output
+        @input = input
+        @reline = reline
+        @terminal_guard = terminal_guard || TerminalGuard.new(
+          output: @output,
+          reline: @reline,
+          quiet: (@config.respond_to?(:fetch) ? @config.fetch("ui.quiet_notices", false) : false) == true
+        )
+        @hooks = Hooks.new
+        @commands = {}
+        @running = false
+        @dirty_turns = 0
+        # Plan 91 — set by the !paste command, consumed once by
+        # read_and_process_line to enter explicit paste mode.
+        @paste_requested = false
+        @conversation_history = []
+        # The in-flight Orchestrator::Loop during a free-text/goal turn, nil at
+        # idle. Set for the duration of a turn only (same-thread, synchronous
+        # tool execution); the ensure block in execute_free_text/goal clears it.
+        # NOT the runtime manager's orchestrator_loop fiber instance — that is
+        # a different, rebuilt-on-reprovide object no running turn is using.
+        @active_loop = nil
+
+        wire_runtime_context(parts)
+        load_plugins(parts)
+        register_runtime_services
+        build_and_provide_tool_registry
+        sync_ui
+        sync_default_llm_route
+        warm_up!
+      end
+
+      def sync_context_and_ast(files)
+        return unless files && !files.empty?
+
+        root_d = @buffer_manager&.root_dir || Dir.pwd
+        files.each do |rel_file|
+          @context_index.update_file(rel_file)
+          full_path = File.join(root_d, rel_file)
+          File.exist?(full_path) ? @ast_graph.index_file(full_path) : @ast_graph.remove_file(full_path)
+        end
+        @ast_graph.save_to_cache(@cache_store) if @cache_store
+      end
+
+      # Öneri 3 (Kademe 4): warm_ast_graph / stop_background_indexer /
+      # join_indexer_safely / perform_warm_ast_graph,
+      # lib/rubik/repl/ast_warmup.rb mixin'ine taşındı (AST grafiği ısınma ve
+      # arka plan indexer yaşam döngüsü).
+
+      def outline_for(file_path)
+        full_path = File.expand_path(file_path, @buffer_manager&.root_dir || Dir.pwd)
+        @ast_graph.index_file(full_path) if File.exist?(full_path) && !@ast_graph.file_symbols.key?(full_path)
+        @ast_graph.outline_for(file_path)
+      end
+
+      def symbol_definition(symbol_name)
+        res = @ast_graph.symbol_definition(symbol_name)
+        if res.nil? && @indexer_thread&.alive?
+          join_indexer_safely(0.2)
+          res = @ast_graph.symbol_definition(symbol_name)
+        end
+        res
+      end
+
+      def search_symbols(query)
+        join_indexer_safely(0.2) if @ast_graph.symbols.empty? && @indexer_thread&.alive?
+        @ast_graph.symbols.values.select { |sym| sym.name.downcase.include?(query.downcase) }
+      end
+
+      def register_command(name, description:, usage: nil, custom: false, audience: nil, &handler)
+        key = name.to_s.downcase.delete_prefix("!")
+        return false if custom && @commands.key?(key) && !@commands[key][:custom]
+
+        resolved = { human: :human, agent: :agent, both: :both }.fetch(audience || (custom ? :both : :human)) do
+          raise ArgumentError, "invalid audience: #{audience.inspect}"
+        end
+        @commands[key] = { description: description, usage: usage, handler: handler, custom: custom, audience: resolved }
+        true
+      end
+
+      def unregister_command(name)
+        @commands.delete(name.to_s.downcase.delete_prefix("!"))
+      end
+
+      def run(input_stream = nil)
+        @running = true
+
+        if input_stream
+          run_stream(input_stream)
+        else
+          run_interactive
+        end
+      end
+
+      def running?
+        !@running.nil? && @running
+      end
+
+      def stop
+        if @buffer_manager&.dirty? && (@config.nil? || @config.fetch("buffer.exit_guard", true) != false)
+          count = @buffer_manager.dirty_files.size
+          @output.puts "⚠️ Warning: You have #{count} unapplied dirty buffer change(s)! Run '!apply' to persist or '!diff' to review."
+        end
+        @ui_renderer&.spinner&.kill
+        stop_background_indexer
+        @config_cleanups&.reverse_each(&:call)
+        @config_cleanups = []
+        # Ordering is load-bearing: disposing the runtime manager drains the
+        # ctx.on_dispose inverses (including LSP and MCP stop_all, and the
+        # subagent-notice unsubscribe) BEFORE shutdown_all kills subagents,
+        # so kill-time completion events find no listener and never spam the
+        # terminal on exit. Subsequent stop_all calls are idempotent no-ops.
+        @runtime_manager&.dispose!
+        @subagent_supervisor&.shutdown_all
+        @lsp_manager&.stop_all
+        @mcp_manager&.stop_all
+        Rubik.current_shell = nil if Rubik.current_shell == self
+        Rubik.runtime_manager = nil if Rubik.runtime_manager == @runtime_manager
+        @running = false
+      end
+      alias close stop
+      alias dispose stop
+
+      # Parses and dispatches a single line of REPL input to the appropriate handler.
+      #
+      # @param input_text [String] the raw input line from the user
+      # @return [void]
+      def execute_input(input_text)
+        parsed = CommandParser.parse(input_text)
+        @recorder.record(parsed.type, input_text) if !@replaying && parsed.type != :empty && parsed.type != :prompt
+
+        case parsed.type
+        when :empty
+          # noop
+        when :command
+          execute_command(parsed)
+        when :prompt
+          execute_free_text(parsed.raw)
+        end
+
+        check_dirty_buffer_reminder unless @replaying
+      end
+
+      def check_dirty_buffer_reminder
+        return unless @buffer_manager
+
+        if @buffer_manager.dirty?
+          @dirty_turns += 1
+          interval = @config.fetch("buffer.reminder_interval", 3).to_i
+          if interval.positive? && @dirty_turns >= interval
+            count = @buffer_manager.dirty_files.size
+            @output.puts "💡 [Rubik::Buffer] #{count} unapplied file modification(s) in buffer. Run '!diff' to review or '!apply' to persist to disk."
+            @dirty_turns = 0
+          end
+        else
+          @dirty_turns = 0
+        end
+      end
+
+      def allowed_external_dirs
+        @buffer_manager&.allowed_external_dirs || []
+      end
+
+      # Öneri 3 (Kademe 2): with_output / capture_output / execute_command /
+      # execute_free_text, lib/rubik/repl/input_execution.rb mixin'ine taşındı
+      # (I/O geçişi, bang-komut dispatch'i, serbest metin turn yaşam döngüsü).
+      # Öneri 3 (Kademe 3): build_tool_registry / orchestrator_loop /
+      # build_orchestrator_loop, lib/rubik/repl/setup_factories.rb mixin'ine
+      # taşındı (araç kaydı kurulumu ve orchestrator loop fabrikaları).
+
+      def register_default_commands
+        Rubik::REPL::Commands.register_all(self)
+      end
+    end
+  end
+end