rubik 0.1.0

data/lib/rubik/prompt/services.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Prompt
+    # Frozen-in view of everything the prompt renderer needs (architecture
+    # review 2026-10-01, candidate 2). Unlike Tools::Services there is NO
+    # fresh tier and NO coeffect lookup here: the prompt layer never
+    # constructs services (a Guard/Sandbox built here would be policy the
+    # caller never granted) and never resolves coeffects — the orchestrator
+    # resolves, the prompt renders. Unsatisfied slots degrade to empty
+    # sections, exactly matching the builder's historical nil-tolerant
+    # rendering.
+    #
+    # Owns: the slot list (the Struct members are the SSOT) and its frozen
+    # snapshot semantics.
+    # Leaves: where values come from — the composition root builds the
+    # view (from_shell / explicit kwargs); coeffect resolution (skills
+    # index, type registry) stays in the orchestrator.
+    Services = Struct.new(
+      :config, :commands, :buffer_manager, :snapshot_store, :context_index,
+      :lsp_manager, :skills_index, :type_registry, :context_limit,
+      :max_output_tokens, :root_dir, :extra_context,
+      keyword_init: true
+    ) do
+      def initialize(config: nil, commands: nil, buffer_manager: nil, snapshot_store: nil, context_index: nil,
+                     lsp_manager: nil, skills_index: nil, type_registry: nil, context_limit: nil,
+                     max_output_tokens: nil, root_dir: Dir.pwd, extra_context: "")
+        super
+        freeze
+      end
+
+      # Reader-only shell view: a public reader contributes its value, a
+      # reader-less duck type contributes nothing (graceful degradation,
+      # never a raise — an ivar without a reader is invisible here, by
+      # design). Explicit non-nil overrides beat shell readers, preserving
+      # the historical kwarg-over-shell precedence
+      # (test_from_shell_overrides_beat_shell_readers).
+      # root_dir/context_limit/max_output_tokens/skills_index/extra_context
+      # are per-run values, not shell state — they arrive via overrides.
+      def self.from_shell(shell, **overrides)
+        base = {
+          config: reader(shell, :config),
+          commands: reader(shell, :commands),
+          buffer_manager: reader(shell, :buffer_manager),
+          snapshot_store: reader(shell, :snapshot_store),
+          context_index: reader(shell, :context_index),
+          lsp_manager: reader(shell, :lsp_manager),
+          type_registry: reader(shell, :subagent_supervisor)&.type_registry
+        }
+        new(**base, **overrides.compact)
+      end
+
+      def self.reader(shell, name)
+        shell.respond_to?(name) ? shell.public_send(name) : nil
+      end
+
+      private_class_method :reader
+    end
+  end
+end

data/lib/rubik/prompt/token_estimator.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../platform"
+require_relative "conversation_rows"
+
+module Rubik
+  module Prompt
+    module TokenEstimator
+      CHARS_PER_TOKEN = 3.8
+
+      module_function
+
+      def estimate_text(text)
+        return 0 if text.nil?
+
+        str = text.to_s
+        return 0 if str.empty?
+
+        (str.length / CHARS_PER_TOKEN).ceil
+      end
+
+      def estimate_message(msg)
+        return 0 unless ConversationRows.row?(msg)
+
+        tokens = 4 # Base message overhead (role delimiter, headers)
+        role = ConversationRows.value_of(msg, :role)
+        tokens += estimate_text(role) if role
+
+        content = ConversationRows.value_of(msg, :content)
+        tokens += estimate_text(content) if content
+
+        tool_calls = msg[:tool_calls] || msg["tool_calls"]
+        if tool_calls && !tool_calls.empty?
+          tool_calls_str = tool_calls.is_a?(String) ? Rubik::Platform.clean_utf8(tool_calls) : Rubik::Platform.safe_json_generate(tool_calls)
+          tokens += estimate_text(tool_calls_str)
+        end
+
+        tool_call_id = msg[:tool_call_id] || msg["tool_call_id"]
+        tokens += estimate_text(tool_call_id) if tool_call_id
+
+        tool_name = msg[:tool_name] || msg["tool_name"]
+        tokens += estimate_text(tool_name) if tool_name
+
+        tokens
+      end
+
+      def estimate_history(messages)
+        return 0 unless messages.is_a?(Array)
+
+        messages.sum { |msg| estimate_message(msg) }
+      end
+
+      def estimate_tool_schemas(schemas)
+        return 0 if schemas.nil?
+        return 0 if schemas.respond_to?(:empty?) && schemas.empty?
+
+        json_str = schemas.is_a?(String) ? Rubik::Platform.clean_utf8(schemas) : Rubik::Platform.safe_json_generate(schemas)
+        estimate_text(json_str)
+      end
+    end
+  end
+end

