woods 2.0.0.beta2 → 2.0.0.beta4

data/docs/WATCH_DAEMON.md

@@ -29,8 +29,10 @@ Ctrl-C to stop.
 | `WOODS_WATCH_DEBOUNCE` | `0.4` | Seconds of quiet before a batch is considered settled |
 | `WOODS_WATCH_FULL_THRESHOLD` | `50` | Actionable changed-file count above which a full extraction replaces incremental |
 | `WOODS_WATCH_POLL` | unset | `1` forces the polling backend, set this inside a container watching a bind mount |
+| `WOODS_WATCH_POLL_INTERVAL` | `1.0` | Positive, finite seconds of sleep between polling scans; does not select the polling backend |
 | `WOODS_WATCH_IDLE_TIMEOUT` | unset | Seconds of quiet after which a dormant daemon exits |
 | `WOODS_WATCH_CATCH_UP` | `1` | `0` skips the startup reconciliation |
+| `WOODS_WATCH_TRUST_FOREIGN_HOST` | unset | `1` lets a reader trust a fresh foreign-host heartbeat without checking its pid locally; see [cross-host liveness](#cross-host-liveness) |
 
 Run it under a supervisor. When boot-captured configuration changes the daemon
 exits `75` (`EX_TEMPFAIL`) on purpose, see [Restart triggers](#restart-triggers).
@@ -75,6 +77,13 @@ This is `rails/spring`'s contract, copied deliberately: Spring's staleness bugs
 came from under-scoping exactly this set, so the boundary here is drawn on the
 generous side.
 
+A restart-trigger change found at startup is reconciled with one full extraction
+when it is covered by the task's environment-boot snapshot. That advances the
+generation through real extraction, so a supervisor restart does not repeatedly
+exit `75` over the same files. Live restart triggers still stop the daemon,
+including edits during startup extraction. Their paths survive shutdown even
+when the preceding extraction has advanced the generation watermark.
+
 The same escalation happens when the app *can't* reload at all, a boot with
 `config.enable_reloading = false`. Extracting against constants that no longer
 match their source would be worse than saying so.
@@ -87,7 +96,7 @@ partial write:
 
 | Failure | What happens |
 |---|---|
-| Reload raises (`SyntaxError`, `NameError`) | Degraded status naming the reason; index intact at generation N; retried on the next event |
+| Reload raises (`SyntaxError`, `NameError`) | Degraded status naming the reason; index intact at generation N; pending paths retried on the next file event or heartbeat |
 | Extraction raises | Degraded status; generation not advanced |
 | Payload directory can't be opened, over a payload-born index | Degraded status; generation not advanced. An incremental run only writes the units it touched, so there is no complete flat index it could fall back to publishing, see [Payload publishing](#payload-publishing) |
 | Index written but the generation bump failed | Degraded status; paths carried forward. The extractor deliberately does not fail an otherwise-good extraction over an unwritable marker, but the marker *is* what readers refresh on, so the daemon cross-checks that the number moved rather than reporting `running` over an index nothing can see |
@@ -110,17 +119,23 @@ at a known generation, reason attached), `stopped` (nothing is maintaining this
 index). A stale answer is only dangerous when nothing says so.
 
 The file is written world-readable (0644) by design: host-side hooks read it
-through a bind mount. Every other artifact Woods writes stays at 0600.
+through a bind mount. Writes through `Woods::AtomicFile` default to owner-only
+0600 unless the caller supplies another mode. This is not a guarantee for every
+Woods artifact: the SQLite metadata store does not enforce 0600, and a newly
+created database uses 0644 under umask 022. Restrict access to the output
+directory according to the source and metadata it contains.
 
 Note that `SyntaxError` is a `ScriptError`, not a `StandardError`. Rescuing
 only the latter would let a half-typed file kill the daemon.
 
 A cycle that fails to land its work never loses its paths. Lock contention, a
 failed reload, and a raising extraction all carry the batch into `@pending`, and
-the next cycle folds it back in, the files really did change, and no later
-event will mention them again. The retry is not a tight loop: a degraded cycle
-ends the drain and waits for the next event, because the cause needs an edit to
-clear.
+the next cycle folds it back in even if no new event mentions those files.
+A degraded cycle ends the current drain to avoid a tight retry loop. Pending
+paths are retried on the next file event or [heartbeat](#the-heartbeat), so a
+finished contending writer does not require another edit to trigger recovery.
+Heartbeat retries use a separate worker so status updates and lock refresh
+continue while extraction runs.
 
 ### The heartbeat
 
@@ -151,6 +166,24 @@ it starts: edits and pulled commits that landed while nothing was watching are
 invisible to it forever. That matters because callers stand down when a daemon
 is alive, so *alive has to mean covered*.
 
+The standalone `woods:watch` task snapshots reload/restart inputs before invoking
+Rails' `environment` task. Inputs unchanged across that boundary, including
+carried paths that remain deleted, may be reconciled by a full extraction.
+Unreleased after `2.0.0.beta3`: registered restart inputs deleted while the
+daemon was stopped also trigger a full extraction after a fresh environment
+boot. Nominal framework paths still use the bounded deletion sweep.
+Changes during environment initialization still require restart. Lock contention,
+extraction failure, and publication failure retain the full-reconciliation
+obligation for retry; a successful publish clears it.
+
+This boundary covers **environment initialization**. Bundler and
+`config/application.rb` can run before the task begins; the snapshot does not
+prove that edits during those earlier stages were incorporated. Start the task
+against a settled boot configuration. If Rails is already initialized or the
+`environment` task was already invoked, the daemon keeps conservative restart
+handling. Use `bundle exec rake woods:watch` as a separate process, rather than
+`bundle exec rake environment woods:watch`.
+
 So `run` reconciles before it waits. The watermark is `generation.json`'s mtime, written last on every successful run, so it means "when this index was last
 known good", and everything modified since is uncovered, whoever changed it.
 With no generation file there is no index, every file is uncovered, and the
@@ -161,7 +194,12 @@ external cleanup targeting the large directories), and readers deliberately
 degrade a dangling pointer to the index root, so trusting the mtime there would
 report "current at startup" over a directory holding nothing.
 
-**The watcher thread starts before this reconciliation runs, not after.** A
+**The built-in watcher establishes detection before reconciliation runs.**
+Polling signals readiness after its baseline scan; native watching signals after
+listener startup, including a fallback to polling. Startup waits up to 30 seconds
+for readiness and reports an error if detection cannot start. Callbacks enqueue
+live events immediately, while extraction waits until startup obligations are
+established. A
 file saved while catch-up's own extraction is still in flight (which can take
 minutes on a storm-triggered full run) used to be lost twice: no watcher
 existed yet to see it, and the polling watcher takes its baseline snapshot
