woods 2.0.0 → 2.1.0

data/lib/woods/watch/daemon.rb

@@ -10,6 +10,8 @@ require_relative 'status'
 require_relative 'tree_scan'
 require_relative 'watcher'
 require_relative 'boot_snapshot'
+require_relative 'catch_up'
+require_relative 'claim_lease'
 require 'json'
 require 'set'
 require 'securerandom'
@@ -110,7 +112,7 @@ module Woods
       # daemons that both pass {#another_daemon_alive?} before either has
       # published a status record would otherwise both proceed. See
       # {#claim_startup?}.
-      CLAIM_FILENAME = 'watch_claim.json'
+      CLAIM_FILENAME = ClaimLease::CLAIM
 
       # A daemon cycle is milliseconds; a manual full extraction is seconds to
       # minutes. This bounds how long a crashed writer can block the daemon.
@@ -423,7 +425,7 @@ module Woods
         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
+        action = :reextract if action == :ignore && reconciliation_required?
         return :restart if action == :reload && !@reloader.enabled?
 
         action
@@ -448,6 +450,7 @@ module Woods
         @startup_paths = Set.new
         @live_paths = Set.new
         @startup_full = false
+        @reconciliation_pending = false
         @pending_mutex = Mutex.new
         @stop_reason = nil
         @drain_mutex = Mutex.new
@@ -492,7 +495,12 @@ module Woods
       end
 
       def carry_forward(change_set)
-        @pending_mutex.synchronize { @pending.merge(change_set.absolute_paths) }
+        @pending_mutex.synchronize do
+          @pending.merge(change_set.absolute_paths)
+          # Deletion-only startup intentionally names no paths: its bounded
+          # sweep must not treat nominal framework paths as deleted sources.
+          @reconciliation_pending = true if change_set.empty?
+        end
       end
 
       # Run cycles until the pending set is empty. One call per watcher batch;
@@ -542,7 +550,11 @@ module Woods
       end
 
       def pending_empty?
-        @pending_mutex.synchronize { @pending.empty? }
+        @pending_mutex.synchronize { @pending.empty? && !@reconciliation_pending }
+      end
+
+      def reconciliation_required?
+        @pending_mutex.synchronize { @startup_full || @reconciliation_pending }
       end
 
       # Only a drained startup boundary (or a later recovery) can establish
@@ -613,24 +625,22 @@ module Woods
 
       # Reconcile changes that predate this daemon.
       #
-      # The generation file is rewritten as the last act of every successful
-      # extraction, so its mtime is "when this index was last known good".
-      # Anything modified since is uncovered, whoever made the change and
-      # whether or not a daemon was watching at the time. With no generation
-      # file at all there is no index, and every file is uncovered — which the
-      # storm threshold correctly turns into one full extraction.
+      # Capture precedes publication. CatchUp keeps edits in that interval
+      # visible, including those after the final source-verification scan.
       #
       # @return [void]
       def catch_up
         return unless @catch_up
 
         carried = restore_pending
-        paths = (uncovered_paths + carried + vanished_restart_paths).uniq
+        scan = catch_up_scan
+        paths = (scan.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)
+        prepare_startup_reconciliation(paths, rebuild: scan.rebuild?)
         paths |= boot_changes
         if paths.empty?
+          return extract(ChangeSet.new(paths: [], root: @root)) if @startup_full
           return reconcile_deletions if stale_deletions?
 
           return @logger.info('[Woods] watch: index is current at startup')
@@ -641,7 +651,8 @@ module Woods
         drain
       end
 
-      def prepare_startup_reconciliation(paths)
+      def prepare_startup_reconciliation(paths, rebuild: false)
+        @startup_full = rebuild
         return unless @boot_snapshot
 
         restart_paths = paths.select do |path|
@@ -650,7 +661,7 @@ module Woods
         end
         @pending_mutex.synchronize do
           @startup_paths.merge(restart_paths)
-          @startup_full = restart_paths.any?
+          @startup_full ||= restart_paths.any?
         end
       end
 
@@ -721,38 +732,11 @@ module Woods
       end
 
       def uncovered_paths
-        watermark = index_watermark
-        TreeScan.files(root: @root, ignored: ignored_directories)
-                .select { |path| uncovered?(path, watermark) }
+        catch_up_scan.paths
       end
 