data/lib/rubik/prompt/tool_teachings.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Prompt
+    # Tool teachings keyed by canonical tool name (architecture review
+    # 2026-10-01, candidate 1): the sentences that teach HOW a specific tool
+    # is used live here, one key per tool, instead of being embedded unnamed
+    # in Doctrine.operational_rules_xml's heredoc. Identity (the tool) lives in
+    # its Tools::Declaration; prose (the presentation) lives here — a prompt
+    # layer concern. test_tool_teachings welds the two: every key must
+    # resolve to a declared (Catalog) tool, so a rename that forgets the
+    # prompt fails the suite.
+    #
+    # The strings are interpolated into the operational rules HEREDOC at the
+    # same positions they originally occupied — the rendered rules are
+    # byte-identical (pinned by the substring tests in
+    # test_structured_context_builder, test_agent_command_contract,
+    # test_buffer_apply_conflict, test_repl_tool_separation_and_guardrails).
+    module ToolTeachings
+      TEACHINGS = {
+        "replace_file_content" =>
+          "For modifying existing files, prefer `replace_file_content` with exact verbatim `target_content` " \
+          "(or `old_content`) and `replacement_content` (or `new_content`).",
+        "write_file" =>
+          "For creating new files or completely rewriting files, use `write_file`.",
+        "apply_buffer" =>
+          "All edits stage safely into the in-memory buffer. Call `apply_buffer` to persist buffer edits to disk. " \
+          "If `apply_buffer` reports `[CONFLICT]` due to external modifications (e.g. from code formatters or " \
+          "external processes), inspect latest disk changes with `read_file(path: \"...\", reload: true)` or " \
+          "overwrite deliberately with `apply_buffer(force: true)`.",
+        "synthesize_tool" =>
+          "When you need a specialized capability not available in the built-in toolbelt (such as custom AST " \
+          "transformers, data converters, or domain-specific benchmarkers), dynamically create and register your " \
+          "own tool at runtime using `synthesize_tool(name: '...', description: '...', code: '->(args) { ... }')`.",
+        "storage" =>
+          "Persist agent workfiles — goals, plans, memory notes, wiki knowledge, reviews — in the central " \
+          "`storage` database (`storage` tool: put/get/list/search/set_ref/delete), NOT as scattered files in " \
+          "the repository worktree. Read entities back with `read_file(path: 'rubik://storage/<type>/<id>')`; " \
+          "browse with `rubik://storage/index` and `rubik://storage/<type>` listings.",
+        "run_command" =>
+          "GitHub facts must be verified, not assumed: after `gh pr merge` (which can succeed with EMPTY output) " \
+          "confirm the merge with `gh pr view <number> --json state`; `mergeable: UNKNOWN` right after a push means " \
+          "GitHub is still recomputing — wait briefly and re-check instead of rebasing; `gh pr checks` exits 1 both " \
+          "for failing checks and for repos with no CI — disambiguate with `gh pr view --json statusCheckRollup`. " \
+          "In repos that intentionally commit no lockfile, install dependencies with `npm install --no-package-lock` " \
+          "(or the package manager's equivalent) so setup does not dirty the worktree with a new lockfile.",
+        "show_file" =>
+          "When the user asks to SEE a stored entity (review report, plan, ...), use " \
+          "`show_file(path: 'rubik://storage/...')` — it renders the full content directly to their terminal " \
+          "while your context stays lean; only fall back to read_file when YOU must reason about the content.",
+        "vakanuvis" =>
+          "The background chronicler keeps compiled knowledge (memory cards, wiki pages) in rubik://storage. " \
+          "At task start — and again after any compaction — ask it with `vakanuvis(action: 'recall', query: '...')` " \
+          "instead of pre-loading pages: it returns a deterministic digest plus rubik:// source links. When " \
+          "dispatching a subagent, paste the relevant recall digest (or its rubik:// link) into the task brief. " \
+          "At the end of a task, persist only the durable knowledge with `vakanuvis(action: 'record', topic: '...', " \
+          "body: '...')` — memory writes go through record (ref minting, upsert, supersede come free), never " \
+          "through raw storage puts. Recall is keyword-AND over card/page text, so END every recorded body and " \
+          "digest query with its own vocabulary: include a `Keywords:` line listing 5-10 synonyms in BOTH working " \
+          "languages (e.g. TR + EN) — a Turkish query cannot otherwise find an English page. If recall is too " \
+          "shallow, queue `vakanuvis(action: 'digest', query: '...')`: it returns a deterministic receipt and " \
+          "compiles the wiki page asynchronously. Make the session close a standard digest point: review the " \
+          "session's new cards, queue one digest per open topic, and let the home index refresh.",
+        "prune_context" =>
+          "When long sessions leave stale exploration and superseded tool output weighing on the ROOT window, " \
+          "check `prune_context(action: 'status')` (window estimate vs ceiling, staged plan state) and force a " \
+          "cleanup with `prune_context(action: 'prune', reason: '...')`: it queues an LLM-proposed, " \
+          "harness-validated keep/drop/summarize plan that applies at the NEXT turn boundary — the call returns " \
+          "a deterministic receipt and never blocks. Goal/task statements, decisions and recent context are " \
+          "always preserved; deterministic compaction remains the emergency safety net."
+      }.freeze
+
+      module_function
+
+      def teaching_for(tool_name) = TEACHINGS[tool_name.to_s]
+    end
+  end
+end

