woods 2.0.0.beta2 → 2.0.0.beta4

data/lib/woods/mcp/server.rb

@@ -14,16 +14,20 @@ require_relative '../tasks'
 require_relative '../watch/status'
 require_relative '../filename_utils'
 require_relative '../update_check'
+require_relative '../retrieval/source_evidence'
+require_relative '../session_tracer/unit_resolver'
 require_relative 'bootstrap_state'
 require_relative 'errors'
 require_relative 'index_reader'
 require_relative 'index_reader_pinning'
+require_relative 'initialization_guidance'
 require_relative 'protocol_policy'
 require_relative 'tasks/extension'
 require_relative 'tasks/request_capture'
 require_relative 'tasks/store'
 require_relative 'tool_contract'
 require_relative 'tool_response_renderer'
+require_relative 'traversal_response'
 require_relative 'version_aware_tool_dispatch'
 
 module Woods
@@ -70,6 +74,7 @@ module Woods
       # controls that actually shrink the answer are `depth`, `types` and
       # `via`; `limit` and `offset` only page what those leave (B-183).
       DEFAULT_TRAVERSAL_LIMIT = 50
+      DEFAULT_GRAPH_ANALYSIS_LIMIT = 20
 
       class << self
         # Build a configured MCP::Server with all tools and resources.
@@ -90,6 +95,7 @@ module Woods
         def build(index_dir:, retriever: nil, operator: nil, feedback_store: nil, snapshot_store: nil,
                   bootstrap_state: nil, response_format: nil, warmup: true, retriever_reloader: nil)
           reader = IndexReader.new(index_dir)
+          retriever.bind_reader(reader) if retriever.respond_to?(:bind_reader)
           reader.warmup! if warmup
           config = Woods.configuration
           format = response_format || (config.respond_to?(:context_format) ? config.context_format : nil) || :markdown
@@ -156,7 +162,10 @@ module Woods
                                 description: 'Traverse forward dependencies of a unit (what it depends on). ' \
                                              'Narrow with depth, types and via first: they shrink the answer, ' \
                                              'while limit and offset only page it. Returns a BFS tree with ' \
-                                             "depth, bounded to #{DEFAULT_TRAVERSAL_LIMIT} nodes by default.",
+                                             "depth, paged to #{DEFAULT_TRAVERSAL_LIMIT} nodes by default. " \
+                                             'max_nodes/max_edges bound the walk independently; partial_reason reports a budget cutoff and total_is_exact is false. ' \
+                                             'Published relationships are not exhaustive source-reference coverage. ' \
+                                             'Use explain:true for recorded directed relationships and bounded witnesses; ambiguous types remain explicit.',
                                 reader_method: :traverse_dependencies,
                                 render_key: :dependencies)
           define_traversal_tool(server, reader, respond, renderer,
@@ -164,7 +173,10 @@ module Woods
                                 description: 'Traverse reverse dependencies of a unit (what depends on it). ' \
                                              'Narrow with depth, types and via first: they shrink the answer, ' \
                                              'while limit and offset only page it. Returns a BFS tree with ' \
-                                             "depth, bounded to #{DEFAULT_TRAVERSAL_LIMIT} nodes by default.",
+                                             "depth, paged to #{DEFAULT_TRAVERSAL_LIMIT} nodes by default. " \
+                                             'max_nodes/max_edges bound the walk independently; partial_reason reports a budget cutoff and total_is_exact is false. ' \
+                                             'Published relationships are not exhaustive source-reference coverage. ' \
+                                             'Use explain:true for recorded directed relationships and bounded witnesses; ambiguous types remain explicit.',
                                 reader_method: :traverse_dependents,
                                 render_key: :dependents)
           define_structure_tool(server, reader, respond, renderer)
@@ -191,6 +203,7 @@ module Woods
           register_resource_handler(server, reader)
           ToolContract.apply!(server)
           IndexReaderPinning.install(server, reader: reader)
+          server.instructions = InitializationGuidance.for(server.tools.keys)
 
           # Last, after every conditional registration above — the whole point is
           # that a host with Notion wired advertises the same tool order as one
@@ -238,9 +251,9 @@ module Woods
           !token.nil? && ids && !ids.empty?
         end
 
-        def text_response(text)
+        def text_response(text, data: nil)
           structured = { text: text }