-      def uncovered?(path, watermark)
-        return true if watermark.nil?
-
-        File.mtime(path).to_f > watermark
-      rescue SystemCallError
-        false
-      end
-
-      # When this index was last known good, or nil when there is no usable
-      # index — which the storm threshold turns into one full extraction.
-      #
-      # A dangling payload pointer counts as "no index" (INF-10). The marker
-      # can outlive the directory it names (a partial restore from a CI
-      # artifact, an external cleanup targeting the large directories), and
-      # {Generation#payload_dir} deliberately degrades to the index root for
-      # *readers* — so a gutted index would otherwise read "current at
-      # startup", publish `running`, and have every caller stand down over a
-      # directory holding no index at all. "Alive means covered" is the
-      # daemon's contract; here it would have been false.
-      #
-      # @return [Float, nil]
-      def index_watermark
-        return nil if dangling_payload_pointer?
-
-        File.mtime(@generation.path).to_f
-      rescue SystemCallError
-        nil
+      def catch_up_scan
+        CatchUp.new(root: @root, output_dir: @output_dir, ignored: ignored_directories)
       end
 
       # @return [Boolean] true when the marker names a payload directory that
@@ -1018,6 +1002,7 @@ module Woods
                   else
                     extractor.extract_changed(change_set.absolute_paths)
                   end
+        extractor.raise_on_publication_failure! if extractor.respond_to?(:raise_on_publication_failure!)
 
         action = full ? :full : :incremental
         return unpublished(action, change_set, started) if wrote_without_publishing?(touched, before)
@@ -1037,7 +1022,7 @@ module Woods
 
       def full_extraction?(change_set)
         if @startup_full
-          @logger.info('[Woods] watch: environment boot covers startup changes — full extraction')
+          @logger.info('[Woods] watch: startup coverage requires full extraction')
           return true
         end
 
@@ -1050,6 +1035,7 @@ module Woods
 
       def finish_extraction(action, change_set, touched, started)
         result = publish(action, change_set, touched, started)
+        @pending_mutex.synchronize { @reconciliation_pending = false }
         if action == :full
           @startup_full = false
           @pending_mutex.synchronize { @startup_paths.clear }
@@ -1071,8 +1057,10 @@ module Woods
       # previous index while the daemon says `running`. Not raising was right;
       # not noticing was not.
       #
-      # A no-op incremental deliberately does not bump, so this only fires when
-      # units were actually written.
+      # The extractor's explicit publication-error check above also covers
+      # payload changes with no touched units, such as withdrawing flows. Keep
+      # this fallback for injected extractors without that reporting method.
+      # A genuine no-op deliberately does not bump.
       def wrote_without_publishing?(touched, before)
         return false if touched != :all && Array(touched).empty?
 
@@ -1188,7 +1176,31 @@ module Woods
       def claim_startup?
         return true if ENV['WOODS_IGNORE_WATCH'] == '1' && !@conservative_claims
 
+        prepare_claim_lease if @conservative_claims
+        acquire_startup_claim
+      rescue ClaimLease::Unavailable, SystemCallError => e
+        raise unless @conservative_claims
+
+        @logger.warn("[Woods] watch: managed claim unavailable: #{e.message}")
+        false
+      ensure
+        close_unclaimed_lease
+      end
+
+      def close_unclaimed_lease
+        return if @claimed
+
+        @claim_lease&.close
+      end
+
+      def prepare_claim_lease
+        FileUtils.mkdir_p(@output_dir)
+        @claim_lease = ClaimLease.new(@output_dir)
+      end
+
+      def acquire_startup_claim
         with_claim_lock do
+          @claim_lease&.acquire
           3.times do
             return true if create_claim
             return false unless reclaim_if_stale
@@ -1203,11 +1215,13 @@ module Woods
       # pauses, B deletes S and publishes its live claim, A resumes and
       # unlinks B's claim, and both return as owners. An `flock` on a
       # sidecar file makes the whole loop one critical section; the kernel
-      # releases it if the holder dies. Where the filesystem refuses the
-      # lock (some network mounts) the loop runs unserialized, as before.
-      def with_claim_lock
+      # releases it if the holder dies. Managed startup refuses unavailable
+      # locks; raw startup retains its earlier unserialized fallback.
+      def with_claim_lock(&block)
+        return @claim_lease.coordinate(&block) if @claim_lease
+
         lock = open_claim_lock
-        yield
+        block.call
       ensure
         lock&.close
       end
@@ -1243,7 +1257,7 @@ module Woods
       # race this method exists to close.
       def create_claim
         FileUtils.mkdir_p(@output_dir)
