woods 1.6.1 → 2.0.0.beta2

data/docs/WHY_WOODS.md

@@ -0,0 +1,219 @@
+# Why Woods?
+
+AI coding assistants are only as good as the context they receive. For Rails applications,
+that context is almost always wrong, not because the AI is bad, but because Rails hides
+most of its behavior behind conventions, concerns, and runtime magic that no static tool
+can see. Woods fixes this.
+
+---
+
+## The Problem: LLMs Get Rails Wrong
+
+Rails is a framework built on convention over configuration. That's great for developers,
+but it means the "real" code, the callbacks, the scopes, the route bindings, the concern
+behavior, isn't visible in source files. An LLM reading your files sees the skeleton.
+Woods shows the whole body.
+
+**Three concrete examples:**
+
+### "What callbacks fire when User saves?"
+
+Without Woods, an LLM reads your 40-line `User` model and guesses:
+
+```
+User has: before_validation :normalize_email, before_save :set_slug
+```
+
+But `User` includes `Auditable`, `Searchable`, and `SoftDeletable`, each with their own
+callback chains. The real answer is a chain of 11 callbacks across 4 files, including
+`after_commit :reindex_search` and `after_destroy :purge_avatar`.
+
+With Woods, the model unit has all concerns inlined and the full resolved callback
+chain in structured metadata. The LLM sees exactly what Rails sees at runtime.
+
+### "What routes map to OrdersController?"
+
+Without Woods, an LLM assumes standard REST and guesses:
+
+```
+GET    /orders          orders#index
+GET    /orders/:id      orders#show
+POST   /orders          orders#create
+...
+```
+
+Your app has custom routes: `POST /checkout` → `orders#create`, `PUT /orders/:id/cancel`
+→ `orders#cancel`, and a nested resource under `/shops/:shop_id`. The LLM's guess is wrong
+on path, wrong on nesting, and missing the custom action entirely.
+
+With Woods, `ControllerExtractor` calls `Rails.application.routes` at runtime and
+prepends the real route table to the controller source. No guessing.
+
+### "What does the checkout flow do?"
+
+Without Woods, an LLM reads `CheckoutService` and sees a 60-line service object.
+It describes what the service does, but misses that `order.save!` triggers `after_commit
+: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.
+
+---
+
+## What Does Woods Do?
+
+Woods runs inside your Rails application and produces structured, runtime-accurate
+representations of every layer: models, controllers, services, jobs, components, routes,
+middleware, and more.
+
+**The key outcomes:**
+
+**Concern inlining.** Every `include`d concern is read from disk and embedded directly into
+the model unit. When an AI asks about `User`, it gets `User` + `Auditable` + `Searchable`
+in one context block, not three separate lookups.
+
+```ruby
+# What an AI sees without Woods (app/models/user.rb):
+class User < ApplicationRecord
+  include Auditable
+  include Searchable
+end  # 4 lines, the AI guesses what these concerns add
+
+# What Woods produces (User.json source_code field):
+# == Schema Information
+# email    :string           not null
+# name     :string
+#
+# class User < ApplicationRecord
+#   include Auditable
+#   include Searchable
+#   validates :email, presence: true
+# end
+#
+# ┌─────────────────────────────────────────────────────────────────────┐
+# │ Included from: Auditable                                            │
+# └─────────────────────────────────────────────────────────────────────┘
+#   def audit_trail; AuditLog.create!(auditable: self); end
+#   after_save :audit_trail
+# ─────────────────────────── End Auditable ───────────────────────────
+#
+# ┌─────────────────────────────────────────────────────────────────────┐
+# │ Included from: Searchable                                           │
+# └─────────────────────────────────────────────────────────────────────┘
+#   scope :search, ->(q) { where("name ILIKE ?", "%#{q}%") }
+#   after_commit :reindex_search
+# ─────────────────────────── End Searchable ───────────────────────────
+```
+
+**Schema prepending.** Model source gets a schema header with column types, indexes, and
+foreign keys pulled live from the database. No more confusing `string` vs `text` vs
+`integer` guesses.
+
+**Route-to-controller binding.** Controller source gets a route block prepended showing
+exactly which HTTP verbs and paths map to which actions. URL → code is always explicit.
+
+**Dependency graph.** 35 extractors build a bidirectional graph: what each unit depends on,
+and what depends on it. Change `Auditable` and you can trace every model affected.
+
+**Two MCP servers.** The Index Server defines 29 schemas and registers 14 in the normal
+packaged launch; it reads pre-extracted JSON without booting Rails. The Console Server
+has a 31-schema inventory but registers 9 tools by default, or 11 with explicit embedded
+read tools, and bridges to a live Rails process for bounded database queries.
+
+```bash
+# What you get after extraction
+tmp/woods/
+├── generation.json            # Atomic pointer to the current complete payload
+└── payloads/gen-<N>/
+    ├── manifest.json          # Extraction metadata and git SHA
+    ├── dependency_graph.json  # Full graph with PageRank scores
+    └── models/User.json       # Schema + inlined concerns + resolved callbacks
+```
+
+---
+
+## Who Is Woods For?
+
+**Teams using MCP-capable coding tools and agents.** Woods is model-independent; it
+supplies Rails context through MCP to tools backed by OpenAI, Anthropic, Google, xAI,
+or other model providers. If an agent helps with Rails code but lacks runtime context,
+Woods fills that gap.
+
+**Rails apps of any size.** Small apps benefit from accurate schema and route context.
+Large monoliths benefit most, hundreds of models with deep callback chains and concern
+hierarchies are exactly where static tools fail and Woods shines.
+
+**Anyone who wants structured codebase context.** The extraction output is plain JSON, useful beyond AI tools for documentation, impact analysis, and onboarding.
+
+Woods works with any database (MySQL, PostgreSQL, SQLite), any background job
+system (Sidekiq, Solid Queue, GoodJob), and any view layer (ERB, Phlex, ViewComponent).
+See [docs/BACKEND_MATRIX.md](BACKEND_MATRIX.md) for the full compatibility matrix.
+
+---
+
+## When NOT to Use Woods
+
+Woods is not a universal fit. Skip it when:
+
+- **You're not building in Rails.** Woods leans hard on `ActiveRecord::Base.descendants`, `Rails.application.routes`, and reflection APIs, the value dries up outside Rails. For Django, Phoenix, or non-framework Ruby, other tools are a better fit.
+- **You need static analysis without booting.** Extraction requires a booted Rails environment because runtime introspection is the whole point. If your constraint is "can't boot the app" (locked-down CI, untrusted code review), static parsers are what you want.
+- **Production-only environments.** Extraction should run in development or CI. The Console Server is explicitly unsafe for production even with all five defense layers, it is a dev/staging tool.
+- **Row-level data is the goal.** Woods extracts schema and structure, not data. If you need to index row content for retrieval (customer records, documents, audit events), a different pipeline is appropriate.
+- **Tiny apps that already fit in context.** A 20-model app may not benefit, the LLM can probably read every file. Woods' win scales with monolith size and concern depth.
+- **You want a hosted service.** Woods is a gem, not a SaaS. Extraction output lives on your machines and the MCP servers run on your hardware. There is no cloud component.
+
+---
+
+## How Woods compares to other Rails code tools
+
+Three tools answered "what is in this Rails app" for coding agents in 2026. Woods overlaps with each on structure and differs on runtime behavior.
+
+| Tool | Version checked | How it reads the app | Strong at | Does not cover |
+|---|---|---|---|---|
+| 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 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.
+
+---
+
+## Quick Start
+
+Install, extract, validate, and connect:
+
+```bash
+# 1. Add to your Rails app's Gemfile
+gem 'woods', '~> 2.0', group: :development
+
+# 2. Install
+bundle install
+bin/rails generate woods:install
+
+# The generator also emits a legacy application migration. Woods 2's shipped
+# paths do not use those tables; remove it for a new default installation.
+
+# 3. Extract (requires a booted Rails environment)
+bin/rails woods:extract
+
+# 4. Verify
+bin/rails woods:validate
+bin/rails woods:stats
+
+# 5. Add to .mcp.json
+# { "mcpServers": { "woods": { "command": "bundle",
+#     "args": ["exec", "woods-mcp-start", "./tmp/woods"],
+#     "cwd": "/absolute/path/to/your-rails-app" } } }
+
+# 6. Ask your AI tool a question about your codebase
+```
+
+For Docker, run extraction inside the application container. If Woods is installed
+only there, launch the Index Server through that container too. See
+[Getting started](GETTING_STARTED.md) for the complete walkthrough and
+[Docker setup](DOCKER_SETUP.md) for executable container and host alternatives.

data/exe/woods-console

@@ -27,6 +27,7 @@ unless protocol_out
   $stdout.reopen($stderr)
 end
 
+require 'woods'
 require 'woods/console/server'
 
 unless Woods.configuration.console_mcp_enabled
@@ -36,8 +37,19 @@ unless Woods.configuration.console_mcp_enabled
   exit 1
 end
 
-# Ensure all application models are loaded for the registry.
-Rails.application.eager_load!
+# Ensure all application models are loaded for the registry. A NameError
+# here (e.g. app/graphql/ referencing an uninstalled gem) would otherwise
+# crash the whole server before it can even report why — warn and continue
+# with whatever eager_load! managed to load, mirroring the extractor's own
+# eager_load! fallback (Extractor#safe_eager_load!). The registry below is
+# then built from whatever's in ActiveRecord::Base.descendants, so a partial
+# load just means a partial registry, not a dead server.
+begin
+  Rails.application.eager_load!
+rescue NameError => e
+  warn "[Woods Console] eager_load! hit NameError: #{e.message}. " \
+       'Continuing with a possibly incomplete model registry.'
+end
 
 registry = ActiveRecord::Base.descendants.each_with_object({}) do |model, hash|
   next if model.abstract_class?
@@ -78,14 +90,38 @@ rescue StandardError
   next
 end
 
-validator = Woods::Console::ModelValidator.new(registry: registry)
-safe_context = Woods::Console::SafeContext.new(connection: ActiveRecord::Base.connection)
+validator = Woods::Console::ModelValidator.new(registry: registry, table_names: model_tables)
+
+# SafeContext gets the writing connection *pool*, not a connection, so each
+# request leases a fresh connection via `pool.with_connection { ... }` and
+# returns it when the rolled-back transaction completes. Capturing one
+# connection here pinned it for the process lifetime: after a database
+# failover or a `wait_timeout` recycle every tool call failed on the stale
+# connection until restart. The HTTP path has leased per request since
+# `RackMiddleware#build_embedded_server`; stdio predated that fix.
+safe_context = Woods::Console::SafeContext.new(pool: ActiveRecord::Base.connection_pool)
 
 config = Woods.configuration
 redacted_columns = Array(config.console_redacted_columns)
 redacted_key_values = Array(config.console_redacted_key_values)
 read_tools_enabled = config.console_embedded_read_tools
 
