woods 2.0.0.beta4 → 2.0.1

data/docs/WHY_WOODS.md

@@ -56,9 +56,11 @@ It describes what the service does, but misses that `order.save!` triggers `afte
 :send_confirmation_email` on `Order`, which itself enqueues `InventoryJob` via
 `after_save :reserve_stock` on `LineItem`.
 
-With Woods, the dependency graph links `CheckoutService` → `Order` → `LineItem` →
-`InventoryJob`. A single retrieval call assembles the full execution picture: the service,
-the models it touches, the callbacks those models fire, and the jobs those callbacks enqueue.
+With Woods, published graph relationships can connect related services, models,
+callbacks, and jobs for retrieval. Arbitrary method-body constant references are
+not exhaustively indexed, so the whole `CheckoutService` → `Order` → `LineItem` →
+`InventoryJob` chain may not be recorded. Inspect the source and any flow evidence,
+including reported ambiguity and traversal limits, before concluding what runs.
 
 ---
 
@@ -175,11 +177,13 @@ Three tools answered "what is in this Rails app" for coding agents in 2026. Wood
 | Rubydex (Shopify) | 0.4.1, announced 2026-05-12 | Rust static index of declarations, references, ancestors; experimental `rdx mcp` | Symbol references across a large tree, fast re-index, reported 15 to 80 percent token reduction | Resolved callbacks, inlined concerns, routes as Rails builds them, database partition, churn |
 | rails-mcp-server | 2.0.0 | Boots the app; `analyze_models`, `get_routes`, `get_schema` | Live model, route, and schema listings over MCP | Callback side effects, request flows, git churn, graph reports, persistent index with generations |
 | ruby-lsp-rails | 0.5.0.beta1 | Runtime server over `rails runner` for the editor | Model columns, association targets, route info at the cursor | A persistent index other tools can read, graph analysis, multi-database facts |
-| Woods | 2.0 | Boots the app once, publishes an atomic JSON generation, serves it without Rails | Resolved runtime behavior on top of structure: inlined concerns, callback side effects, flows, churn, PageRank; database partition and Packwerk boundaries are in progress on this branch | Symbol-level references inside method bodies (Rubydex is the better fit and is complementary) |
+| Woods | 2.0 | Boots the app once, publishes an atomic JSON generation, serves it without Rails | Resolved runtime behavior on top of structure: inlined concerns, callback side effects, flows, churn, PageRank; recorded database partitions and Packwerk boundaries | Symbol-level references inside method bodies (Rubydex is the better fit and is complementary) |
 
 Woods and Rubydex are complementary. Rubydex answers "where is this symbol referenced". Woods answers "what happens when this runs, and what does it touch". An agent can use both: Rubydex for references, Woods for behavior, boundaries, and blast radius.
 