data/lib/rubik/prompt.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "prompt/context_builder"
+require_relative "prompt/doctrine"
+require_relative "prompt/services"
+require_relative "prompt/token_estimator"
+require_relative "prompt/context_compactor"
+require_relative "prompt/emergency_compactor"
+
+module Rubik
+  module Prompt
+  end
+end

data/lib/rubik/repair/loop.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "json"
+require "tempfile"
+
+module Rubik
+  module Repair
+    class Loop
+      attr_reader :max_attempts, :attempts_made, :config
+
+      def initialize(provider:, buffer_manager:, snapshot_store:, adapter_registry:, max_attempts: nil, config: nil)
+        @provider = provider
+        @buffer_manager = buffer_manager
+        @snapshot_store = snapshot_store
+        @adapter_registry = adapter_registry
+        @config = config
+        @max_attempts = (max_attempts || config&.fetch("repair.max_attempts", 3) || 3).to_i
+        @attempts_made = 0
+      end
+
+      def repair(diagnostics, target_file, lang = :ruby)
+        @attempts_made = 0
+        current_diag = diagnostics
+
+        while @attempts_made < @max_attempts
+          @attempts_made += 1
+
+          @snapshot_store.create_snapshot(@buffer_manager)
+
+          prompt = build_repair_prompt(current_diag, target_file, @attempts_made)
+          res = @provider.complete([{ role: "user", content: prompt }])
+          proposed_code = extract_code(res.text)
+
+          @buffer_manager.write(target_file, proposed_code)
+
+          # Verify syntax against in-memory buffer via tempfile
+          check_res = check_buffer_syntax(target_file, lang)
+
+          return { ok: true, attempts: @attempts_made, code: proposed_code } if check_res[:ok]
+
+          current_diag = Rubik::Diagnostics::Parser.parse(check_res[:output], lang)
+          @snapshot_store.undo(@buffer_manager)
+
+        end
+
+        { ok: false, attempts: @attempts_made, last_diagnostics: current_diag }
+      end
+
+      private
+
+      def check_buffer_syntax(target_file, lang)
+        adapter = @adapter_registry.get(lang.to_s)
+        return { ok: true } unless adapter
+
+        content = @buffer_manager.read(target_file)
+        ext = File.extname(target_file)
+
+        Tempfile.create(["rubik_repair_", ext]) do |tmp|
+          tmp.write(content)
+          tmp.flush
+          adapter.check_syntax(tmp.path)
+        end
+      end
+
+      def build_repair_prompt(diagnostics, target_file, attempt_num)
+        diag_str = diagnostics.map { |d| d.format_prompt_snippet(nil, @buffer_manager.root_dir, @buffer_manager) }.join("\n\n")
+        current_content = @buffer_manager.read(target_file) || ""
+
+        <<~PROMPT
+          You are repairing code that failed with compiler/test errors.
+          Attempt #{attempt_num} of #{@max_attempts}.
+
+          Target File: #{target_file}
+          Current Content:
+          ```
+          #{current_content}
+          ```
+
+          Diagnostics:
+          #{diag_str}
+
+          Output ONLY the corrected code for #{target_file} wrapped in ```code``` blocks.
+        PROMPT
+      end
+
+      def extract_code(text)
+        if text.include?("```")
+          text.split("```").at(1).to_s.sub(/^[a-z]+\n/, "").strip
+        else
+          text.strip
+        end
+      end
+    end
+  end
+end