@@ -173,8 +211,9 @@ already tolerate the duplicate paths this produces against whatever catch-up
 finds on its own via the tree scan.
 
 Deletions need one extra step, because a deleted file leaves no mtime to scan:
-if any path the index attributes a unit to is gone from disk, the daemon runs
-one cycle with an *empty* change set, which reaches the ghost units through the
+registered restart inputs follow the full-reconciliation rule above. For other
+registered paths gone from disk, a deletion-only startup runs one cycle with an
+*empty* change set, which reaches the ghost units through the
 extractor's bounded deletion sweep. Deliberately empty, naming the paths would
 make the deletions authoritative for every unit type, and some registered paths
 are nominal (on Rails < 7.1, `ActiveRecord::SchemaMigration` registers a
@@ -185,7 +224,7 @@ supplies the trigger.
 This is what makes the documented hook pattern safe:
 
 ```bash
-bundle exec rake woods:watch_status || start_the_daemon
+bundle exec rake woods:watch_status || start_the_daemon # same host; see cross-host liveness below
 bundle exec rake woods:incremental   # stands down, the daemon has these
 ```
 
@@ -215,9 +254,19 @@ polling rather than trust a watcher that may sit silent while files change
 under it:
 
 ```bash
-WOODS_WATCH_POLL=1 bundle exec rake woods:watch
+WOODS_WATCH_POLL=1 WOODS_WATCH_POLL_INTERVAL=2.5 bundle exec rake woods:watch
 ```
 
+### Polling cost
+
+For a slow bind mount, increase `WOODS_WATCH_POLL_INTERVAL` to reduce scan
+frequency. The default is 1.0 second; the example above uses 2.5 seconds.
+Each cycle also includes the scan's duration. Longer intervals can delay
+change detection and polling shutdown. The value also applies when a native
+watcher fails and falls back to polling; it has no effect while native watching
+is active. Blank, malformed, nonfinite, zero and negative values are rejected
+before the daemon starts.
+
 Selection is also self-correcting at runtime. If `listen` cannot start at all, inotify watch exhaustion (`ENOSPC`) is the usual reason on a large tree, the
 daemon logs it and falls back to polling rather than exiting, because a daemon
 costing some CPU beats one that never fires. Failures *after* startup are not
@@ -234,6 +283,14 @@ Ignored by default: `.git`, `node_modules`, `tmp`, `log`, `coverage`,
 `vendor/bundle`, `public/assets`, `public/packs`, `storage`. That ignore list is
 what keeps a polling scan bounded.
 
+Polling and startup catch-up preserve each logical path when multiple directory
+symlinks point to the same source tree. For example, `a_shared/user.rb` and
+`app/models/user.rb` both remain visible; an earlier alias must not hide the path
+that extraction recognizes. Cycles back to a directory already on the current
+traversal branch are pruned, while independent sibling aliases remain visible.
+This can increase scan work for deliberately repeated aliases; avoid unnecessary
+aliases in large watched trees. Ignored logical paths are still pruned.
+
 ## Placement
 
 The spike asked for three placements to be compared and one chosen. Every
@@ -418,13 +475,11 @@ party) behaves exactly as it always did.
 was told the index matched HEAD while every answer described the tree before
 those edits.
 
