woods 2.0.0.beta4 → 2.0.1

data/lib/woods/watch/supervision_records.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Woods
+  module Watch
+    # Bounded readers and liveness correlation for persisted supervision records.
+    module SupervisionRecords
+      # Read bounded records without granting signal or writer-lock authority.
+      # @param index [String] published index root
+      # @return [Hash] supervision records with separately evaluated liveness
+      def self.read(index)
+        directory = File.join(index, SupervisionStatus::DIRECTORY)
+        return { records: [] } unless readable_directory?(directory)
+
+        names = Dir.each_child(directory).take(SupervisionStatus::MAX_SCAN + 1)
+        records = names.first(SupervisionStatus::MAX_SCAN).filter_map do |name|
+          read_record(File.join(directory, name)) if /\A[a-f0-9]{32}\.json\z/.match?(name)
+        end
+        records.sort_by! { |record| [record['alive'] ? 0 : 1, -Time.iso8601(record['updated_at']).to_f] }
+        correlate(records.first(SupervisionStatus::MAX_RECORDS), index)
+        truncated = names.size > SupervisionStatus::MAX_SCAN || records.size > SupervisionStatus::MAX_RECORDS
+        { records: records.first(SupervisionStatus::MAX_RECORDS), truncated: truncated }
+      rescue SystemCallError
+        { records: [] }
+      end
+
+      def self.readable_directory?(directory)
+        File.directory?(directory) && !File.symlink?(directory)
+      end
+      private_class_method :readable_directory?
+
+      def self.read_record(path)
+        bytes = bounded_read(path)
+        return unless bytes
+
+        record = JSON.parse(bytes)
+        return unless valid_record?(record, path)
+
+        age = Time.now - Time.iso8601(record['updated_at'])
+        record['alive'] = record['state'] != 'stopped' &&
+                          age.between?(-30, SupervisionStatus::STALE_AFTER) && local_alive?(record)
+        record
+      rescue SystemCallError, JSON::ParserError, TypeError, ArgumentError
+        nil
+      end
+      private_class_method :read_record
+
+      def self.bounded_read(path)
+        return if File.symlink?(path)
+
+        flags = File::RDONLY | File::NONBLOCK
+        flags |= File::NOFOLLOW if File.const_defined?(:NOFOLLOW)
+        bytes = File.open(path, flags) { |file| file.read(SupervisionStatus::MAX_BYTES + 1) if file.stat.file? }
+        bytes if bytes && bytes.bytesize <= SupervisionStatus::MAX_BYTES
+      end
+      private_class_method :bounded_read
+
+      def self.valid_record?(record, path)
+        record.is_a?(Hash) && record['version'] == 1 && record['launcher'] == File.basename(path, '.json') &&
+          SupervisionStatus::STATES.include?(record['state'])
+      end
+      private_class_method :valid_record?
+
+      def self.local_alive?(record)
+        unless record['host'] == Status.host_identity && record['pid'].is_a?(Integer) && record['pid'].positive?
+          return false
+        end
+
+        Process.kill(0, record['pid'])
+        true
+      rescue Errno::ESRCH
+        false
+      rescue Errno::EPERM
+        true
+      end
+      private_class_method :local_alive?
+
+      def self.correlate(records, index)
+        status = Status.new(output_dir: index)
+        daemon = status.read
+        daemon_alive = daemon.is_a?(Hash) && status.alive?
+        records.each do |record|
+          record['active_child'] = daemon_alive && matches_child?(record, daemon)
+        end
+      rescue SystemCallError, TypeError, NoMethodError
+        records.each { |record| record['active_child'] = false }
+      end
+      private_class_method :correlate
+
+      def self.matches_child?(record, daemon)
+        record['alive'] && record['child_pid'] == daemon['pid'] && record['host'] == daemon['host']
+      end
+      private_class_method :matches_child?
+    end
+  end
+end