-The database-partition layer, in progress on this branch, is the one place Woods will be alone. Rubydex is static, and the other two resolve associations without saying which database each side lives on. See [Extractor reference](EXTRACTOR_REFERENCE.md#modelextractor) for the fields.
+Woods records database-partition metadata on models and Packwerk package ownership
+and boundaries. See [Extractor reference](EXTRACTOR_REFERENCE.md#modelextractor)
+for the fields and their coverage limits.
 
 ---
 

data/exe/woods-console

@@ -21,14 +21,14 @@
 # Check if the rake task already captured stdout for us.
 protocol_out = $woods_protocol_out # rubocop:disable Style/GlobalVars
 
-unless protocol_out
-  # Running via rails runner — capture stdout ourselves.
-  protocol_out = $stdout.dup
-  $stdout.reopen($stderr)
-end
+# Running via rails runner — capture stdout ourselves.
+protocol_out ||= $stdout.dup
+# Keep application logs and writes on stderr for the entire server lifetime.
+$stdout.reopen($stderr)
 
 require 'woods'
 require 'woods/console/server'
+require 'woods/console/stdio_transport'
 
 unless Woods.configuration.console_mcp_enabled
   warn 'Woods Console MCP is disabled. Set ' \
@@ -132,9 +132,11 @@ server = Woods::Console::Server.build_embedded(
   model_reflections: model_reflections
 )
 
-# Restore the protocol output for MCP transport.
-$stdout.reopen(protocol_out)
-protocol_out.close unless protocol_out.closed?
-
-transport = MCP::Server::Transports::StdioTransport.new(server)
-transport.open
+# Only the transport writes to the saved pipe. Restoring process stdout here
+# would also redirect Rails loggers and runtime puts back into the protocol.
+transport = Woods::Console::StdioTransport.new(server, output: protocol_out)
+begin
+  transport.open
+ensure
+  protocol_out.close unless protocol_out.closed?
+end

data/exe/woods-mcp-http

@@ -46,6 +46,20 @@ require_relative '../lib/woods/embedding/text_preparer'
 require_relative '../lib/woods/embedding/indexer'
 
 begin
+  raw_origins = ENV.fetch('WOODS_MCP_HTTP_ALLOWED_ORIGINS', '')
+  unless raw_origins.valid_encoding?
+    invalid_entry = raw_origins.b.split(',').find do |entry|
+      !entry.dup.force_encoding(raw_origins.encoding).valid_encoding?
+    end
+    label = invalid_entry.to_s.b.byteslice(0, 160).inspect
+    raise Woods::ConfigurationError, "Invalid WOODS_MCP_HTTP_ALLOWED_ORIGINS entry #{label}: invalid encoding"
+  end
+  allowed_origins = raw_origins.split(',').map(&:strip).reject(&:empty?)
+  begin
+    origin_policy = Woods::MCP::OriginPolicy.new(allowed_origins: allowed_origins)
+  rescue ArgumentError => e
+    raise Woods::ConfigurationError, "#{e.message} (WOODS_MCP_HTTP_ALLOWED_ORIGINS)"
+  end
   index_dir = Woods::MCP::Bootstrapper.resolve_index_dir(ARGV)
   retriever, bootstrap_state = Woods::MCP::Bootstrapper.build_retriever(index_dir: index_dir)
   snapshot_store = Woods::MCP::Bootstrapper.build_snapshot_store(index_dir)
@@ -96,17 +110,10 @@ server = Woods::MCP::Server.build(
 # hatch is transitional — the spec has removed all three. See
 # docs/MCP_HTTP_TRANSPORT.md#statelessness.
 stateless = !%w[0 false no].include?(ENV.fetch('WOODS_MCP_HTTP_STATELESS', '1').strip.downcase)
-allowed_origins = ENV.fetch('WOODS_MCP_HTTP_ALLOWED_ORIGINS', '').split(',').map(&:strip).reject(&:empty?)
-allowed_hosts = allowed_origins.filter_map do |origin|
-  URI.parse(origin).host
-rescue URI::InvalidURIError
-  nil
-end
 transport = MCP::Server::Transports::StreamableHTTPTransport.new(
   server,
   stateless: stateless,
-  allowed_origins: allowed_origins,
-  allowed_hosts: allowed_hosts
+  **origin_policy.transport_options
 )
 server.transport = transport
 
@@ -116,7 +123,7 @@ inner = proc do |env|
   transport.handle_request(Rack::Request.new(env))
 end
 app = token ? Woods::MCP::BearerAuth.new(inner, token: token) : inner
-app = Woods::MCP::OriginGuard.new(app, allowed_origins: allowed_origins)
+app = Woods::MCP::OriginGuard.new(app, policy: origin_policy)
 
 origin_summary = allowed_origins.empty? ? 'loopback' : allowed_origins.join(',')
 auth_mode = token ? 'bearer' : 'none'

data/exe/woods-watch

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'woods/watch/cli'
+exit Woods::Watch::CLI.new.run(ARGV)

data/lib/generators/woods/watch_generator.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'woods/watch/installation'
+
+module Woods
+  module Generators
+    # Reversible opt-in startup integration; never rewrites an application's bin/dev.
+    class WatchGenerator < Rails::Generators::Base
+      desc 'Install, update, or remove owned Woods watcher startup configuration'
+
+      class_option :mode, type: :string, desc: 'Explicit startup mode: procfile, puma, or external'
+      class_option :operation, type: :string, default: 'setup', desc: 'setup, update, remove, or recover'
+      class_option :procfile, type: :string, default: 'Procfile.dev', desc: 'Existing root-level Foreman Procfile'
+      class_option :manager_command, type: :string,
+                                     desc: 'Normal Foreman startup argv, e.g. foreman start -f Procfile.dev'
+      class_option :child_command, type: :string, default: 'bin/rails woods:watch',
+                                   desc: 'Application task command, parsed as argv (no shell evaluation)'
+
+      # Rails generators otherwise print Thor errors and return a successful status.
+      # @return [Boolean] whether a refused installation fails the CLI command
+      def self.exit_on_failure?
+        true
+      end
+
+      # @return [void]
+      def configure_watcher
+        operation = behavior == :revoke ? 'remove' : options[:operation]
+        installation = build_installation(operation)
+        if operation == 'recover'
+          say installation.recover(pretend: options[:pretend])
+          return
+        end
+        plan = installation.plan
+        say JSON.pretty_generate(plan.summary)
+        return if options[:pretend]
+
+        say installation.apply(plan)
+        say installation.handoff unless operation == 'remove'
+      rescue Woods::Watch::Installation::Conflict => e
+        raise Thor::Error, e.message
+      end
+
+      private
+
+      def build_installation(operation)
+        Woods::Watch::Installation.new(root: destination_root, mode: options[:mode], operation: operation,
+                                       procfile: options[:procfile], manager_command: options[:manager_command],
+                                       child_command: options[:child_command])
+      end
+    end
+  end
+end

data/lib/puma/plugin/woods.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative '../../woods/watch/puma_adapter'
+
+Puma::Plugin.create do
+  def start(launcher)
+    @woods_adapter ||= Woods::Watch::PumaAdapter.new(launcher)
+    @woods_adapter.install
+  end
+end

data/lib/tasks/woods.rake

@@ -123,6 +123,9 @@ namespace :woods do
 
   desc 'Watch the app and keep the index current (resident daemon)'
   task :watch do
+    require 'woods/watch/managed_child'
+    managed_child = Woods::Watch::ManagedChild.from_env
+    managed_child&.call(:task_loaded, woods_version: Woods::VERSION)
     # Observe inputs before Rails initializes. A snapshot taken in Daemon.new
     # would silently bless edits made while initializers were running.
     require 'woods/watch/boot_snapshot'
@@ -130,6 +133,11 @@ namespace :woods do
     fresh_environment = !environment.already_invoked && !Rails.application.initialized?
     boot_snapshot = Woods::Watch::BootSnapshot.new(root: Rails.root) if fresh_environment
     environment.invoke
+    if managed_child && !Rails.env.development?
+      managed_child.call(:terminal, reason: 'unsupported_environment')
+      warn 'Managed Woods watching requires the finalized Rails development environment.'
+      next
+    end
     # Both, and the extractor is not optional. The daemon's default
     # extractor_factory names Woods::Extractor lazily, so omitting this require
     # loaded and started cleanly and then NameError'd on the first real cycle —
@@ -140,6 +148,7 @@ namespace :woods do
     require 'woods/watch/daemon'
 
     output_dir = ENV.fetch('WOODS_OUTPUT', Woods.configuration.output_dir)
+    managed_child&.call(:identity, root: File.expand_path(Rails.root.to_s), index: File.expand_path(output_dir.to_s))
 
     poll_interval = begin
       Float(ENV.fetch('WOODS_WATCH_POLL_INTERVAL', Woods::Watch::Watcher::DEFAULT_POLL_INTERVAL))
@@ -162,6 +171,8 @@ namespace :woods do
       idle_timeout: ENV.fetch('WOODS_WATCH_IDLE_TIMEOUT', nil) && Float(ENV.fetch('WOODS_WATCH_IDLE_TIMEOUT')),
       catch_up: ENV['WOODS_WATCH_CATCH_UP'] != '0',
       boot_snapshot: boot_snapshot,
+      lifecycle: managed_child,
+      conservative_claims: !managed_child.nil?,
       logger: Rails.logger
     )
 
@@ -182,6 +193,7 @@ namespace :woods do
     puts
 
     reason = daemon.run
+    managed_child&.call(:terminal, reason: reason.to_s)
 
     if reason == :restart_required
       # Boot-captured state changed; Rails cannot reload it. Exit non-zero so
@@ -192,6 +204,8 @@ namespace :woods do
     end
 
     puts 'Watcher stopped.'
+  ensure
+    managed_child&.close
   end
 
   desc 'Keep watch over the woods — resident index daemon (alias for watch)'

data/lib/woods/cache/cache_middleware.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'digest'
+require 'securerandom'
 require_relative 'cache_store'
 # CachedEmbeddingProvider includes Embedding::Provider::Interface at load
 # time, so the interface must be defined before this file's class bodies run
@@ -408,6 +409,8 @@ module Woods
         @retriever = retriever
         @cache_store = cache_store
         @context_ttl = context_ttl
+        @context_namespace = SecureRandom.hex(16)
+        @context_mutex = Mutex.new
       end
 
       # Expose the wrapped stores so the MCP +reload+ tool and
@@ -421,20 +424,23 @@ module Woods
       def mode = @retriever.respond_to?(:mode) ? @retriever.mode : :semantic
       def default_budget = @retriever.respond_to?(:default_budget) ? @retriever.default_budget : 8000
 
-      # Invalidate every cached context result. Called from the MCP +reload+
-      # tool after the retriever's stores have been re-hydrated from a fresh
-      # embed — otherwise cached results from the old embedding run would
-      # linger until their TTL expires and contradict the new stores.
+      # Read the live corpus rather than caching diagnostics across reloads.
+      # @return [Hash, nil] local semantic corpus statistics, when supported
+      def corpus_status(include_types: true)
+        @retriever.corpus_status(include_types: include_types) if @retriever.respond_to?(:corpus_status)
+      end
+
+      # Retire this retriever's cached contexts after its corpus reloads.
       #
-      # Embedding caches (query → vector) are NOT cleared: the query-vector
-      # mapping is deterministic for a given provider+model and survives any
-      # index reload. Only context results (query → ranked units) go stale.
+      # Each retriever has its own unpredictable namespace, even when several
+      # applications share a backend. Rotating it also prevents an in-flight
+      # request from repopulating the active cache with a pre-reload result.
+      # Old entries expire by their configured TTL; no global backend deletion
+      # is needed. Embedding caches are independent and remain available.
       #
       # @return [void]
       def invalidate_context_cache!
-        @cache_store.clear(namespace: :context)
-      rescue StandardError => e
-        warn("[Woods] CachedRetriever context-cache invalidation failed: #{e.message}")
+        @context_mutex.synchronize { @context_namespace = SecureRandom.hex(16) }
       end
 
       # Execute the retrieval pipeline with context-level caching.
@@ -486,7 +492,8 @@ module Woods
       # @param exclude_types [Array<String, Symbol>, nil]
       # @return [String]
       def context_key(query, budget, types: nil, exclude_types: nil, packages: nil, source_paths: nil, evidence: 'full') # rubocop:disable Metrics/ParameterLists
-        parts = [query, budget.to_s, fingerprint(types), fingerprint(exclude_types)]
+        namespace = @context_mutex.synchronize { @context_namespace }
+        parts = [namespace, query, budget.to_s, fingerprint(types), fingerprint(exclude_types)]
         parts << 'lexical' if mode == :lexical
         parts << JSON.generate(evidence: evidence) unless evidence == 'full'
         if Retrieval::Scope.requested?(packages: packages, source_paths: source_paths)

data/lib/woods/console/adapter_family.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Woods
+  module Console
+    # Adapter names differ from the SQL grammar and session settings they use.
+    module AdapterFamily
+      # Classify a live connection by adapter ancestry, database configuration,
+      # then its display name. Unknown families remain nil: SQL callers must
+      # refuse rather than silently omit dialect-specific safeguards.
+      # @param connection [Object] Active Record connection or compatible adapter
+      # @return [Symbol, nil] :postgres, :mysql, :sqlite, or unknown
+      def self.for(connection)
+        ancestry = connection.class.ancestors.filter_map(&:name)
+        return :postgres if ancestry.include?('ActiveRecord::ConnectionAdapters::PostgreSQLAdapter')
+        return :mysql if ancestry.any? { |name| name.match?(/::(?:AbstractMysql|Mysql2|Trilogy)Adapter\z/) }
+        return :sqlite if ancestry.include?('ActiveRecord::ConnectionAdapters::SQLite3Adapter')
+
+        from_name(configured_adapter(connection)) || from_name(connection.adapter_name)
+      end
+
+      def self.configured_adapter(connection)
+        return unless connection.respond_to?(:pool) && connection.pool.respond_to?(:db_config)
+
+        connection.pool.db_config.adapter
+      end
+      private_class_method :configured_adapter
+
+      def self.from_name(value)
+        name = value.to_s.downcase
+        return :mysql if name.include?('mysql') || %w[trilogy mariadb].include?(name)
+        return :postgres if name.include?('postgre') || %w[postgis cockroachdb redshift].include?(name)
+        return :sqlite if name.include?('sqlite')
+
+        nil
+      end
+      private_class_method :from_name
+    end
+  end
+end

data/lib/woods/console/credential_index.rb

@@ -46,7 +46,7 @@ module Woods
     #   index.redact("token: sk_live_actual_secret_value")
     #     # => "token: [REDACTED:credential]"
     #
-    class CredentialIndex
+    class CredentialIndex # rubocop:disable Metrics/ClassLength
       # Captured at require time so the mtime-check warning has a stable
       # reference point even if the clock skews later. Frozen immediately
       # to prevent accidental mutation.
@@ -187,7 +187,10 @@ module Woods
       def initialize(secrets:)
         filtered = Array(secrets).select { |s| s.is_a?(String) && s.length >= MIN_LENGTH }
         @secrets = filtered.to_set.freeze
-        @pattern = @secrets.empty? ? nil : Regexp.union(@secrets.to_a)
+        # Regexp alternatives match in order: a shorter prefix must not consume
+        # only the start of a longer indexed credential and expose its suffix.
+        longest_first = @secrets.each_with_index.sort_by { |secret, idx| [-secret.length, idx] }.map(&:first)
+        @pattern = @secrets.empty? ? nil : Regexp.union(longest_first)
       end
 
       # @return [Boolean] true when no secrets were collected (missing key,
@@ -212,7 +215,34 @@ module Woods
       def redact(str)
         return str if empty? || !str.is_a?(String) || !@pattern.match?(str)
 
-        str.gsub(@pattern, REDACTED)
+        offset = 0
+        parts = []
+        redaction_spans(str).each do |start, finish|
+          parts << str[offset...start] << REDACTED
+          offset = finish
+        end
+        parts << str[offset..]
+        parts.join
+      end
+
+      private
+
+      # Search from each match's start, rather than its end, so an overlapping
+      # credential cannot expose its suffix after an earlier replacement.
+      # Union the covered spans before changing the original string.
+      def redaction_spans(str)
+        spans = []
+        offset = 0
+        while (match = @pattern.match(str, offset))
+          start, finish = match.offset(0)
+          if spans.last && start < spans.last[1]
+            spans.last[1] = [spans.last[1], finish].max
+          else
+            spans << [start, finish]
+          end
+          offset = start + 1
+        end
+        spans
       end
     end
   end