woods 1.6.1 → 2.0.0.beta2

data/lib/woods/published_index/typed_unit_reader.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+
+module Woods
+  class PublishedIndex
+    # Reads one type's unit file directly from a pinned payload, bypassing
+    # {Woods::MCP::IndexReader#find_unit}'s identifier-only map, which lets a
+    # later `TYPE_DIRS` entry silently overwrite an earlier one when two
+    # types share an identifier.
+    #
+    # Split out of {PublishedIndex} for the same reason as {EdgeShaper}: a
+    # pure function of the payload directory and the reader's own per-type
+    # index, with no need to touch the retention lock.
+    module TypedUnitReader
+      # @param payload_dir [Pathname] the pinned generation's payload directory
+      # @param reader [Woods::MCP::IndexReader]
+      # @param identifier [String]
+      # @param type [String] singular type name
+      # @return [Hash, nil] string-keyed unit, or nil when this type has no
+      #   such identifier
+      def self.call(payload_dir, reader, identifier, type)
+        dir = Woods::MCP::IndexReader::TYPE_TO_DIR[type]
+        return nil unless dir
+        return nil unless reader.list_units(type: type).any? { |entry| entry['identifier'] == identifier }
+
+        path = payload_dir.join(dir, filename_for(identifier))
+        return nil unless path.file?
+
+        JSON.parse(path.binread.force_encoding(Encoding::UTF_8))
+      end
+
+      # The on-disk filename for a unit, matching
+      # `Woods::MCP::IndexReader#build_identifier_map`'s naming exactly.
+      #
+      # @param identifier [String]
+      # @return [String]
+      def self.filename_for(identifier)
+        base = identifier.gsub('::', '__').gsub(/[^a-zA-Z0-9_-]/, '_')
+        digest = Digest::SHA256.hexdigest(identifier)[0, 8]
+        "#{base}_#{digest}.json"
+      end
+
+      private_class_method :filename_for
+    end
+  end
+end