-The fingerprint (a digest of `git status --porcelain`) is *as of the call*.
-Nothing records the digest the index was built at, so it cannot tell you "this
-is the same dirty state the index describes", it gives a stable identity for
-the current dirty state, so two of your own calls can be compared to detect the
-tree moving underneath you. Pair it with `generation` to distinguish "tree
-changed and the index followed" from "tree changed and the index has not caught
-up".
+The fingerprint hashes the current `git status --porcelain` path/status list.
+Repeated edits to the same already-dirty file can leave it identical. It is not
+content identity. Use `index.source_freshness` for generation-bound content
+verification; see [source freshness](SOURCE_FRESHNESS.md) for `current`, `drifted`,
+`unknown`, scan budgets, fresh-process capture and partial-runtime limitations.
 
 ### Multi-file read consistency
 
@@ -534,7 +589,7 @@ and a hook-triggered `woods:incremental`. They share the existing file-based
 A hook can check cheaply:
 
 ```bash
-bundle exec rake woods:watch_status || start_the_daemon   # exit 0 = alive
+bundle exec rake woods:watch_status || start_the_daemon   # same host, exit 0 = alive
 ```
 
 The check does not boot Rails. Without `WOODS_OUTPUT`, it resolves
@@ -543,63 +598,145 @@ launcher's current directory, so `rake -f /app/Rakefile woods:watch_status`
 and worktree-manager invocations inspect the same per-app status. Set
 `WOODS_OUTPUT` when the daemon uses a non-default index directory.
 
-Liveness needs three things to agree, each ruling out a different way the
-status file lies: a state a live daemon writes, a pid that still exists (a
-`kill -9` leaves the file behind), and a recent timestamp (a machine that lost
-power leaves a `running` record whose pid some unrelated process now owns).
+### Cross-host liveness
 
