woods 2.0.0.beta2 → 2.0.0.beta4

data/lib/woods/unblocked/exporter.rb

@@ -8,6 +8,7 @@ require_relative 'client'
 require_relative 'rate_limiter'
 require_relative 'document_builder'
 require_relative 'sync_manifest'
+require_relative '../export/typed_reader'
 
 module Woods
   module Unblocked
@@ -75,6 +76,7 @@ module Woods
 
         @client = client || Client.new(api_token: api_token, rate_limiter: limiter)
         @reader = reader || build_reader(index_dir)
+        @typed_reader = Export::TypedReader.new(@reader)
         # Cite the ref the index was actually extracted from. `main` was
         # hardcoded, so citations on a `master`-default repo pointed at a
         # branch that need not exist.
@@ -96,10 +98,11 @@ module Woods
       #
       # @return [Hash] { synced:, skipped:, deleted:, errors: }
       def sync_all
-        with_pinned_index do
+        prepared = false
+        with_prepared_index do
+          prepared = true
           @current_uris = Set.new
           @budget_exhausted = false
-          build_uri_index
           reconcile_from_remote if @manifest.empty?
 
           synced = 0
@@ -108,6 +111,7 @@ module Woods
 
           FULL_SYNC_TYPES.each do |type|
             break if @budget_exhausted
+            next if type.start_with?('graphql_') # the family already includes these actual types
 
             result = sync_type(type)
             synced += result[:synced]
@@ -124,11 +128,11 @@ module Woods
             errors.concat(result[:errors])
           end
 
-          deleted = @budget_exhausted ? 0 : purge_stale(errors)
+          deleted = @budget_exhausted || @ambiguous_uris.any? ? 0 : purge_stale(errors)
           { synced: synced, skipped: skipped, deleted: deleted, errors: cap_errors(errors) }
         end
       ensure
-        save_manifest
+        save_manifest if prepared
       end
 
       # Sync all units of a given type.
@@ -136,10 +140,12 @@ module Woods
       # @param type [String] Unit type (e.g. "model", "controller")
       # @return [Hash] { synced:, skipped:, errors: }
       def sync_type(type)
-        units = @reader.list_units(type: type)
-        log "  #{type}: #{units.size} units"
+        with_prepared_index do
+          units = units_for(type)
+          log "  #{type}: #{units.size} units"
 
-        sync_units(units)
+          sync_unit_data(units.map { |unit| [unit, unit] })
+        end
       end
 
       # Sync the top N most-connected units of a type (by dependent count).
@@ -148,35 +154,42 @@ module Woods
       # @param max_count [Integer] Maximum units to sync
       # @return [Hash] { synced:, skipped:, errors: }
       def sync_type_partial(type, max_count)
-        units = @reader.list_units(type: type)
-        return empty_stats if units.empty?
-
-        # Load full data to sort by dependent count
-        units_with_data = units.filter_map do |entry|
-          data = @reader.find_unit(entry['identifier'])
-          next unless data
-
-          dep_count = (data['dependents'] || []).size
-          { entry: entry, data: data, dep_count: dep_count }
+        with_prepared_index do
+          units = units_for(type)
+          units.each { |unit| track_uri(unit) }
+          top = units.sort_by { |unit| -(unit['dependents'] || []).size }.first(max_count)
+          log "  #{type}: #{top.size}/#{units.size} units (top by dependents)"
+          result = sync_unit_data(top.map { |unit| [unit, unit] })
+          result[:skipped] += units.size - top.size
+          result
         end
+      end
 
-        # Every unit of this type still exists — track its URI so partial units
-        # that fall *out* of the top-N are never mistaken for deletions.
-        units_with_data.each { |u| track_uri(u[:data]) }
-
-        top_units = units_with_data.sort_by { |u| -u[:dep_count] }.first(max_count)
-        # Count against what was actually synced — units.size includes entries
-        # whose unit data was missing (dropped by the filter_map above).
-        skipped_count = units.size - top_units.size
+      private
 
-        log "  #{type}: #{top_units.size}/#{units.size} units (top by dependents)"
+      # Complete preflight precedes all remote writes and destructive pruning.
+      # Nested sync methods share this snapshot; standalone methods pin as well.
+      def with_prepared_index
+        return yield if @prepared_index
 