+# Mirrors Woods::Console::RackMiddleware#check_blocked_tables_config! — the
+# stdio server wires the same TableGate config, so it needs the same loud
+# warning (or hard failure in production) when Layer 1 is inactive.
+if Array(config.console_blocked_tables).empty?
+  blocked_tables_message =
+    '[Woods Console] console_blocked_tables is empty — Layer 1 (table gate) is INACTIVE. ' \
+    'All tables are reachable via the Console MCP. ' \
+    'Set console_blocked_tables in your Woods initializer to restrict access. ' \
+    'Example: Woods.configure { |c| c.console_blocked_tables = ' \
+    'Woods::DEFAULT_CONSOLE_BLOCKED_TABLES + %w[your_table] }'
+
+  raise Woods::ConfigurationError, blocked_tables_message if Rails.env.production?
+
+  warn blocked_tables_message
+end
+
 server = Woods::Console::Server.build_embedded(
   model_validator: validator,
   safe_context: safe_context,

data/exe/woods-console-mcp

@@ -1,46 +1,32 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Console MCP server for querying live Rails application state.
+# Launches the real embedded Console MCP server through direct, Docker, or SSH
+# process execution. The child owns stdio and lifecycle directly.
 #
-# Usage:
-#   woods-console-mcp
-#   WOODS_CONSOLE_CONFIG=/path/to/console.yml woods-console-mcp
-#
-# Connects to a Rails application via a bridge process (Docker exec, direct,
-# or SSH) and exposes read-only query tools via the Model Context Protocol
-# (stdio transport).
-#
-# Disabled by default. Set Woods.configuration.console_mcp_enabled = true
-# in the host application's Woods initializer to enable. Layer 1 blocked
-# tables, Layer 2 credential scanning, and Layer 3 column/EAV redaction are
-# all configured through Woods::Configuration — see docs/CONSOLE_MCP_SETUP.md.
-
-# Suppress json-schema MultiJSON deprecation notice that would otherwise pollute
-# stderr during MCP stdio transport. The deprecation fires the first time
-# +json-schema+ is required — must happen before any Woods require that could
-# transitively pull it in. MCP clients parsing stderr can't tolerate banners.
-begin
-  require 'json-schema'
-  JSON::Validator.use_multi_json = false if defined?(JSON::Validator) && JSON::Validator.respond_to?(:use_multi_json=)
-rescue LoadError
-  # json-schema isn't in every bundle.
-end
+# Configuration precedence:
+#   1. WOODS_CONSOLE_CONFIG, when set (the file must exist)
+#   2. ~/.woods/console.yml, when present
+#   3. direct mode with `bundle exec rake woods:console`
 
 require 'yaml'
-require 'woods'
-require_relative '../lib/woods/console/server'
+require_relative '../lib/woods/console/connection_manager'
 
-unless Woods.configuration.console_mcp_enabled
-  warn 'Woods Console MCP is disabled. Set ' \
-       'Woods.configuration.console_mcp_enabled = true to enable. ' \
-       'See docs/CONSOLE_MCP_SETUP.md for the full security posture.'
+explicit_path = ENV.fetch('WOODS_CONSOLE_CONFIG', nil)
+config_path = explicit_path || File.expand_path('~/.woods/console.yml')
+
+if explicit_path && !File.file?(config_path)
+  warn "[woods-console-mcp] Config file does not exist: #{config_path}"
   exit 1
 end
 
-config_path = ENV.fetch('WOODS_CONSOLE_CONFIG', File.expand_path('~/.woods/console.yml'))
-config = File.exist?(config_path) ? YAML.safe_load_file(config_path) : {}
+begin
+  config = File.file?(config_path) ? YAML.safe_load_file(config_path, aliases: false) : {}
+  config ||= {}
+  raise Woods::Console::ConnectionError, "#{config_path} must contain a YAML mapping" unless config.is_a?(Hash)
 
-server = Woods::Console::Server.build(config: config)
-transport = MCP::Server::Transports::StdioTransport.new(server)
-transport.open
+  Woods::Console::ConnectionManager.new(config: config).replace_process!
+rescue Psych::Exception, Woods::Console::ConnectionError => e
+  warn "[woods-console-mcp] #{e.message}"
+  exit 1
+end

data/exe/woods-mcp

@@ -11,6 +11,13 @@
 # them via the Model Context Protocol (stdio transport).
 # Does NOT require Rails — only reads pre-extracted data.
 
+# A wrapper can exec this file directly, bypassing RubyGems' generated launcher.
+# Activate this installed gem before optional requires select dependency versions.
+# Source checkouts continue to use their calling bundle.
+Gem::Specification.find_all_by_name('woods').find do |spec|
+  File.realpath(spec.full_gem_path) == File.realpath(File.expand_path('..', __dir__))
+end&.activate
+
 # Suppress json-schema MultiJSON deprecation notice that would otherwise pollute
 # stderr during MCP stdio transport. The deprecation fires the first time
 # +json-schema+ is required — earlier revisions set the flag *after* the
@@ -37,14 +44,18 @@ begin
   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)