-          structured[:data] = JSON.parse(text)
+          structured[:data] = data.nil? ? JSON.parse(text) : data
           ::MCP::Tool::Response.new(
             [{ type: 'text', text: text }],
             structured_content: structured
@@ -384,7 +397,7 @@ module Woods
 
           sliced = offset.positive? ? original.drop(offset) : original
           container[key] = limit ? truncate_section(sliced, limit) : sliced
-          if original.size > offset + (limit || original.size)
+          if offset.positive? || container[key].size < original.size
             container["#{key}_total"] = original.size
             container["#{key}_truncated"] = true
           end
@@ -394,12 +407,11 @@ module Woods
         # Page a traversal result's `nodes` hash in place, in BFS order.
         #
         # Mirrors {#paginate_section}'s metadata keys (`nodes_total`,
-        # `nodes_truncated`, `nodes_offset`) so both renderers print the one
-        # truncation line they already had for `graph_analysis`. A page that
-        # holds every node adds no keys at all, so a small result renders
-        # exactly as it did before the bound existed (B-183).
+        # `nodes_truncated`, `nodes_offset`). A page that holds every admitted
+        # node adds no pagination keys (B-183). TraversalResponse separately
+        # annotates scope and total exactness before pagination.
         #
-        # `nodes_total` marks *any* partial answer, not only one with more
+        # `nodes_total` marks *any* paged answer, not only one with more
         # behind it. Keying it on `total > offset + limit` left the last page
         # of a walk indistinguishable from a complete one: 21 nodes of 121,
         # with nothing saying 100 were skipped. `nodes_truncated` still means
@@ -435,6 +447,11 @@ module Woods
                 identifier: { type: 'string',
                               description: 'Exact unit identifier (e.g. "Post", "PostsController", "Api::V1::HealthController")' },
                 name: { type: 'string', description: 'Alias for `identifier`. Either one works.' },
+                type: { type: 'string', description: 'Optional actual published unit type, to disambiguate shared identifiers.' },
+                evidence: { type: 'string', enum: %w[full compact outline], description: 'Published evidence mode (default full).' },
+                query: { type: 'string', description: 'Optional relevance query for compact evidence; absent means API orientation.' },
+                budget: { type: 'integer', minimum: 1, description: 'Compact/outline token estimate budget (default 2000); full lookup remains complete.' },
+                source_sha256: { type: 'string', description: 'Require the published source SHA256 from an earlier excerpt; refuses changed source.' },
                 include_source: { type: 'boolean', description: 'Include source_code in response (default: true)' },
                 sections: {
                   type: 'array', items: { type: 'string' },
@@ -445,7 +462,7 @@ module Woods
               # accepted alias. The handler validates that one of the two
               # was provided.
             }
-          ) do |server_context:, identifier: nil, name: nil, include_source: nil, sections: nil|
+          ) do |server_context:, identifier: nil, name: nil, include_source: nil, sections: nil, type: nil, evidence: 'full', query: nil, budget: nil, source_sha256: nil|
             identifier ||= name
             if identifier.nil? || identifier.empty?
               next respond_err.call(
@@ -457,8 +474,30 @@ module Woods
               )
             end
             sections = coerce.call(sections)
-            unit = reader.find_unit(identifier)
+            begin
+              Retrieval::SourceEvidence.validate_mode!(evidence)
+              if evidence != 'full' && (include_source == false || sections&.any?)
+                raise ArgumentError, 'compact/outline evidence cannot be combined with include_source: false or sections'
+              end
+              if evidence == 'full' && (!query.nil? || !budget.nil?)
+                raise ArgumentError, 'query and budget apply only to compact/outline evidence'
+              end
+            rescue ArgumentError => e
+              next respond_err.call(e.message, code: :unsupported_argument, tool: 'lookup', argument: 'evidence')
+            end
+            unit = type ? reader.find_unit(identifier, type: type) : reader.find_unit(identifier)
             if unit
+              if source_sha256 && Digest::SHA256.hexdigest(unit['source_code'].to_s) != source_sha256
+                next respond_err.call('Published source changed since the excerpt; retrieve fresh evidence before verification.',
+                                      code: :stale_index, tool: 'lookup', argument: 'source_sha256')
+              end
+              if evidence != 'full'
+                selected = Retrieval::SourceEvidence.new(unit: unit, query: query, generation: reader.loaded_generation)
+                                                    .render(mode: evidence, budget: budget || 2000,
+                                                            counter: ->(text) { (text.length / 4.0).ceil })
+                next ::MCP::Tool::Response.new([{ type: 'text', text: selected.text }],
+                                               structured_content: { text: selected.text, data: { evidence: selected.provenance } })
+              end
               always_include = %w[type identifier file_path namespace]
               filtered = unit
               filtered = filtered.except('source_code') if include_source == false