-        result = sync_unit_data(top_units.map { |u| [u[:entry], u[:data]] })
-        result[:skipped] += skipped_count
-        result
+        with_pinned_index do
+          @published_units = @typed_reader.all
+          build_uri_index
+          @prepared_index = true
+          begin
+            yield
+          ensure
+            @prepared_index = false
+            @published_units = nil
+          end
+        end
       end
 
-      private
+      def units_for(type)
+        # The historical graphql family includes all four actual subtypes.
+        types = type == 'graphql' ? MCP::IndexReader::UNIT_TYPES_BY_DIR.fetch('graphql') : [type]
+        @published_units.select { |unit| types.include?(unit['type']) }
+      end
 
       # Run a multi-read export body against one index generation.
       #
@@ -197,36 +210,6 @@ module Woods
         @reader.with_pinned_generation(&block)
       end
 
-      def sync_units(units)
-        synced = 0
-        skipped = 0
-        errors = []
-
-        units.each do |entry|
-          unit_data = @reader.find_unit(entry['identifier'])
-          unless unit_data
-            skipped += 1
-            next
-          end
-
-          track_uri(unit_data)
-          if push_document(unit_data) == :skipped
-            skipped += 1
-          else
-            synced += 1
-          end
-        rescue Woods::Error => e
-          errors << "#{entry['identifier']}: #{e.message}"
-          break if note_budget_exhaustion(e)
-        rescue StandardError => e
-          # Include the class — "undefined method for nil" without it is
-          # unactionable in CI logs.
-          errors << "#{entry['identifier']}: #{e.class}: #{e.message}"
-        end
-
-        { synced: synced, skipped: skipped, errors: errors }
-      end
-
       def sync_unit_data(entries_with_data)
         synced = 0
         skipped = 0
@@ -256,6 +239,10 @@ module Woods
       #
       # @return [Symbol] :synced or :skipped
       def push_document(unit_data)
+        if @ambiguous_uris.include?(@builder.uri_for(unit_data))
+          raise ExtractionError,
+                "ambiguous export URI for #{unit_data['type']}:#{unit_data['identifier']} — push skipped"
+        end
         # No file_path → the URI falls back to the bare repo URL, which every
         # such unit would share: they'd overwrite each other remotely and
         # ping-pong the manifest hash forever. Skip them.
@@ -411,24 +398,26 @@ module Woods
         "#{base}?unit=#{URI.encode_www_form_component(unit_data['identifier'])}"
       end
 
-      # One cheap pass over the type indexes (entries already carry file_path,
-      # and read_index is cached) to find files that define more than one synced
-      # unit. For each such base URI, the lexically-smallest identifier — the
+      # Inspect the complete validated snapshot, including excluded types, for
+      # same-name cross-type collisions. For files with distinct synced names,
+      # the lexically-smallest identifier — the
       # outer/top-level class — keeps the bare URI; siblings are suffixed. Solo
       # files (the overwhelming majority) are absent from the map and unchanged,
       # so this introduces no churn for them.
       def build_uri_index
         groups = Hash.new { |h, k| h[k] = [] }
-        synced_types.each do |type|
-          @reader.list_units(type: type).each do |entry|
-            next unless entry['file_path']
+        @published_units.each do |unit|
+          next unless unit['file_path']
 
-            groups[@builder.uri_for(entry)] << entry['identifier']
-          end
+          groups[@builder.uri_for(unit)] << unit
         end
 
-        @uri_primary = groups.each_with_object({}) do |(uri, identifiers), primary|
-          unique = identifiers.uniq
+        @ambiguous_uris = groups.each_with_object(Set.new) do |(uri, units), ambiguous|
+          identities = units.map { |unit| [unit['identifier'], unit['type']] }.uniq
+          ambiguous << uri if identities.group_by(&:first).any? { |_, variants| variants.size > 1 }
+        end
+        @uri_primary = groups.each_with_object({}) do |(uri, units), primary|
+          unique = units.select { |unit| synced_types.include?(unit['type']) }.map { |unit| unit['identifier'] }.uniq
           primary[uri] = unique.min if unique.size > 1
         end
       end

data/lib/woods/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Woods
-  VERSION = '2.0.0.beta2'
+  VERSION = '2.0.0.beta4'
 end