data/lib/woods/published_index.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require 'pathname'
+require_relative 'generation'
+require_relative 'payload_store'
+require_relative 'mcp/index_reader'
+require_relative 'published_index/edge_shaper'
+require_relative 'published_index/generation_catalog'
+require_relative 'published_index/typed_unit_reader'
+
+module Woods
+  class Error < StandardError; end unless defined?(Woods::Error)
+
+  # A small, stable Ruby API over a published Woods index for tools that are
+  # not MCP clients: RuboCop cops, CI gate scripts, `woods:check:*` tasks (#280).
+  #
+  # Three things it does that the MCP reader does not expose directly:
+  #
+  # * pin one published generation (the current one, or a retained older
+  #   `payloads/gen-N`) for the reader's whole lifetime, so a check reads one
+  #   consistent snapshot and can compare two generations against each other;
+  # * hold that generation's {Woods::PayloadStore} retention lock for as long
+  #   as the reader is open, so a concurrent publish's pruning cannot remove
+  #   the payload out from under it;
+  # * iterate edges with their attributes as plain hashes, and hand out a
+  #   checksum keyed to the pinned payload for RuboCop's
+  #   `external_dependency_checksum`.
+  #
+  # Everything is read-only and needs no Rails. Unit hashes are string-keyed,
+  # exactly as written on disk. Unlike {Woods::MCP::IndexReader}, a
+  # {PublishedIndex} never auto-refreshes: every fact it returns comes from
+  # the one generation it opened with, for its entire lifetime.
+  #
+  # Holds an open file handle (a shared lock on the pinned generation's
+  # `manifest.json`) for as long as the reader is open. Use the block form or
+  # call {#close} explicitly; do not let an instance leak past the scope that
+  # needs it.
+  #
+  # **Not thread-safe.** A single instance is meant for one script or cop
+  # process reading one generation; it keeps no mutex around its lock file or
+  # its underlying {Woods::MCP::IndexReader}. Give each thread its own
+  # {PublishedIndex} rather than sharing one.
+  #
+  # @example A cop keyed on the index
+  #   Woods::PublishedIndex.open(Rails.root.join('tmp/woods')) do |index|
+  #     index.table_database_map            # => { "orders" => "primary", "events" => "analytics" }
+  #     index.external_dependency_checksum  # => "9f2c..." (changes on every publish)
+  #   end
+  #
+  # @example Comparing two generations
+  #   before = Woods::PublishedIndex.new(dir, generation: 41)
+  #   after  = Woods::PublishedIndex.new(dir, generation: 42)
+  #   begin
+  #     # ...
+  #   ensure
+  #     before.close
+  #     after.close
+  #   end
+  #
+  class PublishedIndex
+    # Raised when `generation.json` exists but cannot be parsed. Distinct from
+    # a *missing* pointer file, which means a flat (pre-2.0) index and is not
+    # an error.
+    class CorruptPointerError < Woods::Error; end
+
+    # @return [Pathname] the index root passed to {#initialize}
+    attr_reader :index_dir
+
+    # Published generation numbers, ascending.
+    #
+    # A generation counts as published only when its number is at or below
+    # the pointer `generation.json` currently names AND its payload directory
+    # holds a `manifest.json`. A directory numbered above the pointer, or one
+    # without a manifest (an interrupted or failed publish), is never listed.
+    #
+    # @param index_dir [String, Pathname]
+    # @return [Array<Integer>]
+    # @raise [CorruptPointerError] when `generation.json` exists but will not parse
+    def self.available_generations(index_dir)
+      GenerationCatalog.available(Pathname.new(index_dir.to_s))
+    end
+
+    # Open a reader, yield it, and guarantee the generation lock is released.
+    #
+    # Without a block this behaves exactly like {.new}: the caller owns the
+    # lock and must call {#close}.
+    #
+    # @param (see #initialize)
+    # @yieldparam index [PublishedIndex]
+    # @return [PublishedIndex] when no block is given
+    # @return [Object] the block's return value, when a block is given
+    def self.open(index_dir, generation: nil)
+      index = new(index_dir, generation: generation)
+      return index unless block_given?
+
+      begin
+        yield index
+      ensure
+        index.close
+      end
+    end
+
+    # @param index_dir [String, Pathname] the index root (holds generation.json)
+    # @param generation [Integer, nil] pin a published generation; defaults to
+    #   the currently published one
+    # @raise [ArgumentError] when the index, or the requested generation, is
+    #   not published
+    # @raise [CorruptPointerError] when `generation.json` exists but will not parse
+    def initialize(index_dir, generation: nil)
+      @index_dir = Pathname.new(index_dir.to_s)
+      @lock_file = nil
+      pointer = GenerationCatalog.pointer(@index_dir)
+
+      if pointer.number.zero? && generation.nil?
+        initialize_flat_index
+      else
+        initialize_generation(generation || pointer.number)
+      end
+
+      open_reader!
+    end
+
+    # @return [Integer] the generation being read; 0 for a flat index
+    # @return [Pathname] the directory the units are read from
+    attr_reader :generation_number, :payload_dir
+
+    # Release the retention lock held on the pinned generation, if any.
+    #
+    # Safe to call more than once. A flat index (generation 0) holds no lock,
+    # so this is a no-op for it.
+    #
+    # @return [void]
+    def close
+      @lock_file&.flock(File::LOCK_UN)
+      @lock_file&.close
+      @lock_file = nil
+    end
+
+    # @return [Hash] parsed manifest.json
+    def manifest
+      @reader.manifest
+    end
+
+    # Look up one unit by identifier.
+    #
+    # `Woods::MCP::IndexReader#find_unit` (used when +type+ is nil) keys its
+    # identifier map on identifier alone: if two type directories both list
+    # the same identifier, whichever type sorts last in
+    # `Woods::MCP::IndexReader::TYPE_DIRS` wins, silently. Pass +type+ to read
+    # that type's unit file directly and skip the collision.
+    #
+    # @param identifier [String]
+    # @param type [String, Symbol, nil] singular type name; disambiguates an
+    #   identifier shared by more than one type
+    # @return [Hash, nil] string-keyed unit, or nil
+    def unit(identifier, type: nil)
+      return @reader.find_unit(identifier) if type.nil?
+
+      TypedUnitReader.call(@payload_dir, @reader, identifier, type.to_s)
+    end
+
+    # Index entries, each with a `'type'` key added.
+    #
+    # @param type [String, Symbol, nil] singular type name to restrict to
+    # @return [Array<Hash>]
+    def units(type: nil)
+      dirs = if type
+               dir = Woods::MCP::IndexReader::TYPE_TO_DIR[type.to_s]
+               dir ? [dir] : []
+             else
+               Woods::MCP::IndexReader::TYPE_DIRS
+             end
+      dirs.flat_map do |dir|
+        @reader.list_units(type: Woods::MCP::IndexReader::DIR_TO_TYPE[dir])
+               .map { |entry| entry.merge('type' => Woods::MCP::IndexReader::DIR_TO_TYPE[dir]) }
+      end
+    end
+
+    # Every forward edge in the graph, primary nodes and variants alike.
+    #
+    # An identifier shared by more than one type contributes one edge per
+    # owning type; two edges are never folded into one just because they look
+    # alike once reduced to `{from, to, via, through, through_db, disable_joins}`.
+    #
+    # @param via [String, Symbol, nil] restrict to one relationship label
+    # @return [Array<Hash>] `{ from:, to:, via:, through:, through_db:, disable_joins: }`
+    def edges(via: nil)
+      wanted = via&.to_s
+      EdgeShaper.call(@reader.raw_graph_data).select { |edge| wanted.nil? || edge[:via] == wanted }
+    end
+
+    # @yieldparam edge [Hash] see {#edges}
+    # @return [void]
+    def each_edge(via: nil, &block)
+      edges(via: via).each(&block)
+    end
+
+    # @param identifier [String]
+    # @param via [String, Symbol, nil]
+    # @return [Array<String>] identifiers that depend on `identifier`
+    def dependents_of(identifier, via: nil)
+      return Array((@reader.raw_graph_data['reverse'] || {})[identifier]).dup if via.nil?
+
+      edges(via: via).select { |edge| edge[:to] == identifier }.map { |edge| edge[:from] }.uniq
+    end
+
+    # table name => database name, from model units that carry
+    # `metadata.database` (Rails 6.1+ extractions).
+    #
+    # Reads every model unit once; cache it in a cop.
+    #
+    # @return [Hash{String => String}]
+    def table_database_map
+      units(type: 'model').each_with_object({}) do |entry, map|
+        data = unit(entry['identifier'], type: 'model')
+        next unless data
+
+        table = data.dig('metadata', 'table_name')
+        database = data.dig('metadata', 'database')
+        map[table] = database if table && database
+      end
+    end
+
+    # A digest of the pinned payload's `manifest.json`. RuboCop re-runs a cop
+    # on every file when this value changes, so keying on the manifest that
+    # was rewritten by the publish this reader is pinned to catches every
+    # publish, whether the reader ended up on a flat index or a numbered
+    # generation.
+    #
+    # @return [String] SHA-256 hex
+    def external_dependency_checksum
+      Digest::SHA256.file(@payload_dir.join('manifest.json').to_s).hexdigest
+    end
+
+    private
+
+    # @return [void]
+    def initialize_flat_index
+      raise ArgumentError, "No manifest.json found in: #{@index_dir}" unless @index_dir.join('manifest.json').file?
+
+      @generation_number = 0
+      @payload_dir = @index_dir
+    end
+
+    # @param number [Integer]
+    # @return [void]
+    # @raise [ArgumentError] when +number+ is not a published generation
+    def initialize_generation(number)
+      dir = Woods::PayloadStore.new(@index_dir).path_for(number)
+      unless self.class.available_generations(@index_dir).include?(number)
+        raise ArgumentError, "Generation #{number} is not published under #{@index_dir} (expected #{dir.basename})"
+      end
+
+      @generation_number = number
+      @payload_dir = dir
+      acquire_retention_lock!
+    end
+
+    # Hold the same shared advisory lock on the generation's `manifest.json`
+    # that {Woods::MCP::IndexReader} takes to survive concurrent retention
+    # (see `PayloadStore#prune`'s doc comment on the lock protocol), but for
+    # the whole lifetime of this reader rather than one pinned read. Kept
+    # open until {#close}.
+    #
+    # @return [void]
+    def acquire_retention_lock!
+      @lock_file = File.open(@payload_dir.join('manifest.json').to_s, File::RDONLY)
+      @lock_file.flock(File::LOCK_SH)
+    end
+
+    # Build the underlying reader, releasing any retention lock already
+    # acquired ({#initialize_generation}) before letting the failure
+    # propagate. Without this a `PublishedIndex` that fails to finish
+    # constructing would leak an open advisory lock for the life of the
+    # process.
+    #
+    # @return [void]
+    def open_reader!
+      @reader = Woods::MCP::IndexReader.new(@payload_dir.to_s, auto_refresh: false)
+    rescue Exception # rubocop:disable Lint/RescueException -- release the lock for every failure mode, then re-raise unchanged
+      close
+      raise
+    end
+  end
+end

