clawmem 0.7.2 → 0.8.0

package/AGENTS.md

@@ -96,6 +96,14 @@ curl http://host:8090/v1/models
 | `CLAWMEM_ENABLE_AMEM` | enabled | A-MEM note construction + link generation during indexing. |
 | `CLAWMEM_ENABLE_CONSOLIDATION` | disabled | Background worker backfills unenriched docs. Needs long-lived MCP process. |
 | `CLAWMEM_CONSOLIDATION_INTERVAL` | 300000 | Worker interval in ms (min 15000). |
+| `CLAWMEM_HEAVY_LANE` | disabled | **v0.8.0.** Enable the quiet-window heavy maintenance worker — a second, longer-interval consolidation lane with DB-backed `worker_leases` exclusivity, stale-first batching, and `maintenance_runs` journaling. Runs alongside the light lane; off by default. |
+| `CLAWMEM_HEAVY_LANE_INTERVAL` | 1800000 | **v0.8.0.** Heavy-lane tick interval in ms (min 30000, default 30 min). |
+| `CLAWMEM_HEAVY_LANE_WINDOW_START` | (none) | **v0.8.0.** Start hour (0-23) of the quiet window. Unset → no window. |
+| `CLAWMEM_HEAVY_LANE_WINDOW_END` | (none) | **v0.8.0.** End hour (0-23, exclusive) of the quiet window. Supports midnight wrap (22→6). |
+| `CLAWMEM_HEAVY_LANE_MAX_USAGES` | 30 | **v0.8.0.** Max `context_usage` rows in the last 10 min before the heavy lane skips with `reason='query_rate_high'`. |
+| `CLAWMEM_HEAVY_LANE_OBS_LIMIT` | 100 | **v0.8.0.** Phase 2 stale-first observation batch size. |
+| `CLAWMEM_HEAVY_LANE_DED_LIMIT` | 40 | **v0.8.0.** Phase 3 stale-first deductive candidate batch size. |
+| `CLAWMEM_HEAVY_LANE_SURPRISAL` | `false` | **v0.8.0.** When `true`, the heavy lane seeds Phase 2 with k-NN anomaly-ranked doc ids from `computeSurprisalScores` instead of stale-first ordering. Degrades to stale-first (`surprisal-fallback-stale` metric) on vaults without embeddings. |
 | `CLAWMEM_NUDGE_INTERVAL` | `15` | Prompts between lifecycle tool use before `<vault-nudge>` injection. 0 to disable. |
 | `CLAWMEM_MERGE_SCORE_NORMAL` | `0.93` | **v0.7.1.** Phase 2 merge-safety score threshold when candidate and existing anchors align. Merges above this normalized 3-gram cosine similarity are allowed. |
 | `CLAWMEM_MERGE_SCORE_STRICT` | `0.98` | **v0.7.1.** Strictest merge-safety score threshold (fallback when anchors are ambiguous). |
@@ -503,8 +511,9 @@ The `memory_relations` table is populated by multiple independent sources:
 | `buildTemporalBackbone()` | temporal | `build_graphs` MCP tool (manual) | Creation-order edges between all active docs. |
 | `buildSemanticGraph()` | semantic | `build_graphs` MCP tool (manual) | Pure cosine similarity. PK collision: `INSERT OR IGNORE` means A-MEM semantic edges take precedence if they exist first. |
 | Entity co-occurrence graph | entity | A-MEM enrichment (indexing) | LLM entity extraction → quality filters (title/length/blocklist/location validation) → type-agnostic canonical resolution within compatibility buckets (person, org, location, tech=project/service/tool/concept) → `entity_mentions` + `entity_cooccurrences` tables. Entity edges use IDF-based specificity scoring. Feeds ENTITY intent queries and MPFP `[entity, semantic]` patterns. |
-| `consolidated_observations` | supporting, contradicts | Consolidation worker (background) | 3-tier consolidation: facts → observations → mental models. Observations track `proof_count`, `trend` (STABLE/STRENGTHENING/WEAKENING/STALE), and source links. **v0.7.1 safety gates:** name-aware merge gate uses entity-anchor comparison + 3-gram cosine similarity (dual-threshold `CLAWMEM_MERGE_SCORE_NORMAL`=0.93 / `_STRICT`=0.98) to prevent cross-entity merges ("Alice decided X" merging into "Bob decided X"). Merge-time contradiction gate runs deterministic heuristic + LLM check; blocked merges route to `CLAWMEM_CONTRADICTION_POLICY`=`link` (new row + `contradicts` edge, default) or `supersede` (old row `status='inactive'`, new row replaces). |
-| Deductive synthesis | supporting, contradicts | Consolidation worker Phase 3 (background, every ~15 min) | Combines 2-3 related recent observations (decision/preference/milestone/problem, last 7 days) into `content_type='deductive'` documents with `source_doc_ids` provenance. First-class searchable docs with ∞ half-life. **v0.7.1 anti-contamination wrapper:** every draft passes through deterministic pre-checks (empty conclusion, invalid source_indices, pool-only entity contamination via `entity_mentions` or lexical fallback) + LLM validator (fail-open with `validatorFallbackAccepts` counter) + dedupe. Per-reason rejection stats exposed via `DeductiveSynthesisStats` (contaminationRejects, invalidIndexRejects, unsupportedRejects, emptyRejects, dedupSkipped, validatorFallbackAccepts). Contradictory dedupe matches are linked via `contradicts` edges. |
+| `consolidated_observations` | supporting, contradicts | Consolidation worker (background, light + heavy lanes) | 3-tier consolidation: facts → observations → mental models. Observations track `proof_count`, `trend` (STABLE/STRENGTHENING/WEAKENING/STALE), and source links. **v0.7.1 safety gates:** name-aware merge gate uses entity-anchor comparison + 3-gram cosine similarity (dual-threshold `CLAWMEM_MERGE_SCORE_NORMAL`=0.93 / `_STRICT`=0.98) to prevent cross-entity merges ("Alice decided X" merging into "Bob decided X"). Merge-time contradiction gate runs deterministic heuristic + LLM check; blocked merges route to `CLAWMEM_CONTRADICTION_POLICY`=`link` (new row + `contradicts` edge, default) or `supersede` (old row `status='inactive'`, new row replaces). **v0.8.0:** the heavy lane calls `consolidateObservations(store, llm, { maxDocs, guarded: true, staleOnly: true })` — `guarded: true` forces merge-safety enforcement regardless of `CLAWMEM_MERGE_GUARD_DRY_RUN`, and `staleOnly: true` reorders candidates by `recall_stats.last_recalled_at ASC` so long-unseen docs bubble up first. Optional `candidateIds` filter plumbs k-NN anomaly ids from `computeSurprisalScores`. |
+| Deductive synthesis | supporting, contradicts | Consolidation worker Phase 3 (background, every ~15 min in the light lane; batched in the heavy lane) | Combines 2-3 related recent observations (decision/preference/milestone/problem, last 7 days) into `content_type='deductive'` documents with `source_doc_ids` provenance. First-class searchable docs with ∞ half-life. **v0.7.1 anti-contamination wrapper:** every draft passes through deterministic pre-checks (empty conclusion, invalid source_indices, pool-only entity contamination via `entity_mentions` or lexical fallback) + LLM validator (fail-open with `validatorFallbackAccepts` counter) + dedupe. Per-reason rejection stats exposed via `DeductiveSynthesisStats` (contaminationRejects, invalidIndexRejects, unsupportedRejects, emptyRejects, dedupSkipped, validatorFallbackAccepts). Contradictory dedupe matches are linked via `contradicts` edges. **v0.8.0:** heavy lane calls `generateDeductiveObservations(store, llm, { maxRecent, guarded: true, staleOnly: true })` for stale-first batching on large vaults. |
+| Heavy maintenance lane journal | — | `clawmem` process with `CLAWMEM_HEAVY_LANE=true` (v0.8.0) | Writes a row to the `maintenance_runs` table for every scheduled heavy-lane attempt (including skips). Columns: `lane` (`heavy`), `phase` (`gate`/`consolidate`/`deductive`), `status` (`started`/`completed`/`failed`/`skipped`), `reason` (`outside_window`/`query_rate_high`/`lease_unavailable`), per-phase `selected`/`processed`/`created`/`null_call` counts, and `metrics_json` with selector type (`stale-first`/`surprisal`/`surprisal-fallback-stale`) + full `DeductiveSynthesisStats` on completed Phase 3 runs. Exclusivity is enforced via the new `worker_leases` table with atomic `INSERT ... ON CONFLICT DO UPDATE ... WHERE expires_at <= ?` acquisition, random 16-byte fencing tokens, and TTL reclaim. Gate uses the existing `context_usage` table (no `query_activity` table) and `recall_stats.last_recalled_at` for stale-first ordering. Off by default — requires explicit opt-in. |
 | Conversation synthesis (`runConversationSynthesis`) | semantic, supporting, contradicts, causal, temporal, entity | `clawmem mine <dir> --synthesize` (opt-in, post-index) | **v0.7.2.** Two-pass LLM pipeline over freshly imported `content_type='conversation'` docs. Pass 1 extracts structured facts (decision/preference/milestone/problem) via `extractFactsFromConversation`, saves each via dedup-aware `saveMemory`, populates a local Set-based alias map. Pass 2 resolves cross-fact links against the local map first (fails closed on ambiguity — multi-candidate titles return unresolved), falls back to collection-scoped SQL lookup with LIMIT 2 ambiguity detection. Relations upsert via `ON CONFLICT DO UPDATE SET weight = MAX(weight, excluded.weight)` — idempotent on equal-weight reruns but monotonically accepts stronger later evidence. Synthesized fact paths are a pure function of `(sourceDocId, slug(title), short sha256(normalizedTitle))`, so reruns update in place instead of creating parallel rows. Counters split into `llmFailures` (null/thrown/invalid-JSON) vs `docsWithNoFacts` (valid-empty extraction). All failures non-fatal — never rolls back the mine import. |
 
 **Edge collision:** Both `generateMemoryLinks()` and `buildSemanticGraph()` insert `relation_type='semantic'`. PK is `(source_id, target_id, relation_type)` — first writer wins.