data/lib/woods/watch/boot_snapshot.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative '../reload_policy'
+require_relative 'tree_scan'
+require_relative 'watcher'
+
+module Woods
+  module Watch
+    # Files observed before the watch task invokes Rails' environment task.
+    # This bounds environment initialization, not earlier Bundler/application
+    # loading. Hosts embedding the daemon may provide the same explicit boundary.
+    class BootSnapshot
+      def initialize(root:, policy: ReloadPolicy.new)
+        @root = File.expand_path(root.to_s)
+        @policy = policy
+        @files = scan
+      end
+
+      # True for unchanged files, including a carried path absent before and
+      # after boot. A deleted initializer must not demand another restart.
+      def covers?(path)
+        absolute = File.expand_path(path, @root)
+        @files[absolute] == fingerprint(absolute)
+      end
+
+      # Includes additions and deletions, even if another writer has advanced
+      # the index watermark while Rails was booting.
+      def changed_paths
+        current = scan
+        (@files.keys | current.keys).reject { |path| @files[path] == current[path] }
+      end
+
+      private
+
+      def scan
+        TreeScan.files(root: @root, ignored: Watcher::DEFAULT_IGNORED_DIRECTORIES).each_with_object({}) do |path, files|
+          next unless %i[restart reload].include?(@policy.classify(path.delete_prefix("#{@root}/")))
+
+          stamp = fingerprint(path)
+          files[path] = stamp if stamp
+        end
+      end
+
+      def fingerprint(path)
+        stat = File.stat(path)
+        [stat.ino, stat.size, stat.mtime, stat.ctime]
+      rescue Errno::ENOENT, Errno::ENOTDIR
+        nil
+      end
+    end
+  end
+end

data/lib/woods/watch/daemon.rb

@@ -9,9 +9,11 @@ require_relative '../reload_policy'
 require_relative 'status'
 require_relative 'tree_scan'
 require_relative 'watcher'
+require_relative 'boot_snapshot'
 require 'json'
 require 'set'
 require 'securerandom'
+require 'timeout'
 
 module Woods
   module Watch
@@ -138,6 +140,9 @@ module Woods
       # which most daemon cycles are (a single-file cycle is milliseconds).
       HEARTBEAT_SHUTDOWN_TIMEOUT = 2
 
+      # Native registration or a polling baseline must finish before catch-up.
+      WATCHER_STARTUP_TIMEOUT = 30
+
       # @return [Woods::Generation]
       attr_reader :generation
 
@@ -156,6 +161,9 @@ module Woods
       # @param lock [Woods::Coordination::PipelineLock, nil] writer lock for
       #   this index; built from {LOCK_NAME} when nil
       # @param catch_up [Boolean] reconcile changes that predate startup
+      # @param poll_interval [Float] finite, positive seconds between polling scans
+      # @param boot_snapshot [BootSnapshot, nil] captured before environment
+      #   initialization; permits full reconciliation of unchanged startup inputs
       # @param force_polling [Boolean] never use the `listen` backend — the
       #   right choice across a container bind mount, where native FS events
       #   do not propagate
@@ -166,7 +174,9 @@ module Woods
       def initialize(output_dir:, root: nil, extractor_factory: nil, reloader: nil, watcher: nil,
                      policy: ReloadPolicy.new, debounce: DEFAULT_DEBOUNCE,
                      full_extraction_threshold: DEFAULT_FULL_EXTRACTION_THRESHOLD,
-                     idle_timeout: nil, lock: nil, catch_up: true, force_polling: false, logger: nil)
+                     idle_timeout: nil, lock: nil, catch_up: true, force_polling: false,
+                     boot_snapshot: nil, poll_interval: Watcher::DEFAULT_POLL_INTERVAL, logger: nil)
+        @poll_interval = validated_poll_interval(poll_interval)
         @output_dir = output_dir.to_s
         @root = (root || (defined?(Rails) ? Rails.root : Dir.pwd)).to_s
         @extractor_factory = extractor_factory || -> { Woods::Extractor.new(output_dir: @output_dir) }
@@ -177,6 +187,7 @@ module Woods
         @full_extraction_threshold = full_extraction_threshold
         @idle_timeout = idle_timeout
         @catch_up = catch_up
+        @boot_snapshot = boot_snapshot
         @force_polling = force_polling
         @logger = logger || default_logger
         @generation = Generation.new(output_dir: @output_dir)
@@ -231,11 +242,19 @@ module Woods
       # @return [Hash] `{ action:, state:, generation:, reason:, count:,
       #   duration_ms: }`
       def process(paths = [])