-        content = JSON.generate(pid: Process.pid, host: Status.host_identity)
+        content = JSON.generate(pid: Process.pid, host: Status.host_identity, **(@claim_lease&.fields || {}))
         tmp_path = "#{claim_path}.tmp.#{Process.pid}.#{SecureRandom.hex(4)}"
         File.write(tmp_path, content)
         begin
@@ -1303,7 +1317,7 @@ module Woods
       # @return [String, nil] the claim file's current bytes, or nil if it
       #   doesn't exist
       def claim_bytes
-        File.read(claim_path)
+        @claim_lease ? @claim_lease.snapshot : File.read(claim_path)
       rescue Errno::ENOENT
         nil
       end
@@ -1313,12 +1327,12 @@ module Woods
       #   or already-vanished claim counts as stale too, since it cannot be a
       #   live daemon's claim
       def stale_claim?
-        record = JSON.parse(File.read(claim_path))
+        record = JSON.parse(claim_bytes)
         return false if @conservative_claims && !verifiable_managed_claim?(record)
         return true unless same_claim_host?(record['host'])
 
         !claim_pid_alive?(record['pid'])
-      rescue JSON::ParserError, SystemCallError
+      rescue JSON::ParserError, SystemCallError, TypeError
         !@conservative_claims
       end
 
@@ -1374,18 +1388,25 @@ module Woods
       def release_claim
         return unless @claimed
 
-        FileUtils.rm_f(claim_path) if own_claim?
+        if @claim_lease
+          @claim_lease.coordinate { FileUtils.rm_f(claim_path) if own_claim? }
+        elsif own_claim?
+          FileUtils.rm_f(claim_path)
+        end
+      ensure
+        @claim_lease&.close
         @claimed = false
       end
 
       # @return [Boolean] whether the claim on disk still records this process
       def own_claim?
-        record = JSON.parse(File.read(claim_path))
+        record = JSON.parse(claim_bytes)
+        return record.is_a?(Hash) && record['token'] == @claim_lease.token if @claim_lease
         return true unless record.is_a?(Hash)
 
         record['pid'] == Process.pid && same_claim_host?(record['host'])
-      rescue JSON::ParserError, SystemCallError
-        true
+      rescue JSON::ParserError, SystemCallError, TypeError, ClaimLease::Unavailable
+        !@claim_lease
       end
 
       def claim_path

data/lib/woods/watch/installation/options.rb

@@ -92,7 +92,7 @@ module Woods
 
         def validate_idle!
           value = @environment['WOODS_WATCH_IDLE_TIMEOUT']
-          return if mode == 'external' || value.nil? || value.empty?
+          return if mode == 'external' || value.to_s.strip.empty?
 
           raise Conflict, 'Unset WOODS_WATCH_IDLE_TIMEOUT; managed maintenance needs a resident child'
         end

data/lib/woods/watch/installation/receipt.rb

@@ -26,7 +26,12 @@ module Woods
         # @param expected [Hash] prior content fingerprint and mode
         # @return [void]
         def self.verify_file!(document, expected)
-          return if document.fingerprint == expected
+          actual = document.fingerprint
+          # Git records the owner's executable bit, not the checkout's umask.
+          # Plan snapshots separately retain exact modes for preview/apply drift.
+          same_content = actual.slice('sha256', 'exists') == expected.slice('sha256', 'exists')
+          same_executable = (actual.fetch('mode') & 0o100) == (expected.fetch('mode') & 0o100)
+          return if same_content && same_executable
 
           raise Conflict, "Owned watcher file was edited or removed: #{document.path}"
         end

data/lib/woods/watch/managed_child.rb

@@ -26,7 +26,7 @@ module Woods
         descriptor, launcher, attempt = values
         validate_environment!(descriptor, [launcher, attempt])
 
-        unless env['WOODS_WATCH_IDLE_TIMEOUT'].to_s.empty?
+        unless env['WOODS_WATCH_IDLE_TIMEOUT'].to_s.strip.empty?
           raise ArgumentError, 'WOODS_WATCH_IDLE_TIMEOUT must be unset for managed watching'
         end
 

data/lib/woods/watch/supervisor.rb

@@ -25,7 +25,7 @@ module Woods
       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?
+          env['WOODS_WATCH_IDLE_TIMEOUT'].to_s.strip.empty?
 
         @command = command
         @root = File.realpath(root)

data/lib/woods/watch/tree_scan.rb

