woods 2.0.0.beta2 → 2.0.0.beta4

data/lib/woods/watch/polling_watcher.rb

@@ -18,11 +18,14 @@ module Woods
     # is what keeps that bounded: skipping `.git`, `node_modules`, `tmp` and
     # friends takes a Rails app from "everything" to "the source tree".
     class PollingWatcher
+      # Optional daemon handshake; called once detection is established.
+      attr_writer :ready_callback
+
       # @param root [String, Pathname] directory to watch
       # @param ignored [Array<String>] directory names/prefixes to skip
       # @param interval [Float] seconds between scans
       # @param sleeper [#call] injected for specs, so they need not pass time
-      def initialize(root:, ignored: Watcher::DEFAULT_IGNORED_DIRECTORIES, interval: 1.0,
+      def initialize(root:, ignored: Watcher::DEFAULT_IGNORED_DIRECTORIES, interval: Watcher::DEFAULT_POLL_INTERVAL,
                      sleeper: ->(seconds) { sleep(seconds) })
         @root = root.to_s
         @ignored = ignored
@@ -47,6 +50,7 @@ module Woods
 
         @running = true
         primed_now?
+        @ready_callback&.call
 
         while @running
           @sleeper.call(@interval)

data/lib/woods/watch/status.rb

@@ -31,9 +31,10 @@ module Woods
       STATES = %i[running degraded stopped].freeze
 
       # A status record older than this is not believed, however healthy it
-      # claims to be. Generous relative to a debounce window, because an idle
-      # daemon only rewrites its status when something happens.
+      # claims to be. The daemon heartbeats every five minutes, including
+      # while idle, so this allows two missed heartbeats.
       STALE_AFTER = 900 # 15 minutes
+      MAX_FUTURE_SKEW = 30 # seconds of clock difference tolerated across hosts
 
       # @param output_dir [String, Pathname] index directory
       # @param clock [#call] returns the ISO8601 stamp for a write
@@ -86,31 +87,34 @@ module Woods
 
       # Is a daemon currently maintaining this index?
       #
-      # Three things have to hold, and each rules out a different way the
-      # status file lies: the state has to be one a live daemon writes, the
-      # recorded pid has to still exist (a `kill -9` leaves the file behind),
-      # and the record has to be recent (a machine that lost power leaves a
-      # `running` record with a pid some unrelated process now owns).
+      # Require a live state, a positive pid, and a recent timestamp. A local
+      # pid must still exist; foreign-host trust explicitly substitutes bounded
+      # heartbeat freshness for that uncheckable process evidence. A crashed
+      # foreign daemon can therefore remain believable until the record ages out.
       #
       # Callers use this to decide whether to do the work themselves — a
       # session-start hook that would otherwise run `woods:incremental` can
       # skip it when a daemon is already on the job.
       #
       # @param max_age [Numeric] seconds after which a record is disbelieved
+      # @param trust_foreign_host [Boolean] trust a fresh foreign-host record
+      #   without a local pid check; defaults to WOODS_WATCH_TRUST_FOREIGN_HOST=1
       # @return [Boolean]
-      def alive?(max_age: STALE_AFTER)
+      def alive?(max_age: STALE_AFTER, trust_foreign_host: ENV['WOODS_WATCH_TRUST_FOREIGN_HOST'] == '1')
         record = read
         return false unless %w[running degraded].include?(record['state'])
-        return false unless same_host?(record['host'])
-        return false unless process_alive?(record['pid'])
+        return false unless record['pid'].is_a?(Integer) && record['pid'].positive?
+        return false unless recent?(record['updated_at'], max_age)
+        return trust_foreign_host unless same_host?(record['host'])
 
-        recent?(record['updated_at'], max_age)
+        process_alive?(record['pid'])
       end
 
       # The identity a pid is only meaningful within.
       #
       # In a container the hostname defaults to the container id, so this
-      # changes exactly when the pid namespace does.
+      # usually changes with the pid namespace. Custom or reused hostnames
+      # cannot establish namespace identity.
       #
       # @return [String]
       def self.host_identity
@@ -128,8 +132,8 @@ module Woods
       # deployment. A container pid like 47 almost always exists on the host, so
       # a host hook would read `running` plus a live-looking pid plus a fresh
       # timestamp and stand down while nothing was covering it. Comparing the
-      # recorded host means a cross-namespace reader disbelieves the record
-      # rather than misreading it.
+      # recorded host keeps a cross-namespace reader from checking an unrelated
+      # local pid. Foreign records are rejected unless freshness trust is enabled.
       #
       # Records written before this field existed have no host; treat them as
       # same-host so an in-place upgrade does not declare a live daemon dead.
@@ -160,7 +164,8 @@ module Woods
       def recent?(iso8601, max_age)
         return false if iso8601.nil?
 
-        Time.parse(@clock.call) - Time.parse(iso8601) <= max_age
+        age = Time.iso8601(@clock.call) - Time.iso8601(iso8601)
+        age.between?(-MAX_FUTURE_SKEW, max_age)
       rescue ArgumentError, TypeError
         false
       end

data/lib/woods/watch/tree_scan.rb

@@ -50,14 +50,14 @@ module Woods
       def each_file(root:, ignored:, visited: nil, &block)
         base = root.to_s
         prefix = "#{base}/"
-        visited ||= Set.new
+        visited = (visited || Set.new).dup
         visited << real_dir(base)
 
         Find.find(base) do |path|
           next if path == base
 
           skip = skip?(path.delete_prefix(prefix), ignored)
-          Find.prune if visit_entry(path, skip, ignored, visited, &block) == :prune
+          Find.prune if visit_entry(path, skip, ignored, visited, root: base, &block) == :prune
         end
       rescue Errno::ENOENT
         # The root vanished mid-walk (a worktree removed under us). Nothing to
@@ -68,7 +68,7 @@ module Woods
       # Classify one entry and act on it.
       #
       # @return [Symbol, nil] `:prune` when the caller should not descend
-      def visit_entry(path, skip, ignored, visited, &block)
+      def visit_entry(path, skip, ignored, visited, root:, &block)
         # `Find` stats with `lstat`, so it neither descends a symlinked
         # directory nor reports one as a file — the entry would just vanish. A
         # full extraction globs, and `Dir.glob` *does* follow them, so leaving
@@ -76,7 +76,7 @@ module Woods
         # symlinked `app/models`, or a monorepo linking shared code in, simply
         # never produced an event.
         if symlinked_directory?(path)
-          descend_symlink(path, ignored, visited, &block) unless skip
+          descend_symlink(path, ignored, visited | directory_ancestors(path, root), &block) unless skip
           nil
         elsif File.directory?(path)
           skip ? :prune : nil
@@ -86,19 +86,27 @@ module Woods
         end
       end
 
-      # Walk a symlinked directory, once.
-      #
-      # The `visited` set is keyed on the *resolved* path, which is what makes
-      # this terminate: a link pointing at its own ancestor is an infinite tree
-      # to any walker that follows links naively, and two links pointing at one
-      # directory would otherwise yield every file under it twice — enough to
-      # make a change look like two changes to the caller diffing walks.
+      # Detect cycles along this logical traversal branch, not across siblings.
+      # Two aliases of one target are distinct extraction paths: suppressing
+      # one can leave only an ignored alias and hide the relevant app path.
+      # Find does not expose exit events for ordinary directories, so collect
+      # their ancestors at each symlink rather than retaining a global set.
+      def directory_ancestors(path, root)
+        ancestors = Set.new
+        directory = File.dirname(path)
+        loop do
+          ancestors << real_dir(directory)
+          break if directory == root || File.dirname(directory) == directory
+
+          directory = File.dirname(directory)
+        end
+        ancestors
+      end
+
       def descend_symlink(path, ignored, visited, &block)
         target = real_dir(path)
         return if target.nil? || visited.include?(target)
 
-        visited << target
-
         # Walk the *resolved* directory — `Find.find` lstats even the root it is
         # handed, so pointing it at the link itself yields the link and stops —
         # then rewrite each result back under the link. Callers compare these

data/lib/woods/watch/watcher.rb

@@ -27,6 +27,9 @@ module Woods
     # Every backend implements the same two methods: `start(&on_change)`,
     # which yields an array of absolute paths, and `stop`.
     module Watcher
+      # Seconds of sleep between polling scans.
+      DEFAULT_POLL_INTERVAL = 1.0
+
       # Directory names never worth watching. Scanning them is what makes a
       # polling watcher expensive, and a change inside one is never extraction
       # input.
@@ -52,7 +55,7 @@ module Woods
       # @param force_polling [Boolean] skip the listen backend entirely
       # @param logger [#info, #warn] where backend selection is reported
       # @return [#start, #stop]
-      def build(root:, ignored: DEFAULT_IGNORED_DIRECTORIES, poll_interval: 1.0,
+      def build(root:, ignored: DEFAULT_IGNORED_DIRECTORIES, poll_interval: DEFAULT_POLL_INTERVAL,
                 force_polling: false, logger: nil)
         force_polling ||= containerized?
 

data/lib/woods.rb

@@ -135,7 +135,7 @@ module Woods
                   :concurrent_extraction, :precompute_flows, :extract_navigation_edges, :enable_snapshots,
                   :session_tracer_enabled, :session_tracer_allow_production,
                   :session_store, :session_id_proc, :session_exclude_paths,
-                  :console_mcp_enabled, :console_mcp_path, :console_mcp_token,
+                  :console_mcp_enabled, :console_mcp_http_enabled, :console_mcp_path, :console_mcp_token,
                   :console_mcp_allowed_origins,
                   :console_redacted_columns,
                   :console_redacted_key_values, :console_embedded_read_tools,
@@ -147,13 +147,15 @@ module Woods
                   :unblocked_api_token, :unblocked_collection_id, :unblocked_repo_url,
                   :cache_store, :cache_options,
                   :dump_retention_count, :component_paths
-    attr_reader :embedding_model, :max_context_tokens, :similarity_threshold, :extractors, :pretty_json,
-                :context_format, :cache_enabled, :volatile_dependency_ratio,
+    attr_reader :retrieval_mode, :embedding_model, :max_context_tokens, :similarity_threshold, :extractors,
+                :pretty_json,
+                :context_format, :cache_enabled, :volatile_dependency_ratio, :volatile_dependency_limit_per_target,
                 :graph_cycle_limit, :graph_cycle_max_length,
                 :incremental_blast_radius_depth, :durable_payload_writes
 
     def initialize # rubocop:disable Metrics/MethodLength
       @output_dir = nil # Resolved lazily; Rails.root is nil at require time
+      @retrieval_mode = :semantic
       @embedding_model = 'text-embedding-3-small'
       @embedding_model_explicit = false
       @max_context_tokens = 8000
@@ -173,10 +175,13 @@ module Woods
       @session_id_proc = nil
       @session_exclude_paths = []
       @console_mcp_enabled = false
+      # Preserve existing HTTP setups. Stdio-only hosts explicitly disable
+      # HTTP while leaving the Console master switch enabled.
+      @console_mcp_http_enabled = true
       @console_mcp_path = '/mcp/console'
       # Accept token from config or env var. Nil by default — the railtie
-      # refuses to wire the middleware in production without a real token
-      # and only warns loudly in non-prod when unset.
+      # rejects production boot when HTTP Console is enabled without a real
+      # token, and warns in non-production. Stdio does not use this token.
       @console_mcp_token = ENV.fetch('WOODS_CONSOLE_MCP_TOKEN', nil)
       # Origins allowed to reach the embedded console MCP. Loopback only
       # by default; override in host initializers for tunneled or internal
@@ -209,6 +214,7 @@ module Woods
       @cache_options = {}     # { redis: client, cache: store, ttl: { embeddings: 86400, ... } }
       @dump_retention_count = 3
       @volatile_dependency_ratio = 3.0
+      @volatile_dependency_limit_per_target = nil
       @graph_cycle_limit = GraphAnalyzer::DEFAULT_CYCLE_LIMIT
       @graph_cycle_max_length = GraphAnalyzer::DEFAULT_CYCLE_MAX_LENGTH
       # nil = the unbounded transitive closure. See the setter for why the
@@ -255,6 +261,7 @@ module Woods
       @max_context_tokens = value
     end
 
+    # Deprecated compatibility setting; retrieval never applies this cutoff.
     # @param value [Numeric] Must be between 0.0 and 1.0 inclusive
     # @raise [ConfigurationError] if value is out of range or not numeric
     def similarity_threshold=(value)
@@ -265,6 +272,8 @@ module Woods
         raise ConfigurationError, "similarity_threshold must be between 0.0 and 1.0, got #{value.inspect}"
       end
 
+      warn '[woods] similarity_threshold is deprecated and does not filter retrieval results; ' \
+           'use explicit types/scopes and inspect returned ranking evidence instead.'
       @similarity_threshold = float_val
     end
 
@@ -317,6 +326,16 @@ module Woods
       @pretty_json = value
     end
 
+    # @param value [Symbol, String] semantic (default) or lexical
+    # @raise [ConfigurationError] if value is not a supported retrieval mode
+    def retrieval_mode=(value)
+      unless %w[semantic lexical].include?(value.to_s)
+        raise ConfigurationError, "retrieval_mode must be semantic or lexical, got #{value.inspect}"
+      end
+
+      @retrieval_mode = value.to_sym
+    end
+
     # @param value [Symbol] Must be one of :claude, :markdown, :plain, :json
     # @raise [ConfigurationError] if value is not a valid format
     def context_format=(value)
@@ -348,6 +367,16 @@ module Woods
       @volatile_dependency_ratio = value.to_f
     end
 
+    # Maximum volatile report edges per typed dependency, before the global
+    # report limit. `nil` preserves the unlimited default.
+    #
+    # @param value [Integer, nil] must be a positive Integer, or nil
+    # @raise [ConfigurationError] otherwise
+    def volatile_dependency_limit_per_target=(value)
+      @volatile_dependency_limit_per_target = validate_optional_positive_integer!(:volatile_dependency_limit_per_target,
+                                                                                  value)
+    end
+
     # How many distinct cycles {Woods::GraphAnalyzer#cycles} enumerates before
     # it stops. `nil` removes the cap and restores exhaustive enumeration.
     #
@@ -493,11 +522,8 @@ module Woods
     # @param output_dir [String] Override output directory
     # @return [Hash] Extraction results
     def extract!(output_dir: nil)
-      require_relative 'woods/extractor'
-
       dir = output_dir || configuration.output_dir
-      extractor = Extractor.new(output_dir: dir)
-      extractor.extract_all
+      with_extraction_writer(dir, &:extract_all)
     end
 
     # Perform incremental extraction
@@ -505,10 +531,23 @@ module Woods
     # @param changed_files [Array<String>] List of changed files
     # @return [Array<String>] Re-extracted unit identifiers
     def extract_changed!(changed_files)
+      with_extraction_writer(configuration.output_dir) { |extractor| extractor.extract_changed(changed_files) }
+    end
+
+    private
+
+    # One-shot public callers share the task/watch writer lock. Unlike a rake
+    # task, a library caller needs a typed timeout exception, not process exit.
+    def with_extraction_writer(output_dir)
       require_relative 'woods/extractor'
+      require_relative 'woods/rake_helpers'
 
-      extractor = Extractor.new(output_dir: configuration.output_dir)
-      extractor.extract_changed(changed_files)
+      RakeHelpers.woods_with_extraction_lock(output_dir, raise_on_timeout: true) do
+        extractor = Extractor.new(output_dir: output_dir)
+        result = yield extractor
+        extractor.raise_on_publication_failure!
+        result
+      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.0",
+  "version": "2.3.47",
   "author": {
     "name": "lost-in-the"
   },

data/plugin/hooks/adapters/normalize.jq

@@ -0,0 +1,15 @@
+def valid_string:
+  type == "string" and length > 0 and utf8bytelength <= 4096 and (contains("\u0000") | not);
+def invalid: error("Unsupported or malformed edit event; no refresh queued.");
+. as $input |
+if type != "object" then invalid
+elif $client == "claude" then
+  if .hook_event_name == "PostToolUse" and (["Write", "Edit", "MultiEdit"] | index($input.tool_name)) then
+    {version:1,root:.cwd,events:[{path:.tool_input.file_path,operation:"update"}]}
+  else invalid end
+elif $client == "opencode" and .version == 1 and .client == "opencode" then
+  {version:1,root:.root,events:.events}
+else invalid end
+| if (.root | valid_string) and (.root | startswith("/")) and (.events | type == "array" and length > 0 and length <= 1000)
+  and all(.events[]; type == "object" and (.path | valid_string) and (.operation as $operation | ["add","update","delete"] | index($operation)))
+  then .events |= (map({path,operation}) | unique_by(.path,.operation)) else invalid end

data/plugin/hooks/adapters/normalize.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'json'
+
+# Standalone stdlib fallback for hosts without jq; never loads the Woods bundle.
+module WoodsHookEvent
+  module_function
+
+  def string?(value)
+    value.is_a?(String) && !value.empty? && value.bytesize <= 4096 && !value.include?("\0") && value.valid_encoding?
+  end
+
+  def normalize(client, input)
+    raise ArgumentError unless input.is_a?(Hash)
+
+    root, events = client_event(client, input)
+    validate_envelope(root, events)
+
+    normalized = events.map { |event| normalize_event(event) }.uniq
+    { 'version' => 1, 'root' => root,
+      'events' => normalized.sort_by { |event| event.values_at('path', 'operation') } }
+  end
+
+  def validate_envelope(root, events)
+    raise ArgumentError unless string?(root) && root.start_with?('/')
+    raise ArgumentError unless events.is_a?(Array) && events.size.between?(1, 1000)
+  end
+
+  def client_event(client, input)
+    case client
+    when 'claude' then claude_event(input)
+    when 'opencode'
+      raise ArgumentError unless input['version'] == 1 && input['client'] == 'opencode'
+
+      [input['root'], input['events']]
+    else raise ArgumentError
+    end
+  end
+
+  def claude_event(input)
+    raise ArgumentError unless input['hook_event_name'] == 'PostToolUse' &&
+                               %w[Write Edit MultiEdit].include?(input['tool_name']) &&
+                               input['tool_input'].is_a?(Hash)
+
+    [input['cwd'], [{ 'path' => input.fetch('tool_input').fetch('file_path'), 'operation' => 'update' }]]
+  end
+
+  def normalize_event(event)
+    raise ArgumentError unless event.is_a?(Hash) && string?(event['path']) &&
+                               %w[add update delete].include?(event['operation'])
+
+    { 'path' => event['path'], 'operation' => event['operation'] }
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    puts JSON.generate(WoodsHookEvent.normalize(ARGV.fetch(0), JSON.parse($stdin.read(1_048_577))))
+  rescue JSON::ParserError, ArgumentError, KeyError, TypeError
+    warn '[Woods hooks] Unsupported or malformed edit event; no refresh queued.'
+    exit 1
+  end
+end

data/plugin/hooks/hooks.json

@@ -11,6 +11,16 @@
             "timeout": 600
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/woods-context.sh\" PostToolUse",
+            "timeout": 2
+          }
+        ]
       }
     ],
     "SessionStart": [
@@ -23,6 +33,16 @@
             "timeout": 20
           }
         ]
