rubik 0.3.3 → 0.3.5

data/lib/rubik/runtime/overlay_storage.rb

@@ -48,7 +48,10 @@ module Rubik
       end
 
       def manifest_path(dir)
-        File.join(dir, ".manifest.json")
+        ensure_valid_overlay_dir!(dir)
+        path = File.join(dir, ".manifest.json")
+        ensure_contained_path!(path, dir)
+        path
       end
 
       def load_manifest(dir)
@@ -56,7 +59,7 @@ module Rubik
         return {} unless File.exist?(path)
 
         JSON.parse(File.read(path))
-      rescue JSON::ParserError
+      rescue JSON::ParserError, ArgumentError
         {}
       end
 
@@ -73,6 +76,7 @@ module Rubik
       end
 
       def record_hash(dir, filename, scope)
+        ensure_valid_overlay_dir!(dir)
         if manifest_state(dir) == :corrupt
           # Bozuk manifesti sessizce "heal" etmek (yalnızca yeni kaydı yazmak) diğer
           # kayıtlı overlay'leri tahliye eder; bunun yerine kaydı reddet.
@@ -80,6 +84,7 @@ module Rubik
         end
 
         path = File.join(dir, filename)
+        ensure_contained_path!(path, dir)
         hash = Digest::SHA256.hexdigest(normalize_content(File.binread(path)))
         manifest = load_manifest(dir)
         manifest[filename] = {
@@ -93,6 +98,11 @@ module Rubik
       def verify_integrity(file_path, dir, bootstrap_eligible: false)
         return :trusted if trust_mode?
 
+        unless safe_path_under?(file_path, dir)
+          warn "[SECURITY] Path traversal attempt detected for overlay '#{file_path}'. Skipping."
+          return :rejected
+        end
+
         basename = File.basename(file_path)
         manifest = load_manifest(dir)
         current_content = File.exist?(file_path) ? File.binread(file_path) : ""
@@ -140,6 +150,8 @@ module Rubik
 
         filename = "#{clean_name.gsub(':', '_')}.rb"
         file_path = File.join(target_dir, filename)
+        ensure_contained_path!(file_path, target_dir)
+
         header = <<~RUBY
           # frozen_string_literal: true
           #{COMMAND_SENTINEL} !#{clean_name}
@@ -164,6 +176,7 @@ module Rubik
         target_dir = scope.to_sym == :global ? global_commands_dir : project_commands_dir
         filename = "#{clean_name.gsub(':', '_')}.rb"
         file_path = File.join(target_dir, filename)
+        ensure_contained_path!(file_path, target_dir)
 
         raise "cannot delete '#{filename}': .manifest.json in #{target_dir} is corrupt; delete it and re-record overlays" if manifest_state(target_dir) == :corrupt
 
@@ -190,8 +203,10 @@ module Rubik
 
           file_path = cmd_meta[:path]
           cmd_name = cmd_meta[:name]
+          target_dir = cmd_meta[:scope].to_sym == :global ? global_commands_dir : project_commands_dir
 
           begin
+            ensure_contained_path!(file_path, target_dir)
             code = File.read(file_path)
             eval_command(shell, cmd_name, code, cmd_meta[:scope])
             loaded << cmd_name
@@ -249,6 +264,8 @@ module Rubik
 
         filename = "#{clean_name}.rb"
         file_path = File.join(target_dir, filename)
+        ensure_contained_path!(file_path, target_dir)
+
         schema_json = params_schema ? JSON.dump(params_schema) : "{}"
         header = <<~RUBY
           # frozen_string_literal: true
@@ -278,6 +295,7 @@ module Rubik
         target_dir = scope.to_sym == :global ? global_tools_dir : project_tools_dir
         filename = "#{clean_name}.rb"
         file_path = File.join(target_dir, filename)
+        ensure_contained_path!(file_path, target_dir)
 
         raise "cannot delete '#{filename}': .manifest.json in #{target_dir} is corrupt; delete it and re-record overlays" if manifest_state(target_dir) == :corrupt
 
@@ -301,6 +319,10 @@ module Rubik
         list_tools.each do |t_meta|
           next if t_meta[:integrity] == :rejected
 
+          file_path = t_meta[:path]
+          target_dir = t_meta[:scope].to_sym == :global ? global_tools_dir : project_tools_dir
+          ensure_contained_path!(file_path, target_dir)
+
           code = File.read(t_meta[:path])
           tool_inst = eval_tool(t_meta[:name], code, t_meta[:scope])
           if tool_inst
@@ -357,6 +379,41 @@ module Rubik
 
       private
 
+      def ensure_valid_overlay_dir!(dir)
+        allowed = [
+          [project_commands_dir, @root_dir],
+          [global_commands_dir, @home_dir],
+          [project_tools_dir, @root_dir],
+          [global_tools_dir, @home_dir]
+        ]
+        valid = allowed.any? do |allowed_dir, trusted_root|
+          Platform.path_equal?(dir, allowed_dir) && Platform.resolved_path_under?(dir, trusted_root)
+        end
+        return if valid
+
+        raise ArgumentError, "Invalid overlay directory: #{dir}"
+      end
+
+      def ensure_contained_path!(path, parent_dir)
+        raise ArgumentError, "Path traversal attempt detected: #{path}" unless safe_path_under?(path, parent_dir)
+      end
+
+      def safe_path_under?(path, parent_dir)
+        return false if path.nil? || parent_dir.nil?
+
+        ensure_valid_overlay_dir!(parent_dir)
+
+        # Lexical containment check first
+        return false unless Platform.path_under?(path, parent_dir)
+
+        # If path exists or parent exists, also check resolved path containment
+        return Platform.resolved_path_under?(path, parent_dir) if File.exist?(path) || File.exist?(parent_dir)
+
+        true
+      rescue StandardError
+        false
+      end
+
       # Bootstrap kabul taramasında kullanılacak guard: kwarg'la geçilen örnek
       # (üretimde service catalog'un tek operatör-policy guard'ı) ya da lazy
       # default. Lazy çözüm bilinçli: overlay_storage.rb standalone require

data/lib/rubik/sandbox/driver/docker.rb

@@ -14,7 +14,7 @@ module Rubik
         DEFAULT_IMAGE = "rubik-sandbox:latest"
 
         def available?
-          !Rubik::Platform.which("docker").nil? && system("docker ps > #{Rubik::Platform.dev_null} 2>&1")
+          !Rubik::Platform.which("docker").nil? && system("docker", "ps", out: File::NULL, err: File::NULL)
         end
 
         def run(cmd, timeout: 15, chdir: Dir.pwd, allow_network: false, memory_limit_mb: 512, cpus: "1.0")
@@ -48,7 +48,7 @@ module Rubik
               error_message: "Docker sandbox error"
             )
           ensure
