woods 2.0.1 → 2.1.0

data/docs/UNBLOCKED_INTEGRATION.md

@@ -241,11 +241,64 @@ document id of everything last pushed. On each run the exporter:
 - **pushes** only new or changed documents,
 - **deletes** documents whose source unit has disappeared.
 
-Documents are upserted by URI, so the sync is always safe to re-run. If the
-manifest is missing (first run, or a CI cache miss) the exporter reconciles
-document ids from the remote collection and falls back to a full re-push,
-rebuilding the manifest, correct, just more API calls than one run. In steady
-state an unchanged codebase costs ~0 calls.
+Documents are upserted by URI. **Included in Woods 2.1:** the manifest keeps
+separate repository/ref scopes; switching branches preserves the other branch's
+documents. Ref segments are URL-encoded, including `#`, `?`, and `%`.
+
+Every sync first inventories remote documents through all pages. A short page
+is not proof of completion; malformed pages or repeated cursors stop before
+writes. Individual remote documents without a non-empty string URI are skipped;
+they provide no URI ownership evidence. This adds listing calls even when all
+local documents are unchanged.
+URIs are unique across the remote organization: Woods refuses a URI already
+assigned to another collection instead of moving it.
+
+A missing manifest rebuilds receipts for current documents but does **not**
+adopt unrelated remote documents for deletion. Keep the manifest in a durable
+CI cache. An unreadable, corrupt, or wrong-collection manifest requires recovery
+from a known-good copy; setting force flags cannot recover ownership. Historical
+entries adopted remotely with a null content hash are not deletion authority.
+
+### Explicit ref migration
+
+**Included in Woods 2.1:** unresolved owned receipts from a legacy manifest
+leave sync incomplete. A URI prefix cannot prove the old ref: a slash can belong
+to either a ref name or a source path. Woods never adopts or purges those
+receipts by prefix. Select the known source ref with
+`UNBLOCKED_MIGRATE_FROM_REF`, or review obsolete remote documents and their
+legacy receipts for manual cleanup when there is no current replacement.
+`UNBLOCKED_FORCE_PURGE` cannot bypass this ownership requirement.
+
+Use migration only when retiring the old export scope, rather than publishing
+two branches independently. Keep one writer per local manifest **and** remote
+repository/ref scope; coordinate writers across worktrees and CI jobs.
+
+```bash
+UNBLOCKED_MIGRATE_FROM_REF=old-branch UNBLOCKED_DRY_RUN=1 bin/rails woods:unblocked_sync
+UNBLOCKED_MIGRATE_FROM_REF=old-branch bin/rails woods:unblocked_sync
+```
+
+Preview reads the pinned index and local receipts, makes no remote requests or
+local writes, and lists the proposed URI pairs. Review that list before applying.
+Use the same source and target ref to migrate formerly unescaped special-character
+URIs. Woods uploads replacements, persists successful receipts, then deletes
+only recorded old IDs with unambiguous current replacements. This bounded
+one-for-one cleanup does not require `UNBLOCKED_FORCE_PURGE`.
+
+Interrupted migration resumes on the next sync of the target scope, even without
+the environment variable. Missing ownership, changed remote IDs, missing
+replacements, failed writes, and incomplete cleanup remain visible as incomplete;
+Woods retains old copies until it can verify the replacement. It never infers
+ownership from the collection listing. Records without matching replacement
+units require operator review and manual cleanup. A historical bare URI shared
+by multiple current units is ambiguous and is also retained for review; Woods
+does not guess its old owner from the new lexically first identifier. Proven
+one-to-one migrations also upload replacements outside the ordinary top-N cap. This is not an API-level
+rename: remote IDs can change, so annotations attached to the old ID may not move.
+
+Do not run an older Woods exporter against the upgraded version-2 manifest.
+For rollback, stop sync and restore its pre-migration manifest together with the
+corresponding remote state; restoring just the file cannot undo remote deletions.
 
 Pair with `woods:incremental` to re-extract only changed files; the sync then
 pushes only the documents whose content actually changed.
@@ -273,10 +326,9 @@ enumeration or complete per-bucket listings plus strict typed lookup.
   is a small subset and an unguarded purge would wipe the collection.
 
   The guard also fires on *intentional* large removals: dropping a unit type