data/lib/woods/watch/supervision_status.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'status'
+require_relative 'supervision_records'
+
+module Woods
+  module Watch
+    # Independent owner records: a parked duplicate cannot overwrite the
+    # daemon heartbeat or make incremental hooks defer to an inactive writer.
+    class SupervisionStatus
+      DIRECTORY = 'watch_supervisors'
+      MAX_RECORDS = 32
+      MAX_SCAN = 256
+      MAX_BYTES = 8192
+      STALE_AFTER = 30
+      STATES = %w[starting booting reconciling ready degraded retrying parked stopped].freeze
+      FIELDS = %i[state reason attempt child_pid retry_at].freeze
+
+      # @param index [String] application-resolved output directory
+      # @param token [String] unguessable launcher identity
+      def initialize(index:, token:)
+        raise ArgumentError, 'invalid launcher token' unless /\A[a-f0-9]{32}\z/.match?(token)
+
+        @token = token
+        @directory = File.join(index, DIRECTORY)
+        @path = File.join(@directory, "#{token}.json")
+      end
+
+      # @param fields [Hash] state, owned child, attempt and bounded reason
+      # @return [void]
+      def write(**fields)
+        validate_fields!(fields)
+        verify_ownership!
+        data = { version: 1, launcher: @token, pid: Process.pid, host: Status.host_identity,
+                 updated_at: Time.now.utc.iso8601 }.merge(fields)
+        bytes = JSON.generate(data)
+        raise ArgumentError, 'oversized supervision record' if bytes.bytesize > MAX_BYTES
+
+        AtomicFile.write(@path, bytes, mode: 0o644)
+        prune_stale
+      end
+
+      # @param index [String] published index root
+      # @return [Hash] bounded supervision diagnostics
+      def self.read(index)
+        SupervisionRecords.read(index)
+      end
+
+      def self.read_record(path)
+        SupervisionRecords.send(:read_record, path)
+      end
+      private_class_method :read_record
+
+      def self.local_alive?(record)
+        SupervisionRecords.send(:local_alive?, record)
+      end
+      private_class_method :local_alive?
+
+      private
+
+      def verify_ownership!
+        raise ArgumentError, 'invalid supervision directory' if File.symlink?(@directory)
+        return unless File.exist?(@path) || File.symlink?(@path)
+
+        previous = self.class.send(:read_record, @path)
+        return if previous && previous['pid'] == Process.pid && previous['host'] == Status.host_identity
+
+        raise ArgumentError, 'supervision record belongs to another owner'
+      end
+
+      def validate_fields!(fields)
+        valid = (fields.keys - FIELDS).empty? && STATES.include?(fields[:state]) &&
+                fields[:reason].is_a?(String) && /\A[a-z_]{1,80}\z/.match?(fields[:reason]) &&
+                fields[:attempt].is_a?(String) && /\A[a-f0-9]{32}\z/.match?(fields[:attempt])
+        raise ArgumentError, 'invalid supervision fields' unless valid
+      end
+
+      def prune_stale
+        records = self.class.read(File.dirname(@directory))[:records]
+        records.each do |record|
+          next unless expired?(record) && removable?(record)
+
+          path = File.join(@directory, "#{record['launcher']}.json")
+          current = self.class.send(:read_record, path)
+          stored = record.except('active_child')
+          File.unlink(path) if current == stored
+        end
+      rescue SystemCallError
+        nil
+      end
+
+      def expired?(record)
+        record['launcher'] != @token && !record['alive'] &&
+          Time.now - Time.iso8601(record['updated_at']) > STALE_AFTER
+      end
+
+      def removable?(record)
+        record['state'] == 'stopped' ||
+          (record['host'] == Status.host_identity && !self.class.send(:local_alive?, record))
+      end
+    end
+  end
+end

