woods 2.0.0.beta2 → 2.0.0.beta3

data/plugin/hooks/woods-post-edit.sh

@@ -1,226 +1,3 @@
 #!/usr/bin/env bash
-# Woods PostToolUse hook (#280): after an edit to a graph-changing path,
-# refresh the index with `woods:incremental` in the background.
-#
-# Reads `cwd` from the hook payload, not CLAUDE_PROJECT_DIR, so a session in
-# a linked worktree refreshes that worktree's own index. Runs only when an
-# index already exists there. `woods:incremental` stands down under a
-# running watch daemon and takes the extraction lock itself; the lock here
-# only stops this hook from queueing one rake process per keystroke.
-#
-# Opt-in: this hook is shipped disabled. It does nothing until
-# WOODS_HOOKS_ENABLED=1 is set (see docs/WATCH_DAEMON.md and the woods-setup
-# skill for where to set it). WOODS_HOOKS_DISABLED=1 turns it back off even
-# after it has been enabled, without touching the enable setting.
-#
-# Lock contention must not drop an edit. A hook invocation that finds the
-# run lock busy appends its path to hook-pending.txt and returns immediately
-# instead of waiting; whichever invocation is holding the run lock drains
-# that file in a loop, passing every path collected on each drain as one
-# CHANGED_FILES batch, until a drain comes back empty. The one narrow gap
-# this leaves: an append that lands after the holder's last (empty) drain
-# but before it releases the run lock sits in the file, unprocessed, until
-# the next graph-changing edit triggers a hook that both appends it and
-# then wins the now-free run lock itself. That edit is delayed, not lost,
-# and the SessionStart hook's staleness warning is the backstop for it.
-#
-# The mkdir-based lock fallback has no kernel-enforced release: a `flock`
-# held by a killed process is freed automatically, but a lock *directory*
-# a killed process made is not. A hook killed mid-drain (OOM, a `kill -9`,
-# the host restarting) leaves `hook.lock.d` or `hook-pending.lock.d` behind
-# forever, so every later hook either skips draining permanently (the run
-# lock) or spins until the 600s hook timeout on every single invocation
-# (the pending lock, which blocks). Both lock directories are therefore
-# reclaimed once their mtime is older than WOODS_HOOK_LOCK_STALE_SECONDS: a
-# fresh lock directory is still respected as busy.
-#
-# Knobs:
-#   WOODS_HOOK_RAKE      command prefix, default "bundle exec rake"
-#                        (Docker: "docker compose exec -T app bundle exec rake")
-#   WOODS_OUTPUT         index directory override, same variable
-#                        woods:incremental/woods:watch_status already read;
-#                        default tmp/woods under the payload's cwd
-#   WOODS_HOOKS_ENABLED  set to 1 to turn the hook on
-#   WOODS_HOOKS_DISABLED set to 1 to turn it back off
-#   WOODS_HOOK_LOCK_STALE_SECONDS
-#                        age (mtime) after which a leftover mkdir-based lock
-#                        directory is reclaimed instead of respected as busy;
-#                        default 1800 (a few multiples of the 600s hook
-#                        timeout). Only the mkdir fallback needs this;
-#                        flock has no equivalent problem.
-set -u
-
-[ "${WOODS_HOOKS_DISABLED:-0}" = "1" ] && exit 0
-[ "${WOODS_HOOKS_ENABLED:-0}" = "1" ] || exit 0
-
-payload="$(cat)"
-
-# $1: dotted key path. Prefers jq, falls back to ruby, else gives up quietly.
-field() {
-  if command -v jq >/dev/null 2>&1; then
-    printf '%s' "$payload" | jq -r ".$1 // empty"
-  elif command -v ruby >/dev/null 2>&1; then
-    printf '%s' "$payload" | ruby -rjson -e '
-      value = JSON.parse($stdin.read)
-      ARGV[0].split(".").each { |key| value = value.is_a?(Hash) ? value[key] : nil }
-      print value.to_s' -- "$1"
-  else
-    printf ''
-  fi
-}
-
-cwd="$(field cwd)"
-file="$(field tool_input.file_path)"
-[ -z "$cwd" ] && exit 0
-[ -z "$file" ] && exit 0
-
-# Same no-boot resolution woods:watch_status uses: an explicit WOODS_OUTPUT
-# wins outright (absolute or relative to cwd), otherwise tmp/woods under cwd.
-# This is the config's own override knob, not a second hardcoded path.
-configured_output="${WOODS_OUTPUT:-tmp/woods}"
-case "$configured_output" in
-  /*) tmp_dir="$configured_output" ;;
-  *) tmp_dir="$cwd/$configured_output" ;;
-esac
-
-[ -f "$tmp_dir/generation.json" ] || exit 0
-
-case "$file" in
-  "$cwd"/*) rel="${file#"$cwd"/}" ;;
-  /*) exit 0 ;;
-  *) rel="$file" ;;
-esac
-
-case "$rel" in
-  app/models/*|config/routes.rb|config/routes/*|db/migrate/*|db/*_migrate/*|db/schema.rb|db/structure.sql|package.yml|*/package.yml|packwerk.yml) ;;
-  *) exit 0 ;;
-esac
-
-rake="${WOODS_HOOK_RAKE:-bundle exec rake}"
-log="$tmp_dir/hook.log"
-pending_file="$tmp_dir/hook-pending.txt"
-pending_lock="$tmp_dir/hook-pending.lock"
-pending_lock_dir="$tmp_dir/hook-pending.lock.d"
-run_lock="$tmp_dir/hook.lock"
-run_lock_dir="$tmp_dir/hook.lock.d"
-
-mkdir -p "$tmp_dir" 2>/dev/null || true
-
-have_flock() { command -v flock >/dev/null 2>&1; }
-
-# mtime of a directory in epoch seconds, GNU stat then BSD stat, empty if
-# neither exists (treated as "not stale": fail closed, keep waiting rather
-# than reclaim on a guess).
-dir_mtime() {
-  stat -c %Y "$1" 2>/dev/null || stat -f %m "$1" 2>/dev/null
-}
-
-# True when $1 is an mkdir-based lock directory old enough that it can only
-# be a crash leftover, never a legitimately still-running hook (a hook run
-# is one rake invocation, bounded by the 600s hook timeout).
-lock_dir_stale() {
-  mtime="$(dir_mtime "$1")"
-  [ -z "$mtime" ] && return 1
-  now="$(date +%s)"
-  age=$((now - mtime))
-  [ "$age" -gt "${WOODS_HOOK_LOCK_STALE_SECONDS:-1800}" ]
-}
-
-# Blocking mkdir-based lock acquire: waits for $1, reclaiming it once stale
-# rather than waiting for a crashed holder that will never release it.
-acquire_mkdir_lock() {
-  while ! mkdir "$1" 2>/dev/null; do
-    if lock_dir_stale "$1"; then
-      rmdir "$1" 2>/dev/null || true
-      continue
-    fi
-    sleep 0.1
-  done
-}
-
-release_mkdir_lock() {
-  rmdir "$1" 2>/dev/null || true
-}
-
-# Non-blocking mkdir-based lock attempt: one reclaim retry when stale, no
-# wait otherwise (contention here means "someone else is already draining,"
-# not "someone crashed").
-try_acquire_mkdir_lock() {
-  mkdir "$1" 2>/dev/null && return 0
-  if lock_dir_stale "$1"; then
-    rmdir "$1" 2>/dev/null || true
-    mkdir "$1" 2>/dev/null && return 0
-  fi
-  return 1
-}
-
-# Append one path to the pending file. Blocking: the critical section is a
-# single append, so any wait here is brief regardless of who else holds it.
-append_pending() {
-  if have_flock; then
-    exec 7>"$pending_lock"
-    flock 7
-    printf '%s\n' "$1" >>"$pending_file"
-    flock -u 7
-    exec 7>&-
-  else
-    acquire_mkdir_lock "$pending_lock_dir"
-    printf '%s\n' "$1" >>"$pending_file"
-    release_mkdir_lock "$pending_lock_dir"
-  fi
-}
-
-# Print and clear whatever is currently pending, empty output if nothing is.
-drain_pending() {
-  if have_flock; then
-    exec 7>"$pending_lock"
-    flock 7
-    if [ -s "$pending_file" ]; then
-      cat "$pending_file"
-      : >"$pending_file"
-    fi
-    flock -u 7
-    exec 7>&-
-  else
-    acquire_mkdir_lock "$pending_lock_dir"
-    if [ -s "$pending_file" ]; then
-      cat "$pending_file"
-      : >"$pending_file"
-    fi
-    release_mkdir_lock "$pending_lock_dir"
-  fi
-}
-
-run_incremental() {
-  # A drain can return several paths at once; CHANGED_FILES takes a
-  # comma-separated list (see lib/tasks/woods.rake).
-  changed="$(printf '%s\n' "$1" | tr '\n' ',' | sed 's/,$//')"
-  # shellcheck disable=SC2086
-  ( cd "$cwd" && CHANGED_FILES="$changed" $rake woods:incremental ) >>"$log" 2>&1
-}
-
-drain_until_empty() {
-  while :; do
-    batch="$(drain_pending)"
-    [ -z "$batch" ] && break
-    run_incremental "$batch"
-  done
-}
-
-append_pending "$rel"
-
-if have_flock; then
-  exec 8>"$run_lock"
-  if flock -n 8; then
-    drain_until_empty
-    flock -u 8
-  fi
-  exec 8>&-
-else
-  if try_acquire_mkdir_lock "$run_lock_dir"; then
-    drain_until_empty
-    release_mkdir_lock "$run_lock_dir"
-  fi
-fi
-
-exit 0
+# Claude PostToolUse adapter; the shared runner owns queueing and refresh.
+exec "$BASH" "${BASH_SOURCE[0]%/*}/woods-refresh.sh" claude