-            system("docker rm -f #{container_name} > #{Rubik::Platform.dev_null} 2>&1")
+            system("docker", "rm", "-f", container_name, out: File::NULL, err: File::NULL)
           end
 
           {

data/lib/rubik/session/replayer.rb

@@ -18,9 +18,8 @@ module Rubik
       def replay_file(session_file_path)
         return false unless File.exist?(session_file_path)
 
-        lines = File.readlines(session_file_path)
         @shell&.instance_variable_set(:@replaying, true)
-        lines.each do |line|
+        File.foreach(session_file_path) do |line|
           next if line.strip.empty?
 
           event = begin

data/lib/rubik/storage/store.rb

@@ -499,10 +499,11 @@ module Rubik
         # (elle düzenleme: "42", ["x"]) tüm tipi zehirlemesin.
         skipped = 0
         records = File.foreach(path, encoding: "UTF-8").filter_map do |line|
-          next if line.strip.empty?
+          line.strip!
+          next if line.empty?
 
           parsed = begin
-            JSON.parse(line.scrub)
+            JSON.parse(line.valid_encoding? ? line : line.scrub)
           rescue JSON::ParserError
             nil
           end

data/lib/rubik/storage/vakanuvis/distill_gate.rb

@@ -238,6 +238,10 @@ module Rubik
         # talebi olarak sunar. Tümü geçerse sayfanın eski gap notu
         # supersede edilir (öz-onarım kapanışı). Düzlem 1 sayfa metnini
         # ASLA düzenlemez — düzeltme daima bir sonraki derlemeye aittir.
+        def active_recall_hits(store, **)
+          store.search_ranked(**).reject { |record| record["status"] == Vocabulary::STATUS_SUPERSEDED }
+        end
+
         def run_recall_smoke(gate, proposal, page_id)
           checks = proposal.fetch("checks", [])
           return if checks.empty?
@@ -247,8 +251,8 @@ module Rubik
           # koşulmalı — ilk RECALL_LIMIT kayıt. 6. sıradaki sayfa maestro'ya
           # görünmüyorsa iska sayılmalı (öz-onarım döngüsü kör kalmasın).
           missed = checks.reject do |check|
-            gate.store.search_ranked(query: check, type: Harness::RECALL_TYPES)
-                .first(Harness::RECALL_LIMIT).any? { |r| r["id"] == page_id }
+            active_recall_hits(gate.store, query: check, type: Harness::RECALL_TYPES)
+              .first(Harness::RECALL_LIMIT).any? { |r| r["id"] == page_id }
           end
           if missed.empty?
             resolved = gate.store.get(type: "note", id: gap_ref)

data/lib/rubik/storage/vakanuvis/gate.rb

@@ -21,10 +21,15 @@ module Rubik
         # supervisor, event_bus ve sözlü girdiler dışarıdan verilir —
         # Harness'e ASLA geri dokunmaz.
         class Gate
+          DEFAULT_MAX_DIGEST_JOBS = 100
           attr_reader :store, :supervisor, :dmesg, :session_slug, :max_steps, :model
 
           def initialize(store:, max_steps:, session_slug:, supervisor: nil, dmesg: nil,
-                         event_bus: nil, enabled: true, model: nil)
+                         event_bus: nil, enabled: true, model: nil, max_digest_jobs: DEFAULT_MAX_DIGEST_JOBS)
+            raise ArgumentError, "max_digest_jobs must be a positive integer" unless max_digest_jobs.is_a?(Integer) && max_digest_jobs.positive?
+
+            @max_digest_jobs = max_digest_jobs
+            @digest_targets = {} # accepted targets retain their slot through harvest/retry
             @store = store
             @supervisor = supervisor
             @dmesg = dmesg