+      },
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/woods-context.sh\" SessionStart",
+            "timeout": 2
+          }
+        ]
       }
     ]
   }

data/plugin/hooks/woods-context.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Independently opt-in synchronous hints. The process deadline includes stdin,
+# bundle startup, index/cache preparation, source verification and state I/O.
+set -u
+[ "${WOODS_HOOKS_DISABLED:-0}" = 1 ] && exit 0
+[ "${WOODS_HOOK_CONTEXT_ENABLED:-0}" = 1 ] || exit 0
+case "${1:-}" in SessionStart|PostToolUse) ;; *) exit 0 ;; esac
+exec 3<&0
+capture_response() {
+  runner=""; timer=""
+  cleanup() {
+    [ -z "$runner" ] || kill -KILL -- "-$runner" 2>/dev/null || true
+    [ -z "$timer" ] || kill -KILL -- "-$timer" 2>/dev/null || true
+  }
+  trap cleanup EXIT
+  trap 'exit 1' INT TERM
+  set -m
+  command="${WOODS_HOOK_CONTEXT_COMMAND:-bundle exec woods-hook-context}"
+  ( $command "$1" ) <&3 2>/dev/null &
+  runner=$!
+  ( sleep 0.85; kill -KILL -- "-$runner" 2>/dev/null ) >/dev/null 2>&1 &
+  timer=$!
+  wait "$runner" 2>/dev/null
+  status=$?
+  cleanup
+  wait "$timer" 2>/dev/null || true
+  runner=""; timer=""
+  # Carry the producer status in-band: Bash 3.2 cannot wait on this
+  # process-substitution PID. Cleanup finishes before the final status frame.
+  printf '\n%s' "$status"
+}
+# Bash 3.2-compatible process substitution: buffer the bounded response until
+# EOF and successful producer exit. Never forward a timed-out partial envelope.
+exec 4< <(capture_response "$1")
+supervisor=$!
+trap 'kill -TERM "$supervisor" 2>/dev/null; exit 0' INT TERM
+response=""
+# <=2048 payload bytes + newline/status byte; one extra byte rejects overflow.
+LC_ALL=C IFS= read -r -d '' -n 2051 response <&4
+read_status=$?
+exec 4<&-
+if [ "$read_status" -ne 1 ]; then
+  kill -TERM "$supervisor" 2>/dev/null || true
+  exit 0
+fi
+case "$response" in *$'\n'0) response="${response%$'\n'0}" ;; *) exit 0 ;; esac
+wait "$supervisor" 2>/dev/null || true
+# One builtin write of an already complete <=2KiB envelope to the client pipe.
+printf '%s' "$response"
+exit 0