@@ -485,8 +524,9 @@ module Woods
           server.define_tool(
             name: 'search',
             description: 'Find code units whose identifiers (or source/metadata) match a regex. ' \
-                         'Example: search("Worker|Job") returns all workers and jobs; search("^Post") ' \
-                         'returns units starting with "Post". Returns [{identifier, type, match_field}]. ' \
+                         'Example: search("Worker|Job") finds workers and jobs; search("^Post") ' \
+                         'returns units starting with "Post". Returns [{identifier, type, match_field}] plus completeness. ' \
+                         'Check completeness before treating discovery as exhaustive; a limit is only a page size. ' \
                          'Use `lookup` for exact identifiers, `dependencies`/`dependents` for graph traversal. ' \
                          'Gotchas: query is a Ruby regex — literal pipe needs escaping as \\|; ' \
                          'types restricts which index directories are scanned (e.g. ["mailer"] scans only ' \
@@ -500,6 +540,10 @@ module Woods
                   type: 'array', items: { type: 'string' },
                   description: 'Restrict scan to these unit types: model, controller, service, job, mailer, etc.'
                 },
+                packages: { type: 'array', items: { type: 'string' },
+                            description: 'Exact published package owners, OR within the list; AND with source_paths and types.' },
+                source_paths: { type: 'array', items: { type: 'string' },
+                                description: 'Application-relative directory prefixes; segment-aware, OR within the list. Applied before limits.' },
                 fields: {
                   type: 'array', items: { type: 'string', enum: %w[identifier metadata source_code] },
                   description: 'Fields to search: identifier (default), source_code, metadata'
@@ -517,7 +561,8 @@ module Woods
                 }
               }
             }
-          ) do |server_context:, query: nil, types: nil, fields: nil, limit: nil, exact_prefix: nil, exact_suffix: nil|
+          ) do |server_context:, query: nil, types: nil, fields: nil, limit: nil, exact_prefix: nil, exact_suffix: nil,
+                packages: nil, source_paths: nil|
             if (query.nil? || query.empty?) &&
                (exact_prefix.nil? || exact_prefix.empty?) &&
                (exact_suffix.nil? || exact_suffix.empty?)
@@ -538,17 +583,29 @@ module Woods
               fields: fields || %w[identifier],
               limit: limit || 20,
               exact_prefix: exact_prefix,
-              exact_suffix: exact_suffix
+              exact_suffix: exact_suffix,
+              packages: packages, source_paths: source_paths
             )
             results = search_result[:results]
             payload = {
               query: query,
               result_count: results.size,
-              results: results
+              results: results,
+              completeness: search_result[:completeness]
             }
+            payload[:applied_scope] = search_result[:applied_scope] if search_result[:applied_scope]
             payload[:note] = search_result[:note] if search_result[:note]
             payload[:partial] = true if search_result[:partial]
+            payload[:hint] = search_result[:hint] if search_result[:hint]
             respond.call(renderer.render(:search, payload))
+          rescue Retrieval::Scope::InvalidScopeError => e
+            respond_err.call(e.message, code: :unsupported_argument, tool: 'search', argument: 'scope')
+          rescue IOError, SystemCallError, JSON::ParserError, EncodingError
+            respond_err.call(
+              'Search completeness: unknown (unreadable_or_corrupt_source). ' \
+              'An Index artifact is unavailable or malformed; inspect woods_status and run woods:validate.',
+              code: :corrupt_artifact, tool: 'search', completeness: SearchResults.unavailable
+            )
           end
         end
 