+        process_batch(paths)
+      end
+
+      private
+
+      # Only the resident loop can discharge work covered by its explicit
+      # environment-boot snapshot. Direct #process calls remain conservative.
+      def process_batch(paths = [], startup: false)
         change_set = ChangeSet.new(paths: drain_with(paths), root: @root)
         cycle_completed = false
 
         begin
-          result = case required_action(change_set)
+          result = case required_action(change_set, startup: startup)
                    when :ignore then nothing_to_do
                    when :restart then require_restart(change_set)
                    when :reload then attempt_reload ? extract(change_set) : degraded_reload(change_set)
@@ -249,13 +268,20 @@ module Woods
           # shutdown's heartbeat.kill lands on a thread doing real work) would
           # otherwise lose the batch #drain_with already popped from @pending.
           # Every branch above that finishes normally already carries its own
-          # paths forward on failure (or intentionally doesn't, e.g. :restart);
+          # paths forward on failure or restart;
           # this only fires for the abnormal case none of them can catch.
           carry_forward(change_set) unless cycle_completed
         end
       end
 
-      private
+      def validated_poll_interval(value)
+        interval = Float(value)
+        unless interval.finite? && interval.positive?
+          raise ArgumentError, 'poll_interval (WOODS_WATCH_POLL_INTERVAL) must be finite and greater than zero'
+        end
+
+        interval
+      end
 
       # The watch loop proper, split from {#run} so the shutdown `ensure` —
       # publish `stopped`, persist carried paths — can only ever fire for a
@@ -273,11 +299,19 @@ module Woods
         @last_event_at = monotonic_now
         heartbeat = start_heartbeat
 
-        watcher_thread = launch_watcher do |paths|
-          enqueue(paths)
-          drain
+        # Watch immediately, but establish startup obligations before any
+        # callback can drain them. Live callbacks enqueue under a separate mutex.
+        watcher_thread = nil
+        @drain_mutex.synchronize do
+          watcher_thread = launch_watcher do |paths|
+            enqueue(paths)
+            drain
+          end
+          await_watcher_ready
+          catch_up unless @stop_reason
+          drain_cycles
+          @last_event_at = monotonic_now
         end
-        catch_up
         watcher_thread.join
         raise @watcher_failure if @watcher_failure
 
@@ -308,7 +342,7 @@ module Woods
         # plausibly) before reaching that line, and it must still happen
         # before #persist_pending — otherwise a watcher thread still draining
         # a batch races the shutdown snapshot of @pending.
-        watcher_thread&.join
+        watcher_thread&.join(HEARTBEAT_SHUTDOWN_TIMEOUT) || watcher_thread&.kill&.join
         stop_heartbeat(heartbeat)
         # Before #persist_pending, for the same reason the watcher join is: a
         # retry drain still running would race the shutdown snapshot of
@@ -346,9 +380,18 @@ module Woods
           start_watching(&on_change)
         rescue StandardError => e
           @watcher_failure = e
+        ensure
+          @watcher_ready << :finished
         end
       end
 
+      def await_watcher_ready
+        Timeout.timeout(WATCHER_STARTUP_TIMEOUT) { @watcher_ready.pop }
+        raise @watcher_failure if @watcher_failure
+      rescue Timeout::Error
+        raise WatcherError, 'watcher did not establish its baseline before the startup timeout'
+      end
+
       # @param heartbeat [Thread, nil]
       # @return [void]
       def stop_heartbeat(heartbeat)
@@ -363,8 +406,12 @@ module Woods
       # `:reload` by restarting, since extracting against constants that no
       # longer match their source is the thing the classification exists to
       # prevent.
-      def required_action(change_set)
-        action = @policy.classify_all(change_set.relative_paths)
+      def required_action(change_set, startup: false)
+        paths = change_set.absolute_paths
+        paths = paths.reject { |path| startup_covered?(path) } if startup
+        relative = ChangeSet.new(paths: paths, root: @root).relative_paths
+        action = @policy.classify_all(relative)
+        action = :reextract if action == :ignore && @startup_full
         return :restart if action == :reload && !@reloader.enabled?
 
         action
@@ -386,10 +433,14 @@ module Woods
 
       def reset_cycle_state
         @pending = Set.new
+        @startup_paths = Set.new
+        @live_paths = Set.new
+        @startup_full = false
         @pending_mutex = Mutex.new
         @stop_reason = nil
         @drain_mutex = Mutex.new
         @retry_thread = nil
+        @watcher_ready = Queue.new
       end
 
       # Wait out the debounce window so events that land during it join the