data/lib/woods/railtie.rb

@@ -1,16 +1,46 @@
 # frozen_string_literal: true
 
+require 'woods/railtie_support'
+
 module Woods
   # Railtie integrates Woods into Rails applications.
   # Loads rake tasks automatically when the gem is bundled.
-  # Conditionally inserts session tracer middleware when enabled.
+  #
+  # == Console MCP (#183)
+  #
+  # The console stack (OriginGuard -> BearerAuth -> Console::RackMiddleware)
+  # is mounted unconditionally, but every decision is deferred to request
+  # time: railtie initializers run before `:load_config_initializers`, so
+  # flags and tokens set in `config/initializers/woods.rb` (the
+  # generator-created location) do not exist yet when middleware arguments
+  # are captured. Both guards are scoped to `console_mcp_path` — requests
+  # outside it pass through untouched — and while `console_mcp_enabled` is
+  # false the whole stack passes through, so an unconfigured host app is
+  # completely unaffected. Boot-time validation of the settled configuration
+  # happens in `after_initialize` via {Woods::RailtieSupport}.
+  #
+  # == Session tracer
+  #
+  # SessionTracer::Middleware requires a store at construction, so it cannot
+  # be mounted lazily. It stays conditionally mounted, and the
+  # `after_initialize` hook warns when the flag was set too late to mount
+  # (i.e. in config/initializers instead of config/application.rb).
   class Railtie < Rails::Railtie
     rake_tasks do
       load File.expand_path('../tasks/woods.rake', __dir__)