@@ -563,6 +620,7 @@ module Woods
               properties: {
                 identifier: { type: 'string', description: 'Unit identifier to start from' },
                 depth: { type: 'integer', description: 'Maximum traversal depth (default: 2)' },
+                explain: { type: 'boolean', description: 'Include recorded relationship evidence and shared shortest witnesses (default: false)' },
                 types: {
                   type: 'array', items: { type: 'string' },
                   description: 'Filter to these types'
@@ -580,23 +638,31 @@ module Woods
                 },
                 limit: { type: 'integer',
                          description: "Maximum nodes to return (default: #{DEFAULT_TRAVERSAL_LIMIT})" },
-                offset: { type: 'integer', description: 'Skip this many nodes (default: 0)' }
+                offset: { type: 'integer', description: 'Skip this many nodes (default: 0)' },
+                max_nodes: { type: 'integer', minimum: 1, maximum: 10_000,
+                             description: 'Visited-node budget including root (default: 1000; maximum: 10000)' },
+                max_edges: { type: 'integer', minimum: 1, maximum: 100_000,
+                             description: 'Edge-check budget before filters, including reverse via checks (default: 10000; maximum: 100000)' }
               },
               required: ['identifier']
             }
-          ) do |identifier:, server_context:, depth: nil, types: nil, via: nil, limit: nil, offset: nil|
+          ) do |identifier:, server_context:, depth: nil, types: nil, via: nil, limit: nil, offset: nil, max_nodes: nil, max_edges: nil, explain: nil|
             types = coerce.call(types)
             via = coerce.call(via)
             depth = coerce_int.call(depth)
             limit = coerce_int.call(limit)
             offset = coerce_int.call(offset)
-            result = reader.send(reader_method, identifier, depth: depth || 2, types: types, via: via)
+            result = reader.send(reader_method, identifier, depth: depth || 2, types: types, via: via,
+                                                            max_nodes: coerce_int.call(max_nodes) || 1000,
+                                                            max_edges: coerce_int.call(max_edges) || 10_000, explain: explain || false)
             if result[:found] == false
               result[:message] =
                 "Identifier '#{identifier}' not found in the index. Use 'search' to find valid identifiers."
             end
+            TraversalResponse.annotate(result)
             paginate_nodes.call(result, limit || DEFAULT_TRAVERSAL_LIMIT, offset || 0)
-            respond.call(renderer.render(render_key, result))
+            TraversalEvidencePage.apply(result)
+            respond.call(renderer.render(render_key, result), data: result)
           end
         end
 
@@ -636,32 +702,20 @@ module Woods
                   enum: ToolResponseRenderer::GRAPH_ANALYSIS_SECTIONS + %w[all],
                   description: 'Which analysis to return. Default: all'
                 },
-                limit: { type: 'integer', description: 'Limit results per section (default: 20)' },
+                limit: { type: 'integer', description: "Limit results per section (default: #{DEFAULT_GRAPH_ANALYSIS_LIMIT})" },
                 offset: { type: 'integer', description: 'Skip this many results per section (default: 0)' }
               }
             }
           ) do |server_context:, analysis: nil, limit: nil, offset: nil|
-            limit = coerce_int.call(limit)
+            limit = coerce_int.call(limit) || DEFAULT_GRAPH_ANALYSIS_LIMIT
             offset = coerce_int.call(offset)
             data = reader.graph_analysis
             section = analysis || 'all'
             effective_offset = offset || 0
 
-            result = if section == 'all'
-                       if limit || effective_offset.positive?
-                         truncated = data.dup
-                         ToolResponseRenderer::GRAPH_ANALYSIS_SECTIONS.each do |key|
-                           paginate.call(truncated, key, limit, effective_offset)
-                         end
-                         truncated
-                       else
-                         data
-                       end
-                     else
-                       single = { section => data[section] || [], 'stats' => data['stats'] }
-                       paginate.call(single, section, limit, effective_offset) if limit || effective_offset.positive?
-                       single
-                     end
+            result = section == 'all' ? data.dup : { section => data[section] || [], 'stats' => data['stats'] }
+            sections = section == 'all' ? ToolResponseRenderer::GRAPH_ANALYSIS_SECTIONS : [section]
+            sections.each { |key| paginate.call(result, key, limit, effective_offset) }
 
             respond.call(renderer.render(:graph_analysis, result))
           end
@@ -874,13 +928,14 @@ module Woods
           coerce = method(:coerce_array)
           stale_check = method(:stale_index_result?)
           degraded_response = method(:degraded_retrieval_response)