-rescue Woods::MCP::BootstrapError => e
+# ConfigurationError is caught alongside BootstrapError so an unusable
+# embedding configuration (e.g. a provider wired without its required
+# credential) surfaces as the one-line operator message instead of a raw
+# backtrace (M9).
+rescue Woods::MCP::BootstrapError, Woods::ConfigurationError => e
   warn "[woods-mcp] #{e.class.name.split('::').last}: #{e.message}"
   warn "[woods-mcp] details: #{e.details.inspect}" if e.respond_to?(:details) && !e.details.empty?
   exit 2
 end
 
-retriever_reloader = lambda do
-  Woods::MCP::Bootstrapper.reload_stores!(retriever, index_dir: index_dir)
+retriever_reloader = lambda do |reader|
+  Woods::MCP::Bootstrapper.reload_stores!(retriever, index_dir: index_dir, reader: reader, state: bootstrap_state)
 end
 
 server = Woods::MCP::Server.build(
@@ -52,10 +63,12 @@ server = Woods::MCP::Server.build(
   bootstrap_state: bootstrap_state, retriever_reloader: retriever_reloader
 )
 
-# Pin protocol version for broad client compatibility (Claude Code, Cursor, etc.)
-if ENV['MCP_PROTOCOL_VERSION']
-  server.configuration = MCP::Configuration.new(protocol_version: ENV['MCP_PROTOCOL_VERSION'])
-end
+# Never pin by default: the SDK server answers `initialize` for legacy
+# clients AND serves `server/discover` for modern ones, so pinning collapses
+# it to one era. MCP_PROTOCOL_VERSION exists only as an operator escape
+# hatch for a client that can't negotiate — see the "never pin
+# MCP_PROTOCOL_VERSION" gotcha in CLAUDE.md.
+server.configuration.protocol_version = ENV['MCP_PROTOCOL_VERSION'] if ENV['MCP_PROTOCOL_VERSION']
 
 transport = MCP::Server::Transports::StdioTransport.new(server)
 transport.open

data/exe/woods-mcp-http

@@ -9,7 +9,15 @@
 #
 # Reads JSON files from the extraction output directory and exposes
 # them via the Model Context Protocol (Streamable HTTP transport).
-# Requires the `rackup` gem and a Rack-compatible server (e.g., puma).
+# Requires a Rack-compatible server (e.g., puma). Uses `rackup` when available
+# and falls back to Rack 2's bundled handler registry for older Rails hosts.
+
+# A wrapper can exec this file directly, bypassing RubyGems' generated launcher.
+# Activate this installed gem before optional requires select dependency versions.
+# Source checkouts continue to use their calling bundle.
+Gem::Specification.find_all_by_name('woods').find do |spec|
+  File.realpath(spec.full_gem_path) == File.realpath(File.expand_path('..', __dir__))
+end&.activate
 
 # Suppress json-schema MultiJSON deprecation before any require chain that
 # could transitively load json-schema. See exe/woods-mcp for the full rationale.
@@ -20,7 +28,13 @@ rescue LoadError
   # json-schema isn't in every bundle.
 end
 
-require 'rackup'
+begin
+  require 'rackup'
+rescue LoadError
+  require 'rack'
+end
+require 'bundler'
+require 'uri'
 require_relative '../lib/woods'
 require_relative '../lib/woods/dependency_graph'
 require_relative '../lib/woods/graph_analyzer'
@@ -35,7 +49,11 @@ begin
   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)