@@ -37,7 +42,7 @@ module Rubik
             @distillers = {}
             @lock = Mutex.new
             # v2 §4-V5: kirli işareti — son başarılı derlemeden bu yana KALICI
-            # içerik (memory+wiki+note satır ayak izi) değişmediyse toplu
+            # içerik (memory+wiki+note içerik ayak izi) değişmediyse toplu
             # damıtıcı doğmaz. Turn satırları ayak izini değiştirmez: saf
             # turn akışında derleme boşa yakılmaz.
             @compile_footprint = nil
@@ -54,19 +59,22 @@ module Rubik
             target = Vocabulary.wiki_ref(query)
             # v2 §4-V5: aynı hedefli iş zaten kuyrukta ya da uçuştaysa makbuz
             # 'already queued' varyantına düşer — çift doğum yok.
-            in_flight = @lock.synchronize do
-              busy = @pending_digests.any? { |j| j[:target] == target } ||
-                     @distillers.any? { |_id, j| j[:target] == target }
-              unless busy
-                @pending_digests << { query: query, target: target,
-                                      transcript_uris: source_transcript_uris }
-              end
-              busy
+            admission = @lock.synchronize do
+              next :duplicate if @digest_targets.key?(target)
+              next :full if @digest_targets.size >= @max_digest_jobs
+
+              @pending_digests << { query: query, target: target, transcript_uris: source_transcript_uris }
+              @digest_targets[target] = true
+              :accepted
             end
-            if in_flight
+            if admission == :duplicate
               return "Digest already queued for '#{target}' (#{AnnalWriter.one_line(query, 60)}): the chronicler is " \
                      "compiling it — recall it later with vakanuvis(action: 'recall', query: '...')."
             end
+            if admission == :full
+              return "Digest not accepted for '#{target}': capacity #{@max_digest_jobs} is full. " \
+                     "Existing jobs are preserved; retry after a digest finishes."
+            end
 
             spawned = spawn_job!(batch: false)
             DistillGate.receipt(query: query, target: target, spawned: !spawned.nil?)
@@ -122,6 +130,7 @@ module Rubik
               # gerçek değeri yaz (future harvest sembolleri sessiz kalmasın).
               Vakanuvis.log_via(@dmesg, :warn, "distiller ended with unexpected outcome=#{outcome.inspect} — dropped, store untouched")
             end
+            @lock.synchronize { @digest_targets.delete(job[:target]) } unless [:incomplete, :crashed].include?(outcome)
             outcome
           end
 
@@ -213,7 +222,7 @@ module Rubik
           end
 
           def restore_job(job)