data/lib/woods/watch/supervisor.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require_relative 'managed_process'
+require_relative 'lifecycle'
+require_relative 'supervision_status'
+require_relative 'supervisor_reporting'
+
+module Woods
+  module Watch
+    # Foreground retry owner shared by Procfile and Puma installations.
+    # It never retries configuration conflicts or silently takes over ownership.
+    class Supervisor # rubocop:disable Metrics/ClassLength -- retry, park and shutdown share one foreground attempt state
+      include SupervisorReporting
+
+      RETRY_DELAYS = [1, 2, 4, 8, 16, 30].freeze
+
+      # @param command [Array<String>] fresh application invocation on each attempt
+      # @param root [String] application root
+      # @param env [Hash] application environment
+      # @param logger [#puts] diagnostic destination (stderr by default)
+      # @param boot_timeout [Numeric] pre-identity boot deadline
+      # @param shutdown_timeout [Numeric] graceful application shutdown
+      # @param retry_delays [Array<Numeric>] bounded retry schedule
+      # rubocop:disable-next Metrics/ParameterLists -- independently injectable process policy and diagnostics
+      def initialize(command:, root:, env: ENV.to_h, logger: $stderr, boot_timeout: 300,
+                     shutdown_timeout: 10, retry_delays: RETRY_DELAYS)
+        raise ArgumentError, 'WOODS_WATCH_IDLE_TIMEOUT must be unset for managed watching' unless
+          env['WOODS_WATCH_IDLE_TIMEOUT'].to_s.empty?
+
+        @command = command
+        @root = File.realpath(root)
+        @env = env
+        @logger = logger
+        @boot_timeout = boot_timeout
+        @shutdown_timeout = shutdown_timeout
+        @retry_delays = retry_delays
+        @token = SecureRandom.hex(16)
+        @attempts = @failures = 0
+        @stopping = false
+      end
+
+      # @return [String, nil] honest lifecycle state
+      attr_reader :state, :attempts
+
+      # @return [Integer] zero after owner-requested shutdown
+      def run
+        until @stopping
+          run_attempt
+          break if @stopping
+
+          reason = retry_reason
+          reason ? retry_after(reason) : park(@protocol.terminal || 'incompatible_or_stopped_task')
+        end
+        0
+      ensure
+        @process&.stop
+        publish('stopped', 'owner_stopped')
+      end
+
+      # Signal-safe request; process cleanup occurs on the run thread.
+      # @return [void]
+      def stop
+        @stopping = true
+      end
+
+      private
+
+      def run_attempt
+        prepare_attempt
+        @process.start
+        monitor_attempt
+      rescue ArgumentError => e
+        @invalid = true
+        @logger.puts("[woods-watch] incompatible lifecycle: #{e.message}")
+      ensure
+        @process&.stop
+      end
+
+      def prepare_attempt
+        retire_status
+        @attempts += 1
+        @attempt = SecureRandom.hex(16)
+        @invalid = @timed_out = false
+        @ready_at = nil
+        @started_at = monotonic
+        @protocol = Lifecycle.new(launcher: @token, attempt: @attempt, root: @root)
+        @process = ManagedProcess.new(command: @command, root: @root, env: @env, events: true,
+                                      launcher: @token, attempt: @attempt, shutdown_timeout: @shutdown_timeout)
+        publish('starting', 'boot_pending')
+      end
+
+      def monitor_attempt
+        loop do
+          consume_events
+          break if @stopping || @protocol.finished? || !@process.alive?
+
+          if !@protocol.booted? && monotonic - @started_at >= @boot_timeout
+            @timed_out = true
+            break
+          end
+          raise ArgumentError, 'lifecycle stream ended while task was running' if @process.eof?
+
+          heartbeat
+          sleep 0.05
+        end
+        consume_events
+      end
+
+      def consume_events
+        @process.read_events.each do |line|
+          record = @protocol.accept(line)
+          @status = SupervisionStatus.new(index: @protocol.index, token: @token) if record['event'] == 'identity'
+          track_readiness(record) if record['event'] == 'startup'
+          publish(@protocol.state, @protocol.reason) if @protocol.state && !%w[exit terminal].include?(record['event'])
+        end
+      end
+
+      def track_readiness(record)
+        @ready_at = record['state'] == 'ready' ? (@ready_at || monotonic) : nil
+      end
+
+      def retry_reason
+        return if parked_outcome?
+        return 'boot_timeout' if @timed_out
+        return 'restart_required' if @protocol.terminal == 'restart_required' && @protocol.exit_code == 75
+        return if [0, 127].include?(@protocol.exit_code)
+
+        'child_failed'
+      end
+
+      def parked_outcome?
+        @invalid || %w[already_running unsupported_environment].include?(@protocol.terminal)
+      end
+
+      def retry_after(reason)
+        @failures = 0 if @ready_at && monotonic - @ready_at >= 60
+        delay = @retry_delays.fetch([@failures, @retry_delays.size - 1].min)
+        @failures += 1
+        publish('retrying', reason, retry_at: (Time.now + delay).utc.iso8601)
+        wait_until(monotonic + delay)
+      end
+
+      def park(reason)
+        publish('parked', reason)
+        @logger.puts('[woods-watch] restart the owner after correcting configuration; no automatic takeover')
+        wait_until(Float::INFINITY)
+      end
+
+      def wait_until(deadline)
+        until @stopping || monotonic >= deadline
+          heartbeat
+          sleep 0.05
+        end
+      end
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/woods/watch/supervisor_reporting.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Woods
+  module Watch
+    # Publication and retirement of one launcher's diagnostic records.
+    module SupervisorReporting
+      private
+
+      def publish(state, reason, **details)
+        return unless state
+
+        reason ||= 'pending'
+        changed = @state != state || @reason != reason
+        @state = state
+        @reason = reason
+        @details = details
+        @logger.puts("[woods-watch] #{state}: #{reason || 'pending'} (attempt #{@attempts})") if changed
+        heartbeat(force: true)
+      end
+
+      def heartbeat(force: false)
+        return unless @status && heartbeat_due?(force)
+
+        @status.write(state: @state, reason: @reason, attempt: @attempt,
+                      child_pid: @process&.alive? ? @protocol.child_pid : nil, **(@details || {}))
+        @heartbeat_at = monotonic
+      rescue SystemCallError, ArgumentError => e
+        @logger.puts("[woods-watch] cannot write supervision status (#{e.class})")
+        @heartbeat_at = monotonic
+      end
+
+      def heartbeat_due?(force)
+        force || !@heartbeat_at || monotonic - @heartbeat_at >= 5
+      end
+
+      def retire_status
+        @status&.write(state: 'stopped', reason: 'attempt_finished', attempt: @attempt, child_pid: nil)
+      rescue SystemCallError, ArgumentError => e
+        @logger.puts("[woods-watch] cannot retire supervision status (#{e.class})")
+      ensure
+        @status = nil
+        @heartbeat_at = nil
+      end
+    end
+  end
+end

