woods 2.0.0.beta4 → 2.0.1

data/lib/woods/extractor.rb

@@ -2103,10 +2103,28 @@ module Woods
       end
 
       @git_available = complete_git_history?
+    rescue Errno::ENOENT
+      warn_missing_git_executable
+      @git_available = false
     rescue StandardError
       @git_available = false
     end
 
+    # An explicit Git directory still requests history when .git is not mounted
+    # at Rails.root. Ordinary source archives remain a supported, quiet path.
+    #
+    # @return [void]
+    def warn_missing_git_executable
+      configured = [GitCommand::OVERRIDE_KEY, 'GIT_DIR'].any? { |key| !ENV[key].to_s.empty? }
+      return unless configured || File.exist?(File.join(Rails.root.to_s, '.git'))
+
+      Rails.logger.warn(
+        '[Woods] Git history unavailable: git executable was not found in PATH. ' \
+        'Extraction continues without per-unit Git metadata. Install Git in the extraction environment ' \
+        'and run a full extraction to refresh Git metadata.'
+      )
+    end
+
     # A shallow HEAD resolves but represents an incomplete ancestry. Do not
     # turn that boundary into apparent one-commit/new-file churn facts.
     def complete_git_history?
@@ -2134,19 +2152,19 @@ module Woods
       cause = error.to_s.lines.first.to_s.strip
       Rails.logger.warn(
         '[Woods] git cannot resolve HEAD for this working tree, so no unit will carry git ' \
-        "metadata: #{cause}. Over a linked worktree in a container, mount the canonical git " \
-        'directory and point WOODS_GIT_DIR at it; GIT_DIR alone is not enough, because the ' \
-        "worktree's private git directory reaches the shared one through a relative pointer."
+        "metadata: #{cause}. For a linked worktree, mount the complete shared .git directory " \
+        'at its original path, or set WOODS_GIT_DIR to /mounted-common/worktrees/<id> within ' \
+        'the relocated complete layout. Derive <id> from the worktree Git metadata, not its branch name; ' \
+        "selecting /mounted-common itself uses the primary checkout's HEAD."
       )
     end
 
     # The git command line every enrichment call runs.
     #
     # `-C <root>` keeps the result independent of the process working
-    # directory. `WOODS_GIT_DIR` wins when set: it names the canonical git
-    # directory directly, which is the escape hatch for a container that can
-    # mount that directory but not the host path a worktree pointer names
-    # (B-181).
+    # directory. `WOODS_GIT_DIR` wins when set and selects that git directory's
+    # HEAD. A relocated linked worktree needs its worktree-specific directory
+    # inside the complete shared Git layout (B-181).
     #
     # @param args [Array<String>] git arguments
     # @return [Array<String>] full argv

data/lib/woods/git_command.rb

@@ -7,18 +7,17 @@ module Woods
   # than at the process working directory, so extraction launched from another
   # checkout never reports that checkout's history.
   #
-  # `WOODS_GIT_DIR` wins when set. It is the escape hatch for a container over
-  # a linked worktree: `.git` there is a file naming an absolute host path that
-  # may not be mounted, and git's own `GIT_DIR` is not enough, because a
-  # worktree's private git directory reaches the shared object store through a
-  # relative `commondir` pointer that resolves outside the mount, which
-  # `GIT_COMMON_DIR` does not override (B-181, B-186).
+  # `WOODS_GIT_DIR` wins when set and selects HEAD exactly as `--git-dir`
+  # does. For a container over a linked worktree, select its private directory
+  # within the complete mounted Git layout (shared objects, refs and worktrees).
+  # Selecting the shared root instead selects the primary checkout's HEAD.
+  # A same-path mount that resolves the worktree's .git pointer needs no override.
   #
   # Three call sites use this, and the documentation promises all three:
   # per-unit enrichment (`Extractor`), manifest provenance (`GitProvenance`),
   # and the `woods:incremental` diff range (`lib/tasks/woods.rake`).
   module GitCommand
-    # Environment variable naming the canonical git directory.
+    # Environment variable naming the explicitly selected git directory.
     OVERRIDE_KEY = 'WOODS_GIT_DIR'
 
     module_function

data/lib/woods/git_provenance.rb

@@ -85,12 +85,10 @@ module Woods
       ''
     end
 