@@ -405,9 +456,12 @@ module Woods
       end
 
       # Merge a watcher batch into the pending set without processing it.
-      def enqueue(paths)
+      def enqueue(paths, startup: false)
         absolute = ChangeSet.new(paths: paths, root: @root).absolute_paths
-        @pending_mutex.synchronize { @pending.merge(absolute) }
+        @pending_mutex.synchronize do
+          @pending.merge(absolute)
+          @live_paths.merge(absolute) unless startup
+        end
         @last_event_at = monotonic_now
       end
 
@@ -457,7 +511,7 @@ module Woods
       def drain_cycles
         until pending_empty? || @stop_reason
           settle
-          result = process
+          result = process_batch(startup: true)
 
           if result[:action] == :restart
             # @watcher, not a captured local — start_watching's polling
@@ -529,7 +583,11 @@ module Woods
         return unless @catch_up
 
         carried = restore_pending
-        paths = (uncovered_paths + carried).uniq
+        paths = (uncovered_paths + carried + vanished_restart_paths).uniq
+        boot_changes = @boot_snapshot ? @boot_snapshot.changed_paths : []
+        enqueue(boot_changes) unless boot_changes.empty?
+        prepare_startup_reconciliation(paths)
+        paths |= boot_changes
         if paths.empty?
           return reconcile_deletions if stale_deletions?
 
@@ -537,17 +595,36 @@ module Woods
         end
 
         @logger.info("[Woods] watch: #{paths.size} path(s) changed before startup — catching up")
-        enqueue(paths)
+        enqueue(paths, startup: true)
         drain
       end
 
+      def prepare_startup_reconciliation(paths)
+        return unless @boot_snapshot
+
+        restart_paths = paths.select do |path|
+          set = ChangeSet.new(paths: [path], root: @root)
+          required_action(set) == :restart && @boot_snapshot.covers?(path)
+        end
+        @pending_mutex.synchronize do
+          @startup_paths.merge(restart_paths)
+          @startup_full = restart_paths.any?
+        end
+      end
+
+      def startup_covered?(path)
+        eligible = @pending_mutex.synchronize { @startup_paths.include?(path) && !@live_paths.include?(path) }
+        eligible && @boot_snapshot.covers?(path)
+      end
+
       # A file deleted while nothing was watching leaves no mtime for the scan
       # to see — {TreeScan} only walks files that exist — so a deletion-only
       # downtime would log "index is current" while ghost units survive. The
       # graph knows every path it attributed a unit to; any of those gone from
       # disk means the extractor's sweep has reconciling to do.
       #
-      # The daemon only *detects*; it does not name the paths. Naming them
+      # Except for boot inputs handled by vanished_restart_paths, the daemon
+      # only detects; it does not name the paths. Naming them
       # would put them in the change set, whose deletions are authoritative for
       # any unit type — and some registered paths are nominal (on Rails < 7.1,
       # `ActiveRecord::SchemaMigration` registers a convention path no app
@@ -555,9 +632,22 @@ module Woods
       # still produces. An empty-change-set run reaches the same ghosts through
       # the sweep, which carries the bounds that make it safe.
       def stale_deletions?
-        root_prefix = "#{@root}/"
+        vanished_registered_paths.any?
+      end
 
-        persisted_registered_paths.any? do |path|
+      # Deleted boot inputs have no mtime and are absent from a fresh snapshot.
+      # Preserve their restart obligation so a boot that already omitted them
+      # performs a full extraction. Do not promote nominal model paths to
+      # authoritative deletions, even when application reloading is disabled.
+      def vanished_restart_paths
+        vanished_registered_paths.select do |path|
+          @policy.classify(path.delete_prefix("#{@root}/")) == :restart
+        end
+      end
+
+      def vanished_registered_paths
+        root_prefix = "#{@root}/"
+        persisted_registered_paths.select do |path|
           path.start_with?(root_prefix) && !File.exist?(path)
         end
       end
@@ -759,7 +849,7 @@ module Woods
       # start at all (inotify exhaustion being the usual reason). A daemon that
       # costs some CPU beats one that silently never fires.
       def start_watching(&on_change)
-        @watcher.start(&on_change)
+        start_backend(&on_change)
       rescue WatcherError => e
         raise if @polling_fallback
 