data/lib/rubik/repair.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "repair/loop"
+
+module Rubik
+  module Repair
+  end
+end

data/lib/rubik/repl/ast_warmup.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Rubik
+  module REPL
+    # Öneri 3 (Kademe 4): Shell'den ayrılan AST ısınma bloğu. warm_ast_graph
+    # ısınmayı senkron ya da arka plan thread'inde tetikler; stop_background_indexer
+    # ve join_indexer_safely indexer thread'inin çökmesiz teardown'unu (Audit 1)
+    # sağlar; perform_warm_ast_graph delta tarama → indeksleme → stale temizliği →
+    # cache kalıcılığı zincirini yürütür.
+    # Durum Shell'de yaşar (@indexer_thread, @buffer_manager, @context_index,
+    # @ast_graph, @cache_store, @logger, @event_bus); mixin yalnızca ısınma
+    # politikasını kodlar.
+    module AstWarmup
+      # Ö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 warm_ast_graph(async: true)
+        if async
+          stop_background_indexer
+          # Reset the cooperative-stop flag so repeated warm cycles behave the
+          # same as the first (per-turn scopes, MCP reconnects, tool epochs).
+          @indexer_stop_requested = false
+          @indexer_thread = Thread.new do
+            perform_warm_ast_graph
+          rescue StandardError => e
+            @logger&.warn("AST graph background indexer thread error: #{e.class}: #{e.message}")
+          end
+          ctx = @runtime_manager&.context || (respond_to?(:context) ? context : nil)
+          if ctx.respond_to?(:register_disposable) && ctx != @indexer_disposable_ctx
+            @indexer_disposable_ctx = ctx
+            ctx.register_disposable { stop_background_indexer }
+          end
+        else
+          perform_warm_ast_graph
+        end
+      end
+
+      # Single-homed "workspace roots changed → resync index → re-warm AST"
+      # sequence (formerly hand-wired in !workspace add/remove and reactive
+      # config wiring). sync_roots already performs additional_roots= +
+      # full_scan + fiber reconcile; the sync re-warm keeps symbols fresh
+      # before control returns to the caller.
+      def sync_workspace_index!
+        return unless @context_index
+
+        Rubik::Runtime::IndexService.sync_roots(
+          @runtime_manager, @context_index,
+          additional_roots: @buffer_manager&.additional_roots,
+          ast_graph: @ast_graph, cache_store: @cache_store
+        )
+        warm_ast_graph(async: false)
+      end
+
+      # Audit 1: teardown/join of the background indexer never crashes shutdown
+      # or blocks symbol lookups; detail surfaced via debug_warn. The bounded
+      # join mechanics live in Concurrency::Join; the failure log channel
+      # stays here.
+      #
+      # Cooperative cancellation, NOT Thread#kill: a one-shot warm cycle may run
+      # perform_warm_ast_graph's delta-scan -> index -> purge -> save_to_cache
+      # chain, and #kill would abort it between save_to_cache and completion,
+      # leaving a partially written / inconsistent cache (AGENTS.md §5 leaked
+      # side-effects + partial-write). The worker checks @indexer_stop_requested
+      # before committing the cache; here we only request + graceful-join.
+      def stop_background_indexer
+        return unless @indexer_thread
+
+        @indexer_stop_requested = true
+        join_indexer_safely
+        @indexer_thread = nil unless @indexer_thread&.alive?
+      rescue StandardError => e
+        debug_warn("Background AST indexer teardown failed: #{e.class}: #{e.message}")
+        nil
+      end
+
+      def join_indexer_safely(timeout = nil)
+        result = Rubik::Concurrency::Join.thread(@indexer_thread, timeout: timeout)
+        debug_warn("Background AST indexer join failed: #{result.class}: #{result.message}") if result.is_a?(StandardError)
+        nil
+      end
+
+      def perform_warm_ast_graph
+        root_d = @buffer_manager&.root_dir || Dir.pwd
+        delta = @context_index.incremental_scan
+        indexed_files = @ast_graph.file_symbols.keys
+
+        files_to_index = (delta[:added] + delta[:modified]).dup
+
+        @context_index.files.each_key do |rel_file|
+          break if @indexer_stop_requested
+
+          full_path = File.join(root_d, rel_file)
+          ext = File.extname(rel_file).downcase
+          files_to_index << rel_file if Rubik::AST::Extractor.supported_extensions.include?(ext) && !(indexed_files.include?(full_path) || indexed_files.include?(rel_file))
+        end
+
+        files_to_index.uniq.each do |rel_file|
+          break if @indexer_stop_requested
+
+          full_path = File.join(root_d, rel_file)
+          ext = File.extname(rel_file).downcase
+          @ast_graph.index_file(full_path) if Rubik::AST::Extractor.supported_extensions.include?(ext) && File.exist?(full_path)
+        end
+
+        delta[:deleted].each do |rel_file|
+          break if @indexer_stop_requested
+
+          full_path = File.join(root_d, rel_file)
+          @ast_graph.remove_file(full_path)
+        end
+
+        return if @indexer_stop_requested
+
+        purged = Rubik::Runtime::ASTService.purge_stale_entries!(@ast_graph, @context_index, root_d)
+
+        if @cache_store && File.directory?(root_d) && !@indexer_stop_requested &&
+           (!files_to_index.empty? || !delta[:deleted].empty? || purged.positive?)
+          @ast_graph.save_to_cache(@cache_store)
+        end
+      rescue StandardError => e
+        @logger&.warn("AST graph warm failed: #{e.message}")
+        @event_bus&.emit(:ast_warm_failed, error: e.message)
+        nil
+      end
+    end
+  end
+end