package/CLAUDE.md

@@ -96,6 +96,14 @@ curl http://host:8090/v1/models
 | `CLAWMEM_ENABLE_AMEM` | enabled | A-MEM note construction + link generation during indexing. |
 | `CLAWMEM_ENABLE_CONSOLIDATION` | disabled | Background worker backfills unenriched docs. Needs long-lived MCP process. |
 | `CLAWMEM_CONSOLIDATION_INTERVAL` | 300000 | Worker interval in ms (min 15000). |
+| `CLAWMEM_HEAVY_LANE` | disabled | **v0.8.0.** Enable the quiet-window heavy maintenance worker — a second, longer-interval consolidation lane with DB-backed `worker_leases` exclusivity, stale-first batching, and `maintenance_runs` journaling. Runs alongside the light lane; off by default. |
+| `CLAWMEM_HEAVY_LANE_INTERVAL` | 1800000 | **v0.8.0.** Heavy-lane tick interval in ms (min 30000, default 30 min). |
+| `CLAWMEM_HEAVY_LANE_WINDOW_START` | (none) | **v0.8.0.** Start hour (0-23) of the quiet window. Unset → no window. |
+| `CLAWMEM_HEAVY_LANE_WINDOW_END` | (none) | **v0.8.0.** End hour (0-23, exclusive) of the quiet window. Supports midnight wrap (22→6). |
+| `CLAWMEM_HEAVY_LANE_MAX_USAGES` | 30 | **v0.8.0.** Max `context_usage` rows in the last 10 min before the heavy lane skips with `reason='query_rate_high'`. |
+| `CLAWMEM_HEAVY_LANE_OBS_LIMIT` | 100 | **v0.8.0.** Phase 2 stale-first observation batch size. |
+| `CLAWMEM_HEAVY_LANE_DED_LIMIT` | 40 | **v0.8.0.** Phase 3 stale-first deductive candidate batch size. |
+| `CLAWMEM_HEAVY_LANE_SURPRISAL` | `false` | **v0.8.0.** When `true`, the heavy lane seeds Phase 2 with k-NN anomaly-ranked doc ids from `computeSurprisalScores` instead of stale-first ordering. Degrades to stale-first (`surprisal-fallback-stale` metric) on vaults without embeddings. |
 | `CLAWMEM_NUDGE_INTERVAL` | `15` | Prompts between lifecycle tool use before `<vault-nudge>` injection. 0 to disable. |
 | `CLAWMEM_MERGE_SCORE_NORMAL` | `0.93` | **v0.7.1.** Phase 2 merge-safety score threshold when candidate and existing anchors align. Merges above this normalized 3-gram cosine similarity are allowed. |
 | `CLAWMEM_MERGE_SCORE_STRICT` | `0.98` | **v0.7.1.** Strictest merge-safety score threshold (fallback when anchors are ambiguous). |
@@ -503,8 +511,9 @@ The `memory_relations` table is populated by multiple independent sources:
 | `buildTemporalBackbone()` | temporal | `build_graphs` MCP tool (manual) | Creation-order edges between all active docs. |
 | `buildSemanticGraph()` | semantic | `build_graphs` MCP tool (manual) | Pure cosine similarity. PK collision: `INSERT OR IGNORE` means A-MEM semantic edges take precedence if they exist first. |
 | Entity co-occurrence graph | entity | A-MEM enrichment (indexing) | LLM entity extraction → quality filters (title/length/blocklist/location validation) → type-agnostic canonical resolution within compatibility buckets (person, org, location, tech=project/service/tool/concept) → `entity_mentions` + `entity_cooccurrences` tables. Entity edges use IDF-based specificity scoring. Feeds ENTITY intent queries and MPFP `[entity, semantic]` patterns. |
-| `consolidated_observations` | supporting, contradicts | Consolidation worker (background) | 3-tier consolidation: facts → observations → mental models. Observations track `proof_count`, `trend` (STABLE/STRENGTHENING/WEAKENING/STALE), and source links. **v0.7.1 safety gates:** name-aware merge gate uses entity-anchor comparison + 3-gram cosine similarity (dual-threshold `CLAWMEM_MERGE_SCORE_NORMAL`=0.93 / `_STRICT`=0.98) to prevent cross-entity merges ("Alice decided X" merging into "Bob decided X"). Merge-time contradiction gate runs deterministic heuristic + LLM check; blocked merges route to `CLAWMEM_CONTRADICTION_POLICY`=`link` (new row + `contradicts` edge, default) or `supersede` (old row `status='inactive'`, new row replaces). |
-| Deductive synthesis | supporting, contradicts | Consolidation worker Phase 3 (background, every ~15 min) | Combines 2-3 related recent observations (decision/preference/milestone/problem, last 7 days) into `content_type='deductive'` documents with `source_doc_ids` provenance. First-class searchable docs with ∞ half-life. **v0.7.1 anti-contamination wrapper:** every draft passes through deterministic pre-checks (empty conclusion, invalid source_indices, pool-only entity contamination via `entity_mentions` or lexical fallback) + LLM validator (fail-open with `validatorFallbackAccepts` counter) + dedupe. Per-reason rejection stats exposed via `DeductiveSynthesisStats` (contaminationRejects, invalidIndexRejects, unsupportedRejects, emptyRejects, dedupSkipped, validatorFallbackAccepts). Contradictory dedupe matches are linked via `contradicts` edges. |
+| `consolidated_observations` | supporting, contradicts | Consolidation worker (background, light + heavy lanes) | 3-tier consolidation: facts → observations → mental models. Observations track `proof_count`, `trend` (STABLE/STRENGTHENING/WEAKENING/STALE), and source links. **v0.7.1 safety gates:** name-aware merge gate uses entity-anchor comparison + 3-gram cosine similarity (dual-threshold `CLAWMEM_MERGE_SCORE_NORMAL`=0.93 / `_STRICT`=0.98) to prevent cross-entity merges ("Alice decided X" merging into "Bob decided X"). Merge-time contradiction gate runs deterministic heuristic + LLM check; blocked merges route to `CLAWMEM_CONTRADICTION_POLICY`=`link` (new row + `contradicts` edge, default) or `supersede` (old row `status='inactive'`, new row replaces). **v0.8.0:** the heavy lane calls `consolidateObservations(store, llm, { maxDocs, guarded: true, staleOnly: true })` — `guarded: true` forces merge-safety enforcement regardless of `CLAWMEM_MERGE_GUARD_DRY_RUN`, and `staleOnly: true` reorders candidates by `recall_stats.last_recalled_at ASC` so long-unseen docs bubble up first. Optional `candidateIds` filter plumbs k-NN anomaly ids from `computeSurprisalScores`. |
+| Deductive synthesis | supporting, contradicts | Consolidation worker Phase 3 (background, every ~15 min in the light lane; batched in the heavy lane) | Combines 2-3 related recent observations (decision/preference/milestone/problem, last 7 days) into `content_type='deductive'` documents with `source_doc_ids` provenance. First-class searchable docs with ∞ half-life. **v0.7.1 anti-contamination wrapper:** every draft passes through deterministic pre-checks (empty conclusion, invalid source_indices, pool-only entity contamination via `entity_mentions` or lexical fallback) + LLM validator (fail-open with `validatorFallbackAccepts` counter) + dedupe. Per-reason rejection stats exposed via `DeductiveSynthesisStats` (contaminationRejects, invalidIndexRejects, unsupportedRejects, emptyRejects, dedupSkipped, validatorFallbackAccepts). Contradictory dedupe matches are linked via `contradicts` edges. **v0.8.0:** heavy lane calls `generateDeductiveObservations(store, llm, { maxRecent, guarded: true, staleOnly: true })` for stale-first batching on large vaults. |
+| Heavy maintenance lane journal | — | `clawmem` process with `CLAWMEM_HEAVY_LANE=true` (v0.8.0) | Writes a row to the `maintenance_runs` table for every scheduled heavy-lane attempt (including skips). Columns: `lane` (`heavy`), `phase` (`gate`/`consolidate`/`deductive`), `status` (`started`/`completed`/`failed`/`skipped`), `reason` (`outside_window`/`query_rate_high`/`lease_unavailable`), per-phase `selected`/`processed`/`created`/`null_call` counts, and `metrics_json` with selector type (`stale-first`/`surprisal`/`surprisal-fallback-stale`) + full `DeductiveSynthesisStats` on completed Phase 3 runs. Exclusivity is enforced via the new `worker_leases` table with atomic `INSERT ... ON CONFLICT DO UPDATE ... WHERE expires_at <= ?` acquisition, random 16-byte fencing tokens, and TTL reclaim. Gate uses the existing `context_usage` table (no `query_activity` table) and `recall_stats.last_recalled_at` for stale-first ordering. Off by default — requires explicit opt-in. |
 | Conversation synthesis (`runConversationSynthesis`) | semantic, supporting, contradicts, causal, temporal, entity | `clawmem mine <dir> --synthesize` (opt-in, post-index) | **v0.7.2.** Two-pass LLM pipeline over freshly imported `content_type='conversation'` docs. Pass 1 extracts structured facts (decision/preference/milestone/problem) via `extractFactsFromConversation`, saves each via dedup-aware `saveMemory`, populates a local Set-based alias map. Pass 2 resolves cross-fact links against the local map first (fails closed on ambiguity — multi-candidate titles return unresolved), falls back to collection-scoped SQL lookup with LIMIT 2 ambiguity detection. Relations upsert via `ON CONFLICT DO UPDATE SET weight = MAX(weight, excluded.weight)` — idempotent on equal-weight reruns but monotonically accepts stronger later evidence. Synthesized fact paths are a pure function of `(sourceDocId, slug(title), short sha256(normalizedTitle))`, so reruns update in place instead of creating parallel rows. Counters split into `llmFailures` (null/thrown/invalid-JSON) vs `docsWithNoFacts` (valid-empty extraction). All failures non-fatal — never rolls back the mine import. |
 
 **Edge collision:** Both `generateMemoryLinks()` and `buildSemanticGraph()` insert `relation_type='semantic'`. PK is `(source_id, target_id, relation_type)` — first writer wins.