+          retrieval_mode = retriever.respond_to?(:mode) ? retriever.mode : :semantic
           server.define_tool(
             name: 'codebase_retrieve',
-            description: 'Semantic search: retrieve relevant code units for a natural-language question. ' \
+            description: 'Ranked retrieval: relevant code units for a natural-language question. ' \
                          'Example: codebase_retrieve("how does billing work?") returns ranked source context. ' \
                          'Returns a token-budgeted context string ready to paste into a prompt. ' \
                          'Use `search` for exact name/pattern matching; use this for conceptual questions. ' \
-                         'Requires an embedding provider — disabled if OPENAI_API_KEY is unset and Ollama is unreachable. ' \
+                         'Uses configured embeddings, or explicit WOODS_RETRIEVAL_MODE=lexical over extraction units. ' \
                          'By default excludes test_mappings (~33% of a typical index) so spec filenames do not ' \
                          'dominate semantic rank; pass types: ["test_mapping"] to opt back in. ' \
                          'Parameter: use `budget` for the token budget (not `limit` — that means result count ' \
@@ -890,12 +945,15 @@ module Woods
                 query: { type: 'string',
                          description: 'Natural language question (e.g. "How does user authentication work?")' },
                 budget: { type: 'integer',
-                          description: 'Token budget for context assembly (default: 8000).' },
+                          description: 'Token budget for context assembly (configured max_context_tokens; otherwise 8000).' },
+                evidence: { type: 'string', enum: %w[full compact outline],
+                            description: 'Explicit complete spans or API outline within each ranked unit; default full retains existing output.' },
                 types: {
                   type: 'array', items: { type: 'string' },
                   description: 'Restrict results to these unit types (model, controller, service, job, mailer, ' \
                                'rails_source, test_mapping, etc.). Overrides the default test_mapping exclusion. ' \
-                               'When the unfiltered top-K has no candidate of a requested type, the retriever ' \
+                               'Lexical mode and explicit package/path scopes filter before limits and omit the global rank table. ' \
+                               'In semantic mode, when the unfiltered top-K has no requested type, the retriever ' \
                                'falls back to rank-within-type so the response is populated whenever units of ' \
                                'the requested type exist in the index. The response appends a "Type rank ' \
                                'context" table with per-type: source, rank in unfiltered top-K, global_k, ' \
@@ -904,6 +962,10 @@ module Woods
                                '(index has this type but other requested types filled the result), absent ' \
                                '(zero units of this type in the index).'
                 },
+                packages: { type: 'array', items: { type: 'string' },
+                            description: 'Exact published nearest package owners. OR within the list; AND with paths and type eligibility.' },
+                source_paths: { type: 'array', items: { type: 'string' },
+                                description: 'Application-relative directory prefixes. Scope applies before candidate limits; graph expansion stays inside it.' },
                 exclude_types: {
                   type: 'array', items: { type: 'string' },
                   description: 'Additional types to exclude on top of the default test_mapping exclusion.'
@@ -911,7 +973,7 @@ module Woods
               },
               required: ['query']
             }
-          ) do |query:, server_context:, budget: nil, limit: nil, types: nil, exclude_types: nil|
+          ) do |query:, server_context:, budget: nil, limit: nil, types: nil, exclude_types: nil, packages: nil, source_paths: nil, evidence: 'full'|
             # `limit` isn't declared in the schema but clients still send it
             # because sibling tools (search, recent_changes, pagerank) use
             # `limit` as a result count. Mapping it to `budget` here would
@@ -919,10 +981,10 @@ module Woods
             # budget). Surface a helpful typed error instead.
             unless limit.nil?
               next respond_err.call(
-                'codebase_retrieve uses `budget` (token budget, default 8000), not `limit`. ' \
+                'codebase_retrieve uses `budget` (token budget, configured default), not `limit`. ' \
                 '`limit` is the result-count parameter on sibling tools (search, recent_changes, pagerank). ' \
                 "Pass `budget: #{coerce_int.call(limit)}` if you meant a #{coerce_int.call(limit)}-token context, " \
-                'or drop the kwarg entirely for the default 8000.',
+                'or drop the kwarg entirely for the configured default.',
                 code: :unsupported_argument,
                 tool: 'codebase_retrieve',
                 argument: 'limit',
@@ -931,6 +993,11 @@ module Woods
               )
             end
 
+            begin
+              Retrieval::SourceEvidence.validate_mode!(evidence)
+            rescue ArgumentError => e
+              next respond_err.call(e.message, code: :unsupported_argument, tool: 'codebase_retrieve', argument: 'evidence')
+            end
             budget = coerce_int.call(budget)
             types = coerce.call(types)
             exclude_types = coerce.call(exclude_types)
