woods 1.6.4 → 2.0.0.beta1

data/lib/woods/mcp/server.rb

@@ -1,15 +1,28 @@
 # frozen_string_literal: true
 
+require 'digest'
 require 'json'
 require 'logger'
 require 'mcp'
 require 'open3'
 require 'time'
 require 'set'
+require 'uri'
+require_relative '../atomic_file'
+require_relative '../generation'
 require_relative '../tasks'
+require_relative '../watch/status'
 require_relative '../filename_utils'
 require_relative '../update_check'
+require_relative 'bootstrap_state'
+require_relative 'errors'
 require_relative 'index_reader'
+require_relative 'index_reader_pinning'
+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 'version_aware_tool_dispatch'
 
@@ -39,6 +52,25 @@ module Woods
       @pipeline_mutex = Mutex.new
       @pipeline_in_flight = {}
 
+      # Seconds `pipeline_extract` will wait for the on-disk extraction lock
+      # before reporting contention (#170). Deliberately short: the tool
+      # answers a live agent, and "another writer is mid-run, retry" is a
+      # better answer than a multi-minute stall (the rake writers wait
+      # `LOCK_STALE_TIMEOUT` because a human started them and asked them to
+      # finish). Module-level rather than inside `class << self`, so specs can
+      # stub it and lexical lookup from the tool definitions still finds it.
+      PIPELINE_LOCK_WAIT = 2.0
+
+      # Human-readable pipeline names for the `already_running` message.
+      PIPELINE_LABELS = { extraction: 'Extraction', embedding: 'Embedding' }.freeze
+
+      # How many traversal nodes `dependents` and `dependencies` return when
+      # the caller names no limit. A hub at the default depth 2 used to return
+      # about 178 KB with nothing saying it had been anything but complete. The
+      # 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
+
       class << self
         # Build a configured MCP::Server with all tools and resources.
         #
@@ -70,10 +102,11 @@ module Woods
           respond_err = method(:error_response)
           op_missing = lambda do |tool|
             error_response(
-              'Pipeline operator is not configured. Pass `operator:` to Woods::MCP::Server.build ' \
-              'or use Woods::MCP::Bootstrapper to wire StatusReporter, ErrorEscalator, and PipelineGuard.',
+              'Pipeline operator is not configured. Pass `operator:` (a StatusReporter, ' \
+              'ErrorEscalator, and PipelineGuard) to Woods::MCP::Server.build when embedding ' \
+              'the server — neither packaged executable wires one today.',
               code: :not_configured, config_key: 'operator',
-              doc_link: 'docs/OPERATOR_GUIDE.md', tool: tool
+              doc_link: 'docs/MCP_TOOL_COOKBOOK.md#conditional-tools--wiring', tool: tool
             )
           end
           fb_missing = lambda do |tool|
@@ -81,7 +114,7 @@ module Woods
               'Feedback store is not configured. Pass `feedback_store:` to Woods::MCP::Server.build ' \
               'to enable retrieval feedback capture.',
               code: :not_configured, config_key: 'feedback_store',
-              doc_link: 'docs/FEEDBACK_STORE.md', tool: tool
+              doc_link: 'docs/MCP_TOOL_COOKBOOK.md#conditional-tools--wiring', tool: tool
             )
           end
           snap_missing = lambda do |tool|
@@ -89,27 +122,49 @@ module Woods
               'Snapshot store is not configured. Set `enable_snapshots: true` in Woods.configure ' \
               'and pass `snapshot_store:` to Woods::MCP::Server.build.',
               code: :not_configured, config_key: 'enable_snapshots',
-              doc_link: 'docs/TEMPORAL_SNAPSHOTS.md', tool: tool
+              doc_link: 'docs/MCP_TOOL_COOKBOOK.md#conditional-tools--wiring', tool: tool
             )
           end
 