-rescue Woods::MCP::BootstrapError => e
+# ConfigurationError is caught alongside BootstrapError so an unusable
+# embedding configuration (e.g. a provider wired without its required
+# credential) surfaces as the one-line operator message instead of a raw
+# backtrace (M9).
+rescue Woods::MCP::BootstrapError, Woods::ConfigurationError => e
   warn "[woods-mcp-http] #{e.class.name.split('::').last}: #{e.message}"
   warn "[woods-mcp-http] details: #{e.details.inspect}" if e.respond_to?(:details) && !e.details.empty?
   exit 2
@@ -55,24 +73,75 @@ if loopback && token.nil?
   warn '[woods-mcp-http] WARNING: running on loopback without a token; local processes can reach this server.'
 end
 
-retriever_reloader = lambda do
-  Woods::MCP::Bootstrapper.reload_stores!(retriever, index_dir: index_dir)
+retriever_reloader = lambda do |reader|
+  Woods::MCP::Bootstrapper.reload_stores!(retriever, index_dir: index_dir, reader: reader, state: bootstrap_state)
 end
 
 server = Woods::MCP::Server.build(
   index_dir: index_dir, retriever: retriever, snapshot_store: snapshot_store,
   bootstrap_state: bootstrap_state, retriever_reloader: retriever_reloader
 )
-transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
-server.transport = transport
-
+# Stateless Streamable HTTP (MCP 2026-07-28, SEP-2567) is the default.
+#
+# Protocol-level sessions are gone from the spec, and for this server they were
+# never carrying anything: the index is on disk, `IndexReader` self-refreshes off
+# the published generation, and no tool holds per-client state. What the session
+# DID do was tie every client to one server process — so a restart (gem upgrade,
+# machine sleep, worktree rebuild) invalidated every session and forced a
+# re-initialize. Stateless makes a restart invisible, and lets several instances
+# serve one volume-mounted index without sticky routing.
+#
+# Set WOODS_MCP_HTTP_STATELESS=0 to restore session mode for a client that still
+# needs `Mcp-Session-Id`, the GET SSE stream, or DELETE teardown. That escape
+# 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
+)
+server.transport = transport
 
-inner = proc { |env| transport.handle_request(Rack::Request.new(env)) }
+inner = proc do |env|
+  env = env.dup
+  env.delete('HTTP_MCP_SESSION_ID') if stateless
+  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)
 
 origin_summary = allowed_origins.empty? ? 'loopback' : allowed_origins.join(',')
 auth_mode = token ? 'bearer' : 'none'
-warn "Woods MCP HTTP server starting on http://#{host}:#{port} (auth: #{auth_mode}, origins: #{origin_summary})"
-Rackup::Handler.default.run(app, Port: port, Host: host)
+session_mode = stateless ? 'stateless' : 'sessions (deprecated)'
+warn "Woods MCP HTTP server starting on http://#{host}:#{port} " \
+     "(auth: #{auth_mode}, origins: #{origin_summary}, mode: #{session_mode})"
+begin
+  handler = if defined?(Rackup::Handler)
+              Rackup::Handler.default
+            else
+              Rack::Handler.default
+            end
+rescue LoadError => e
+  abort "[woods-mcp-http] No Rack server handler is available (#{e.message}). " \
+        'Add a Rack-compatible server such as puma to the host bundle, or run under an existing Rack server.'
+end
+
+unless handler.respond_to?(:run)
+  abort '[woods-mcp-http] No Rack server handler is available. ' \
+        'Add a Rack-compatible server such as puma to the host bundle, or run under an existing Rack server.'
+end
+
+begin
+  handler.run(app, Port: port, Host: host)
+rescue LoadError => e
+  abort "[woods-mcp-http] Rack server handler failed to load (#{e.message}). " \
+        'Add a Rack-compatible server such as puma to the host bundle, or run under an existing Rack server.'
+end