package/README.md

@@ -43,6 +43,7 @@ ClawMem turns your markdown notes, project docs, and research dumps into persist
 - **Manages document lifecycle** — policy-driven archival sweeps with restore capability
 - **Auto-routes queries** via `memory_retrieve` — classifies intent and dispatches to the optimal search backend
 - **Syncs project issues** from Beads issue trackers into searchable memory
+- **Runs a quiet-window heavy maintenance lane** — a second consolidation worker, off by default behind `CLAWMEM_HEAVY_LANE=true`, that runs on a longer interval only inside a configurable hour window. Gated by `context_usage` query-rate so it never competes for CPU/GPU with interactive sessions, scoped exclusively via DB-backed `worker_leases`, stale-first by default with an optional surprisal selector, and journals every attempt in `maintenance_runs` for operator visibility (v0.8.0)
 
 Runs fully local with no API keys and no cloud services. Integrates via Claude Code hooks and MCP tools, as an OpenClaw ContextEngine plugin, or as a Hermes Agent MemoryProvider plugin. All modes share the same vault for cross-runtime memory. Works with any MCP-compatible client.
 
@@ -80,6 +81,20 @@ Opt-in LLM pass that runs **after** `clawmem mine` finishes indexing an imported
 
 Adds +63 tests (46 unit + 5 integration + 12 regression) on top of the v0.7.1 baseline.
 