@@ -949,12 +1016,20 @@ module Woods
             end
             if retriever
               begin
+                scope_options = if Retrieval::Scope.requested?(packages: packages, source_paths: source_paths)
+                                  { packages: packages, source_paths: source_paths }
+                                else
+                                  {}
+                                end
+                scope_options[:evidence] = evidence unless evidence == 'full'
                 result = retriever.retrieve(
                   query,
-                  budget: budget || 8000,
+                  budget: budget || (retriever.respond_to?(:default_budget) ? retriever.default_budget : 8000),
                   types: types,
-                  exclude_types: exclude_types
+                  exclude_types: exclude_types, **scope_options
                 )
+              rescue Retrieval::Scope::InvalidScopeError => e
+                next respond_err.call(e.message, code: :unsupported_argument, tool: 'codebase_retrieve', argument: 'scope')
               rescue Woods::Retriever::StoreError => e
                 # M8: a metadata-store failure mid-query must not surface as
                 # a raw raise through the tool boundary (or as the misleading
@@ -963,7 +1038,7 @@ module Woods
                   respond_err,
                   reason: e.message,
                   stores: [e.store],
-                  phase: 'query'
+                  phase: 'query', mode: retrieval_mode
                 )
               end
               if stale_check.call(result)
@@ -975,12 +1050,22 @@ module Woods
                   tool: 'codebase_retrieve'
                 )
               end
-              respond.call(result.context)
+              if evidence != 'full' || (result.respond_to?(:applied_scope) && result.applied_scope)
+                ::MCP::Tool::Response.new(
+                  [{ type: 'text', text: result.context }],
+                  structured_content: { text: result.context, data: { applied_scope: result.applied_scope, sources: result.sources } },
+                  meta: { applied_scope: result.applied_scope }
+                )
+              else
+                respond.call(result.context)
+              end
             else
               respond_err.call(
                 'Semantic search is disabled — no embedding provider is configured. ' \
                 'To enable: set OPENAI_API_KEY, or run Ollama locally ' \
                 '(brew install ollama && ollama serve && ollama pull nomic-embed-text). ' \
+                'For ranked discovery with no embeddings, set WOODS_RETRIEVAL_MODE=lexical in the MCP process ' \
+                'environment and restart the server. See docs/RETRIEVAL_GUIDE.md#embedding-free-lexical-retrieval. ' \
                 'Use the `search` tool for pattern-based matching in the meantime.',
                 code: :not_configured,
                 config_key: 'embedding_provider',
@@ -1020,7 +1105,16 @@ module Woods
         # @param phase [String] 'boot' (hydration failure) or 'query'
         #   (store failure at query time)
         # @return [MCP::Tool::Response]
-        def degraded_retrieval_response(respond_err, reason:, stores:, phase:)
+        def degraded_retrieval_response(respond_err, reason:, stores:, phase:, mode: :semantic)
+          if mode == :lexical
+            return respond_err.call(
+              "Lexical retrieval is degraded: #{reason}. No partial lexical snapshot was served. " \
+              'Inspect woods_status and repair or re-extract the published index, then retry.',
+              code: :degraded_index, tool: 'codebase_retrieve', degraded: true,
+              phase: phase, stores: stores, reason: reason, mode: 'lexical'
+            )
+          end
+
           respond_err.call(
             "Semantic search is degraded: #{reason}. The affected store(s) return no data, so " \
             'queries would come back empty — this is NOT "no results". ' \
@@ -1129,6 +1223,9 @@ module Woods
             )
             doc = assembler.assemble(session_id, budget: budget || 8000, depth: depth || 1)
             respond.call(doc.to_markdown)
+          rescue Woods::SessionTracer::AmbiguousUnitError => e
+            respond_err.call(e.message, code: :ambiguous_identity, tool: 'session_trace',
+                                        identifier: e.identifier, types: e.types)
           rescue StandardError => e
             respond_err.call(
               "Session trace failed: #{e.message}",
@@ -1979,13 +2076,17 @@ module Woods
             description: 'Diagnose whether the Woods index and server are healthy. Returns extraction metadata ' \
                          '(last run, unit counts, git SHA, staleness in seconds), retriever/embedding configuration, ' \
                          'bootstrap state (hydrated / degraded / failed + reason), feature flags, and a ready flag. ' \
-                         'Call this first on cold connect to learn what the server knows.',
-            input_schema: { type: 'object', properties: {} }
-          ) do |server_context:|
+                         'Includes source-content freshness; quick scans have a 250ms budget, explicit deep scans have 5s. ' \
+                         'Incomplete evidence is unknown. Call this first on cold connect.',
+            input_schema: { type: 'object', properties: {
+              source_check: { type: 'string', enum: %w[quick deep], default: 'quick',
+                              description: 'Bounded source content verification: quick (250ms) or deep (5s).' }
+            } }
+          ) do |server_context:, source_check: 'quick'|
             _ = server_context
             status = Woods::MCP::Server.build_status(
               reader: reader, retriever: retriever, index_dir: index_dir,
-              bootstrap_state: bootstrap_state
+              bootstrap_state: bootstrap_state, source_check: source_check
             )
             respond.call(JSON.pretty_generate(status))
           end