data/lib/rubik/repl/command_context.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require_relative "service_catalog"
+require_relative "../session/replayer"
+
+module Rubik
+  module REPL
+    # Per-dispatch, closed view of the Shell for bang-command handlers —
+    # the §7.1 ShellDeps pattern applied to the command axis. Built inside
+    # InputExecution#execute_command, AFTER with_output has swapped the
+    # capture TeeIO in, so ctx.out is exactly the stream a handler should
+    # print to on both the human and the exec_repl_command path (recorder
+    # capture and LLM-history truncation keep working unchanged).
+    #
+    # Closed surface (frozen by test_command_context):
+    #   · out / output : the active (capture-aware) IO. `output` exists so
+    #     the UI collaborators (Panel / DiffViewer / Approvals) can take ctx
+    #     where they previously took the shell — structural duck, UI files
+    #     untouched.
+    #   · services     : derived from ServiceCatalog.reader_names — the SSOT.
+    #     Adding a catalog service extends ctx automatically; optional
+    #     services read as nil (no respond_to? probing).
+    #   · rebindable   : conversation_history / active_loop (get + set) and
+    #     conversation_route_stamp (write-only) — the ONLY Shell state a
+    #     command may rebind. Writers delegate to the Shell accessors; ctx
+    #     never shadows them.
+    #   · effects      : the named verbs below. Anything else raises
+    #     NoMethodError — extend deliberately, together with the freeze test
+    #     and the boundary guard.
+    #
+    # Handlers are invoked as handler.call(args, ctx). There is no
+    # register_command, no ivar access and no method_missing: the interface
+    # a command sees is exactly this list.
+    class CommandContext
+      # Shell-owned readers outside the catalog (lifecycle state, table, IO).
+      SHELL_READERS = [:indexer_thread, :input, :commands].freeze
+
+      # Derived from the SSOT at load time; frozen so the surface cannot
+      # grow ad hoc.
+      SERVICE_READERS = (ServiceCatalog.reader_names + SHELL_READERS).freeze
+
+      def initialize(shell)
+        @shell = shell
+      end
+
+      # Dynamic, NOT constructor-captured: with_output swaps @output before
+      # the handler runs, and refresh_ui! rebinds it afterwards — freezing
+      # the IO here would silently detach every command print from the
+      # capture/record seam.
+      def out
+        @shell.output
+      end
+      alias output out
+
+      # IO conveniences for stored 2-arity synthesized handlers whose source
+      # contract was ->(args, out) { out.puts ... }: they now receive ctx,
+      # so ctx itself must print.
+      def puts(*)
+        out.puts(*)
+      end
+
+      def print(*)
+        out.print(*)
+      end
+
+      def flush
+        out.flush if out.respond_to?(:flush)
+      end
+
+      SERVICE_READERS.each do |name|
+        define_method(name) { @shell.public_send(name) }
+      end
+
+      # Read-only inspection view (overrides the loop-generated reader):
+      # handlers may consult the command table (!help / !commands) but
+      # never mutate it — registrations belong to the shell's spine.
+      def commands
+        @shell.commands.dup.freeze
+      end
+
+      # Live presentation theme (re-resolved per call: refresh_ui! may swap
+      # the theme between registration and invocation).
+      def theme
+        @shell.theme
+      end
+
+      # ── Plugin coeffects (catalog entries expose no shell reader) ───────
+      def plugin_manager
+        coeffect(Rubik::Coeffects::PLUGIN_MANAGER)
+      end
+
+      def plugin_storage
+        coeffect(Rubik::Coeffects::PLUGIN_STORAGE)
+      end
+
+      # ── Rebindable conversation state (write-through delegation) ────────
+      def conversation_history
+        @shell.conversation_history
+      end
+
+      def conversation_history=(history)
+        @shell.conversation_history = history
+      end
+
+      def active_loop
+        @shell.active_loop
+      end
+
+      def active_loop=(loop_instance)
+        @shell.active_loop = loop_instance
+      end
+
+      def conversation_route_stamp=(stamp)
+        @shell.conversation_route_stamp = stamp
+      end
+
+      # Additional Shell readers commands legitimately consult (plain reads,
+      # no writers — see the rebindable block above for what IS writable).
+      def agent_caller
+        @shell.agent_caller
+      end
+
+      def current_model_spec
+        @shell.current_model_spec
+      end
+
+      # ── Command effects (named, closed; one-line delegations) ───────────
+      def stop
+        @shell.stop
+      end
+
+      def execute_free_text(text)
+        @shell.execute_free_text(text)
+      end
+
+      def resume_session(identifier = :latest)
+        @shell.resume_session(identifier)
+      end
+
+      def refresh_ui!
+        @shell.refresh_ui!
+      end
+
+      def render_step_event(step_info)
+        @shell.render_step_event(step_info)
+      end
+
+      def detect_git_branch
+        @shell.detect_git_branch
+      end
+
+      def sync_context_and_ast(files)
+        @shell.sync_context_and_ast(files)
+      end
+
+      def sync_workspace_index!
+        @shell.sync_workspace_index!
+      end
+
+      def resync_llm_route!
+        @shell.resync_llm_route!
+      end
+
+      def refresh_llm_registry!
+        @shell.refresh_llm_registry!
+      end
+
+      def trim_conversation_window!
+        @shell.trim_conversation_window!
+      end
+
+      # Pruner apply seam (goal yolu): aşamalı budama planını turn başında,
+      # orchestrator.run pencereyi tohumlamadan ÖNCE uygular (input_execution
+      # yolu Shell'e doğrudan çağırır; !goal buradan geçer).
+      def apply_staged_prune_plan!
+        @shell.apply_staged_prune_plan!
+      end
+
+      def ask_yes_no(prompt, default: "n")
+        @shell.ask_yes_no(prompt, default: default)
+      end
+
+      def orchestrator_loop(opts = {})
+        @shell.orchestrator_loop(opts)
+      end
+
+      def warm_ast_graph(async: true)
+        @shell.warm_ast_graph(async: async)
+      end
+
+      def build_tool_registry
+        @shell.build_tool_registry
+      end
+
+      def request_paste!
+        @shell.request_paste!
+      end
+
+      # The one whole-shell handoff a command may still make: the replayer
+      # plants @replaying on its receiver and re-enters execute_input, so it
+      # must own the real Shell — passing ctx would plant the flag on the
+      # wrong object and break replay suppression.
+      def session_replayer
+        Rubik::Session::Replayer.new(@shell)
+      end
+
+      private
+
+      def coeffect(key)
+        Rubik::Coeffects.get(@shell.runtime_manager&.context, key)
+      end
+    end
+  end
+end