clawmem 0.8.1 → 0.8.2

package/AGENTS.md

@@ -94,9 +94,9 @@ curl http://host:8090/v1/models
 | `CLAWMEM_NO_LOCAL_MODELS` | `false` | Blocks `node-llama-cpp` from auto-downloading GGUF models. Set `true` for remote-only setups. |
 | `CLAWMEM_VAULTS` | (none) | JSON map of vault name → SQLite path for multi-vault mode. E.g. `{"work":"~/.cache/clawmem/work.sqlite"}` |
 | `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_ENABLE_CONSOLIDATION` | disabled | Background worker backfills unenriched docs and runs Phase 2/3 consolidation + deductive synthesis. **v0.8.2:** every tick is wrapped in a DB-backed `worker_leases` row (`light-consolidation` key), so multiple host processes against the same vault cannot race on Phase 2 merge writes. Hosted by either `clawmem watch` (canonical, long-lived) or `clawmem mcp` (per-session fallback). |
 | `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` | 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. **v0.8.2:** canonical host is `clawmem watch` (e.g. systemd `clawmem-watcher.service`); `clawmem mcp` retains the same gate as a fallback host but emits a stderr warning advising operators to move heavy-lane hosting to the watcher because per-session stdio MCPs may never be alive during the configured quiet window. |
 | `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). |

package/CLAUDE.md

@@ -94,9 +94,9 @@ curl http://host:8090/v1/models
 | `CLAWMEM_NO_LOCAL_MODELS` | `false` | Blocks `node-llama-cpp` from auto-downloading GGUF models. Set `true` for remote-only setups. |
 | `CLAWMEM_VAULTS` | (none) | JSON map of vault name → SQLite path for multi-vault mode. E.g. `{"work":"~/.cache/clawmem/work.sqlite"}` |
 | `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_ENABLE_CONSOLIDATION` | disabled | Background worker backfills unenriched docs and runs Phase 2/3 consolidation + deductive synthesis. **v0.8.2:** every tick is wrapped in a DB-backed `worker_leases` row (`light-consolidation` key), so multiple host processes against the same vault cannot race on Phase 2 merge writes. Hosted by either `clawmem watch` (canonical, long-lived) or `clawmem mcp` (per-session fallback). |
 | `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` | 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. **v0.8.2:** canonical host is `clawmem watch` (e.g. systemd `clawmem-watcher.service`); `clawmem mcp` retains the same gate as a fallback host but emits a stderr warning advising operators to move heavy-lane hosting to the watcher because per-session stdio MCPs may never be alive during the configured quiet window. |
 | `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). |

package/README.md