+      # Loaded here too, or `woods:evaluate` exists on no host — the file
+      # shipped in the gem for its whole life without ever being loaded, so
+      # the retrieval-quality harness had no entry point at all (#212).
+      load File.expand_path('../tasks/woods_evaluation.rake', __dir__)
+      # Read-only checks over retained generations (#280); no Rails boot.
+      load File.expand_path('../tasks/woods_checks.rake', __dir__)
     end
 
     initializer 'woods.session_tracer' do |app|
-      config = Woods.configuration
+      # RailtieSupport.config initializes defaults when the host app never
+      # called Woods.configure — this initializer runs in every app.
+      config = Woods::RailtieSupport.config
+      Woods::RailtieSupport.session_tracer_state = nil
       next unless config.session_tracer_enabled
 
       if defined?(Rails) && Rails.env.production? && !config.session_tracer_allow_production
@@ -21,6 +51,7 @@ module Woods
         else
           warn msg
         end
+        Woods::RailtieSupport.session_tracer_state = :skipped_production
         next
       end
 
@@ -32,47 +63,55 @@ module Woods
         session_id_proc: config.session_id_proc,
         exclude_paths: config.session_exclude_paths
       )
+      Woods::RailtieSupport.session_tracer_state = :mounted
     end
 
     initializer 'woods.console_mcp' do |app|