-          server = VersionAwareServer.new(
+          server = ::MCP::Server.new(
             name: 'woods',
             version: Woods::VERSION,
             resources: resources,
-            resource_templates: resource_templates
+            resource_templates: resource_templates,
+            configuration: ::MCP::Configuration.new.merge(::MCP.configuration),
+            **ProtocolPolicy.cache_hints
           )
+          # Rewrite "Tool not found" into version-aware update guidance for agents
+          # running against an older gem than the skill they're following assumes.
+          server.singleton_class.prepend(VersionAwareToolDispatch)
+          # Make the per-request Tasks opt-in reachable from a tool handler,
+          # which otherwise only sees `arguments`.
+          server.singleton_class.prepend(Tasks::RequestCapture)
+
+          # The Tasks extension backs the two long-running tools. Registered
+          # unconditionally rather than only alongside `operator`, because
+          # `tasks/get` must keep answering for a handle minted by a *previous*
+          # process — the crash-resilience case is precisely the one where this
+          # server was restarted and may come up wired differently.
+          task_store = Tasks::Store.new(index_dir)
+          Tasks::Extension.install(server, store: task_store)
 
           define_lookup_tool(server, reader, respond, respond_err, renderer)
           define_search_tool(server, reader, respond, respond_err, renderer)
           define_traversal_tool(server, reader, respond, renderer,
                                 name: 'dependencies',
-                                description: 'Traverse forward dependencies of a unit (what it depends on). Returns a BFS tree with depth.',
+                                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.",
                                 reader_method: :traverse_dependencies,
                                 render_key: :dependencies)
           define_traversal_tool(server, reader, respond, renderer,
                                 name: 'dependents',
-                                description: 'Traverse reverse dependencies of a unit (what depends on it). Returns a BFS tree with depth.',
+                                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.",
                                 reader_method: :traverse_dependents,
                                 render_key: :dependents)
           define_structure_tool(server, reader, respond, renderer)
@@ -118,9 +173,9 @@ module Woods
           define_pagerank_tool(server, reader, respond, renderer)
           define_framework_tool(server, reader, respond, renderer)
           define_recent_changes_tool(server, reader, respond, renderer)
-          define_reload_tool(server, reader, respond, retriever_reloader)
-          define_retrieve_tool(server, retriever, respond, respond_err)
-          define_trace_flow_tool(server, reader, index_dir, respond, respond_err, renderer)
+          define_reload_tool(server, reader, respond, respond_err, retriever_reloader, bootstrap_state)
+          define_retrieve_tool(server, retriever, respond, respond_err, bootstrap_state)
+          define_trace_flow_tool(server, reader, respond, respond_err, renderer)
           # Conditionally register collaborator-dependent tools. Historically
           # all 15 stubs were registered unconditionally and returned
           # isError: true when the wiring was missing — that added token
@@ -128,14 +183,19 @@ module Woods
           # try tools guaranteed to fail. Only register when the collaborator
           # is wired, so tools/list reflects what the server can actually do.
           define_session_trace_tool(server, reader, respond, respond_err) if session_tracer_wired?
-          define_operator_tools(server, operator, respond, respond_err, op_missing) if operator
+          define_operator_tools(server, operator, respond, respond_err, op_missing, task_store) if operator
           define_feedback_tools(server, feedback_store, respond, respond_err, fb_missing) if feedback_store
           define_snapshot_tools(server, snapshot_store, respond, respond_err, snap_missing) if snapshot_store
           define_notion_sync_tool(server, reader, index_dir, respond, respond_err) if notion_wired?
           define_woods_status_tool(server, reader, retriever, index_dir, bootstrap_state, respond)
           register_resource_handler(server, reader)
+          ToolContract.apply!(server)
+          IndexReaderPinning.install(server, reader: reader)
 
-          server
+          # Last, after every conditional registration above — the whole point is
+          # that a host with Notion wired advertises the same tool order as one
+          # without it.
+          ProtocolPolicy.sort_tools!(server)
         end
 
         private
@@ -165,7 +225,7 @@ module Woods
 
         # Notion export needs both an API token and at least one database ID.
         # A non-blank NOTION_API_TOKEN env var overrides the config token (see
-        # docs/NOTION_EXPORT.md). Resolution goes through
+        # docs/NOTION_INTEGRATION.md). Resolution goes through
         # Woods.resolve_notion_token so a blank env var is treated as absent
         # (rather than masking a valid configured token) — matching the
         # exporter and the notion_sync handler.
@@ -179,7 +239,17 @@ module Woods
         end
 
         def text_response(text)
-          ::MCP::Tool::Response.new([{ type: 'text', text: text }])
+          structured = { text: text }
+          structured[:data] = JSON.parse(text)
+          ::MCP::Tool::Response.new(
+            [{ type: 'text', text: text }],
+            structured_content: structured
+          )
+        rescue JSON::ParserError
+          ::MCP::Tool::Response.new(
+            [{ type: 'text', text: text }],
+            structured_content: structured
+          )
         end
 
         # Build a structured error response that carries machine-readable
@@ -197,7 +267,12 @@ module Woods
           meta[:config_key] = config_key if config_key
           meta[:doc_link] = doc_link if doc_link
           meta.merge!(extra) unless extra.empty?
-          ::MCP::Tool::Response.new([{ type: 'text', text: message }], error: true, meta: meta)
+          ::MCP::Tool::Response.new(
+            [{ type: 'text', text: message }],
+            error: true,
+            structured_content: { text: message },
+            meta: meta
+          )
         end
 
         def truncate_section(array, limit)
@@ -254,7 +329,7 @@ module Woods
         # Load a precomputed flow document written by FlowPrecomputer, when
         # `config.precompute_flows` was enabled during extraction. Returns nil
         # when the entry point is missing a method suffix, the JSON file isn't
-        # on disk, or the file can't be parsed — callers fall back to
+        # on disk, or the file can't be read or parsed — callers fall back to
         # FlowAssembler.
         #
         # @param index_dir [String]
@@ -271,11 +346,27 @@ module Woods
           # flows/) using the SAME transform FlowPrecomputer writes with, so a
           # legitimately precomputed flow always resolves to the file on disk.
           filename = Woods::FilenameUtils.flow_filename(controller, action)
+          # The path is derived from the entry point and joined against THIS
+          # process's index_dir — the path *values* in flow_index.json /
+          # metadata[:flow_paths] are never consulted. That is what keeps
+          # both formats working unchanged: post-#190 indexes persist
+          # output_dir-relative values ("flows/X_y.json"), while pre-#190
+          # indexes persisted the extraction machine's absolute paths (e.g.
+          # container-side "/app/tmp/woods/flows/X_y.json"), which need not
+          # resolve on the reading host at all.
           path = File.join(index_dir, 'flows', filename)
           return nil unless File.exist?(path)
 
-          Woods::FlowDocument.from_h(JSON.parse(File.read(path)))
-        rescue JSON::ParserError, Errno::ENOENT
+          # AtomicFile.read, not File.read: flow documents carry free-text
+          # (args_hint / condition strings) that can be non-ASCII, and a bare
+          # read under LANG=C tags the result US-ASCII so the first
+          # JSON.parse raises Encoding::InvalidByteSequenceError.
+          Woods::FlowDocument.from_h(JSON.parse(Woods::AtomicFile.read(path)))
+        rescue JSON::ParserError, Errno::ENOENT, EncodingError
+          # EncodingError included so ANY unreadable precomputed flow (torn,
+          # corrupt, mis-encoded bytes) degrades to query-time reassembly as
+          # documented, instead of escaping to trace_flow's generic handler
+          # as an internal_error.
           nil
         end
 
@@ -300,6 +391,37 @@ module Woods
           container["#{key}_offset"] = offset if offset.positive?
         end
 
+        # 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_total` marks *any* partial 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
+        # what it always did, "there is more after this page".
+        #
+        # @param result [Hash] traversal result, mutated
+        # @param limit [Integer] maximum nodes to retain
+        # @param offset [Integer] nodes to skip from the front
+        # @return [void]
+        def paginate_traversal_nodes(result, limit, offset)
+          nodes = result[:nodes]
+          return unless nodes.is_a?(Hash)
+
+          total = nodes.size
+          return if offset.zero? && total <= limit
+
+          result[:nodes] = nodes.to_a.drop(offset).take(limit).to_h
+          result[:nodes_total] = total if offset.positive? || total > limit
+          result[:nodes_truncated] = true if total > offset + limit
+          result[:nodes_offset] = offset if offset.positive?
+        end
+
         def define_lookup_tool(server, reader, respond, respond_err, renderer)
           coerce = method(:coerce_array)
           server.define_tool(
@@ -379,7 +501,7 @@ module Woods
                   description: 'Restrict scan to these unit types: model, controller, service, job, mailer, etc.'
                 },
                 fields: {
-                  type: 'array', items: { type: 'string' },
+                  type: 'array', items: { type: 'string', enum: %w[identifier metadata source_code] },
                   description: 'Fields to search: identifier (default), source_code, metadata'
                 },
                 limit: { type: 'integer', description: 'Maximum results (default: 20)' },
@@ -433,6 +555,7 @@ module Woods
         def define_traversal_tool(server, reader, respond, renderer, name:, description:, reader_method:, render_key:)
           coerce = method(:coerce_array)
           coerce_int = method(:coerce_integer)
+          paginate_nodes = method(:paginate_traversal_nodes)
           server.define_tool(
             name: name,
             description: description,
@@ -445,25 +568,34 @@ module Woods
                   description: 'Filter to these types'
                 },
                 via: {
-                  type: 'array', items: { type: 'string' },
+                  anyOf: [
+                    { type: 'string' },
+                    { type: 'array', items: { type: 'string' } }
+                  ],
                   description: 'Filter by relationship type. Accepts either a single string ' \
                                "(e.g. 'code_reference') or an array " \
                                "(e.g. ['code_reference','render']); both forms are coerced to an array internally. " \
                                'Known values: link_to, redirect_to, form_action, render, code_reference, ' \
-                               'belongs_to, has_many, has_one, has_and_belongs_to_many.'
-                }
+                               'belongs_to, has_many, has_one, has_and_belongs_to_many, polymorphic_interface.'
+                },
+                limit: { type: 'integer',
+                         description: "Maximum nodes to return (default: #{DEFAULT_TRAVERSAL_LIMIT})" },
+                offset: { type: 'integer', description: 'Skip this many nodes (default: 0)' }
               },
               required: ['identifier']
             }
-          ) do |identifier:, server_context:, depth: nil, types: nil, via: nil|
+          ) do |identifier:, server_context:, depth: nil, types: nil, via: nil, limit: nil, offset: 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)
             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)
             respond.call(renderer.render(render_key, result))
           end
         end
