@karmaniverous/jeeves-meta 0.4.1 → 0.5.0

package/dist/cli/jeeves-meta/index.js

@@ -1,9 +1,13 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-import { readFileSync, readdirSync, unlinkSync, mkdirSync, writeFileSync, existsSync, statSync, copyFileSync, watchFile } from 'node:fs';
-import { dirname, join, relative } from 'node:path';
+import fs, { readFileSync, readdirSync, unlinkSync, mkdirSync, writeFileSync, existsSync, statSync, copyFileSync, watchFile } from 'node:fs';
+import path, { dirname, join, resolve, relative } from 'node:path';
 import { z } from 'zod';
+import { fileURLToPath } from 'node:url';
+import 'node:fs/promises';
+import process$1 from 'node:process';
 import { createHash, randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
 import pino from 'pino';
 import { Cron } from 'croner';
 import Fastify from 'fastify';
@@ -67,6 +71,8 @@ const serviceConfigSchema = metaConfigSchema.extend({
     schedule: z.string().default('*/30 * * * *'),
     /** Optional channel identifier for reporting. */
     reportChannel: z.string().optional(),
+    /** Interval in ms for periodic watcher health check. 0 = disabled. Default: 60000. */
+    watcherHealthIntervalMs: z.number().int().min(0).default(60_000),
     /** Logging configuration. */
     logging: loggingSchema.default(() => loggingSchema.parse({})),
 });
@@ -166,6 +172,122 @@ var configLoader = /*#__PURE__*/Object.freeze({
     resolveConfigPath: resolveConfigPath
 });
 
+const toPath = urlOrPath => urlOrPath instanceof URL ? fileURLToPath(urlOrPath) : urlOrPath;
+
+function findUpSync(name, {
+	cwd = process$1.cwd(),
+	type = 'file',
+	stopAt,
+} = {}) {
+	let directory = path.resolve(toPath(cwd) ?? '');
+	const {root} = path.parse(directory);
+	stopAt = path.resolve(directory, toPath(stopAt) ?? root);
+	const isAbsoluteName = path.isAbsolute(name);
+
+	while (directory) {
+		const filePath = isAbsoluteName ? name : path.join(directory, name);
+
+		try {
+			const stats = fs.statSync(filePath, {throwIfNoEntry: false});
+			if ((type === 'file' && stats?.isFile()) || (type === 'directory' && stats?.isDirectory())) {
+				return filePath;
+			}
+		} catch {}
+
+		if (directory === stopAt || directory === root) {
+			break;
+		}
+
+		directory = path.dirname(directory);
+	}
+}
+
+const isTypeOnlyPackageJsonData = packageData => {
+	if (!packageData || typeof packageData !== 'object' || Array.isArray(packageData)) {
+		return false;
+	}
+
+	const keys = Object.keys(packageData);
+	return keys.length === 1 && keys[0] === 'type' && typeof packageData.type === 'string';
+};
+
+const isTypeOnlyPackageJsonSync = filePath => {
+	let fileContents;
+
+	try {
+		fileContents = fs.readFileSync(filePath, 'utf8');
+	} catch {
+		return false;
+	}
+
+	try {
+		return isTypeOnlyPackageJsonData(JSON.parse(fileContents));
+	} catch {
+		return false;
+	}
+};
+
+const getNextSearchDirectory = filePath => {
+	const packageDirectoryPath = path.dirname(filePath);
+	const parentDirectoryPath = path.dirname(packageDirectoryPath);
+	return parentDirectoryPath === packageDirectoryPath ? undefined : parentDirectoryPath;
+};
+
+const findPackageDirectorySync = (directory, ignoreTypeOnlyPackageJson) => {
+	const filePath = findUpSync('package.json', {cwd: directory});
+	if (!filePath) {
+		return undefined;
+	}
+
+	const packageDirectoryPath = path.dirname(filePath);
+	if (!ignoreTypeOnlyPackageJson) {
+		return packageDirectoryPath;
+	}
+
+	if (!isTypeOnlyPackageJsonSync(filePath)) {
+		return packageDirectoryPath;
+	}
+
+	const nextDirectory = getNextSearchDirectory(filePath);
+	if (!nextDirectory) {
+		return undefined;
+	}
+
+	return findPackageDirectorySync(nextDirectory, ignoreTypeOnlyPackageJson);
+};
+
+function packageDirectorySync({cwd, ignoreTypeOnlyPackageJson} = {}) {
+	return findPackageDirectorySync(cwd ?? process$1.cwd(), ignoreTypeOnlyPackageJson);
+}
+
+/**
+ * Shared constants for the jeeves-meta service package.
+ *
+ * @module constants
+ */
+/** Default HTTP port for the jeeves-meta service. */
+const DEFAULT_PORT = 1938;
+/** Default port as a string (for Commander CLI defaults). */
+const DEFAULT_PORT_STR = String(DEFAULT_PORT);
+/** Service name identifier. */
+const SERVICE_NAME = 'jeeves-meta';
+/** Service version, read from package.json at startup. */
+const SERVICE_VERSION = (() => {
+    try {
+        const dir = dirname(fileURLToPath(import.meta.url));
+        const root = packageDirectorySync({ cwd: dir });
+        if (root) {
+            const pkg = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8'));
+            if (pkg.version)
+                return pkg.version;
+        }
+        return 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+})();
+
 /**
  * List archive snapshot files in chronological order.
  *
@@ -282,114 +404,29 @@ function normalizePath(p) {
 }
 
 /**
- * Paginated scan helper for exhaustive scope enumeration.
+ * Discover .meta/ directories via watcher `/walk` endpoint.
  *
- * @module paginatedScan
- */
-/**
- * Perform a paginated scan that follows cursor tokens until exhausted.
- *
- * @param watcher - WatcherClient instance.
- * @param params - Base scan parameters (cursor is managed internally).
- * @returns All matching files across all pages.
- */
-async function paginatedScan(watcher, params, logger) {
-    const allFiles = [];
-    let cursor;
-    let pageCount = 0;
-    const start = Date.now();
-    do {
-        const pageStart = Date.now();
-        const result = await watcher.scan({ ...params, cursor });
-        allFiles.push(...result.files);
-        pageCount++;
-        logger?.debug({
-            page: pageCount,
-            files: result.files.length,
-            pageMs: Date.now() - pageStart,
-            hasNext: Boolean(result.next),
-        }, 'paginatedScan page');
-        cursor = result.next;
-    } while (cursor);
-    logger?.debug({
-        pages: pageCount,
-        totalFiles: allFiles.length,
-        totalMs: Date.now() - start,
-    }, 'paginatedScan complete');
-    return allFiles;
-}
-
-/**
- * Discover .meta/ directories via watcher scan.
- *
- * Replaces filesystem-based globMetas() with a watcher query
- * that returns indexed .meta/meta.json points, filtered by domain.
+ * Uses filesystem enumeration through the watcher (not Qdrant) to find
+ * all `.meta/meta.json` files and returns deduplicated meta directory paths.
  *
  * @module discovery/discoverMetas
  */
 /**
- * Build a single Qdrant filter clause from a key-value pair.
+ * Discover all .meta/ directories via watcher walk.
  *
- * Arrays use `match.value` on the first element (Qdrant array membership).
- * Scalars (string, number, boolean) use `match.value` directly.
- * Objects and other non-filterable types are skipped with a warning.
- */
-function buildMatchClause(key, value) {
-    if (Array.isArray(value)) {
-        if (value.length === 0)
-            return null;
-        return { key, match: { value: value[0] } };
-    }
-    if (typeof value === 'string' ||
-        typeof value === 'number' ||
-        typeof value === 'boolean') {
-        return { key, match: { value } };
-    }
-    // Non-filterable value (object, null, etc.) — valid for tagging but
-    // cannot be expressed as a Qdrant match clause.
-    return null;
-}
-/**
- * Build a Qdrant filter from config metaProperty.
- *
- * Iterates all key-value pairs in `metaProperty` (a generic record)
- * to construct `must` clauses. Always appends `file_path: meta.json`
- * for deduplication.
+ * Uses the watcher's `/walk` endpoint to find all `.meta/meta.json` files
+ * and returns deduplicated meta directory paths.
  *
- * @param config - Meta config with metaProperty.
- * @returns Qdrant filter object for scanning live metas.
- */
-function buildMetaFilter(config) {
-    const must = [];
-    for (const [key, value] of Object.entries(config.metaProperty)) {
-        const clause = buildMatchClause(key, value);
-        if (clause)
-            must.push(clause);
-    }
-    must.push({
-        key: 'file_path',
-        match: { text: '.meta/meta.json' },
-    });
-    return { must };
-}
-/**
- * Discover all .meta/ directories via watcher scan.
- *
- * Queries the watcher for indexed .meta/meta.json points using the
- * configured domain filter. Returns deduplicated meta directory paths.
- *
- * @param config - Meta config (for domain filter).
- * @param watcher - WatcherClient for scan queries.
+ * @param watcher - WatcherClient for walk queries.
  * @returns Array of normalized .meta/ directory paths.
  */
-async function discoverMetas(config, watcher, logger) {
-    const filter = buildMetaFilter(config);
-    const scanFiles = await paginatedScan(watcher, { filter, fields: ['file_path'] }, logger);
+async function discoverMetas(watcher) {
+    const allPaths = await watcher.walk(['**/.meta/meta.json']);
     // Deduplicate by .meta/ directory path (handles multi-chunk files)
     const seen = new Set();
     const metaPaths = [];
-    for (const sf of scanFiles) {
-        const fp = normalizePath(sf.file_path);
+    for (const filePath of allPaths) {
+        const fp = normalizePath(filePath);
         // Derive .meta/ directory from file_path (strip /meta.json)
         const metaPath = fp.replace(/\/meta\.json$/, '');
         if (seen.has(metaPath))
@@ -530,6 +567,25 @@ function cleanupStaleLocks(metaPaths, logger) {
     }
 }
 
+/**
+ * Read and parse a meta.json file from a `.meta/` directory.
+ *
+ * Shared utility to eliminate repeated `JSON.parse(readFileSync(...))` across
+ * discovery, orchestration, and route handlers.
+ *
+ * @module readMetaJson
+ */
+/**
+ * Read and parse a meta.json file from a `.meta/` directory path.
+ *
+ * @param metaPath - Path to the `.meta/` directory.
+ * @returns Parsed meta.json content.
+ * @throws If the file doesn't exist or contains invalid JSON.
+ */
+function readMetaJson(metaPath) {
+    return JSON.parse(readFileSync(join(metaPath, 'meta.json'), 'utf8'));
+}
+
 /**
  * Build the ownership tree from discovered .meta/ paths.
  *
@@ -625,9 +681,9 @@ const MAX_STALENESS_SECONDS$1 = 365 * 86_400;
  * @param watcher - Watcher HTTP client for discovery.
  * @returns Enriched meta list with summary statistics and ownership tree.
  */
-async function listMetas(config, watcher, logger) {
-    // Step 1: Discover deduplicated meta paths via watcher scan
-    const metaPaths = await discoverMetas(config, watcher, logger);
+async function listMetas(config, watcher) {
+    // Step 1: Discover deduplicated meta paths via watcher walk
+    const metaPaths = await discoverMetas(watcher);
     // Step 2: Build ownership tree
     const tree = buildOwnershipTree(metaPaths);
     // Step 3: Read and enrich each meta from disk
@@ -646,7 +702,7 @@ async function listMetas(config, watcher, logger) {
     for (const node of tree.nodes.values()) {
         let meta;
         try {
-            meta = JSON.parse(readFileSync(join(node.metaPath, 'meta.json'), 'utf8'));
+            meta = readMetaJson(node.metaPath);
         }
         catch {
             // Skip unreadable metas
@@ -734,67 +790,50 @@ async function listMetas(config, watcher, logger) {
 }
 
 /**
- * Recursive filesystem walker for file enumeration.
+ * Filter file paths by modification time.
  *
- * Replaces paginated watcher scans for scope/delta/staleness checks.
- * Returns normalized forward-slash paths.
+ * Shared utility for staleness detection and delta file enumeration.
+ * Uses `fs.statSync` for fast local mtime checks on known paths.
  *
- * @module walkFiles
+ * @module mtimeFilter
  */
-/** Default directory names to always skip. */
-const DEFAULT_SKIP = new Set([
-    'node_modules',
-    '.git',
-    '.rollup.cache',
-    'dist',
-    'Thumbs.db',
-]);
 /**
- * Recursively walk a directory and return all file paths.
+ * Check if any file in the list was modified after the given timestamp.
  *
- * @param root - Root directory to walk.
- * @param options - Walk options.
- * @returns Array of normalized file paths.
+ * Short-circuits on first match for efficiency (staleness checks).
+ *
+ * @param files - Array of file paths to check.
+ * @param afterMs - Timestamp in milliseconds. Files with `mtimeMs > afterMs` match.
+ * @returns True if any file was modified after the timestamp.
  */
-function walkFiles(root, options) {
-    const exclude = new Set([...DEFAULT_SKIP, ...(options?.exclude ?? [])]);
-    const modifiedAfter = options?.modifiedAfter;
-    const maxDepth = options?.maxDepth ?? 50;
-    const results = [];
-    function walk(dir, depth) {
-        if (depth > maxDepth)
-            return;
-        let entries;
+function hasModifiedAfter(files, afterMs) {
+    for (const filePath of files) {
         try {
-            entries = readdirSync(dir, { withFileTypes: true });
+            if (statSync(filePath).mtimeMs > afterMs)
+                return true;
         }
         catch {
-            return; // Permission errors, missing dirs — skip
-        }
-        for (const entry of entries) {
-            if (exclude.has(entry.name))
-                continue;
-            const fullPath = join(dir, entry.name);
-            if (entry.isDirectory()) {
-                walk(fullPath, depth + 1);
-            }
-            else if (entry.isFile()) {
-                if (modifiedAfter !== undefined) {
-                    try {
-                        const stat = statSync(fullPath);
-                        if (Math.floor(stat.mtimeMs / 1000) <= modifiedAfter)
-                            continue;
-                    }
-                    catch {
-                        continue;
-                    }
-                }
-                results.push(normalizePath(fullPath));
-            }
+            // Unreadable file — skip
         }
     }
-    walk(root, 0);
-    return results;
+    return false;
+}
+/**
+ * Filter files to only those modified after the given timestamp.
+ *
+ * @param files - Array of file paths to filter.
+ * @param afterMs - Timestamp in milliseconds. Files with `mtimeMs > afterMs` are included.
+ * @returns Filtered array of file paths.
+ */
+function filterModifiedAfter(files, afterMs) {
+    return files.filter((filePath) => {
+        try {
+            return statSync(filePath).mtimeMs > afterMs;
+        }
+        catch {
+            return false;
+        }
+    });
 }
 
 /**
@@ -804,7 +843,7 @@ function walkFiles(root, options) {
  * - Its own .meta/ subtree (outputs, not inputs)
  * - Child meta ownerPath subtrees (except their .meta/meta.json for rollups)
  *
- * Uses filesystem walks instead of watcher scans for performance.
+ * All filesystem enumeration delegated to the watcher's `/walk` endpoint.
  *
  * @module discovery/scope
  */
@@ -821,7 +860,7 @@ function getScopePrefix(node) {
  * - The node's own .meta/ subtree (synthesis outputs are not scope inputs)
  * - Child meta ownerPath subtrees (except child .meta/meta.json for rollups)
  *
- * walkFiles already returns normalized forward-slash paths.
+ * Watcher walk returns normalized forward-slash paths.
  */
 function filterInScope(node, files) {
     const prefix = node.ownerPath + '/';
@@ -846,10 +885,10 @@ function filterInScope(node, files) {
     });
 }
 /**
- * Get all files in scope for a meta node via filesystem walk.
+ * Get all files in scope for a meta node via watcher walk.
  */
-function getScopeFiles(node) {
-    const allFiles = walkFiles(node.ownerPath);
+async function getScopeFiles(node, watcher) {
+    const allFiles = await watcher.walk([`${node.ownerPath}/**`]);
     return {
         scopeFiles: filterInScope(node, allFiles),
         allFiles,
@@ -859,13 +898,12 @@ function getScopeFiles(node) {
  * Get files modified since a given timestamp within a meta node's scope.
  *
  * If no generatedAt is provided (first run), returns all scope files.
+ * Reuses scope files from getScopeFiles() and filters locally by mtime.
  */
-function getDeltaFiles(node, generatedAt, scopeFiles) {
+function getDeltaFiles(generatedAt, scopeFiles) {
     if (!generatedAt)
         return scopeFiles;
-    const modifiedAfter = Math.floor(new Date(generatedAt).getTime() / 1000);
-    const deltaFiles = walkFiles(node.ownerPath, { modifiedAfter });
-    return filterInScope(node, deltaFiles);
+    return filterModifiedAfter(scopeFiles, new Date(generatedAt).getTime());
 }
 
 /**
@@ -962,7 +1000,7 @@ class GatewayExecutor {
         this.gatewayUrl = (options.gatewayUrl ?? 'http://127.0.0.1:18789').replace(/\/+$/, '');
         this.apiKey = options.apiKey;
         this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-        this.workspaceDir = options.workspaceDir ?? 'J:\\jeeves\\jeeves-meta';
+        this.workspaceDir = options.workspaceDir ?? join(tmpdir(), 'jeeves-meta');
     }
     /** Invoke a gateway tool via the /tools/invoke HTTP endpoint. */
     async invoke(tool, args) {
@@ -1166,10 +1204,10 @@ function condenseScopeFiles(files, maxIndividual = 30) {
  * @param watcher - WatcherClient for scope enumeration.
  * @returns The computed context package.
  */
-function buildContextPackage(node, meta) {
-    // Scope and delta files via watcher scan
-    const { scopeFiles } = getScopeFiles(node);
-    const deltaFiles = getDeltaFiles(node, meta._generatedAt, scopeFiles);
+async function buildContextPackage(node, meta, watcher) {
+    // Scope and delta files via watcher walk
+    const { scopeFiles } = await getScopeFiles(node, watcher);
+    const deltaFiles = getDeltaFiles(meta._generatedAt, scopeFiles);
     // Child meta outputs
     const childMetas = {};
     for (const child of node.children) {
@@ -1493,6 +1531,67 @@ function mergeAndWrite(options) {
     return result.data;
 }
 
+/**
+ * Build a minimal MetaNode from a known meta path using watcher walk.
+ *
+ * Used for targeted synthesis (when a specific path is requested) to avoid
+ * the full discovery + ownership tree build. Discovers only immediate child
+ * `.meta/` directories.
+ *
+ * @module discovery/buildMinimalNode
+ */
+/**
+ * Build a minimal MetaNode for a known meta path.
+ *
+ * Walks the owner directory for child `.meta/meta.json` files and constructs
+ * a shallow ownership tree (self + direct children only).
+ *
+ * @param metaPath - Absolute path to the `.meta/` directory.
+ * @param watcher - WatcherClient for filesystem enumeration.
+ * @returns MetaNode with direct children wired.
+ */
+async function buildMinimalNode(metaPath, watcher) {
+    const normalized = normalizePath(metaPath);
+    const ownerPath = normalizePath(dirname(metaPath));
+    // Find child metas using watcher walk.
+    // We include only *direct* children (nearest descendants in the ownership tree)
+    // to match the ownership semantics used elsewhere.
+    const rawMetaJsonPaths = await watcher.walk([
+        `${ownerPath}/**/.meta/meta.json`,
+    ]);
+    const candidateMetaPaths = [
+        ...new Set(rawMetaJsonPaths.map((p) => normalizePath(dirname(p)))),
+    ].filter((p) => p !== normalized);
+    const candidates = candidateMetaPaths
+        .map((mp) => ({ metaPath: mp, ownerPath: normalizePath(dirname(mp)) }))
+        .sort((a, b) => a.ownerPath.length - b.ownerPath.length);
+    const directChildren = [];
+    for (const c of candidates) {
+        const nestedUnderExisting = directChildren.some((d) => c.ownerPath === d.ownerPath ||
+            c.ownerPath.startsWith(d.ownerPath + '/'));
+        if (!nestedUnderExisting)
+            directChildren.push(c);
+    }
+    const children = directChildren.map((c) => ({
+        metaPath: c.metaPath,
+        ownerPath: c.ownerPath,
+        treeDepth: 1,
+        children: [],
+        parent: null,
+    }));
+    const node = {
+        metaPath: normalized,
+        ownerPath,
+        treeDepth: 0,
+        children,
+        parent: null,
+    };
+    for (const child of children) {
+        child.parent = node;
+    }
+    return node;
+}
+
 /**
  * Weighted staleness formula for candidate selection.
  *
@@ -1572,29 +1671,30 @@ function discoverStalestPath(candidates, depthWeight) {
 }
 
 /**
- * Staleness detection via watcher scan.
+ * Staleness detection via watcher walk.
  *
- * A meta is stale when any file in its scope was modified after _generatedAt.
+ * A meta is stale when any watched file in its scope was modified after
+ * `_generatedAt`.
  *
  * @module scheduling/staleness
  */
 /**
- * Check if a meta is stale by querying the watcher for modified files.
+ * Check if a meta is stale.
+ *
+ * Uses watcher `/walk` to enumerate watched files under the scope prefix,
+ * then applies a local mtime check (fast) to detect any modifications since
+ * `_generatedAt`. Short-circuits on first match.
  *
  * @param scopePrefix - Path prefix for this meta's scope.
  * @param meta - Current meta.json content.
  * @param watcher - WatcherClient instance.
- * @returns True if any file in scope was modified after _generatedAt.
+ * @returns True if any file in scope was modified after `_generatedAt`.
  */
-function isStale(scopePrefix, meta) {
+async function isStale(scopePrefix, meta, watcher) {
     if (!meta._generatedAt)
         return true; // Never synthesized = stale
-    const generatedAtUnix = Math.floor(new Date(meta._generatedAt).getTime() / 1000);
-    const modified = walkFiles(scopePrefix, {
-        modifiedAfter: generatedAtUnix,
-        maxDepth: 1,
-    });
-    return modified.length > 0;
+    const files = await watcher.walk([`${scopePrefix}/**`]);
+    return hasModifiedAfter(files, new Date(meta._generatedAt).getTime());
 }
 /** Maximum staleness for never-synthesized metas (1 year in seconds). */
 const MAX_STALENESS_SECONDS = 365 * 86_400;
@@ -1804,72 +1904,13 @@ function finalizeCycle(opts) {
  * @param watcher - Watcher HTTP client.
  * @returns Result indicating whether synthesis occurred.
  */
-/**
- * Build a minimal MetaNode from the filesystem for a known meta path.
- * Discovers immediate child .meta/ dirs without a full watcher scan.
- */
-function buildMinimalNode(metaPath) {
-    const normalized = normalizePath(metaPath);
-    const ownerPath = normalizePath(dirname(metaPath));
-    // Find child .meta/ directories by scanning the owner directory
-    const children = [];
-    function findChildMetas(dir, depth) {
-        if (depth > 10)
-            return; // Safety limit
-        try {
-            const entries = readdirSync(dir, { withFileTypes: true });
-            for (const entry of entries) {
-                if (!entry.isDirectory())
-                    continue;
-                const fullPath = normalizePath(join(dir, entry.name));
-                if (entry.name === '.meta' && fullPath !== normalized) {
-                    // Found a child .meta — check it has meta.json
-                    if (existsSync(join(fullPath, 'meta.json'))) {
-                        children.push({
-                            metaPath: fullPath,
-                            ownerPath: normalizePath(dirname(fullPath)),
-                            treeDepth: 1, // Relative to target
-                            children: [],
-                            parent: null, // Set below
-                        });
-                    }
-                    // Don't recurse into .meta dirs
-                    return;
-                }
-                if (entry.name === 'node_modules' ||
-                    entry.name === '.git' ||
-                    entry.name === 'archive')
-                    continue;
-                findChildMetas(fullPath, depth + 1);
-            }
-        }
-        catch {
-            // Permission errors, etc — skip
-        }
-    }
-    findChildMetas(ownerPath, 0);
-    const node = {
-        metaPath: normalized,
-        ownerPath,
-        treeDepth: 0,
-        children,
-        parent: null,
-    };
-    // Wire parent references
-    for (const child of children) {
-        child.parent = node;
-    }
-    return node;
-}
 /** Run the architect/builder/critic pipeline on a single node. */
 async function synthesizeNode(node, currentMeta, config, executor, watcher, onProgress) {
-    const architectPrompt = currentMeta._architect ?? config.defaultArchitect;
-    const criticPrompt = currentMeta._critic ?? config.defaultCritic;
     // Step 5-6: Steer change detection
     const latestArchive = readLatestArchive(node.metaPath);
     const steerChanged = hasSteerChanged(currentMeta._steer, latestArchive?._steer, Boolean(latestArchive));
     // Step 7: Compute context (includes scope files and delta files)
-    const ctx = buildContextPackage(node, currentMeta);
+    const ctx = await buildContextPackage(node, currentMeta, watcher);
     // Step 5 (deferred): Structure hash from context scope files
     const newStructureHash = computeStructureHash(ctx.scopeFiles);
     const structureChanged = newStructureHash !== currentMeta._structureHash;
@@ -1913,9 +1954,9 @@ async function synthesizeNode(node, currentMeta, config, executor, watcher, onPr
                     metaPath: node.metaPath,
                     current: currentMeta,
                     config,
-                    architect: architectPrompt,
+                    architect: currentMeta._architect ?? '',
                     builder: '',
-                    critic: criticPrompt,
+                    critic: currentMeta._critic ?? '',
                     builderOutput: null,
                     feedback: null,
                     structureHash: newStructureHash,
@@ -1999,9 +2040,9 @@ async function synthesizeNode(node, currentMeta, config, executor, watcher, onPr
         metaPath: node.metaPath,
         current: currentMeta,
         config,
-        architect: architectPrompt,
+        architect: currentMeta._architect ?? '',
         builder: builderBrief,
-        critic: criticPrompt,
+        critic: currentMeta._critic ?? '',
         builderOutput,
         feedback,
         structureHash: newStructureHash,
@@ -2025,26 +2066,25 @@ async function orchestrateOnce(config, executor, watcher, targetPath, onProgress
         const targetMetaJson = join(normalizedTarget, 'meta.json');
         if (!existsSync(targetMetaJson))
             return { synthesized: false };
-        const node = buildMinimalNode(normalizedTarget);
+        const node = await buildMinimalNode(normalizedTarget, watcher);
         if (!acquireLock(node.metaPath))
             return { synthesized: false };
         try {
-            const currentMeta = JSON.parse(readFileSync(targetMetaJson, 'utf8'));
+            const currentMeta = readMetaJson(normalizedTarget);
             return await synthesizeNode(node, currentMeta, config, executor, watcher, onProgress);
         }
         finally {
             releaseLock(node.metaPath);
         }
     }
-    const metaPaths = await discoverMetas(config, watcher, logger);
+    const metaPaths = await discoverMetas(watcher);
     if (metaPaths.length === 0)
         return { synthesized: false };
     // Read meta.json for each discovered meta
     const metas = new Map();
     for (const mp of metaPaths) {
-        const metaFilePath = join(mp, 'meta.json');
         try {
-            metas.set(normalizePath(mp), JSON.parse(readFileSync(metaFilePath, 'utf8')));
+            metas.set(normalizePath(mp), readMetaJson(mp));
         }
         catch {
             // Skip metas with unreadable meta.json
@@ -2077,13 +2117,12 @@ async function orchestrateOnce(config, executor, watcher, targetPath, onProgress
     for (const candidate of ranked) {
         if (!acquireLock(candidate.node.metaPath))
             continue;
-        const verifiedStale = isStale(getScopePrefix(candidate.node), candidate.meta);
+        const verifiedStale = await isStale(getScopePrefix(candidate.node), candidate.meta, watcher);
         if (!verifiedStale && candidate.meta._generatedAt) {
             // Bump _generatedAt so it doesn't win next cycle
-            const metaFilePath = join(candidate.node.metaPath, 'meta.json');
-            const freshMeta = JSON.parse(readFileSync(metaFilePath, 'utf8'));
+            const freshMeta = readMetaJson(candidate.node.metaPath);
             freshMeta._generatedAt = new Date().toISOString();
-            writeFileSync(metaFilePath, JSON.stringify(freshMeta, null, 2));
+            writeFileSync(join(candidate.node.metaPath, 'meta.json'), JSON.stringify(freshMeta, null, 2));
             releaseLock(candidate.node.metaPath);
             if (config.skipUnchanged)
                 continue;
@@ -2096,7 +2135,7 @@ async function orchestrateOnce(config, executor, watcher, targetPath, onProgress
         return { synthesized: false };
     const node = winner.node;
     try {
-        const currentMeta = JSON.parse(readFileSync(join(node.metaPath, 'meta.json'), 'utf8'));
+        const currentMeta = readMetaJson(node.metaPath);
         return await synthesizeNode(node, currentMeta, config, executor, watcher, onProgress);
     }
     finally {
@@ -2117,7 +2156,7 @@ async function orchestrateOnce(config, executor, watcher, targetPath, onProgress
  * @returns Array with a single result.
  */
 async function orchestrate(config, executor, watcher, targetPath, onProgress, logger) {
-    const result = await orchestrateOnce(config, executor, watcher, targetPath, onProgress, logger);
+    const result = await orchestrateOnce(config, executor, watcher, targetPath, onProgress);
     return [result];
 }
 
@@ -2340,7 +2379,7 @@ class Scheduler {
      */
     async discoverStalest() {
         try {
-            const result = await listMetas(this.config, this.watcher, this.logger);
+            const result = await listMetas(this.config, this.watcher);
             const stale = result.entries
                 .filter((e) => e.stalenessSeconds > 0)
                 .map((e) => ({
@@ -2626,7 +2665,7 @@ function registerMetasRoutes(app, deps) {
     app.get('/metas', async (request) => {
         const query = metasQuerySchema.parse(request.query);
         const { config, watcher } = deps;
-        const result = await listMetas(config, watcher, request.log);
+        const result = await listMetas(config, watcher);
         let entries = result.entries;
         // Apply filters
         if (query.pathPrefix) {
@@ -2689,7 +2728,7 @@ function registerMetasRoutes(app, deps) {
         const query = metaDetailQuerySchema.parse(request.query);
         const { config, watcher } = deps;
         const targetPath = normalizePath(decodeURIComponent(request.params.path));
-        const result = await listMetas(config, watcher, request.log);
+        const result = await listMetas(config, watcher);
         const targetNode = findNode(result.tree, targetPath);
         if (!targetNode) {
             return reply.status(404).send({
@@ -2722,7 +2761,7 @@ function registerMetasRoutes(app, deps) {
             return r;
         };
         // Compute scope
-        const { scopeFiles, allFiles } = getScopeFiles(targetNode);
+        const { scopeFiles, allFiles } = await getScopeFiles(targetNode, watcher);
         // Compute staleness
         const metaTyped = meta;
         const staleSeconds = metaTyped._generatedAt
@@ -2769,7 +2808,7 @@ function registerPreviewRoute(app, deps) {
         const query = request.query;
         let result;
         try {
-            result = await listMetas(config, watcher, request.log);
+            result = await listMetas(config, watcher);
         }
         catch {
             return reply.status(503).send({
@@ -2803,16 +2842,16 @@ function registerPreviewRoute(app, deps) {
             }
             targetNode = findNode(result.tree, stalestPath);
         }
-        const meta = JSON.parse(readFileSync(join(targetNode.metaPath, 'meta.json'), 'utf8'));
+        const meta = readMetaJson(targetNode.metaPath);
         // Scope files
-        const { scopeFiles } = getScopeFiles(targetNode);
+        const { scopeFiles } = await getScopeFiles(targetNode, watcher);
         const structureHash = computeStructureHash(scopeFiles);
         const structureChanged = structureHash !== meta._structureHash;
         const latestArchive = readLatestArchive(targetNode.metaPath);
         const steerChanged = hasSteerChanged(meta._steer, latestArchive?._steer, Boolean(latestArchive));
         const architectTriggered = isArchitectTriggered(meta, structureChanged, steerChanged, config.architectEvery);
         // Delta files
-        const deltaFiles = getDeltaFiles(targetNode, meta._generatedAt, scopeFiles);
+        const deltaFiles = getDeltaFiles(meta._generatedAt, scopeFiles);
         // EMA token estimates
         const estimatedTokens = {
             architect: meta._architectTokensAvg ?? meta._architectTokens ?? 0,
@@ -2927,11 +2966,11 @@ function registerStatusRoute(app, deps) {
         else {
             status = 'idle';
         }
-        // Metas summary is expensive (paginated watcher scan + disk reads).
+        // Metas summary is expensive (watcher walk + disk reads).
         // Use GET /metas for full inventory; status is a lightweight health check.
         return {
-            service: 'jeeves-meta',
-            version: '0.4.0',
+            service: SERVICE_NAME,
+            version: SERVICE_VERSION,
             uptime: process.uptime(),
             status,
             currentTarget: queue.current?.path ?? null,
@@ -2948,7 +2987,10 @@ function registerStatusRoute(app, deps) {
                 nextAt: scheduler?.nextRunAt?.toISOString() ?? null,
             },
             dependencies: {
-                watcher: watcherHealth,
+                watcher: {
+                    ...watcherHealth,
+                    rulesRegistered: deps.registrar?.isRegistered ?? false,
+                },
                 gateway: gatewayHealth,
             },
         };
@@ -2976,7 +3018,7 @@ function registerSynthesizeRoute(app, deps) {
             // Discover stalest candidate
             let result;
             try {
-                result = await listMetas(config, watcher, request.log);
+                result = await listMetas(config, watcher);
             }
             catch {
                 return reply.status(503).send({
@@ -3153,7 +3195,15 @@ function buildMetaRules(config) {
                 },
             ],
             render: {
-                frontmatter: ['meta_id', 'generated_at', '*', '!has_error'],
+                frontmatter: [
+                    'meta_id',
+                    'generated_at',
+                    '*',
+                    '!_*',
+                    '!json',
+                    '!file',
+                    '!has_error',
+                ],
                 body: [{ path: 'json._content', heading: 1, label: 'Synthesis' }],
             },
             renderAs: 'md',
@@ -3345,6 +3395,8 @@ function registerShutdownHandlers(deps) {
         if (deps.routeDeps) {
             deps.routeDeps.shuttingDown = true;
         }
+        // 0. Run optional cleanup
+        deps.onShutdown?.();
         // 1. Stop scheduler
         if (deps.scheduler) {
             deps.scheduler.stop();
@@ -3378,7 +3430,7 @@ function registerShutdownHandlers(deps) {
 /**
  * HTTP implementation of the WatcherClient interface.
  *
- * Talks to jeeves-watcher's POST /scan and POST /rules endpoints
+ * Talks to jeeves-watcher's POST /walk and POST /rules/register endpoints
  * with retry and exponential backoff.
  *
  * @module watcher-client/HttpWatcherClient
@@ -3432,61 +3484,80 @@ class HttpWatcherClient {
         // Unreachable, but TypeScript needs it
         throw new Error('Retry exhausted');
     }
-    async scan(params) {
-        // Build Qdrant filter: merge explicit filter with pathPrefix/modifiedAfter
-        const mustClauses = [];
-        // Carry over any existing 'must' clauses from the provided filter
-        if (params.filter) {
-            const existing = params.filter.must;
-            if (Array.isArray(existing)) {
-                mustClauses.push(...existing);
-            }
-        }
-        // Translate pathPrefix into a Qdrant text match on file_path
-        if (params.pathPrefix !== undefined) {
-            mustClauses.push({
-                key: 'file_path',
-                match: { text: params.pathPrefix },
-            });
+    async registerRules(source, rules) {
+        await this.post('/rules/register', { source, rules });
+    }
+    async walk(globs) {
+        const raw = (await this.post('/walk', { globs }));
+        return (raw.paths ?? []);
+    }
+}
+
+/**
+ * Periodic watcher health check for rule registration resilience.
+ *
+ * Pings watcher `/status` on a configurable interval, detects restarts
+ * (uptime decrease), and re-registers virtual rules automatically.
+ * Independent of the synthesis scheduler.
+ *
+ * @module rules/healthCheck
+ */
+/**
+ * Manages the periodic watcher health check loop.
+ *
+ * Starts a `setInterval` that pings the watcher and delegates
+ * restart detection to `RuleRegistrar.checkAndReregister()`.
+ */
+class WatcherHealthCheck {
+    watcherUrl;
+    intervalMs;
+    registrar;
+    logger;
+    handle = null;
+    constructor(opts) {
+        this.watcherUrl = opts.watcherUrl.replace(/\/+$/, '');
+        this.intervalMs = opts.intervalMs;
+        this.registrar = opts.registrar;
+        this.logger = opts.logger;
+    }
+    /** Start the periodic health check. No-op if intervalMs is 0. */
+    start() {
+        if (this.intervalMs <= 0) {
+            this.logger.info('Watcher health check disabled (interval = 0)');
+            return;
         }
-        // Translate modifiedAfter into a Qdrant range filter on modified_at
-        if (params.modifiedAfter !== undefined) {
-            mustClauses.push({
-                key: 'modified_at',
-                range: { gt: params.modifiedAfter },
-            });
+        this.handle = setInterval(() => {
+            void this.check();
+        }, this.intervalMs);
+        // Don't prevent process exit
+        if (typeof this.handle === 'object' && 'unref' in this.handle) {
+            this.handle.unref();
         }
-        const filter = { must: mustClauses };
-        const body = { filter };
-        if (params.fields !== undefined) {
-            body.fields = params.fields;
+        this.logger.info({ intervalMs: this.intervalMs }, 'Watcher health check started');
+    }
+    /** Stop the periodic health check. */
+    stop() {
+        if (this.handle) {
+            clearInterval(this.handle);
+            this.handle = null;
         }
-        if (params.limit !== undefined) {
-            body.limit = params.limit;
+    }
+    /** Single health check iteration. */
+    async check() {
+        try {
+            const res = await fetch(this.watcherUrl + '/status', {
+                signal: AbortSignal.timeout(5000),
+            });
+            if (!res.ok) {
+                this.logger.warn({ status: res.status }, 'Watcher health check: non-OK response');
+                return;
+            }
+            const data = (await res.json());
+            await this.registrar.checkAndReregister(data.uptime);
         }
-        if (params.cursor !== undefined) {
-            body.cursor = params.cursor;
+        catch (err) {
+            this.logger.debug({ err }, 'Watcher health check: unreachable (expected during startup)');
         }
-        const raw = (await this.post('/scan', body));
-        // jeeves-watcher returns { points, cursor }; map to ScanResponse.
-        const points = (raw.points ?? raw.files ?? []);
-        const next = (raw.cursor ?? raw.next);
-        const files = points.map((p) => {
-            const payload = (p.payload ?? p);
-            return {
-                file_path: (payload.file_path ?? payload.path ?? ''),
-                modified_at: (payload.modified_at ?? payload.mtime ?? 0),
-                content_hash: (payload.content_hash ?? ''),
-                ...payload,
-            };
-        });
-        return { files, next: next ?? undefined };
-    }
-    async registerRules(source, rules) {
-        await this.post('/rules/register', { source, rules });
-    }
-    async unregisterRules(source) {
-        await this.post('/rules/unregister', { source });
     }
 }
 
@@ -3626,7 +3697,16 @@ async function startService(config, configPath) {
     // Rule registration (fire-and-forget with retries)
     const registrar = new RuleRegistrar(config, logger, watcher);
     scheduler.setRegistrar(registrar);
+    routeDeps.registrar = registrar;
     void registrar.register();
+    // Periodic watcher health check (independent of scheduler)
+    const healthCheck = new WatcherHealthCheck({
+        watcherUrl: config.watcherUrl,
+        intervalMs: config.watcherHealthIntervalMs,
+        registrar,
+        logger,
+    });
+    healthCheck.start();
     // Config hot-reload (gap #12)
     if (configPath) {
         watchFile(configPath, { interval: 5000 }, () => {
@@ -3660,6 +3740,9 @@ async function startService(config, configPath) {
         queue,
         logger,
         routeDeps,
+        onShutdown: () => {
+            healthCheck.stop();
+        },
     });
     logger.info('Service fully initialized');
 }
@@ -3670,7 +3753,7 @@ async function startService(config, configPath) {
  * @module cli
  */
 const program = new Command();
-program.name('jeeves-meta').description('Jeeves Meta synthesis service');
+program.name(SERVICE_NAME).description('Jeeves Meta synthesis service');
 // ─── start ──────────────────────────────────────────────────────────
 program
     .command('start')
@@ -3709,7 +3792,7 @@ async function apiPost(port, path, body) {
 program
     .command('status')
     .description('Show service status')
-    .option('-p, --port <port>', 'Service port', '1938')
+    .option('-p, --port <port>', 'Service port', DEFAULT_PORT_STR)
     .action(async (opts) => {
     try {
         const data = await apiGet(parseInt(opts.port, 10), '/status');
@@ -3724,7 +3807,7 @@ program
 program
     .command('list')
     .description('List all discovered meta entities')
-    .option('-p, --port <port>', 'Service port', '1938')
+    .option('-p, --port <port>', 'Service port', DEFAULT_PORT_STR)
     .action(async (opts) => {
     try {
         const data = await apiGet(parseInt(opts.port, 10), '/metas');
@@ -3739,7 +3822,7 @@ program
 program
     .command('detail <path>')
     .description('Show full detail for a single meta entity')
-    .option('-p, --port <port>', 'Service port', '1938')
+    .option('-p, --port <port>', 'Service port', DEFAULT_PORT_STR)
     .action(async (metaPath, opts) => {
     try {
         const encoded = encodeURIComponent(metaPath);
@@ -3755,7 +3838,7 @@ program
 program
     .command('preview')
     .description('Dry-run: preview inputs for next synthesis cycle')
-    .option('-p, --port <port>', 'Service port', '1938')
+    .option('-p, --port <port>', 'Service port', DEFAULT_PORT_STR)
     .option('--path <path>', 'Specific meta path to preview')
     .action(async (opts) => {
     try {
@@ -3772,7 +3855,7 @@ program
 program
     .command('synthesize')
     .description('Trigger synthesis (enqueues work)')
-    .option('-p, --port <port>', 'Service port', '1938')
+    .option('-p, --port <port>', 'Service port', DEFAULT_PORT_STR)
     .option('--path <path>', 'Specific meta path to synthesize')
     .action(async (opts) => {
     try {
@@ -3789,7 +3872,7 @@ program
 program
     .command('seed <path>')
     .description('Create .meta/ directory + meta.json for a path')
-    .option('-p, --port <port>', 'Service port', '1938')
+    .option('-p, --port <port>', 'Service port', DEFAULT_PORT_STR)
     .action(async (metaPath, opts) => {
     try {
         const data = await apiPost(parseInt(opts.port, 10), '/seed', {
@@ -3806,7 +3889,7 @@ program
 program
     .command('unlock <path>')
     .description('Remove .lock file from a meta entity')
-    .option('-p, --port <port>', 'Service port', '1938')
+    .option('-p, --port <port>', 'Service port', DEFAULT_PORT_STR)
     .action(async (metaPath, opts) => {
     try {
         const data = await apiPost(parseInt(opts.port, 10), '/unlock', {
@@ -3823,7 +3906,7 @@ program
 program
     .command('validate')
     .description('Validate current or candidate config')
-    .option('-p, --port <port>', 'Service port', '1938')
+    .option('-p, --port <port>', 'Service port', DEFAULT_PORT_STR)
     .option('-c, --config <path>', 'Validate a candidate config file locally')
     .action(async (opts) => {
     try {
@@ -3856,7 +3939,7 @@ const service = program
 service.addCommand(new Command('install')
     .description('Print install instructions for a system service')
     .option('-c, --config <path>', 'Path to configuration file')
-    .option('-n, --name <name>', 'Service name', 'JeevesMeta')
+    .option('-n, --name <name>', 'Service name', 'jeeves-meta')
     .action((options) => {
     const { name } = options;
     const configFlag = options.config ? ` -c "${options.config}"` : '';
@@ -3921,7 +4004,7 @@ service.addCommand(new Command('install')
 // start command (prints OS-specific start instructions)
 service.addCommand(new Command('start')
     .description('Print start instructions for the installed service')
-    .option('-n, --name <name>', 'Service name', 'JeevesMeta')
+    .option('-n, --name <name>', 'Service name', 'jeeves-meta')
     .action((options) => {
     const { name } = options;
     if (process.platform === 'win32') {
@@ -3940,7 +4023,7 @@ service.addCommand(new Command('start')
 // stop command
 service.addCommand(new Command('stop')
     .description('Stop the running service')
-    .option('-n, --name <name>', 'Service name', 'JeevesMeta')
+    .option('-n, --name <name>', 'Service name', 'jeeves-meta')
     .action((options) => {
     const { name } = options;
     if (process.platform === 'win32') {
@@ -3959,7 +4042,7 @@ service.addCommand(new Command('stop')
 // status command (service subcommand — queries HTTP API)
 service.addCommand(new Command('status')
     .description('Show service status via HTTP API')
-    .option('-p, --port <port>', 'Service port', '1938')
+    .option('-p, --port <port>', 'Service port', DEFAULT_PORT_STR)
     .action(async (opts) => {
     try {
         const data = await apiGet(parseInt(opts.port, 10), '/status');
@@ -3972,7 +4055,7 @@ service.addCommand(new Command('status')
 }));
 service.addCommand(new Command('remove')
     .description('Print remove instructions for a system service')
-    .option('-n, --name <name>', 'Service name', 'JeevesMeta')
+    .option('-n, --name <name>', 'Service name', 'jeeves-meta')
     .action((options) => {
     const { name } = options;
     if (process.platform === 'win32') {