-One known limit: the pid check sees only the caller's own pid namespace. In the
-Docker layout, daemon in the container, output volume-mounted to the host, a
-host-side `watch_status` tests a host pid that has nothing to do with the
-containerized daemon, so it can misread liveness in either direction for up to
-`STALE_AFTER` (the timestamp check still bounds it, and the heartbeat keeps a
-live daemon inside that bound). Run `watch_status` on the same side as the
-daemon; a cross-namespace liveness protocol isn't worth its complexity here.
+By default, a reader trusts only a same-host record: a `running` or `degraded`
+state, a positive pid that still exists, and a recent ISO8601 timestamp. Foreign
+hostnames are rejected because a container pid cannot be checked on the host.
+
+For a daemon and reader sharing the same index through a bind mount, opt in in
+each reader's environment:
+
+```bash
+export WOODS_WATCH_TRUST_FOREIGN_HOST=1
+bundle exec rake woods:watch_status || start_the_daemon
+```
+
+Set the variable inside one-off containers running `woods:incremental`, and in
+the host MCP process when it reports `woods_status`. Docker does not forward a
+host environment variable automatically: pass `-e WOODS_WATCH_TRUST_FOREIGN_HOST=1`
+to `docker compose run` or `docker compose exec`, or configure that service's
+environment. Use the same shared index (`WOODS_OUTPUT` when needed) in each process.
+
+Opted-in readers accept foreign `running` and `degraded` records on heartbeat
+freshness, without any local pid lookup. Heartbeats run every five minutes; a
+crashed foreign daemon can still be believed for up to 15 minutes after its last
+heartbeat. Missing or malformed timestamps and timestamps more than 30 seconds
+in the future are rejected. Keep the participating clocks synchronized.
+
+`degraded` means alive but unable to update: `watch_status` exits 0, incremental
+still attempts extraction, and clean refuses. `WOODS_IGNORE_WATCH=1` still
+overrides writer stand-down and clean protection. It does not alter the status
+report. Direct Ruby callers can override the environment with
+`Status#alive?(trust_foreign_host: true)` or `false`.
+
+This is liveness evidence for an established daemon, not a cross-container
+startup lease. Simultaneous starts in foreign namespaces still need one
+supervisor to coordinate ownership. Hostnames are also imperfect identity:
+custom or reused identical container hostnames retain the local-pid limitation.
 
 ### Hooks for agent sessions
 
+For client registration and the supported Claude/OpenCode event shapes, see
+[edit client adapters](CLIENT_HOOKS.md). Both use the shared queue below.
+
 The daemon covers a human's editor session. A `claude -p` run in a worktree
-with no daemon needs a different trigger, so the Woods plugin ships two
+with no daemon needs a different trigger, so the Woods plugin ships two freshness
 hooks (`plugin/hooks/hooks.json`), both shipped disabled:
 
 | Hook | When | What it does |
 |---|---|---|