-            @pending_digests.unshift(job) if job[:target]
+            @pending_digests.push(job) if job[:target]
           end
 
           def confirm(inst_id, job)
@@ -224,11 +233,23 @@ module Rubik
             @lock.synchronize { @compile_footprint.nil? || @compile_footprint != footprint }
           end
 
-          # Kalıcı içerik ayak izi: kart + sayfa + not (annal dahil) satır
-          # sayıları. Turn satırları mevcut annal notuna satır ekler, ayak
-          # izini değiştirmez — saf turn akışında derleme boşa yakılmaz.
+          # Kalıcı içerik ayak izi: sabit id + içerik hash'i + durum.
+          # Annal'ın yalnız turn satırları ayıklanır; diğer not değişiklikleri
+          # ve mevcut kart/sayfa güncellemeleri derleyiciyi yeniden kirletir.
           def footprint
-            ["memory", "wiki", "note"].sum { |t| @store.list(type: t).size }
+            ["memory", "wiki", "note"].flat_map do |type|
+              @store.list(type: type).sort_by(&:id).map do |summary|
+                record = @store.get(type: type, id: summary.id)
+                next [type, summary.id, nil] unless record
+
+                hash = record["hash"]
+                if type == "note" && (Vocabulary::ANNAL_TAGS - Array(record["tags"])).empty?
+                  body = record["body"].to_s.lines.grep_v(/\A- \[\d+\] turn .*\(event=turn\.\d+\.[^)]*\)\s*\z/).join.rstrip
+                  hash = Digest::SHA256.hexdigest([record["title"], body, record["tags"], record["links"]].to_json)
+                end
+                [type, summary.id, hash, record["status"]]
+              end
+            end
           end
 
           # Kaynak disiplini (v2 §4-V4): yalnız status=completed transcript

data/lib/rubik/storage/vakanuvis/harness.rb

@@ -63,7 +63,9 @@ module Rubik
           # (kurucu enjeksiyonu — gate Harness'e geri dokunmaz).
           @gate = DistillGate::Gate.new(store: @store, supervisor: @supervisor, dmesg: @dmesg,
                                         event_bus: @event_bus, enabled: @distiller_enabled,
-                                        max_steps: @max_steps, model: @model, session_slug: @session_slug)
+                                        max_steps: @max_steps, model: @model, session_slug: @session_slug,
+                                        max_digest_jobs: fetch_cfg("subagents.vakanuvis.max_digest_jobs",
+                                                                   DistillGate::Gate::DEFAULT_MAX_DIGEST_JOBS))
         end
 
         class << self
@@ -90,9 +92,13 @@ module Rubik
         # 2 saniyede durmazsa (yavaş bir flush/spawn içinde) kill gelir ve
         # işlenemeyen olay sayısı dmesg'e düşer — sessiz kayıp yok.
         def shutdown
-          @monitor.synchronize { @stopped = true }
-          @monitor.synchronize { @busy += 1 } # STOP işaretinin de işleniş sayılır
-          @queue.push(STOP)
+          @monitor.synchronize do
+            return if @stopped
+
+            @stopped = true
+            @busy += 1 # STOP işaretinin de işleniş sayılır
+            @queue.push(STOP)
+          end
           @worker&.join(2)
           if @worker&.alive?
             Vakanuvis.log_via(@dmesg, :warn, "worker did not stop in 2s — killing with #{queue_size} event(s) unprocessed")
@@ -114,17 +120,19 @@ module Rubik
         # ---- olay giriş kapıları (kworker thread'inde çağrılır) -----------
 
         def enqueue_event(kind, payload)
-          return false if stopped?
-
           unless payload.is_a?(Hash)
             Vakanuvis.log_via(@dmesg, :warn, "discarded non-hash #{kind} event (#{payload.class})")
             return false
           end
 
-          drop_oldest! if @queue.size >= @max_queue
-          @monitor.synchronize { @busy += 1 }
-          @queue.push([kind, payload])
-          true
+          @monitor.synchronize do
+            return false if @stopped
+
+            drop_oldest! if @queue.size >= @max_queue
+            @busy += 1
+            @queue.push([kind, payload])
+            true
+          end
         end
 
         def queue_size = @queue.size
@@ -142,7 +150,7 @@ module Rubik
 
           allowed = Array(types).map(&:to_s)
           allowed = RECALL_TYPES if allowed.empty?