@@ -769,8 +859,20 @@ module Woods
         # the output-directory feedback loop {#ignored_directories} exists to
         # break, on precisely the path a large tree reaches.
         @watcher = Watcher.build(
-          root: @root, ignored: ignored_directories, logger: @logger, force_polling: true
+          root: @root, ignored: ignored_directories, logger: @logger, force_polling: true,
+          poll_interval: @poll_interval
         )
+        start_backend(&on_change)
+      end
+
+      def start_backend(&on_change)
+        if @watcher.respond_to?(:ready_callback=)
+          @watcher.ready_callback = -> { @watcher_ready << :ready }
+        else
+          # Existing injected watchers own their startup contract. Built-in
+          # backends signal only after the actual baseline/registration.
+          @watcher_ready << :ready
+        end
         @watcher.start(&on_change)
       end
 
@@ -800,6 +902,7 @@ module Woods
       end
 
       def require_restart(change_set)
+        carry_forward(change_set)
         triggers = @policy.paths_requiring(change_set.relative_paths, :restart)
         reason = "restart required: #{triggers.first(5).join(', ')}"
         @logger.warn("[Woods] watch: #{reason}")
@@ -864,13 +967,7 @@ module Woods
       end
 
       def run_extraction(change_set, started)
-        # Count only paths that imply extraction work. Sixty edited markdown
-        # files plus one model is a one-model change, and reading it as a storm
-        # would trade a millisecond cycle for a full extraction.
-        actionable = actionable_count(change_set)
-        full = actionable > @full_extraction_threshold
-        log_storm(actionable) if full
-
+        full = full_extraction?(change_set)
         before = @generation.current.number
         extractor = @extractor_factory.call
         touched = if full
@@ -883,7 +980,7 @@ module Woods
         action = full ? :full : :incremental
         return unpublished(action, change_set, started) if wrote_without_publishing?(touched, before)
 
-        publish(action, change_set, touched, started)
+        finish_extraction(action, change_set, touched, started)
       rescue ScriptError, StandardError => e
         # Extraction failed, so nothing landed — the generation stays where it
         # was and the index keeps serving its last good state.
@@ -896,6 +993,28 @@ module Woods
                                      duration_ms: elapsed_ms(started))
       end
 
+      def full_extraction?(change_set)
+        if @startup_full
+          @logger.info('[Woods] watch: environment boot covers startup changes — full extraction')
+          return true
+        end
+
+        # Ignorable paths do not make a storm out of a single model edit.
+        actionable = actionable_count(change_set)
+        full = actionable > @full_extraction_threshold
+        log_storm(actionable) if full
+        full
+      end
+
+      def finish_extraction(action, change_set, touched, started)
+        result = publish(action, change_set, touched, started)
+        if action == :full
+          @startup_full = false
+          @pending_mutex.synchronize { @startup_paths.clear }
+        end
+        result
+      end
+
       def actionable_count(change_set)
         change_set.relative_paths.count { |path| @policy.classify(path) != :ignore }
       end
@@ -992,8 +1111,10 @@ module Woods
         return false if ENV['WOODS_IGNORE_WATCH'] == '1'
         return false unless @status.alive?
 
-        other = @status.read['pid']
-        return false if other.nil? || other.to_i == Process.pid
+        record = @status.read
+        other = record['pid']
+        return false if other.nil?
+        return false if same_claim_host?(record['host']) && other.to_i == Process.pid
 
         @logger.warn(
           "[Woods] a watch daemon (pid #{other}) is already maintaining #{@output_dir} — standing down. " \
@@ -1225,7 +1346,8 @@ module Woods
 
       def build_watcher
         @watcher = Watcher.build(
-          root: @root, ignored: ignored_directories, logger: @logger, force_polling: @force_polling
+          root: @root, ignored: ignored_directories, logger: @logger, force_polling: @force_polling,
+          poll_interval: @poll_interval
         )
       end
 

data/lib/woods/watch/listen_watcher.rb

@@ -15,6 +15,9 @@ module Woods
     # silent while files change under it. Hosts in that position should force
     # polling rather than trust this backend.
     class ListenWatcher
+      # 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 listen_class [Class] injectable for specs
@@ -50,6 +53,7 @@ module Woods
             on_change.call(batch) if batch.any?
           end
           @listener.start
+          @ready_callback&.call
         rescue StandardError => e
           # inotify watch exhaustion (ENOSPC) lands here, and it is the most
           # likely failure on a large tree. {Watcher.build}'s caller falls back