@@ -492,12 +624,16 @@ module Woods
           coerce_int = method(:coerce_integer)
           server.define_tool(
             name: 'graph_analysis',
-            description: 'Get structural analysis of the dependency graph: orphans, dead ends, hubs, cycles, and bridges.',
+            description: 'Get structural analysis of the dependency graph: orphans, dead ends, hubs, cycles, bridges, ' \
+                         'cross_database_edges (associations and foreign keys across databases), ' \
+                         'volatile_dependencies (edges into units that change far more often than the dependent), ' \
+                         'and undeclared_package_edges (edges that cross a package boundary the source package ' \
+                         'never declared).',
             input_schema: {
               properties: {
                 analysis: {
                   type: 'string',
-                  enum: %w[orphans dead_ends hubs cycles bridges all],
+                  enum: ToolResponseRenderer::GRAPH_ANALYSIS_SECTIONS + %w[all],
                   description: 'Which analysis to return. Default: all'
                 },
                 limit: { type: 'integer', description: 'Limit results per section (default: 20)' },
@@ -514,7 +650,7 @@ module Woods
             result = if section == 'all'
                        if limit || effective_offset.positive?
                          truncated = data.dup
-                         %w[orphans dead_ends hubs cycles bridges].each do |key|
+                         ToolResponseRenderer::GRAPH_ANALYSIS_SECTIONS.each do |key|
                            paginate.call(truncated, key, limit, effective_offset)
                          end
                          truncated
@@ -522,7 +658,7 @@ module Woods
                          data
                        end
                      else
-                       single = { section => data[section], 'stats' => data['stats'] }
+                       single = { section => data[section] || [], 'stats' => data['stats'] }
                        paginate.call(single, section, limit, effective_offset) if limit || effective_offset.positive?
                        single
                      end
@@ -658,38 +794,86 @@ module Woods
           end
         end
 
-        def define_reload_tool(server, reader, respond, retriever_reloader)
+        def define_reload_tool(server, reader, respond, respond_err, retriever_reloader, bootstrap_state)
           server.define_tool(
             name: 'reload',
             description: 'Reload extraction data from disk. Use after re-running extraction or woods:embed to pick ' \
                          'up changes without restarting the server. Refreshes the JSON index (manifest, dependency ' \
                          'graph, unit cache) AND re-hydrates the retriever\'s in-memory vector/metadata/graph ' \
-                         'stores from the latest dumps. Durable backends (pgvector, Qdrant) are auto-refreshed ' \
-                         'externally — their counts in the response reflect the read-through state.',
+                         'stores from the latest dumps. The refresh is transactional (build-then-swap): candidate ' \
+                         'stores are built off-side, and on any failure nothing is swapped — the previous ' \
+                         'generation keeps being served and a degraded_index error names it. Durable backends ' \
+                         '(pgvector, Qdrant) are auto-refreshed externally — their counts in the response reflect ' \
+                         'the read-through state.',
             input_schema: { type: 'object', properties: {} }
           ) do |server_context:|
-            reader.reload!
-            manifest = reader.manifest
-            payload = {
-              reloaded: true,
-              extracted_at: manifest['extracted_at'],
-              total_units: manifest['total_units'],
-              counts: manifest['counts']
-            }
             if retriever_reloader
-              begin
-                payload[:retriever] = retriever_reloader.call
+              counts = begin
+                retriever_reloader.call(reader)
+              rescue Woods::MCP::ReloadDegraded => e
+                reason = "#{e.class}: #{e.message}"
+                bootstrap_state&.record_reload_failure(generation: e.generation, stores: e.stores, reason: reason)
+                next respond_err.call(
+                  "Reload failed; nothing was swapped. Generation #{e.generation} is still being served: " \
+                  "#{reason} Fix the underlying store or index issue, then invoke reload again.",
+                  code: :degraded_index,
+                  tool: 'reload',
+                  degraded: true,
+                  phase: 'reload',
+                  generation: e.generation,
+                  stores: e.stores,
+                  reason: reason
+                )
               rescue StandardError => e
-                payload[:retriever] = { error: "#{e.class}: #{e.message}" }
+                # A foreign error from a custom reloader leaves the reader and
+                # stores untouched too (the transaction is all-or-nothing), so
+                # it maps to the same reload-phase degraded shape with best-
+                # effort fields.
+                generation = reader.loaded_generation || 0
+                reason = "#{e.class}: #{e.message}"
+                bootstrap_state&.record_reload_failure(generation: generation,
+                                                       stores: %w[vector metadata graph], reason: reason)
+                next respond_err.call(
+                  "Reload failed; nothing was swapped. Generation #{generation} is still being served: " \
+                  "#{reason} Fix the underlying store or index issue, then invoke reload again.",
+                  code: :degraded_index,
+                  tool: 'reload',
+                  degraded: true,
+                  phase: 'reload',
+                  generation: generation,
+                  stores: %w[vector metadata graph],
+                  reason: reason
+                )
+              end
+
+              manifest = reader.manifest
+              payload = {
+                reloaded: true,
+                extracted_at: manifest['extracted_at'],
+                total_units: manifest['total_units'],
+                counts: manifest['counts'],
+                retriever: counts
+              }
+              respond.call(JSON.pretty_generate(payload))
+            else
+              reader.with_exclusive_reload do |manifest|
+                payload = {
+                  reloaded: true,
+                  extracted_at: manifest['extracted_at'],
+                  total_units: manifest['total_units'],
+                  counts: manifest['counts']
+                }
+                respond.call(JSON.pretty_generate(payload))
               end
             end
-            respond.call(JSON.pretty_generate(payload))
           end
         end
 
-        def define_retrieve_tool(server, retriever, respond, respond_err)
+        def define_retrieve_tool(server, retriever, respond, respond_err, bootstrap_state = nil)
           coerce_int = method(:coerce_integer)
           coerce = method(:coerce_array)
+          stale_check = method(:stale_index_result?)
+          degraded_response = method(:degraded_retrieval_response)
           server.define_tool(
             name: 'codebase_retrieve',
             description: 'Semantic search: retrieve relevant code units for a natural-language question. ' \
@@ -750,13 +934,47 @@ module Woods
             budget = coerce_int.call(budget)
             types = coerce.call(types)
             exclude_types = coerce.call(exclude_types)
-            if retriever
-              result = retriever.retrieve(
-                query,
-                budget: budget || 8000,
-                types: types,
-                exclude_types: exclude_types
+            # M6: a hydration failure at boot left the in-memory stores
+            # empty. Every query would come back as a clean empty result —
+            # indistinguishable from "no matches" — so surface the degraded
+            # state as typed metadata instead of answering with nothing.
+            if bootstrap_state&.hydration_failed?
+              failures = bootstrap_state.hydration_failures
+              next degraded_response.call(
+                respond_err,
+                reason: failures.values.map { |e| "#{e.class}: #{e.message}" }.join('; '),
+                stores: failures.keys.map(&:to_s),
+                phase: 'boot'
               )
+            end
+            if retriever
+              begin
+                result = retriever.retrieve(
+                  query,
+                  budget: budget || 8000,
+                  types: types,
+                  exclude_types: exclude_types
+                )
+              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
+                # :absent / empty answers the retriever used to produce).
+                next degraded_response.call(
+                  respond_err,
+                  reason: e.message,
+                  stores: [e.store],
+                  phase: 'query'
+                )
+              end
+              if stale_check.call(result)
+                next respond_err.call(
+                  'The vector index appears stale: matches were found but their source data is ' \
+                  'missing (likely a deleted or renamed unit). Re-run `woods:embed` (or ' \
+                  '`woods:embed_incremental`) to refresh the index, then retry.',
+                  code: :stale_index,
+                  tool: 'codebase_retrieve'
+                )
+              end
               respond.call(result.context)
             else
               respond_err.call(
@@ -773,7 +991,51 @@ module Woods
           end
         end
 
-        def define_trace_flow_tool(server, reader, index_dir, respond, respond_err, renderer)
+        # Detect a stale vector index: candidates matched the query but every
+        # one of them pointed at a unit the metadata store no longer has
+        # (deleted/renamed since the last embed). Distinguishes that case
+        # from a genuine "no matches" so the tool can say what happened
+        # instead of returning near-empty context as clean success.
+        #
+        # @param result [Woods::Retriever::RetrievalResult] (or a test double
+        #   with the same shape — +trace+ may be absent/nil on older doubles)
+        # @return [Boolean]
+        def stale_index_result?(result)
+          trace = result.respond_to?(:trace) ? result.trace : nil
+          return false unless trace
+
+          trace.ranked_count.to_i.positive? &&
+            trace.skipped_missing_metadata.to_i.positive? &&
+            Array(result.sources).empty?
+        end
+
+        # Typed degraded-metadata response for codebase_retrieve (M6/M8). A
+        # degraded retriever must never answer with a clean empty result: the
+        # response is a tool error carrying the machine-readable degraded
+        # marker, which stores are affected, and the underlying reason.
+        #
+        # @param respond_err [Method] the tool error-response builder
+        # @param reason [String] human-readable failure summary
+        # @param stores [Array<String>] affected store component names
+        # @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:)
+          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". ' \
+            'Run `woods_status` for the bootstrap report, re-run `woods:embed` if the index is stale, ' \
+            'and restart the server once the store is loadable.',
+            code: :degraded_index,
+            tool: 'codebase_retrieve',
+            degraded: true,
+            phase: phase,
+            stores: stores,
+            reason: reason
+          )
+        end
+
+        def define_trace_flow_tool(server, reader, respond, respond_err, renderer)
           require_relative '../flow_assembler'
           require_relative '../flow_document'
           require_relative '../dependency_graph'
@@ -803,10 +1065,10 @@ module Woods
             # extraction (gated on `config.precompute_flows`) — it avoids
             # re-parsing source on every request. Fall back to query-time
             # reassembly when no precomputed document exists.
-            flow_doc = load_precomputed.call(index_dir, entry_point)
+            flow_doc = load_precomputed.call(reader.payload_dir, entry_point)
             flow_doc ||= begin
               graph = reader.dependency_graph
-              assembler = Woods::FlowAssembler.new(graph: graph, extracted_dir: index_dir)
+              assembler = Woods::FlowAssembler.new(graph: graph, extracted_dir: reader.payload_dir.to_s)
               assembler.assemble(entry_point, max_depth: max_depth)
             end
 
@@ -816,6 +1078,14 @@ module Woods
             # surface it, rather than wrapping the error payload in a
             # successful response — consistent with session_trace and
             # codebase_retrieve.
+            if ToolContract.artifact_error?(e)
+              next respond_err.call(
+                'trace_flow could not read a required Index artifact.',
+                code: :corrupt_artifact,
+                tool: 'trace_flow'
+              )
+            end
+
             respond_err.call(
               "trace_flow failed: #{e.message}",
               code: :internal_error,
@@ -847,7 +1117,7 @@ module Woods
                 'and set `session_tracer_enabled = true` in Woods.configure.',
                 code: :not_configured,
                 config_key: 'session_store',
-                doc_link: 'docs/SESSION_TRACER.md',
+                doc_link: 'docs/MCP_TOOL_COOKBOOK.md#conditional-tools--wiring',
                 tool: 'session_trace'
               )
             end
@@ -869,9 +1139,9 @@ module Woods
           end
         end
 
-        def define_operator_tools(server, operator, respond, respond_err, op_missing)
-          define_pipeline_extract_tool(server, operator, respond, respond_err, op_missing)
-          define_pipeline_embed_tool(server, operator, respond, respond_err, op_missing)
+        def define_operator_tools(server, operator, respond, respond_err, op_missing, task_store)
+          define_pipeline_extract_tool(server, operator, respond, respond_err, op_missing, task_store)
+          define_pipeline_embed_tool(server, operator, respond, respond_err, op_missing, task_store)
           define_pipeline_status_tool(server, operator, respond, respond_err, op_missing)
           define_pipeline_diagnose_tool(server, operator, respond, respond_err, op_missing)
           define_pipeline_repair_tool(server, operator, respond, respond_err, op_missing)
@@ -884,7 +1154,8 @@ module Woods
           define_retrieval_suggest_tool(server, feedback_store, respond, fb_missing)
         end
 
-        def define_pipeline_extract_tool(server, operator, respond, respond_err, op_missing)
+        def define_pipeline_extract_tool(server, operator, respond, respond_err, op_missing, task_store)
+          cooldown = method(:cooldown_error)
           server.define_tool(
             name: 'pipeline_extract',
             description: 'Trigger a codebase extraction pipeline run. Checks rate limits before proceeding.',
@@ -919,50 +1190,114 @@ module Woods
             end
 
             guard = operator[:pipeline_guard]
-            if guard && !guard.allow?(:extraction)
-              next respond_err.call(
-                'Extraction is rate-limited. Try again later.',
-                code: :rate_limited,
-                tool: 'pipeline_extract',
-                retry_after_seconds: 300
-              )
+            if (blocked = cooldown.call(guard, :extraction, 'pipeline_extract'))
+              next blocked
             end
 
-            # Acquire the in-process lock BEFORE recording to the guard.
-            # Otherwise a refused "already running" request still resets
-            # the cooldown clock and blocks the next legitimate attempt
-            # for the full 5-minute window once the current run finishes.
-            unless Woods::MCP::Server.send(:pipeline_start, :extraction)
-              next respond_err.call(
-                'Extraction pipeline is already running. Wait for it to complete.',
-                code: :already_running,
-                tool: 'pipeline_extract'
-              )
+            build_extraction_runner = lambda do |output_dir|
+              lambda do
+                # exe/woods-mcp deliberately loads no extraction machinery, so
+                # Woods::Extractor is not defined in a standalone index-server
+                # process. Resolve it here, the same lazy require Woods.extract!
+                # uses — otherwise every pipeline_extract run dies in the
+                # background with NameError.
+                require_relative '../extractor' unless defined?(Woods::Extractor)
+                extractor = Woods::Extractor.new(output_dir: output_dir)
+                incremental ? extractor.extract_changed(files) : extractor.extract_all
+              end
             end
 
-            # Lock acquired — now it's safe to record the run.
-            guard&.record!(:extraction)
+            next Woods::MCP::Server.send(
+              :start_pipeline_run,
+              kind: :extraction, tool: 'pipeline_extract',
+              task_store: task_store, respond: respond, respond_err: respond_err,
+              runner_builder: build_extraction_runner,
+              started: -> { guard&.record!(:extraction) },
+              started_message: 'Extraction pipeline started in background thread'
+            )
+          end
+        end
 
-            Thread.new do
-              extractor = Woods::Extractor.new(
-                output_dir: Woods.configuration.output_dir
-              )
-              incremental ? extractor.extract_changed(files) : extractor.extract_all
-            rescue StandardError => e
-              logger = defined?(Rails) ? Rails.logger : Logger.new($stderr)
-              logger.error("[Woods] Pipeline extract failed: #{e.message}")
-            ensure
-              Woods::MCP::Server.send(:pipeline_finish, :extraction)
-            end
+        # The same lock every other writer against this index uses —
+        # `woods:extract`/`incremental`/`refresh` and the watch daemon all
+        # build it from the daemon's constants (see CLAUDE.md, "writers
+        # serialize on PipelineLock").
+        #
+        # @param output_dir [String, Pathname] index directory
+        # @return [Woods::Coordination::PipelineLock]
+        def build_extraction_lock(output_dir)
+          require_relative '../coordination/pipeline_lock'
+          require_relative '../coordination/lock_heartbeat'
+          require_relative '../watch/daemon'
+
+          Woods::Coordination::PipelineLock.new(
+            lock_dir: output_dir.to_s,
+            name: Woods::Watch::Daemon::LOCK_NAME,
+            stale_timeout: Woods::Watch::Daemon::LOCK_STALE_TIMEOUT
+          )
+        end
 
-            respond.call(JSON.pretty_generate({
-                                                status: 'started',
-                                                message: 'Extraction pipeline started in background thread'
-                                              }))
+        # Poll for the lock until {PIPELINE_LOCK_WAIT} elapses. Monotonic, so
+        # a clock adjustment mid-wait cannot stretch or shrink the window.
+        #
+        # @param lock [Woods::Coordination::PipelineLock]
+        # @return [Boolean] whether the lock was acquired
+        def acquire_lock_briefly(lock)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + PIPELINE_LOCK_WAIT
+          acquired = lock.acquire
+          until acquired || Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+            sleep 0.1
+            acquired = lock.acquire
           end
+          acquired
         end
 
-        def define_pipeline_embed_tool(server, operator, respond, respond_err, op_missing)
+        # Build the cooldown-gate error for pipeline_extract/pipeline_embed,
+        # or nil when the operation may proceed.
+        #
+        # `PipelineGuard#allow?` fails closed on state it cannot verify
+        # (corrupt or permission-denied), which reads identically to a
+        # genuine, elapsing cooldown from the boolean alone. Reporting
+        # `:rate_limited, retry_after_seconds: 300` for state that will
+        # never resolve on its own is the inaccurate public metadata this
+        # closes — `PipelineGuard#state_status` distinguishes why, and the
+        # tool error now says so.
+        #
+        # @param guard [Woods::Operator::PipelineGuard, nil]
+        # @param operation [Symbol] :extraction or :embedding
+        # @param tool [String] tool name, for the error payload
+        # @return [MCP::Tool::Response, nil]
+        def cooldown_error(guard, operation, tool)
+          return nil unless guard
+          return nil if guard.allow?(operation)
+
+          case guard.state_status
+          when :corrupt
+            # `pipeline_repair`'s `reset_cooldowns` action deletes state by
+            # key and cannot act on content it cannot parse, so it will not
+            # clear this — the fix is replacing or removing the state file
+            # directly.
+            error_response(
+              'Pipeline cooldown state is corrupt, so the cooldown cannot be verified. ' \
+              'Inspect and replace (or remove) pipeline_guard.json in the operator state directory.',
+              code: :cooldown_state_corrupt, tool: tool
+            )
+          when :permission_denied
+            error_response(
+              'Pipeline cooldown state is unreadable (permission denied), so the cooldown cannot be verified. ' \
+              'Check the operator state directory permissions.',
+              code: :cooldown_state_unreadable, tool: tool
+            )
+          else
+            error_response(
+              "#{operation == :extraction ? 'Extraction' : 'Embedding'} is rate-limited. Try again later.",
+              code: :rate_limited, tool: tool, retry_after_seconds: 300
+            )
+          end
+        end
+
+        def define_pipeline_embed_tool(server, operator, respond, respond_err, op_missing, task_store)
+          cooldown = method(:cooldown_error)
           server.define_tool(
             name: 'pipeline_embed',
             description: 'Trigger embedding generation for extracted units. Checks rate limits before proceeding.',
@@ -975,49 +1310,239 @@ module Woods
             next op_missing.call('pipeline_embed') unless operator
 
             guard = operator[:pipeline_guard]
-            if guard && !guard.allow?(:embedding)
-              next respond_err.call(
-                'Embedding is rate-limited. Try again later.',
-                code: :rate_limited,
-                tool: 'pipeline_embed',
-                retry_after_seconds: 300
-              )
+            if (blocked = cooldown.call(guard, :embedding, 'pipeline_embed'))
+              next blocked
             end
 
-            # Acquire the in-process lock first so a refused "already
-            # running" request doesn't burn the cooldown clock.
-            unless Woods::MCP::Server.send(:pipeline_start, :embedding)
-              next respond_err.call(
-                'Embedding pipeline is already running. Wait for it to complete.',
-                code: :already_running,
-                tool: 'pipeline_embed'
-              )
+            build_embed_runner = lambda do |_output_dir|
+              lambda do
+                # Share the rake-task wiring so the MCP path picks up the
+                # provider-tuned TextPreparer + token-aware chunker. Without
+                # this, MCP-triggered embedding still hit Ollama's "input
+                # length exceeds context length" error after the rake path
+                # was fixed in PR #70.
+                indexer = Woods::Tasks.build_embed_indexer
+                incremental ? indexer.index_incremental : indexer.index_all
+              end
+            end
+
+            next Woods::MCP::Server.send(
+              :start_pipeline_run,
+              kind: :embedding, tool: 'pipeline_embed',
+              task_store: task_store, respond: respond, respond_err: respond_err,
+              runner_builder: build_embed_runner,
+              started: -> { guard&.record!(:embedding) },
+              started_message: 'Embedding pipeline started in background thread'
+            )
+          end
+        end
+
+        # Claim the in-process pipeline slot, take the cross-process writer
+        # lock, and hand the run off to a background thread.
+        #
+        # Owns the entire window between {pipeline_start} and the hand-off.
+        # Before this existed, ANY raise inside that window skipped
+        # {pipeline_finish} for the life of the process, so every later call
+        # answered `already_running` and only a restart cleared it (MCP-3).
+        # `PipelineLock#acquire` rescues only `Errno::EEXIST` and opens/creates
+        # files, so an index directory this process cannot write — the
+        # documented Docker deployment mounts the index into a host-side
+        # server — raises `SystemCallError` out of {acquire_lock_briefly}
+        # rather than returning false. That escaping error also reached
+        # {ToolContract} as a nested SystemCallError and came back as
+        # `corrupt_artifact` ("An Index artifact is unavailable or malformed"),
+        # a misdiagnosis of a permissions failure. Both are closed here, with
+        # the same handoff-flag shape {run_pipeline_in_background} uses one
+        # layer down (L6).
+        #
+        # Cross-PROCESS serialization (#170): {pipeline_start} only guards this
+        # process; the rake writers and the watch daemon serialize on the
+        # on-disk PipelineLock, and an unlocked MCP run was free to rewrite the
+        # index under any of them with the loser's work silently discarded. The
+        # wait is short and the failure explicit — an MCP tool must not sit on
+        # a lock queue for minutes the way `woods:extract` does.
+        #
+        # A nil/duck-typed configuration (no output_dir) yields no lock: there
+        # is no known lock domain, and the run fails in the background exactly
+        # as it always has on an unconfigured host.
+        #
+        # @param kind [Symbol] :extraction or :embedding
+        # @param tool [String] tool name, for the error payloads
+        # @param runner_builder [Proc] called with the resolved output_dir;
+        #   returns the runner lambda {run_pipeline_in_background} executes
+        # @return [Hash, MCP::Tool::Response]
+        def start_pipeline_run(kind:, tool:, task_store:, respond:, respond_err:, runner_builder:, started:,
+                               started_message:)
+          # Claim the slot BEFORE recording to the guard. Otherwise a refused
+          # "already running" request still resets the cooldown clock and
+          # blocks the next legitimate attempt for the full window.
+          unless pipeline_start(kind)
+            return respond_err.call(
+              "#{PIPELINE_LABELS.fetch(kind)} pipeline is already running. Wait for it to complete.",
+              code: :already_running,
+              tool: tool
+            )
+          end
+
+          handed_off = false
+          held_lock = nil
+          begin
+            config = Woods.configuration
+            output_dir = config.output_dir if config.respond_to?(:output_dir)
+            lock = output_dir && build_extraction_lock(output_dir)
+            if lock
+              unless acquire_lock_briefly(lock)
+                return respond_err.call(
+                  'Another writer holds the extraction lock (a rake task or the watch daemon ' \
+                  'is writing this index). Try again shortly.',
+                  code: :locked,
+                  tool: tool
+                )
+              end
+
+              held_lock = lock
             end
 
-            guard&.record!(:embedding)
+            # Built before the flag flips: a runner_builder that raises must
+            # still release the lock and the slot on the way out.
+            runner = runner_builder.call(output_dir)
+
+            # From here the background hand-off owns both the on-disk lock and
+            # the in-process slot: run_pipeline_in_background releases them on
+            # every one of its own paths.
+            handed_off = true
+            run_pipeline_in_background(
+              kind: kind, tool: tool, lock: lock, task_store: task_store,
+              respond: respond, respond_err: respond_err, runner: runner,
+              started: started, started_message: started_message
+            )
+          rescue SystemCallError => e
+            respond_err.call(
+              'The index directory\'s writer lock could not be taken — this is a filesystem ' \
+              "permissions problem, not a corrupt index (#{e.class}: #{e.message}). Make the index " \
+              'directory writable by this process, then invoke the tool again.',
+              code: :lock_unwritable,
+              tool: tool,
+              exception: e.class.name
+            )
+          ensure
+            unless handed_off
+              held_lock&.release
+              pipeline_finish(kind)
+            end
+          end
+        end
+
+        # Run a pipeline on a background thread and answer the caller.
+        #
+        # Both pipeline tools reached this point with the same shape: a lock
+        # they may or may not hold, a runner lambda, and the need to answer
+        # immediately because a full run takes minutes. What differs now is
+        # *how* they answer.
+        #
+        # When the client declared the Tasks extension, the answer is a durable
+        # `CreateTaskResult`. That is the whole point of the extension here: the
+        # handle outlives this process, so a client that disconnects mid-run can
+        # reconnect and still learn whether extraction succeeded — and if the
+        # process dies, {Tasks::Store} resolves the orphaned record to `failed`
+        # instead of leaving an agent polling a run that no longer exists.
+        #
+        # When it did not, the answer is exactly what it always was. The spec is
+        # explicit that a task must never go to a client that did not opt in:
+        # such a client would read the handle as the final result and report a
+        # completed run that had not started.
+        #
+        # @param kind [Symbol] :extraction or :embedding, for the in-process lock
+        # @param tool [String] tool name, for the task record and error text
+        # @param lock [Woods::Coordination::PipelineLock, nil]
+        # @param task_store [Tasks::Store, nil] nil disables the task path
+        # @param respond [Method] the text-response builder
+        # @param runner [Proc] the actual work
+        # @param started_message [String] legacy fire-and-forget message
+        # @return [Hash, MCP::Tool::Response]
+        def run_pipeline_in_background(kind:, tool:, lock:, task_store:, respond:, respond_err:, runner:, started:,
+                                       started_message:)
+          # Ownership of the on-disk lock transfers to the background thread
+          # the moment Thread.new succeeds — its ensure releases it when the
+          # run finishes. Before that point (guard failures, started hook),
+          # THIS method owns the lock and must release it on the way out
+          # (L6): the rescue below covers only SystemCallError/IOError, so a
+          # guard bug raising anything else used to leak the on-disk lock
+          # and block every later writer until the stale window expired.
+          handoff = false
+          begin
+            task = create_pipeline_task(task_store, tool)
+            started.call
 
             Thread.new do
-              # Share the rake-task wiring so the MCP path picks up the
-              # provider-tuned TextPreparer + token-aware chunker. Without
-              # this, MCP-triggered embedding still hit Ollama's "input
-              # length exceeds context length" error after the rake path
-              # was fixed in PR #70.
-              indexer = Woods::Tasks.build_embed_indexer
-              incremental ? indexer.index_incremental : indexer.index_all
-            rescue StandardError => e
+              # Heartbeat, like the rake writers: a full run on a large host can
+              # outlive the lock's stale window, and an untouched lock would be
+              # retired by the next contender mid-run — recreating the two-writer
+              # clobber.
+              if lock
+                Woods::Coordination::LockHeartbeat.run(lock) { runner.call }
+              else
+                runner.call
+              end
+              task_store&.complete!(task.id, result: pipeline_task_result(tool)) if task
+            rescue StandardError, ScriptError => e
+              # ScriptError (SyntaxError, LoadError) is not a StandardError, and
+              # +runner.call+ can lazily +require_relative+ the extractor — a
+              # half-typed file must degrade this background thread, not kill it
+              # silently while the task record sits at "working" until pid-death
+              # (see the "rescue ScriptError anywhere a reload can happen" rule).
               logger = defined?(Rails) ? Rails.logger : Logger.new($stderr)
-              logger.error("[Woods] Pipeline embed failed: #{e.message}")
+              logger.error("[Woods] Pipeline #{kind} failed: #{e.message}")
+              # Recording the failure is the half that was missing: previously the
+              # error reached a log the agent cannot read, and the tool had
+              # already reported success.
+              task_store&.fail!(task.id, message: "#{e.class}: #{e.message}") if task
             ensure
-              Woods::MCP::Server.send(:pipeline_finish, :embedding)
+              lock&.release
+              Woods::MCP::Server.send(:pipeline_finish, kind)
             end
+            handoff = true
 
-            respond.call(JSON.pretty_generate({
-                                                status: 'started',
-                                                message: 'Embedding pipeline started in background thread'
-                                              }))
+            return Tasks::Extension.create_task_result(task) if task
+
+            respond.call(JSON.pretty_generate({ status: 'started', message: started_message }))
+          rescue SystemCallError, IOError => e
+            respond_err.call(
+              'The task could not be durably recorded, so the pipeline was not started.',
+              code: :task_store_unavailable,
+              tool: tool,
+              exception: e.class.name
+            )
+          ensure
+            unless handoff
+              lock&.release
+              Woods::MCP::Server.send(:pipeline_finish, kind)
+            end
           end
         end
 
+        # Mint a task record, or return nil to take the legacy path.
+        #
+        # Nil only when the client did not opt in. Once a client opts in, task
+        # durability is part of the response contract; a write failure propagates
+        # to {run_pipeline_in_background}, which fails closed before work starts.
+        #
+        # @return [Tasks::Store::Task, nil]
+        def create_pipeline_task(task_store, tool)
+          return nil unless task_store && Tasks::RequestCapture.tasks_requested?
+
+          task_store.create!(tool: tool)
+        end
+
+        # What `tasks/get` hands back on success — shaped like the synchronous
+        # tool result the caller would have received had it waited.
+        def pipeline_task_result(tool)
+          {
+            'content' => [{ 'type' => 'text', 'text' => "#{tool} completed successfully." }],
+            'isError' => false
+          }
+        end
+
         # Acquire a pipeline-kind lock atomically. Returns false when
         # another thread is already running that kind of pipeline (so the
         # caller can refuse the new request instead of racing the running
@@ -1117,8 +1642,21 @@ module Woods
             when 'clear_locks'
               lock = operator[:pipeline_lock]
               if lock
-                lock.release
-                respond.call(JSON.pretty_generate({ repaired: true, action: 'clear_locks' }))
+                outcome = lock.retire_stale
+                case outcome
+                when :cleared
+                  respond.call(JSON.pretty_generate({ repaired: true, action: 'clear_locks', outcome: 'cleared' }))
+                when :missing
+                  respond_err.call(
+                    'No pipeline lock exists; nothing was repaired.',
+                    code: :lock_missing, tool: 'pipeline_repair', action: action, repaired: false
+                  )
+                when :not_stale
+                  respond_err.call(
+                    'The pipeline lock is active and was not cleared.',
+                    code: :lock_active, tool: 'pipeline_repair', action: action, repaired: false
+                  )
+                end
               else
                 respond_err.call(
                   'Pipeline lock is not configured.',
@@ -1128,7 +1666,22 @@ module Woods
                 )
               end
             when 'reset_cooldowns'
-              respond.call(JSON.pretty_generate({ repaired: true, action: 'reset_cooldowns' }))
+              guard = operator[:pipeline_guard]
+              if guard.nil?
+                respond_err.call(
+                  'Pipeline guard is not configured.',
+                  code: :not_configured,
+                  config_key: 'operator.pipeline_guard',
+                  tool: 'pipeline_repair'
+                )
+              elsif guard.reset!(:all)
+                respond.call(JSON.pretty_generate({ repaired: true, action: action, outcome: 'reset' }))
+              else
+                respond_err.call(
+                  'No pipeline cooldown state exists; nothing was repaired.',
+                  code: :cooldown_state_missing, tool: 'pipeline_repair', action: action, repaired: false
+                )
+              end
             else
               respond_err.call(
                 "Unknown repair action: #{action}",
@@ -1352,7 +1905,7 @@ module Woods
                 'notion_api_token is not configured. Set it in Woods.configure or via the NOTION_API_TOKEN env var.',
                 code: :not_configured,
                 config_key: 'notion_api_token',
-                doc_link: 'docs/NOTION_EXPORT.md',
+                doc_link: 'docs/NOTION_INTEGRATION.md',
                 tool: 'notion_sync'
               )
             end
@@ -1362,7 +1915,7 @@ module Woods
                 'notion_database_ids is not configured. Set it in Woods.configure.',
                 code: :not_configured,
                 config_key: 'notion_database_ids',
-                doc_link: 'docs/NOTION_EXPORT.md',
+                doc_link: 'docs/NOTION_INTEGRATION.md',
                 tool: 'notion_sync'
               )
             end
@@ -1452,6 +2005,20 @@ module Woods
         # 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)
+          # 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
+            reader.respond_to?(:with_pinned_generation)
+
+          reader.with_pinned_generation do
+            build_status_payload(reader, retriever, index_dir, bootstrap_state)
+          end
+        end
+
+        def build_status_payload(reader, retriever, index_dir, bootstrap_state)
           manifest = safe_manifest(reader)
           extracted_at = manifest && manifest['extracted_at']
           staleness = staleness_seconds(extracted_at)
@@ -1469,7 +2036,8 @@ module Woods
               index_dir: index_dir.to_s,
               update: Woods::UpdateCheck.status_hash
             },
-            index: index_section(manifest, extracted_at, staleness, index_dir),
+            index: index_section(manifest, extracted_at, staleness, index_dir, reader),
+            watch: watch_section(index_dir),
             retriever: {
               configured: !retriever.nil?,
               class: retriever&.class&.name
@@ -1498,7 +2066,7 @@ 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)
+        def index_section(manifest, extracted_at, staleness, index_dir, reader = nil)
           base = {
             extracted_at: extracted_at,
             staleness_seconds: staleness,
@@ -1512,6 +2080,9 @@ module Woods
             schema_sha: manifest && manifest['schema_sha']
           }
 
+          base.merge!(generation_fields(index_dir, reader))
+          base.merge!(working_tree_fields(index_dir))
+
           manifest_sha = manifest && manifest['git_sha']
           head_sha = manifest_sha ? resolve_head_sha(index_dir) : nil
           return base unless head_sha
@@ -1521,20 +2092,156 @@ module Woods
           base
         end
 
+        # The generation the index is published at.
+        #
+        # Every extraction mode that writes the *unit* index bumps this as its
+        # last write, so it answers "has the index moved?" without comparing
+        # timestamps — which `staleness_seconds` can't, since it measures
+        # wall-clock age rather than whether anything changed.
+        #
+        # One carve-out: `woods:extract_framework` writes only `rails_source/`
+        # and does not bump, so a framework re-extraction leaves this number
+        # where it was. That is deliberate — framework sources are pinned by the
+        # `Gemfile.lock`, reported separately above, and treating them as an
+        # index generation would invalidate every reader's cache for data that
+        # changes when dependencies do, not when the app does.
+        #
+        # @return [Hash]
+        def generation_fields(index_dir, reader = nil)
+          return {} unless index_dir
+
+          marker = Woods::Generation.new(output_dir: index_dir).current
+          return { generation: nil } if marker.number.zero?
+
+          fields = { generation: marker.number,
+                     generation_updated_at: marker.updated_at,
+                     generation_reason: marker.reason }
+          fields.merge(served_generation_fields(marker, reader))
+        rescue StandardError
+          {}
+        end
+
+        # What the *reader* is actually serving, which is not always what is
+        # published.
+        #
+        # `build_status` pins the reader so the manifest and counts above come
+        # from one generation, but this method reads `generation.json` from
+        # disk — so a publish landing mid-call would otherwise report a
+        # generation number beside counts from the previous one, the exact
+        # mismatch the pin is there to remove. When they differ, say so instead
+        # of quietly picking one.
+        def served_generation_fields(marker, reader)
+          return {} unless reader.respond_to?(:loaded_generation)
+
+          served = reader.loaded_generation
+          return {} if served.nil? || served == marker.number
+
+          { served_generation: served, generation_lag: marker.number - served }
+        rescue StandardError
+          {}
+        end
+
+        # Whether the working tree has uncommitted changes, and a fingerprint
+        # of them.
+        #
+        # `git_sha_matches_head` only sees *committed* HEAD, so an agent
+        # working through forty uncommitted edits could be told the index
+        # matches HEAD while every answer described the tree before those
+        # edits. `working_tree_dirty` is the fix for that.
+        #
+        # The fingerprint is a digest of `git status --porcelain` *as of this
+        # call*. Nothing records the digest the index was built at, so it does
+        # not answer "is this the same dirty state the index describes" — it
+        # gives a caller a stable identity for the current dirty state, so two
+        # of its own calls can be compared to detect the tree moving underneath
+        # it. Pair it with `generation` to tell "tree changed, index followed"
+        # from "tree changed, index has not caught up".
+        #
+        # @return [Hash]
+        def working_tree_fields(index_dir)
+          porcelain = resolve_working_tree_status(index_dir)
+          return {} if porcelain.nil?
+
+          { working_tree_dirty: !porcelain.empty?,
+            working_tree_fingerprint: Digest::SHA256.hexdigest(porcelain)[0, 16] }
+        end
+
+        # `git status --porcelain` for the repo containing +index_dir+, or nil
+        # when that can't be answered.
+        #
+        # capture3, not capture2e: stderr still must not reach the stdio
+        # transport, but folding it into stdout makes any warning git emits on a
+        # successful run — a stale index.lock notice, a detached-HEAD advisory,
+        # `core.fsmonitor` chatter — part of the "porcelain" output. A clean tree
+        # then reports dirty, and the fingerprint changes with the warning rather
+        # than with the code.
+        def resolve_working_tree_status(index_dir)
+          return nil unless index_dir
+
+          dir = index_dir.to_s
+          return nil unless File.directory?(dir)
+
+          output, _stderr, status = Open3.capture3('git', '-C', dir, 'status', '--porcelain')
+          status.success? ? output : nil
+        rescue StandardError
+          nil
+        end
+
+        # The watch daemon's state, so an agent can branch on whether anything
+        # is keeping this index current.
+        #
+        # Three states matter and they are not interchangeable: `running`
+        # (current, or current within a debounce window), `degraded` (alive but
+        # unable to update — the reason says why, and the index is frozen at a
+        # known generation), and `stopped`/`absent` (nothing is maintaining
+        # this index; fall back to whatever the last explicit run left).
+        #
+        # @return [Hash]
+        def watch_section(index_dir)
+          return { state: 'absent' } unless index_dir
+
+          path = File.join(index_dir.to_s, Woods::Watch::Status::FILENAME)
+          return { state: 'absent' } unless File.exist?(path)
+
+          # AtomicFile.read: the daemon's reasons contain em dashes, and a
+          # US-ASCII default external encoding turns a plain File.read of them
+          # into an Encoding::InvalidByteSequenceError — raising out of
+          # woods_status entirely rather than degrading it.
+          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
+          # 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
+          # different questions and an operator wants both.
+          status = Woods::Watch::Status.new(output_dir: index_dir)
+          { state: record['state'], reason: record['reason'], generation: record['generation'],
+            pid: record['pid'], updated_at: record['updated_at'],
+            alive: status.alive?, stale_after_seconds: Woods::Watch::Status::STALE_AFTER,
+            last_action: record['last_action'], last_duration_ms: record['last_duration_ms'] }
+        rescue StandardError
+          { state: 'absent' }
+        end
+
         # Resolve the current HEAD SHA for the git repo containing +index_dir+.
         # Returns nil when git is unavailable or +index_dir+ is not in a repo —
         # callers treat nil as "can't compare" rather than "mismatch".
         #
-        # Uses +capture2e+ so git's "fatal: not a git repository" stderr banner
-        # does not leak through the MCP stdio transport. MCP clients that parse
-        # stderr for protocol framing can't tolerate stray lines.
+        # capture3 keeps git's stderr out of the MCP stdio transport — clients
+        # that parse stderr for protocol framing can't tolerate stray lines —
+        # *and* out of the SHA. capture2e folded them together, so a warning on
+        # an otherwise successful `rev-parse` (a stale `index.lock` notice, a
+        # `core.fsmonitor` complaint) was concatenated into the value this
+        # method returns and compared against the manifest as if it were a SHA.
+        # Same hazard as {#resolve_working_tree_status}, one probe over.
         def resolve_head_sha(index_dir)
           return nil unless index_dir
 
           dir = index_dir.to_s
           return nil unless File.directory?(dir)
 
-          output, status = Open3.capture2e('git', '-C', dir, 'rev-parse', 'HEAD')
+          output, _stderr, status = Open3.capture3('git', '-C', dir, 'rev-parse', 'HEAD')
           status.success? ? output.strip : nil
         rescue Errno::ENOENT, Errno::EACCES
           # git not installed or not executable on this host — equivalent to
@@ -1614,28 +2321,74 @@ module Woods
         def register_resource_handler(server, reader)
           server.resources_read_handler do |params|
             uri = params[:uri]
-            case uri
-            when 'codebase://manifest'
-              [{ uri: uri, mimeType: 'application/json', text: JSON.pretty_generate(reader.manifest) }]
-            when 'codebase://graph'
-              [{ uri: uri, mimeType: 'application/json', text: JSON.pretty_generate(reader.raw_graph_data) }]
-            when %r{\Acodebase://unit/(.+)\z}
-              identifier = Regexp.last_match(1)
-              unit = reader.find_unit(identifier)
-              if unit
-                [{ uri: uri, mimeType: 'application/json', text: JSON.pretty_generate(unit) }]
-              else
-                [{ uri: uri, mimeType: 'text/plain', text: "Unit not found: #{identifier}" }]
-              end
-            when %r{\Acodebase://type/(.+)\z}
-              type = Regexp.last_match(1)
-              units = reader.list_units(type: type)
-              [{ uri: uri, mimeType: 'application/json', text: JSON.pretty_generate(units) }]
-            else
-              [{ uri: uri, mimeType: 'text/plain', text: "Unknown resource: #{uri}" }]
+            kind, target = parse_resource_uri(uri)
+            raise ::MCP::Server::ResourceNotFoundError.new(uri, params) unless kind
+
+            payload = resource_payload(reader, kind, target)
+            raise ::MCP::Server::ResourceNotFoundError.new(uri, params) if payload.nil?
+
+            [{ uri: uri, mimeType: 'application/json', text: JSON.pretty_generate(payload) }]
+          rescue ::MCP::Server::ResourceNotFoundError
+            raise
+          rescue JSON::ParserError, SystemCallError, IOError, TypeError => e
+            raise corrupt_resource_error(uri, params, e)
+          end
+        end
+
+        def parse_resource_uri(uri)
+          return [:manifest, nil] if uri == 'codebase://manifest'
+          return [:graph, nil] if uri == 'codebase://graph'
+          return unless uri.is_a?(String)
+
+          parsed = URI.parse(uri)
+          return unless parsed.scheme == 'codebase'
+          return unless %w[unit type].include?(parsed.host)
+          return if parsed.userinfo || parsed.port || parsed.query || parsed.fragment || parsed.opaque
+
+          raw_target = parsed.path.to_s.delete_prefix('/')
+          return if raw_target.empty? || raw_target.include?('/')
+
+          target = URI::DEFAULT_PARSER.unescape(raw_target).force_encoding(Encoding::UTF_8)
+          return unless target.valid_encoding?
+          return if target.match?(%r{[%\\/\x00-\x1f\x7f]})
+          return if %w[. ..].include?(target)
+
+          [parsed.host.to_sym, target]
+        rescue URI::InvalidURIError
+          nil
+        end
+
+        def resource_payload(reader, kind, target)
+          case kind
+          when :manifest
+            reader.manifest.tap { |value| raise TypeError unless value.is_a?(Hash) }
+          when :graph
+            reader.raw_graph_data.tap do |value|
+              raise TypeError unless value.is_a?(Hash) && value['nodes'].is_a?(Hash) && value['edges'].is_a?(Hash)
+            end
+          when :unit
+            reader.find_unit(target).tap do |value|
+              raise TypeError if value && (!value.is_a?(Hash) || value['identifier'] != target)
+            end
+          when :type
+            return nil unless IndexReader::TYPE_TO_DIR.key?(target)
+
+            reader.list_units(type: target).tap do |value|
+              raise TypeError unless value.is_a?(Array) && value.all?(Hash)
             end
           end
         end
+
+        def corrupt_resource_error(uri, params, original_error)
+          ::MCP::Server::RequestHandlerError.new(
+            'Resource artifact is unavailable or malformed.',
+            params,
+            error_type: :internal_error,
+            original_error: original_error,
+            error_code: ::JsonRpcHandler::ErrorCode::INTERNAL_ERROR,
+            error_data: { uri: uri, error_code: 'corrupt_artifact' }
+          )
+        end
       end
     end
   end