data/plugin/hooks/woods-refresh.sh

@@ -0,0 +1,260 @@
+#!/usr/bin/env bash
+# Opt-in refresh dispatcher. Each edit is durable until its task succeeds.
+# See docs/WATCH_DAEMON.md for retry, daemon deferral and Docker transport.
+set -u
+umask 077
+[ "${WOODS_HOOKS_DISABLED:-0}" = 1 ] && exit 0
+[ "${WOODS_HOOKS_ENABLED:-0}" = 1 ] || exit 0
+
+client="${1:-}"
+hook_dir="${BASH_SOURCE[0]%/*}"
+# Preserve raw bytes until JSON validation: Bash command substitution silently
+# removes NUL bytes and could turn a malformed path into a different valid one.
+input_file="$(mktemp "${TMPDIR:-/tmp}/woods-hook-input.XXXXXX")" || exit 0
+trap 'rm -f "$input_file"' EXIT
+trap 'exit 143' TERM INT
+head -c 1048577 >"$input_file" || exit 0
+payload_bytes="$(wc -c <"$input_file")"
+[ "$payload_bytes" -le 1048576 ] || { printf '[Woods hooks] Oversized edit event; no refresh queued.\n' >&2; exit 0; }
+if command -v jq >/dev/null 2>&1; then
+  payload="$(jq -c --arg client "$client" -f "$hook_dir/adapters/normalize.jq" <"$input_file" 2>/dev/null)" || {
+    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
+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
+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")'
+  fi
+}
+cwd="$(field; printf .)"
+cwd="${cwd%.}"
+cwd="${cwd%/}"
+[ -n "$cwd" ] || exit 0
+[ -d "$cwd" ] || exit 0
+configured_output="${WOODS_OUTPUT:-tmp/woods}"
+case "$configured_output" in /*) tmp_dir="$configured_output" ;; *) tmp_dir="$cwd/$configured_output" ;; esac
+[ -f "$tmp_dir/generation.json" ] || exit 0
+source "$hook_dir/woods-input-rules.sh" || exit 0
+# Validate every member before publishing the event. Missing/deleted paths are
+# allowed; symlink components are deliberately unsupported, including escapes.
+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" }'
+  fi
+}
+relevant=0
+invalid=0
+while IFS= read -r -d '' operation && IFS= read -r -d '' file; do
+  case "$file" in "$cwd"/*) rel="${file#"$cwd"/}" ;; /*) invalid=1; break ;; *) rel="$file" ;; esac
+  case "/$rel/" in */../*|*/./*|*//* ) invalid=1; break ;; esac
+  parent="$cwd/$rel"
+  while [ "$parent" != "$cwd" ]; do
+    if [ -L "$parent" ]; then invalid=1; break; fi
+    parent="${parent%/*}"
+  done
+  [ "$invalid" = 0 ] || break
+  [ "$(woods_input_action "$rel")" = ignore ] || relevant=1
+done < <(event_fields)
+if [ "$invalid" = 1 ]; then
+  printf '[Woods hooks] Foreign, escaping or symlinked edit path; no refresh queued.\n' >&2
+  exit 0
+fi
+[ "$relevant" = 1 ] || exit 0
+
+log="$tmp_dir/hook.log"
+queue="$tmp_dir/hook-pending"
+run_lock="$tmp_dir/hook.lock"
+run_lock_dir="$tmp_dir/hook.lock.d"
+mkdir -p "$queue" || exit 0
+# Files are immutable once published. A killed worker never destroys its batch.
+enqueue() {
+  event="$queue/$$.$RANDOM.$RANDOM"
+  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
+  fi
+  mv "$event.tmp" "$event.json"
+}
+# One immutable file keeps a multi-file event indivisible across crashes.
+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
+fi
+mv "$event.tmp" "$event.json" || exit 0
+
+# A private deadline applies even when the client backgrounds async hooks.
+budget="${WOODS_HOOK_TIMEOUT_SECONDS:-600}"
+case "$budget" in ''|*[!0-9]*|0) printf 'Invalid WOODS_HOOK_TIMEOUT_SECONDS; queued work retained.\n' >>"$log"; exit 0 ;; esac
+[ "$budget" -le 3600 ] || exit 0
+started=$SECONDS
+have_flock() { command -v flock >/dev/null 2>&1; }
+acquire() {
+  if have_flock; then
+    exec 8>"$run_lock"
+    flock -n 8
+  else
+    if ! mkdir "$run_lock_dir" 2>/dev/null; then
+      owners=("$run_lock_dir"/owner-*)
+      [ "${#owners[@]}" -le 1 ] || return 1
+      if [ "${#owners[@]}" -eq 1 ]; then
+        owner="${owners[0]##*/owner-}"
+        # Never steal a live owner's lease solely because its mtime is old.
+        case "$owner" in *[!0-9]*) return 1 ;; esac
+        kill -0 "$owner" 2>/dev/null && return 1
+        # Only the reclaimer that removes this marker may replace the directory.
+        # Another reclaimer may already have created a new, still-empty lock.
+        rm "${owners[0]}" 2>/dev/null || return 1
+        rmdir "$run_lock_dir" 2>/dev/null || return 1
+      else
+        # Compatibility recovery for an old empty mkdir lock after a crash.
+        mtime="$(stat -c %Y "$run_lock_dir" 2>/dev/null || stat -f %m "$run_lock_dir" 2>/dev/null)"
+        [ -n "$mtime" ] || return 1
+        now="$(date +%s)"
+        [ "$((now - mtime))" -gt "${WOODS_HOOK_LOCK_STALE_SECONDS:-1800}" ] || return 1
+        rmdir "$run_lock_dir" 2>/dev/null || return 1
+      fi
+      mkdir "$run_lock_dir" 2>/dev/null || return 1
+    fi
+    : >"$run_lock_dir/owner-$$" 2>/dev/null || return 1
+    owners=("$run_lock_dir"/owner-*)
+    if [ "${#owners[@]}" -ne 1 ]; then
+      rm -f "$run_lock_dir/owner-$$"
+      return 1
+    fi
+  fi
+}
+release() {
+  if have_flock; then flock -u 8; exec 8>&-; else rm -f "$run_lock_dir/owner-$$"; rmdir "$run_lock_dir" 2>/dev/null || true; fi
+}
+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 '
+      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] }))
+    ' -- "$configured_output" "${batch[@]}"
+  fi
+}
+run_batch() {
+  encoded="$(encode_batch)" || return 1
+  [ -n "$encoded" ] || return 1
+  remaining=$((budget - SECONDS + started))
+  [ "$remaining" -gt 0 ] || return 124
+  rake="${WOODS_HOOK_RAKE:-bundle exec rake}"
+  # Job control gives this command and its descendants a dedicated process group.
+  # The task argument crosses Docker exec without requiring env forwarding or a
+  # host-only queue path to exist inside the application container.
+  set -m
+  ( exec 8>&-; cd "$cwd" || exit 1; exec $rake "woods:hook_refresh[$encoded]" ) >>"$log" 2>&1 &
+  runner=$!
+  ( exec 8>&-; sleep "$remaining"; kill -TERM -- "-$runner" 2>/dev/null; sleep 1; kill -KILL -- "-$runner" 2>/dev/null ) >/dev/null 2>&1 &
+  timer=$!
+  wait "$runner" 2>/dev/null
+  result=$?
+  kill -KILL -- "-$runner" 2>/dev/null || true
+  runner=""
+  kill -TERM -- "-$timer" 2>/dev/null || true
+  wait "$timer" 2>/dev/null || true
+  timer=""
+  set +m
+  return "$result"
+}
+cleanup() {
+  [ -z "${runner:-}" ] || kill -KILL -- "-$runner" 2>/dev/null || true
+  [ -z "${timer:-}" ] || kill -TERM -- "-$timer" 2>/dev/null || true
+  if [ "${legacy_directory_owned:-0}" = 1 ]; then
+    rmdir "$tmp_dir/hook-pending.lock.d" 2>/dev/null || true
+  fi
+  release
+}
+shopt -s nullglob
+acquire || exit 0
+trap 'exit 143' TERM INT
+trap 'cleanup' EXIT
+# Upgrade recovery: import the previous newline queue before retiring it.
+# A crash during import can duplicate an event but cannot erase its obligation.
+legacy_pending="$tmp_dir/hook-pending.txt"
+if [ -s "$legacy_pending" ]; then
+  if have_flock; then
+    exec 7>"$tmp_dir/hook-pending.lock"
+    flock -n 7 || exit 0
+  else
+    if ! mkdir "$tmp_dir/hook-pending.lock.d" 2>/dev/null; then
+      printf 'Legacy queue import deferred: hook-pending.lock.d is busy; both queues retained.\n' >>"$log"
+      exit 0
+    fi
+    legacy_directory_owned=1
+  fi
+  while IFS= read -r legacy_path || [ -n "$legacy_path" ]; do
+    [ "$((SECONDS - started))" -lt "$budget" ] || exit 0
+    [ -n "$legacy_path" ] || continue
+    enqueue "$legacy_path" || exit 0
+  done <"$legacy_pending"
+  rm -f "$legacy_pending"
+  if have_flock; then
+    flock -u 7
+    exec 7>&-
+  else
+    rmdir "$tmp_dir/hook-pending.lock.d" 2>/dev/null || true
+    legacy_directory_owned=0
+  fi
+fi
+while :; do
+  batch=("$queue"/*.json)
+  if [ "${#batch[@]}" -eq 0 ]; then
+    # Release before checking again: an arrival either becomes our next batch
+    # or acquires ownership itself. There is no last-drain/release gap.
+    release
+    trap - EXIT
+    batch=("$queue"/*.json)
+    [ "${#batch[@]}" -gt 0 ] || break
+    acquire || break
+    trap 'cleanup' EXIT
+    continue
+  fi
+  candidates=("${batch[@]:0:16}")
+  batch=()
+  batch_bytes=0
+  batch_events=0
+  for candidate in "${candidates[@]}"; do
+    event_bytes="$(wc -c <"$candidate")"
+    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
+    fi
+    [ "$((batch_events + event_count))" -le 1000 ] || break
+    [ "$((batch_bytes + event_bytes))" -le 49152 ] || break
+    batch+=("$candidate")
+    batch_bytes=$((batch_bytes + event_bytes))
+    batch_events=$((batch_events + event_count))
+  done
+  if [ "${#batch[@]}" -eq 0 ]; then
+    printf 'Oversized hook event; pending work retained for inspection.\n' >>"$log"
+    break
+  fi
+  if run_batch; then
+    rm -f "${batch[@]}"
+  else
+    result=$?
+    printf 'Woods hook deferred/failed (status %s); pending events retained in %s. Retry on the next edit or invoke the hook again after resolving the cause.\n' "$result" "$queue" >>"$log"
+    break
+  fi
+done
+exit 0

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

@@ -1,77 +1,69 @@
 #!/usr/bin/env bash
-# Woods SessionStart hook (#280): say so when the published generation is
-# older than the last commit. Stdout from a SessionStart hook is added to
-# the session context, so the agent sees the warning before it trusts the
-# index.
-#
-# This check only compares two commit-adjacent timestamps: the generation's
-# `updated_at` and `git log -1`'s commit time. It says nothing about
-# uncommitted edits (the index can be stale against a dirty working tree
-# with no stale commit to detect) or about a checkout sitting on an older
-# commit than the one that produced the generation (the timestamp comparison
-# can read as fresh there even though the code and the index disagree). Read
-# a quiet run as "not behind the last commit," not as "definitely current."
-#
-# Opt-in: shipped disabled. Nothing prints until WOODS_HOOKS_ENABLED=1 is
-# set; WOODS_HOOKS_DISABLED=1 turns it back off without touching that
-# setting.
+# Opt-in, bounded source-content verification through the application's rake
+# command. The status task has no Rails environment prerequisite; Docker-only
+# installations do not need the Woods gem or an application bundle on the host.
 set -u
 
 [ "${WOODS_HOOKS_DISABLED:-0}" = "1" ] && exit 0
 [ "${WOODS_HOOKS_ENABLED:-0}" = "1" ] || exit 0
-
 payload="$(cat)"
-
 field() {
   if command -v jq >/dev/null 2>&1; then
-    printf '%s' "$payload" | jq -r ".$1 // empty"
+    printf '%s' "$1" | jq -r --arg name "$2" '.[$name] // empty' 2>/dev/null
   elif command -v ruby >/dev/null 2>&1; then
-    printf '%s' "$payload" | ruby -rjson -e '
-      value = JSON.parse($stdin.read)
-      ARGV[0].split(".").each { |key| value = value.is_a?(Hash) ? value[key] : nil }
-      print value.to_s' -- "$1"
-  else
-    printf ''
+    printf '%s' "$1" | ruby -rjson -e 'print JSON.parse($stdin.read).fetch(ARGV[0], "")' -- "$2" 2>/dev/null
   fi
 }
-
-cwd="$(field cwd)"
-[ -z "$cwd" ] && exit 0
-
-# Same no-boot resolution the PostToolUse hook and woods:watch_status use:
-# WOODS_OUTPUT overrides outright, otherwise tmp/woods under cwd.
+cwd="$(field "$payload" cwd)"
+[ -n "$cwd" ] && [ -d "$cwd" ] || exit 0
 configured_output="${WOODS_OUTPUT:-tmp/woods}"
 case "$configured_output" in
-  /*) tmp_dir="$configured_output" ;;
-  *) tmp_dir="$cwd/$configured_output" ;;
+  /*) output_dir="$configured_output" ;;
+  *) output_dir="$cwd/$configured_output" ;;
 esac
-
-marker="$tmp_dir/generation.json"
-[ -f "$marker" ] || exit 0
-
+[ -f "$output_dir/generation.json" ] || exit 0
 if command -v jq >/dev/null 2>&1; then
-  updated="$(jq -r '.updated_at // empty' "$marker")"
-  number="$(jq -r '.number // empty' "$marker")"
+  encoded="$(jq -nr --arg output "$configured_output" '{output:$output,mode:"quick"} | @base64')"
 elif command -v ruby >/dev/null 2>&1; then
-  updated="$(ruby -rjson -e 'print JSON.parse(File.read(ARGV[0]))["updated_at"].to_s' -- "$marker")"
-  number="$(ruby -rjson -e 'print JSON.parse(File.read(ARGV[0]))["number"].to_s' -- "$marker")"
+  encoded="$(ruby -rjson -rbase64 -e 'print Base64.strict_encode64(JSON.generate(output: ARGV[0], mode: "quick"))' -- "$configured_output")"
 else
   exit 0
 fi
-[ -z "$updated" ] && exit 0
 
-last_commit="$(git -C "$cwd" log -1 --format=%cI 2>/dev/null)"
-[ -z "$last_commit" ] && exit 0
-
-stale=0
-if command -v ruby >/dev/null 2>&1; then
-  ruby -rtime -e 'exit(Time.parse(ARGV[0]) < Time.parse(ARGV[1]) ? 1 : 0)' -- "$updated" "$last_commit" || stale=1
-elif date -d "$updated" +%s >/dev/null 2>&1; then
-  [ "$(date -d "$updated" +%s)" -lt "$(date -d "$last_commit" +%s)" ] && stale=1
-fi
-
-if [ "$stale" = "1" ]; then
-  echo "Woods index is stale: generation ${number:-?} was published at $updated, before the last commit at $last_commit." \
-       "Run bin/rails woods:incremental (or start bin/rails woods:watch) before trusting woods answers."
+record="$(mktemp "${TMPDIR:-/tmp}/woods-source-status.XXXXXX")" || exit 0
+runner=""; timer=""
+cleanup() {
+  [ -z "$runner" ] || kill -KILL -- "-$runner" 2>/dev/null || true
+  [ -z "$timer" ] || kill -TERM -- "-$timer" 2>/dev/null || true
+  rm -f "$record"
+}
+trap cleanup EXIT
+trap 'exit 0' INT TERM
+# Ten seconds includes command startup; the shared content verifier itself has
+# a 250ms scan budget. A client hook timeout alone is not a process deadline.
+set -m
+rake="${WOODS_HOOK_RAKE:-bundle exec rake}"
+( cd "$cwd" || exit 1; exec $rake "woods:source_status[$encoded]" ) >"$record" 2>/dev/null &
+runner=$!
+( sleep 10; kill -TERM -- "-$runner" 2>/dev/null; sleep 1; kill -KILL -- "-$runner" 2>/dev/null ) >/dev/null 2>&1 &
+timer=$!
+wait "$runner" 2>/dev/null
+result=$?
+kill -KILL -- "-$runner" 2>/dev/null || true
+runner=""
+kill -TERM -- "-$timer" 2>/dev/null || true
+wait "$timer" 2>/dev/null || true
+timer=""
+set +m
+if [ "$result" -ne 0 ]; then
+  echo 'Woods source freshness is unknown: source verification was unavailable or exceeded its deadline. Inspect woods_status; use woods-extract full for a fresh capture.'
+  exit 0
 fi
+status="$(tail -n 1 "$record")"
+state="$(field "$status" state)"
+case "$state" in
+  current) ;;
+  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.' ;;
+esac
 exit 0

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

@@ -7,6 +7,19 @@ description: Make a repository's coding agents use the Woods index by default
 
 Installing the gem gives one operator an index; this skill gives every future agent session one. Wiring is three small, reviewable changes to the host repository. Each edits shared, checked-in files, so propose the diff and get approval before writing, match the repository's existing conventions, and leave unrelated content untouched.
 
+## Managed configuration availability
+
+`woods-agent-config` (#407) is unreleased after `2.0.0.beta2`. First record the
+installed version and test `bundle exec woods-agent-config --help` in the
+selected application bundle. When supported, use its saved setup/update/remove
+plan and explicit client/scope/root selection; apply the reviewed plan within
+the user's existing authorization. Do not infer ownership from a server name
+or repair edited managed sections by overwriting them. Plans and recovery
+journals contain private configuration bytes. See the canonical
+[managed configuration runbook](https://github.com/lost-in-the/woods/blob/main/docs/AGENT_SETUP.md#managed-claude-code-configuration)
+for host/Compose preflight, actual Claude file locations, conflict recovery,
+and removal. Preserve manual setup for older installed versions.
+
 ## Preflight
 
 Confirm Woods actually works before advertising it to every future session: