rubik 0.6.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -55,6 +55,7 @@ module Rubik
55
55
  @healthy_since = {}
56
56
  @recovery_errors = {}
57
57
  @registered_disposable_langs = {}
58
+ @client_inverses = {}
58
59
  @monitor = Monitor.new
59
60
  end
60
61
 
@@ -176,6 +177,8 @@ module Rubik
176
177
  else
177
178
  record_crash(lang_str)
178
179
  stop_client_safely(client)
180
+ @clients.delete(lang_str)
181
+ unregister_client_unlocked(lang_str)
179
182
  failure = Runtime::DiagnosticEngine.diagnose(
180
183
  cmd: ServerCommand.display(client.server_cmd),
181
184
  exit_code: 1,
@@ -238,6 +241,15 @@ module Rubik
238
241
  client.did_save(file_path, content)
239
242
  end
240
243
 
244
+ def did_close_file(file_path)
245
+ return false unless enabled?
246
+
247
+ client = client_for(file_path)
248
+ return false unless client&.running
249
+
250
+ client.did_close(file_path)
251
+ end
252
+
241
253
  def sync_buffer_file_if_needed(file_path, buffer_manager)
242
254
  return false unless enabled? && buffer_manager
243
255
 
@@ -455,24 +467,30 @@ module Rubik
455
467
  end
456
468
 
457
469
  def register_client_unlocked(lang, client)
470
+ lang_str = lang.to_s.downcase
458
471
  effective_ctx = @context || @runtime_manager&.context
459
472
  return unless effective_ctx
460
473
 
461
- effective_ctx.provide("lsp:#{lang}", client)
462
- return if @registered_disposable_langs[lang] == effective_ctx.object_id
474
+ effective_ctx.provide("lsp:#{lang_str}", client)
475
+ return if @registered_disposable_langs[lang_str] == effective_ctx.object_id
463
476
 
464
- @registered_disposable_langs[lang] = effective_ctx.object_id
465
- effective_ctx.register_disposable do
466
- current = @clients[lang]
477
+ inverse = effective_ctx.register_disposable do
478
+ current = @clients[lang_str]
467
479
  current.stop if current&.running
468
480
  end
481
+ @registered_disposable_langs[lang_str] = effective_ctx.object_id
482
+ @client_inverses[lang_str] = inverse
469
483
  end
470
484
 
471
485
  def unregister_client_unlocked(lang)
472
486
  lang_str = lang.to_s.downcase
473
487
  @registered_disposable_langs.delete(lang_str)
488
+ inverse = @client_inverses.delete(lang_str)
474
489
  effective_ctx = @context || @runtime_manager&.context
475
- effective_ctx&.unprovide("lsp:#{lang_str}") if effective_ctx.respond_to?(:unprovide)
490
+ return unless effective_ctx
491
+
492
+ effective_ctx.unprovide("lsp:#{lang_str}") if effective_ctx.respond_to?(:unprovide)
493
+ effective_ctx.unregister_disposable(inverse) if inverse && effective_ctx.respond_to?(:unregister_disposable)
476
494
  end
477
495
 
478
496
  def stop_client_safely(client)
@@ -36,8 +36,9 @@ module Rubik
36
36
  end
37
37
 
38
38
  def append_diagnostics(deps, written_file, tool_result)
39
+ timeout = deps.lsp_manager&.config&.fetch("lsp.feedback_timeout", 0.5) || 0.5
39
40
  snapshot = if deps.lsp_manager.respond_to?(:wait_for_diagnostics)
40
- deps.lsp_manager.wait_for_diagnostics(written_file, timeout: 0.2)
41
+ deps.lsp_manager.wait_for_diagnostics(written_file, timeout: timeout)
41
42
  else
42
43
  deps.lsp_manager.diagnostics_snapshot_for(written_file)
43
44
  end
@@ -5,6 +5,7 @@ require_relative "auto_apply"
5
5
  require_relative "tool_call_id"
6
6
  require_relative "tool_history"
7
7
  require_relative "tool_circuit_breaker"
8
+ require_relative "tool_timeout"
8
9
  require_relative "maestro_gate"
9
10
  require_relative "lsp_feedback"
10
11
 
@@ -160,11 +161,20 @@ module Rubik
160
161
  "circuit open for '#{tool_instance.name}' — repeated failures; waiting out the cooldown before retrying"
161
162
  end
162
163
 
163
- raw_output = tool_instance.execute(tool_args)
164
+ raw_output = ToolTimeout.call(tool_instance, config: @deps.shell&.config,
165
+ canonical_name: tool_instance.name) do
166
+ tool_instance.execute(tool_args)
167
+ end
164
168
  t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
165
169
  dur = ((t1 - t0) * 1000).round(1)
166
170
 
167
171
  normalize_raw_output(raw_output, tool_name, call_id, dur)
172
+ rescue ToolTimeout::BudgetExceeded => e
173
+ t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
174
+ dur = ((t1 - t0) * 1000).round(1)
175
+ ToolTimeout.emit_timeout_event(tool_name: tool_instance.name, budget_seconds: e.budget_seconds,
176
+ elapsed_seconds: e.elapsed_seconds, context: @deps.runtime_manager&.context)
177
+ ToolTimeout.timeout_result(tool_name: tool_name, call_id: call_id, exceeded: e, duration_ms: dur)
168
178
  rescue StandardError => e
169
179
  t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
170
180
  dur = ((t1 - t0) * 1000).round(1)
@@ -2,6 +2,7 @@
2
2
 
3
3
  require_relative "../../tools/truncator"
4
4
  require_relative "../../tools/result"
5
+ require_relative "../tool_timeout"
5
6
 
6
7
  module Rubik
7
8
  module Orchestrator
@@ -16,12 +17,20 @@ module Rubik
16
17
  def dispatch_subagent_tool(tool, name, args)
17
18
  return error_result(name, "Tool '#{name}' is not available in subagent toolset.") unless tool
18
19
 
19
- raw = tool.execute(args)
20
20
  cfg = @config.respond_to?(:fetch) ? @config : nil
21
+ raw = Rubik::Orchestrator::ToolTimeout.call(tool, config: cfg,
22
+ canonical_name: tool.respond_to?(:name) ? tool.name : name) do
23
+ tool.execute(args)
24
+ end
21
25
  max_chars = (cfg&.fetch("tools.max_output_chars", Rubik::Tools::Truncator::DEFAULT_MAX_CHARS) || Rubik::Tools::Truncator::DEFAULT_MAX_CHARS).to_i
22
26
  max_lines = (cfg&.fetch("tools.max_output_lines", Rubik::Tools::Truncator::DEFAULT_MAX_LINES) || Rubik::Tools::Truncator::DEFAULT_MAX_LINES).to_i
23
27
  strategy = Rubik::Tools::Truncator.resolve_strategy(cfg&.fetch("tools.truncation_strategy", Rubik::Tools::Truncator::DEFAULT_STRATEGY))
24
28
  normalize_tool_result(raw, name, max_chars: max_chars, max_lines: max_lines, strategy: strategy)
29
+ rescue Rubik::Orchestrator::ToolTimeout::BudgetExceeded => e
30
+ Rubik::Orchestrator::ToolTimeout.emit_timeout_event(tool_name: name, budget_seconds: e.budget_seconds,
31
+ elapsed_seconds: e.elapsed_seconds, context: @context)
32
+ Rubik::Orchestrator::ToolTimeout.timeout_result(tool_name: name, call_id: nil, exceeded: e,
33
+ duration_ms: (e.elapsed_seconds * 1000).round(1))
25
34
  rescue StandardError => e
26
35
  error_result(name, "Tool execution error: #{e.class}: #{e.message}", error: e.message)
27
36
  end
@@ -0,0 +1,193 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "../coeffects"
4
+ require_relative "../tools/result"
5
+
6
+ module Rubik
7
+ module Orchestrator
8
+ # Bounded tool execution behind `tools.call_timeout`. The dispatch seam
9
+ # runs the call on a worker thread and joins with the resolved budget.
10
+ # Ruby threads cannot be force-killed: an expired call is ABANDONED —
11
+ # it keeps running in the background and its result is discarded — so
12
+ # the budget bounds turn latency, not resource use. Budget off (nil)
13
+ # yields inline: byte-identical to the unwrapped seam.
14
+ module ToolTimeout
15
+ # Raised in the CALLER thread when the join budget expires. The
16
+ # dispatch seam's rescue converts it into an honest error Result so
17
+ # the turn continues.
18
+ class BudgetExceeded < StandardError
19
+ attr_reader :tool_name, :budget_seconds, :elapsed_seconds
20
+
21
+ def initialize(tool_name:, budget_seconds:, elapsed_seconds:)
22
+ @tool_name = tool_name
23
+ @budget_seconds = budget_seconds
24
+ @elapsed_seconds = elapsed_seconds
25
+ super("tool '#{tool_name}' exceeded the #{budget_seconds}s call budget")
26
+ end
27
+ end
28
+
29
+ ENV_KEY = "RUBIK_TOOLS_CALL_TIMEOUT"
30
+ OFF = :off
31
+
32
+ module_function
33
+
34
+ # Budget resolution precedence: an explicit env disable wins, then the
35
+ # per-tool override (off or budget), then the env / config global.
36
+ # Returns nil = off (inline execution).
37
+ def budget_for(config, canonical_name)
38
+ env = resolve_env_budget
39
+ return nil if env == OFF
40
+
41
+ override = resolve_override(config, canonical_name)
42
+ return nil if override == OFF
43
+ return override unless override.nil?
44
+
45
+ env.nil? ? resolve_config_budget(config) : env
46
+ end
47
+
48
+ # The seam entry point. budget nil ⇒ yield inline (no Thread.new — the
49
+ # "knob unset ⇒ byte-identical" contract; the tool is not even asked
50
+ # for its name). Otherwise the yield runs on a named worker thread; an
51
+ # expired join abandons the worker and raises BudgetExceeded in the
52
+ # caller.
53
+ def call(tool, config:, canonical_name: nil)
54
+ budget = budget_for(config, canonical_name)
55
+ return yield if budget.nil?
56
+
57
+ name = canonical_name || tool.name
58
+ result = nil
59
+ error = nil
60
+ # Distinguishes "worker never completed" (killed before the body /
61
+ # hard VM abort — no honest answer exists) from a legitimate nil
62
+ # return. A kill landing mid-body still runs the ensure, which reads
63
+ # as a nil result — the inline-parity residual this seam accepts.
64
+ done = false
65
+ t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
66
+ worker = Thread.new do
67
+ result = yield
68
+ # Re-raised verbatim in the caller below, preserving today's
69
+ # raise-path semantics for ANY exception class, not just
70
+ # StandardError. The re-raise carries the worker-side backtrace;
71
+ # dispatch-site frames are not prepended (the tool's own failure
72
+ # site is what matters for debugging).
73
+ rescue Exception => e # rubocop:disable Lint/RescueException
74
+ error = e
75
+ ensure
76
+ done = true
77
+ end
78
+ worker.name = "rubik-tool-#{name}"
79
+
80
+ unless worker.join(budget)
81
+ elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
82
+ raise BudgetExceeded.new(tool_name: name, budget_seconds: budget, elapsed_seconds: elapsed)
83
+ end
84
+ raise error if error
85
+ raise StandardError, "tool worker for '#{name}' died without completing or raising" unless done
86
+
87
+ result
88
+ end
89
+
90
+ # Honest error result: names the tool and budget, discloses the
91
+ # abandonment, and points at the narrower-retry / override escapes.
92
+ def timeout_result(tool_name:, call_id:, exceeded:, duration_ms:)
93
+ msg = "Tool '#{tool_name}' timed out after #{exceeded.budget_seconds}s. " \
94
+ "The call was abandoned (it may still be running in the background) and its result was discarded. " \
95
+ "Retry with a narrower scope (e.g. add a 'path' or 'extension' filter), or adjust " \
96
+ "'tools.call_timeout_overrides' for this tool."
97
+ Rubik::Tools::Result.new(
98
+ tool_name: tool_name, call_id: call_id, status: :error,
99
+ error: "tool call timeout (budget #{exceeded.budget_seconds}s)", output: msg,
100
+ duration_ms: duration_ms,
101
+ metadata: { "timed_out" => true, "budget_seconds" => exceeded.budget_seconds }
102
+ )
103
+ end
104
+
105
+ # Observability door (mirrors MCP Manager#emit_mcp_event): post —
106
+ # never emit (drain) — so the dispatcher's dmesg door records the
107
+ # timeout under the "tools" subsystem. An unresolved bus, or a post
108
+ # refused by a stopped dispatcher (returns false without raising),
109
+ # falls back to the log; a failing emission never alters the tool
110
+ # result.
111
+ def emit_timeout_event(tool_name:, budget_seconds:, elapsed_seconds:, context:)
112
+ bus = Rubik::Coeffects.get(context, Rubik::Coeffects::EVENTS)
113
+ if bus.respond_to?(:post)
114
+ posted = bus.post(:tool_call_timeout, { tool: tool_name },
115
+ subsystem: :tools, level: :warn,
116
+ budget_seconds: budget_seconds, elapsed_seconds: elapsed_seconds.round(1))
117
+ return if posted
118
+
119
+ Rubik::Log.warn(:tools, "tool '#{tool_name}' exceeded the #{budget_seconds}s call budget " \
120
+ "(event bus refused the record; abandoned after #{elapsed_seconds.round(1)}s)")
121
+ else
122
+ Rubik::Log.warn(:tools, "tool '#{tool_name}' exceeded the #{budget_seconds}s call budget " \
123
+ "(abandoned after #{elapsed_seconds.round(1)}s)")
124
+ end
125
+ rescue StandardError => e
126
+ Rubik::Log.warn(:tools, "failed to emit tool timeout event for '#{tool_name}' " \
127
+ "(budget #{budget_seconds}s: #{e.class}: #{e.message})")
128
+ end
129
+
130
+ # "0" / "off" / "false" / "no" explicitly disable (beats the config
131
+ # file and per-tool overrides); any other non-positive number or
132
+ # garbage warns and falls through to config.
133
+ def resolve_env_budget
134
+ raw = ENV.fetch(ENV_KEY, nil)
135
+ return nil if raw.nil? || raw.strip.empty?
136
+ return OFF if ["off", "false", "no"].include?(raw.strip.downcase)
137
+
138
+ value = parse_seconds(raw)
139
+ if value.nil?
140
+ Rubik::Log.warn(:tools, "ignoring invalid #{ENV_KEY} #{raw.inspect}; falling back to config")
141
+ return nil
142
+ end
143
+ return OFF if value <= 0
144
+
145
+ value
146
+ end
147
+
148
+ # mcp.call_timeout mirror at the config boundary: an invalid value
149
+ # warns and lands on off — the knob must never fail a turn.
150
+ def resolve_config_budget(config)
151
+ raw = config&.fetch("tools.call_timeout", nil)
152
+ return nil if raw.nil?
153
+
154
+ value = parse_seconds(raw)
155
+ return value if value&.positive?
156
+
157
+ Rubik::Log.warn(:tools, "ignoring invalid tools.call_timeout #{raw.inspect} (expected a positive number); treating as off")
158
+ nil
159
+ end
160
+
161
+ # Canonical tool name => seconds. 0/false disables the budget for that
162
+ # tool (the per-tool escape hatch); a positive value replaces the
163
+ # global budget; garbage warns and inherits. Lookup uses key presence,
164
+ # not truthiness — a `false` override must survive the `||` shorthand.
165
+ def resolve_override(config, canonical_name)
166
+ overrides = config&.fetch("tools.call_timeout_overrides", nil)
167
+ return nil unless overrides.is_a?(Hash)
168
+
169
+ key = canonical_name.to_s
170
+ raw = overrides.key?(key) ? overrides[key] : overrides[key.to_sym]
171
+ return nil if raw.nil?
172
+
173
+ value = parse_seconds(raw)
174
+ return OFF if value.nil? && ["off", "false"].include?(raw.to_s.strip.downcase)
175
+ return OFF if value && value <= 0
176
+ return value if value
177
+
178
+ Rubik::Log.warn(:tools, "ignoring invalid call_timeout override for '#{canonical_name}' #{raw.inspect}; using the global budget")
179
+ nil
180
+ end
181
+
182
+ # Non-finite values (Infinity, NaN) are rejected: an infinite budget
183
+ # would silently block the turn forever, the exact failure this knob
184
+ # exists to bound.
185
+ def parse_seconds(raw)
186
+ value = Float(raw)
187
+ value&.finite? ? value : nil
188
+ rescue ArgumentError, TypeError
189
+ nil
190
+ end
191
+ end
192
+ end
193
+ end
@@ -188,6 +188,12 @@ module Rubik
188
188
  @shell.warm_ast_graph(async: async)
189
189
  end
190
190
 
191
+ # Huge-root guidance (#356): boot and !context scan share the
192
+ # assessment and the once-per-session memo on the Shell.
193
+ def maybe_warn_huge_root!(strong_only: true)
194
+ @shell.maybe_warn_huge_root!(strong_only: strong_only)
195
+ end
196
+
191
197
  def build_tool_registry
192
198
  @shell.build_tool_registry
193
199
  end
@@ -49,9 +49,23 @@ module Rubik
49
49
  end
50
50
 
51
51
  private_class_method def self.handle_context_scan(ctx)
52
+ # Explicit opt-in point: weak signals (a plain gitless root) speak here.
53
+ ctx.maybe_warn_huge_root!(strong_only: false)
52
54
  ctx.context_index.full_scan
53
55
  ctx.warm_ast_graph(async: false)
54
- ctx.out.puts "Context index and AST symbol graph updated."
56
+ summary = ctx.context_index.status_summary
57
+ if ctx.context_index.files.empty?
58
+ # Scanner#scan swallows mid-walk aborts into a possibly empty
59
+ # index; claiming success here would loop the model forever.
60
+ ctx.out.puts "Context scan produced NO indexed files — the scan aborted partway (see the log for " \
61
+ "'context scan aborted') or the root has no indexable files. " \
62
+ "Tools will answer 'not ready' until a scan yields files."
63
+ elsif summary[:last_scan_aborted]
64
+ ctx.out.puts "Context scan finished PARTIALLY: #{summary[:file_count]} files indexed, but the scan " \
65
+ "aborted (#{summary[:last_scan_error]}). Results may be incomplete."
66
+ else
67
+ ctx.out.puts "Context index and AST symbol graph updated."
68
+ end
55
69
  rescue Errno::EACCES => e
56
70
  root_path = begin
57
71
  ctx.buffer_manager.root_dir
@@ -122,6 +136,7 @@ module Rubik
122
136
  ctx.out.puts " • Consumed Tokens : #{est_tokens} tokens (#{pct}% of usable capacity)"
123
137
  ctx.out.puts " • Active Turns : #{ctx.conversation_history.size} turn(s)"
124
138
  ctx.out.puts " • Indexed Files : #{summary[:file_count]} files"
139
+ ctx.out.puts " • Index State : PARTIAL — last scan aborted (#{summary[:last_scan_error]})" if summary[:last_scan_aborted]
125
140
  ctx.out.puts " • AST Symbol Count : #{ast_symbols_count} symbols"
126
141
  ctx.out.puts "=================================="
127
142
  guidance = Rubik::Tools::DiagnosticReporter.render_context_status_guidance(
@@ -159,6 +174,7 @@ module Rubik
159
174
  ctx.out.puts "Estimated Prompt Tokens: #{est_tokens} / #{ceiling} tokens #{bar_str}"
160
175
  ctx.out.puts "Compaction Strategy: #{strategy}"
161
176
  ctx.out.puts "Indexed Files: #{summary[:file_count]}, AST Symbols: #{ast_symbols_count}"
177
+ ctx.out.puts "Index State: PARTIAL — last scan aborted (#{summary[:last_scan_error]})" if summary[:last_scan_aborted]
162
178
  ctx.out.puts "============================================="
163
179
  return unless (args && (args.include?("--guidance") || args.include?("-g"))) || est_tokens > (ceiling * 0.8)
164
180
 
@@ -11,7 +11,7 @@ module Rubik
11
11
 
12
12
  # Whole-command synopses: shared by the spine registration (usage:)
13
13
  # and the fallback branches that print them, so the two cannot drift.
14
- USAGE_LSP = "Usage: !lsp <status | on | off | diag [file] | start <lang> | stop [lang] | restart [lang] | servers> [--project|--global]"
14
+ USAGE_LSP = "Usage: !lsp <status | on | off | diag [file] | start <lang> | stop [lang] | restart [lang] | reset [lang] | servers> [--project|--global]"
15
15
  USAGE_SYMBOLS = "Usage: !symbols <name>"
16
16
  USAGE_OUTLINE = "Usage: !outline <file_path>"
17
17
  USAGE_REFS = "Usage: !refs <symbol_name>"
@@ -113,11 +113,23 @@ module Rubik
113
113
  handle_lsp_stop(clean_args[1], ctx)
114
114
  when "restart"
115
115
  handle_lsp_restart(clean_args[1], ctx)
116
+ when "reset"
117
+ handle_lsp_reset(clean_args[1], ctx)
116
118
  else
117
119
  ctx.out.puts USAGE_LSP
118
120
  end
119
121
  end
120
122
 
123
+ private_class_method def self.handle_lsp_reset(lang, ctx)
124
+ if lang.nil? || lang.empty?
125
+ ctx.lsp_manager.crash_stats.clear
126
+ ctx.out.puts "Reset LSP circuit breaker for all languages."
127
+ else
128
+ ctx.lsp_manager.reset_circuit!(lang)
129
+ ctx.out.puts "Reset LSP circuit breaker for '#{lang}'."
130
+ end
131
+ end
132
+
121
133
  private_class_method def self.handle_lsp_status(ctx)
122
134
  summary = ctx.lsp_manager.status_summary
123
135
  ctx.out.puts "=== LSP Integration Status ==="
@@ -16,7 +16,8 @@ module Rubik
16
16
  Parts = ServiceCatalog.parts_struct
17
17
 
18
18
  def self.build(config:, root_dir: nil, event_bus: nil, buffer_manager: nil, snapshot_store: nil, dmesg: nil, dispatcher: nil, init: nil)
19
- effective_root = File.expand_path(root_dir || buffer_manager&.root_dir || config&.root_dir || Dir.pwd)
19
+ fallback_root = (ENV["RUBIK_TEST"] == "1" && ENV.fetch("RUBIK_TEST_ROOT", nil)) || Dir.pwd
20
+ effective_root = File.expand_path(root_dir || buffer_manager&.root_dir || config&.root_dir || fallback_root)
20
21
  scope = ServiceCatalog::Scope.new(
21
22
  root_dir: effective_root,
22
23
  overrides: {
@@ -141,7 +141,11 @@ module Rubik
141
141
  # default (RUBIK_TEST=1 warms synchronously-off) so the schema entry
142
142
  # never forces async warm in tests.
143
143
  warm_async = Platform.async_knob(@config, "ast.async_warm")
144
- warm_ast_graph(async: warm_async)
144
+ maybe_warn_huge_root!
145
+ # A strong huge-root signal skips the boot warm walk: the index
146
+ # stays empty and tools answer the honest not-ready message until
147
+ # an explicit '!context scan' opts in. Warning only — never a block.
148
+ warm_ast_graph(async: warm_async) unless skip_huge_root_boot_scan?
145
149
  register_default_commands
146
150
  Rubik.current_shell = self
147
151
  Rubik.runtime_manager = @runtime_manager
@@ -159,6 +163,52 @@ module Rubik
159
163
  wire_subagent_events!
160
164
  end
161
165
 
166
+ # Huge-root guidance: classify the session root with cheap probes,
167
+ # print ONE guidance notice per session, and (via skip_huge_root_boot_scan?)
168
+ # gate the boot warm walk. Boot warns on STRONG signals only — a plain
169
+ # gitless root stays silent so ordinary sessions and tests see no new
170
+ # output; the weak gitless aggravator surfaces at the explicit
171
+ # '!context scan' (strong_only: false). Memoized so the scan reuses
172
+ # the assessment without a second git spawn.
173
+ def maybe_warn_huge_root!(strong_only: true)
174
+ return unless @config.nil? || @config.fetch("context.huge_root_notice", true)
175
+ return if @huge_root_notice_shown
176
+
177
+ assessment = huge_root_assessment
178
+ return if strong_only && !assessment.strong
179
+
180
+ guidance = Rubik::Context::RootHeuristics.guidance(assessment, boot_scan_skipped: huge_root_boot_scan_skipped?)
181
+ return if guidance.empty?
182
+
183
+ @huge_root_notice_shown = true
184
+ if @terminal_guard
185
+ @terminal_guard.print_safe_notice(guidance)
186
+ else
187
+ @output&.puts guidance
188
+ end
189
+ end
190
+
191
+ def huge_root_assessment
192
+ @huge_root_assessment ||= Rubik::Context::RootHeuristics.assess(
193
+ @buffer_manager&.root_dir || @config&.root_dir || Dir.pwd,
194
+ home_dir: @config.respond_to?(:home_dir) ? @config.home_dir : nil
195
+ )
196
+ end
197
+
198
+ # Boot scans by default; only a STRONG signal (home dir, filesystem
199
+ # root, OS-data dir) skips the walk, and the knob re-enables it.
200
+ # Gitless roots are weak: guidance only, boot unaffected.
201
+ def skip_huge_root_boot_scan?
202
+ huge_root_boot_scan_skipped?
203
+ end
204
+
205
+ def huge_root_boot_scan_skipped?
206
+ return false unless huge_root_assessment.strong
207
+ return false unless @config.respond_to?(:fetch)
208
+
209
+ !@config.fetch("context.boot_scan_on_huge_root", false)
210
+ end
211
+
162
212
  # Async MCP boot progress notices (mcp-async-boot D8): subscribe BEFORE
163
213
  # the boot triggers so no event is missed, with the unsubscribe inverse
164
214
  # registered in the same breath (wire_subagent_events! pattern). Async
@@ -101,6 +101,7 @@ module Rubik
101
101
  end
102
102
  else
103
103
  @ast_graph.remove_file(full_path)
104
+ @lsp_manager&.did_close_file(rel_file) if @lsp_manager&.enabled?
104
105
  end
105
106
  end
106
107
  @ast_graph.save_to_cache(@cache_store) if @cache_store
@@ -55,23 +55,21 @@ module Rubik
55
55
  end
56
56
  alias on_dispose register_disposable
57
57
 
58
- # Number of pending inverse operations in the Omega accumulator.
59
- # Exposed for runtime visualization (!agents panel, !runtime).
60
- def disposable_count
61
- @monitor.synchronize { @disposables.size }
62
- end
63
-
64
- def services
65
- @monitor.synchronize { @services.dup.freeze }
66
- end
58
+ # Symmetric removal of an inverse from the Omega accumulator before
59
+ # context disposal (AGENTS.md §4).
60
+ def unregister_disposable(inverse)
61
+ return unless inverse
67
62
 
68
- def service_names
69
- @monitor.synchronize { @services.keys }
63
+ @monitor.synchronize { @disposables.delete(inverse) }
70
64
  end
65
+ alias prune_disposable unregister_disposable
71
66
 
72
- def last_dispose_errors
73
- @monitor.synchronize { @last_dispose_errors.dup }
74
- end
67
+ # Number of pending inverse operations in the Omega accumulator.
68
+ # Exposed for runtime visualization (!agents panel, !runtime).
69
+ def disposable_count = @monitor.synchronize { @disposables.size }
70
+ def services = @monitor.synchronize { @services.dup.freeze }
71
+ def service_names = @monitor.synchronize { @services.keys }
72
+ def last_dispose_errors = @monitor.synchronize { @last_dispose_errors.dup }
75
73
 
76
74
  def provide(name, service)
77
75
  key = name.to_s.downcase
@@ -14,6 +14,7 @@ module Rubik
14
14
  "typeprof --lsp --stdio"
15
15
  ],
16
16
  "python" => [
17
+ "ruff server",
17
18
  "pyright-langserver --stdio",
18
19
  "pylsp",
19
20
  "jedi-language-server"
@@ -2,6 +2,7 @@
2
2
 
3
3
  require_relative "../base"
4
4
  require_relative "../../coeffects"
5
+ require_relative "../index_messages"
5
6
  require_relative "../uri_resolver"
6
7
  require_relative "../output"
7
8
  require_relative "../diagnostic_reporter"
@@ -152,6 +153,11 @@ module Rubik
152
153
  }
153
154
  }
154
155
  )
156
+ # Honest not-ready answer for the empty-index window: names the cause,
157
+ # the escape hatch, and that ignore-excluded dirs never enter the index.
158
+ INDEX_NOT_READY_MESSAGE = "#{IndexMessages::INDEX_NOT_READY_PREFIX}" \
159
+ "browse with run_command (e.g. `ls`) / read files by absolute path. " \
160
+ "Note: directories excluded by ignore rules (.gitignore / default excludes) never enter the index.".freeze
155
161
  def initialize(context_index = nil, root_dir: Dir.pwd, runtime_context: nil, context: nil)
156
162
  super(DECLARATION)
157
163
  @context_index = context_index
@@ -167,7 +173,7 @@ module Rubik
167
173
  path_filter = args["path"] || args[:path]
168
174
  ext_filter = args["extension"] || args[:extension]
169
175
  idx = context_index
170
- return ToolOutput.error("Context index is not available. Run '!context scan' or restart the session to build it.") unless idx
176
+ return ToolOutput.error(IndexMessages::INDEX_UNAVAILABLE_MESSAGE) unless idx
171
177
 
172
178
  filter, error = BaseTool.normalize_path_filter(path_filter, @root_dir)
173
179
  if error
@@ -176,23 +182,36 @@ module Rubik
176
182
  return ToolOutput.error(DiagnosticReporter.render_traversal_blocked(path_filter, allowed_roots: allowed))
177
183
  end
178
184
 
179
- files = idx.files.empty? ? idx.full_scan : idx.files
185
+ # Tools never scan: an empty index answers honestly instead of
186
+ # triggering a synchronous full_scan inside the tool call.
187
+ return ToolOutput.error(INDEX_NOT_READY_MESSAGE) if idx.files.empty?
188
+
189
+ files = idx.files
190
+ # A no-match/ignored verdict from a PARTIAL index is the dangerous
191
+ # case — the file may exist but the aborted walk never saw it — so
192
+ # every answer below carries the disclosure.
193
+ partial_note = IndexMessages.note_for(idx)
180
194
  # Path-filtered list drives the B9 explanation: an extension miss in
181
195
  # an INDEXED directory must read "no such files here", not "ignored".
182
196
  path_filtered = filter.empty? ? files.keys : files.keys.select { |f| f.start_with?(filter) }
183
197
  file_list = ext_filter && !ext_filter.empty? ? path_filtered.select { |f| f.end_with?(ext_filter) } : path_filtered
184
198
 
185
- return ignored_directory_message(filter, ext_filter) if path_filtered.empty? && existing_but_unindexed?(@root_dir, filter)
199
+ return with_note(ignored_directory_message(filter, ext_filter), partial_note) if path_filtered.empty? && existing_but_unindexed?(@root_dir, filter)
186
200
 
187
- return BaseTool.no_match_message(filter) if file_list.empty?
201
+ return with_note(BaseTool.no_match_message(filter), partial_note) if file_list.empty?
188
202
 
189
- "Found #{file_list.size} file(s):\n#{file_list.first(50).map { |f| " - #{f}" }.join("\n")}"
203
+ listing = "Found #{file_list.size} file(s):\n#{file_list.first(50).map { |f| " - #{f}" }.join("\n")}"
204
+ partial_note ? "#{listing}#{partial_note}" : listing
190
205
  rescue Errno::EACCES => e
191
206
  ToolOutput.error(DiagnosticReporter.render_permission_denied(path_filter || @root_dir, operation: "read", reason: e.message))
192
207
  end
193
208
 
194
209
  private
195
210
 
211
+ def with_note(message, note)
212
+ note ? "#{message}#{note}" : message
213
+ end
214
+
196
215
  # Session review B9: `list_files(path: 'lib')` answered "No matching
197
216
  # files" for a directory that exists — the context index prunes ignore
198
217
  # rules (.gitignore, DEFAULT_IGNORES) silently. Say so and hand the