data/exe/woods-mcp-start

@@ -1,58 +1,63 @@
-#!/usr/bin/env bash
-# Self-healing wrapper for the Woods MCP server.
-# Ensures Ruby dependencies are installed, validates the index directory,
-# and starts the stdio MCP server.
-#
-# Usage (direct):
-#   woods-mcp-start /path/to/index_dir
-#
-# Usage (.mcp.json):
-#   {
-#     "command": "${HOME}/work/codebase_index/exe/woods-mcp-start",
-#     "args": ["${HOME}/my-rails-app/tmp/woods"]
-#   }
-#
-# All diagnostic output goes to stderr to keep stdio clean for MCP protocol.
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-GEM_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
-INDEX_DIR="${1:-${WOODS_DIR:-}}"
-
-# --- Validate index directory ---
-if [[ -z "$INDEX_DIR" ]]; then
-  echo "Error: No index directory specified." >&2
-  echo "Usage: woods-mcp-start /path/to/index_dir" >&2
-  exit 1
-fi
+#!/usr/bin/env ruby
+# frozen_string_literal: true
 
-if [[ ! -d "$INDEX_DIR" ]]; then
-  echo "Error: Index directory does not exist: $INDEX_DIR" >&2
-  echo "Run extraction first: bundle exec rake woods:extract" >&2
-  exit 1
-fi
+# Preflight entry point for the Woods Index MCP server: it validates the index
+# directory and its published manifest, then `exec`s woods-mcp in place. There
+# is no supervision and no restart loop — a crashed woods-mcp stays down, the
+# same as when launched directly. RubyGems loads gem executables as Ruby, so
+# this wrapper must remain a Ruby program when packaged.
 