@@ -108,6 +108,22 @@ Adds +56 tests (13 worker-lease + 35 maintenance unit + 8 maintenance integratio
 
 Adds +27 tests (22 unit + 5 integration) on top of the v0.8.0 baseline.
 
+### v0.8.2 Dual-Host Worker Architecture
+
+Both maintenance lanes can now be hosted by the long-lived `clawmem watch` watcher service in addition to the existing per-session `clawmem mcp` host. This makes the systemd-managed watcher the canonical 24/7 home for the v0.8.0 heavy maintenance lane — its quiet-window logic finally sees a live worker at the configured hours regardless of whether any Claude Code session is open. The light consolidation lane (Phase 1 backfill + Phase 2 merge + Phase 3 deductive synthesis + Phase 4 recall stats) now also acquires its own DB-backed `worker_leases` row before each tick, symmetric with the heavy lane's existing exclusivity, so multiple host processes against the same vault cannot race on Phase 2 merges or Phase 3 deductive writes.
+
+- **Light-lane worker lease** — `runConsolidationTick` wraps every tick (Phase 1 → 4) in `withWorkerLease` against a new `light-consolidation` worker name with a 10-minute TTL. Two host processes (e.g. one watcher service + one per-session stdio MCP) cannot both consolidate the same near-duplicate observations or both INSERT a duplicate row into `consolidated_observations`. Phase 1 enrichment is also serialized — overkill for cost but cleaner for symmetry. The in-process `isRunning` reentrancy guard remains the cheap first defense before the SQLite lease round-trip.
+- **`cmdWatch` hosts both workers** — `clawmem watch` honors the same `CLAWMEM_ENABLE_CONSOLIDATION` and `CLAWMEM_HEAVY_LANE` env-var gates as `cmdMcp`. Off by default. Mirror the existing systemd unit (or your wrapper `.env`) to opt in. The recommended deployment for v0.8.2+ is to set both env vars on `clawmem-watcher.service` and leave `cmdMcp` unset, so the heavy lane has a continuously available host independent of Claude Code session lifecycle.
+- **`cmdMcp` is now a fallback host with a heavy-lane warning** — `cmdMcp` retains the same env-var gates so non-watcher deployments (e.g. macOS users running everything via Claude Code launchd) keep working unchanged. When `CLAWMEM_HEAVY_LANE=true` is set on a stdio MCP host, `cmdMcp` emits a one-line warning to stderr advising operators to move heavy-lane hosting to `clawmem watch` instead.
+- **Async drain on shutdown** — both worker stop helpers (`stopConsolidationWorker` and the closure returned by `startHeavyMaintenanceWorker`) are now `async`, clearing their `setInterval` AND polling their in-flight running flag until any mid-tick worker drains. This guarantees the worker's `withWorkerLease` finally block runs against a still-open store, so the lease is released cleanly instead of leaking until TTL expiry. Bounded waits (15s light, 30s heavy) prevent a stuck tick from wedging shutdown indefinitely; the next process reclaims any stranded lease atomically.
+- **Signal handlers registered before worker startup** — both `cmdWatch` and `cmdMcp` now register their `SIGINT`/`SIGTERM` handlers BEFORE any worker initialization. A signal arriving in the brief window between worker startup and handler registration would otherwise terminate the host via the default signal action (exit 143) and skip the async drain entirely.
+- **Subprocess smoke test** — new `tests/integration/cmdwatch-workers.integration.test.ts` spawns `bun src/clawmem.ts watch` against a temp vault with short worker intervals, exercises the env-var gates, exercises a real heavy-lane tick (slow path, ~35s), and asserts the lease is released cleanly on `SIGTERM`.
+- **Bug fix: removed dead skill-vault watcher block from `clawmem.ts cmdWatch()`** — a try/catch wrapped block had been silently destructuring `getSkillContentRoot` from `./config.ts`, but that helper is forge-internal and was never exported in public ClawMem. The runtime catch swallowed the failure so it had no observable effect, but TypeScript flagged a static `TS2339` error on the destructure. v0.8.2 removes the dead code path. No behavior change for public users.
+
+Adds +15 tests (9 light-lane lease unit + 5 cmdWatch fast subprocess + 1 cmdWatch slow subprocess) on top of the v0.8.1 baseline.
+
+For operational guidance — enabling the workers via systemd drop-in, tuning intervals to your usage pattern, monitoring queries, and rollback steps — see [docs/guides/systemd-services.md](docs/guides/systemd-services.md#background-maintenance-workers-v082).
+
 ## Architecture
 
 <p align="center">
@@ -173,7 +189,7 @@ After installing, here's the full journey from zero to working memory:
 | **1. Bootstrap** | Create a vault, index your first collection, embed, install hooks and MCP | `clawmem bootstrap ~/notes --name notes` | One command does it all. Or run each step manually (see below). |
 | **2. Choose models** | Pick embedding + reranker models based on your hardware | 12GB+ VRAM → SOTA stack (zembed-1 + zerank-2). Less → QMD native combo. No GPU → cloud embedding or CPU fallback. | [GPU Services](#gpu-services) |
 | **3. Download models** | Get the GGUF files for your chosen stack | `wget` from HuggingFace, or let `node-llama-cpp` auto-download the QMD native models on first use | [Embedding](#embedding), [LLM Server](#llm-server), [Reranker Server](#reranker-server) |
-| **4. Start services** | Run GPU servers (if using dedicated GPU) and background services | `llama-server` for each model. systemd units for watcher + embed timer. | [systemd services](docs/guides/systemd-services.md) |
+| **4. Start services** | Run GPU servers (if using dedicated GPU) and background services. Optionally enable the v0.8.2 background maintenance workers in the watcher unit so consolidation + deductive synthesis run automatically. | `llama-server` for each model. systemd units for watcher + embed timer. Drop-in for the watcher to enable workers + tune intervals + set the quiet window. | [systemd services](docs/guides/systemd-services.md), [background workers](docs/guides/systemd-services.md#background-maintenance-workers-v082) |
 | **5. Decide what to index** | Add collections for your projects, notes, research, and domain docs | `clawmem collection add ~/project --name project` | The more relevant markdown you index, the better retrieval works. See [building a rich context field](docs/introduction.md#building-a-rich-context-field). |
 | **6. Connect your agent** | Hook into Claude Code, OpenClaw, Hermes, or any MCP client | `clawmem setup hooks && clawmem setup mcp` for Claude Code. `clawmem setup openclaw` for OpenClaw. Copy `src/hermes/` to Hermes plugins for Hermes. | [Integration](#integration) |
 | **7. Verify** | Confirm everything is working | `clawmem doctor` (full health check) or `clawmem status` (quick index stats) | [Verify Installation](#verify-installation) |
@@ -223,6 +239,8 @@ clawmem embed             # Re-embed if upgrading embedding models (not needed f
 
 Routine patch updates (e.g. 0.2.0 → 0.2.1) do not require reindexing.
 
+For version-specific upgrade notes (opt-in features, optional cleanup steps, verification commands), see [docs/guides/upgrading.md](docs/guides/upgrading.md).
+
 ### Integration
 
 #### Claude Code

package/SKILL.md

@@ -85,14 +85,14 @@ curl http://host:8090/v1/models
 | `CLAWMEM_RERANK_URL` | `http://localhost:8090` | Reranker server. Falls to `node-llama-cpp` if unset + `NO_LOCAL_MODELS=false`. |
 | `CLAWMEM_NO_LOCAL_MODELS` | `false` | Blocks `node-llama-cpp` auto-downloads. Set `true` for remote-only. |
 | `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_ENABLE_CONSOLIDATION` | disabled | Light-lane consolidation worker (Phase 1 backfill + Phase 2 merge + Phase 3 deductive synthesis + Phase 4 recall stats). **v0.8.2:** every tick wraps in a `worker_leases` row (`light-consolidation` key) so multiple host processes against the same vault cannot race on Phase 2 merges. Hosted by `clawmem watch` (canonical) or `clawmem mcp` (per-session fallback). |
 | `CLAWMEM_CONSOLIDATION_INTERVAL` | 300000 | Worker interval in ms (min 15000). |
 | `CLAWMEM_MERGE_SCORE_NORMAL` | `0.93` | **v0.7.1.** Phase 2 merge-safety score threshold when candidate and existing anchors align. |
 | `CLAWMEM_MERGE_SCORE_STRICT` | `0.98` | **v0.7.1.** Strictest merge-safety threshold (fallback when anchors are ambiguous). |
 | `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` | 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. **v0.8.2:** canonical host is `clawmem watch` (e.g. systemd `clawmem-watcher.service`); `clawmem mcp` retains the same gate as a fallback host but emits a stderr warning advising operators to move heavy-lane hosting to the watcher because per-session stdio MCPs may never be alive during the configured quiet window. |
 | `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'`. |
@@ -767,7 +767,7 @@ clawmem consolidate [--dry-run] # Find and archive duplicate low-confidence docu
 - SAME (composite scoring), MAGMA (intent + graph), A-MEM (self-evolving notes) layer on top of QMD substrate.
 - Three `llama-server` instances on local or remote GPU. Wrapper defaults to `localhost:8088/8089/8090`.
 - `CLAWMEM_NO_LOCAL_MODELS=false` (default) allows in-process fallback. Set `true` for remote-only to fail fast.
-- Consolidation worker (`CLAWMEM_ENABLE_CONSOLIDATION=true`) backfills unenriched docs. Only runs if MCP process stays alive long enough (every 5min).
+- Consolidation worker (`CLAWMEM_ENABLE_CONSOLIDATION=true`) backfills unenriched docs and runs Phase 2 merge / Phase 3 deductive synthesis. **v0.8.2:** hosted by either `clawmem watch` (long-lived, canonical) or `clawmem mcp` (per-session fallback); every tick acquires a `light-consolidation` `worker_leases` row before doing work, so dual-hosting against the same vault is safe.
 - Beads integration: `syncBeadsIssues()` queries `bd` CLI (Dolt backend, v0.58.0+), creates markdown docs, maps dependency edges into `memory_relations`. Watcher auto-triggers on `.beads/` changes; `beads_sync` MCP for manual sync.
 - HTTP REST API: `clawmem serve [--port 7438]` — optional REST server on localhost. Search, retrieval, lifecycle, and graph traversal. `POST /retrieve` mirrors `memory_retrieve` with auto-routing (keyword/semantic/causal/timeline/hybrid). `POST /search` provides direct mode selection. Bearer token auth via `CLAWMEM_API_TOKEN` env var (disabled if unset).
 - OpenClaw ContextEngine plugin: `clawmem setup openclaw` — registers as native OpenClaw context engine. Dual-mode: shares vault with Claude Code hooks. Uses `before_prompt_build` for retrieval, `afterTurn()` for extraction, `compact()` for pre-compaction + runtime delegation (v0.3.0+, required for OpenClaw v2026.3.28+).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmem",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "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/clawmem.ts

@@ -45,6 +45,14 @@ import { enrichResults, reciprocalRankFusion, toRanked, type RankedResult } from
 import { splitDocument } from "./splitter.ts";
 import { getProfile, updateProfile, isProfileStale } from "./profile.ts";
 import { regenerateAllDirectoryContexts } from "./directory-context.ts";
+import {
+  startConsolidationWorker,
+  stopConsolidationWorker,
+} from "./consolidation.ts";
+import {
+  parseHeavyLaneConfigFromEnv,
+  startHeavyMaintenanceWorker,
+} from "./maintenance.ts";
 import { readHookInput, writeHookOutput, makeEmptyOutput, type HookOutput } from "./hooks.ts";
 import { contextSurfacing } from "./hooks/context-surfacing.ts";
 import { sessionBootstrap } from "./hooks/session-bootstrap.ts";
@@ -1363,13 +1371,74 @@ async function cmdWatch() {
   const dirs = collections.map(col => col.path);
   const s = getStore();
 
+  // v0.8.2 Codex Turn 1 fix: register signal handlers BEFORE any async
+  // startup work or worker startup. Resources are declared as null and
+  // assigned once their respective creators run; the shutdown closure
+  // captures the variable references so updates after registration are
+  // visible. Without this ordering, a SIGTERM arriving during the brief
+  // window between the worker startup banner and the handler registration
+  // would terminate the watcher via the default signal action (exit 143)
+  // instead of running the async drain → release → close sequence.
+  let stopHeavyLane: (() => Promise<void>) | null = null;
+  let watcherHandle: { close: () => void } | null = null;
+  let checkpointTimerHandle: Timer | null = null;
+
+  // Graceful shutdown — stop workers, close watchers, then exit. SIGTERM
+  // handling is critical for systemd `systemctl --user stop` to shut down
+  // cleanly instead of being killed by the unit timeout. Both worker stops
+  // are awaited so any mid-tick worker drains and releases its lease via
+  // its own withWorkerLease finally block before we close the store.
+  const shutdown = async (signal: string) => {
+    console.log(`\n${c.dim}[watch] Received ${signal}, shutting down...${c.reset}`);
+    if (stopHeavyLane) {
+      await stopHeavyLane();
+      stopHeavyLane = null;
+    }
+    await stopConsolidationWorker();
+    if (checkpointTimerHandle) {
+      clearInterval(checkpointTimerHandle);
+      checkpointTimerHandle = null;
+    }
+    if (watcherHandle) {
+      watcherHandle.close();
+      watcherHandle = null;
+    }
+    closeStore();
+    process.exit(0);
+  };
+  process.on("SIGINT", () => { void shutdown("SIGINT"); });
+  process.on("SIGTERM", () => { void shutdown("SIGTERM"); });
+
   console.log(`${c.bold}Watching ${dirs.length} collection(s) for changes...${c.reset}`);
   for (const col of collections) {
     console.log(`  ${c.dim}${col.name}: ${col.path}${c.reset}`);
   }
   console.log(`${c.dim}Press Ctrl+C to stop.${c.reset}`);
 
-  const watcher = startWatcher(dirs, {
+  // v0.8.2: Light + heavy maintenance lane workers (opt-in via env vars).
+  // Hosting them in `cmdWatch` makes the long-lived watcher service the
+  // canonical host for both lanes — `clawmem-watcher.service` runs 24/7
+  // under systemd, so the heavy lane's quiet-window logic actually sees a
+  // live worker at the configured hours regardless of whether any Claude
+  // Code session is open. `cmdMcp` (stdio MCP) keeps the same env-var
+  // gates as a fallback host, but warns when CLAWMEM_HEAVY_LANE=true
+  // since per-session MCPs are short-lived. Both hosts share the same
+  // DB-backed `worker_leases` exclusivity (heavy lane v0.8.0, light lane
+  // v0.8.2), so running both at once is safe.
+  if (Bun.env.CLAWMEM_ENABLE_CONSOLIDATION === "true") {
+    const llm = getDefaultLlamaCpp();
+    const intervalMs = parseInt(Bun.env.CLAWMEM_CONSOLIDATION_INTERVAL || "300000", 10);
+    console.log(`${c.dim}[watch] Starting consolidation worker (light lane, interval=${intervalMs}ms)${c.reset}`);
+    startConsolidationWorker(s, llm, intervalMs);
+  }
+  if (Bun.env.CLAWMEM_HEAVY_LANE === "true") {
+    const llm = getDefaultLlamaCpp();
+    const cfg = parseHeavyLaneConfigFromEnv();
+    console.log(`${c.dim}[watch] Starting heavy maintenance lane worker${c.reset}`);
+    stopHeavyLane = startHeavyMaintenanceWorker(s, llm, cfg);
+  }
+
+  watcherHandle = startWatcher(dirs, {
     debounceMs: 2000,
     onChanged: async (fullPath, event) => {
       // Find which collection this belongs to
@@ -1424,45 +1493,12 @@ async function cmdWatch() {
     },
   });
 
-  // Skill vault watcher: watch _clawmem-skills/ content root if configured
-  let skillWatcher: { close: () => void } | null = null;
-  try {
-    const { getVaultPath, getSkillContentRoot } = await import("./config.ts");
-    const { resolveStore } = await import("./store.ts");
-    const skillVaultPath = getVaultPath("skill");
-    const skillRoot = getSkillContentRoot();
-
-    if (skillVaultPath && existsSync(skillRoot)) {
-      const skillStore = resolveStore("skill");
-      console.log(`${c.bold}Watching skill vault content root...${c.reset}`);
-      console.log(`  ${c.dim}skill: ${skillRoot} → ${skillVaultPath}${c.reset}`);
-
-      skillWatcher = startWatcher([skillRoot], {
-        debounceMs: 2000,
-        onChanged: async (fullPath, event) => {
-          const relativePath = fullPath.slice(skillRoot.length + 1);
-          console.log(`${c.dim}[${event}]${c.reset} skill/${relativePath}`);
-
-          const stats = await indexCollection(skillStore, "skill-observations", skillRoot, "**/*.md");
-          if (stats.added > 0 || stats.updated > 0 || stats.removed > 0) {
-            console.log(`  skill: +${stats.added} ~${stats.updated} -${stats.removed}`);
-          }
-        },
-        onError: (err) => {
-          console.error(`${c.red}Skill watch error: ${err.message}${c.reset}`);
-        },
-      });
-    }
-  } catch {
-    // Skill vault not configured — skip
-  }
-
   // Periodic WAL checkpoint: the watcher holds a long-lived DB connection which
   // prevents SQLite auto-checkpoint from shrinking the WAL file. Without this,
   // the WAL grows unbounded (observed 77MB+), slowing every concurrent DB access
   // (hooks, MCP) and eventually causing UserPromptSubmit hook timeouts.
   const WAL_CHECKPOINT_INTERVAL = 5 * 60 * 1000; // 5 minutes
-  const checkpointTimer = setInterval(() => {
+  checkpointTimerHandle = setInterval(() => {
     try {
       s.db.exec("PRAGMA wal_checkpoint(PASSIVE)");
     } catch {
@@ -1470,16 +1506,7 @@ async function cmdWatch() {
     }
   }, WAL_CHECKPOINT_INTERVAL);
 
-  // Keep running until Ctrl+C
-  process.on("SIGINT", () => {
-    clearInterval(checkpointTimer);
-    watcher.close();
-    skillWatcher?.close();
-    closeStore();
-    process.exit(0);
-  });
-
-  // Block forever
+  // Block forever — shutdown is driven by signal handlers registered above.
   await new Promise(() => {});
 }
 

package/src/consolidation.ts

@@ -17,6 +17,7 @@ import type { LlamaCpp } from "./llm.ts";
 import { extractJsonFromLLM } from "./amem.ts";
 import { hashContent } from "./indexer.ts";
 import { passesMergeSafety } from "./text-similarity.ts";
+import { withWorkerLease } from "./worker-lease.ts";
 import {
   checkContradiction,
   isActionableContradiction,
@@ -166,22 +167,68 @@ let consolidationTimer: Timer | null = null;
 let isRunning = false;
 let tickCount = 0;
 
+/**
+ * DB-backed worker lease name for the light consolidation lane (v0.8.2).
+ * Distinct from the heavy-maintenance lane's lease so both lanes can hold
+ * independent exclusivity against the same SQLite vault without colliding.
+ */
+export const DEFAULT_LIGHT_LANE_WORKER_NAME = "light-consolidation";
+
+/**
+ * Default worker-lease TTL for the light lane (10 min). A tick normally
+ * finishes in seconds, but Phase 2 consolidation + Phase 3 deductive
+ * synthesis can stack many LLM calls under worst-case conditions. A 10-min
+ * ceiling covers that case without leaving a stranded lease forever if the
+ * process is SIGKILL'd mid-tick — the next worker reclaims it atomically
+ * via the single-statement upsert in `acquireWorkerLease` once the TTL
+ * has elapsed.
+ */
+export const DEFAULT_LIGHT_LANE_LEASE_TTL_MS = 10 * 60 * 1000;
+
+/**
+ * Options for a single consolidation tick (v0.8.2). All fields optional;
+ * omitting the bag reproduces pre-v0.8.2 behavior except for the newly
+ * added DB-backed lease wrap, which is always on.
+ *
+ *  - `workerName`   override the lease name (default "light-consolidation").
+ *                   Tests should pass a unique name to avoid cross-test
+ *                   contention with other suites running in the same bun
+ *                   process.
+ *  - `leaseTtlMs`   override the lease TTL. Tests use short TTLs (e.g.
+ *                   100 ms with a past `now`) to exercise expiry reclaim
+ *                   without real delay.
+ */
+export interface ConsolidationTickOptions {
+  workerName?: string;
+  leaseTtlMs?: number;
+}
+
 // =============================================================================
 // Worker Functions
 // =============================================================================
 
 /**
- * Starts the consolidation worker that enriches documents missing A-MEM metadata
- * and periodically consolidates observations.
+ * Starts the consolidation worker that enriches documents missing A-MEM
+ * metadata and periodically consolidates observations.
  *
- * @param store - Store instance with A-MEM methods
- * @param llm - LLM instance for memory note construction
- * @param intervalMs - Tick interval in milliseconds (default: 300000 = 5 min)
+ * v0.8.2 — every tick is wrapped in a DB-backed worker lease (see
+ * `runConsolidationTick`), so multiple host processes running this worker
+ * against the same vault cannot run Phase 2 merge / Phase 3 deductive
+ * synthesis concurrently. The tick still uses an in-process `isRunning`
+ * reentrancy guard that fires before the lease round-trip, so the common
+ * case (single process, overlapping timer fires) is handled without
+ * touching SQLite.
+ *
+ * @param store      - Store instance with A-MEM methods
+ * @param llm        - LLM instance for memory note construction
+ * @param intervalMs - Tick interval in milliseconds (default 300000 = 5 min)
+ * @param opts       - Optional lease overrides (worker name, TTL)
  */
 export function startConsolidationWorker(
   store: Store,
   llm: LlamaCpp,
-  intervalMs: number = 300000
+  intervalMs: number = 300000,
+  opts: ConsolidationTickOptions = {},
 ): void {
   // Clamp interval to minimum 15 seconds
   const interval = Math.max(15000, intervalMs);
@@ -190,7 +237,7 @@ export function startConsolidationWorker(
 
   // Set up periodic tick
   consolidationTimer = setInterval(async () => {
-    await tick(store, llm);
+    await runConsolidationTick(store, llm, opts);
   }, interval);
 
   // Use unref() to avoid blocking process exit
@@ -200,55 +247,133 @@ export function startConsolidationWorker(
 }
 
 /**
- * Stops the consolidation worker.
+ * Stops the consolidation worker. Async since v0.8.2 — clears the interval
+ * AND awaits any in-flight tick before resolving, so callers (signal
+ * handlers, test fixtures) can safely close the store afterward without
+ * yanking the DB out from under a mid-tick worker. The wait is bounded by
+ * `STOP_DRAIN_TIMEOUT_MS` (15s) so a pathologically stuck tick cannot
+ * wedge shutdown indefinitely; if the timeout fires, the function logs
+ * and returns anyway (the next process will reclaim the stale lease via
+ * the v0.8.0 `worker_leases` TTL upsert).
  */
-export function stopConsolidationWorker(): void {
+export async function stopConsolidationWorker(): Promise<void> {
   if (consolidationTimer) {
     clearInterval(consolidationTimer);
     consolidationTimer = null;
+    console.log("[consolidation] Worker stop signaled — draining in-flight tick");
+  }
+  const deadline = Date.now() + STOP_DRAIN_TIMEOUT_MS;
+  while (isRunning && Date.now() < deadline) {
+    await new Promise<void>((resolve) => setTimeout(resolve, 50));
+  }
+  if (isRunning) {
+    console.log(
+      `[consolidation] Worker stop drain timed out after ${STOP_DRAIN_TIMEOUT_MS}ms — tick still running`,
+    );
+  } else {
     console.log("[consolidation] Worker stopped");
   }
 }
 
 /**
- * Single worker tick: A-MEM backfill + periodic observation consolidation.
+ * v0.8.2 — bounded wait for in-flight light-lane tick during shutdown.
+ * 15 seconds is more than enough for Phase 1 + Phase 4 to drain (the
+ * cheap phases) and lets Phase 2/3 mid-flight LLM calls finish naturally
+ * in most environments. Stuck-tick scenarios (e.g. unreachable LLM with
+ * no socket timeout) fall back to the v0.8.0 worker_leases TTL reclaim.
+ */
+const STOP_DRAIN_TIMEOUT_MS = 15_000;
+
+/**
+ * Run one consolidation tick: Phase 1 (A-MEM backfill) → Phase 2 (observation
+ * consolidation, every 6th tick) → Phase 3 (deductive synthesis, every 3rd
+ * tick) → Phase 4 (recall stats recomputation, every tick).
+ *
+ * v0.8.2 — wrapped in a DB-backed worker lease so at most one host process
+ * ticks at a time against the same vault, symmetric with the v0.8.0 heavy
+ * maintenance lane's `worker_leases` exclusivity pattern. Phase 2 is the
+ * race-sensitive phase Codex flagged in the v0.8.2 pre-rollout review:
+ * without the lease, two concurrent workers could both INSERT a new
+ * consolidated observation for the same cluster, or both merge into the
+ * same existing row and lose source_ids from the read-modify-write update
+ * in `mergeIntoExistingConsolidation`.
+ *
+ * An in-process reentrancy guard (`isRunning`) fires before the lease
+ * round-trip, so overlapping setInterval timer fires from the same process
+ * do not incur a SQLite round-trip per skip.
+ *
+ * Returns `{ acquired }` so integration tests (and the setInterval wrapper)
+ * can distinguish ticks that did real work from ticks skipped by the lease
+ * or reentrancy gate.
+ *
+ * Exported in v0.8.2 so tests can drive individual ticks directly without
+ * spinning up the setInterval loop.
  */
-async function tick(store: Store, llm: LlamaCpp): Promise<void> {
-  // Reentrancy guard
+export async function runConsolidationTick(
+  store: Store,
+  llm: LlamaCpp,
+  opts: ConsolidationTickOptions = {},
+): Promise<{ acquired: boolean }> {
+  // In-process reentrancy guard: catches overlapping setInterval fires in
+  // the same process before we hit SQLite. Cheap; the lease is the
+  // cross-process authority.
   if (isRunning) {
-    console.log("[consolidation] Skipping tick (already running)");
-    return;
+    console.log("[consolidation] Skipping tick (already running in-process)");
+    return { acquired: false };
   }
 
-  isRunning = true;
-  tickCount++;
+  const workerName = opts.workerName ?? DEFAULT_LIGHT_LANE_WORKER_NAME;
+  const leaseTtlMs = opts.leaseTtlMs ?? DEFAULT_LIGHT_LANE_LEASE_TTL_MS;
 
+  isRunning = true;
   try {
-    // Phase 1: A-MEM backfill (every tick)
-    await backfillAmem(store, llm);
+    const lease = await withWorkerLease(
+      store,
+      workerName,
+      leaseTtlMs,
+      async () => {
+        tickCount++;
+        try {
+          // Phase 1: A-MEM backfill (every tick)
+          await backfillAmem(store, llm);
+
+          // Phase 2: Observation consolidation (every 6th tick — ~30 min
+          // at default interval). Race-sensitive — see doc comment above.
+          if (tickCount % 6 === 0) {
+            await consolidateObservations(store, llm);
+          }
 
-    // Phase 2: Observation consolidation (every 6th tick, ~30 min at default interval)
-    if (tickCount % 6 === 0) {
-      await consolidateObservations(store, llm);
-    }
+          // Phase 3: Deductive synthesis (every 3rd tick — ~15 min).
+          // Writes are mostly idempotent on the hash-stable path but the
+          // anti-contamination validator still burns LLM calls, so
+          // running two workers in parallel is pure cost.
+          if (tickCount % 3 === 0) {
+            await generateDeductiveObservations(store, llm);
+          }
 
-    // Phase 3: Deductive synthesis (every 3rd tick, ~15 min at default interval)
-    if (tickCount % 3 === 0) {
-      await generateDeductiveObservations(store, llm);
-    }
+          // Phase 4: Recall stats recomputation (every tick — lightweight
+          // SQL aggregation). Non-critical — recall stats are
+          // informational, not retrieval-blocking.
+          try {
+            const updated = store.recomputeRecallStats();
+            if (updated > 0) {
+              console.log(`[consolidation] Phase 4: recomputed recall_stats for ${updated} docs`);
+            }
+          } catch (err) {
+            console.error("[consolidation] Phase 4 recall stats failed:", err);
+          }
+        } catch (err) {
+          console.error("[consolidation] Tick failed:", err);
+        }
+      },
+    );
 
-    // Phase 4: Recall stats recomputation (every tick — lightweight SQL aggregation)
-    try {
-      const updated = store.recomputeRecallStats();
-      if (updated > 0) {
-        console.log(`[consolidation] Phase 4: recomputed recall_stats for ${updated} docs`);
-      }
-    } catch (err) {
-      // Non-critical — recall stats are informational, not retrieval-blocking
-      console.error("[consolidation] Phase 4 recall stats failed:", err);
+    if (!lease.acquired) {
+      console.log(
+        `[consolidation] Skipping tick (lease '${workerName}' held by another worker)`,
+      );
     }
-  } catch (err) {
-    console.error("[consolidation] Tick failed:", err);
+    return { acquired: lease.acquired };
   } finally {
     isRunning = false;
   }

package/src/maintenance.ts

@@ -77,6 +77,37 @@ const DEFAULT_CONFIG: Required<Omit<HeavyMaintenanceConfig, "workerName" | "cloc
 
 const DEFAULT_WORKER_NAME = "heavy-maintenance";
 
+/**
+ * Parse a `HeavyMaintenanceConfig` from `Bun.env` (v0.8.2). Shared by every
+ * host that can start the heavy lane (`cmdMcp` in mcp.ts, `cmdWatch` in
+ * clawmem.ts) so the env var convention stays in one place. Each field is
+ * left undefined when its env var is unset, so `DEFAULT_CONFIG` continues
+ * to drive any field the operator did not explicitly override.
+ */
+export function parseHeavyLaneConfigFromEnv(): HeavyMaintenanceConfig {
+  return {
+    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",
+  };
+}
+
 // =============================================================================
 // Journal helpers
 // =============================================================================
@@ -503,7 +534,7 @@ export function startHeavyMaintenanceWorker(
   store: Store,
   llm: LlamaCpp,
   cfg: HeavyMaintenanceConfig = {},
-): () => void {
+): () => Promise<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);
@@ -530,11 +561,35 @@ export function startHeavyMaintenanceWorker(
   }, interval);
   heavyTimer.unref();
 
-  return () => {
+  // v0.8.2 — async stop handle. Clears the timer AND awaits any in-flight
+  // tick before resolving, so callers can safely close the store afterward
+  // without yanking the DB from under a mid-tick worker. Bounded wait —
+  // a pathologically stuck tick cannot wedge shutdown indefinitely; the
+  // worker_leases TTL upsert reclaims any stranded lease on the next
+  // process startup.
+  return async () => {
     if (heavyTimer) {
       clearInterval(heavyTimer);
       heavyTimer = null;
+      console.log("[heavy-lane] Worker stop signaled — draining in-flight tick");
+    }
+    const deadline = Date.now() + HEAVY_STOP_DRAIN_TIMEOUT_MS;
+    while (heavyRunning && Date.now() < deadline) {
+      await new Promise<void>((resolve) => setTimeout(resolve, 50));
+    }
+    if (heavyRunning) {
+      console.log(
+        `[heavy-lane] Worker stop drain timed out after ${HEAVY_STOP_DRAIN_TIMEOUT_MS}ms — tick still running`,
+      );
+    } else {
       console.log("[heavy-lane] Worker stopped");
     }
   };
 }
+
+/**
+ * v0.8.2 — bounded wait for in-flight heavy-lane tick during shutdown.
+ * 30 seconds covers a Phase 2 + Phase 3 stack with reasonable LLM latencies
+ * before falling back to the worker_leases TTL reclaim path.
+ */
+const HEAVY_STOP_DRAIN_TIMEOUT_MS = 30_000;

package/src/mcp.ts

@@ -39,7 +39,10 @@ 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 {
+  parseHeavyLaneConfigFromEnv,
+  startHeavyMaintenanceWorker,
+} from "./maintenance.ts";
 import { listVaults, loadVaultConfig } from "./config.ts";
 import { getEntityGraphNeighbors, searchEntities } from "./entity.ts";
 
@@ -2595,8 +2598,37 @@ This is the recommended entry point for ALL memory queries.`,
   await server.connect(transport);
 
   // ---------------------------------------------------------------------------
-  // Consolidation Worker
-  // ---------------------------------------------------------------------------
+  // Shutdown wiring + Workers
+  // ---------------------------------------------------------------------------
+
+  // v0.8.2 Codex Turn 2 fix: register signal handlers BEFORE any worker
+  // startup, mirroring the same null-handle capture pattern that cmdWatch
+  // uses. The handler is the only thing that suppresses Node's default
+  // signal action (terminate), so a SIGTERM arriving in the brief window
+  // between worker startup and `process.on(...)` registration would
+  // exit-143 the process and skip the async drain entirely, leaking any
+  // lease the worker had just acquired. Capturing `stopHeavyLane` as a
+  // mutable closure variable lets the registration happen before the
+  // worker is actually created — the handler reads whatever value is
+  // bound at the moment a signal arrives.
+  let stopHeavyLane: (() => Promise<void>) | null = null;
+
+  // Signal handlers for graceful shutdown. async stop sequence: both
+  // worker stops await any in-flight tick before resolving so the store
+  // is not closed underneath a mid-tick worker. Bounded waits inside the
+  // stop functions guarantee the handler cannot wedge indefinitely.
+  const shutdownMcp = async (signal: string) => {
+    console.error(`\n[mcp] Received ${signal}, shutting down...`);
+    if (stopHeavyLane) {
+      await stopHeavyLane();
+      stopHeavyLane = null;
+    }
+    await stopConsolidationWorker();
+    closeAllStores();
+    process.exit(0);
+  };
+  process.on("SIGINT", () => { void shutdownMcp("SIGINT"); });
+  process.on("SIGTERM", () => { void shutdownMcp("SIGTERM"); });
 
   // Start consolidation worker if enabled
   if (Bun.env.CLAWMEM_ENABLE_CONSOLIDATION === "true") {
@@ -2609,49 +2641,25 @@ This is the recommended entry point for ALL memory queries.`,
   // 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;
+  //
+  // v0.8.2: warn when this lane is enabled on a stdio MCP host. Per-session
+  // MCPs spawned by Claude Code die with the session, which means the
+  // configured quiet window may never see a live worker if no Claude Code
+  // session is open at that time. The watcher service (`clawmem watch`) is
+  // the canonical long-lived host for the heavy lane as of v0.8.2 — see
+  // docs/concepts/architecture.md and docs/guides/upgrading.md for the
+  // dual-host rationale.
   if (Bun.env.CLAWMEM_HEAVY_LANE === "true") {
+    console.error(
+      "[mcp] WARNING: CLAWMEM_HEAVY_LANE=true on a stdio MCP host. " +
+        "Per-session MCPs are short-lived; the configured quiet window may " +
+        "never see a live worker. As of v0.8.2 the canonical heavy-lane host " +
+        "is `clawmem watch` (e.g. systemd user unit clawmem-watcher.service). " +
+        "Set the same env var on the watcher service for reliable operation.",
+    );
     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);
+    stopHeavyLane = startHeavyMaintenanceWorker(store, llm, parseHeavyLaneConfigFromEnv());
   }
-
-  // Signal handlers for graceful shutdown
-  process.on("SIGINT", () => {
-    console.error("\n[mcp] Received SIGINT, shutting down...");
-    stopConsolidationWorker();
-    if (stopHeavyLane) stopHeavyLane();
-    closeAllStores();
-    process.exit(0);
-  });
-
-  process.on("SIGTERM", () => {
-    console.error("\n[mcp] Received SIGTERM, shutting down...");
-    stopConsolidationWorker();
-    if (stopHeavyLane) stopHeavyLane();
-    closeAllStores();
-    process.exit(0);
-  });
 }
 
 if (import.meta.main) {