-    # +WOODS_GIT_DIR+ names the canonical git directory outright and wins when
-    # set. It is the escape hatch for a container that can mount that
-    # directory but not the host path a linked worktree's +.git+ file points
-    # at; git's own +GIT_DIR+ is not enough there, because a worktree's
-    # private git directory reaches the shared one through a relative
-    # +commondir+ pointer that resolves outside the mount.
+    # +WOODS_GIT_DIR+ selects a git directory and its HEAD outright and wins when
+    # set. A relocated linked worktree needs its private directory inside the
+    # complete mounted Git layout, preserving access to shared objects and refs.
+    # Selecting the shared root instead uses the primary checkout's HEAD.
     #
     # @param args [Array<String>] git arguments
     # @return [Array<String>] full argv

data/lib/woods/mcp/bearer_auth.rb

@@ -55,7 +55,7 @@ module Woods
         expected = resolve_token
         header = env['HTTP_AUTHORIZATION'].to_s
         # Only the ASCII scheme changes case; do not normalize or trim the token.
-        presented = header.match?(/\A[Bb][Ee][Aa][Rr][Ee][Rr] /) ? header[7..] : nil
+        presented = header.b.match?(/\A[Bb][Ee][Aa][Rr][Ee][Rr] /) ? header.byteslice(7..) : nil
 
         if expected && presented && Rack::Utils.secure_compare(expected, presented)
           @app.call(env)

data/lib/woods/mcp/bootstrapper.rb

@@ -176,7 +176,9 @@ module Woods
         retriever = build_retriever_from_config(config, resolved, artifact, state)
         probe_and_mark_state(config, state)
         derive_state_from_store_health(state)
-        warn "[woods-mcp] semantic search: #{state.status} (#{config.embedding_provider})"
+        corpus = retriever.corpus_status(include_types: false) if retriever.respond_to?(:corpus_status)
+        corpus_note = corpus ? "; corpus: #{corpus[:state]}" : ''
+        warn "[woods-mcp] semantic search: #{state.status} (#{config.embedding_provider})#{corpus_note}"
 
         [retriever, state]
       end

data/lib/woods/mcp/initialization_guidance.rb

@@ -11,7 +11,7 @@ module Woods
 
       WORKFLOW = <<~TEXT
         Start with woods_status: check index readiness, generation freshness and relevant type counts before relying on results.
-        For exact names, discover identifiers with search (prefer literal exact_prefix/exact_suffix), then inspect with lookup. For conceptual questions, use codebase_retrieve only when woods_status reports retrieval enabled. Otherwise use search and lookup.
+        For exact names, discover identifiers with search (prefer literal exact_prefix/exact_suffix), then inspect with lookup. For conceptual questions, check retrieval mode and data in woods_status before codebase_retrieve; structural readiness alone is insufficient. Otherwise use search and lookup.
         Follow dependencies or dependents at depth 1 or 2; narrow types and via before paging. Respect partial results and limits: a missing match is not proof of absence, and a partial traversal does not establish every dependent or leaf.
         Verify important conclusions against current source and tests. Recorded relationships and inferred downstream impact do not prove runtime execution or test coverage.
         Registration does not authorize extraction, configuration changes, or live Console access. Use only the tools registered here and operate within the user's authorized scope.

data/lib/woods/mcp/origin_guard.rb

@@ -2,7 +2,7 @@
 
 require 'json'
 
-require_relative '../util/host_guard'
+require_relative 'origin_policy'
 
 module Woods
   module MCP
@@ -21,17 +21,13 @@ module Woods
     # also requiring Host to appear in the allow-list (or to be a loopback
     # address), we close that gap even when Rails is bound to 0.0.0.0.
     #
-    # Port-matching: an allow-list entry WITHOUT a port (`http://localhost`)
-    # matches that host on any port. An entry WITH a port (`http://localhost:3000`)
-    # requires an exact port match. Specify explicit ports when port isolation
-    # matters.
+    # Cross-origin entries match exactly. A portless entry also permits
+    # same-authority requests on other ports; cross-port browser clients need
+    # their actual origin explicitly configured, as required by the SDK.
     #
     # Also answers CORS preflight (OPTIONS) with the matching allow-list.
     class OriginGuard
-      DEFAULT_ALLOWED = %w[
-        http://localhost http://127.0.0.1 http://[::1]
-        https://localhost https://127.0.0.1 https://[::1]
-      ].freeze
+      DEFAULT_ALLOWED = OriginPolicy::DEFAULT_ORIGINS
 
       # Hosts that always pass the Host-header check even without an explicit
       # allow-list entry — they resolve to loopback by definition and cannot