-  from the sync set, changing `unblocked_repo_url` (every URI changes), or a
-  big codebase deletion can all legitimately exceed 30%. The refusal warning
+  from the sync set or a big codebase deletion can all legitimately exceed 30%. The refusal warning
   names the counts, if the deletions are expected, re-run once with
-  `UNBLOCKED_FORCE_PURGE=1`.
+  `UNBLOCKED_FORCE_PURGE=1`. It does not bypass migration ownership checks.
 
 ## Troubleshooting
 

data/docs/UPGRADING_TO_2.md

@@ -8,35 +8,6 @@ published 1.6.x security patch as the rollback version.
 <!-- release-state:upgrade-availability -->
 <!-- release-state:end -->
 
-## 2.0.1 security maintenance update
-
-This maintenance line adds Console request/output policy corrections and isolates
-retrieval contexts between retriever instances. It does not add the graph or
-extraction features under development for 2.1. Confirm the installed package
-version and use its matching tag documentation.
-
-No index or database schema migration is required. Restart Console/MCP processes
-after upgrading. Explicit malformed HTTP origin entries now fail at boot with the
-offending entry named; fix the entry rather than weakening authentication.
-Automatic and manual Console mounts raise `Woods::ConfigurationError` for these
-settings, including invalidly encoded entries. With
-no allowlist configured, the existing loopback defaults remain unchanged. See
-[HTTP origin matching](MCP_HTTP_TRANSPORT.md#browser-origins-dns-rebinding-defense).
-
-Raw `console_sql` now refuses ambiguous protected results and genuinely unknown
-adapter families. PostgreSQL-subclass adapters retain PostgreSQL handling;
-structured Console tools remain available with other adapters. Prefer explicit
-unaliased scalar projections or structured reads when a query is refused.
-[Console setup](CONSOLE_MCP_SETUP.md#maintenance-policy-corrections) describes the
-compatibility boundary. Context caches refill after restart; retired entries
-follow the configured TTL or backend eviction. See
-[retrieval cache options](CONFIGURATION_REFERENCE.md#retrieval-cache-options).
-Rolling back restores the affected behavior.
-
-Polymorphic `belongs_to` association counts remain unsupported in 2.0.1 and
-1.6.4 and return a generic execution error; the 2.1 functional correction is
-not backported.
-
 ## Upgrade outcome
 
 After this runbook you will have:
@@ -48,6 +19,21 @@ After this runbook you will have:
 - an MCP client connected to the v2 packaged tool surface;
 - a documented way back to v1 if verification fails.
 
+### HTTP configuration checks
+
+Supporting revisions after 2.0.0 validate HTTP origin allowlists at boot.
+Enabled automatic and manual Console mounts use the same
+`Woods::ConfigurationError` diagnostic for malformed origin entries. An invalid
+entry now prevents enabled HTTP startup and the diagnostic names that entry.
+Use `http(s)://host[:port]` entries without paths, credentials, or query strings,
+then restart. With no explicit Index allowlist, the default policy is unchanged.
+An explicit list replaces browser-origin defaults, including loopback. HTTP(S)
+default ports are equivalent to their omitted form. Stdio-only Console users can
+keep `console_mcp_http_enabled = false`.
+
+See [HTTP origins](MCP_HTTP_TRANSPORT.md#browser-origins-dns-rebinding-defense)
+and [Console setup](CONSOLE_MCP_SETUP.md) for the configuration contract.
+
 ### Console read compatibility
 
 For supporting security-patch revisions, any nonempty column or EAV redaction
@@ -90,8 +76,9 @@ eviction; disabling both can retain them indefinitely. See
 | `mcp >= 1.2, < 2.0` and protocol negotiation | Old lockfiles or manually pinned protocol versions can fail | Bundle update Woods/MCP; normally leave protocol version unset |
 | Index MCP surface aligned to executable wiring | Agents may ask for tools that only exist as conditional schemas | Update agent instructions to the 14-tool default |
 | Console surface tightened to 9 or 11 tools | Agents may ask for Tier 2/3 or eval schemas that do not execute | Use registered default/read tools only |
-| Missing-token behavior changed outside production | An enabled Console HTTP endpoint now stays mounted but returns 401 without a valid token; production still refuses to boot without one | Preserve or configure a secret token of at least 32 characters; send it only to the HTTP transport |
+| Console HTTP validation uses finalized application configuration | Flags set in a 1.x initializer could miss early boot validation; v2 refuses a missing token in production and a configured short token in any environment | Configure a secret token of at least 32 characters, or explicitly disable HTTP for stdio-only use |
 | Durable-store reconciliation and a 30% purge guard | The first v2 embed may refuse a legitimate rename-heavy deletion | Back up, inspect the deletion, then use the one-run override only if correct |
+| Explicit `config.embedding_model` selects the embedding model | An old assignment that embedding ignored can now change the produced vectors; `embedding_options[:model]` takes precedence | Verify the effective model and rebuild embeddings when it changes, even if the dimension stays the same |
 | Embedding dimension preflight | A previously tolerated model/store mismatch now fails before writing | Rebuild into a store with the configured dimension |
 | Export reconciliation guards | Obsidian or Unblocked can refuse a rename-heavy stale-document sweep | Back up and use exporter-specific override only after review |
 | Notion column pages are grouped by physical table | Models sharing a table (STI, a shared `self.table_name`) previously rewrote each other's column pages on every run | Re-sync once after re-extraction; the shared pages settle and the churn stops |
@@ -101,8 +88,25 @@ eviction; disabling both can retain them indefinitely. See
 | `woods:embed`, `woods:embed_incremental`, and `woods:notion_sync` exit 1 on reported errors | CI jobs that were green while every unit or page failed now fail | Read the printed errors, fix the cause, re-run; completed work is durable |
 | The Index MCP `reload` tool needs write access to the index directory | A read-only index mount can serve structural reads but cannot reload in place | Grant write access, or restart the MCP process after publishing |
 | `config.extractors` and `config.add_gem` warn as unimplemented | Old config may imply filtering that never occurred | Remove or comment the settings; do not rely on them |
+| Legacy `config.log_level=` removed | The old no-op assignment raises `NoMethodError` | Remove it; configure the application logger instead |
+| Legacy unsafe-eval opt-in removed | `WOODS_CONSOLE_UNSAFE_EVAL=true`, an enabled `console_unsafe_eval_enabled`, or legacy confirmation/audit options refuse Console server construction | Remove these settings; use supported read tools or the application’s normal console for deliberate code execution |
 | New watch, refresh, and evaluation tasks | New operational options become available | Optional; no migration action |
 
+## Updating an existing 2.0 installation to 2.1
+
+After selecting Woods 2.1 in the application bundle, keep the last good index and
+run one full `bin/rails woods:extract`, followed by `bin/rails woods:validate`.
+This establishes source-reference cache format 3 and repairs affected discovery
+identities. Incremental extraction requires that compatible baseline. Rebuild
+embeddings and exports if the identifiers they store changed; restart MCP to load
+the new gem. A reader upgrade alone cannot add relationships to an older index.
+
+The expanded references remain conservative: component callers and unresolved
+runtime scopes are not exhaustively covered. Full and incremental results can
+still differ in `dependents` presentation order without changing membership.
+Large affected sets may cost as much as a full extraction; choose full extraction
+for those workloads rather than assuming every incremental run is faster.
+
 ## Before changing the bundle
 
 ### Check the loader for wrapper-nested classes
@@ -124,6 +128,39 @@ extraction. Rebuild embeddings and exports if identifiers change. A genuine
 duplicate under a supported loader still needs distinct constants or one source
 file. Woods does not provide a classic-mode naming fallback for this case.
 
+Woods 2.0.0 can also misidentify valid Struct/Data assignments inside namespace
+wrappers on supported loaders ([#559](https://github.com/lost-in-the/woods/issues/559)).
+**Included in Woods 2.1:** supporting writers verify the loaded
+assignment's identity and source ownership for PORO and library units. Check
+the exact writer revision, then follow the [assigned value-class rules](EXTRACTOR_REFERENCE.md#assigned-value-classes).
+Run a full extraction to repair old wrapper identities and rebuild reference-cache
+format 3; incremental extraction refuses older formats. Keep the previous
+generation until that rebuild succeeds. Do not rename valid application constants
+to work around an older writer's inference.
+
+**Included in Woods 2.1:** the collision guard also applies to incremental
+extraction and targeted refresh ([#561](https://github.com/lost-in-the/woods/issues/561)).
+Those paths previously could publish a conflicting source that a full extraction
+would reject. Refusal leaves the last published generation readable. If an older
+run already replaced a unit's owner, fixing the guard alone cannot reconstruct
+the lost unit: correct the producer/source issue and run a successful full
+extraction, then validate it. Keep the previous generation until the rebuild
+succeeds; do not delete the index to bypass the collision.
+
+### Refresh GraphQL discovery on a supporting writer
+
+**Included in Woods 2.1:** the discovery fixes for
+[#558](https://github.com/lost-in-the/woods/issues/558),
+[#562](https://github.com/lost-in-the/woods/issues/562) and
+[#563](https://github.com/lost-in-the/woods/issues/563) add schema-class units,
+loaded resolver subclasses and types from every application schema. Schemas use
+the existing `graphql_type` category with `metadata.graphql_kind: "schema"`.
+Verify the loaded writer revision, boot/eager-load the intended application,
+then run a full extraction and validate to fill gaps in older indexes. Readers
+can continue serving the previous generation until publication succeeds.
+See [GraphQL extraction](EXTRACTOR_REFERENCE.md#graphqlextractor) for runtime
+ownership, query-root classification, handled failures and source-fallback limits.
+
 ### 1. Record the current installation
 
 Run in the same environment that boots Rails:
@@ -139,7 +176,13 @@ Record the current Woods version, output directory, storage preset/providers, em
 
 ### 2. Back up durable data
 
-The generated structural index can be recreated, but its location may also hold local vector dumps and exporter manifests. Copy or snapshot the complete configured output directory before cleaning it.
+The generated structural index can be recreated, but its location may also hold
+`woods.sqlite3` snapshot history, JSON `snapshots/`, local vector dumps and exporter
+manifests. Stop Woods writers/readers, including the watcher, before taking an
+offline copy or consistent filesystem snapshot of the complete output directory.
+For SQLite, use a database-aware backup or close its users before copying; a live
+main-file-only copy can omit data still in the WAL. Back up explicitly configured
+stores outside the output directory separately.
 
 Back up external vector stores separately:
 
@@ -189,26 +232,73 @@ Pay particular attention to:
 - the configured embedding model/dimension;
 - `console_mcp_enabled`, `console_mcp_http_enabled`, the HTTP `console_mcp_token` secret source, allowed origins, path, and embedded read-tool flags;
 - snapshot, session, Notion, Obsidian, and Unblocked settings;
-- old `config.extractors` or `config.add_gem` calls, which are not implemented selectors.
+- old `config.extractors` or `config.add_gem` calls, which are not implemented selectors;
+- removed `config.log_level=` and unsafe-eval settings;
+- early middleware configuration: a custom `console_mcp_path` and session tracer
+  setup belong in `config/application.rb`, before Railtie initializers run. See
+  [Console configuration](CONSOLE_MCP_SETUP.md#configuration-options) and
+  [session tracer options](CONFIGURATION_REFERENCE.md#session-tracer-options).
 
 Review existing Woods migrations and tables before accepting any newly generated migration. Do not create duplicate `woods_units`, `woods_edges`, or `woods_embeddings` tables.
 
 ### 3. Clean and re-extract
 
-After the backup is verified:
+After the backup is verified and Woods processes are stopped:
 
 ```bash
 bin/rails woods:clean
+```
+
+**Cleaning deletes durable history inside this directory too:** `woods.sqlite3`,
+JSON `snapshots/`, vector dumps and export manifests. Before running extraction,
+choose how to retain history:
+
+- Keep the complete backup as a separate historical/rollback copy and start a new
+  v2 history; or
+- Restore only the closed, consistent `woods.sqlite3` backup and/or `snapshots/`
+  directory into the cleaned output. Woods migrates the snapshot database on
+  its next use. Do not restore the old structural payload, `generation.json`,
+  vector dumps or export manifests into this new baseline.
+
+Restoring JSON files does not import them into SQLite. If SQLite has become
+available since JSON capture, extraction and packaged MCP prefer it; keep an
+explicit JSON historical reader for the restored files. `WOODS_SNAPSHOTS=true`
+enables snapshot construction without forcing that backend. See
+[snapshot store selection](MCP_SERVERS.md#conditional-index-capabilities).
+
+Then run:
+
+```bash
 bin/rails woods:extract
 bin/rails woods:validate
 bin/rails woods:stats
 ```
 
+If you carried history forward, verify an old snapshot remains readable before
+restarting writers. A full capture at an existing Git SHA replaces that SHA's
+snapshot, and configured retention can prune old entries. Keep the untouched
+backup through the rollback window.
+
 Included in Woods `2.0.0`: `woods:clean` removes index artifacts but keeps
 the output directory and its hidden extraction guard. This stable guard lets
 concurrent writers coordinate safely; its presence does not mean an index remains.
 
-The clean extract is required for corrected identifier shapes. Do not use an incremental run as the first v2 extraction: after `woods:clean` there is no baseline, and v2 `woods:incremental` refuses that state rather than publishing a near-empty index as the application's complete truth.
+The clean extract is required for corrected identifier shapes. Do not use
+incremental extraction, targeted refresh or an embedded pipeline's incremental
+operation as the first v2 run. A flat index being readable, a successful
+`woods:validate`, or a newer manifest `woods_version` does not certify that all
+retained v1 units were migrated. After cleaning there is no structural baseline,
+and incremental extraction refuses that state. **Included in Woods 2.1:**
+incremental extraction and targeted refresh also refuse a flat index with a
+manifest, or a generation whose manifest names a writer major version below 2,
+before creating a new payload. Run a full `woods:extract` to rebuild it. A
+missing writer field in a generation manifest is allowed for early v2 betas;
+readers retain legacy compatibility. This guard cannot detect v1 units already
+retained by an older incremental writer that relabeled its manifest as v2.
+Supporting source-reference writers also refuse incompatible reference caches.
+CI caches must distinguish Woods major versions
+and restore the exact source baseline described in the
+[incremental CI recipe](INCREMENTAL_EXTRACTION.md#github-actions-with-an-exact-baseline).
 
 An interrupted extraction leaves readers on the last complete generation because Woods publishes `generation.json` only after the payload is complete. Re-run the task; do not delete a partial directory speculatively. A run that completes its payload but cannot publish the marker now fails loudly instead of reporting success, so treat a non-zero exit as work to redo rather than as a partial success.
 
@@ -237,7 +327,13 @@ WOODS_ALLOW_PURGE=1 bin/rails woods:embed
 
 The override permits deletion; it is not a repair command. Do not set it permanently.
 
-If Woods reports a dimension mismatch, verify the configured embedding model. Rebuild into a store created for the new dimension. Vectors cannot be converted in place.
+An explicitly assigned `config.embedding_model` now selects the model used to
+embed, unless `embedding_options[:model]` overrides it. Earlier embedding could
+ignore that assignment even though query configuration recorded it. Verify the
+effective model before the first embed. A model change requires rebuilding vectors
+even when both models have the same width. A dimension mismatch additionally
+requires a store created for the new dimension; vectors cannot be converted in
+place.
 
 An interrupted embed is safe to re-run; durable checkpoints resume or repair the missing unit.
 
@@ -253,6 +349,14 @@ Re-run every export after extraction and embeddings are verified. Renamed identi
 
 Review the target and backup before any force-purge override. Use `WOODS_NOTION_FORCE=1` only when you intentionally want Notion to re-check unchanged content hashes.
 
+**Included in Woods 2.1:** Unblocked keeps separate repository/ref scopes.
+Legacy receipts that cannot be assigned safely leave sync incomplete, including
+old exports from a non-`main` ref. Preview an explicit
+`UNBLOCKED_MIGRATE_FROM_REF=<old-ref>` migration; review obsolete documents with
+no current replacement for manual remote and receipt cleanup. Woods does not
+infer ownership from a URI prefix, and `UNBLOCKED_FORCE_PURGE` cannot resolve it.
+Follow [explicit ref migration](UNBLOCKED_INTEGRATION.md#explicit-ref-migration).
+
 **Notion needs one settling re-sync.** v2 groups column pages by physical table instead of by model, so models that share a table write one page per physical column, with the `Table` relation listing every owning model and their validations unioned. The page titles, and therefore the manifest keys, are unchanged, but the content hash of every shared-table column changes once. Expect the first post-upgrade `woods:notion_sync` to update those pages; subsequent runs skip them. This also ends the v1 behavior where two models sharing a table rewrote the same column page back and forth on every run. See [Notion integration](NOTION_INTEGRATION.md).
 
 ## Update CI and scheduled automation
@@ -311,7 +415,8 @@ names and count same-named typed variants once, matching name-based ground truth
 Older dumps remain readable; re-embed to recover variants
 that an older writer had already overwritten.
 
-SQLite migration 007 preserves snapshot rows and permits one row per
+SQLite migration 007 preserves rows **in a database that was retained or restored**;
+it cannot recover a database deleted by `woods:clean`. It permits one row per
 `(snapshot_id, identifier, unit_type)`. JSON snapshot readers accept older untyped
 records, while new records preserve both names and types. Lost historical variants
 cannot be reconstructed from old snapshots. Back up `woods.sqlite3` and the whole
@@ -346,6 +451,10 @@ Update agent prompts that refer to the old inventory. Standard Index launch prov
 
 Structural reads still work from a read-only index mount, but the `reload` tool does not: its transactional refresh takes the same on-disk writer lock as extraction and embedding, so the MCP process needs write access to the index directory. Without it, `reload` returns a typed degraded error and keeps serving the previous aligned generation rather than swapping in a partial one. Grant write access, or restart the MCP process after publishing. [MCP servers](MCP_SERVERS.md) owns the detail.
 
+**Included in Woods 2.1:** `:local` snapshot vectors and SQLite metadata cannot
+reload atomically in the running server, even with write access. Restart
+`woods-mcp` after `woods:embed` when using that preset.
+
 ### Console users: preserve or configure the HTTP token
 
 If HTTP Console is enabled, preserve or configure a secret token of at least
@@ -358,8 +467,11 @@ Stdio does not use a bearer token. On versions supporting
 `console_mcp_http_enabled`, set it to `false` for stdio-only use without HTTP
 boot validation, while keeping the master `console_mcp_enabled` flag on.
 The HTTP flag defaults to `true` to preserve existing deployments; choosing a
-stdio client alone does not turn HTTP off. Older versions without this flag
-still require a token at production boot whenever Console is enabled.
+stdio client alone does not turn HTTP off. In some 1.x paths, flags assigned in
+`config/initializers/woods.rb` were read too early to trigger boot validation.
+v2 validates the settled configuration after initializers: the same application
+can now fail boot until its token is corrected or HTTP is explicitly disabled.
+Do not rely on the earlier validation timing as a supported configuration.
 
 Follow [Console MCP setup](CONSOLE_MCP_SETUP.md) for transport-specific setup
 and the [Configuration reference](CONFIGURATION_REFERENCE.md) for defaults.
@@ -378,6 +490,9 @@ Complete every applicable check:
 - [ ] `search`, `lookup`, and `dependents` work with v2 identifiers.
 - [ ] Semantic retrieval works after re-embedding, if enabled.
 - [ ] Console exposes only the authorized 9/11 tools, if enabled.
+- [ ] Legacy `config.log_level=` and unsafe-eval settings were removed.
+- [ ] Custom Console path and session tracing settings are configured before Railtie initialization.
+- [ ] Retained snapshot history is readable, and its untouched backup remains available.
 - [ ] An enabled Console reads a token of at least 32 characters from a secret source; its value was not printed or committed.
 - [ ] Console HTTP rejects a request without the bearer token with 401 and accepts the configured client, if HTTP is used.
 - [ ] Console stdio starts through the application bundle, if stdio is used.

data/docs/WATCH_DAEMON.md

@@ -116,9 +116,17 @@ supported. Do not prepend an `environment` task or an already booted Rails runne
 The generator records relative owned paths and fingerprints in `.woods-watch.json`.
 Commit it with the generated configuration so a new clone/worktree can update or
 remove that setup. Runtime transaction state stays under `tmp/woods-watch-install/`;
-keep that directory ignored. Changes to owned content or executable permissions
-cause a conflict rather than an overwrite. Review the conflict and restore or
-adapt the owned setup explicitly; do not delete the receipt to force an overwrite.
+keep that directory ignored. Changes to owned content or removal of the owner's
+executable bit cause a conflict rather than an overwrite. Review the conflict
+and restore or adapt the owned setup explicitly; do not delete the receipt to
+force an overwrite.
+
+Included in Woods 2.1: ownership compares the executable bit Git records,
+so ordinary checkout permissions such as `0755` and `0775` both retain ownership.
+Older builds compare the entire mode and can refuse setup in a clone made under
+a different umask. Record the loaded revision before relying on this fix.
+Saved preview/apply snapshots still check exact permissions: a chmod after a
+preview of that file requires a fresh preview.
 
 ```bash
 # Change modes or update owned setup (include the selected mode's options).
@@ -178,6 +186,56 @@ There is no automatic ownership takeover. Managed duplicate prevention is scoped
 to one host/process namespace; do not mix raw and managed writers across different
 containers sharing an index. Use one external owner for that arrangement.
 
+**Included in Woods 2.1 ([#591](https://github.com/lost-in-the/woods/issues/591)):**
+empty and whitespace-only idle-timeout values behave as unset in the task,
+launcher and installer. Earlier builds accepted an empty value in managed
+validation but crashed during task startup; unset it when using those builds.
+
+### Recovering an abandoned managed claim
+
+**Included in Woods 2.1; verify `woods-watch --help` before using this command.**
+New managed daemons hold a lifetime filesystem lock in `watch_claim.json.lease`.
+The Rails child holds it throughout startup, extraction and shutdown, independently
+of its launcher. Its `watch_claim.json` records a fresh `token` and lease identity.
+After the original owner/container has stopped, inspect the claim at the exact
+index used by the application, then select its token explicitly:
+
+```bash
+bundle exec woods-watch --recover-claim /app/tmp/woods --claim-token TOKEN_FROM_CLAIM
+```
+
+Run this inside the environment that can access that index and its sidecars.
+Recovery does not boot Rails or start a watcher. It holds both the startup
+coordination lock and lifetime lease, checks the token and lease inode, and
+removes only the selected abandoned claim. Restart the normal Foreman/Puma/external
+owner afterward and verify startup reconciliation. Tokens select a claim; they
+are not credentials. A changed token means another owner claimed the index:
+inspect it rather than repeatedly substituting tokens.
+
+Recovery preserves the old status record. Keep the reader-only
+`WOODS_WATCH_TRUST_FOREIGN_HOST` override unset in the owner startup environment;
+otherwise its existing status precheck can honor the retired container's last
+heartbeat until the normal 15-minute freshness bound expires. Lifetime lease
+protection remains active without that override.
+
+A live local or foreign owner keeps its lease even if its claim is old. Recovery
+refuses a held lock, unknown protocol, missing/replaced lease, malformed record,
+or unavailable locking. Claim age, heartbeat age and a PID in a different container
+never prove abandonment. The filesystem must support cooperative `flock` across
+every process sharing the index; this is not a distributed lease service. Do not
+mix old/raw writers with managed ownership across containers. Never unlink,
+replace or recreate the `.lease` or `.lock` sidecars while writers may exist.
+`woods:clean` preserves these sidecars and the claim, including during forced
+cleanup; it does not reset watcher ownership.
+
+Legacy claims have no lifetime-lease proof and cannot use this command. Stop
+their original owner through its process manager. If the original namespace is
+gone and ownership cannot be verified, choose a new empty output directory,
+configure exactly one writer and its readers to use it, and run a fresh full
+extraction. Keep the old index until the replacement is verified. This recovery
+does not require deleting the unverifiable claim or guessing whether its PID is
+dead. Upgrading Woods alone does not rewrite a live or abandoned legacy claim.
+
 Daemon liveness, completed startup reconciliation, and source freshness remain
 different facts. Managed supervision records under `watch_supervisors/` expose
 starting/retrying/parked state separately in `woods_status`; an alive supervisor
@@ -329,15 +387,27 @@ against a settled boot configuration. If Rails is already initialized or the
 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
-storm threshold correctly turns that into one full extraction. A marker whose
-payload pointer no longer resolves counts as no index too: the marker can
-outlive the directory it names (a partial restore from a CI artifact, an
-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.
+So `run` reconciles before it waits. Supporting Git builds record source
+capture start as optional `captured_at` metadata in the generation's
+`source_inputs.json`. Startup considers files modified from that boundary,
+rounded down to include the entire second on coarse filesystems, plus recorded
+source-change error paths. Publication time is too late: a file can change
+between capture and publication, including after final source verification.
+
+A bounded content scan excludes candidates only when their recorded consumer
+identities all match the current bytes. Unchanged files in the capture second
+therefore do not repeatedly trigger extraction. Missing identity evidence keeps
+the candidate uncovered. This startup check is not a full source-freshness
+certification; use [`source_freshness`](SOURCE_FRESHNESS.md) for that evidence.
+
+An older index without this capture boundary, or one with invalid/mismatched
+metadata or a dangling payload pointer, receives a full reconciliation under
+the same reload/restart rules. A successful full publication records the new
+boundary even when no incremental units would change, so the migration does
+not repeat on every startup. With no generation at all, every file is uncovered
+and the normal storm threshold applies. On older installed versions that still
+use the marker mtime, recover by completing a full extraction against settled
+source before restarting watch.
 
 **The built-in watcher establishes detection before reconciliation runs.**
 Polling signals readiness after its baseline scan; native watching signals after
@@ -350,8 +420,8 @@ 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
 inside `start`, after the save, so its first diff already excluded it. Worse,
 the save's mtime predates the generation bump catch-up publishes at the end, so
-a future restart's watermark check would read the file as already covered,
-permanently. Starting the watcher first closes that window; `enqueue`/`drain`
+older marker-based catch-up could miss it again on restart. Starting the watcher
+first closes the live-event window; `enqueue`/`drain`
 already tolerate the duplicate paths this produces against whatever catch-up
 finds on its own via the tree scan.
 
@@ -366,6 +436,19 @@ convention path no app has), which authoritative deletion would wrongly remove.
 The sweep carries the bounds that make reconciliation safe; the daemon only
 supplies the trigger.
 
+**Included in Woods 2.1:** if that deletion-only cycle fails or cannot take the
+extraction lock, the daemon keeps a reconciliation obligation even though its
+path list is empty. The next event or heartbeat retries the bounded sweep;
+successful reconciliation clears the obligation, including a genuine no-op
+for a nominal framework path. A restart rediscovers outstanding deletions from
+the unchanged published graph.
+
+The daemon also checks the extractor's publication error before accepting an
+empty touched-unit list. Removing disabled precomputed flow artifacts changes
+the payload without necessarily changing any units. If publication fails, the
+previous generation remains active, status stays degraded, and the event is
+retained for retry.
+
 This is what makes the documented hook pattern safe:
 
 ```bash

data/exe/woods-console-mcp

@@ -7,7 +7,7 @@
 # Configuration precedence:
 #   1. WOODS_CONSOLE_CONFIG, when set (the file must exist)
 #   2. ~/.woods/console.yml, when present
-#   3. direct mode with `bundle exec rake woods:console`
+#   3. direct mode with executable app bin/rake, otherwise bundle exec rake
 
 require 'yaml'
 require_relative '../lib/woods/console/connection_manager'
@@ -22,7 +22,7 @@ end
 
 begin
   config = File.file?(config_path) ? YAML.safe_load_file(config_path, aliases: false) : {}
-  config ||= {}
+  config = {} if config.nil?
   raise Woods::Console::ConnectionError, "#{config_path} must contain a YAML mapping" unless config.is_a?(Hash)
 
   Woods::Console::ConnectionManager.new(config: config).replace_process!

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

@@ -122,7 +122,8 @@ Woods.configure do |config|
 
   # config.console_mcp_enabled = false
   # config.console_mcp_http_enabled = true  # set false for stdio-only Console use
-  # config.console_mcp_path    = '/mcp/console'
+  # A custom console_mcp_path belongs in config/application.rb before Railtie
+  # initialization, not this initializer. The default is '/mcp/console'.
 
   # Console HTTP requires a strong bearer token. Its Origin/Host guard is
   # loopback-only by default; list the public MCP host and any browser client