data/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "woods-plugin",
   "description": "Woods user guides for Claude Code: set up, upgrade, configure MCP servers for, investigate codebases with, enable a repository's agents on, and diagnose the Woods Rails code-intelligence gem.",
-  "version": "2.3.47",
+  "version": "2.3.54",
   "author": {
     "name": "lost-in-the"
   },

data/plugin/skills/woods-agent-enable/SKILL.md

@@ -23,7 +23,7 @@ and removal. Preserve manual setup for older installed versions.
 For concurrent configuration operations, wait for the active operation to
 finish and generate a fresh plan if the saved snapshots changed. Do not remove
 its lock or overwrite the other application's entry. Coordination across
-applications sharing user configuration is unreleased after `2.0.0.beta3`;
+applications sharing user configuration is included in Woods `2.0.0`;
 check the installed revision before relying on it.
 
 ## Preflight

data/plugin/skills/woods-diagnose/SKILL.md

@@ -36,26 +36,57 @@ bundle exec rails runner 'Rails.application.eager_load!; puts "eager load ok"'
 
 Use the application's normal Docker command and environment variables when applicable. Fix boot/eager-load failures before Woods.
 
+### Watcher setup cannot find already installed Rails or dependencies
+
+Compare normal task discovery with installer preflight in the same container and
+application environment. Early Git builds of the watcher installer stripped
+`BUNDLE_PATH` and `BUNDLE_APP_CONFIG`; Woods `2.0.0` includes the #540 fix.
+Record the loaded revision and bundle configuration source before
+reinstalling dependencies or writing a local bundle-path workaround. Follow the
+[watcher installation guide](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#managed-development-startup).
+
+### Puma cannot load the Woods plugin after switching branches
+
+Early generated guards checked only whether Woods was activated. An older gem
+can satisfy that check without providing `puma/plugin/woods.rb`. The #542 fix is
+included in Woods `2.0.0`: verify the loaded revision, then use a supporting
+bundle to preview and apply `bin/rails generate woods:watch --operation update
+--mode puma`. The updated guard checks the active gem's require paths, so older
+gems boot without a watcher. Repeating setup does not upgrade the guard. Follow
+the [owned setup runbook](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#ownership-updates-and-removal);
+do not change the owned directive or receipt manually.
+
 ### Watch repeatedly exits 75
 
+First identify the lifecycle owner. The raw task deliberately exits 75; a bare
+Foreman entry then stops all services. Managed `woods-watch`/Puma setup (#538)
+is included in Woods `2.0.0`: verify installed executable/generator help and
+loaded revision before proposing it. Supporting launchers retry boot failures,
+reject idle TTL, and park ownership/protocol conflicts until owner restart.
+Inspect separate supervision state rather than treating its parent PID as a
+healthy daemon. Before the first resolved index path, use launcher logs.
+Do not remove claims or kill PIDs from status to force takeover. See
+[startup diagnosis](https://github.com/lost-in-the/woods/blob/main/docs/TROUBLESHOOTING.md#watcher-startup-or-planned-restart-fails).
+
 Check the installed version's watch guide. Older releases, including
 `2.0.0.beta2`, can rediscover the same restart-trigger paths on every boot. Stop
 the supervisor, run one successful full extraction, then restart the standalone
 watch task. Do not assume automatic startup reconciliation exists in that release.
 For versions documenting environment-boot snapshots, confirm that the command is
-`bundle exec rake woods:watch`, with no preceding `environment` task, and check
+the application's actual `rails woods:watch` or `rake woods:watch` entrypoint,
+with no preceding `environment` task, and check
 whether boot inputs keep changing during initialization or catch-up.
 
 ### Watch retains facts from an initializer deleted while stopped
 
-Record the installed revision. Unreleased after `2.0.0.beta3`, startup preserves
+Record the installed revision. In Woods `2.0.0`, startup preserves
 registered deleted boot inputs as full-extraction obligations. On earlier builds,
 stop watch, run a successful full extraction in a fresh process, then restart
 standalone `woods:watch`. See the installed version's watch guide.
 
 ### A cleaned index directory still exists
 
-Unreleased after `2.0.0.beta3`, `woods:clean` retains the output directory and
+In Woods `2.0.0`, `woods:clean` retains the output directory and
 hidden extraction guard for concurrent writer coordination. Verify published
 artifacts are gone; do not remove that guard while writers may be running.
 
@@ -134,7 +165,7 @@ with `server.version`; missing/null is unknown, not a failure. A validator
 major-version warning calls for full extraction and upgrade review, while a match
 does not certify retained units were migrated. See [writer provenance](https://github.com/lost-in-the/woods/blob/main/docs/PUBLISHED_INDEX.md#manifest-writer-provenance).
 
-Unreleased after `2.0.0.beta3`: incremental/refresh handled source errors keep
+Included in Woods `2.0.0`: incremental/refresh handled source errors keep
 the previous generation active and leave watch batches pending. Repair the
 logged source error and retry the complete batch; see
 [handled source errors](https://github.com/lost-in-the/woods/blob/main/docs/INCREMENTAL_EXTRACTION.md#handled-source-errors-and-retry).
@@ -177,6 +208,24 @@ access with its `WOODS_GIT_DIR` setting. A failed history stream is discarded;
 repair git access and run full extraction to refresh retained metadata. See the
 [history contract](https://github.com/lost-in-the/woods/blob/main/docs/CONFIGURATION_REFERENCE.md#git-enrichment-history).
 
+If per-unit Git metadata is absent, check `git --version` inside the extraction
+process/container as well as repository access. Builds with #551 warn when Git
+cannot execute and a repository is expected; older versions may be silent.
+Source archives without a Git directory remain supported. `GIT_SHA` and
+structural `ready` do not certify history availability. After repairing Git,
+run full extraction; see the
+[missing-executable diagnostic](https://github.com/lost-in-the/woods/blob/main/docs/TROUBLESHOOTING.md#git-executable-is-missing-from-the-extraction-environment).
+
+For linked-worktree provenance/history mismatches, check the installed version's
+`WOODS_GIT_DIR` support and compare the selected branch and exact SHA inside the
+extraction environment. Mount the complete shared `.git` at its original path
+with no override, or select `/mounted-common/worktrees/<id>` within a relocated
+complete mount. Derive `<id>` from Git metadata, not the branch name. Selecting
+the shared root uses the primary checkout's HEAD and also changes incremental
+ranges. A commit alone may leave the source-file watcher idle; run full
+extraction after repair or when current Git history is required. See the
+[worktree mount guide](https://github.com/lost-in-the/woods/blob/main/docs/TROUBLESHOOTING.md#git-directory-mounts-for-linked-worktrees).
+
 After a bundle change or removal of a dynamically defined job, incremental
 extraction can retain stale runtime units. Use a fresh process with the updated
 bundle for full extraction, then validate. For missing external gem paths,
@@ -205,13 +254,13 @@ Compare the client config with the exact command, absolute `cwd`, bundle, and in
 bundle exec woods-mcp-start ./tmp/woods
 ```
 
-If startup says `Could not resolve a published Woods index` (unreleased after
-`2.0.0.beta3`) or names a missing `manifest.json` on older versions, first check
+If startup says `Could not resolve a published Woods index` (included in Woods
+`2.0.0`) or names a missing `manifest.json` on older versions, first check
 the selected index path: an atomic index uses `generation.json` to locate its
 payload manifest. The new headline does not change index validation or recovery.
 Point at an existing index before suggesting a new extraction. Prefer the
-explicit path above; `WOODS_DIR` is also supported. An unreleased change after
-`2.0.0.beta3` adds `WOODS_OUTPUT` after those two choices, so verify the installed
+explicit path above; `WOODS_DIR` is also supported. Woods `2.0.0` includes
+`WOODS_OUTPUT` after those two choices, so verify the installed
 version's configuration guide before relying on that fallback.
 
 Then reconnect through the MCP client and call `woods_status`. Use client-native tool inspection after initialization. Expect 14 packaged Index tools, not all conditional schemas.
@@ -253,6 +302,18 @@ paging alone only visits the discovered prefix. See the
 
 ## 4. Check semantic retrieval
 
+Do not treat structural `ready: true` or bootstrap `hydrated` as proof that
+embeddings exist. Check the installed reader's capabilities: builds with #549
+expose `woods_status.retriever.corpus`, including locally known vector and
+metadata record counts by type. Missing fields or `null` counts mean unknown,
+not zero. Counts include chunks and do not certify complete unit coverage.
+When both stores are known empty, supporting readers return `empty_index` with
+embed or explicit lexical-mode guidance. Follow the
+[corpus diagnostic contract](https://github.com/lost-in-the/woods/blob/main/docs/RETRIEVAL_GUIDE.md#semantic-corpus-diagnostics).
+Older readers need direct embedding-artifact checks; installing this plugin
+does not update the serving gem. Keep reader revision and index writer version
+separate when comparing results.
+
 Configured retrieval defaults (#446) are available in Woods `2.0.0.beta3`. For an installed
 version that supports them, an omitted tool budget uses the serving retriever's
 configured default; an explicit budget overrides it. Standalone MCP does not
@@ -296,6 +357,14 @@ endpoint to silence this warning.
 
 Console failures are live Rails/config/security failures, not Index failures. Verify authorized environment, Rails boot, `WOODS_CONSOLE_CONFIG` or direct `cwd`, blocked-table policy, credentials, and stderr.
 
+For stdio parse errors or response mismatches during tool calls, check for Rails
+logs on stdout. Through Woods `2.0.0.beta4`, stdout is restored after boot;
+configure the Console process's logger to use stderr or a file. Runtime stdout
+isolation is included in Woods `2.0.0`: verify a patched installed revision
+before relying on it. Prefer `bundle exec rake woods:console`; direct Rails
+runner invocation cannot capture output already emitted during Rails boot.
+See the [Console logging diagnosis](https://github.com/lost-in-the/woods/blob/main/docs/CONSOLE_MCP_SETUP.md#rails-logs-break-mcp-protocol).
+
 For MySQL SQL refusals, inspect the executing session's `sql_mode` and the installed version's Console guide. Do not change quote modes to bypass a security refusal.
 
 For SQLite SQL refusals on `2.0.0.beta4` or a reviewed revision containing its Console corrections, consult the installed Console guide for supported identifier and table-reference syntax. Simplify the query to supported syntax; never relax the blocked-table or function policy. These builds also check resolved default scopes and scan normalized response values. Confirm a patched gem is published before recommending it, and check the installed version’s canonical Console guide; do not infer release availability from this plugin.
@@ -391,3 +460,14 @@ the named file before moving it aside, or choose a new export directory. Older v
 byte-identical generated assets into `_woods/ownership.json`; changed legacy sidecars may need this
 manual recovery. Never fabricate ownership receipts or remove personal files to silence the error.
 See the installed version's `docs/OBSIDIAN_INTEGRATION.md` for the exact safety contract.
+
+### Console read compatibility on security-patch candidates
+
+Verify the loaded revision for corrections after 2.0.0. Active redaction refuses
+SQL relation/CTE column alias lists; typed EAV matching can intentionally mask
+extra values where tables share a final name or differ only by case. Keep the
+policy enabled and use explicit scalar columns or structured tools. Check exact
+sensitive-key spelling and configure binary secret columns for column redaction.
+Read the [Console compatibility guide](https://github.com/lost-in-the/woods/blob/main/docs/CONSOLE_MCP_SETUP.md#read-policy-compatibility)
+at the installed revision for adapter, timeout and projection limits; a plugin
+update does not patch Woods.

data/plugin/skills/woods-investigate/SKILL.md

@@ -16,7 +16,7 @@ Follow the [agent guide](https://github.com/lost-in-the/woods/blob/main/docs/AGE
 when instructions are absent. A registered tool does not establish retrieval
 readiness or authorize maintenance or live Console access.
 
-Call `woods_status` before relying on the index. Require a ready index with a current generation and non-zero counts for the types you need; use `codebase_retrieve` only when status reports retrieval enabled. If status is unhealthy or the generation predates the code under review, report that and ask the owner to run `woods:incremental` or `woods:extract` — do not present "not found" as proof the code does not exist.
+Call `woods_status` before relying on the index. Require a ready index with a current generation and non-zero counts for the types you need; verify the retrieval mode and its data before using `codebase_retrieve` (see Conceptual questions below). If status is unhealthy or the generation predates the code under review, report that and ask the owner to run `woods:incremental` or `woods:extract` — do not present "not found" as proof the code does not exist.
 
 ## The default loop
 
@@ -31,9 +31,9 @@ Identifiers are namespaced and typed; never invent one from a filename when `sea
 
 - **Code review / change impact**: `lookup` the changed unit, then `dependents` at depth 1 before going deeper. Group results by relationship type and layer; report direct dependents separately from inferred downstream impact. A graph edge is not test coverage — select tests from mappings and repository search.
 - **Audit / architecture assessment**: `graph_analysis` for orphans, dead ends, hubs, cycles, bridges, cross-database edges, volatile dependencies, and undeclared package edges; `domain_clusters` for architectural domains; `pagerank` for high-impact units worth reading first.
-- **Investigating behavior / debugging**: `trace_flow` from the user-visible entry point (route, controller action, job, mailer, service), `lookup` at ambiguous steps, and verify anything conditional or dynamically dispatched in source and tests — do not infer call order from a dependency edge.
+- **Investigating behavior / debugging**: find the exact indexed unit with `search` and `lookup`, then use `trace_flow` with `UnitIdentifier` or `UnitIdentifier#method` (for example, `CheckoutService#order`). Bare `order` names a unit, potentially a factory, rather than locating an application method. Receiverless local calls may remain unexpanded; inspect their source or trace the owning unit's method explicitly. Flow output is not proof of runtime execution or exhaustive call coverage. See the [flow workflow](https://github.com/lost-in-the/woods/blob/main/docs/AGENT_GUIDE.md#trace-a-feature-flow).
 - **Onboarding**: `structure` for the codebase overview, `lookup` and `dependencies`/`dependents` for a unit's neighborhood, and `domain_clusters` for the domain map, then the default loop on the units that matter.
-- **Conceptual questions**: `codebase_retrieve` when status says ready; govern with `budget` (never `limit`), then verify key units with `lookup`.
+- **Conceptual questions**: check retrieval mode and data before `codebase_retrieve`; structural `ready` alone does not establish semantic availability. On readers supporting #549, inspect `retriever.corpus`; missing or unknown counts require checking embedding artifacts. Govern with `budget` (never `limit`), then verify key units with `lookup`.
 
 ## Boundaries
 
@@ -60,12 +60,12 @@ PORO and library targets. No dependents or test-only dependents do not establish
 absence of production callers; check source before making that claim.
 
 The response `graph_coverage` notice, `total_is_exact` field, and human label
-`witness types unambiguous` (#470/#471) are unreleased after Woods `2.0.0.beta3`.
+`witness types unambiguous` (#470/#471) are included in Woods `2.0.0`.
 Verify the installed server version and actual response fields; this plugin does
 not add them. Apply these limits to older servers even without the notice.
 Supporting stdio and HTTP servers expose the paginated traversal payload in
 `structuredContent.data` independently of the text renderer (#481, also
-unreleased after `2.0.0.beta3`). Check the installed response; older default
+included in Woods `2.0.0`). Check the installed response; older default
 responses may carry only text. Do not pass an unsupported `format` argument.
 
 `total_is_exact: false` means a budget-limited prefix; a true value describes only
@@ -106,7 +106,7 @@ recorded reachability does not establish observed execution. See the
 
 Pass explicit `limit` and `offset` when paging `graph_analysis`. Enforcing the
 advertised default of 20 rows per section and preserving total/offset on last
-and empty pages (#519) are unreleased after `2.0.0.beta3`; check the installed
+and empty pages (#519) are included in Woods `2.0.0`; check the installed
 response rather than inferring support from the plugin version. On supporting
 servers, read `<section>_total` and `<section>_offset` in JSON, or the human
 pagination notice. An empty later page does not mean no findings. Totals count