@karmaniverous/jeeves-meta 0.2.2 → 0.3.1

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { readFileSync, readdirSync, unlinkSync, mkdirSync, writeFileSync, existsSync, statSync } from 'node:fs';
+import { readFileSync, readdirSync, unlinkSync, mkdirSync, writeFileSync, existsSync } from 'node:fs';
 import { dirname, join, relative, sep, resolve } from 'node:path';
 import { z } from 'zod';
-import { randomUUID, createHash } from 'node:crypto';
+import { createHash } from 'node:crypto';
 
 /**
  * Zod schema for jeeves-meta configuration.
@@ -15,7 +15,6 @@ import { randomUUID, createHash } from 'node:crypto';
 /** Zod schema for jeeves-meta configuration. */
 const synthConfigSchema = z.object({
     /** Filesystem paths to watch for .meta/ directories. */
-    watchPaths: z.array(z.string()).min(1),
     /** Watcher service base URL. */
     watcherUrl: z.url(),
     /** OpenClaw gateway base URL for subprocess spawning. */
@@ -48,6 +47,21 @@ const synthConfigSchema = z.object({
     skipUnchanged: z.boolean().default(true),
     /** Number of metas to synthesize per invocation. */
     batchSize: z.number().int().min(1).default(1),
+    /**
+     * Watcher metadata properties for live .meta/meta.json files.
+     * Virtual rules use these to tag live metas; scan queries derive
+     * their filter from the first domain value.
+     */
+    metaProperty: z
+        .object({ domains: z.array(z.string()).min(1) })
+        .default({ domains: ['meta'] }),
+    /**
+     * Watcher metadata properties for .meta/archive/** snapshots.
+     * Virtual rules use these to tag archive files.
+     */
+    metaArchiveProperty: z
+        .object({ domains: z.array(z.string()).min(1) })
+        .default({ domains: ['meta-archive'] }),
 });
 
 /**
@@ -310,81 +324,174 @@ var index$1 = /*#__PURE__*/Object.freeze({
 });
 
 /**
- * Ensure meta.json exists in each .meta/ directory.
+ * Normalize file paths to forward slashes for consistency with watcher-indexed paths.
  *
- * If meta.json is missing, creates it with a generated UUID.
+ * Watcher indexes paths with forward slashes (`j:/domains/...`). This utility
+ * ensures all paths in the library use the same convention, regardless of
+ * the platform's native separator.
  *
- * @module discovery/ensureMetaJson
+ * @module normalizePath
  */
 /**
- * Ensure meta.json exists at the given .meta/ path.
+ * Normalize a file path to forward slashes.
  *
- * @param metaPath - Absolute path to a .meta/ directory.
- * @returns The meta.json content (existing or newly created).
+ * @param p - File path (may contain backslashes).
+ * @returns Path with all backslashes replaced by forward slashes.
  */
-function ensureMetaJson(metaPath) {
-    const filePath = join(metaPath, 'meta.json');
-    if (existsSync(filePath)) {
-        const raw = readFileSync(filePath, 'utf8');
-        return JSON.parse(raw);
-    }
-    // Create the archive subdirectory while we're at it
-    const archivePath = join(metaPath, 'archive');
-    if (!existsSync(archivePath)) {
-        mkdirSync(archivePath, { recursive: true });
+function normalizePath$1(p) {
+    return p.replaceAll('\\', '/');
+}
+
+/**
+ * Paginated scan helper for exhaustive scope enumeration.
+ *
+ * @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) {
+    const allFiles = [];
+    let cursor;
+    do {
+        const result = await watcher.scan({ ...params, cursor });
+        allFiles.push(...result.files);
+        cursor = result.next;
+    } while (cursor);
+    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.
+ *
+ * @module discovery/discoverMetas
+ */
+/**
+ * Build a Qdrant filter from config metaProperty.
+ *
+ * @param config - Synth config with metaProperty.
+ * @returns Qdrant filter object for scanning live metas.
+ */
+function buildMetaFilter(config) {
+    return {
+        must: [
+            {
+                key: 'domains',
+                match: { value: config.metaProperty.domains[0] },
+            },
+        ],
+    };
+}
+/**
+ * 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 - Synth config (for domain filter).
+ * @param watcher - WatcherClient for scan queries.
+ * @returns Array of normalized .meta/ directory paths.
+ */
+async function discoverMetas(config, watcher) {
+    const filter = buildMetaFilter(config);
+    const scanFiles = await paginatedScan(watcher, {
+        filter,
+        fields: ['file_path'],
+    });
+    // Deduplicate by file_path (multi-chunk files)
+    const seen = new Set();
+    const metaPaths = [];
+    for (const sf of scanFiles) {
+        const fp = normalizePath$1(sf.file_path);
+        if (seen.has(fp))
+            continue;
+        seen.add(fp);
+        // Derive .meta/ directory from file_path (strip /meta.json)
+        const metaPath = fp.replace(/\/meta\.json$/, '');
+        metaPaths.push(metaPath);
     }
-    const meta = { _id: randomUUID() };
-    writeFileSync(filePath, JSON.stringify(meta, null, 2) + '\n');
-    return meta;
+    return metaPaths;
 }
 
 /**
- * Glob watchPaths for .meta/ directories.
+ * File-system lock for preventing concurrent synthesis on the same meta.
  *
- * Walks each watchPath recursively, collecting directories named '.meta'
- * that contain (or will contain) a meta.json file.
+ * Lock file: .meta/.lock containing PID + timestamp.
+ * Stale timeout: 30 minutes.
  *
- * @module discovery/globMetas
+ * @module lock
  */
+const LOCK_FILE = '.lock';
+const STALE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
 /**
- * Recursively find all .meta/ directories under the given paths.
+ * Attempt to acquire a lock on a .meta directory.
  *
- * @param watchPaths - Root directories to search.
- * @returns Array of absolute paths to .meta/ directories.
+ * @param metaPath - Absolute path to the .meta directory.
+ * @returns True if lock was acquired, false if already locked (non-stale).
  */
-function globMetas(watchPaths) {
-    const results = [];
-    function walk(dir) {
-        let entries;
+function acquireLock(metaPath) {
+    const lockPath = join(metaPath, LOCK_FILE);
+    if (existsSync(lockPath)) {
         try {
-            entries = readdirSync(dir);
+            const raw = readFileSync(lockPath, 'utf8');
+            const data = JSON.parse(raw);
+            const lockAge = Date.now() - new Date(data.startedAt).getTime();
+            if (lockAge < STALE_TIMEOUT_MS) {
+                return false; // Lock is active
+            }
+            // Stale lock — fall through to overwrite
         }
         catch {
-            return; // Skip unreadable directories
-        }
-        for (const entry of entries) {
-            const full = join(dir, entry);
-            let stat;
-            try {
-                stat = statSync(full);
-            }
-            catch {
-                continue;
-            }
-            if (!stat.isDirectory())
-                continue;
-            if (entry === '.meta') {
-                results.push(full);
-            }
-            else {
-                walk(full);
-            }
+            // Corrupt lock file — overwrite
         }
     }
-    for (const wp of watchPaths) {
-        walk(wp);
+    const lock = {
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+    };
+    writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n');
+    return true;
+}
+/**
+ * Release a lock on a .meta directory.
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ */
+function releaseLock(metaPath) {
+    const lockPath = join(metaPath, LOCK_FILE);
+    try {
+        unlinkSync(lockPath);
+    }
+    catch {
+        // Already removed or never existed
+    }
+}
+/**
+ * Check if a .meta directory is currently locked (non-stale).
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @returns True if locked and not stale.
+ */
+function isLocked(metaPath) {
+    const lockPath = join(metaPath, LOCK_FILE);
+    if (!existsSync(lockPath))
+        return false;
+    try {
+        const raw = readFileSync(lockPath, 'utf8');
+        const data = JSON.parse(raw);
+        const lockAge = Date.now() - new Date(data.startedAt).getTime();
+        return lockAge < STALE_TIMEOUT_MS;
+    }
+    catch {
+        return false; // Corrupt lock = not locked
     }
-    return results;
 }
 
 /**
@@ -397,7 +504,7 @@ function globMetas(watchPaths) {
  * @module discovery/ownershipTree
  */
 /** Normalize path separators to forward slashes for consistent comparison. */
-function normalizePath$1(p) {
+function normalizePath(p) {
     return p.split(sep).join('/');
 }
 /**
@@ -411,8 +518,8 @@ function buildOwnershipTree(metaPaths) {
     // Create nodes, sorted by ownerPath length (shortest first = shallowest)
     const sorted = [...metaPaths]
         .map((mp) => ({
-        metaPath: normalizePath$1(mp),
-        ownerPath: normalizePath$1(dirname(mp)),
+        metaPath: normalizePath(mp),
+        ownerPath: normalizePath(dirname(mp)),
     }))
         .sort((a, b) => a.ownerPath.length - b.ownerPath.length);
     for (const { metaPath, ownerPath } of sorted) {
@@ -464,6 +571,138 @@ function findNode(tree, targetPath) {
     return Array.from(tree.nodes.values()).find((n) => n.metaPath === targetPath || n.ownerPath === targetPath);
 }
 
+/**
+ * Unified meta listing: scan, dedup, enrich.
+ *
+ * Single source of truth for all consumers that need a list of metas
+ * with enriched metadata. Replaces duplicated scan+dedup logic in
+ * plugin tools, CLI, and prompt injection.
+ *
+ * @module discovery/listMetas
+ */
+/**
+ * Discover, deduplicate, and enrich all metas.
+ *
+ * This is the single consolidated function that replaces all duplicated
+ * scan+dedup+enrich logic across the codebase. All enrichment comes from
+ * reading meta.json on disk (the canonical source).
+ *
+ * @param config - Validated synthesis config.
+ * @param watcher - Watcher HTTP client for discovery.
+ * @returns Enriched meta list with summary statistics and ownership tree.
+ */
+async function listMetas(config, watcher) {
+    // Step 1: Discover deduplicated meta paths via watcher scan
+    const metaPaths = await discoverMetas(config, watcher);
+    // Step 2: Build ownership tree
+    const tree = buildOwnershipTree(metaPaths);
+    // Step 3: Read and enrich each meta from disk
+    const entries = [];
+    let staleCount = 0;
+    let errorCount = 0;
+    let lockedCount = 0;
+    let neverSynthesizedCount = 0;
+    let totalArchTokens = 0;
+    let totalBuilderTokens = 0;
+    let totalCriticTokens = 0;
+    let lastSynthPath = null;
+    let lastSynthAt = null;
+    let stalestPath = null;
+    let stalestEffective = -1;
+    for (const node of tree.nodes.values()) {
+        let meta;
+        try {
+            meta = JSON.parse(readFileSync(join(node.metaPath, 'meta.json'), 'utf8'));
+        }
+        catch {
+            // Skip unreadable metas
+            continue;
+        }
+        const depth = meta._depth ?? node.treeDepth;
+        const emphasis = meta._emphasis ?? 1;
+        const hasError = Boolean(meta._error);
+        const locked = isLocked(normalizePath$1(node.metaPath));
+        const neverSynth = !meta._generatedAt;
+        // Compute staleness
+        let stalenessSeconds;
+        if (neverSynth) {
+            stalenessSeconds = Infinity;
+        }
+        else {
+            const genAt = new Date(meta._generatedAt).getTime();
+            stalenessSeconds = Math.max(0, Math.floor((Date.now() - genAt) / 1000));
+        }
+        // Tokens
+        const archTokens = meta._architectTokens ?? 0;
+        const buildTokens = meta._builderTokens ?? 0;
+        const critTokens = meta._criticTokens ?? 0;
+        // Accumulate summary stats
+        if (stalenessSeconds > 0)
+            staleCount++;
+        if (hasError)
+            errorCount++;
+        if (locked)
+            lockedCount++;
+        if (neverSynth)
+            neverSynthesizedCount++;
+        totalArchTokens += archTokens;
+        totalBuilderTokens += buildTokens;
+        totalCriticTokens += critTokens;
+        // Track last synthesized
+        if (meta._generatedAt) {
+            if (!lastSynthAt || meta._generatedAt > lastSynthAt) {
+                lastSynthAt = meta._generatedAt;
+                lastSynthPath = node.metaPath;
+            }
+        }
+        // Track stalest (effective staleness for scheduling)
+        const depthFactor = Math.pow(1 + config.depthWeight, depth);
+        const effectiveStaleness = (stalenessSeconds === Infinity
+            ? Number.MAX_SAFE_INTEGER
+            : stalenessSeconds) *
+            depthFactor *
+            emphasis;
+        if (effectiveStaleness > stalestEffective) {
+            stalestEffective = effectiveStaleness;
+            stalestPath = node.metaPath;
+        }
+        entries.push({
+            path: node.metaPath,
+            depth,
+            emphasis,
+            stalenessSeconds,
+            lastSynthesized: meta._generatedAt ?? null,
+            hasError,
+            locked,
+            architectTokens: archTokens > 0 ? archTokens : null,
+            builderTokens: buildTokens > 0 ? buildTokens : null,
+            criticTokens: critTokens > 0 ? critTokens : null,
+            children: node.children.length,
+            node,
+            meta,
+        });
+    }
+    return {
+        summary: {
+            total: entries.length,
+            stale: staleCount,
+            errors: errorCount,
+            locked: lockedCount,
+            neverSynthesized: neverSynthesizedCount,
+            tokens: {
+                architect: totalArchTokens,
+                builder: totalBuilderTokens,
+                critic: totalCriticTokens,
+            },
+            stalestPath,
+            lastSynthesizedPath: lastSynthPath,
+            lastSynthesizedAt: lastSynthAt,
+        },
+        entries,
+        tree,
+    };
+}
+
 /**
  * Compute the file scope owned by a meta node.
  *
@@ -535,26 +774,126 @@ function computeEma(current, previous, decay = DEFAULT_DECAY) {
 }
 
 /**
- * Paginated scan helper for exhaustive scope enumeration.
+ * Shared error utilities.
  *
- * @module paginatedScan
+ * @module errors
  */
 /**
- * Perform a paginated scan that follows cursor tokens until exhausted.
+ * Wrap an unknown caught value into a SynthError.
  *
- * @param watcher - WatcherClient instance.
- * @param params - Base scan parameters (cursor is managed internally).
- * @returns All matching files across all pages.
+ * @param step - Which synthesis step failed.
+ * @param err - The caught error value.
+ * @param code - Error classification code.
+ * @returns A structured SynthError.
  */
-async function paginatedScan(watcher, params) {
-    const allFiles = [];
-    let cursor;
-    do {
-        const result = await watcher.scan({ ...params, cursor });
-        allFiles.push(...result.files);
-        cursor = result.next;
-    } while (cursor);
-    return allFiles;
+function toSynthError(step, err, code = 'FAILED') {
+    return {
+        step,
+        code,
+        message: err instanceof Error ? err.message : String(err),
+    };
+}
+
+/**
+ * SynthExecutor implementation using the OpenClaw gateway HTTP API.
+ *
+ * Lives in the library package so both plugin and runner can import it.
+ * Spawns sub-agent sessions via the gateway, polls for completion,
+ * and extracts output text.
+ *
+ * @module executor/GatewayExecutor
+ */
+const DEFAULT_POLL_INTERVAL_MS = 5000;
+const DEFAULT_TIMEOUT_MS = 600_000; // 10 minutes
+/** Sleep helper. */
+function sleep$1(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * SynthExecutor that spawns OpenClaw sessions via the gateway HTTP API.
+ *
+ * Used by both the OpenClaw plugin (in-process tool calls) and the
+ * runner/CLI (external invocation). Constructs from `gatewayUrl` and
+ * optional `apiKey` — typically sourced from `SynthConfig`.
+ */
+class GatewayExecutor {
+    gatewayUrl;
+    apiKey;
+    pollIntervalMs;
+    constructor(options = {}) {
+        this.gatewayUrl = (options.gatewayUrl ?? 'http://127.0.0.1:3000').replace(/\/+$/, '');
+        this.apiKey = options.apiKey;
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    }
+    async spawn(task, options) {
+        const timeoutMs = (options?.timeout ?? DEFAULT_TIMEOUT_MS / 1000) * 1000;
+        const deadline = Date.now() + timeoutMs;
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (this.apiKey) {
+            headers['Authorization'] = 'Bearer ' + this.apiKey;
+        }
+        const spawnRes = await fetch(this.gatewayUrl + '/api/sessions/spawn', {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                task,
+                mode: 'run',
+                model: options?.model,
+                runTimeoutSeconds: options?.timeout,
+            }),
+        });
+        if (!spawnRes.ok) {
+            const text = await spawnRes.text();
+            throw new Error('Gateway spawn failed: HTTP ' +
+                spawnRes.status.toString() +
+                ' - ' +
+                text);
+        }
+        const spawnData = (await spawnRes.json());
+        if (!spawnData.sessionKey) {
+            throw new Error('Gateway spawn returned no sessionKey: ' + JSON.stringify(spawnData));
+        }
+        const { sessionKey } = spawnData;
+        // Poll for completion
+        while (Date.now() < deadline) {
+            await sleep$1(this.pollIntervalMs);
+            const historyRes = await fetch(this.gatewayUrl +
+                '/api/sessions/' +
+                encodeURIComponent(sessionKey) +
+                '/history?limit=50', { headers });
+            if (!historyRes.ok)
+                continue;
+            const history = (await historyRes.json());
+            if (history.status === 'completed' || history.status === 'done') {
+                // Extract token usage from session-level or message-level usage
+                let tokens;
+                if (history.usage?.totalTokens) {
+                    tokens = history.usage.totalTokens;
+                }
+                else {
+                    // Sum message-level usage as fallback
+                    let sum = 0;
+                    for (const msg of history.messages ?? []) {
+                        if (msg.usage?.totalTokens)
+                            sum += msg.usage.totalTokens;
+                    }
+                    if (sum > 0)
+                        tokens = sum;
+                }
+                // Extract the last assistant message as output
+                const messages = history.messages ?? [];
+                for (let i = messages.length - 1; i >= 0; i--) {
+                    if (messages[i].role === 'assistant' && messages[i].content) {
+                        return { output: messages[i].content, tokens };
+                    }
+                }
+                return { output: '', tokens };
+            }
+        }
+        throw new Error('Synthesis subprocess timed out after ' + timeoutMs.toString() + 'ms');
+    }
 }
 
 /**
@@ -737,227 +1076,113 @@ function buildBuilderTask(ctx, meta, config) {
  * @param meta - Current meta.json (with _content already set by builder).
  * @param config - Synthesis config.
  * @returns The critic task prompt string.
- */
-function buildCriticTask(ctx, meta, config) {
-    const sections = [
-        meta._critic ?? config.defaultCritic,
-        '',
-        '## SYNTHESIS TO EVALUATE',
-        meta._content ?? '(No content produced)',
-        '',
-        '## SCOPE',
-        `Path: ${ctx.path}`,
-        `Files in scope: ${ctx.scopeFiles.length.toString()}`,
-    ];
-    appendSharedSections(sections, ctx, {
-        includePreviousContent: false,
-        feedbackHeading: '## YOUR PREVIOUS FEEDBACK',
-        includeChildMetas: false,
-    });
-    sections.push('', '## OUTPUT FORMAT', 'Return your evaluation as Markdown text. Be specific and actionable.');
-    return sections.join('\n');
-}
-
-/**
- * Merge synthesis results into meta.json.
- *
- * Preserves human-set fields (_id, _steer, _depth).
- * Writes engine fields (_generatedAt, _structureHash, etc.).
- * Validates against schema before writing.
- *
- * @module orchestrator/merge
- */
-/**
- * Merge results into meta.json and write atomically.
- *
- * @param options - Merge options.
- * @returns The updated MetaJson.
- * @throws If validation fails (malformed output).
- */
-function mergeAndWrite(options) {
-    const merged = {
-        // Preserve human-set fields
-        _id: options.current._id,
-        _steer: options.current._steer,
-        _depth: options.current._depth,
-        _emphasis: options.current._emphasis,
-        // Engine fields
-        _architect: options.architect,
-        _builder: options.builder,
-        _critic: options.critic,
-        _generatedAt: new Date().toISOString(),
-        _structureHash: options.structureHash,
-        _synthesisCount: options.synthesisCount,
-        // Token tracking
-        _architectTokens: options.architectTokens,
-        _builderTokens: options.builderTokens,
-        _criticTokens: options.criticTokens,
-        _architectTokensAvg: options.architectTokens !== undefined
-            ? computeEma(options.architectTokens, options.current._architectTokensAvg)
-            : options.current._architectTokensAvg,
-        _builderTokensAvg: options.builderTokens !== undefined
-            ? computeEma(options.builderTokens, options.current._builderTokensAvg)
-            : options.current._builderTokensAvg,
-        _criticTokensAvg: options.criticTokens !== undefined
-            ? computeEma(options.criticTokens, options.current._criticTokensAvg)
-            : options.current._criticTokensAvg,
-        // Content from builder
-        _content: options.builderOutput?.content ?? options.current._content,
-        // Feedback from critic
-        _feedback: options.feedback ?? options.current._feedback,
-        // Error handling
-        _error: options.error ?? undefined,
-        // Spread structured fields from builder
-        ...options.builderOutput?.fields,
-    };
-    // Clean up undefined optional fields
-    if (merged._steer === undefined)
-        delete merged._steer;
-    if (merged._depth === undefined)
-        delete merged._depth;
-    if (merged._emphasis === undefined)
-        delete merged._emphasis;
-    if (merged._architectTokens === undefined)
-        delete merged._architectTokens;
-    if (merged._builderTokens === undefined)
-        delete merged._builderTokens;
-    if (merged._criticTokens === undefined)
-        delete merged._criticTokens;
-    if (merged._architectTokensAvg === undefined)
-        delete merged._architectTokensAvg;
-    if (merged._builderTokensAvg === undefined)
-        delete merged._builderTokensAvg;
-    if (merged._criticTokensAvg === undefined)
-        delete merged._criticTokensAvg;
-    if (merged._error === undefined)
-        delete merged._error;
-    if (merged._content === undefined)
-        delete merged._content;
-    if (merged._feedback === undefined)
-        delete merged._feedback;
-    // Validate
-    const result = metaJsonSchema.safeParse(merged);
-    if (!result.success) {
-        throw new Error(`Meta validation failed: ${result.error.message}`);
-    }
-    // Write atomically
-    const filePath = join(options.metaPath, 'meta.json');
-    writeFileSync(filePath, JSON.stringify(result.data, null, 2) + '\n');
-    return result.data;
-}
-
-/**
- * Shared error utilities.
- *
- * @module errors
- */
-/**
- * Wrap an unknown caught value into a SynthError.
- *
- * @param step - Which synthesis step failed.
- * @param err - The caught error value.
- * @param code - Error classification code.
- * @returns A structured SynthError.
- */
-function toSynthError(step, err, code = 'FAILED') {
-    return {
-        step,
-        code,
-        message: err instanceof Error ? err.message : String(err),
-    };
-}
-
-/**
- * File-system lock for preventing concurrent synthesis on the same meta.
- *
- * Lock file: .meta/.lock containing PID + timestamp.
- * Stale timeout: 30 minutes.
- *
- * @module lock
- */
-const LOCK_FILE = '.lock';
-const STALE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
-/**
- * Attempt to acquire a lock on a .meta directory.
- *
- * @param metaPath - Absolute path to the .meta directory.
- * @returns True if lock was acquired, false if already locked (non-stale).
- */
-function acquireLock(metaPath) {
-    const lockPath = join(metaPath, LOCK_FILE);
-    if (existsSync(lockPath)) {
-        try {
-            const raw = readFileSync(lockPath, 'utf8');
-            const data = JSON.parse(raw);
-            const lockAge = Date.now() - new Date(data.startedAt).getTime();
-            if (lockAge < STALE_TIMEOUT_MS) {
-                return false; // Lock is active
-            }
-            // Stale lock — fall through to overwrite
-        }
-        catch {
-            // Corrupt lock file — overwrite
-        }
-    }
-    const lock = {
-        pid: process.pid,
-        startedAt: new Date().toISOString(),
-    };
-    writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n');
-    return true;
-}
-/**
- * Release a lock on a .meta directory.
- *
- * @param metaPath - Absolute path to the .meta directory.
- */
-function releaseLock(metaPath) {
-    const lockPath = join(metaPath, LOCK_FILE);
-    try {
-        unlinkSync(lockPath);
-    }
-    catch {
-        // Already removed or never existed
-    }
-}
-/**
- * Check if a .meta directory is currently locked (non-stale).
- *
- * @param metaPath - Absolute path to the .meta directory.
- * @returns True if locked and not stale.
- */
-function isLocked(metaPath) {
-    const lockPath = join(metaPath, LOCK_FILE);
-    if (!existsSync(lockPath))
-        return false;
-    try {
-        const raw = readFileSync(lockPath, 'utf8');
-        const data = JSON.parse(raw);
-        const lockAge = Date.now() - new Date(data.startedAt).getTime();
-        return lockAge < STALE_TIMEOUT_MS;
-    }
-    catch {
-        return false; // Corrupt lock = not locked
-    }
+ */
+function buildCriticTask(ctx, meta, config) {
+    const sections = [
+        meta._critic ?? config.defaultCritic,
+        '',
+        '## SYNTHESIS TO EVALUATE',
+        meta._content ?? '(No content produced)',
+        '',
+        '## SCOPE',
+        `Path: ${ctx.path}`,
+        `Files in scope: ${ctx.scopeFiles.length.toString()}`,
+    ];
+    appendSharedSections(sections, ctx, {
+        includePreviousContent: false,
+        feedbackHeading: '## YOUR PREVIOUS FEEDBACK',
+        includeChildMetas: false,
+    });
+    sections.push('', '## OUTPUT FORMAT', 'Return your evaluation as Markdown text. Be specific and actionable.');
+    return sections.join('\n');
 }
 
 /**
- * Normalize file paths to forward slashes for consistency with watcher-indexed paths.
+ * Merge synthesis results into meta.json.
  *
- * Watcher indexes paths with forward slashes (`j:/domains/...`). This utility
- * ensures all paths in the library use the same convention, regardless of
- * the platform's native separator.
+ * Preserves human-set fields (_id, _steer, _depth).
+ * Writes engine fields (_generatedAt, _structureHash, etc.).
+ * Validates against schema before writing.
  *
- * @module normalizePath
+ * @module orchestrator/merge
  */
 /**
- * Normalize a file path to forward slashes.
+ * Merge results into meta.json and write atomically.
  *
- * @param p - File path (may contain backslashes).
- * @returns Path with all backslashes replaced by forward slashes.
+ * @param options - Merge options.
+ * @returns The updated MetaJson.
+ * @throws If validation fails (malformed output).
  */
-function normalizePath(p) {
-    return p.replaceAll('\\', '/');
+function mergeAndWrite(options) {
+    const merged = {
+        // Preserve human-set fields
+        _id: options.current._id,
+        _steer: options.current._steer,
+        _depth: options.current._depth,
+        _emphasis: options.current._emphasis,
+        // Engine fields
+        _architect: options.architect,
+        _builder: options.builder,
+        _critic: options.critic,
+        _generatedAt: new Date().toISOString(),
+        _structureHash: options.structureHash,
+        _synthesisCount: options.synthesisCount,
+        // Token tracking
+        _architectTokens: options.architectTokens,
+        _builderTokens: options.builderTokens,
+        _criticTokens: options.criticTokens,
+        _architectTokensAvg: options.architectTokens !== undefined
+            ? computeEma(options.architectTokens, options.current._architectTokensAvg)
+            : options.current._architectTokensAvg,
+        _builderTokensAvg: options.builderTokens !== undefined
+            ? computeEma(options.builderTokens, options.current._builderTokensAvg)
+            : options.current._builderTokensAvg,
+        _criticTokensAvg: options.criticTokens !== undefined
+            ? computeEma(options.criticTokens, options.current._criticTokensAvg)
+            : options.current._criticTokensAvg,
+        // Content from builder
+        _content: options.builderOutput?.content ?? options.current._content,
+        // Feedback from critic
+        _feedback: options.feedback ?? options.current._feedback,
+        // Error handling
+        _error: options.error ?? undefined,
+        // Spread structured fields from builder
+        ...options.builderOutput?.fields,
+    };
+    // Clean up undefined optional fields
+    if (merged._steer === undefined)
+        delete merged._steer;
+    if (merged._depth === undefined)
+        delete merged._depth;
+    if (merged._emphasis === undefined)
+        delete merged._emphasis;
+    if (merged._architectTokens === undefined)
+        delete merged._architectTokens;
+    if (merged._builderTokens === undefined)
+        delete merged._builderTokens;
+    if (merged._criticTokens === undefined)
+        delete merged._criticTokens;
+    if (merged._architectTokensAvg === undefined)
+        delete merged._architectTokensAvg;
+    if (merged._builderTokensAvg === undefined)
+        delete merged._builderTokensAvg;
+    if (merged._criticTokensAvg === undefined)
+        delete merged._criticTokensAvg;
+    if (merged._error === undefined)
+        delete merged._error;
+    if (merged._content === undefined)
+        delete merged._content;
+    if (merged._feedback === undefined)
+        delete merged._feedback;
+    // Validate
+    const result = metaJsonSchema.safeParse(merged);
+    if (!result.success) {
+        throw new Error(`Meta validation failed: ${result.error.message}`);
+    }
+    // Write atomically
+    const filePath = join(options.metaPath, 'meta.json');
+    writeFileSync(filePath, JSON.stringify(result.data, null, 2) + '\n');
+    return result.data;
 }
 
 /**
@@ -1216,17 +1441,32 @@ function finalizeCycle(metaPath, current, config, architect, builder, critic, bu
  * @param watcher - Watcher HTTP client.
  * @returns Result indicating whether synthesis occurred.
  */
-async function orchestrateOnce(config, executor, watcher) {
-    // Step 1: Discover
-    const metaPaths = globMetas(config.watchPaths);
+async function orchestrateOnce(config, executor, watcher, targetPath) {
+    // Step 1: Discover via watcher scan
+    const metaPaths = await discoverMetas(config, watcher);
     if (metaPaths.length === 0)
         return { synthesized: false };
-    // Ensure all meta.json files exist
+    // Read meta.json for each discovered meta
     const metas = new Map();
     for (const mp of metaPaths) {
-        metas.set(normalizePath(mp), ensureMetaJson(mp));
+        const metaFilePath = join(mp, 'meta.json');
+        try {
+            metas.set(normalizePath$1(mp), JSON.parse(readFileSync(metaFilePath, 'utf8')));
+        }
+        catch {
+            // Skip metas with unreadable meta.json
+            continue;
+        }
     }
     const tree = buildOwnershipTree(metaPaths);
+    // If targetPath specified, skip candidate selection — go directly to that meta
+    let targetNode;
+    if (targetPath) {
+        const normalized = normalizePath$1(targetPath);
+        targetNode = findNode(tree, normalized) ?? undefined;
+        if (!targetNode)
+            return { synthesized: false };
+    }
     // Steps 3-4: Staleness check + candidate selection
     const candidates = [];
     for (const node of tree.nodes.values()) {
@@ -1261,9 +1501,13 @@ async function orchestrateOnce(config, executor, watcher) {
         winner = candidate;
         break;
     }
-    if (!winner)
+    if (!winner && !targetNode)
+        return { synthesized: false };
+    const node = targetNode ?? winner.node;
+    // For targeted path, acquire lock now (candidate selection already locked for stalest)
+    if (targetNode && !acquireLock(node.metaPath)) {
         return { synthesized: false };
-    const { node } = winner;
+    }
     try {
         // Re-read meta after lock (may have changed)
         const currentMeta = JSON.parse(readFileSync(join(node.metaPath, 'meta.json'), 'utf8'));
@@ -1373,12 +1617,13 @@ async function orchestrateOnce(config, executor, watcher) {
  * @param config - Validated synthesis config.
  * @param executor - Pluggable LLM executor.
  * @param watcher - Watcher HTTP client.
+ * @param targetPath - Optional: specific meta/owner path to synthesize instead of stalest candidate.
  * @returns Array of results, one per cycle attempted.
  */
-async function orchestrate(config, executor, watcher) {
+async function orchestrate(config, executor, watcher, targetPath) {
     const results = [];
     for (let i = 0; i < config.batchSize; i++) {
-        const result = await orchestrateOnce(config, executor, watcher);
+        const result = await orchestrateOnce(config, executor, watcher, targetPath);
         results.push(result);
         if (!result.synthesized)
             break; // No more candidates
@@ -1386,108 +1631,6 @@ async function orchestrate(config, executor, watcher) {
     return results;
 }
 
-/**
- * SynthExecutor implementation using the OpenClaw gateway HTTP API.
- *
- * Lives in the library package so both plugin and runner can import it.
- * Spawns sub-agent sessions via the gateway, polls for completion,
- * and extracts output text.
- *
- * @module executor/GatewayExecutor
- */
-const DEFAULT_POLL_INTERVAL_MS = 5000;
-const DEFAULT_TIMEOUT_MS = 600_000; // 10 minutes
-/** Sleep helper. */
-function sleep$1(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-/**
- * SynthExecutor that spawns OpenClaw sessions via the gateway HTTP API.
- *
- * Used by both the OpenClaw plugin (in-process tool calls) and the
- * runner/CLI (external invocation). Constructs from `gatewayUrl` and
- * optional `apiKey` — typically sourced from `SynthConfig`.
- */
-class GatewayExecutor {
-    gatewayUrl;
-    apiKey;
-    pollIntervalMs;
-    constructor(options = {}) {
-        this.gatewayUrl = (options.gatewayUrl ?? 'http://127.0.0.1:3000').replace(/\/+$/, '');
-        this.apiKey = options.apiKey;
-        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-    }
-    async spawn(task, options) {
-        const timeoutMs = (options?.timeout ?? DEFAULT_TIMEOUT_MS / 1000) * 1000;
-        const deadline = Date.now() + timeoutMs;
-        const headers = {
-            'Content-Type': 'application/json',
-        };
-        if (this.apiKey) {
-            headers['Authorization'] = 'Bearer ' + this.apiKey;
-        }
-        const spawnRes = await fetch(this.gatewayUrl + '/api/sessions/spawn', {
-            method: 'POST',
-            headers,
-            body: JSON.stringify({
-                task,
-                mode: 'run',
-                model: options?.model,
-                runTimeoutSeconds: options?.timeout,
-            }),
-        });
-        if (!spawnRes.ok) {
-            const text = await spawnRes.text();
-            throw new Error('Gateway spawn failed: HTTP ' +
-                spawnRes.status.toString() +
-                ' - ' +
-                text);
-        }
-        const spawnData = (await spawnRes.json());
-        if (!spawnData.sessionKey) {
-            throw new Error('Gateway spawn returned no sessionKey: ' + JSON.stringify(spawnData));
-        }
-        const { sessionKey } = spawnData;
-        // Poll for completion
-        while (Date.now() < deadline) {
-            await sleep$1(this.pollIntervalMs);
-            const historyRes = await fetch(this.gatewayUrl +
-                '/api/sessions/' +
-                encodeURIComponent(sessionKey) +
-                '/history?limit=50', { headers });
-            if (!historyRes.ok)
-                continue;
-            const history = (await historyRes.json());
-            if (history.status === 'completed' || history.status === 'done') {
-                // Extract token usage from session-level or message-level usage
-                let tokens;
-                if (history.usage?.totalTokens) {
-                    tokens = history.usage.totalTokens;
-                }
-                else {
-                    // Sum message-level usage as fallback
-                    let sum = 0;
-                    for (const msg of history.messages ?? []) {
-                        if (msg.usage?.totalTokens)
-                            sum += msg.usage.totalTokens;
-                    }
-                    if (sum > 0)
-                        tokens = sum;
-                }
-                // Extract the last assistant message as output
-                const messages = history.messages ?? [];
-                for (let i = messages.length - 1; i >= 0; i--) {
-                    if (messages[i].role === 'assistant' && messages[i].content) {
-                        return { output: messages[i].content, tokens };
-                    }
-                }
-                return { output: '', tokens };
-            }
-        }
-        throw new Error('Synthesis subprocess timed out after ' + timeoutMs.toString() + 'ms');
-    }
-}
-
 /**
  * HTTP implementation of the WatcherClient interface.
  *
@@ -1546,16 +1689,31 @@ class HttpWatcherClient {
         throw new Error('Retry exhausted');
     }
     async scan(params) {
-        const body = {};
-        if (params.pathPrefix !== undefined) {
-            body.pathPrefix = params.pathPrefix;
+        // 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);
+            }
         }
-        if (params.filter !== undefined) {
-            body.filter = params.filter;
+        // Translate pathPrefix into a Qdrant text match on file_path
+        if (params.pathPrefix !== undefined) {
+            mustClauses.push({
+                key: 'file_path',
+                match: { text: params.pathPrefix },
+            });
         }
+        // Translate modifiedAfter into a Qdrant range filter on modified_at
         if (params.modifiedAfter !== undefined) {
-            body.modifiedAfter = params.modifiedAfter;
+            mustClauses.push({
+                key: 'modified_at',
+                range: { gt: params.modifiedAfter },
+            });
         }
+        const filter = { must: mustClauses };
+        const body = { filter };
         if (params.fields !== undefined) {
             body.fields = params.fields;
         }
@@ -1604,25 +1762,26 @@ var index = /*#__PURE__*/Object.freeze({
     buildBuilderTask: buildBuilderTask,
     buildContextPackage: buildContextPackage,
     buildCriticTask: buildCriticTask,
+    buildMetaFilter: buildMetaFilter,
     buildOwnershipTree: buildOwnershipTree,
     computeEffectiveStaleness: computeEffectiveStaleness,
     computeEma: computeEma,
     computeStructureHash: computeStructureHash,
     createSnapshot: createSnapshot,
-    ensureMetaJson: ensureMetaJson,
+    discoverMetas: discoverMetas,
     filterInScope: filterInScope,
     findNode: findNode,
     getScopePrefix: getScopePrefix,
-    globMetas: globMetas,
     hasSteerChanged: hasSteerChanged,
     isArchitectTriggered: isArchitectTriggered,
     isLocked: isLocked,
     isStale: isStale,
     listArchiveFiles: listArchiveFiles,
+    listMetas: listMetas,
     loadSynthConfig: loadSynthConfig,
     mergeAndWrite: mergeAndWrite,
     metaJsonSchema: metaJsonSchema,
-    normalizePath: normalizePath,
+    normalizePath: normalizePath$1,
     orchestrate: orchestrate,
     paginatedScan: paginatedScan,
     parseArchitectOutput: parseArchitectOutput,
@@ -1648,6 +1807,10 @@ var index = /*#__PURE__*/Object.freeze({
  *
  * @module cli
  */
+/** Read and parse a meta.json file with proper typing. */
+function readMeta(metaPath) {
+    return JSON.parse(readFileSync(join(metaPath, 'meta.json'), 'utf8'));
+}
 const args = process.argv.slice(2);
 const command = args.find((a) => !a.startsWith('-'));
 const jsonOutput = args.includes('--json');
@@ -1683,73 +1846,38 @@ function output(data) {
         console.log(JSON.stringify(data, null, 2));
     }
 }
-function runStatus(config) {
-    const metaPaths = globMetas(config.watchPaths);
-    const tree = buildOwnershipTree(metaPaths);
-    let stale = 0;
-    let errors = 0;
-    let locked = 0;
-    let neverSynth = 0;
-    let archTokens = 0;
-    let buildTokens = 0;
-    let critTokens = 0;
-    for (const node of tree.nodes.values()) {
-        const meta = ensureMetaJson(node.metaPath);
-        const s = actualStaleness(meta);
-        if (s > 0)
-            stale++;
-        if (meta._error)
-            errors++;
-        if (isLocked(normalizePath(node.metaPath)))
-            locked++;
-        if (!meta._generatedAt)
-            neverSynth++;
-        if (meta._architectTokens)
-            archTokens += meta._architectTokens;
-        if (meta._builderTokens)
-            buildTokens += meta._builderTokens;
-        if (meta._criticTokens)
-            critTokens += meta._criticTokens;
-    }
-    output({
-        total: tree.nodes.size,
-        stale,
-        errors,
-        locked,
-        neverSynthesized: neverSynth,
-        tokens: { architect: archTokens, builder: buildTokens, critic: critTokens },
-    });
+async function runStatus(config) {
+    const watcher = new HttpWatcherClient({ baseUrl: config.watcherUrl });
+    const result = await listMetas(config, watcher);
+    output(result.summary);
 }
-function runList(config) {
+async function runList(config) {
     const prefix = getArg('--prefix');
     const filter = getArg('--filter');
-    const metaPaths = globMetas(config.watchPaths);
-    const tree = buildOwnershipTree(metaPaths);
-    const rows = [];
-    for (const node of tree.nodes.values()) {
-        if (prefix && !node.metaPath.includes(prefix))
-            continue;
-        const meta = ensureMetaJson(node.metaPath);
-        const s = actualStaleness(meta);
-        const hasError = Boolean(meta._error);
-        const isLockedNow = isLocked(normalizePath(node.metaPath));
-        if (filter === 'hasError' && !hasError)
-            continue;
-        if (filter === 'stale' && s <= 0)
-            continue;
-        if (filter === 'locked' && !isLockedNow)
-            continue;
-        if (filter === 'never' && meta._generatedAt)
-            continue;
-        rows.push({
-            path: node.metaPath,
-            depth: meta._depth ?? node.treeDepth,
-            staleness: s === Infinity ? 'never' : String(Math.round(s)) + 's',
-            hasError,
-            locked: isLockedNow,
-            children: node.children.length,
-        });
-    }
+    const watcher = new HttpWatcherClient({ baseUrl: config.watcherUrl });
+    const result = await listMetas(config, watcher);
+    let entries = result.entries;
+    if (prefix) {
+        entries = entries.filter((e) => e.path.includes(prefix));
+    }
+    if (filter === 'hasError')
+        entries = entries.filter((e) => e.hasError);
+    if (filter === 'stale')
+        entries = entries.filter((e) => e.stalenessSeconds > 0);
+    if (filter === 'locked')
+        entries = entries.filter((e) => e.locked);
+    if (filter === 'never')
+        entries = entries.filter((e) => e.stalenessSeconds === Infinity);
+    const rows = entries.map((e) => ({
+        path: e.path,
+        depth: e.depth,
+        staleness: e.stalenessSeconds === Infinity
+            ? 'never'
+            : String(Math.round(e.stalenessSeconds)) + 's',
+        hasError: e.hasError,
+        locked: e.locked,
+        children: e.children,
+    }));
     output({ total: rows.length, items: rows });
 }
 async function runDetail(config) {
@@ -1759,15 +1887,15 @@ async function runDetail(config) {
         process.exit(1);
     }
     const archiveArg = getArg('--archive');
-    const metaPaths = globMetas(config.watchPaths);
-    const tree = buildOwnershipTree(metaPaths);
-    const normalized = normalizePath(targetPath);
-    const node = findNode(tree, normalized);
+    const watcher = new HttpWatcherClient({ baseUrl: config.watcherUrl });
+    const metaResult = await listMetas(config, watcher);
+    const normalized = normalizePath$1(targetPath);
+    const node = findNode(metaResult.tree, normalized);
     if (!node) {
         console.error('Meta not found: ' + targetPath);
         process.exit(1);
     }
-    const meta = ensureMetaJson(node.metaPath);
+    const meta = readMeta(node.metaPath);
     const result = { meta };
     if (archiveArg) {
         const { listArchiveFiles } = await Promise.resolve().then(function () { return index$1; });
@@ -1783,27 +1911,26 @@ async function runDetail(config) {
 }
 async function runPreview(config) {
     const targetPath = getArg('--path');
-    const { filterInScope, paginatedScan, readLatestArchive, computeStructureHash, selectCandidate, } = await Promise.resolve().then(function () { return index; });
-    const metaPaths = globMetas(config.watchPaths);
-    const tree = buildOwnershipTree(metaPaths);
+    const { filterInScope, paginatedScan, readLatestArchive, computeStructureHash, } = await Promise.resolve().then(function () { return index; });
     const watcher = new HttpWatcherClient({ baseUrl: config.watcherUrl });
+    const metaResult = await listMetas(config, watcher);
     let targetNode;
     if (targetPath) {
-        const normalized = normalizePath(targetPath);
-        targetNode = findNode(tree, normalized);
+        const normalized = normalizePath$1(targetPath);
+        targetNode = findNode(metaResult.tree, normalized);
         if (!targetNode) {
             console.error('Meta not found: ' + targetPath);
             process.exit(1);
         }
     }
     else {
-        const candidates = [];
-        for (const node of tree.nodes.values()) {
-            const meta = ensureMetaJson(node.metaPath);
-            const s = actualStaleness(meta);
-            if (s > 0)
-                candidates.push({ node, meta, actualStaleness: s });
-        }
+        const candidates = metaResult.entries
+            .filter((e) => e.stalenessSeconds > 0)
+            .map((e) => ({
+            node: e.node,
+            meta: e.meta,
+            actualStaleness: e.stalenessSeconds,
+        }));
         const weighted = computeEffectiveStaleness(candidates, config.depthWeight);
         const winner = selectCandidate(weighted);
         if (!winner) {
@@ -1812,7 +1939,7 @@ async function runPreview(config) {
         }
         targetNode = winner.node;
     }
-    const meta = ensureMetaJson(targetNode.metaPath);
+    const meta = readMeta(targetNode.metaPath);
     const allFiles = await paginatedScan(watcher, {
         pathPrefix: targetNode.ownerPath,
     });
@@ -1840,9 +1967,6 @@ async function runSynthesize(config) {
     const batchArg = getArg('--batch');
     const effectiveConfig = {
         ...config,
-        ...(targetPath
-            ? { watchPaths: [targetPath.replace(/[/\\]\.meta[/\\]?$/, '')] }
-            : {}),
         ...(batchArg ? { batchSize: parseInt(batchArg, 10) } : {}),
     };
     const executor = new GatewayExecutor({
@@ -1850,7 +1974,7 @@ async function runSynthesize(config) {
         apiKey: config.gatewayApiKey,
     });
     const watcher = new HttpWatcherClient({ baseUrl: config.watcherUrl });
-    const results = await orchestrate(effectiveConfig, executor, watcher);
+    const results = await orchestrate(effectiveConfig, executor, watcher, targetPath ?? undefined);
     const synthesized = results.filter((r) => r.synthesized);
     output({
         synthesizedCount: synthesized.length,
@@ -1921,9 +2045,16 @@ async function runValidate(config) {
     catch {
         checks.gateway = 'UNREACHABLE (' + config.gatewayUrl + ')';
     }
-    // Check watch paths
-    const metaPaths = globMetas(config.watchPaths);
-    checks.metas = String(metaPaths.length) + ' .meta/ directories found';
+    // Check meta discovery via watcher
+    try {
+        const watcherClient = new HttpWatcherClient({ baseUrl: config.watcherUrl });
+        const metaPaths = await discoverMetas(config, watcherClient);
+        checks.metas =
+            String(metaPaths.length) + ' .meta/ entities discovered via watcher';
+    }
+    catch {
+        checks.metas = 'FAILED — could not discover metas (watcher may be down)';
+    }
     output({ config: 'valid', checks });
 }
 function runConfigShow(config) {
@@ -1983,10 +2114,10 @@ async function main() {
     }
     switch (command) {
         case 'status':
-            runStatus(config);
+            await runStatus(config);
             break;
         case 'list':
-            runList(config);
+            await runList(config);
             break;
         case 'detail':
             await runDetail(config);