-          hits = @store.search_ranked(query: q, type: allowed).first(RECALL_LIMIT)
+          hits = DistillGate.active_recall_hits(@store, query: q, type: allowed).first(RECALL_LIMIT)
           unless hits.empty?
             lines = hits.map { |r| recall_line(r) }
             header = "Recalled #{hits.size} entit#{hits.size == 1 ? 'y' : 'ies'} for '#{AnnalWriter.one_line(q, 80)}':"
@@ -186,8 +194,8 @@ module Rubik
                    "recall shows compiled pages; a submitted digest appears here until it compiles."
           end
 
-          "Digest queue: #{targets[:queued].size} queued (#{targets[:queued].join(', ')}), " \
-            "#{targets[:in_flight].size} in flight (#{targets[:in_flight].join(', ')})."
+          "Digest queue: #{targets[:queued].size} queued (#{digest_target_summary(targets[:queued])}), " \
+            "#{targets[:in_flight].size} in flight (#{digest_target_summary(targets[:in_flight])})."
         end
 
         # Soğuk-başlangıç yönelimi (issue #99 P2): ilk sorgu sözcük dağı
@@ -214,6 +222,12 @@ module Rubik
 
         private
 
+        def digest_target_summary(targets)
+          shown = targets.first(10)
+          shown << "+#{targets.size - 10} targets" if targets.size > 10
+          shown.join(", ")
+        end
+
         # v2 §4-V2 + issue #99 P2: AND boşluğu tek tip körlük değil — en
         # yakın kısmi eşleşmeler dürüstçe "(fallback)" damgasıyla sunulur
         # (gerçek eşleşme değildir), transcript izleri kapsam ipucu olarak
@@ -226,9 +240,8 @@ module Rubik
           # Süpersede edilmiş sayılar "en yakın kısmi eşleşme" olarak
           # sunulmaz (review M1) — emekli bir sayfayı okumaya davet etmek,
           # issue #100'ün "iki kopya, biri bozuk" bulgusunun aynısıdır.
-          relaxed = @store.search_ranked(query: q, type: allowed, require_all: false)
-                          .reject { |r| r["status"] == Vocabulary::STATUS_SUPERSEDED }
-                          .first(RECALL_FALLBACK_LIMIT)
+          relaxed = DistillGate.active_recall_hits(@store, query: q, type: allowed, require_all: false)
+                               .first(RECALL_FALLBACK_LIMIT)
           transcripts = @store.search(query: q, type: "transcript")
           if relaxed.empty? && transcripts.empty?
             return "No chronicled knowledge matches '#{AnnalWriter.one_line(q, 80)}'. Recall is keyword-AND: retry with " \
@@ -319,13 +332,15 @@ module Rubik
         end
 
         def handle_subagent(payload)
-          # Önce kronik (Düzlem 1 garantisi), sonra hasat (Düzlem 2): hasat
-          # patlarsa bile olayın annal satırı yazılmış olur — deterministik
-          # katman LLM katmanının hatasından zarar görmez.
+          # Önce kronik, sonra hasat; iki düzlemin hataları birbirini
+          # engellemez. Annal yazılamasa da digest tamamlanır/geri kuyruğa alınır.
           seq = next_seq
           line = AnnalWriter.subagent_line(seq, payload)
-          append_session([[event_key(payload), line]])
-          @gate.completion_event(payload)
+          begin
+            append_session([[event_key(payload), line]])
+          ensure
+            @gate.completion_event(payload)
+          end
           maintain if flush_due?
         end
 

data/lib/rubik/storage/vakanuvis/memory_steward.rb

@@ -136,10 +136,12 @@ module Rubik
         # `storage put type=memory` ile açılmış) satırları disipline
         # sokar — başlıktan slug türet, en yeni satıra mem.<slug> ref'i
         # bağla (bir sonraki record() artık O satırı günceller), aynı
-        # slug'a düşen eski kopyaları supersede et. Deterministik: sıra
+        # slug'a düşen eski kopyaları supersede et. Mevcut canonical ref
+        # her zaman korunur; kaçak kopyalar onun lehine emekli edilir. Deterministik: sıra
         # ve seçim yalnızca [row] üzerinden.
         def sweep_rogue_memory(store)
-          bound_ids = store.refs.select { |ref, _id| Vocabulary.memory_ref?(ref) }.values
+          bindings = store.refs.select { |ref, _id| Vocabulary.memory_ref?(ref) }
+          bound_ids = bindings.values
           rows = store.list(type: "memory").reject do |s|
             bound_ids.include?(s.id) || s.status == Vocabulary::STATUS_SUPERSEDED
           end
@@ -147,11 +149,15 @@ module Rubik
 
           swept = 0
           rows.group_by { |s| Vocabulary.slug(s.title) }.each do |slug, group|
-            winner = group.max_by(&:row)
-            store.set_ref(Vocabulary.memory_ref(slug), winner.id)
-            group.reject { |s| s.id == winner.id }.each do |s|
+            ref = Vocabulary.memory_ref(slug)
+            winner_id = bindings[ref]
+            unless winner_id
+              winner_id = group.max_by(&:row).id
+              store.set_ref(ref, winner_id)
+            end
+            group.reject { |s| s.id == winner_id }.each do |s|
               rogue = store.get(type: "memory", id: s.id)
-              Vakanuvis.supersede_record(store, rogue, by: winner.id) if rogue
+              Vakanuvis.supersede_record(store, rogue, by: winner_id) if rogue
             end
             swept += group.size
           end

data/lib/rubik/tools/builtins/lifecycle.rb

@@ -112,8 +112,12 @@ module Rubik
               description: "Language or service identifier (e.g., 'ruby', 'python', 'rust', 'go', 'zig', 'c', 'bash')"
             },
             proposed_command: {
-              type: "string",
-              description: "Replacement or custom command string (optional, probed automatically if auto_probe: true)"
+              oneOf: [{ type: "string" },
+                      { type: "object", properties: { executable: { type: "string" },
+                                                      args: { type: "array", items: { type: "string" } } },
+                        required: ["executable", "args"], additionalProperties: false },
+                      { type: "array", items: { type: "string" }, minItems: 1 }],
+              description: "Replacement command: a legacy string or, for LSP, {executable, args} / argv array. Omit to probe automatically."
             },
             probe_args: {
               type: "array", items: { type: "string" },
@@ -142,7 +146,14 @@ module Rubik
       def execute(args = {})
         target = (args["target"] || args[:target]).to_s.downcase.strip
         lang = (args["language_or_type"] || args[:language_or_type]).to_s.downcase.strip
-        proposed_cmd = (args["proposed_command"] || args[:proposed_command]).to_s.strip
+        raw_command = args["proposed_command"] || args[:proposed_command]
+        if raw_command.is_a?(Hash) || raw_command.is_a?(Array)
+          return ToolOutput.error("Structured command argv is supported only for LSP repairs.") unless target == "lsp"
+
+          proposed_cmd = raw_command
+        else
+          proposed_cmd = raw_command.to_s.strip
+        end
         auto_probe = if args["auto_probe"].nil?
                        args[:auto_probe].nil? || args[:auto_probe]
                      else
@@ -152,7 +163,7 @@ module Rubik
         return ToolOutput.error("Target and language_or_type must be provided.") if target.empty? || lang.empty?
 
         # 1. Automatic Probing if proposed_cmd is not specified or auto_probe is requested
-        if proposed_cmd.empty? && auto_probe
+        if !command_provided?(proposed_cmd) && auto_probe
           candidate = case target
                       when "lsp"
                         Rubik::Runtime::Discovery.probe_lsp(lang, root_dir: @root_dir)
@@ -179,7 +190,7 @@ module Rubik
           end
         end
 
-        return ToolOutput.error("No command provided or discovered for #{target} (#{lang}).") if proposed_cmd.empty?
+        return ToolOutput.error("No command provided or discovered for #{target} (#{lang}).") unless command_provided?(proposed_cmd)
 
         # 2. Pre-flight Verification in Isolated Sub-Context (ctx.extend())
         root_ctx = @runtime_manager&.context || Rubik::Runtime::Context.new
@@ -313,11 +324,11 @@ module Rubik
         end
 
         if @config.nil? && ["lsp", "test_runner", "linter"].include?(target)
-          return "⚠️ Promoted '#{proposed_cmd}' for #{target} (#{lang}) — no config is attached, " \
+          return "⚠️ Promoted '#{display_command(proposed_cmd)}' for #{target} (#{lang}) — no config is attached, " \
                  "so the command is active for this session only and was not saved."
         end
 
-        "✨ Successfully verified and promoted runtime service for #{target} (#{lang}): '#{proposed_cmd}'. " \
+        "✨ Successfully verified and promoted runtime service for #{target} (#{lang}): '#{display_command(proposed_cmd)}'. " \
           "Service is now active in the live context."
       end
 
@@ -326,6 +337,22 @@ module Rubik
       def verify_binary(target, lang, proposed_cmd, sub_ctx, probe_args: nil)
         Rubik::Runtime::RepairProbe.new(root_dir: @root_dir).verify(target, lang, proposed_cmd, sub_ctx, probe_args: probe_args)
       end
+
+      def command_provided?(command)
+        if command.is_a?(String)
+          !command.strip.empty?
+        elsif command.is_a?(Hash) || command.is_a?(Array)
+          !Rubik::LSP::ServerCommand.argv(command).empty?
+        else
+          false
+        end
+      rescue ArgumentError
+        false
+      end
+
+      def display_command(command)
+        command.is_a?(Hash) || command.is_a?(Array) ? Rubik::LSP::ServerCommand.display(command) : command.to_s
+      end
     end
 
     class FinishTool < BaseTool

data/lib/rubik/tools/builtins/lsp.rb

@@ -39,16 +39,32 @@ module Rubik
         @lsp_manager.sync_buffer_file_if_needed(path, bm) if bm && @lsp_manager.respond_to?(:sync_buffer_file_if_needed)
 
         if path.empty?
-          all = @lsp_manager.all_diagnostics
-          total_issues = all.values.flatten.size
+          all = @lsp_manager.all_diagnostic_snapshots
+          total_issues = all.values.sum { |snapshot| snapshot[:diagnostics].size }
+          pending = all.values.count { |snapshot| snapshot[:state] == :pending }
+          unversioned = all.values.count { |snapshot| snapshot[:state] == :unversioned }
           if total_issues.zero?
-            "No active LSP diagnostics across workspace (all clean)."
+            if pending.positive?
+              "LSP analysis pending for #{pending} workspace file(s); no clean result is available yet."
+            elsif unversioned.positive?
+              "No diagnostics were reported for #{unversioned} workspace file(s), but the server omitted document versions; freshness is unverified."
+            elsif all.empty?
+              "No active LSP diagnostics have been published for open workspace documents."
+            else
+              "No LSP diagnostics were reported for #{all.size} analyzed workspace file(s)."
+            end
           else
             lines = ["=== Active Workspace LSP Diagnostics (#{total_issues} issue(s)) ==="]
-            all.each do |fpath, diags|
+            all.each do |fpath, snapshot|
+              diags = snapshot[:diagnostics]
               next if diags.empty?
 
-              lines << "\nFile: #{fpath} (#{diags.size}):"
+              freshness = if snapshot[:state] == :pending
+                            "PENDING; previous results may be stale"
+                          else
+                            (snapshot[:state] == :unversioned ? "VERSION UNVERIFIED" : "current")
+                          end
+              lines << "\nFile: #{fpath} (#{diags.size}; #{freshness}):"
               diags.each do |d|
                 sev = d["severity"] == 1 ? "ERROR" : "WARN"
                 start_line = (d.dig("range", "start", "line") || 0) + 1
@@ -58,11 +74,23 @@ module Rubik
             lines.join("\n")
           end
         else
-          diags = @lsp_manager.diagnostics_for(path)
+          snapshot = @lsp_manager.diagnostics_snapshot_for(path)
+          diags = snapshot[:diagnostics]
           if diags.empty?
-            append_buffer_tip("No LSP diagnostics or errors for '#{path}'.", path)
+            message = case snapshot[:state]
+                      when :pending then "LSP analysis is pending for '#{path}'; no clean result is available yet."
+                      when :unversioned then "No LSP diagnostics were reported for '#{path}', but the server omitted document versions; freshness is unverified."
+                      when :fresh then "No LSP diagnostics or errors for '#{path}'."
+                      else "No LSP diagnostic result is available for '#{path}'."
+                      end
+            append_buffer_tip(message, path)
           else
-            lines = ["=== LSP Diagnostics for #{path} (#{diags.size} issue(s)) ==="]
+            freshness = if snapshot[:state] == :pending
+                          "pending; previous results may be stale"
+                        else
+                          (snapshot[:state] == :unversioned ? "version unverified" : "current")
+                        end
+            lines = ["=== LSP Diagnostics for #{path} (#{diags.size} issue(s); #{freshness}) ==="]
             diags.each do |d|
               sev = case d["severity"]
                     when 1 then "ERROR"