-if [[ ! -f "$INDEX_DIR/manifest.json" ]]; then
-  echo "Error: No manifest.json in: $INDEX_DIR" >&2
-  echo "Run extraction first: bundle exec rake woods:extract" >&2
-  exit 1
-fi
+index_dir = ARGV[0] || ENV.fetch('WOODS_DIR', nil)
 
-# --- Ensure Ruby dependencies are installed ---
-export BUNDLE_GEMFILE="${GEM_DIR}/Gemfile"
+if index_dir.nil? || index_dir.empty?
+  warn 'Error: No index directory specified.'
+  warn 'Usage: woods-mcp-start /path/to/index_dir'
+  exit 1
+end
 
-if ! bundle check > /dev/null 2>&1; then
-  echo "Installing woods dependencies..." >&2
-  if ! bundle install --quiet >&2 2>&1; then
-    echo "Error: bundle install failed. Check Ruby version and network." >&2
-    exit 1
-  fi
-  echo "Dependencies installed." >&2
-fi
+unless File.directory?(index_dir)
+  warn "Error: Index directory does not exist: #{index_dir}"
+  warn 'Run extraction first: bundle exec rake woods:extract'
+  exit 1
+end
+
+# Mirrors Woods::Generation#payload_dir + Woods::MCP::Bootstrapper.manifest_present?
+# (lib/woods/generation.rb, lib/woods/mcp/bootstrapper.rb) without requiring
+# the gem: this pre-flight runs before the `exec` below, so pulling in the
+# whole library just to check one file is wasted work on every boot. A
+# payload-born index has no manifest.json at the root — it lives under the
+# directory generation.json's `payload` pointer names — so the pointer is
+# followed here too, with the same escape guard, before concluding the
+# directory holds no index. woods-mcp re-checks this properly through
+# Bootstrapper regardless; this is just an early, friendlier exit.
+def manifest_present?(index_dir)
+  return true if File.file?(File.join(index_dir, 'manifest.json'))
+
+  generation_path = File.join(index_dir, 'generation.json')
+  return false unless File.file?(generation_path)
+
+  require 'json'
+  require_relative '../lib/woods/atomic_file'
+  payload_name = JSON.parse(Woods::AtomicFile.read(generation_path))['payload']
+  return false if payload_name.nil? || payload_name.empty?
+
+  root = File.expand_path(index_dir)
+  candidate = File.expand_path(File.join(root, payload_name))
+  return false unless candidate.start_with?("#{root}#{File::SEPARATOR}")
+
+  File.file?(File.join(candidate, 'manifest.json'))
+rescue JSON::ParserError, SystemCallError
+  false
+end
+
+unless manifest_present?(index_dir)
+  warn "Error: No manifest.json in: #{index_dir}"
+  warn 'Run extraction first: bundle exec rake woods:extract'
+  exit 1
+end
 
-# --- Pin MCP protocol version for Claude Code compatibility ---
-export MCP_PROTOCOL_VERSION="${MCP_PROTOCOL_VERSION:-2024-11-05}"
+if ENV['MCP_PROTOCOL_VERSION'] && !ENV['MCP_PROTOCOL_VERSION'].empty?
+  warn "Pinning MCP protocol version to #{ENV.fetch('MCP_PROTOCOL_VERSION')} (unset it to negotiate)."
+end
 
-# --- Start the MCP server ---
-exec bundle exec ruby "${GEM_DIR}/exe/woods-mcp" "$INDEX_DIR"
+exec(File.expand_path('woods-mcp', __dir__), index_dir)