@@ -2004,21 +2105,21 @@ module Woods
         # provider in use. Without this, operators debugging "wrong provider" see
         # status claiming +embedding_model: "text-embedding-3-small"+ next to
         # +embedding_provider: "ollama"+ and reasonably distrust every field.
-        def build_status(reader:, retriever:, index_dir:, bootstrap_state: nil)
+        def build_status(reader:, retriever:, index_dir:, bootstrap_state: nil, source_check: 'quick')
           # Pin the generation across the whole payload. Without this the
           # manifest can be read at generation N and `generation_fields` then
           # report N+1 — a status report that describes counts from one index
           # while announcing the number of another, which is precisely the
           # confusion this tool exists to resolve.
-          return build_status_payload(reader, retriever, index_dir, bootstrap_state) unless
+          return build_status_payload(reader, retriever, index_dir, bootstrap_state, source_check) unless
             reader.respond_to?(:with_pinned_generation)
 
           reader.with_pinned_generation do
-            build_status_payload(reader, retriever, index_dir, bootstrap_state)
+            build_status_payload(reader, retriever, index_dir, bootstrap_state, source_check)
           end
         end
 
-        def build_status_payload(reader, retriever, index_dir, bootstrap_state)
+        def build_status_payload(reader, retriever, index_dir, bootstrap_state, source_check)
           manifest = safe_manifest(reader)
           extracted_at = manifest && manifest['extracted_at']
           staleness = staleness_seconds(extracted_at)
@@ -2036,14 +2137,15 @@ module Woods
               index_dir: index_dir.to_s,
               update: Woods::UpdateCheck.status_hash
             },
-            index: index_section(manifest, extracted_at, staleness, index_dir, reader),
+            index: index_section(manifest, extracted_at, staleness, index_dir, reader, source_check),
             watch: watch_section(index_dir),
             retriever: {
               configured: !retriever.nil?,
-              class: retriever&.class&.name
+              class: retriever&.class&.name,
+              **(retriever.respond_to?(:mode) && retriever.mode == :lexical ? { mode: 'lexical' } : {})
             },
             bootstrap: bootstrap_state&.to_h,
-            features: features_from(config, resolved)
+            features: retrieval_features(config, resolved, retriever)
           }
         end
 
@@ -2066,10 +2168,11 @@ module Woods
         # diff directly. This is an observability signal, not a hard gate —
         # hard-refusing responses would be much more disruptive than a loudly-
         # visible staleness flag that agents can branch on.
-        def index_section(manifest, extracted_at, staleness, index_dir, reader = nil)
+        def index_section(manifest, extracted_at, staleness, index_dir, reader = nil, source_check = 'quick')
           base = {
             extracted_at: extracted_at,
             staleness_seconds: staleness,
+            woods_version: manifest && manifest['woods_version'],
             rails_version: manifest && manifest['rails_version'],
             ruby_version: manifest && manifest['ruby_version'],
             total_units: manifest && manifest['total_units'],
@@ -2080,6 +2183,11 @@ module Woods
             schema_sha: manifest && manifest['schema_sha']
           }
 
+          base[:source_freshness] = if reader.respond_to?(:source_freshness)
+                                      reader.source_freshness(mode: source_check)
+                                    else
+                                      { 'state' => 'unknown', 'reasons' => ['source_reader_unavailable'], 'complete' => false }
+                                    end
           base.merge!(generation_fields(index_dir, reader))
           base.merge!(working_tree_fields(index_dir))
 