@@ -2,6 +2,7 @@
 
 require 'find'
 require 'set'
+require 'woods/source_path_encoding'
 
 module Woods
   module Watch
@@ -48,12 +49,15 @@ module Woods
       # @yieldparam path [String] absolute path to a regular file
       # @return [void]
       def each_file(root:, ignored:, visited: nil, &block)
-        base = root.to_s
+        base = SourcePathEncoding.utf8(root)
+        return unless base
+
         prefix = "#{base}/"
         visited = (visited || Set.new).dup
         visited << real_dir(base)
 
         Find.find(base) do |path|
+          path = decoded_entry(path)
           next if path == base
 
           skip = skip?(path.delete_prefix(prefix), ignored)
@@ -65,6 +69,11 @@ module Woods
         nil
       end
 
+      # Prune before any string matching or descent into an undecodable entry.
+      def decoded_entry(path)
+        SourcePathEncoding.utf8(path) || Find.prune
+      end
+
       # Classify one entry and act on it.
       #
       # @return [Symbol, nil] `:prune` when the caller should not descend
@@ -126,7 +135,7 @@ module Woods
 
       # @return [String, nil] resolved path, or nil for a broken/looping link
       def real_dir(path)
-        File.realpath(path)
+        SourcePathEncoding.utf8(File.realpath(path))
       rescue SystemCallError
         nil
       end
@@ -147,6 +156,9 @@ module Woods
       # @param relative [String] path relative to the watched root
       # @return [Boolean] whether any segment is a dotfile Woods does not read
       def hidden?(relative)
+        relative = SourcePathEncoding.utf8(relative)
+        return true unless relative
+
         relative.split(File::SEPARATOR).any? { |segment| hidden_segment?(segment) }
       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.54",
+  "version": "2.3.71",
   "author": {
     "name": "lost-in-the"
   },

data/plugin/hooks/adapters/normalize.rb

@@ -55,8 +55,9 @@ 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
+    input = $stdin.binmode.read(1_048_577).force_encoding(Encoding::UTF_8)
+    puts JSON.generate(WoodsHookEvent.normalize(ARGV.fetch(0), JSON.parse(input)))
+  rescue JSON::ParserError, EncodingError, ArgumentError, KeyError, TypeError
     warn '[Woods hooks] Unsupported or malformed edit event; no refresh queued.'
     exit 1
   end

data/plugin/hooks/woods-input-rules.sh