-| `PostToolUse` (`Edit`, `Write`, `MultiEdit`), async | An edit under `app/models`, `config/routes*`, `db/migrate`, `db/*_migrate`, `db/schema.rb`, `db/structure.sql`, or any `package.yml` / `packwerk.yml` | Appends the path to `hook-pending.txt` under a lock, then runs `CHANGED_FILES=<paths> woods:incremental` for whatever is pending, output to `hook.log` |
-| `SessionStart` (`startup`, `resume`) | Session begins | Prints a warning when `generation.json`'s `updated_at` predates `git log -1` |
-
-Both read `cwd` from the hook payload, not `CLAUDE_PROJECT_DIR`, which stays
-at the launch root inside a worktree. Both do nothing until
-`tmp/woods/generation.json` exists, and neither runs at all until
-`WOODS_HOOKS_ENABLED=1` is set; `WOODS_HOOKS_DISABLED=1` turns them back off
-without touching that setting. `woods:incremental` still stands down under a
-`:running` daemon, so a hook and a daemon on the same worktree never
-contend. `WOODS_HOOK_RAKE` sets the command prefix (Docker:
-`docker compose exec -T app bundle exec rake`); `WOODS_OUTPUT` points the
-hooks at a non-default index directory, the same variable
-`woods:incremental`/`woods:watch_status` already read.
-
-A hook invocation that finds another one already draining the pending file
-does not wait for it: it appends its own path and returns, and the
-in-progress drainer picks that path up on its next pass, looping until a
-drain comes back empty. The one gap this leaves is an append that lands
-between the drainer's last (empty) drain and its releasing the lock: that
-edit is delayed to the next graph-changing edit rather than lost outright,
-and the `SessionStart` warning is the backstop for it.
-
-On a host without `flock`, the mkdir-based fallback lock has no kernel-enforced
-release, so a hook killed mid-drain would otherwise leave a lock directory
-behind forever; each lock directory is reclaimed once its mtime is older than
-`WOODS_HOOK_LOCK_STALE_SECONDS` (default 1800), while a fresh one is still
-respected as busy.
-The age check needs `stat`; on a host with neither `flock` nor `stat`, a crashed
-pending-lock holder can still make the next hook wait until the hook timeout.
-
-The `SessionStart` warning compares two commit-adjacent timestamps only:
-the generation's `updated_at` against the last commit's time. It says
-nothing about uncommitted changes in the working tree, and a checkout
-sitting on an older commit than the one that produced the generation can
-still read as fresh under this check. Treat a quiet session start as "not
-behind the last commit," not as a general freshness guarantee.
+| `PostToolUse` (`Edit`, `Write`, `MultiEdit`), async | A supported extraction or boot input changes | Queues an immutable JSON event, then calls `woods:hook_refresh[<encoded batch>]`; output goes to `hook.log` |
+| `SessionStart` (`startup`, `resume`) | Session begins | Checks source content through `woods:source_status`; warns on drift or unknown evidence |
+
+Both read `cwd` from the hook payload, so a linked worktree uses its own index.
+Both require an existing `generation.json` and `WOODS_HOOKS_ENABLED=1`;
+`WOODS_HOOKS_DISABLED=1` overrides enablement. The broader refresh task is
+**unreleased after Woods 2.0.0.beta2**. Check the installed gem's task list
+(`bundle exec rake -T woods:hook_refresh`, through the application container
+when appropriate) before enabling this plugin version. An older gem's unknown
+task error leaves queued events in place; installing the plugin does not upgrade
+the gem.
+
+The portable path predicate is generated from `PathDispatcher` and
+`ReloadPolicy` with `bundle exec ruby -Ilib script/generate-hook-rules`.
+A contract test rejects stale generated rules. It covers services, controllers,
+jobs, concerns, views, locales, supported test/lib files, routes, package
+boundaries, and the remaining standard extractor triggers. Unrelated documents
+stay quiet. Normal edits use fresh-process incremental extraction; changes to
+initializers, boot configuration, dependencies, schema, or other restart inputs
+use fresh-process full extraction. The transport also preserves explicit
+`add`, `update`, `delete`, and `move` operations; a relevant deletion/move selects
+full extraction to remove runtime classes absent from the next boot. The Claude
+adapter receives one `tool_input.file_path`. The OpenCode adapter supplies every
+verified patch metadata path, including both rename sides. Neither infers paths
+from shell commands or parses patch text. Custom runtime roots outside the
+standard dispatcher rules require an explicit refresh; the portable predicate
+cannot discover application configuration without booting it.
+
+`WOODS_HOOK_RAKE` sets the command prefix (Docker:
+`docker compose exec -T app bundle exec rake`). The encoded JSON task argument
+carries paths and the output setting across the container boundary, without
+assuming Docker forwards host environment variables or can read a host queue
+filename. The host needs Bash 3.2 or later, standard Unix tools, and either `jq`
+or Ruby; it does not need the application bundle. Prefix words are split without
+shell evaluation: use an executable wrapper for quoted arguments or extra
+container environment settings. `WOODS_OUTPUT` overrides `tmp/woods`, relative
+to each process's application root or as an explicitly supplied absolute path;
+absolute paths must be valid on both sides of a container bind mount.
+
+Each event remains under `<output>/hook-pending/` until the task succeeds.
+Successful no-op consumption is acknowledged too. Contending invocations enqueue
+and return while the owner drains bounded batches (up to 16 queue files /
+1,000 paths / 48 KiB of JSON, without splitting a multi-file event). Commas,
+spaces, and newlines are preserved. An empty drain releases the lock before
+checking again, so a final arriving event can acquire ownership.
+A failed command, killed worker, incompatible gem, or publication failure retains
+its batch for retry: delivery is **at least once**, so crash recovery can repeat
+already completed work. Pending events in the previous `hook-pending.txt` format
+are imported on the next relevant edit. Event filenames are private hook state;
+do not modify them while a worker is running.
+
+An active daemon produces exit **75** before Rails boots. This is a deferral,
+not acknowledgement: the hook cannot prove which queued events the daemon has
+consumed. It retains the queue and writes a diagnostic. It does not start, stop,
+or restart the daemon. After resolving the cause, the next relevant edit retries
+the queue. To retry immediately, invoke `woods-post-edit.sh` with the original
+JSON event on stdin and the same opt-in/output/prefix settings; with a running
+daemon, stop it first or explicitly configure `WOODS_IGNORE_WATCH=1` in the
+application command's environment. A quiet `SessionStart` does not acknowledge
+the queue. Prefer a resident watcher for sustained edits; enabling both does not
+make refresh faster and can accumulate deferred events.
+
+After the complete event input has been read, validated, and queued, the refresh
+hook starts its `WOODS_HOOK_TIMEOUT_SECONDS` deadline (default 600, integer range
+1–3600), including subsequent batches. The producer must close stdin: the 1 MiB
+input limit bounds bytes, not time waiting for EOF. The deadline terminates the local
+command process group and retains work on timeout. For a Docker exec prefix,
+local process termination cannot guarantee cancellation inside the container;
+check the application process and extraction lock before retrying a timed-out
+container run. Async client hook timeouts are not a reliable worker deadline.
+With `flock`, kernel locks release after process exit. The mkdir fallback records
+an owner PID and reclaims dead owners; it never steals a live owner's lock based
+only on age. Only the invocation that removes the recorded dead-owner marker
+may replace its lock directory; competing reclaimers leave their events queued
+for the winning owner. Legacy empty lock directories use `stat` and
+`WOODS_HOOK_LOCK_STALE_SECONDS` (default 1800) for conservative recovery.
+A reused PID can delay recovery until that process exits; inspect the recorded
+owner before manually removing a lock. Hooks sharing this filesystem must run in
+the same host PID namespace; run the actual extraction through the container
+prefix instead of running competing host/container hook workers.
+
+Broader coverage increases the number of Rails boots. A view or locale edit now
+costs a fresh incremental run, while a boot/config edit costs a full run. There
+is no provider or embedding call added by this hook. Opt in for occasional agent
+edits; use `woods:watch` for repeated work, and keep full extraction for large
+change sets as described above.
+
+The `SessionStart` hook uses the shared quick source verifier through
+`WOODS_HOOK_RAKE`. It has a ten-second command deadline, including startup;
+failed commands and old gems lacking `woods:source_status` report unknown.
+It does not initialize Rails or start a provider. See [source freshness](SOURCE_FRESHNESS.md#containers-and-hooks).
 
 ### Reader multiplicity is free
 
@@ -663,5 +800,78 @@ result = daemon.process(changed_paths)
 # => { action: :incremental, state: :running, generation: 42, count: 1, duration_ms: 61 }
 ```
 
+For an embedded `#run`, pass `boot_snapshot: Woods::Watch::BootSnapshot.new(root: …)`
+with the snapshot captured **before** environment initialization if the host can
+establish that boundary. Without it, startup restart inputs remain restart
+requests. Direct `#process` calls always preserve conservative restart handling.
+Injected watchers retain their existing `start`/`stop` interface; those with
+asynchronous startup can implement `ready_callback=` and call it after detection
+is established to participate in the readiness handshake.
+
 `#process` is one whole cycle and is the supported embedding point. `#run` only
 supplies batches to it.
+
+### Optional bounded context hints
+
+Context hints are a separate Claude Code opt-in, **unreleased after Woods
+2.0.0.beta2**. Verify `bundle exec woods-hook-context --help` in the installed
+application bundle before enabling `WOODS_HOOK_CONTEXT_ENABLED=1`. The plugin
+version alone does not establish gem support. `WOODS_HOOKS_DISABLED=1` disables
+both context and refresh; `WOODS_HOOKS_ENABLED` controls only the existing
+freshness/refresh hooks. Either feature can work without the other.
+
+Separate synchronous SessionStart and PostToolUse entries emit Claude's
+`hookSpecificOutput.additionalContext`. SessionStart gives a short served-index
+orientation. After a relevant native Edit/Write/MultiEdit, the hint identifies
+candidates from one retained published generation. Direct candidates and
+transitive candidates are distinguished; test mappings are suggestions, never
+proof of coverage. Post-edit hints always say **pre-refresh snapshot** because
+an edit can precede publication. Source freshness is checked against that same
+payload; unknown/drifted evidence remains explicit. An unresolved or ambiguous
+edited identity directs the agent to manual search and typed lookup. No match
+within the bounded snapshot establishes neither absence nor no impact.
+
+Limits are fixed: depth 2, at most 10 visited nodes including the root, 100
+examined edges, and 2 KiB for the **entire JSON output**, preserving whole rows.
+An index is refused above 16 MiB per required artifact or 50,000 combined graph
+nodes/variants. These preparation checks, JSON parsing, cache construction,
+source verification, path/content hashing, formatting and suppression state all
+run within the hook's private process-group deadline: the worker is killed at
+850 ms, leaving dispatch/cleanup headroom within a one-second work budget.
+The helper also has a 650 ms inner deadline. OS scheduling can delay observation
+of a deadline. Cold bundle/container startup can therefore produce no hint;
+the deadline is not extended. Oversized evidence is marked truncated; missing,
+corrupt, unsupported or timed-out input produces a short unknown notice or
+silence. Silence is never a complete/no-impact claim. The hint boots no Rails
+application and calls no provider.
+
+The synchronous opt-in can add up to this budget to a supported tool call. It
+makes context available to Claude's next model request; it does not rely on the
+later-turn delivery of the independent asynchronous refresh worker. A reminder
+need not appear as a visible transcript entry. See the
+[Claude context-output contract](https://code.claude.com/docs/en/hooks#add-context-for-claude).
+
+The default command is `bundle exec woods-hook-context`. Set
+`WOODS_HOOK_CONTEXT_COMMAND` to an executable wrapper or argv prefix for a
+container-only bundle. Prefix words are split without shell evaluation; a
+wrapper handles quoted arguments. Explicit `WOODS_HOOK_CONTEXT_ROOT` maps the
+hook payload's original cwd and contained edit path onto a runtime-visible
+application root. For example, a container prefix can include
+`docker compose exec -T -e WOODS_HOOK_CONTEXT_ENABLED=1 -e WOODS_HOOK_CONTEXT_ROOT=/app app bundle exec woods-hook-context`.
+Forward a custom `WOODS_OUTPUT` explicitly too. Running Claude inside the
+application container avoids external container startup and path mapping.
+
+Repeat suppression uses session/worktree, served generation/token, changed-file
+content identity and normalized hint content. Repeated identical evidence stays
+quiet; later same-file edits and generation changes can reappear. Missing session
+or bounded content identity disables suppression. Private `hook-context-state.json`
+retains at most 32 sessions and 32 emitted identities per session under a separate
+nonblocking lock. It records **emitted**, not confirmed delivered, hints.
+Contending or unavailable state may skip optional context. Its bounded atomic
+state update never reads, acknowledges, or clears `hook-pending`, nor acquires
+refresh/watch locks. Disable context to roll back without changing refresh.
+
+Only the native Claude context entries are supported here; the OpenCode adapter
+continues to provide refresh events. No prompt-triggered retrieval is injected.
+
+See the [matched public Rails task comparison](EVALUATION.md#matched-optional-context-hook-tasks-406) for delivered hints, task outcomes, measured overhead and observed limitations.

data/exe/woods-agent-config

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/woods/agent_configuration/cli'
+
+exit Woods::AgentConfiguration::CLI.new.run(ARGV)

data/exe/woods-extract

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'woods/source_inputs/launcher'
+exit Woods::SourceInputs::Launcher.run(ARGV)

data/exe/woods-hook-context

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'woods/hooks/context_cli'
+
+exit Woods::Hooks::ContextCLI.run(ARGV.first)

data/exe/woods-mcp-start

@@ -7,7 +7,7 @@
 # same as when launched directly. RubyGems loads gem executables as Ruby, so
 # this wrapper must remain a Ruby program when packaged.
 
-index_dir = ARGV[0] || ENV.fetch('WOODS_DIR', nil)
+index_dir = ARGV[0] || ENV.fetch('WOODS_DIR', nil) || ENV.fetch('WOODS_OUTPUT', nil)
 
 if index_dir.nil? || index_dir.empty?
   warn 'Error: No index directory specified.'
@@ -15,9 +15,13 @@ if index_dir.nil? || index_dir.empty?
   exit 1
 end
 
+index_dir = File.expand_path(index_dir)
+path_remedy = 'Point at the existing index with an explicit path, WOODS_DIR, or WOODS_OUTPUT. ' \
+              'If no index exists, run `bundle exec rake woods:extract` in your Rails app.'
+
 unless File.directory?(index_dir)
   warn "Error: Index directory does not exist: #{index_dir}"
-  warn 'Run extraction first: bundle exec rake woods:extract'
+  warn path_remedy
   exit 1
 end
 
@@ -27,7 +31,7 @@ end
 # whole library just to check one file is wasted work on every boot. A
 # payload-born index has no manifest.json at the root — it lives under the
 # directory generation.json's `payload` pointer names — so the pointer is
-# followed here too, with the same escape guard, before concluding the
+# followed here too, with the same realpath containment check, before concluding the
 # directory holds no index. woods-mcp re-checks this properly through
 # Bootstrapper regardless; this is just an early, friendlier exit.
 def manifest_present?(index_dir)
@@ -39,20 +43,21 @@ def manifest_present?(index_dir)
   require 'json'
   require_relative '../lib/woods/atomic_file'
   payload_name = JSON.parse(Woods::AtomicFile.read(generation_path))['payload']
-  return false if payload_name.nil? || payload_name.empty?
+  return false unless payload_name.is_a?(String) && !payload_name.empty?
 
-  root = File.expand_path(index_dir)
-  candidate = File.expand_path(File.join(root, payload_name))
+  root = File.realpath(index_dir)
+  candidate = File.realpath(payload_name, root)
   return false unless candidate.start_with?("#{root}#{File::SEPARATOR}")
 
   File.file?(File.join(candidate, 'manifest.json'))
-rescue JSON::ParserError, SystemCallError
+rescue JSON::ParserError, SystemCallError, TypeError, NoMethodError
   false
 end
 
 unless manifest_present?(index_dir)
-  warn "Error: No manifest.json in: #{index_dir}"
-  warn 'Run extraction first: bundle exec rake woods:extract'
+  warn "Error: Could not resolve a published Woods index in: #{index_dir}"
+  warn 'Expected generation.json pointing to a payload manifest.json, or a legacy flat manifest.json.'
+  warn path_remedy
   exit 1
 end
 

data/lib/generators/woods/pgvector_generator.rb

@@ -2,6 +2,7 @@
 
 require 'rails/generators'
 require 'rails/generators/active_record'
+require 'woods/storage/pgvector'
 
 module Woods
   module Generators
@@ -15,7 +16,7 @@ module Woods
     #
     # Usage:
     #   rails generate woods:pgvector
-    #   rails generate woods:pgvector --dimensions 3072
+    #   rails generate woods:pgvector --dimensions 768
     #
     class PgvectorGenerator < Rails::Generators::Base
       include ActiveRecord::Generators::Migration
@@ -25,11 +26,16 @@ module Woods
       desc 'Creates the woods_vectors table (pgvector column + HNSW index) used by the Woods vector store'
 
       class_option :dimensions, type: :numeric, default: 1536,
-                                desc: 'Vector dimensions (1536 for text-embedding-3-small, 3072 for large)'
+                                desc: 'Vector dimensions (1-2000; default 1536 for text-embedding-3-small)'
 
       # @return [void]
       def create_migration_file
         @dimensions = options[:dimensions]
+        maximum = Woods::Storage::VectorStore::Pgvector::MAX_HNSW_DIMENSIONS
+        unless @dimensions.is_a?(Integer) && @dimensions.between?(1, maximum)
+          raise ArgumentError, "dimensions must be a positive Integer no greater than #{maximum} for pgvector HNSW"
+        end
+
         migration_template(
           'add_pgvector_to_woods.rb.erb',
           'db/migrate/add_pgvector_to_woods.rb'

data/lib/generators/woods/templates/woods.rb.tt

@@ -24,9 +24,6 @@ Woods.configure do |config|
   # Maximum tokens returned in a retrieval context window.
   # config.max_context_tokens = 8_000
 
-  # Minimum vector similarity score (0.0–1.0) for retrieval results.
-  # config.similarity_threshold = 0.7
-
   # Output format for retrieval: :claude, :markdown, :plain, :json
   # config.context_format = :markdown
 
@@ -124,6 +121,7 @@ Woods.configure do |config|
   #              HTTP calls, callbacks, threads, or other connections/shards.
 
   # config.console_mcp_enabled = false
+  # config.console_mcp_http_enabled = true  # set false for stdio-only Console use
   # config.console_mcp_path    = '/mcp/console'
 
   # Console HTTP requires a strong bearer token. Its Origin/Host guard is