+### v0.8.0 Quiet-Window Heavy Maintenance Lane
+
+A second, longer-interval consolidation worker that keeps Phase 2 + Phase 3 running on large vaults without starving interactive sessions. Off by default — set `CLAWMEM_HEAVY_LANE=true` to enable. The existing 5-minute light-lane worker is unchanged. See [heavy maintenance lane](docs/concepts/architecture.md#heavy-maintenance-lane-v080) for the architectural walkthrough.
+
+- **Quiet-window gating** — the heavy lane only runs inside the hours set by `CLAWMEM_HEAVY_LANE_WINDOW_START` / `CLAWMEM_HEAVY_LANE_WINDOW_END` (0-23). Supports midnight wraparound (e.g., 22→6). Null on either bound means "always in window".
+- **Query-rate gating via `context_usage`** — counts hook injections in the last 10 minutes and skips the tick when the rate exceeds `CLAWMEM_HEAVY_LANE_MAX_USAGES` (default 30). No new `query_activity` table; reuses v0.7.0 telemetry.
+- **DB-backed worker leases** — exclusivity enforced via a new `worker_leases` table with atomic `INSERT ... ON CONFLICT DO UPDATE ... WHERE expires_at <= ?` acquisition, random 16-byte fencing tokens, and TTL reclaim. Safe under multi-process contention; any SQLite error translates to a `lease_unavailable` skip rather than a thrown exception.
+- **Stale-first selection** — Phase 2 and Phase 3 reorder their candidate sets by `COALESCE(recall_stats.last_recalled_at, documents.last_accessed_at, documents.modified_at) ASC` so long-unseen docs bubble up first. Empty `recall_stats` falls through to access-time without erroring.
+- **Optional surprisal selector** — `CLAWMEM_HEAVY_LANE_SURPRISAL=true` plumbs k-NN anomaly-ranked doc ids (via the existing `computeSurprisalScores`) into Phase 2 as an explicit `candidateIds` filter. Degrades to stale-first on vaults without embeddings and logs `selector: 'surprisal-fallback-stale'` in the journal.
+- **`maintenance_runs` journal** — every scheduled attempt writes a row: `status` (`started`/`completed`/`failed`/`skipped`), `reason` for skips, selected/processed/created/null_call counts, and a `metrics_json` payload with selector type and full `DeductiveSynthesisStats` breakdown. Operators can reconstruct any lane decision without reading worker logs.
+- **Force-enforce merge gate** — the heavy lane passes `guarded: true` to `consolidateObservations`, which overrides `CLAWMEM_MERGE_GUARD_DRY_RUN` inside `findSimilarConsolidation` so experimenting operators cannot weaken heavy-lane enforcement via env flag.
+
+Adds +56 tests (13 worker-lease + 35 maintenance unit + 8 maintenance integration) on top of the v0.7.2 baseline.
+
 ## Architecture
 
 <p align="center">

package/SKILL.md

@@ -92,6 +92,12 @@ curl http://host:8090/v1/models
 | `CLAWMEM_MERGE_GUARD_DRY_RUN` | `false` | **v0.7.1.** When `true`, Phase 2 merge-safety rejections are logged but not enforced — use for calibration. |
 | `CLAWMEM_CONTRADICTION_POLICY` | `link` | **v0.7.1.** How the merge-time contradiction gate handles a blocked merge. `link` (default) keeps both rows + inserts `contradicts` edge. `supersede` marks the old row `status='inactive'`. |
 | `CLAWMEM_CONTRADICTION_MIN_CONFIDENCE` | `0.5` | **v0.7.1.** Minimum combined heuristic+LLM confidence required before the contradiction gate blocks a merge. |
+| `CLAWMEM_HEAVY_LANE` | disabled | **v0.8.0.** Enable the quiet-window heavy maintenance worker — a second, longer-interval consolidation lane with DB-backed `worker_leases` exclusivity, stale-first batching, and `maintenance_runs` journaling. Runs alongside the light lane. |
+| `CLAWMEM_HEAVY_LANE_INTERVAL` | 1800000 | **v0.8.0.** Heavy-lane tick interval in ms (min 30000, default 30 min). |
+| `CLAWMEM_HEAVY_LANE_WINDOW_START` / `_END` | (none) | **v0.8.0.** Start/end hours (0-23) of the quiet window. Supports midnight wrap (22→6). Null on either bound = always in window. |
+| `CLAWMEM_HEAVY_LANE_MAX_USAGES` | 30 | **v0.8.0.** Max `context_usage` rows in the last 10 min before the heavy lane skips with `reason='query_rate_high'`. |
+| `CLAWMEM_HEAVY_LANE_OBS_LIMIT` / `_DED_LIMIT` | 100 / 40 | **v0.8.0.** Phase 2 / Phase 3 stale-first batch sizes. |
+| `CLAWMEM_HEAVY_LANE_SURPRISAL` | `false` | **v0.8.0.** When `true`, the heavy lane seeds Phase 2 with k-NN anomaly-ranked doc ids from `computeSurprisalScores` instead of stale-first ordering. Degrades to stale-first on vaults without embeddings. |
 
 **Note:** The `bin/clawmem` wrapper sets all endpoint defaults. Always use the wrapper — never `bun run src/clawmem.ts` directly.
 
@@ -526,9 +532,10 @@ mcp__clawmem__vsearch(query, collection="name", compact=true)   # vector
 | Beads `syncBeadsIssues()` | causal, supporting, semantic | `beads_sync` MCP or watcher | Queries `bd` CLI (Dolt backend). |
 | `buildTemporalBackbone()` | temporal | `build_graphs` MCP (manual) | Creation-order edges. |
 | `buildSemanticGraph()` | semantic | `build_graphs` MCP (manual) | Pure cosine similarity. A-MEM edges take precedence (first-writer wins). |
-| `consolidated_observations` | supporting, contradicts | Consolidation worker (background) | **v0.7.1 safety gates:** Phase 2 name-aware merge gate (entity anchors + 3-gram cosine, dual-threshold `CLAWMEM_MERGE_SCORE_NORMAL`=0.93 / `_STRICT`=0.98) blocks cross-entity merges. Merge-time contradiction gate (heuristic + LLM) routes blocked merges to `link` (default, inserts `contradicts` edge) or `supersede` (old row `status='inactive'`) via `CLAWMEM_CONTRADICTION_POLICY`. |
-| Deductive synthesis | supporting, contradicts | Consolidation worker Phase 3 (every ~15 min) | Combines 2-3 related observations (decision/preference/milestone/problem, last 7 days) into `content_type='deductive'` docs. **v0.7.1 anti-contamination:** deterministic pre-checks (empty/invalid_indices/pool-only entity contamination) + LLM validator (fail-open, `validatorFallbackAccepts` counter) + dedupe. Per-reason rejection stats via `DeductiveSynthesisStats`. Contradictory dedupe matches linked via `contradicts` edges. |
+| `consolidated_observations` | supporting, contradicts | Consolidation worker (background, light + heavy lanes) | **v0.7.1 safety gates:** Phase 2 name-aware merge gate (entity anchors + 3-gram cosine, dual-threshold `CLAWMEM_MERGE_SCORE_NORMAL`=0.93 / `_STRICT`=0.98) blocks cross-entity merges. Merge-time contradiction gate (heuristic + LLM) routes blocked merges to `link` (default, inserts `contradicts` edge) or `supersede` (old row `status='inactive'`) via `CLAWMEM_CONTRADICTION_POLICY`. **v0.8.0:** heavy lane calls `consolidateObservations(store, llm, { maxDocs, guarded: true, staleOnly: true, candidateIds? })` — `guarded: true` forces enforcement regardless of `CLAWMEM_MERGE_GUARD_DRY_RUN`, `staleOnly: true` reorders by `recall_stats.last_recalled_at ASC`, and optional `candidateIds` plumbs surprisal-selector output. |
+| Deductive synthesis | supporting, contradicts | Consolidation worker Phase 3 (every ~15 min in light lane; batched in heavy lane) | Combines 2-3 related observations (decision/preference/milestone/problem, last 7 days) into `content_type='deductive'` docs. **v0.7.1 anti-contamination:** deterministic pre-checks (empty/invalid_indices/pool-only entity contamination) + LLM validator (fail-open, `validatorFallbackAccepts` counter) + dedupe. Per-reason rejection stats via `DeductiveSynthesisStats`. Contradictory dedupe matches linked via `contradicts` edges. **v0.8.0:** heavy lane calls `generateDeductiveObservations(store, llm, { maxRecent, guarded: true, staleOnly: true })` for stale-first batching. |
 | Conversation synthesis | semantic, supporting, contradicts, causal, temporal, entity | `clawmem mine <dir> --synthesize` (opt-in, post-index) | **v0.7.2.** Two-pass LLM pipeline over freshly imported `content_type='conversation'` docs. Pass 1 extracts structured decision/preference/milestone/problem facts + aliases + cross-fact links, saves via dedup-aware `saveMemory`, populates ambiguity-aware local Set map. Pass 2 resolves links (local first, SQL fallback with `LIMIT 2` ambiguity detection), upserts relations via `ON CONFLICT DO UPDATE SET weight = MAX(weight, excluded.weight)`. Synthesized paths are a pure function of `(sourceDocId, slug(title), short sha256(normalizedTitle))` so reruns update in place. All failures non-fatal. Counters split: `llmFailures` (LLM/parse error) vs `docsWithNoFacts` (valid empty extraction). |
+| Heavy maintenance lane journal | — | `CLAWMEM_HEAVY_LANE=true` (v0.8.0) | Writes a row to `maintenance_runs` for every scheduled heavy-lane attempt (including skips). Columns: `lane` (`heavy`), `phase` (`gate`/`consolidate`/`deductive`), `status` (`started`/`completed`/`failed`/`skipped`), `reason` (`outside_window`/`query_rate_high`/`lease_unavailable`), per-phase counts, and `metrics_json` with selector type (`stale-first`/`surprisal`/`surprisal-fallback-stale`) + full `DeductiveSynthesisStats`. Exclusivity via new `worker_leases` table (atomic `INSERT ... ON CONFLICT DO UPDATE ... WHERE expires_at <= ?`, 16-byte fencing tokens, TTL reclaim). Gate reuses `context_usage` (no `query_activity` table). |
 
 **Graph traversal asymmetry:** `adaptiveTraversal()` traverses all edge types outbound (source->target) but only `semantic` and `entity` inbound.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmem",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "On-device context engine and memory for AI agents. Claude Code and OpenClaw. Hooks + MCP server + hybrid RAG search.",
   "type": "module",
   "bin": {

package/src/consolidation.ts

@@ -114,6 +114,50 @@ interface ObservationCluster {
   collection: string;
 }
 
+/**
+ * Phase 2 consolidation option bag (v0.8.0 Ext 5). All fields optional;
+ * omitting the bag reproduces pre-Ext-5 behavior exactly.
+ *
+ *  - `maxDocs`       override for the observation batch size (default 50)
+ *  - `guarded`       when true, force merge-safety enforcement regardless of
+ *                    the `CLAWMEM_MERGE_GUARD_DRY_RUN` env var. Heavy-lane
+ *                    callers pass this so experimenting operators cannot
+ *                    weaken the heavy-lane gate by toggling an env flag.
+ *  - `staleOnly`     when true, order observations by
+ *                    `recall_stats.last_recalled_at ASC` (with
+ *                    `documents.last_accessed_at` fallback) so least-recalled
+ *                    documents are processed first instead of most-recent.
+ *  - `candidateIds`  when non-empty, restricts the Phase 2 candidate set to
+ *                    exactly these document ids. Heavy lane uses this to
+ *                    plumb surprisal-selector output into consolidation so
+ *                    `useSurprisalSelector: true` actually feeds anomaly-first
+ *                    candidates instead of just relabeling the default batch.
+ */
+export interface ConsolidateOptions {
+  maxDocs?: number;
+  guarded?: boolean;
+  staleOnly?: boolean;
+  candidateIds?: number[];
+}
+
+/**
+ * Phase 3 deductive synthesis option bag (v0.8.0 Ext 5). All fields optional;
+ * omitting the bag reproduces pre-Ext-5 behavior exactly.
+ *
+ *  - `maxRecent`  override for the recent-observation window size (default 20)
+ *  - `guarded`    forward-compat marker; currently a no-op because the Phase 3
+ *                 deductive guardrails always enforce their deterministic
+ *                 pre-checks + LLM validator regardless of this flag
+ *  - `staleOnly`  when true, order candidate observations by
+ *                 `recall_stats.last_recalled_at ASC` with
+ *                 `documents.last_accessed_at` fallback
+ */
+export interface DeductiveOptions {
+  maxRecent?: number;
+  guarded?: boolean;
+  staleOnly?: boolean;
+}
+
 // =============================================================================
 // Worker State
 // =============================================================================
@@ -247,17 +291,71 @@ async function backfillAmem(store: Store, llm: LlamaCpp): Promise<void> {
 /**
  * Find clusters of related observations and synthesize into consolidated observations.
  * Runs per-collection to prevent cross-vault false merges.
+ *
+ * `opts` (v0.8.0 Ext 5) lets the heavy-maintenance lane override batch size,
+ * force merge-safety enforcement, and switch to stale-first ordering. The
+ * zero-arg call path (internal light-lane tick) preserves pre-Ext-5 behavior.
  */
-async function consolidateObservations(store: Store, llm: LlamaCpp): Promise<void> {
-  console.log("[consolidation] Starting observation consolidation");
+export async function consolidateObservations(
+  store: Store,
+  llm: LlamaCpp,
+  opts: ConsolidateOptions = {},
+): Promise<void> {
+  const maxDocs = opts.maxDocs && opts.maxDocs > 0 ? opts.maxDocs : 50;
+  const staleOnly = opts.staleOnly === true;
+  const guarded = opts.guarded === true;
+  const candidateIds = opts.candidateIds && opts.candidateIds.length > 0
+    ? opts.candidateIds
+    : null;
+
+  // Early exit when caller passed candidateIds: [] explicitly. An empty
+  // array means "the selector found nothing" — not "select everything".
+  if (opts.candidateIds && opts.candidateIds.length === 0) {
+    console.log("[consolidation] Empty candidateIds array — nothing to consolidate");
+    return;
+  }
+
+  console.log(
+    `[consolidation] Starting observation consolidation (maxDocs=${maxDocs}, ` +
+      `staleOnly=${staleOnly}, guarded=${guarded}, ` +
+      `candidateIds=${candidateIds ? candidateIds.length : "null"})`,
+  );
+
+  // Base SELECT — observation-type docs not yet consolidated.
+  // Stale-first ordering joins recall_stats.last_recalled_at ASC with a
+  // documents.last_accessed_at fallback so long-unseen docs bubble up first.
+  // Default ordering (modified_at DESC) preserves pre-Ext-5 light-lane semantics.
+  const orderBy = staleOnly
+    ? `ORDER BY
+         d.collection,
+         COALESCE(rs.last_recalled_at, d.last_accessed_at, d.modified_at) ASC,
+         d.modified_at ASC`
+    : `ORDER BY d.collection, d.modified_at DESC`;
+
+  const joinClause = staleOnly
+    ? `LEFT JOIN recall_stats rs ON rs.doc_id = d.id`
+    : ``;
+
+  // When candidateIds is provided, restrict the SELECT to those docs. This
+  // is how the heavy lane plumbs surprisal-selector output into Phase 2:
+  // select anomaly-first IDs via computeSurprisalScores, then ask
+  // consolidateObservations to limit its pattern detection to that subset.
+  const candidateFilter = candidateIds
+    ? `AND d.id IN (${candidateIds.map(() => "?").join(",")})`
+    : ``;
+
+  const sqlParams: (number | string)[] = candidateIds
+    ? [...candidateIds, maxDocs]
+    : [maxDocs];
 
-  // Find observation-type documents not yet consolidated
   const observations = store.db.prepare(`
     SELECT d.id, d.title, d.facts, d.amem_context as context, d.modified_at, d.collection
     FROM documents d
+    ${joinClause}
     WHERE d.active = 1
       AND d.content_type = 'observation'
       AND d.facts IS NOT NULL
+      ${candidateFilter}
       AND d.id NOT IN (
         SELECT value FROM (
           SELECT json_each.value as value
@@ -265,9 +363,9 @@ async function consolidateObservations(store: Store, llm: LlamaCpp): Promise<voi
           WHERE co.status = 'active'
         )
       )
-    ORDER BY d.collection, d.modified_at DESC
-    LIMIT 50
-  `).all() as { id: number; title: string; facts: string; context: string; modified_at: string; collection: string }[];
+    ${orderBy}
+    LIMIT ?
+  `).all(...sqlParams) as { id: number; title: string; facts: string; context: string; modified_at: string; collection: string }[];
 
   if (observations.length === 0) {
     console.log("[consolidation] No unconsolidated observations found");
@@ -288,7 +386,7 @@ async function consolidateObservations(store: Store, llm: LlamaCpp): Promise<voi
     if (cluster.docs.length < 2) continue; // Need at least 2 observations to consolidate
 
     try {
-      await synthesizeCluster(store, llm, cluster);
+      await synthesizeCluster(store, llm, cluster, { guarded });
     } catch (err) {
       console.error(`[consolidation] Failed to consolidate cluster for ${collection}:`, err);
     }
@@ -302,11 +400,15 @@ async function consolidateObservations(store: Store, llm: LlamaCpp): Promise<voi
 
 /**
  * Synthesize a cluster of observations into consolidated observations using LLM.
+ *
+ * `opts.guarded` (v0.8.0 Ext 5) forces merge-safety enforcement inside
+ * `findSimilarConsolidation` regardless of `CLAWMEM_MERGE_GUARD_DRY_RUN`.
  */
 async function synthesizeCluster(
   store: Store,
   llm: LlamaCpp,
-  cluster: ObservationCluster
+  cluster: ObservationCluster,
+  opts: { guarded?: boolean } = {},
 ): Promise<void> {
   const docsText = cluster.docs.map((d, i) =>
     `${i + 1}. [${d.modified_at}] "${d.title}"\n   Facts: ${d.facts?.slice(0, 300) || 'none'}\n   Context: ${d.context?.slice(0, 200) || 'none'}`
@@ -364,11 +466,13 @@ Return ONLY the JSON array. /no_think`;
 
     // Check for existing similar consolidated observation (avoid duplicates).
     // Two-stage gate: Jaccard shortlist + name-aware merge safety (Ext 3).
+    // `guarded` forces gate enforcement when the heavy lane calls us.
     const existing = findSimilarConsolidation(
       store,
       pattern.observation,
       cluster.collection,
-      sourceDocIds
+      sourceDocIds,
+      opts.guarded === true,
     );
     if (existing) {
       // Ext 2: contradiction gate. Before merging into an existing
@@ -524,7 +628,8 @@ export function findSimilarConsolidation(
   store: Store,
   observation: string,
   collection: string,
-  candidateSourceDocIds: number[]
+  candidateSourceDocIds: number[],
+  forceEnforce: boolean = false,
 ): { id: number; observation: string; source_doc_ids: string } | null {
   // ORDER BY id ASC makes "first shortlist hit" deterministic across
   // SQLite plan changes — the dry-run legacy parity case relies on
@@ -553,7 +658,12 @@ export function findSimilarConsolidation(
 
   if (shortlist.length === 0) return null;
 
-  const dryRun = process.env.CLAWMEM_MERGE_GUARD_DRY_RUN === "true";
+  // `forceEnforce` (v0.8.0 Ext 5) lets the heavy lane override the env
+  // `CLAWMEM_MERGE_GUARD_DRY_RUN` so operators can experiment with dry-run
+  // in the light lane without weakening heavy-lane guarantees.
+  const dryRun = forceEnforce
+    ? false
+    : process.env.CLAWMEM_MERGE_GUARD_DRY_RUN === "true";
 
   // Dry-run: preserve EXACT legacy behavior — return the first shortlist
   // hit (the pre-Ext-3 code iterated the SELECT rows in order and returned
@@ -723,18 +833,38 @@ function updateTrends(store: Store): void {
  *
  * Only considers decision/preference/milestone/problem observations from the
  * last 7 days that haven't already been used as sources for deductions.
+ *
+ * `opts` (v0.8.0 Ext 5):
+ *  - `maxRecent`  override batch size (default 20)
+ *  - `staleOnly`  order by recall_stats.last_recalled_at ASC with
+ *                 documents.last_accessed_at fallback instead of
+ *                 modified_at DESC
+ *  - `guarded`    forward-compat marker — no-op in v0.8.0 because the Phase 3
+ *                 guardrails always enforce their gates regardless
  */
-async function generateDeductiveObservations(
+export async function generateDeductiveObservations(
   store: Store,
-  llm: LlamaCpp
+  llm: LlamaCpp,
+  opts: DeductiveOptions = {},
 ): Promise<DeductiveSynthesisStats> {
+  const maxRecent = opts.maxRecent && opts.maxRecent > 0 ? opts.maxRecent : 20;
+  const staleOnly = opts.staleOnly === true;
   const stats = emptyDeductiveStats();
   // Find recent high-value observations not yet used in deductions
   const DEDUCTIVE_TYPES = ['decision', 'preference', 'milestone', 'problem'];
+
+  const orderBy = staleOnly
+    ? `ORDER BY COALESCE(rs.last_recalled_at, d.last_accessed_at, d.modified_at) ASC, d.modified_at ASC`
+    : `ORDER BY d.modified_at DESC`;
+  const joinClause = staleOnly
+    ? `LEFT JOIN recall_stats rs ON rs.doc_id = d.id`
+    : ``;
+
   const recentObs = store.db.prepare(`
     SELECT d.id, d.title, d.facts, d.narrative, d.observation_type, d.content_type,
            d.collection, d.path, d.modified_at
     FROM documents d
+    ${joinClause}
     WHERE d.active = 1
       AND d.content_type IN (${DEDUCTIVE_TYPES.map(() => '?').join(',')})
       AND d.observation_type IS NOT NULL
@@ -747,9 +877,9 @@ async function generateDeductiveObservations(
           WHERE dd.content_type = 'deductive' AND dd.active = 1
         )
       )
-    ORDER BY d.modified_at DESC
-    LIMIT 20
-  `).all(...DEDUCTIVE_TYPES) as {
+    ${orderBy}
+    LIMIT ?
+  `).all(...DEDUCTIVE_TYPES, maxRecent) as {
     id: number; title: string; facts: string; narrative: string;
     observation_type: string; content_type: string; collection: string;
     path: string; modified_at: string;

package/src/maintenance.ts

@@ -0,0 +1,540 @@
+/**
+ * ClawMem Heavy Maintenance Lane (v0.8.0 Ext 5)
+ *
+ * A second, longer-interval consolidation worker that runs during configured
+ * quiet windows with stale-first batching, DB-backed exclusivity via
+ * worker_leases, and journal rows in `maintenance_runs` for every attempt.
+ *
+ * Keeps Phase 2/3 consolidation + deductive synthesis running on large vaults
+ * without competing for CPU/GPU against the interactive light lane that
+ * ticks every 5 minutes. Off by default — enabled via `CLAWMEM_HEAVY_LANE=true`
+ * next to the existing light-lane `CLAWMEM_ENABLE_CONSOLIDATION` flag.
+ *
+ * Design notes:
+ *  - Uses existing `context_usage` telemetry for query-rate gating. No new
+ *    `query_activity` table — we count rows where `timestamp > -10 minutes`.
+ *  - Stale-first selection prefers docs whose `recall_stats.last_recalled_at`
+ *    is oldest/null, falling back to `documents.last_accessed_at` / `modified_at`.
+ *  - Optional surprisal selector reuses `computeSurprisalScores` to bubble up
+ *    high-anomaly observations for curator-style runs.
+ *  - Every scheduled attempt writes a `maintenance_runs` row so operators can
+ *    reconstruct the decision without reading worker logs.
+ */
+
+import type { Store } from "./store.ts";
+import type { LlamaCpp } from "./llm.ts";
+import {
+  consolidateObservations,
+  generateDeductiveObservations,
+  computeSurprisalScores,
+  type DeductiveSynthesisStats,
+} from "./consolidation.ts";
+import { withWorkerLease } from "./worker-lease.ts";
+
+// =============================================================================
+// Config
+// =============================================================================
+
+export interface HeavyMaintenanceConfig {
+  /** Interval between heavy-lane ticks in milliseconds (default 30 min). */
+  intervalMs?: number;
+  /** Start hour (0-23) of the quiet window; null/undefined = no window. */
+  windowStartHour?: number | null;
+  /** End hour (0-23, exclusive) of the quiet window; null/undefined = no window. */
+  windowEndHour?: number | null;
+  /** Max context_usage rows in the last 10 min before the lane skips (default 30). */
+  maxContextUsagesPer10m?: number;
+  /** Batch size for Phase 2 consolidation (default 100). */
+  staleObservationLimit?: number;
+  /** Batch size for Phase 3 deductive synthesis (default 40). */
+  staleDeductiveLimit?: number;
+  /** When true, use computeSurprisalScores to select batches for Phase 2. */
+  useSurprisalSelector?: boolean;
+  /** Worker lease TTL in ms (default 10 min — covers worst-case run time). */
+  leaseTtlMs?: number;
+  /** Worker lease name. Override only in tests (default "heavy-maintenance"). */
+  workerName?: string;
+  /** Clock injection for unit tests — defaults to `() => new Date()`. */
+  clock?: () => Date;
+}
+
+// Vault scoping note: the heavy lane operates on whatever Store it is handed
+// — createStore(path) maps 1:1 to a single SQLite vault, so context_usage
+// and recall_stats reads are implicitly vault-scoped via `store.db`. Multi-
+// vault mode is out of scope for v0.8.0 and would require extending this
+// config with an explicit vault list plus a per-vault lease name.
+
+const DEFAULT_CONFIG: Required<Omit<HeavyMaintenanceConfig, "workerName" | "clock">> = {
+  intervalMs: 30 * 60 * 1000,
+  windowStartHour: null,
+  windowEndHour: null,
+  maxContextUsagesPer10m: 30,
+  staleObservationLimit: 100,
+  staleDeductiveLimit: 40,
+  useSurprisalSelector: false,
+  leaseTtlMs: 10 * 60 * 1000,
+};
+
+const DEFAULT_WORKER_NAME = "heavy-maintenance";
+
+// =============================================================================
+// Journal helpers
+// =============================================================================
+
+export type MaintenanceStatus = "started" | "skipped" | "completed" | "failed";
+
+export interface MaintenanceRunSummary {
+  id: number;
+  lane: string;
+  phase: string;
+  status: MaintenanceStatus;
+  reason: string | null;
+  selected_count: number;
+  processed_count: number;
+  created_count: number;
+  updated_count: number;
+  rejected_count: number;
+  null_call_count: number;
+  started_at: string;
+  finished_at: string | null;
+  metrics_json: string | null;
+}
+
+export function insertMaintenanceRun(
+  store: Store,
+  row: {
+    lane: string;
+    phase: string;
+    status: MaintenanceStatus;
+    reason?: string | null;
+    selectedCount?: number;
+    processedCount?: number;
+    createdCount?: number;
+    updatedCount?: number;
+    rejectedCount?: number;
+    nullCallCount?: number;
+    startedAt?: string;
+    finishedAt?: string | null;
+    metrics?: Record<string, unknown> | null;
+  },
+): number {
+  const startedAt = row.startedAt ?? new Date().toISOString();
+  const result = store.db.prepare(
+    `INSERT INTO maintenance_runs
+      (lane, phase, status, reason, selected_count, processed_count,
+       created_count, updated_count, rejected_count, null_call_count,
+       started_at, finished_at, metrics_json)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  ).run(
+    row.lane,
+    row.phase,
+    row.status,
+    row.reason ?? null,
+    row.selectedCount ?? 0,
+    row.processedCount ?? 0,
+    row.createdCount ?? 0,
+    row.updatedCount ?? 0,
+    row.rejectedCount ?? 0,
+    row.nullCallCount ?? 0,
+    startedAt,
+    row.finishedAt ?? null,
+    row.metrics ? JSON.stringify(row.metrics) : null,
+  );
+  return Number(result.lastInsertRowid);
+}
+
+function finalizeMaintenanceRun(
+  store: Store,
+  id: number,
+  patch: {
+    status: MaintenanceStatus;
+    reason?: string | null;
+    selectedCount?: number;
+    processedCount?: number;
+    createdCount?: number;
+    updatedCount?: number;
+    rejectedCount?: number;
+    nullCallCount?: number;
+    finishedAt?: string;
+    metrics?: Record<string, unknown> | null;
+  },
+): void {
+  store.db.prepare(
+    `UPDATE maintenance_runs
+        SET status = ?, reason = ?,
+            selected_count = ?, processed_count = ?,
+            created_count = ?, updated_count = ?,
+            rejected_count = ?, null_call_count = ?,
+            finished_at = ?, metrics_json = ?
+      WHERE id = ?`,
+  ).run(
+    patch.status,
+    patch.reason ?? null,
+    patch.selectedCount ?? 0,
+    patch.processedCount ?? 0,
+    patch.createdCount ?? 0,
+    patch.updatedCount ?? 0,
+    patch.rejectedCount ?? 0,
+    patch.nullCallCount ?? 0,
+    patch.finishedAt ?? new Date().toISOString(),
+    patch.metrics ? JSON.stringify(patch.metrics) : null,
+    id,
+  );
+}
+
+// =============================================================================
+// Gating logic
+// =============================================================================
+
+/**
+ * True when `now` falls inside [windowStartHour, windowEndHour). Both nulls
+ * mean "always in window". Handles midnight wraparound (e.g., 22→6) by
+ * accepting either hour >= start OR hour < end.
+ */
+export function isInQuietWindow(
+  now: Date,
+  windowStartHour: number | null | undefined,
+  windowEndHour: number | null | undefined,
+): boolean {
+  if (windowStartHour == null || windowEndHour == null) return true;
+  if (windowStartHour < 0 || windowStartHour > 23 || windowEndHour < 0 || windowEndHour > 23) {
+    throw new Error(
+      `isInQuietWindow: hours must be 0-23, got start=${windowStartHour} end=${windowEndHour}`,
+    );
+  }
+  if (windowStartHour === windowEndHour) return false; // empty window
+  const hour = now.getHours();
+  if (windowStartHour < windowEndHour) {
+    return hour >= windowStartHour && hour < windowEndHour;
+  }
+  // Wraps midnight
+  return hour >= windowStartHour || hour < windowEndHour;
+}
+
+/**
+ * Count context_usage rows in the last `minutes` minutes. Used as a proxy
+ * for "how busy is the interactive light lane right now" — replaces the
+ * `query_activity` table that Turn 2 of Ext 5 proposed.
+ *
+ * The cutoff is computed in JS as an ISO 8601 string and bound as a
+ * parameter instead of using `datetime('now', '-N minutes')`. SQLite's
+ * `datetime()` returns a space-separated format (`YYYY-MM-DD HH:MM:SS`)
+ * while `context_usage.timestamp` is written in ISO 8601 with a T
+ * separator; lexicographic comparison across those two formats is wrong
+ * (space < T sorts ALL ISO rows as "newer" than any datetime() result).
+ */
+export function countRecentContextUsages(
+  store: Store,
+  minutes: number = 10,
+): number {
+  const cutoff = new Date(Date.now() - minutes * 60 * 1000).toISOString();
+  const row = store.db.prepare(
+    `SELECT COUNT(*) AS cnt FROM context_usage WHERE timestamp > ?`,
+  ).get(cutoff) as { cnt: number } | undefined;
+  return row?.cnt ?? 0;
+}
+
+/**
+ * Decide whether the heavy lane should run on this tick. Returns the
+ * reason for skipping so the journal row can record it.
+ */
+export function shouldRunHeavyMaintenance(
+  store: Store,
+  now: Date,
+  cfg: HeavyMaintenanceConfig = {},
+): { run: boolean; reason?: string } {
+  const merged = { ...DEFAULT_CONFIG, ...cfg };
+  if (!isInQuietWindow(now, merged.windowStartHour, merged.windowEndHour)) {
+    return { run: false, reason: "outside_window" };
+  }
+  const usages = countRecentContextUsages(store, 10);
+  if (usages > merged.maxContextUsagesPer10m) {
+    return { run: false, reason: "query_rate_high" };
+  }
+  return { run: true };
+}
+
+// =============================================================================
+// Stale-first selection helpers
+// =============================================================================
+
+/**
+ * Select up to `limit` observation doc IDs ordered by stale-first:
+ * least-recently-recalled (recall_stats.last_recalled_at ASC, NULL first)
+ * with documents.last_accessed_at as a fallback when recall_stats is empty.
+ *
+ * Used by tests and operators who want to inspect the heavy-lane batch
+ * without actually running Phase 2. The real Phase 2 SQL inside
+ * `consolidateObservations` applies its own stale-first ordering when
+ * `staleOnly: true` is passed.
+ */
+export function selectStaleObservationBatch(
+  store: Store,
+  limit: number,
+): number[] {
+  const rows = store.db.prepare(
+    `SELECT d.id FROM documents d
+       LEFT JOIN recall_stats rs ON rs.doc_id = d.id
+       WHERE d.active = 1
+         AND d.content_type = 'observation'
+       ORDER BY
+         COALESCE(rs.last_recalled_at, d.last_accessed_at, d.modified_at) ASC,
+         d.modified_at ASC
+       LIMIT ?`,
+  ).all(limit) as { id: number }[];
+  return rows.map(r => r.id);
+}
+
+/**
+ * Select up to `limit` decision/preference/milestone/problem doc IDs
+ * ordered by stale-first for Phase 3 deductive synthesis.
+ */
+export function selectStaleDeductiveBatch(
+  store: Store,
+  limit: number,
+): number[] {
+  const DEDUCTIVE_TYPES = ["decision", "preference", "milestone", "problem"];
+  const placeholders = DEDUCTIVE_TYPES.map(() => "?").join(",");
+  const rows = store.db.prepare(
+    `SELECT d.id FROM documents d
+       LEFT JOIN recall_stats rs ON rs.doc_id = d.id
+       WHERE d.active = 1
+         AND d.content_type IN (${placeholders})
+       ORDER BY
+         COALESCE(rs.last_recalled_at, d.last_accessed_at, d.modified_at) ASC,
+         d.modified_at ASC
+       LIMIT ?`,
+  ).all(...DEDUCTIVE_TYPES, limit) as { id: number }[];
+  return rows.map(r => r.id);
+}
+
+/**
+ * Select up to `limit` observation doc IDs ranked by surprisal score
+ * (k-NN average neighbor distance — higher = more anomalous). Wraps
+ * `computeSurprisalScores` so the heavy lane can swap in anomaly-first
+ * selection via `useSurprisalSelector: true`.
+ */
+export function selectSurprisingObservationBatch(
+  store: Store,
+  limit: number,
+): number[] {
+  const results = computeSurprisalScores(store, { limit });
+  return results.map(r => r.docId);
+}
+
+// =============================================================================
+// Worker topology
+// =============================================================================
+
+let heavyTimer: Timer | null = null;
+let heavyRunning = false;
+
+/**
+ * Run a single heavy-lane tick: gate check → worker lease → Phase 2 → Phase 3
+ * → journal row. Exported for tests and for manual invocation via a future
+ * `clawmem heavy-lane --once` CLI flag.
+ */
+export async function runHeavyMaintenanceTick(
+  store: Store,
+  llm: LlamaCpp,
+  cfg: HeavyMaintenanceConfig = {},
+): Promise<MaintenanceRunSummary[]> {
+  const merged = { ...DEFAULT_CONFIG, ...cfg };
+  const workerName = cfg.workerName ?? DEFAULT_WORKER_NAME;
+  const clock = cfg.clock ?? (() => new Date());
+  const results: MaintenanceRunSummary[] = [];
+
+  const now = clock();
+  const gate = shouldRunHeavyMaintenance(store, now, cfg);
+  if (!gate.run) {
+    const skippedId = insertMaintenanceRun(store, {
+      lane: "heavy",
+      phase: "gate",
+      status: "skipped",
+      reason: gate.reason ?? "unknown",
+      finishedAt: new Date().toISOString(),
+    });
+    results.push(loadMaintenanceRun(store, skippedId));
+    return results;
+  }
+
+  const lease = await withWorkerLease(
+    store,
+    workerName,
+    merged.leaseTtlMs,
+    async () => {
+      // Phase 2 — consolidation
+      const phase2Id = insertMaintenanceRun(store, {
+        lane: "heavy",
+        phase: "consolidate",
+        status: "started",
+      });
+      try {
+        // Surprisal selector path: compute anomaly-first candidate ids up
+        // front, then plumb them into consolidateObservations via
+        // candidateIds. When the surprisal backend returns empty (no
+        // embeddings, small vault, k-NN unavailable), fall through to
+        // stale-first ordering so the heavy lane still does useful work.
+        let candidateIds: number[] | undefined;
+        let selectorUsed: "stale-first" | "surprisal" | "surprisal-fallback-stale";
+        if (merged.useSurprisalSelector) {
+          candidateIds = selectSurprisingObservationBatch(
+            store,
+            merged.staleObservationLimit,
+          );
+          if (candidateIds.length === 0) {
+            // Nothing surprising — degrade to stale-first so the lane
+            // does not become a no-op on vaults without embeddings.
+            candidateIds = undefined;
+            selectorUsed = "surprisal-fallback-stale";
+          } else {
+            selectorUsed = "surprisal";
+          }
+        } else {
+          selectorUsed = "stale-first";
+        }
+
+        await consolidateObservations(store, llm, {
+          maxDocs: merged.staleObservationLimit,
+          guarded: true,
+          staleOnly: selectorUsed !== "surprisal",
+          candidateIds,
+        });
+        finalizeMaintenanceRun(store, phase2Id, {
+          status: "completed",
+          selectedCount: candidateIds
+            ? candidateIds.length
+            : merged.staleObservationLimit,
+          metrics: {
+            selector: selectorUsed,
+            ...(candidateIds ? { candidateCount: candidateIds.length } : {}),
+          },
+        });
+      } catch (err) {
+        finalizeMaintenanceRun(store, phase2Id, {
+          status: "failed",
+          reason: "phase2_exception",
+          metrics: { error: (err as Error).message },
+        });
+      }
+      results.push(loadMaintenanceRun(store, phase2Id));
+
+      // Phase 3 — deductive synthesis
+      const phase3Id = insertMaintenanceRun(store, {
+        lane: "heavy",
+        phase: "deductive",
+        status: "started",
+      });
+      try {
+        const stats: DeductiveSynthesisStats = await generateDeductiveObservations(
+          store,
+          llm,
+          {
+            maxRecent: merged.staleDeductiveLimit,
+            guarded: true,
+            staleOnly: true,
+          },
+        );
+        finalizeMaintenanceRun(store, phase3Id, {
+          status: "completed",
+          selectedCount: stats.considered,
+          processedCount: stats.drafted,
+          createdCount: stats.created,
+          rejectedCount: stats.rejected,
+          nullCallCount: stats.nullCalls,
+          metrics: {
+            accepted: stats.accepted,
+            contaminationRejects: stats.contaminationRejects,
+            invalidIndexRejects: stats.invalidIndexRejects,
+            unsupportedRejects: stats.unsupportedRejects,
+            emptyRejects: stats.emptyRejects,
+            dedupSkipped: stats.dedupSkipped,
+            validatorFallbackAccepts: stats.validatorFallbackAccepts,
+          },
+        });
+      } catch (err) {
+        finalizeMaintenanceRun(store, phase3Id, {
+          status: "failed",
+          reason: "phase3_exception",
+          metrics: { error: (err as Error).message },
+        });
+      }
+      results.push(loadMaintenanceRun(store, phase3Id));
+    },
+  );
+
+  if (!lease.acquired) {
+    const skippedId = insertMaintenanceRun(store, {
+      lane: "heavy",
+      phase: "gate",
+      status: "skipped",
+      reason: "lease_unavailable",
+      finishedAt: new Date().toISOString(),
+    });
+    results.push(loadMaintenanceRun(store, skippedId));
+  }
+
+  return results;
+}
+
+function loadMaintenanceRun(store: Store, id: number): MaintenanceRunSummary {
+  const row = store.db.prepare(
+    `SELECT id, lane, phase, status, reason, selected_count, processed_count,
+            created_count, updated_count, rejected_count, null_call_count,
+            started_at, finished_at, metrics_json
+       FROM maintenance_runs WHERE id = ?`,
+  ).get(id) as MaintenanceRunSummary | undefined;
+  if (!row) {
+    throw new Error(`loadMaintenanceRun: row ${id} not found`);
+  }
+  return row;
+}
+
+/**
+ * Start the heavy-maintenance worker loop. Fire-and-forget — returns a stop
+ * function the caller can invoke on process shutdown. Off by default — the
+ * caller decides whether to start it via `CLAWMEM_HEAVY_LANE=true` or equivalent.
+ *
+ * A reentrancy guard prevents overlapping ticks if a prior tick is still
+ * running when the next interval fires. Separate from the DB-backed lease,
+ * which prevents overlap across processes.
+ */
+export function startHeavyMaintenanceWorker(
+  store: Store,
+  llm: LlamaCpp,
+  cfg: HeavyMaintenanceConfig = {},
+): () => void {
+  const merged = { ...DEFAULT_CONFIG, ...cfg };
+  // Clamp interval to minimum 30 seconds so buggy configs can't pin the CPU.
+  const interval = Math.max(30_000, merged.intervalMs);
+
+  console.log(
+    `[heavy-lane] Starting worker (interval=${interval}ms, ` +
+      `window=${merged.windowStartHour ?? "always"}-${merged.windowEndHour ?? "always"}, ` +
+      `maxUsagesPer10m=${merged.maxContextUsagesPer10m})`,
+  );
+
+  heavyTimer = setInterval(async () => {
+    if (heavyRunning) {
+      console.log("[heavy-lane] Skipping tick (still running)");
+      return;
+    }
+    heavyRunning = true;
+    try {
+      await runHeavyMaintenanceTick(store, llm, cfg);
+    } catch (err) {
+      console.error("[heavy-lane] Tick failed:", err);
+    } finally {
+      heavyRunning = false;
+    }
+  }, interval);
+  heavyTimer.unref();
+
+  return () => {
+    if (heavyTimer) {
+      clearInterval(heavyTimer);
+      heavyTimer = null;
+      console.log("[heavy-lane] Worker stopped");
+    }
+  };
+}

package/src/mcp.ts

@@ -39,6 +39,7 @@ import { classifyIntent, decomposeQuery, extractTemporalConstraint, type IntentT
 import { adaptiveTraversal, mergeTraversalResults, mpfpTraversal } from "./graph-traversal.ts";
 import { getDefaultLlamaCpp } from "./llm.ts";
 import { startConsolidationWorker, stopConsolidationWorker } from "./consolidation.ts";
+import { startHeavyMaintenanceWorker, type HeavyMaintenanceConfig } from "./maintenance.ts";
 import { listVaults, loadVaultConfig } from "./config.ts";
 import { getEntityGraphNeighbors, searchEntities } from "./entity.ts";
 
@@ -2604,10 +2605,42 @@ This is the recommended entry point for ALL memory queries.`,
     startConsolidationWorker(store, llm, intervalMs);
   }
 
+  // v0.8.0 Ext 5: Start heavy-maintenance worker if enabled. Runs on a
+  // longer interval than the light lane, only inside a configurable quiet
+  // window, and gated by context_usage query-rate so interactive sessions
+  // are never starved. Off by default.
+  let stopHeavyLane: (() => void) | null = null;
+  if (Bun.env.CLAWMEM_HEAVY_LANE === "true") {
+    const llm = getDefaultLlamaCpp();
+    const cfg: HeavyMaintenanceConfig = {
+      intervalMs: Bun.env.CLAWMEM_HEAVY_LANE_INTERVAL
+        ? parseInt(Bun.env.CLAWMEM_HEAVY_LANE_INTERVAL, 10)
+        : undefined,
+      windowStartHour: Bun.env.CLAWMEM_HEAVY_LANE_WINDOW_START
+        ? parseInt(Bun.env.CLAWMEM_HEAVY_LANE_WINDOW_START, 10)
+        : null,
+      windowEndHour: Bun.env.CLAWMEM_HEAVY_LANE_WINDOW_END
+        ? parseInt(Bun.env.CLAWMEM_HEAVY_LANE_WINDOW_END, 10)
+        : null,
+      maxContextUsagesPer10m: Bun.env.CLAWMEM_HEAVY_LANE_MAX_USAGES
+        ? parseInt(Bun.env.CLAWMEM_HEAVY_LANE_MAX_USAGES, 10)
+        : undefined,
+      staleObservationLimit: Bun.env.CLAWMEM_HEAVY_LANE_OBS_LIMIT
+        ? parseInt(Bun.env.CLAWMEM_HEAVY_LANE_OBS_LIMIT, 10)
+        : undefined,
+      staleDeductiveLimit: Bun.env.CLAWMEM_HEAVY_LANE_DED_LIMIT
+        ? parseInt(Bun.env.CLAWMEM_HEAVY_LANE_DED_LIMIT, 10)
+        : undefined,
+      useSurprisalSelector: Bun.env.CLAWMEM_HEAVY_LANE_SURPRISAL === "true",
+    };
+    stopHeavyLane = startHeavyMaintenanceWorker(store, llm, cfg);
+  }
+
   // Signal handlers for graceful shutdown
   process.on("SIGINT", () => {
     console.error("\n[mcp] Received SIGINT, shutting down...");
     stopConsolidationWorker();
+    if (stopHeavyLane) stopHeavyLane();
     closeAllStores();
     process.exit(0);
   });
@@ -2615,6 +2648,7 @@ This is the recommended entry point for ALL memory queries.`,
   process.on("SIGTERM", () => {
     console.error("\n[mcp] Received SIGTERM, shutting down...");
     stopConsolidationWorker();
+    if (stopHeavyLane) stopHeavyLane();
     closeAllStores();
     process.exit(0);
   });

package/src/store.ts

@@ -854,6 +854,41 @@ function initializeDatabase(db: Database): void {
   if (!mrColNames.has("contradict_confidence")) {
     try { db.exec(`ALTER TABLE memory_relations ADD COLUMN contradict_confidence REAL`); } catch { /* column exists */ }
   }
+
+  // v0.8.0 Ext 5: Heavy maintenance lane journal. Every scheduled attempt
+  // writes one row — including skips — so operators can reconstruct why a
+  // lane did or did not run on any tick.
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS maintenance_runs (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      lane TEXT NOT NULL,
+      phase TEXT NOT NULL,
+      status TEXT NOT NULL,
+      reason TEXT,
+      selected_count INTEGER NOT NULL DEFAULT 0,
+      processed_count INTEGER NOT NULL DEFAULT 0,
+      created_count INTEGER NOT NULL DEFAULT 0,
+      updated_count INTEGER NOT NULL DEFAULT 0,
+      rejected_count INTEGER NOT NULL DEFAULT 0,
+      null_call_count INTEGER NOT NULL DEFAULT 0,
+      started_at TEXT NOT NULL DEFAULT (datetime('now')),
+      finished_at TEXT,
+      metrics_json TEXT
+    )
+  `);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_maintenance_runs_lane_started ON maintenance_runs(lane, started_at DESC)`);
+
+  // v0.8.0 Ext 5: DB-backed worker lease table for multi-process exclusivity
+  // on the heavy lane. Lease holders fence via random token; expired leases
+  // are reclaimed via atomic upsert inside a transaction.
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS worker_leases (
+      worker_name TEXT PRIMARY KEY,
+      lease_token TEXT NOT NULL,
+      acquired_at TEXT NOT NULL,
+      expires_at TEXT NOT NULL
+    )
+  `);
 }
 
 

package/src/worker-lease.ts

@@ -0,0 +1,141 @@
+/**
+ * ClawMem Worker Lease (v0.8.0 Ext 5)
+ *
+ * DB-backed exclusive lease for heavy-lane workers. Uses the `worker_leases`
+ * table (schema in store.ts) instead of module globals so multiple processes
+ * sharing a vault cannot run heavy maintenance concurrently.
+ *
+ * Lease lifecycle:
+ *   1. acquireWorkerLease inserts or reclaims an expired row via transaction
+ *      and returns a random fencing token on success.
+ *   2. The holder runs its work.
+ *   3. releaseWorkerLease deletes the row only if the caller's token matches,
+ *      so a lease reclaimed by another worker after TTL expiry cannot be
+ *      torn down by the original holder.
+ *
+ * withWorkerLease wraps acquire/release around a callback; failure to acquire
+ * is a silent no-op (returns `{acquired: false}`) — callers should log a
+ * `skipped` journal row with reason `lease_unavailable`.
+ */
+
+import { randomBytes } from "node:crypto";
+import type { Store } from "./store.ts";
+
+export interface LeaseAcquireResult {
+  acquired: boolean;
+  token?: string;
+  expiresAt?: string;
+}
+
+function nowIso(now: Date = new Date()): string {
+  return now.toISOString();
+}
+
+function futureIso(now: Date, ttlMs: number): string {
+  return new Date(now.getTime() + ttlMs).toISOString();
+}
+
+/**
+ * Attempt to acquire an exclusive lease on `workerName` for `ttlMs`.
+ *
+ * Returns `{acquired: true, token, expiresAt}` on success, or
+ * `{acquired: false}` if another worker holds a live (non-expired) lease.
+ *
+ * Race-safe under multi-process contention: uses a single
+ * `INSERT ... ON CONFLICT DO UPDATE ... WHERE expires_at <= ?` statement
+ * so the "no row → insert" and "expired row → update" paths cannot
+ * both fire for two concurrent callers. SQLite's changes() reports 1
+ * iff THIS call either inserted a fresh row or reclaimed an expired row;
+ * 0 means a live lease was held by someone else.
+ *
+ * Any SQLITE_BUSY / constraint failure is translated to
+ * `{ acquired: false }` so the advertised non-throw contract holds for
+ * callers that are layering `shouldRunHeavyMaintenance` above this.
+ */
+export function acquireWorkerLease(
+  store: Store,
+  workerName: string,
+  ttlMs: number,
+  now: Date = new Date(),
+): LeaseAcquireResult {
+  if (ttlMs <= 0) {
+    throw new Error(`acquireWorkerLease: ttlMs must be positive, got ${ttlMs}`);
+  }
+  const token = randomBytes(16).toString("hex");
+  const acquiredAt = nowIso(now);
+  const expiresAt = futureIso(now, ttlMs);
+
+  try {
+    // Single-statement atomic acquire. The WHERE on the UPDATE clause
+    // only reclaims when the existing lease has expired (its expires_at
+    // <= our acquired_at); otherwise the ON CONFLICT DO UPDATE becomes
+    // a no-op and SQLite reports changes=0.
+    const result = store.db.prepare(
+      `INSERT INTO worker_leases
+         (worker_name, lease_token, acquired_at, expires_at)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(worker_name) DO UPDATE SET
+         lease_token = excluded.lease_token,
+         acquired_at = excluded.acquired_at,
+         expires_at = excluded.expires_at
+       WHERE worker_leases.expires_at <= excluded.acquired_at`,
+    ).run(workerName, token, acquiredAt, expiresAt);
+
+    if (result.changes === 0) {
+      return { acquired: false };
+    }
+    return { acquired: true, token, expiresAt };
+  } catch (err) {
+    // Defensive fallback: any unexpected DB error (SQLITE_BUSY under
+    // extreme contention, constraint error from schema drift, etc.) is
+    // translated to a lease-unavailable result instead of bubbling up,
+    // so heavy-maintenance callers always get a deterministic
+    // "skipped/lease_unavailable" journal row.
+    console.error(
+      `[worker-lease] acquire error for ${workerName}: ${(err as Error).message}`,
+    );
+    return { acquired: false };
+  }
+}
+
+/**
+ * Release a lease if the caller's token still matches. Returns `true` if
+ * the lease was owned and deleted, `false` if a different token held it
+ * (e.g., TTL expired and another worker reclaimed).
+ */
+export function releaseWorkerLease(
+  store: Store,
+  workerName: string,
+  token: string,
+): boolean {
+  const result = store.db.prepare(
+    `DELETE FROM worker_leases WHERE worker_name = ? AND lease_token = ?`,
+  ).run(workerName, token);
+  return result.changes > 0;
+}
+
+/**
+ * Run `fn` under an exclusive lease on `workerName`. If the lease cannot
+ * be acquired, returns `{acquired: false}` without invoking `fn`. The
+ * lease is always released in a `finally` block, even if `fn` throws.
+ *
+ * Rethrows any error from `fn` — callers are responsible for translating
+ * exceptions into journal rows.
+ */
+export async function withWorkerLease<T>(
+  store: Store,
+  workerName: string,
+  ttlMs: number,
+  fn: () => Promise<T>,
+): Promise<{ acquired: boolean; result?: T }> {
+  const lease = acquireWorkerLease(store, workerName, ttlMs);
+  if (!lease.acquired || !lease.token) {
+    return { acquired: false };
+  }
+  try {
+    const result = await fn();
+    return { acquired: true, result };
+  } finally {
+    releaseWorkerLease(store, workerName, lease.token);
+  }
+}