woods 2.0.0.beta4 → 2.0.0

data/docs/WATCH_DAEMON.md

@@ -34,15 +34,160 @@ Ctrl-C to stop.
 | `WOODS_WATCH_CATCH_UP` | `1` | `0` skips the startup reconciliation |
 | `WOODS_WATCH_TRUST_FOREIGN_HOST` | unset | `1` lets a reader trust a fresh foreign-host heartbeat without checking its pid locally; see [cross-host liveness](#cross-host-liveness) |
 
-Run it under a supervisor. When boot-captured configuration changes the daemon
-exits `75` (`EX_TEMPFAIL`) on purpose, see [Restart triggers](#restart-triggers).
+The raw task needs a supervisor that restarts it after exit `75` (`EX_TEMPFAIL`);
+see [Restart triggers](#restart-triggers). Docker restart policies can supply
+this. A bare task in Foreman cannot: Foreman shuts down its process group when a
+child exits. Use the managed launcher below for native Procfile development.
 
-```yaml
-# Procfile.dev
-web:   bin/rails server
-woods: bundle exec rake woods:watch
+### Managed development startup
+
+**Included in Woods `2.0.0` ([#538](https://github.com/lost-in-the/woods/issues/538)).**
+Record the installed gem path and Git revision as well as VERSION; a checkout
+can have new behavior with the last beta's version. Verify both commands before
+using the new setup:
+
+```bash
+bundle exec woods-watch --help
+bin/rails generate woods:watch --help
+```
+
+Choose one lifecycle owner per application index:
+
+| Existing development workflow | Setup |
+|---|---|
+| Rails/Puma, including a `bin/dev` that just starts Rails | Opt-in `puma` mode; the development Puma master starts one separate extraction process, regardless of worker count. |
+| An existing Foreman workflow | `procfile` mode with the exact existing Procfile and selected normal Foreman command. |
+| Docker Compose, Grove, or another supervisor | `external` mode returns the raw task command; configure its lifecycle through the existing supervisor. |
+
+For Puma, preview before applying:
+
+```bash
+bin/rails generate woods:watch --mode puma --pretend
+bin/rails generate woods:watch --mode puma
+```
+
+This adds an executable `bin/woods-watch` and an owned directive to
+`config/puma.rb`. The directive loads the plugin only when the active Woods gem
+contains it. An absent gem or an older version without the plugin leaves Puma
+running without a watcher; this also works for Git/path bundles. The adapter
+separately enforces Puma's finalized development environment.
+Starting a console, task, or production
+Puma does not start a watcher. The watcher still uses another Rails process and its associated memory.
+Puma installation checks the application's installed Puma version (supported
+majors: 6, 7, and 8 on native Unix Ruby) and selects the normal `bin/rails server`
+path using `config/puma.rb`. If `config/puma/development.rb` exists, setup refuses
+because Puma would choose it first. Custom `-C` configurations need an explicit
+external/Foreman arrangement; this generator does not discover or rewrite them.
+
+For an existing Foreman arrangement, select the command you will actually use:
+
+```bash
+bin/rails generate woods:watch --mode procfile --procfile Procfile.dev \
+  --manager-command 'foreman start -f Procfile.dev' --pretend
+```
+
+Repeat without `--pretend` to apply. Preflight checks task discovery and Foreman
+availability with bounded commands; it does not start services. Installation
+preserves `bin/dev` and every unowned service. If `bin/dev` only runs Rails, it
+will still only run Rails: choose Puma mode or explicitly use the selected
+Foreman command. No process-manager gem is installed automatically.
+
+Run setup with the same application environment as normal startup. Preflight
+preserves environment-based Bundler configuration, including `BUNDLE_PATH`,
+`BUNDLE_APP_CONFIG`, and excluded groups, while resetting inherited activation
+state and requesting frozen resolution. Earlier Git builds of this
+installer dropped those settings ([#540](https://github.com/lost-in-the/woods/issues/540)).
+If normal task discovery works but installer preflight cannot find Rails or an
+installed dependency, check the loaded revision and bundle environment before
+reinstalling gems or adding a persistent `.bundle/config` workaround.
+
+Installer refusals return a nonzero exit status with their diagnostic (#544,
+included in Woods `2.0.0`). Earlier Git builds printed the refusal but exited
+successfully, so automation using those builds must also check the diagnostic and
+whether installation actually applied.
+
+Use `--child-command 'bundle exec rails woods:watch'` when that is the
+application's actual Rails entrypoint. Command strings become explicit argument
+vectors; shell pipelines, variable expansion, and shell setup scripts are not
+supported. Do not prepend an `environment` task or an already booted Rails runner.
+
+### Ownership, updates, and removal
+
+The generator records relative owned paths and fingerprints in `.woods-watch.json`.
+Commit it with the generated configuration so a new clone/worktree can update or
+remove that setup. Runtime transaction state stays under `tmp/woods-watch-install/`;
+keep that directory ignored. Changes to owned content or executable permissions
+cause a conflict rather than an overwrite. Review the conflict and restore or
+adapt the owned setup explicitly; do not delete the receipt to force an overwrite.
+
+```bash
+# Change modes or update owned setup (include the selected mode's options).
+bin/rails generate woods:watch --operation update --mode puma --pretend
+# Remove owned startup fragments and wrapper; preserve application edits.
+bin/rails generate woods:watch --operation remove --pretend
 ```
 
+Repeat without `--pretend` to apply. Stop an existing watcher through its current
+manager before changing owners; the generator does not stop running processes.
+Explicit updates refresh owned directives in place, preserving surrounding text
+and the block's newline style. Repeating setup preserves the existing directive.
+Earlier Git builds used a Puma guard that checked only whether Woods was loaded;
+use the update command above with a supporting bundle to install the capability
+guard ([#542](https://github.com/lost-in-the/woods/issues/542), included in Woods
+`2.0.0`). Do not hand-edit the owned block or receipt.
+
+For a permanent downgrade, remove the startup configuration while the supporting
+gem is still installed. The updated Puma guard lets a branch with an older gem
+boot without indexing; it does not make `bin/woods-watch` or a Foreman entry
+compatible with that gem.
+For Docker/Grove, see [automatic maintenance](AUTOMATIC_MAINTENANCE.md).
+
+An interrupted apply retains its local transaction journal. When Rails boots,
+preview recovery with `bin/rails generate woods:watch --operation recover
+--pretend`, then repeat without `--pretend`. The Rails command boots the application
+before invoking the generator; its `--pretend` prevents installation writes,
+not application initialization.
+
+If an initializer prevents Rails boot, run the boot-free recovery helper directly
+from the application root using its bundle:
+
+```bash
+bundle exec ruby -rwoods/watch/installation -e \
+  'puts Woods::Watch::Installation.new(root: Dir.pwd).recover(pretend: true)'
+```
+
+Repeat with `pretend: false` to restore the recorded transaction. Recovery checks
+snapshots and changes only owned files; concurrent edits keep the journal for
+manual resolution. The helper does not load Rails or run task probes. Do not
+delete a pending journal to force setup.
+
+### Managed restart and failure behavior
+
+`woods-watch -- bin/rails woods:watch` stays outside Rails and starts a fresh child
+for each planned restart. It absorbs exit 75 so Foreman/Puma remain running.
+Managed launching requires POSIX process groups and `fork` (Linux/macOS Ruby).
+Other platforms should use the raw task with an external supervisor.
+Boot failures retry with bounded backoff; a failed extraction leaves the last
+good generation readable. `--boot-timeout SECONDS` defaults to 300 seconds and
+bounds boot/handshake, not a valid extraction or writer-lock wait.
+
+Managed mode requires `WOODS_WATCH_IDLE_TIMEOUT` to be unset: automatic maintenance
+needs a resident child. An unexpected clean stop, incompatible child, or another
+owner parks the launcher with a diagnostic until its normal owner restarts it.
+There is no automatic ownership takeover. Managed duplicate prevention is scoped
+to one host/process namespace; do not mix raw and managed writers across different
+containers sharing an index. Use one external owner for that arrangement.
+
+Daemon liveness, completed startup reconciliation, and source freshness remain
+different facts. Managed supervision records under `watch_supervisors/` expose
+starting/retrying/parked state separately in `woods_status`; an alive supervisor
+without a maintaining child does not provide daemon coverage. If the first Rails
+boot fails before resolving the configured index path, diagnostics are logs-only.
+
+Verify startup catch-up, an edit, and an initializer restart through the existing
+MCP connection before declaring automatic maintenance active. With worktree
+management, also verify source and index mounts switch together.
+
 ## One cycle
 
 ```
@@ -169,7 +314,7 @@ is alive, so *alive has to mean covered*.
 The standalone `woods:watch` task snapshots reload/restart inputs before invoking
 Rails' `environment` task. Inputs unchanged across that boundary, including
 carried paths that remain deleted, may be reconciled by a full extraction.
-Unreleased after `2.0.0.beta3`: registered restart inputs deleted while the
+Included in Woods `2.0.0`: registered restart inputs deleted while the
 daemon was stopped also trigger a full extraction after a fresh environment
 boot. Nominal framework paths still use the bounded deletion sweep.
 Changes during environment initialization still require restart. Lock contention,
@@ -283,6 +428,14 @@ Ignored by default: `.git`, `node_modules`, `tmp`, `log`, `coverage`,
 `vendor/bundle`, `public/assets`, `public/packs`, `storage`. That ignore list is
 what keeps a polling scan bounded.
 
+A commit, ref update, or other Git-only change does not necessarily trigger a
+source-file event. The watcher can therefore keep source current while the
+published Git history or provenance still describes an earlier commit. Run full
+`woods:extract` when current Git metadata is required; incremental extraction
+refreshes history only for rewritten units. For containerized linked worktrees,
+verify [Git directory selection](TROUBLESHOOTING.md#git-directory-mounts-for-linked-worktrees)
+as well as source and index mounts.
+
 Polling and startup catch-up preserve each logical path when multiple directory
 symlinks point to the same source tree. For example, `a_shared/user.rb` and
 `app/models/user.rb` both remain visible; an earlier alias must not hide the path
@@ -293,15 +446,15 @@ aliases in large watched trees. Ignored logical paths are still pruned.
 
 ## Placement
 
-The spike asked for three placements to be compared and one chosen. Every
-collaborator on `Woods::Watch::Daemon` is injected, so all three are reachable
-from the same class, but the default is **(b), a dedicated daemon per
-worktree**:
+Run one dedicated extraction process per active worktree/index. The managed
+Puma adapter and native launcher above retain that separation. Requiring Woods
+or loading its Railtie does not start indexing by itself. Custom integrations
+can use the injected daemon collaborators deliberately:
 
 | Option | Verdict |
 |---|---|
 | **(b) Dedicated daemon**: *recommended default* | One extra booted app per worktree. Isolated: a crash, a restart, or a storm affects only the index. Lifecycle is drivable from worktree hooks. |
-| **(a) Embedded in the dev server** via the Railtie | Marginal memory cost ~0 where a booted app already exists, but couples index freshness to the dev server running and puts extraction on its threads. `Daemon#process` is public precisely so a host can do this deliberately. |
+| **(a) Custom in-process integration** | A host can call public `Daemon#process` deliberately, but must own threading, reloading, and lifecycle. This is not an automatic Railtie feature or the managed Puma adapter. |
 | **(c) Host watcher + in-container session** | Solves bind-mount event unreliability, but with the most moving parts. Forcing the polling backend solves the same problem with none. |
 
 Measured on the fixture app (Ruby 3.3, Rails 8.0):
@@ -652,7 +805,7 @@ hooks (`plugin/hooks/hooks.json`), both shipped disabled:
 Both read `cwd` from the hook payload, so a linked worktree uses its own index.
 Both require an existing `generation.json` and `WOODS_HOOKS_ENABLED=1`;
 `WOODS_HOOKS_DISABLED=1` overrides enablement. The broader refresh task is
-**unreleased after Woods 2.0.0.beta2**. Check the installed gem's task list
+**included in Woods `2.0.0`**. Check the installed gem's task list
 (`bundle exec rake -T woods:hook_refresh`, through the application container
 when appropriate) before enabling this plugin version. An older gem's unknown
 task error leaves queued events in place; installing the plugin does not upgrade
@@ -750,8 +903,10 @@ per-process language-server index does not.
 
 N resident daemons is N booted apps, and most slots are dormant most of the
 time. `idle_timeout` (off by default) stops a daemon after that many seconds
-without a file event, so a slot nobody is working in stops holding ~65 MB. A
-worktree hook or session start revives it.
+without a file event. Revival requires a separately configured supervisor or
+startup hook; the shipped SessionStart hook only checks freshness. Managed
+`woods-watch` rejects this setting because an idle child shutdown would leave
+automatic maintenance inactive until the owner restarts it.
 
 ```ruby
 Woods::Watch::Daemon.new(output_dir: …, idle_timeout: 900).run   # 15 minutes
@@ -813,8 +968,8 @@ supplies batches to it.
 
 ### Optional bounded context hints
 
-Context hints are a separate Claude Code opt-in, **unreleased after Woods
-2.0.0.beta2**. Verify `bundle exec woods-hook-context --help` in the installed
+Context hints are a separate Claude Code opt-in, **included in Woods `2.0.0`**.
+Verify `bundle exec woods-hook-context --help` in the installed
 application bundle before enabling `WOODS_HOOK_CONTEXT_ENABLED=1`. The plugin
 version alone does not establish gem support. `WOODS_HOOKS_DISABLED=1` disables
 both context and refresh; `WOODS_HOOKS_ENABLED` controls only the existing

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-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

@@ -421,6 +421,12 @@ module Woods
       def mode = @retriever.respond_to?(:mode) ? @retriever.mode : :semantic
       def default_budget = @retriever.respond_to?(:default_budget) ? @retriever.default_budget : 8000
 
+      # 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
+
       # 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

data/lib/woods/console/stdio_transport.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'mcp'
+
+module Woods
+  module Console
+    # Keeps protocol writes separate from the host application's stdout.
+    # The SDK still owns framing, negotiation, notifications and shutdown.
+    class StdioTransport < ::MCP::Server::Transports::StdioTransport
+      # @param server [::MCP::Server] Console server
+      # @param output [IO] Original stdout saved before redirecting Rails output
+      def initialize(server, output:)
+        super(server)
+        @output = output
+        @output.set_encoding(Encoding::UTF_8)
+      end
+
+      # SDK responses, notifications and server requests share this writer.
+      # @param message [String, Hash] Encoded JSON or a JSON-compatible message
+      # @return [IO] Flushed protocol output
+      def send_response(message)
+        @output.puts(message.is_a?(String) ? message : JSON.generate(message))
+        @output.flush
+      end
+    end
+  end
+end

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/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.