@@ -56,6 +52,7 @@ module Woods
       #   which runs after Rails railtie initializers captured the middleware
       #   arguments — still takes effect (#183). Empty/nil falls back to
       #   {DEFAULT_ALLOWED}.
+      # @param policy [OriginPolicy, nil] Captured policy also passed to the SDK
       # @param path [String, nil] When set, only requests whose PATH_INFO
       #   starts with this prefix are guarded — everything else passes
       #   straight through to the app. Nil (the default) guards every request.
@@ -82,27 +79,35 @@ module Woods
         method = env['REQUEST_METHOD']
         host = env['HTTP_HOST']
 
-        return forbidden if origin && !origin_allowed?(origin)
-        return forbidden_host if host && !host_allowed?(host)
+        return forbidden unless policy.origin_allowed?(origin, host: host)
+        return forbidden_host unless policy.host_allowed?(host)
 
         return preflight(origin) if method == 'OPTIONS'
 
         status, headers, body = @app.call(env)
-        headers = cors_headers(origin).merge(headers) if origin && origin_allowed?(origin)
+        headers = cors_headers(origin).merge(headers) if origin
         [status, headers, body]
       end
 
+      # The same lazily captured immutable policy is passed to the transport.
+      # @return [OriginPolicy]
+      def policy
+        return @policy if @policy
+
+        @policy_mutex.synchronize do
+          @policy ||= OriginPolicy.new(allowed_origins: @allowed_source.call)
+        end
+      end
+
       private
 
-      def initialize_options(app, allowed_origins: nil, path: nil, enabled: nil)
+      def initialize_options(app, allowed_origins: nil, path: nil, enabled: nil, policy: nil)
         @app = app
         @path = path
         @enabled = enabled
-        if allowed_origins.respond_to?(:call)
-          @allowed_source = allowed_origins
-        else
-          build_allow_list(allowed_origins)
-        end
+        @policy = policy
+        @policy_mutex = Mutex.new
+        @allowed_source = allowed_origins.respond_to?(:call) ? allowed_origins : -> { allowed_origins }
       end
 
       # @param env [Hash] Rack environment
@@ -114,66 +119,8 @@ module Woods
         true
       end
 