-      config = Woods.configuration
-      next unless config.console_mcp_enabled
-
       require 'woods/console/rack_middleware'
       require 'woods/mcp/bearer_auth'
       require 'woods/mcp/origin_guard'
 
-      token = config.console_mcp_token
-      production = defined?(Rails) && Rails.env.production?
-      token_missing = token.nil? || token.to_s.empty?
-
-      if token_missing
-        msg = '[Woods Console] console_mcp_token is not set — Console MCP is a high-privilege ' \
-              'endpoint that runs SQL and model introspection against the live database. ' \
-              'Set Woods.configuration.console_mcp_token (or WOODS_CONSOLE_MCP_TOKEN env var) ' \
-              'to a 32+ character random string.'
-        raise Woods::ConfigurationError, msg if production
-
-        # Non-prod without a token: refuse to wire the middleware at all.
-        # Earlier iterations fell through and installed the RackMiddleware
-        # with ZERO auth/origin guard in front of it — a binding on 0.0.0.0
-        # (common in devcontainers/docker-compose) would expose an
-        # unauthenticated SQL-bearing endpoint to every local process.
-        # Fail-closed: warn and skip.
-        warn "#{msg} Refusing to mount the Console MCP middleware until a token is configured."
-        next
-      end
+      # Mounted unconditionally; enablement, token, and allow-list are all
+      # resolved at request time (see RailtieSupport) so values set in
+      # config/initializers take effect. The path is the one thing captured
+      # now — changing console_mcp_path must happen in config/application.rb
+      # (after_initialize warns otherwise).
+      path = Woods::RailtieSupport.config.console_mcp_path
+      Woods::RailtieSupport.console_mounted_path = path
+      enabled = Woods::RailtieSupport.console_enabled_proc
 
       # Origin guard first — rejects cross-origin POSTs before any auth cost.
-      # BearerAuth next — requires `Authorization: Bearer <token>` on every request.
-      app.middleware.use(Woods::MCP::OriginGuard, allowed_origins: Array(config.console_mcp_allowed_origins))
-      app.middleware.use(Woods::MCP::BearerAuth, token: token)
+      # BearerAuth next — requires `Authorization: Bearer <token>` at the
+      # console path, failing closed (401) while no usable token is
+      # configured. Both are scoped to the console path and inert while
+      # console_mcp_enabled is false.
+      app.middleware.use(
+        Woods::MCP::OriginGuard,
+        allowed_origins: Woods::RailtieSupport.console_allowed_origins_proc,
+        path: path,
+        enabled: enabled
+      )
+      app.middleware.use(
+        Woods::MCP::BearerAuth,
+        token: Woods::RailtieSupport.console_token_proc,
+        path: path,
+        enabled: enabled
+      )
 
       app.middleware.use(
         Woods::Console::RackMiddleware,
-        path: config.console_mcp_path,
-        embedded_read_tools: config.console_embedded_read_tools
+        path: path,
+        embedded_read_tools: Woods::RailtieSupport.console_read_tools_proc
+      )
+    end
+
+    # Runs after :load_config_initializers, when the configuration is final —
+    # this is where boot-time validation belongs (#183).
+    config.after_initialize do
+      Woods::RailtieSupport.verify_console_configuration!(
+        production: defined?(Rails) && Rails.env.production?
       )
+      Woods::RailtieSupport.verify_session_tracer_configuration!
     end
   end
 end