@@ -111,6 +111,10 @@ woods_input_action() {
     case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
     return
   fi
+  if { { [[ "$path" != */tasks/* ]] && [[ "$path" != */generators/* ]] && { [[ "$path" == *.rb ]]; } && { [[ "$path" == lib/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
   if { { { [[ "$path" == *.rake ]]; } && { [[ "$path" == lib/tasks/* ]]; }; }; }; then
     case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
     return

data/plugin/hooks/woods-refresh.sh

@@ -21,18 +21,26 @@ if command -v jq >/dev/null 2>&1; then
     printf '[Woods hooks] Unsupported or malformed edit event; no refresh queued.\n' >&2; exit 0;
   }
 elif command -v ruby >/dev/null 2>&1; then
-  payload="$(ruby "$hook_dir/adapters/normalize.rb" "$client" <"$input_file")" || exit 0
+  payload="$(ruby -EUTF-8:UTF-8 "$hook_dir/adapters/normalize.rb" "$client" <"$input_file")" || exit 0
 else
   printf '[Woods hooks] jq or Ruby is required; no refresh queued.\n' >&2
   exit 0
 fi
 rm -f "$input_file"
 trap - EXIT TERM INT
+# JSON and client paths are UTF-8 regardless of the host process locale.
+# Keep malformed queue/input diagnostics bounded and free of event contents.
+ruby_json() {
+  ruby -EUTF-8:UTF-8 "$@" 2>/dev/null || {
+    printf '[Woods hooks] Invalid UTF-8 or JSON data; refresh not confirmed.\n' >&2
+    return 1
+  }
+}
 field() {
   if command -v jq >/dev/null 2>&1; then
     printf '%s' "$payload" | jq -ej '.root'
   else
-    printf '%s' "$payload" | ruby -rjson -e 'print JSON.parse($stdin.read).fetch("root")'
+    printf '%s' "$payload" | ruby_json -rjson -e 'print JSON.parse($stdin.read).fetch("root")'
   fi
 }
 cwd="$(field; printf .)"
@@ -50,7 +58,7 @@ event_fields() {
   if command -v jq >/dev/null 2>&1; then
     printf '%s' "$payload" | jq -j '.events[] | .operation,"\u0000",.path,"\u0000"'
   else
-    printf '%s' "$payload" | ruby -rjson -e 'JSON.parse($stdin.read).fetch("events").each { |e| print e.fetch("operation"), "\0", e.fetch("path"), "\0" }'
+    printf '%s' "$payload" | ruby_json -rjson -e 'JSON.parse($stdin.read).fetch("events").each { |e| print e.fetch("operation"), "\0", e.fetch("path"), "\0" }'
   fi
 }
 relevant=0
@@ -83,7 +91,7 @@ enqueue() {
   if command -v jq >/dev/null 2>&1; then
     jq -nc --arg path "$1" '{path:$path,operation:"update"}' >"$event.tmp" || return 1
   else
-    ruby -rjson -e 'puts JSON.generate(path: ARGV[0], operation: "update")' -- "$1" >"$event.tmp" || return 1
+    ruby_json -rjson -e 'puts JSON.generate(path: ARGV[0], operation: "update")' -- "$1" >"$event.tmp" || return 1
   fi
   mv "$event.tmp" "$event.json"
 }
@@ -92,7 +100,7 @@ event="$queue/$$.$RANDOM.$RANDOM"
 if command -v jq >/dev/null 2>&1; then
   printf '%s' "$payload" | jq -c --arg root "$cwd" '.events | map(.path |= (if startswith($root + "/") then ltrimstr($root + "/") else . end))' >"$event.tmp" || exit 0
 else
-  printf '%s' "$payload" | ruby -rjson -e 'v = JSON.parse($stdin.read); puts JSON.generate(v.fetch("events").map { |e| e.merge("path" => e.fetch("path").delete_prefix(ARGV.fetch(0) + "/")) })' -- "$cwd" >"$event.tmp" || exit 0
+  printf '%s' "$payload" | ruby_json -rjson -e 'v = JSON.parse($stdin.read); puts JSON.generate(v.fetch("events").map { |e| e.merge("path" => e.fetch("path").delete_prefix(ARGV.fetch(0) + "/")) })' -- "$cwd" >"$event.tmp" || exit 0
 fi
 mv "$event.tmp" "$event.json" || exit 0
 
@@ -144,7 +152,7 @@ encode_batch() {
   if command -v jq >/dev/null 2>&1; then
     jq -sc --arg output "$configured_output" '{version:1,output:$output,events:(map(if type == "array" then . else [.] end) | add)} | @base64' "${batch[@]}" | tr -d '"\n'
   else
-    ruby -rjson -rbase64 -e '
+    ruby_json -rjson -rbase64 -e '
       output = ARGV.shift
       print Base64.strict_encode64(JSON.generate(version: 1, output: output,
         events: ARGV.flat_map { |path| value = JSON.parse(File.read(path)); value.is_a?(Array) ? value : [value] }))
@@ -237,7 +245,7 @@ while :; do
     if command -v jq >/dev/null 2>&1; then
       event_count="$(jq 'if type == "array" then length else 1 end' "$candidate")" || break
     else
-      event_count="$(ruby -rjson -e 'v = JSON.parse(File.read(ARGV[0])); puts(v.is_a?(Array) ? v.size : 1)' "$candidate")" || break
+      event_count="$(ruby_json -rjson -e 'v = JSON.parse(File.read(ARGV[0])); puts(v.is_a?(Array) ? v.size : 1)' "$candidate")" || break
     fi
     [ "$((batch_events + event_count))" -le 1000 ] || break
     [ "$((batch_bytes + event_bytes))" -le 49152 ] || break

data/plugin/hooks/woods-session-start.sh

@@ -11,9 +11,59 @@ field() {
   if command -v jq >/dev/null 2>&1; then
     printf '%s' "$1" | jq -r --arg name "$2" '.[$name] // empty' 2>/dev/null
   elif command -v ruby >/dev/null 2>&1; then
-    printf '%s' "$1" | ruby -rjson -e 'print JSON.parse($stdin.read).fetch(ARGV[0], "")' -- "$2" 2>/dev/null
+    printf '%s' "$1" | ruby -EUTF-8:UTF-8 -rjson -e 'print JSON.parse($stdin.read).fetch(ARGV[0], "")' -- "$2" 2>/dev/null
   fi
 }
+unavailable_summary() {
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$1" | jq -r '.unavailable | select(type == "object") |
+      select(.reason == "source_manifest_too_large" and (.size_bytes | type) == "number" and
+             (.limit_bytes | type) == "number") |
+      select(.size_bytes > .limit_bytes and .limit_bytes > 0) |
+      "source_manifest_too_large; \(.size_bytes) bytes; limit \(.limit_bytes)"' 2>/dev/null
+  elif command -v ruby >/dev/null 2>&1; then
+    printf '%s' "$1" | ruby -EUTF-8:UTF-8 -rjson -e '
+      value = JSON.parse($stdin.read)["unavailable"]
+      if value.is_a?(Hash) && value["reason"] == "source_manifest_too_large"
+        size, limit = value.values_at("size_bytes", "limit_bytes")
+        if [size, limit].all?(Integer) && size > limit && limit > 0
+          print "source_manifest_too_large; #{size} bytes; limit #{limit}"
+        end
+      end
+    ' 2>/dev/null
+  fi
+}
+source_advice() {
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$1" | jq -r 'if (.recommendations | type) == "array" then
+      .recommendations[] | select(. == "deep_check" or . == "fresh_capture" or . == "inspect_source_scan")
+      else empty end' 2>/dev/null
+  elif command -v ruby >/dev/null 2>&1; then
+    printf '%s' "$1" | ruby -EUTF-8:UTF-8 -rjson -e '
+      values = JSON.parse($stdin.read)["recommendations"]
+      allowed = %w[deep_check fresh_capture inspect_source_scan]
+      puts values.select { |value| allowed.include?(value) } if values.is_a?(Array)
+    ' 2>/dev/null
+  fi
+}
+unknown_message() {
+  local advice action
+  advice="$(source_advice "$1")"
+  if [ -z "$advice" ]; then
+    echo 'Woods source freshness is unknown: this generation lacks complete verified source evidence. Inspect woods_status; use woods-extract full for a fresh capture.'
+    return
+  fi
+  printf '%s' 'Woods source freshness is unknown: this check could not verify the current source contents.'
+  # Only the three literal identifiers above reach this word split.
+  for action in $advice; do
+    case "$action" in
+      deep_check) printf '%s' ' Request woods_status with source_check: deep; the quick reader reached its time limit.' ;;
+      fresh_capture) printf '%s' ' Fix the capture or boot evidence reported by woods_status, then run woods-extract full in the application environment.' ;;
+      inspect_source_scan) printf '%s' ' Inspect woods_status verification_reasons, source mapping, permissions and scan limits.' ;;
+    esac
+  done
+  printf '\n'
+}
 cwd="$(field "$payload" cwd)"
 [ -n "$cwd" ] && [ -d "$cwd" ] || exit 0
 configured_output="${WOODS_OUTPUT:-tmp/woods}"
@@ -25,7 +75,10 @@ esac
 if command -v jq >/dev/null 2>&1; then
   encoded="$(jq -nr --arg output "$configured_output" '{output:$output,mode:"quick"} | @base64')"
 elif command -v ruby >/dev/null 2>&1; then
-  encoded="$(ruby -rjson -rbase64 -e 'print Base64.strict_encode64(JSON.generate(output: ARGV[0], mode: "quick"))' -- "$configured_output")"
+  encoded="$(ruby -EUTF-8:UTF-8 -rjson -rbase64 -e 'print Base64.strict_encode64(JSON.generate(output: ARGV[0], mode: "quick"))' -- "$configured_output" 2>/dev/null)" || {
+    echo 'Woods source freshness is unknown: hook options could not be encoded. Inspect woods_status.'
+    exit 0
+  }
 else
   exit 0
 fi
@@ -63,7 +116,11 @@ status="$(tail -n 1 "$record")"
 state="$(field "$status" state)"
 case "$state" in
   current) ;;
+  unavailable)
+    detail="$(unavailable_summary "$status")"
+    printf 'Woods source freshness is unavailable: %s. The code index is usable; inspect woods_status. Repeating a full extraction will not reduce this size.\n' "${detail:-inspect woods_status for the unavailable evidence reason}"
+    ;;
   drifted) echo 'Woods source freshness is drifted: indexed application inputs differ from the working tree. Run woods-extract full, or inspect woods_status before choosing a targeted refresh.' ;;
-  *) echo 'Woods source freshness is unknown: this generation lacks complete verified source evidence. Inspect woods_status; use woods-extract full for a fresh capture.' ;;
+  *) unknown_message "$status" ;;
 esac
 exit 0