woods 2.0.0.beta1 → 2.0.0.beta3

data/lib/woods/mcp/server.rb

@@ -14,10 +14,13 @@ 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'
@@ -90,6 +93,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 +160,9 @@ 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. ' \
+                                             '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 +170,9 @@ 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. ' \
+                                             '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 +199,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
@@ -435,6 +444,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 +459,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 +471,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 +521,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 +537,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 +558,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 +580,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 +617,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,22 +635,29 @@ 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
             paginate_nodes.call(result, limit || DEFAULT_TRAVERSAL_LIMIT, offset || 0)
+            TraversalEvidencePage.apply(result)
             respond.call(renderer.render(render_key, result))
           end
         end
@@ -874,13 +936,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 +953,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 +970,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 +981,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 +989,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 +1001,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 +1024,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 +1046,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,7 +1058,15 @@ 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. ' \
@@ -1020,7 +1111,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 +1229,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 +2082,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 +2111,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 +2143,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 +2174,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 +2189,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 +2324,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 +2377,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],

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,28 @@ module Woods
 
       private
 
+      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

data/lib/woods/mcp/traversal_evidence.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative 'traversal_evidence_index'
+require_relative 'traversal_evidence_page'
+
+module Woods
+  module MCP
+    # Per-query identifier-level BFS with truthful typed records and a shared
+    # predecessor forest. Ambiguous endpoints never become a claimed typed path.
+    class TraversalEvidence
+      class Budget
+        attr_reader :data
+
+        def initialize(max_nodes, max_edges)
+          @data = { max_nodes: max_nodes.to_i.clamp(1, 10_000), max_edges: max_edges.to_i.clamp(1, 100_000),
+                    visited_nodes: 1, visited_edges: 0 }
+        end
+
+        def consume_node
+          throw :traversal_budget, 'node_budget' if data[:visited_nodes] >= data[:max_nodes]
+
+          data[:visited_nodes] += 1
+        end
+
+        def consume_edge
+          throw :traversal_budget, 'edge_budget' if data[:visited_edges] >= data[:max_edges]
+
+          data[:visited_edges] += 1
+        end
+      end
+
+      def initialize(index)
+        @index = index
+      end
+
+      def call(identifier, depth: 2, direction: :forward, types: nil, via: nil, max_nodes: 1000, max_edges: 10_000)
+        return { root: identifier, found: false, nodes: {} } unless @index.include?(identifier)
+
+        prepare(identifier, depth, direction, types, via, max_nodes, max_edges)
+        cursor = 0
+        while cursor < @queue.size
+          current, level = @queue[cursor]
+          cursor += 1
+          entry = @index.node(current, level)
+          @nodes[current] = entry
+          next if @partial_reason || level >= @depth
+
+          @partial_reason = catch(:traversal_budget) do
+            @index.each_edge(current, @direction, @budget) { |edge| visit(current, level, entry, edge) }
+            nil
+          end
+        end
+        response(identifier)
+      end
+
+      private
+
+      def prepare(identifier, depth, direction, types, via, max_nodes, max_edges)
+        @depth = depth
+        @direction = direction
+        @types = types&.to_set
+        @via = via&.to_set
+        @budget = Budget.new(max_nodes, max_edges)
+        @queue = [[identifier, 0]]
+        @nodes = {}
+        @neighbors = Hash.new { |hash, key| hash[key] = Set.new }
+        @edges = {}
+        @edge_ids = {}
+        @partial_reason = nil
+        @witnesses = { identifier => { parent: nil, edge_id: nil, impact: 'root',
+                                       typed_path_complete: @index.types(identifier).size == 1 } }
+      end
+
+      def visit(current, level, entry, edge)
+        return if @via && !@via.include?(edge[:via])
+
+        neighbor = edge.fetch(@direction == :forward ? :target : :source).fetch(:identifier)
+        return if @types && @index.types(neighbor).none? { |type| @types.include?(type) }
+
+        unless @witnesses.key?(neighbor)
+          @budget.consume_node
+          @queue << [neighbor, level + 1]
+          @witnesses[neighbor] = witness(current, level, edge)
+        end
+        edge_id(edge)
+        entry[:deps] << neighbor if @neighbors[current].add?(neighbor)
+      end
+
+      def witness(current, level, edge)
+        complete = @witnesses.fetch(current)[:typed_path_complete] && !edge[:target][:type].nil? &&
+                   @index.types(edge[:source][:identifier]).size == 1
+        { parent: current, edge_id: edge_id(edge), impact: level.zero? ? 'direct' : 'transitive',
+          typed_path_complete: complete }
+      end
+
+      def edge_id(edge)
+        @edge_ids[edge] ||= begin
+          id = "e#{@edges.size}"
+          @edges[id] = edge
+          id
+        end
+      end
+
+      def response(identifier)
+        result = { root: identifier, found: true, nodes: @nodes,
+                   explanation: { direction: @direction.to_s, root: @index.identity(identifier),
+                                  edges: @edges, witnesses: @witnesses } }
+        result.merge!(partial: true, partial_reason: @partial_reason, traversal_budget: @budget.data) if @partial_reason
+        result
+      end
+    end
+  end
+end