data/lib/woods/railtie_support.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Woods
+  # Rails-independent logic behind {Woods::Railtie}.
+  #
+  # Rails railtie initializers run before `:load_config_initializers`, so
+  # anything the railtie reads from Woods.configuration at initializer time
+  # sees the defaults — not the values set in `config/initializers/woods.rb`
+  # (the generator-created location every doc names). The railtie therefore
+  # mounts the console stack unconditionally and defers every decision to
+  # request time via the procs below, and validates the settled
+  # configuration from an `after_initialize` hook (#183).
+  #
+  # This module carries no Rails dependency so the gem's unit specs can
+  # exercise the request-time procs and boot-time verification without
+  # loading Rails::Railtie.
+  module RailtieSupport
+    # Boot-time message for a console enabled without a token. Raised in
+    # production; warned everywhere else. Only the HTTP transport enforces
+    # the token ({Woods::MCP::BearerAuth} fails closed with 401 at the console
+    # path); the stdio server never sees a bearer header, so for it a missing
+    # token is a production-boot failure, not a request failure.
+    MISSING_TOKEN_MESSAGE =
+      '[Woods Console] console_mcp_token is not set — Console MCP is a high-privilege ' \
+      'endpoint that runs SQL and model introspection against the live database. ' \
+      'Set Woods.configuration.console_mcp_token (or WOODS_CONSOLE_MCP_TOKEN env var) ' \
+      'to a 32+ character random string.'
+
+    # Transport qualifier appended to {MISSING_TOKEN_MESSAGE} outside
+    # production (G-3). The token authenticates the *HTTP* Console transport
+    # only: {Woods::Console::RackMiddleware} and {Woods::MCP::BearerAuth} are
+    # what return the 401. The stdio transport (`rake woods:console`,
+    # `exe/woods-console`) speaks over a pipe and neither sends nor consumes a
+    # bearer token, so an unqualified "requests will be refused (401)" sent
+    # stdio-only operators configuring a token their setup never uses.
+    MISSING_TOKEN_TRANSPORT_NOTE =
+      'HTTP Console MCP requests will be refused (401) until one is set. The stdio ' \
+      'transport (rake woods:console) does not transmit or use a bearer token, so a ' \
+      'stdio-only setup still works — set the token before exposing the HTTP endpoint. ' \
+      'Production boot will raise while Console MCP is enabled without a token.'
+
+    class << self
+      # @return [String, nil] path the console stack was mounted at (captured
+      #   at railtie-initializer time). Used by
+      #   {.verify_console_configuration!} to detect a `console_mcp_path`
+      #   set too late to take effect.
+      attr_accessor :console_mounted_path
+
+      # @return [Symbol, nil] `:mounted` when the session tracer middleware
+      #   was inserted, `:skipped_production` when the production guard
+      #   refused it, nil when the flag was off at railtie-initializer time.
+      attr_accessor :session_tracer_state
+
+      # Request-time predicate handed to the console guards and consulted by
+      # {Woods::Console::RackMiddleware}. Reads the live configuration on
+      # every call, so a flag set after the middleware was inserted (e.g. in
+      # config/initializers) still takes effect.
+      #
+      # @return [Proc] arity-0 proc returning the current enabled flag
+      def console_enabled_proc
+        -> { config.console_mcp_enabled }
+      end
+
+      # Deferred bearer token for {Woods::MCP::BearerAuth}, resolved on each
+      # guarded request.
+      #
+      # @return [Proc] arity-0 proc returning the configured token (or nil)
+      def console_token_proc
+        -> { config.console_mcp_token }
+      end
+
+      # Deferred origin allow-list for {Woods::MCP::OriginGuard}, resolved on
+      # the first guarded request.
+      #
+      # @return [Proc] arity-0 proc returning the configured allow-list
+      def console_allowed_origins_proc
+        -> { Array(config.console_mcp_allowed_origins) }
+      end
+
+      # Deferred read-tools flag for {Woods::Console::RackMiddleware},
+      # resolved when the embedded server is first built.
+      #
+      # @return [Proc] arity-0 proc returning the configured flag
+      def console_read_tools_proc
+        -> { config.console_embedded_read_tools }
+      end
+
+      # The live configuration, initialized to defaults when the host never
+      # called Woods.configure — the console stack is mounted in every app
+      # now, so nothing here may assume a configure block ran.
+      #
+      # @return [Woods::Configuration]
+      def config
+        Woods.configuration || Woods.configure
+      end
+
+      # Boot-time console validation, run from `after_initialize` once the
+      # final configuration is known. With the console enabled and no usable
+      # token, every HTTP request at the console path will be refused with
+      # 401 — production refuses to boot instead (matching the pre-#183
+      # fail-closed posture), other environments warn loudly. The stdio
+      # server carries no bearer check, so the warning says which transport
+      # it is about rather than claiming every request fails. A token shorter than
+      # {Woods::MCP::BearerAuth::MIN_TOKEN_LENGTH} is a misconfiguration and
+      # raises in every environment (as the eager BearerAuth constructor
+      # used to). Also warns when `console_mcp_path` changed after the stack
+      # was mounted.
+      #
+      # @param production [Boolean] whether the app runs in production
+      # @return [void]
+      # @raise [Woods::ConfigurationError] on a missing token in production,
+      #   or a too-short token anywhere
+      def verify_console_configuration!(production:)
+        warn_late_console_path(config)
+        return unless config.console_mcp_enabled
+
+        require 'woods/mcp/bearer_auth'
+        token = config.console_mcp_token.to_s
+        if token.empty?
+          raise Woods::ConfigurationError, MISSING_TOKEN_MESSAGE if production
+
+          warn "#{MISSING_TOKEN_MESSAGE} #{MISSING_TOKEN_TRANSPORT_NOTE}"
+        elsif token.length < Woods::MCP::BearerAuth::MIN_TOKEN_LENGTH
+          raise Woods::ConfigurationError,
+                '[Woods Console] console_mcp_token is shorter than ' \
+                "#{Woods::MCP::BearerAuth::MIN_TOKEN_LENGTH} characters; generate one with " \
+                '`SecureRandom.hex(32)` (or `rake woods:generate_token`).'
+        end
+      end
+
+      # Boot-time session tracer validation, run from `after_initialize`.
+      # Unlike the console stack, SessionTracer::Middleware requires a store
+      # at construction, so it cannot be mounted lazily — when the flag was
+      # set too late for the railtie initializer to see it, warn with the
+      # remediation instead of silently doing nothing (#183).
+      #
+      # @return [void]
+      def verify_session_tracer_configuration!
+        return unless config.session_tracer_enabled
+        return unless session_tracer_state.nil?
+
+        warn '[Woods] session_tracer_enabled is set but the middleware was not mounted: ' \
+             'the flag was enabled after Rails railtie initializers ran (config/initializers/ ' \
+             'runs later). Set session_tracer_enabled and session_store in ' \
+             'config/application.rb, then restart.'
+      end
+
+      private
+
+      # 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.
+      #
+      # @param config [Woods::Configuration]
+      # @return [void]
+      def warn_late_console_path(config)
+        mounted = console_mounted_path
+        return if mounted.nil? || mounted == config.console_mcp_path
+
+        warn "[Woods Console] console_mcp_path is #{config.console_mcp_path.inspect} but the " \
+             "console stack was mounted at #{mounted.inspect} — the path was changed after " \
+             'Rails railtie initializers ran. Set console_mcp_path in config/application.rb, ' \
+             'then restart.'
+      end
+    end
+  end
+end

data/lib/woods/release.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Woods
+  # Maintainer-only release machinery, deliberately not packaged with the gem.
+  # These files back `release:prepare` and `release:reopen`, which only ever run
+  # from a source checkout of this repository.
+  module Release
+    # Every refusal the release flow raises. `lib/tasks/release.rake` rescues
+    # this one class and turns it into a clean abort.
+    class Error < StandardError; end
+  end
+end