@@ -2210,7 +2318,7 @@ module Woods
           record = JSON.parse(Woods::AtomicFile.read(path))
           # `state` is whatever the daemon last wrote, and a `kill -9`'d daemon
           # leaves `running` behind forever. `alive?` adds the two checks that
-          # catch that — the pid still exists and the record is recent — so the
+          # catch that — a recent record and, for local hosts, a live pid — so the
           # payload can distinguish "maintaining this index" from "claimed to be,
           # once". Reported as a separate field rather than by overwriting
           # `state`, because the recorded state and the liveness verdict answer
@@ -2263,6 +2371,13 @@ module Woods
         # historic status payloads always reported +false+ regardless of the
         # actual console MCP state. Advertising a misleading field is worse
         # than not advertising it at all.
+        def retrieval_features(config, resolved, retriever)
+          features = features_from(config, resolved)
+          return features unless retriever.respond_to?(:mode) && retriever.mode == :lexical
+
+          features.merge(retrieval_mode: 'lexical', embedding_model: nil, embedding_provider: nil, vector_store: nil)
+        end
+
         def features_from(config, resolved)
           provider_hash = resolved&.embedding_provider || {}
           resolved_provider = resolved_provider_symbol(provider_hash[:class])

data/lib/woods/mcp/tool_contract.rb

@@ -11,6 +11,8 @@ module Woods
       TASK_RESULT_TOOLS = %w[pipeline_embed pipeline_extract].freeze
 
       INTEGER_BOUNDS = {
+        'max_nodes' => [1, 10_000],
+        'max_edges' => [1, 100_000],
         'budget' => [1, 200_000],
         'depth' => [0, 20],
         'limit' => [1, 1_000],
@@ -25,7 +27,7 @@ module Woods
           text: { type: 'string' },
           data: {
             type: %w[object array string number boolean null],
-            description: 'Parsed JSON payload when the selected renderer emits JSON.'
+            description: 'Structured tool payload, including traversal data in every renderer; otherwise parsed JSON when available.'
           }
         },
         required: ['text'],

data/lib/woods/mcp/tool_response_renderer.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative 'traversal_evidence_index'
+require_relative 'traversal_evidence_text'
+
 module Woods
   module MCP
     # Base class for rendering MCP tool responses in different output formats.
@@ -67,6 +70,44 @@ module Woods
 
       private
 
+      def traversal_coverage_lines(data)
+        coverage = fetch_key(data, :graph_coverage)
+        notice = fetch_key(coverage, :notice) if coverage.is_a?(Hash)
+        notice ? [notice] : []
+      end
+
+      def traversal_lower_bound_note(data, shown)
+        return unless fetch_key(data, :total_is_exact) == false
+
+        total = fetch_key(data, :nodes_total, shown)
+        offset = fetch_key(data, :nodes_offset, 0)
+        position = offset.positive? ? " from offset #{offset}" : ''
+        "Showing #{shown} of at least #{total}#{position} " \
+          "(total unknown: #{fetch_key(data, :partial_reason)})."
+      end
+
+      def search_completeness_lines(data)
+        evidence = fetch_key(data, :completeness)
+        return [] unless evidence.is_a?(Hash)
+
+        more = { true => 'yes', false => 'no', nil => 'unknown' }.fetch(fetch_key(evidence, :has_more))
+        total = fetch_key(evidence, :total_matches)
+        lines = [
+          "Search completeness: #{fetch_key(evidence, :status)} (#{fetch_key(evidence, :reason)}).",
+          "More matches: #{more}; total matches: #{total.nil? ? 'unknown' : total}; " \
+          "matched lower bound: #{fetch_key(evidence, :matched_lower_bound)}."
+        ]
+        scope = fetch_key(data, :applied_scope)
+        if scope
+          lines << "Applied scope: packages=#{fetch_key(scope, :packages).inspect}; " \
+                   "source_paths=#{fetch_key(scope, :source_paths).inspect}; " \
+                   "eligible units=#{fetch_key(scope, :eligible_units)}."
+        end
+        hint = fetch_key(data, :hint)
+        lines << hint if hint
+        lines
+      end
+
       # Fetch a value from a hash by symbol or string key, falling back to a default.
       #
       # Handles data hashes that may use either symbol or string keys (e.g., data