-      # Normalize a raw allow-list into `@allowed` + `@allowed_hosts`.
-      #
-      # @param origins [Array<String>, nil]
-      # @return [Array<String>] the normalized allow-list
-      def build_allow_list(origins)
-        allowed = Array(origins).compact.reject { |o| o.to_s.strip.empty? }.map { |o| normalize(o) }
-        allowed = DEFAULT_ALLOWED.dup if allowed.empty?
-        @allowed_hosts = allowed.map { |o| extract_host(o) }.compact.uniq
-        @allowed = allowed
-      end
-
-      # The allow-list, resolving a deferred source on first use. Memoized —
-      # configuration is settled by the time the first request arrives.
-      #
-      # @return [Array<String>]
-      def allowed
-        @allowed || build_allow_list(@allowed_source.call)
-      end
-
-      # @return [Array<String>] hosts extracted from the allow-list
-      def allowed_hosts
-        allowed
-        @allowed_hosts
-      end
-
-      def normalize(origin)
-        origin.to_s.sub(%r{/\z}, '').downcase
-      end
-
-      def extract_host(origin)
-        host = origin.to_s.sub(%r{\Ahttps?://}, '').sub(%r{/.*\z}, '').downcase
-        host.empty? ? nil : host
-      end
-
-      def host_allowed?(host)
-        # Canonicalize (strip port, trailing dot, IPv6 brackets) via the
-        # shared helper so Qdrant and OriginGuard stay in sync on bypass
-        # notations. `normalized` keeps the port for literal allow-list
-        # lookups; `bare` drops it for loopback matching.
-        normalized = host.to_s.downcase.sub(/\.\z/, '')
-        bare = Util::HostGuard.canonicalize(host)
-
-        # Reject non-canonical numeric hosts. Net::HTTP / getaddrinfo
-        # would happily resolve `0x7f000001` or `2130706433` to 127.0.0.1,
-        # bypassing the loopback allow-list.
-        return false if Util::HostGuard.suspicious_numeric_host?(bare)
-
-        return true if LOOPBACK_HOSTS.include?(bare)
-
-        allowed_hosts.include?(normalized) || allowed_hosts.include?(bare)
-      end
-
-      def origin_allowed?(origin)
-        return false if origin.match?(/[[:cntrl:]]/)
-
-        allowed.include?(normalize(origin)) || allowed.include?(normalize(origin).sub(/:\d+\z/, ''))
-      end
-
       def preflight(origin)
-        headers = origin && origin_allowed?(origin) ? cors_headers(origin) : {}
+        headers = origin ? cors_headers(origin) : {}
         [204, headers, []]
       end
 

data/lib/woods/mcp/origin_policy.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'uri'
+require_relative '../util/host_guard'
+
+module Woods
+  module MCP
+    # Immutable HTTP policy shared by Woods preflight and the MCP transport.
+    # Explicit cross-origin entries normalize HTTP(S) default ports. A portless entry also permits
+    # same-authority requests on another port, which the SDK accepts natively.
+    # No request header is rewritten and SDK rebinding protection stays enabled.
+    class OriginPolicy
+      LOOPBACK_HOSTS = %w[localhost 127.0.0.1 ::1].freeze
+      DEFAULT_ORIGINS = %w[
+        http://localhost http://127.0.0.1 http://[::1]
+        https://localhost https://127.0.0.1 https://[::1]
+      ].freeze
+
+      # @param allowed_origins [Array<String>, nil] Explicit browser origins
+      def initialize(allowed_origins: nil)
+        entries = Array(allowed_origins).compact.reject do |entry|
+          entry.to_s.valid_encoding? && entry.to_s.strip.empty?
+        end
+        @explicit_origins = entries.map { |entry| configured_origin(entry) }.uniq.freeze
+        @allowed = (@explicit_origins.empty? ? DEFAULT_ORIGINS : @explicit_origins).freeze
+        @allowed_hosts = @explicit_origins.map do |origin|
+          host = authority(origin)
+          # SDK bare IPv6 host entries omit brackets; host:port entries retain
+          # them. URI#host alone retains brackets and loses explicit ports.
+          (host.end_with?(']') ? host[1...-1] : host).freeze
+        end.uniq.freeze
+        @transport_options = { allowed_origins: transport_origins, allowed_hosts: @allowed_hosts }.freeze
+        freeze
+      end
+
+      # @return [Hash] Constructor options supported by the MCP SDK
+      attr_reader :transport_options
+
+      # @param host [String, nil] Unmodified HTTP Host header
+      # @return [Boolean] Whether the request authority is allowed
+      def host_allowed?(host)
+        return true if host.nil?
+        return false unless host.is_a?(String) && host.valid_encoding?
+
+        parsed = parsed_origin("http://#{host}")
+        return false unless parsed
+
+        hostname = parsed.hostname.downcase
+        return false if Util::HostGuard.suspicious_numeric_host?(hostname)
+        return true if LOOPBACK_HOSTS.include?(hostname)
+
+        @allowed_hosts.include?(host.downcase) || @allowed_hosts.include?(hostname)
+      end
+
+      # @param origin [String, nil] Unmodified HTTP Origin header
+      # @param host [String, nil] Unmodified HTTP Host header
+      # @return [Boolean] Whether preflight and SDK dispatch can both accept it
+      def origin_allowed?(origin, host:)
+        return true if origin.nil?
+        return false unless parsed_origin(origin)
+
+        normalized = normalized_origin(origin)
+        return true if @explicit_origins.include?(normalized)
+        return false unless @allowed.include?(normalized) || @allowed.include?(normalized.sub(/:\d+\z/, ''))
+        return false unless host.is_a?(String) && host.valid_encoding?
+
+        # Matches the SDK's same-authority rule. The origin's scheme selects
+        # its default port; request.scheme is unreliable behind reverse proxies.
+        default_port = normalized.start_with?('https://') ? ':443' : ':80'
+        authority(normalized).delete_suffix(default_port) == host.downcase.delete_suffix(default_port)
+      end
+
+      private
+
+      def configured_origin(entry)
+        raw = entry.to_s
+        normalized = raw.downcase.sub(%r{/\z}, '') if raw.valid_encoding?
+        unless parsed_origin(normalized)
+          label = raw.b.byteslice(0, 160).inspect
+          raise ArgumentError, "Invalid MCP allowed origin #{label}: expected http(s)://host[:port] without a path"
+        end
+
+        normalized_origin(normalized).freeze
+      end
+
+      def normalized_origin(origin)
+        value = origin.downcase
+        value.delete_suffix(value.start_with?('https://') ? ':443' : ':80')
+      end
+
+      # The SDK compares configured origins literally. Include equivalent
+      # default-port spellings without rewriting the incoming request headers.
+      def transport_origins
+        @explicit_origins.flat_map do |origin|
+          parsed = parsed_origin(origin)
+          default = parsed.scheme == 'https' ? 443 : 80
+          parsed.port == default ? [origin, "#{origin}:#{default}"] : [origin]
+        end.uniq.map(&:freeze).freeze
+      end
+
+      def authority(origin)
+        origin.sub(%r{\Ahttps?://}, '')
+      end
+
+      # Parse only serialized HTTP origins, never URLs with paths, userinfo,
+      # query strings, fragments or whitespace. The comparison layer handles
+      # default-port equivalence separately from parsing.
+      def parsed_origin(origin)
+        return unless origin.is_a?(String) && origin.valid_encoding? && origin.ascii_only?
+        return if origin.match?(/[[:space:][:cntrl:]]/)
+
+        parsed = URI.parse(origin)
+        return unless %w[http https].include?(parsed.scheme&.downcase)
+        return unless parsed.host && !parsed.host.empty?
+        return unless parsed.path.to_s.empty? && !parsed.userinfo && !parsed.query && !parsed.fragment
+        return unless parsed.port&.between?(1, 65_535)
+
+        parsed
+      rescue URI::InvalidURIError, ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/woods/mcp/server.rb

@@ -12,6 +12,7 @@ require_relative '../atomic_file'
 require_relative '../generation'
 require_relative '../tasks'
 require_relative '../watch/status'
+require_relative '../watch/supervision_status'
 require_relative '../filename_utils'
 require_relative '../update_check'
 require_relative '../retrieval/source_evidence'
@@ -928,6 +929,7 @@ module Woods
           coerce = method(:coerce_array)
           stale_check = method(:stale_index_result?)
           degraded_response = method(:degraded_retrieval_response)
+          corpus_status = method(:retriever_corpus_status)
           retrieval_mode = retriever.respond_to?(:mode) ? retriever.mode : :semantic
           server.define_tool(
             name: 'codebase_retrieve',
@@ -954,13 +956,13 @@ module Woods
                                'rails_source, test_mapping, etc.). Overrides the default test_mapping exclusion. ' \
                                '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 ' \
+                               'falls back to rank-within-type over the available vectors. The response appends a "Type rank ' \
                                'context" table with per-type: source, rank in unfiltered top-K, global_k, ' \
-                               'total_of_type. Read source to tell the cases apart: in_top_k (strong match), ' \
+                               'total_of_type (retrieval metadata records, not structural or embedded units). ' \
+                               'Read source to tell the cases apart: in_top_k (strong match), ' \
                                'within_type_fallback (weak match surfaced by the fallback), outside_top_k ' \
-                               '(index has this type but other requested types filled the result), absent ' \
-                               '(zero units of this type in the index).'
+                               '(retrieval metadata has this type but other requested types filled the result), absent ' \
+                               '(zero retrieval metadata records of this type; structural units may still exist).'
                 },
                 packages: { type: 'array', items: { type: 'string' },
                             description: 'Exact published nearest package owners. OR within the list; AND with paths and type eligibility.' },
@@ -1015,6 +1017,16 @@ module Woods
               )
             end
             if retriever
+              corpus = corpus_status.call(retriever, include_types: false)
+              if corpus && corpus[:state] == 'empty'
+                next respond_err.call(
+                  'Semantic retrieval has no vectors or retrieval metadata. The structural index may still be ready. ' \
+                  'Run `woods:embed` in the application environment and reload the index, or use ' \
+                  'explicit `WOODS_RETRIEVAL_MODE=lexical` and restart for retrieval without embeddings. ' \
+                  'Use `search` and `lookup` for structural discovery.',
+                  code: :empty_index, tool: 'codebase_retrieve', corpus: corpus
+                )
+              end
               begin
                 scope_options = if Retrieval::Scope.requested?(packages: packages, source_paths: source_paths)
                                   { packages: packages, source_paths: source_paths }
@@ -1138,12 +1150,15 @@ module Woods
 
           server.define_tool(
             name: 'trace_flow',
-            description: 'Trace execution flow from an entry point through the codebase',
+            description: 'Trace a source-derived flow from an exact indexed unit, optionally scoped by #method. ' \
+                         'Receiverless local calls may remain unexpanded; this is not proof of runtime execution.',
             input_schema: {
               properties: {
                 entry_point: {
                   type: 'string',
-                  description: 'Entry point (e.g., UsersController#create)'
+                  description: 'Exact UnitIdentifier, optionally followed by #method (e.g., UsersController#create ' \
+                               'or CheckoutService#order). Bare names identify units, including factories; ' \
+                               'a bare method name does not locate its owning class. Use search and lookup first.'
                 },
                 depth: {
                   type: 'integer',
@@ -2075,7 +2090,10 @@ module Woods
             name: 'woods_status',
             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. ' \
+                         'bootstrap state (hydrated / degraded / failed + reason), and feature flags. ' \
+                         'Top-level `ready` describes structural index availability. ' \
+                         'Semantic corpus diagnostics report local vector/metadata record counts separately; ' \
+                         'unknown counts are null, and nonempty counts do not prove complete embedding coverage. ' \
                          '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: {
@@ -2139,10 +2157,11 @@ module Woods
             },
             index: index_section(manifest, extracted_at, staleness, index_dir, reader, source_check),
             watch: watch_section(index_dir),
+            supervision: index_dir ? Woods::Watch::SupervisionStatus.read(index_dir.to_s) : { records: [] },
             retriever: {
               configured: !retriever.nil?,
               class: retriever&.class&.name,
-              **(retriever.respond_to?(:mode) && retriever.mode == :lexical ? { mode: 'lexical' } : {})
+              **retriever_status_fields(retriever)
             },
             bootstrap: bootstrap_state&.to_h,
             features: retrieval_features(config, resolved, retriever)
@@ -2151,6 +2170,19 @@ module Woods
 
         private
 
+        def retriever_status_fields(retriever)
+          return { mode: 'lexical' } if retriever.respond_to?(:mode) && retriever.mode == :lexical
+
+          corpus = retriever_corpus_status(retriever)
+          corpus ? { corpus: corpus } : {}
+        end
+
+        def retriever_corpus_status(retriever, include_types: true)
+          return if retriever.respond_to?(:mode) && retriever.mode == :lexical
+
+          retriever.corpus_status(include_types: include_types) if retriever.respond_to?(:corpus_status)
+        end
+
         # Assemble the +index+ sub-hash of woods_status, including a staleness
         # gate that compares +manifest.git_sha+ against the current HEAD. The
         # manifest captures +git_sha+ / +gemfile_lock_sha+ / +schema_sha+ at

data/lib/woods/railtie_support.rb

@@ -114,6 +114,7 @@ module Woods
         warn_late_console_path(config)
         return unless config.console_mcp_enabled && config.console_mcp_http_enabled
 
+        verify_console_origins!
         require 'woods/mcp/bearer_auth'
         token = config.console_mcp_token.to_s
         if token.empty?
@@ -147,6 +148,13 @@ module Woods
 
       private
 
+      def verify_console_origins!
+        require 'woods/mcp/origin_policy'
+        Woods::MCP::OriginPolicy.new(allowed_origins: config.console_mcp_allowed_origins)
+      rescue ArgumentError => e
+        raise Woods::ConfigurationError, "[Woods Console] #{e.message}"
+      end
+
       # Warn when the configured console path no longer matches the path the
       # stack was mounted at — the path was set after railtie initializers
       # captured the middleware arguments.

data/lib/woods/retrieval/corpus_status.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Woods
+  module Retrieval
+    # Bounded, local diagnostics: never probe remote stores or providers.
+    # Nonempty counts establish presence, not alignment, completeness, or
+    # provider health. Metadata-only corpora can still serve non-vector paths.
+    module CorpusStatus
+      module_function
+
+      # @return [Hash] state and independently known local store statistics
+      def build(vector_store, metadata_store, include_types: true)
+        vectors = local_stats(vector_store, include_types: include_types)
+        metadata = local_stats(metadata_store, include_types: include_types)
+        { state: state(vectors[:count], metadata[:count]), vectors: vectors, metadata: metadata }
+      end
+
+      def local_stats(store, include_types:)
+        return unknown unless store.respond_to?(:local_corpus_stats)
+
+        stats = store.local_corpus_stats(include_types: include_types)
+        return unknown unless stats[:count].is_a?(Integer) && stats[:count] >= 0
+
+        stats
+      rescue StandardError, NotImplementedError
+        unknown
+      end
+      private_class_method :local_stats
+
+      def unknown
+        { count: nil, by_type: nil, untyped_count: nil }
+      end
+      private_class_method :unknown
+
+      def state(vectors, metadata)
+        return 'unknown' if vectors.nil? || metadata.nil?
+        return 'empty' if vectors.zero? && metadata.zero?
+        return 'metadata_only' if vectors.zero?
+        return 'vectors_only' if metadata.zero?
+
+        'nonempty'
+      end
+      private_class_method :state
+    end
+  end
+end