@karmaniverous/jeeves-meta 0.3.3 → 0.4.0

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

@@ -0,0 +1,3799 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { readFileSync, readdirSync, unlinkSync, mkdirSync, writeFileSync, existsSync, copyFileSync, watchFile } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { z } from 'zod';
+import { createHash, randomUUID } from 'node:crypto';
+import pino from 'pino';
+import { Cron } from 'croner';
+import Fastify from 'fastify';
+
+/**
+ * Zod schema for jeeves-meta service configuration.
+ *
+ * The service config is a strict superset of the core (library-compatible) meta config.
+ *
+ * @module schema/config
+ */
+/** Zod schema for the core (library-compatible) meta configuration. */
+const metaConfigSchema = z.object({
+    /** Watcher service base URL. */
+    watcherUrl: z.url(),
+    /** OpenClaw gateway base URL for subprocess spawning. */
+    gatewayUrl: z.url().default('http://127.0.0.1:18789'),
+    /** Optional API key for gateway authentication. */
+    gatewayApiKey: z.string().optional(),
+    /** Run architect every N cycles (per meta). */
+    architectEvery: z.number().int().min(1).default(10),
+    /** Exponent for depth weighting in staleness formula. */
+    depthWeight: z.number().min(0).default(0.5),
+    /** Maximum archive snapshots to retain per meta. */
+    maxArchive: z.number().int().min(1).default(20),
+    /** Maximum lines of context to include in subprocess prompts. */
+    maxLines: z.number().int().min(50).default(500),
+    /** Architect subprocess timeout in seconds. */
+    architectTimeout: z.number().int().min(30).default(120),
+    /** Builder subprocess timeout in seconds. */
+    builderTimeout: z.number().int().min(60).default(600),
+    /** Critic subprocess timeout in seconds. */
+    criticTimeout: z.number().int().min(30).default(300),
+    /** Thinking level for spawned synthesis sessions. */
+    thinking: z.string().default('low'),
+    /** Resolved architect system prompt text. */
+    defaultArchitect: z.string(),
+    /** Resolved critic system prompt text. */
+    defaultCritic: z.string(),
+    /** Skip unchanged candidates, bump _generatedAt. */
+    skipUnchanged: z.boolean().default(true),
+    /** Watcher metadata properties applied to live .meta/meta.json files. */
+    metaProperty: z.record(z.string(), z.unknown()).default({ _meta: 'current' }),
+    /** Watcher metadata properties applied to archive snapshots. */
+    metaArchiveProperty: z
+        .record(z.string(), z.unknown())
+        .default({ _meta: 'archive' }),
+});
+/** Zod schema for logging configuration. */
+const loggingSchema = z.object({
+    /** Log level. */
+    level: z.string().default('info'),
+    /** Optional file path for log output. */
+    file: z.string().optional(),
+});
+/** Zod schema for jeeves-meta service configuration (superset of MetaConfig). */
+const serviceConfigSchema = metaConfigSchema.extend({
+    /** HTTP port for the service (default: 1938). */
+    port: z.number().int().min(1).max(65535).default(1938),
+    /** Cron schedule for synthesis cycles (default: every 30 min). */
+    schedule: z.string().default('*/30 * * * *'),
+    /** Optional channel identifier for reporting. */
+    reportChannel: z.string().optional(),
+    /** Logging configuration. */
+    logging: loggingSchema.default(() => loggingSchema.parse({})),
+});
+
+/**
+ * Load and resolve jeeves-meta service config.
+ *
+ * Supports \@file: indirection and environment-variable substitution (dollar-brace pattern).
+ *
+ * @module configLoader
+ */
+/**
+ * Deep-walk a value, replacing `\${VAR\}` patterns with process.env values.
+ *
+ * @param value - Arbitrary JSON-compatible value.
+ * @returns Value with env-var placeholders resolved.
+ */
+function substituteEnvVars(value) {
+    if (typeof value === 'string') {
+        return value.replace(/\$\{([^}]+)\}/g, (_match, name) => {
+            const envVal = process.env[name];
+            if (envVal === undefined) {
+                throw new Error(`Environment variable ${name} is not set`);
+            }
+            return envVal;
+        });
+    }
+    if (Array.isArray(value)) {
+        return value.map(substituteEnvVars);
+    }
+    if (value !== null && typeof value === 'object') {
+        const result = {};
+        for (const [key, val] of Object.entries(value)) {
+            result[key] = substituteEnvVars(val);
+        }
+        return result;
+    }
+    return value;
+}
+/**
+ * Resolve \@file: references in a config value.
+ *
+ * @param value - String value that may start with "\@file:".
+ * @param baseDir - Base directory for resolving relative paths.
+ * @returns The resolved string (file contents or original value).
+ */
+function resolveFileRef(value, baseDir) {
+    if (!value.startsWith('@file:'))
+        return value;
+    const filePath = join(baseDir, value.slice(6));
+    return readFileSync(filePath, 'utf8');
+}
+/**
+ * Resolve config path from --config flag or JEEVES_META_CONFIG env var.
+ *
+ * @param args - CLI arguments (process.argv.slice(2)).
+ * @returns Resolved config path.
+ * @throws If no config path found.
+ */
+function resolveConfigPath(args) {
+    let configIdx = args.indexOf('--config');
+    if (configIdx === -1)
+        configIdx = args.indexOf('-c');
+    if (configIdx !== -1 && args[configIdx + 1]) {
+        return args[configIdx + 1];
+    }
+    const envPath = process.env['JEEVES_META_CONFIG'];
+    if (envPath)
+        return envPath;
+    throw new Error('Config path required. Use --config <path> or set JEEVES_META_CONFIG env var.');
+}
+/**
+ * Load service config from a JSON file.
+ *
+ * Resolves \@file: references for defaultArchitect and defaultCritic,
+ * and substitutes environment-variable placeholders throughout.
+ *
+ * @param configPath - Path to config JSON file.
+ * @returns Validated ServiceConfig.
+ */
+function loadServiceConfig(configPath) {
+    const rawText = readFileSync(configPath, 'utf8');
+    const raw = substituteEnvVars(JSON.parse(rawText));
+    const baseDir = dirname(configPath);
+    if (typeof raw['defaultArchitect'] === 'string') {
+        raw['defaultArchitect'] = resolveFileRef(raw['defaultArchitect'], baseDir);
+    }
+    if (typeof raw['defaultCritic'] === 'string') {
+        raw['defaultCritic'] = resolveFileRef(raw['defaultCritic'], baseDir);
+    }
+    return serviceConfigSchema.parse(raw);
+}
+
+var configLoader = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    loadServiceConfig: loadServiceConfig,
+    resolveConfigPath: resolveConfigPath
+});
+
+/**
+ * List archive snapshot files in chronological order.
+ *
+ * @module archive/listArchive
+ */
+/**
+ * List archive .json files sorted chronologically (oldest first).
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @returns Array of absolute paths to archive files, or empty if none.
+ */
+function listArchiveFiles(metaPath) {
+    const archiveDir = join(metaPath, 'archive');
+    try {
+        return readdirSync(archiveDir)
+            .filter((f) => f.endsWith('.json'))
+            .sort()
+            .map((f) => join(archiveDir, f));
+    }
+    catch {
+        return [];
+    }
+}
+
+/**
+ * Prune old archive snapshots beyond maxArchive.
+ *
+ * @module archive/prune
+ */
+/**
+ * Prune archive directory to keep at most maxArchive snapshots.
+ * Removes the oldest files.
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @param maxArchive - Maximum snapshots to retain.
+ * @returns Number of files pruned.
+ */
+function pruneArchive(metaPath, maxArchive) {
+    const files = listArchiveFiles(metaPath);
+    const toRemove = files.length - maxArchive;
+    if (toRemove <= 0)
+        return 0;
+    for (let i = 0; i < toRemove; i++) {
+        unlinkSync(files[i]);
+    }
+    return toRemove;
+}
+
+/**
+ * Read the latest archive snapshot for steer change detection.
+ *
+ * @module archive/readLatest
+ */
+/**
+ * Read the most recent archive snapshot.
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @returns The latest archived meta, or null if no archives exist.
+ */
+function readLatestArchive(metaPath) {
+    const files = listArchiveFiles(metaPath);
+    if (files.length === 0)
+        return null;
+    const raw = readFileSync(files[files.length - 1], 'utf8');
+    return JSON.parse(raw);
+}
+
+/**
+ * Create archive snapshots of meta.json.
+ *
+ * Copies current meta.json to archive/\{ISO-timestamp\}.json with
+ * _archived: true and _archivedAt added.
+ *
+ * @module archive/snapshot
+ */
+/**
+ * Create an archive snapshot of the current meta.json.
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @param meta - Current meta.json content.
+ * @returns The archive file path.
+ */
+function createSnapshot(metaPath, meta) {
+    const archiveDir = join(metaPath, 'archive');
+    mkdirSync(archiveDir, { recursive: true });
+    const now = new Date().toISOString().replace(/[:.]/g, '-');
+    const archiveFile = join(archiveDir, now + '.json');
+    const archived = {
+        ...meta,
+        _archived: true,
+        _archivedAt: new Date().toISOString(),
+    };
+    writeFileSync(archiveFile, JSON.stringify(archived, null, 2) + '\n');
+    return archiveFile;
+}
+
+/**
+ * Normalize file paths to forward slashes for consistency with watcher-indexed paths.
+ *
+ * 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 normalizePath
+ */
+/**
+ * Normalize a file path to forward slashes.
+ *
+ * @param p - File path (may contain backslashes).
+ * @returns Path with all backslashes replaced by forward slashes.
+ */
+function normalizePath(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 single Qdrant filter clause from a key-value pair.
+ *
+ * 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.
+ *
+ * @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.
+ * @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 .meta/ directory path (handles multi-chunk files)
+    const seen = new Set();
+    const metaPaths = [];
+    for (const sf of scanFiles) {
+        const fp = normalizePath(sf.file_path);
+        // Derive .meta/ directory from file_path (strip /meta.json)
+        const metaPath = fp.replace(/\/meta\.json$/, '');
+        if (seen.has(metaPath))
+            continue;
+        seen.add(metaPath);
+        metaPaths.push(metaPath);
+    }
+    return metaPaths;
+}
+
+/**
+ * File-system lock for preventing concurrent synthesis on the same meta.
+ *
+ * Lock file: .meta/.lock containing `_lockPid` + `_lockStartedAt` (underscore-prefixed
+ * reserved keys, consistent with meta.json conventions).
+ * Stale timeout: 30 minutes.
+ *
+ * @module lock
+ */
+const LOCK_FILE = '.lock';
+/**
+ * Resolve a path to a .meta directory.
+ *
+ * If the path already ends with '.meta', returns it as-is.
+ * Otherwise, appends '.meta' as a subdirectory.
+ *
+ * @param inputPath - Path that may or may not end with '.meta'.
+ * @returns The resolved .meta directory path.
+ */
+function resolveMetaDir(inputPath) {
+    return inputPath.endsWith('.meta') ? inputPath : join(inputPath, '.meta');
+}
+const STALE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+/**
+ * Read and classify the state of a .meta/.lock file.
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @returns Parsed lock state.
+ */
+function readLockState(metaPath) {
+    const lockPath = join(metaPath, LOCK_FILE);
+    if (!existsSync(lockPath)) {
+        return { exists: false, staged: false, active: false, data: null };
+    }
+    try {
+        const raw = readFileSync(lockPath, 'utf8');
+        const data = JSON.parse(raw);
+        if ('_id' in data) {
+            return { exists: true, staged: true, active: false, data };
+        }
+        const startedAt = data._lockStartedAt;
+        if (startedAt) {
+            const lockAge = Date.now() - new Date(startedAt).getTime();
+            return {
+                exists: true,
+                staged: false,
+                active: lockAge < STALE_TIMEOUT_MS,
+                data,
+            };
+        }
+        return { exists: true, staged: false, active: false, data };
+    }
+    catch {
+        return { exists: true, staged: false, active: false, data: null };
+    }
+}
+/**
+ * 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 state = readLockState(metaPath);
+    // Active non-stale lock — cannot acquire
+    if (state.active)
+        return false;
+    // Staged, stale, corrupt, or missing — safe to (over)write
+    const lockPath = join(metaPath, LOCK_FILE);
+    const lock = {
+        _lockPid: process.pid,
+        _lockStartedAt: 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) {
+    return readLockState(metaPath).active;
+}
+/**
+ * Clean up stale lock files on startup.
+ *
+ * For each .meta directory found via the provided paths:
+ * - If lock contains PID-only data (synthesis incomplete), delete it.
+ * - If lock contains staged result (_id present), log warning and delete.
+ *
+ * @param metaPaths - Array of .meta directory paths to check.
+ * @param logger - Optional logger for warnings.
+ */
+function cleanupStaleLocks(metaPaths, logger) {
+    for (const metaPath of metaPaths) {
+        const state = readLockState(metaPath);
+        if (!state.exists)
+            continue;
+        const lockPath = join(metaPath, LOCK_FILE);
+        if (state.staged) {
+            logger?.warn({ metaPath }, 'Found staged synthesis result in lock file from previous crash — deleting (conservative: not auto-finalizing)');
+        }
+        else {
+            logger?.warn({ metaPath }, 'Found stale lock file from previous crash — deleting');
+        }
+        try {
+            unlinkSync(lockPath);
+        }
+        catch {
+            // Already gone
+        }
+    }
+}
+
+/**
+ * Build the ownership tree from discovered .meta/ paths.
+ *
+ * Each .meta/ directory owns its parent directory and all descendants,
+ * except subtrees that contain their own .meta/. For those subtrees,
+ * the parent meta consumes the child meta's synthesis output.
+ *
+ * @module discovery/ownershipTree
+ */
+/**
+ * Build an ownership tree from an array of .meta/ directory paths.
+ *
+ * @param metaPaths - Absolute paths to .meta/ directories.
+ * @returns The ownership tree with parent/child relationships.
+ */
+function buildOwnershipTree(metaPaths) {
+    const nodes = new Map();
+    // Create nodes, sorted by ownerPath length (shortest first = shallowest)
+    const sorted = [...metaPaths]
+        .map((mp) => ({
+        metaPath: normalizePath(mp),
+        ownerPath: normalizePath(dirname(mp)),
+    }))
+        .sort((a, b) => a.ownerPath.length - b.ownerPath.length);
+    for (const { metaPath, ownerPath } of sorted) {
+        nodes.set(metaPath, {
+            metaPath,
+            ownerPath,
+            treeDepth: 0,
+            children: [],
+            parent: null,
+        });
+    }
+    const roots = [];
+    // For each node, find its closest ancestor meta
+    for (const node of nodes.values()) {
+        let bestParent = null;
+        let bestParentLen = -1;
+        for (const candidate of nodes.values()) {
+            if (candidate === node)
+                continue;
+            // Check if node's ownerPath is under candidate's ownerPath
+            const rel = relative(candidate.ownerPath, node.ownerPath);
+            if (rel.startsWith('..') || rel === '')
+                continue;
+            // candidate.ownerPath is an ancestor of node.ownerPath
+            if (candidate.ownerPath.length > bestParentLen) {
+                bestParent = candidate;
+                bestParentLen = candidate.ownerPath.length;
+            }
+        }
+        if (bestParent) {
+            node.parent = bestParent;
+            node.treeDepth = bestParent.treeDepth + 1;
+            bestParent.children.push(node);
+        }
+        else {
+            roots.push(node);
+        }
+    }
+    return { nodes, roots };
+}
+/**
+ * Find a node in the ownership tree by meta path or owner path.
+ *
+ * @param tree - The ownership tree to search.
+ * @param targetPath - Path to search for (meta path or owner path).
+ * @returns The matching node, or undefined if not found.
+ */
+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(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.
+ *
+ * A meta owns: parent dir + all descendants, minus child .meta/ subtrees.
+ * For child subtrees, it consumes the child's .meta/meta.json as a rollup input.
+ *
+ * @module discovery/scope
+ */
+/**
+ * Get the scope path prefix for a meta node.
+ *
+ * This is the ownerPath — all files under this path are in scope,
+ * except subtrees owned by child metas.
+ *
+ * @param node - The meta node to compute scope for.
+ * @returns The scope path prefix.
+ */
+function getScopePrefix(node) {
+    return node.ownerPath;
+}
+/**
+ * Filter a list of file paths to only those in scope for a meta node.
+ *
+ * Includes files under ownerPath, excludes files under child meta ownerPaths,
+ * but includes child .meta/meta.json files as rollup inputs.
+ *
+ * @param node - The meta node.
+ * @param files - Array of file paths to filter.
+ * @returns Filtered array of in-scope file paths.
+ */
+function filterInScope(node, files) {
+    const prefix = node.ownerPath + '/';
+    const exclusions = node.children.map((c) => c.ownerPath + '/');
+    const childMetaJsons = new Set(node.children.map((c) => c.metaPath + '/meta.json'));
+    return files.filter((f) => {
+        const normalized = f.split('\\').join('/');
+        // Must be under ownerPath
+        if (!normalized.startsWith(prefix) && normalized !== node.ownerPath)
+            return false;
+        // Check if under a child meta's subtree
+        for (const excl of exclusions) {
+            if (normalized.startsWith(excl)) {
+                // Exception: child meta.json files are included as rollup inputs
+                return childMetaJsons.has(normalized);
+            }
+        }
+        return true;
+    });
+}
+/**
+ * Get all files in scope for a meta node via watcher scan.
+ *
+ * Scans the owner path prefix and filters out child meta subtrees,
+ * keeping only files directly owned by this meta.
+ *
+ * @param node - The meta node.
+ * @param watcher - WatcherClient for scan queries.
+ * @returns Array of in-scope file paths.
+ */
+async function getScopeFiles(node, watcher) {
+    const allScanFiles = await paginatedScan(watcher, {
+        pathPrefix: node.ownerPath,
+    });
+    const allFiles = allScanFiles.map((f) => f.file_path);
+    return {
+        scopeFiles: filterInScope(node, allFiles),
+        allFiles,
+    };
+}
+/**
+ * Get files modified since a given timestamp within a meta node's scope.
+ *
+ * If no generatedAt is provided (first run), returns all scope files.
+ *
+ * @param node - The meta node.
+ * @param watcher - WatcherClient for scan queries.
+ * @param generatedAt - ISO timestamp of last synthesis, or null/undefined for first run.
+ * @param scopeFiles - Pre-computed scope files (used as fallback for first run).
+ * @returns Array of modified in-scope file paths.
+ */
+async function getDeltaFiles(node, watcher, generatedAt, scopeFiles) {
+    if (!generatedAt)
+        return scopeFiles;
+    const modifiedAfter = Math.floor(new Date(generatedAt).getTime() / 1000);
+    const deltaScanFiles = await paginatedScan(watcher, {
+        pathPrefix: node.ownerPath,
+        modifiedAfter,
+    });
+    return filterInScope(node, deltaScanFiles.map((f) => f.file_path));
+}
+
+/**
+ * Exponential moving average helper for token tracking.
+ *
+ * @module ema
+ */
+const DEFAULT_DECAY = 0.3;
+/**
+ * Compute exponential moving average.
+ *
+ * @param current - New observation.
+ * @param previous - Previous EMA value, or undefined for first observation.
+ * @param decay - Decay factor (0-1). Higher = more weight on new value. Default 0.3.
+ * @returns Updated EMA.
+ */
+function computeEma(current, previous, decay = DEFAULT_DECAY) {
+    if (previous === undefined)
+        return current;
+    return decay * current + (1 - decay) * previous;
+}
+
+/**
+ * Shared error utilities.
+ *
+ * @module errors
+ */
+/**
+ * Wrap an unknown caught value into a MetaError.
+ *
+ * @param step - Which synthesis step failed.
+ * @param err - The caught error value.
+ * @param code - Error classification code.
+ * @returns A structured MetaError.
+ */
+function toMetaError(step, err, code = 'FAILED') {
+    return {
+        step,
+        code,
+        message: err instanceof Error ? err.message : String(err),
+    };
+}
+
+/**
+ * Compute a structure hash from a sorted file listing.
+ *
+ * Used to detect when directory structure changes, triggering
+ * an architect re-run.
+ *
+ * @module structureHash
+ */
+/**
+ * Compute a SHA-256 hash of a sorted file listing.
+ *
+ * @param filePaths - Array of file paths in scope.
+ * @returns Hex-encoded SHA-256 hash of the sorted, newline-joined paths.
+ */
+function computeStructureHash(filePaths) {
+    const sorted = [...filePaths].sort();
+    const content = sorted.join('\n');
+    return createHash('sha256').update(content).digest('hex');
+}
+
+/** Sleep for a given number of milliseconds. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * MetaExecutor 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's `/tools/invoke` endpoint,
+ * polls for completion, and extracts output text.
+ *
+ * @module executor/GatewayExecutor
+ */
+const DEFAULT_POLL_INTERVAL_MS = 5000;
+const DEFAULT_TIMEOUT_MS = 600_000; // 10 minutes
+/**
+ * MetaExecutor that spawns OpenClaw sessions via the gateway's
+ * `/tools/invoke` endpoint.
+ *
+ * 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 `MetaConfig`.
+ */
+class GatewayExecutor {
+    gatewayUrl;
+    apiKey;
+    pollIntervalMs;
+    constructor(options = {}) {
+        this.gatewayUrl = (options.gatewayUrl ?? 'http://127.0.0.1:18789').replace(/\/+$/, '');
+        this.apiKey = options.apiKey;
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    }
+    /** Invoke a gateway tool via the /tools/invoke HTTP endpoint. */
+    async invoke(tool, args) {
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (this.apiKey) {
+            headers['Authorization'] = 'Bearer ' + this.apiKey;
+        }
+        const res = await fetch(this.gatewayUrl + '/tools/invoke', {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ tool, args }),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`Gateway ${tool} failed: HTTP ${res.status.toString()} - ${text}`);
+        }
+        const data = (await res.json());
+        if (data.ok === false || data.error) {
+            throw new Error(`Gateway ${tool} error: ${data.error?.message ?? JSON.stringify(data)}`);
+        }
+        return data;
+    }
+    async spawn(task, options) {
+        const timeoutSeconds = options?.timeout ?? DEFAULT_TIMEOUT_MS / 1000;
+        const timeoutMs = timeoutSeconds * 1000;
+        const deadline = Date.now() + timeoutMs;
+        // Step 1: Spawn the sub-agent session
+        const spawnResult = await this.invoke('sessions_spawn', {
+            task,
+            label: options?.label ?? 'jeeves-meta-synthesis',
+            runTimeoutSeconds: timeoutSeconds,
+            ...(options?.thinking ? { thinking: options.thinking } : {}),
+            ...(options?.model ? { model: options.model } : {}),
+        });
+        const details = (spawnResult.result?.details ?? spawnResult.result);
+        const sessionKey = details?.childSessionKey ?? details?.sessionKey;
+        if (typeof sessionKey !== 'string' || !sessionKey) {
+            throw new Error('Gateway sessions_spawn returned no sessionKey: ' +
+                JSON.stringify(spawnResult));
+        }
+        // Step 2: Poll for completion via sessions_history
+        await sleep(3000);
+        while (Date.now() < deadline) {
+            try {
+                const historyResult = await this.invoke('sessions_history', {
+                    sessionKey,
+                    limit: 5,
+                    includeTools: false,
+                });
+                const messages = historyResult.result?.details?.messages ??
+                    historyResult.result?.messages ??
+                    [];
+                const msgArray = messages;
+                if (msgArray.length > 0) {
+                    const lastMsg = msgArray[msgArray.length - 1];
+                    // Complete when last message is assistant with a terminal stop reason
+                    if (lastMsg.role === 'assistant' &&
+                        lastMsg.stopReason &&
+                        lastMsg.stopReason !== 'toolUse' &&
+                        lastMsg.stopReason !== 'error') {
+                        // Sum token usage from all messages
+                        let tokens;
+                        let sum = 0;
+                        for (const msg of msgArray) {
+                            if (msg.usage?.totalTokens)
+                                sum += msg.usage.totalTokens;
+                        }
+                        if (sum > 0)
+                            tokens = sum;
+                        // Find the last assistant message with content
+                        for (let i = msgArray.length - 1; i >= 0; i--) {
+                            if (msgArray[i].role === 'assistant' && msgArray[i].content) {
+                                return { output: msgArray[i].content, tokens };
+                            }
+                        }
+                        return { output: '', tokens };
+                    }
+                }
+            }
+            catch {
+                // Transient poll failure — keep trying
+            }
+            await sleep(this.pollIntervalMs);
+        }
+        throw new Error('Synthesis subprocess timed out after ' + timeoutMs.toString() + 'ms');
+    }
+}
+
+/**
+ * Pino logger factory.
+ *
+ * @module logger
+ */
+/**
+ * Create a pino logger instance.
+ *
+ * @param config - Optional logger configuration.
+ * @returns Configured pino logger.
+ */
+function createLogger(config) {
+    const level = config?.level ?? 'info';
+    if (config?.file) {
+        const transport = pino.transport({
+            target: 'pino/file',
+            options: { destination: config.file, mkdir: true },
+        });
+        return pino({ level }, transport);
+    }
+    return pino({ level });
+}
+
+/**
+ * Build the MetaContext for a synthesis cycle.
+ *
+ * Computes shared inputs once: scope files, delta files, child meta outputs,
+ * previous content/feedback, steer, and archive paths.
+ *
+ * @module orchestrator/contextPackage
+ */
+/**
+ * Condense a file list into glob-like summaries.
+ * Groups by directory + extension pattern.
+ *
+ * @param files - Array of file paths.
+ * @param maxIndividual - Show individual files up to this count.
+ * @returns Condensed summary string.
+ */
+function condenseScopeFiles(files, maxIndividual = 30) {
+    if (files.length <= maxIndividual)
+        return files.join('\n');
+    // Group by dir + extension
+    const groups = new Map();
+    for (const f of files) {
+        const dir = f.substring(0, f.lastIndexOf('/') + 1) || './';
+        const ext = f.includes('.') ? f.substring(f.lastIndexOf('.')) : '(no ext)';
+        const key = dir + '*' + ext;
+        groups.set(key, (groups.get(key) ?? 0) + 1);
+    }
+    // Sort by count descending
+    const sorted = [...groups.entries()].sort((a, b) => b[1] - a[1]);
+    return sorted
+        .map(([pattern, count]) => pattern + ' (' + count.toString() + ' files)')
+        .join('\n');
+}
+/**
+ * Build the context package for a synthesis cycle.
+ *
+ * @param node - The meta node being synthesized.
+ * @param meta - Current meta.json content.
+ * @param watcher - WatcherClient for scope enumeration.
+ * @returns The computed context package.
+ */
+async function buildContextPackage(node, meta, watcher) {
+    // Scope and delta files via watcher scan
+    const { scopeFiles } = await getScopeFiles(node, watcher);
+    const deltaFiles = await getDeltaFiles(node, watcher, meta._generatedAt, scopeFiles);
+    // Child meta outputs
+    const childMetas = {};
+    for (const child of node.children) {
+        const childMetaFile = join(child.metaPath, 'meta.json');
+        try {
+            const raw = readFileSync(childMetaFile, 'utf8');
+            const childMeta = JSON.parse(raw);
+            childMetas[child.ownerPath] = childMeta._content ?? null;
+        }
+        catch {
+            childMetas[child.ownerPath] = null;
+        }
+    }
+    // Archive paths
+    const archives = listArchiveFiles(node.metaPath);
+    return {
+        path: node.metaPath,
+        scopeFiles,
+        deltaFiles,
+        childMetas,
+        previousContent: meta._content ?? null,
+        previousFeedback: meta._feedback ?? null,
+        steer: meta._steer ?? null,
+        archives,
+    };
+}
+
+/**
+ * Build task prompts for each synthesis step.
+ *
+ * @module orchestrator/buildTask
+ */
+/** Append optional context sections shared across all step prompts. */
+function appendSharedSections(sections, ctx, options) {
+    const opts = {
+        includeSteer: true,
+        includePreviousContent: true,
+        includePreviousFeedback: true,
+        feedbackHeading: '## PREVIOUS FEEDBACK',
+        includeChildMetas: true,
+        ...options,
+    };
+    if (opts.includeSteer && ctx.steer) {
+        sections.push('', '## STEERING PROMPT', ctx.steer);
+    }
+    if (opts.includePreviousContent && ctx.previousContent) {
+        sections.push('', '## PREVIOUS SYNTHESIS', ctx.previousContent);
+    }
+    if (opts.includePreviousFeedback && ctx.previousFeedback) {
+        sections.push('', opts.feedbackHeading, ctx.previousFeedback);
+    }
+    if (opts.includeChildMetas && Object.keys(ctx.childMetas).length > 0) {
+        sections.push('', '## CHILD META OUTPUTS');
+        for (const [childPath, content] of Object.entries(ctx.childMetas)) {
+            sections.push(`### ${childPath}`, typeof content === 'string' ? content : '(not yet synthesized)');
+        }
+    }
+}
+/**
+ * Build the architect task prompt.
+ *
+ * @param ctx - Synthesis context.
+ * @param meta - Current meta.json.
+ * @param config - Synthesis config.
+ * @returns The architect task prompt string.
+ */
+function buildArchitectTask(ctx, meta, config) {
+    const sections = [
+        meta._architect ?? config.defaultArchitect,
+        '',
+        '## SCOPE',
+        `Path: ${ctx.path}`,
+        `Total files in scope: ${ctx.scopeFiles.length.toString()}`,
+        `Files changed since last synthesis: ${ctx.deltaFiles.length.toString()}`,
+        '',
+        '### File listing (scope)',
+        condenseScopeFiles(ctx.scopeFiles),
+    ];
+    // Inject previous _builder so architect can see its own prior output
+    if (meta._builder) {
+        sections.push('', '## PREVIOUS TASK BRIEF', meta._builder);
+    }
+    appendSharedSections(sections, ctx);
+    if (ctx.archives.length > 0) {
+        sections.push('', '## ARCHIVE HISTORY', `${ctx.archives.length.toString()} previous synthesis snapshots available in .meta/archive/.`, 'Review these to understand how the synthesis has evolved over time.');
+    }
+    return sections.join('\n');
+}
+/**
+ * Build the builder task prompt.
+ *
+ * @param ctx - Synthesis context.
+ * @param meta - Current meta.json.
+ * @param config - Synthesis config.
+ * @returns The builder task prompt string.
+ */
+function buildBuilderTask(ctx, meta, config) {
+    const sections = [
+        '## TASK BRIEF (from Architect)',
+        meta._builder ?? '(No architect brief available)',
+        '',
+        '## SCOPE',
+        `Path: ${ctx.path}`,
+        `Delta files (${ctx.deltaFiles.length.toString()} changed):`,
+        ...ctx.deltaFiles.slice(0, config.maxLines).map((f) => `- ${f}`),
+    ];
+    appendSharedSections(sections, ctx, {
+        includeSteer: false,
+        feedbackHeading: '## FEEDBACK FROM CRITIC',
+    });
+    sections.push('', '## OUTPUT FORMAT', 'Return a JSON object with:', '- "_content": Markdown narrative synthesis (required)', '- Any additional structured fields as non-underscore keys');
+    return sections.join('\n');
+}
+/**
+ * Build the critic task prompt.
+ *
+ * @param ctx - Synthesis context.
+ * @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');
+}
+
+/**
+ * Structured error from a synthesis step failure.
+ *
+ * @module schema/error
+ */
+/** Zod schema for synthesis step errors. */
+const metaErrorSchema = z.object({
+    /** Which step failed: 'architect', 'builder', or 'critic'. */
+    step: z.enum(['architect', 'builder', 'critic']),
+    /** Error classification code. */
+    code: z.string(),
+    /** Human-readable error message. */
+    message: z.string(),
+});
+
+/**
+ * Zod schema for .meta/meta.json files.
+ *
+ * Reserved properties are underscore-prefixed and engine-managed.
+ * All other keys are open schema (builder output).
+ *
+ * @module schema/meta
+ */
+/** Zod schema for the reserved (underscore-prefixed) meta.json properties. */
+const metaJsonSchema = z
+    .object({
+    /** Stable identity. Generated on first synthesis, never changes. */
+    _id: z.uuid(),
+    /** Human-provided steering prompt. Optional. */
+    _steer: z.string().optional(),
+    /** Architect system prompt used this turn. Defaults from config. */
+    _architect: z.string().optional(),
+    /**
+     * Task brief generated by the architect. Cached and reused across cycles;
+     * regenerated only when triggered.
+     */
+    _builder: z.string().optional(),
+    /** Critic system prompt used this turn. Defaults from config. */
+    _critic: z.string().optional(),
+    /** Timestamp of last synthesis. ISO 8601. */
+    _generatedAt: z.iso.datetime().optional(),
+    /** Narrative synthesis output. Rendered by watcher for embedding. */
+    _content: z.string().optional(),
+    /**
+     * Hash of sorted file listing in scope. Detects directory structure
+     * changes that trigger an architect re-run.
+     */
+    _structureHash: z.string().optional(),
+    /**
+     * Cycles since last architect run. Reset to 0 when architect runs.
+     * Used with architectEvery to trigger periodic re-prompting.
+     */
+    _synthesisCount: z.number().int().min(0).optional(),
+    /** Critic evaluation of the last synthesis. */
+    _feedback: z.string().optional(),
+    /**
+     * Present and true on archive snapshots. Distinguishes live vs. archived
+     * metas.
+     */
+    _archived: z.boolean().optional(),
+    /** Timestamp when this snapshot was archived. ISO 8601. */
+    _archivedAt: z.iso.datetime().optional(),
+    /**
+     * Scheduling priority. Higher = updates more often. Negative allowed;
+     * normalized to min 0 at scheduling time.
+     */
+    _depth: z.number().optional(),
+    /**
+     * Emphasis multiplier for depth weighting in scheduling.
+     * Default 1. Higher values increase this meta's scheduling priority
+     * relative to its depth. Set to 0.5 to halve the depth effect,
+     * 2 to double it, 0 to ignore depth entirely for this meta.
+     */
+    _emphasis: z.number().min(0).optional(),
+    /** Token count from last architect subprocess call. */
+    _architectTokens: z.number().int().optional(),
+    /** Token count from last builder subprocess call. */
+    _builderTokens: z.number().int().optional(),
+    /** Token count from last critic subprocess call. */
+    _criticTokens: z.number().int().optional(),
+    /** Exponential moving average of architect token usage (decay 0.3). */
+    _architectTokensAvg: z.number().optional(),
+    /** Exponential moving average of builder token usage (decay 0.3). */
+    _builderTokensAvg: z.number().optional(),
+    /** Exponential moving average of critic token usage (decay 0.3). */
+    _criticTokensAvg: z.number().optional(),
+    /**
+     * Structured error from last cycle. Present when a step failed.
+     * Cleared on successful cycle.
+     */
+    _error: metaErrorSchema.optional(),
+})
+    .loose();
+
+/**
+ * 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 to specified path (lock staging) or default meta.json
+    const filePath = options.outputPath ?? join(options.metaPath, 'meta.json');
+    writeFileSync(filePath, JSON.stringify(result.data, null, 2) + '\n');
+    return result.data;
+}
+
+/**
+ * Weighted staleness formula for candidate selection.
+ *
+ * effectiveStaleness = actualStaleness * (normalizedDepth + 1) ^ (depthWeight * emphasis)
+ *
+ * @module scheduling/weightedFormula
+ */
+/**
+ * Compute effective staleness for a set of candidates.
+ *
+ * Normalizes depths so the minimum becomes 0, then applies the formula:
+ * effectiveStaleness = actualStaleness * (normalizedDepth + 1) ^ (depthWeight * emphasis)
+ *
+ * Per-meta _emphasis (default 1) multiplies depthWeight, allowing individual
+ * metas to tune how much their tree position affects scheduling.
+ *
+ * @param candidates - Array of \{ node, meta, actualStaleness \}.
+ * @param depthWeight - Exponent for depth weighting (0 = pure staleness).
+ * @returns Same array with effectiveStaleness computed.
+ */
+function computeEffectiveStaleness(candidates, depthWeight) {
+    if (candidates.length === 0)
+        return [];
+    // Get depth for each candidate: use _depth override or tree depth
+    const depths = candidates.map((c) => c.meta._depth ?? c.node.treeDepth);
+    // Normalize: shift so minimum becomes 0
+    const minDepth = Math.min(...depths);
+    const normalizedDepths = depths.map((d) => Math.max(0, d - minDepth));
+    return candidates.map((c, i) => {
+        const emphasis = c.meta._emphasis ?? 1;
+        return {
+            ...c,
+            effectiveStaleness: c.actualStaleness *
+                Math.pow(normalizedDepths[i] + 1, depthWeight * emphasis),
+        };
+    });
+}
+
+/**
+ * Select the best synthesis candidate from stale metas.
+ *
+ * Picks the meta with highest effective staleness.
+ *
+ * @module scheduling/selectCandidate
+ */
+/**
+ * Select the candidate with the highest effective staleness.
+ *
+ * @param candidates - Array of candidates with computed effective staleness.
+ * @returns The winning candidate, or null if no candidates.
+ */
+function selectCandidate(candidates) {
+    if (candidates.length === 0)
+        return null;
+    let best = candidates[0];
+    for (let i = 1; i < candidates.length; i++) {
+        if (candidates[i].effectiveStaleness > best.effectiveStaleness) {
+            best = candidates[i];
+        }
+    }
+    return best;
+}
+/**
+ * Extract stale candidates from a list and return the stalest path.
+ *
+ * Consolidates the repeated pattern of:
+ *   filter → computeEffectiveStaleness → selectCandidate → return path
+ *
+ * @param candidates - Array with node, meta, and stalenessSeconds.
+ * @param depthWeight - Depth weighting exponent from config.
+ * @returns The stalest candidate's metaPath, or null if none are stale.
+ */
+function discoverStalestPath(candidates, depthWeight) {
+    const weighted = computeEffectiveStaleness(candidates, depthWeight);
+    const winner = selectCandidate(weighted);
+    return winner?.node.metaPath ?? null;
+}
+
+/**
+ * Staleness detection via watcher scan.
+ *
+ * A meta is stale when any file in its scope was modified after _generatedAt.
+ *
+ * @module scheduling/staleness
+ */
+/**
+ * Check if a meta is stale by querying the watcher for modified files.
+ *
+ * @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.
+ */
+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 result = await watcher.scan({
+        pathPrefix: scopePrefix,
+        modifiedAfter: generatedAtUnix,
+        limit: 1,
+    });
+    return result.files.length > 0;
+}
+/**
+ * Compute actual staleness in seconds (now minus _generatedAt).
+ *
+ * @param meta - Current meta.json content.
+ * @returns Staleness in seconds, or Infinity if never synthesized.
+ */
+function actualStaleness(meta) {
+    if (!meta._generatedAt)
+        return Infinity;
+    const generatedMs = new Date(meta._generatedAt).getTime();
+    return (Date.now() - generatedMs) / 1000;
+}
+/**
+ * Check whether the architect step should be triggered.
+ *
+ * @param meta - Current meta.json.
+ * @param structureChanged - Whether the structure hash changed.
+ * @param steerChanged - Whether the steer directive changed.
+ * @param architectEvery - Config: run architect every N cycles.
+ * @returns True if the architect step should run.
+ */
+function isArchitectTriggered(meta, structureChanged, steerChanged, architectEvery) {
+    return (!meta._builder ||
+        structureChanged ||
+        steerChanged ||
+        (meta._synthesisCount ?? 0) >= architectEvery);
+}
+/**
+ * Detect whether the steer directive changed since the last archive.
+ *
+ * @param currentSteer - Current _steer value (or undefined).
+ * @param archiveSteer - Archive _steer value (or undefined).
+ * @param hasArchive - Whether an archive snapshot exists.
+ * @returns True if steer changed.
+ */
+function hasSteerChanged(currentSteer, archiveSteer, hasArchive) {
+    if (!hasArchive)
+        return Boolean(currentSteer);
+    return currentSteer !== archiveSteer;
+}
+/**
+ * Compute a normalized staleness score (0–1) for display purposes.
+ *
+ * Uses the same depth/emphasis weighting as candidate selection,
+ * normalized to a 30-day window.
+ *
+ * @param stalenessSeconds - Raw staleness in seconds (null = never synthesized).
+ * @param depth - Meta tree depth.
+ * @param emphasis - Scheduling emphasis multiplier.
+ * @param depthWeight - Depth weighting exponent from config.
+ * @returns Normalized score between 0 and 1.
+ */
+function computeStalenessScore(stalenessSeconds, depth, emphasis, depthWeight) {
+    if (stalenessSeconds === null)
+        return 1;
+    const depthFactor = Math.pow(1 + depthWeight, depth);
+    return Math.min(1, (stalenessSeconds * depthFactor * emphasis) / (30 * 86400));
+}
+
+/**
+ * Parse subprocess outputs for each synthesis step.
+ *
+ * - Architect: returns text \> _builder
+ * - Builder: returns JSON \> _content + structured fields
+ * - Critic: returns text \> _feedback
+ *
+ * @module orchestrator/parseOutput
+ */
+/**
+ * Parse architect output. The architect returns a task brief as text.
+ *
+ * @param output - Raw subprocess output.
+ * @returns The task brief string.
+ */
+function parseArchitectOutput(output) {
+    return output.trim();
+}
+/**
+ * Parse builder output. The builder returns JSON with _content and optional fields.
+ *
+ * Attempts JSON parse first. If that fails, treats the entire output as _content.
+ *
+ * @param output - Raw subprocess output.
+ * @returns Parsed builder output with content and structured fields.
+ */
+function parseBuilderOutput(output) {
+    const trimmed = output.trim();
+    // Try to extract JSON from the output (may be wrapped in markdown code fences)
+    let jsonStr = trimmed;
+    const fenceMatch = /```(?:json)?\s*([\s\S]*?)```/.exec(trimmed);
+    if (fenceMatch) {
+        jsonStr = fenceMatch[1].trim();
+    }
+    try {
+        const parsed = JSON.parse(jsonStr);
+        // Extract _content
+        const content = typeof parsed._content === 'string'
+            ? parsed._content
+            : typeof parsed.content === 'string'
+                ? parsed.content
+                : trimmed;
+        // Extract non-underscore fields
+        const fields = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            if (!key.startsWith('_') && key !== 'content') {
+                fields[key] = value;
+            }
+        }
+        return { content, fields };
+    }
+    catch {
+        // Not valid JSON — treat entire output as content
+        return { content: trimmed, fields: {} };
+    }
+}
+/**
+ * Parse critic output. The critic returns evaluation text.
+ *
+ * @param output - Raw subprocess output.
+ * @returns The feedback string.
+ */
+function parseCriticOutput(output) {
+    return output.trim();
+}
+
+/**
+ * Main orchestration function — the 13-step synthesis cycle.
+ *
+ * Wires together discovery, scheduling, archiving, executor calls,
+ * and merge/write-back.
+ *
+ * @module orchestrator/orchestrate
+ */
+/** Finalize a cycle using lock staging: write to .lock → copy to meta.json + archive → delete .lock. */
+function finalizeCycle(opts) {
+    const lockPath = join(opts.metaPath, '.lock');
+    const metaJsonPath = join(opts.metaPath, 'meta.json');
+    // Stage: write merged result to .lock
+    const updated = mergeAndWrite({
+        metaPath: opts.metaPath,
+        current: opts.current,
+        architect: opts.architect,
+        builder: opts.builder,
+        critic: opts.critic,
+        builderOutput: opts.builderOutput,
+        feedback: opts.feedback,
+        structureHash: opts.structureHash,
+        synthesisCount: opts.synthesisCount,
+        error: opts.error,
+        architectTokens: opts.architectTokens,
+        builderTokens: opts.builderTokens,
+        criticTokens: opts.criticTokens,
+        outputPath: lockPath,
+    });
+    // Commit: copy .lock → meta.json
+    copyFileSync(lockPath, metaJsonPath);
+    // Archive + prune from the committed meta.json
+    createSnapshot(opts.metaPath, updated);
+    pruneArchive(opts.metaPath, opts.config.maxArchive);
+    // .lock is cleaned up by the finally block (releaseLock)
+    return updated;
+}
+/**
+ * Run a single synthesis cycle.
+ *
+ * Discovers all metas, selects the stalest candidate, and runs the
+ * three-step synthesis (architect, builder, critic).
+ *
+ * @param config - Validated synthesis config.
+ * @param executor - Pluggable LLM executor.
+ * @param watcher - Watcher HTTP client.
+ * @returns Result indicating whether synthesis occurred.
+ */
+async function orchestrateOnce(config, executor, watcher, targetPath, onProgress) {
+    // Step 1: Discover via watcher scan
+    const metaPaths = await discoverMetas(config, 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')));
+        }
+        catch {
+            // Skip metas with unreadable meta.json
+            continue;
+        }
+    }
+    // Only build tree from paths with readable meta.json (excludes orphaned/deleted entries)
+    const validPaths = metaPaths.filter((mp) => metas.has(normalizePath(mp)));
+    if (validPaths.length === 0)
+        return { synthesized: false };
+    const tree = buildOwnershipTree(validPaths);
+    // If targetPath specified, skip candidate selection — go directly to that meta
+    let targetNode;
+    if (targetPath) {
+        const normalized = normalizePath(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()) {
+        const meta = metas.get(node.metaPath);
+        if (!meta)
+            continue; // Node not in metas map (e.g. unreadable meta.json)
+        const staleness = actualStaleness(meta);
+        if (staleness > 0) {
+            candidates.push({ node, meta, actualStaleness: staleness });
+        }
+    }
+    const weighted = computeEffectiveStaleness(candidates, config.depthWeight);
+    // Sort by effective staleness descending
+    const ranked = [...weighted].sort((a, b) => b.effectiveStaleness - a.effectiveStaleness);
+    if (ranked.length === 0)
+        return { synthesized: false };
+    // Find the first candidate with actual changes (if skipUnchanged)
+    let winner = null;
+    for (const candidate of ranked) {
+        if (!acquireLock(candidate.node.metaPath))
+            continue;
+        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'));
+            freshMeta._generatedAt = new Date().toISOString();
+            writeFileSync(metaFilePath, JSON.stringify(freshMeta, null, 2));
+            releaseLock(candidate.node.metaPath);
+            if (config.skipUnchanged)
+                continue;
+            return { synthesized: false };
+        }
+        winner = candidate;
+        break;
+    }
+    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 };
+    }
+    try {
+        // Re-read meta after lock (may have changed)
+        const currentMeta = JSON.parse(readFileSync(join(node.metaPath, 'meta.json'), 'utf8'));
+        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 = await buildContextPackage(node, currentMeta, watcher);
+        // Step 5 (deferred): Structure hash from context scope files
+        const newStructureHash = computeStructureHash(ctx.scopeFiles);
+        const structureChanged = newStructureHash !== currentMeta._structureHash;
+        // Step 8: Architect (conditional)
+        const architectTriggered = isArchitectTriggered(currentMeta, structureChanged, steerChanged, config.architectEvery);
+        let builderBrief = currentMeta._builder ?? '';
+        let synthesisCount = currentMeta._synthesisCount ?? 0;
+        let stepError = null;
+        let architectTokens;
+        let builderTokens;
+        let criticTokens;
+        if (architectTriggered) {
+            try {
+                await onProgress?.({
+                    type: 'phase_start',
+                    metaPath: node.metaPath,
+                    phase: 'architect',
+                });
+                const phaseStart = Date.now();
+                const architectTask = buildArchitectTask(ctx, currentMeta, config);
+                const architectResult = await executor.spawn(architectTask, {
+                    thinking: config.thinking,
+                    timeout: config.architectTimeout,
+                });
+                builderBrief = parseArchitectOutput(architectResult.output);
+                architectTokens = architectResult.tokens;
+                synthesisCount = 0;
+                await onProgress?.({
+                    type: 'phase_complete',
+                    metaPath: node.metaPath,
+                    phase: 'architect',
+                    tokens: architectTokens,
+                    durationMs: Date.now() - phaseStart,
+                });
+            }
+            catch (err) {
+                stepError = toMetaError('architect', err);
+                if (!currentMeta._builder) {
+                    // No cached builder — cycle fails
+                    finalizeCycle({
+                        metaPath: node.metaPath,
+                        current: currentMeta,
+                        config,
+                        architect: architectPrompt,
+                        builder: '',
+                        critic: criticPrompt,
+                        builderOutput: null,
+                        feedback: null,
+                        structureHash: newStructureHash,
+                        synthesisCount,
+                        error: stepError,
+                        architectTokens,
+                    });
+                    return {
+                        synthesized: true,
+                        metaPath: node.metaPath,
+                        error: stepError,
+                    };
+                }
+                // Has cached builder — continue with existing
+            }
+        }
+        // Step 9: Builder
+        const metaForBuilder = { ...currentMeta, _builder: builderBrief };
+        let builderOutput = null;
+        try {
+            await onProgress?.({
+                type: 'phase_start',
+                metaPath: node.metaPath,
+                phase: 'builder',
+            });
+            const builderStart = Date.now();
+            const builderTask = buildBuilderTask(ctx, metaForBuilder, config);
+            const builderResult = await executor.spawn(builderTask, {
+                thinking: config.thinking,
+                timeout: config.builderTimeout,
+            });
+            builderOutput = parseBuilderOutput(builderResult.output);
+            builderTokens = builderResult.tokens;
+            synthesisCount++;
+            await onProgress?.({
+                type: 'phase_complete',
+                metaPath: node.metaPath,
+                phase: 'builder',
+                tokens: builderTokens,
+                durationMs: Date.now() - builderStart,
+            });
+        }
+        catch (err) {
+            stepError = toMetaError('builder', err);
+            return { synthesized: true, metaPath: node.metaPath, error: stepError };
+        }
+        // Step 10: Critic
+        const metaForCritic = {
+            ...currentMeta,
+            _content: builderOutput.content,
+        };
+        let feedback = null;
+        try {
+            await onProgress?.({
+                type: 'phase_start',
+                metaPath: node.metaPath,
+                phase: 'critic',
+            });
+            const criticStart = Date.now();
+            const criticTask = buildCriticTask(ctx, metaForCritic, config);
+            const criticResult = await executor.spawn(criticTask, {
+                thinking: config.thinking,
+                timeout: config.criticTimeout,
+            });
+            feedback = parseCriticOutput(criticResult.output);
+            criticTokens = criticResult.tokens;
+            stepError = null; // Clear any architect error on full success
+            await onProgress?.({
+                type: 'phase_complete',
+                metaPath: node.metaPath,
+                phase: 'critic',
+                tokens: criticTokens,
+                durationMs: Date.now() - criticStart,
+            });
+        }
+        catch (err) {
+            stepError = stepError ?? toMetaError('critic', err);
+        }
+        // Steps 11-12: Merge, archive, prune
+        finalizeCycle({
+            metaPath: node.metaPath,
+            current: currentMeta,
+            config,
+            architect: architectPrompt,
+            builder: builderBrief,
+            critic: criticPrompt,
+            builderOutput,
+            feedback,
+            structureHash: newStructureHash,
+            synthesisCount,
+            error: stepError,
+            architectTokens,
+            builderTokens,
+            criticTokens,
+        });
+        return {
+            synthesized: true,
+            metaPath: node.metaPath,
+            error: stepError ?? undefined,
+        };
+    }
+    finally {
+        // Step 13: Release lock
+        releaseLock(node.metaPath);
+    }
+}
+/**
+ * Run a single synthesis cycle.
+ *
+ * Selects the stalest candidate (or a specific target) and runs the
+ * full architect/builder/critic pipeline.
+ *
+ * @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 with a single result.
+ */
+async function orchestrate(config, executor, watcher, targetPath, onProgress) {
+    const result = await orchestrateOnce(config, executor, watcher, targetPath, onProgress);
+    return [result];
+}
+
+/**
+ * Progress reporting via OpenClaw gateway `/tools/invoke` → `message` tool.
+ *
+ * @module progress
+ */
+function formatSeconds(durationMs) {
+    const seconds = durationMs / 1000;
+    return seconds.toFixed(1) + 's';
+}
+function titleCasePhase(phase) {
+    return phase.charAt(0).toUpperCase() + phase.slice(1);
+}
+function formatProgressEvent(event) {
+    switch (event.type) {
+        case 'synthesis_start':
+            return `🔬 Started meta synthesis: ${event.metaPath}`;
+        case 'phase_start': {
+            if (!event.phase) {
+                return `  ⚙️ Phase started: ${event.metaPath}`;
+            }
+            return `  ⚙️ ${titleCasePhase(event.phase)} phase started`;
+        }
+        case 'phase_complete': {
+            const phase = event.phase ? titleCasePhase(event.phase) : 'Phase';
+            const tokens = event.tokens ?? 0;
+            const duration = event.durationMs !== undefined
+                ? formatSeconds(event.durationMs)
+                : '0.0s';
+            return `  ✅ ${phase} phase complete (${String(tokens)} tokens / ${duration})`;
+        }
+        case 'synthesis_complete': {
+            const tokens = event.tokens ?? 0;
+            const duration = event.durationMs !== undefined
+                ? formatSeconds(event.durationMs)
+                : '0.0s';
+            return `✅ Completed: ${event.metaPath} (${String(tokens)} tokens / ${duration})`;
+        }
+        case 'error': {
+            const phase = event.phase ? `${titleCasePhase(event.phase)} ` : '';
+            const error = event.error ?? 'Unknown error';
+            return `❌ Synthesis failed at ${phase}phase: ${event.metaPath}\n   Error: ${error}`;
+        }
+        default: {
+            return 'Unknown progress event';
+        }
+    }
+}
+class ProgressReporter {
+    config;
+    logger;
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger;
+    }
+    async report(event) {
+        const target = this.config.reportChannel;
+        if (!target)
+            return;
+        const message = formatProgressEvent(event);
+        const url = new URL('/tools/invoke', this.config.gatewayUrl);
+        const payload = {
+            tool: 'message',
+            args: {
+                action: 'send',
+                target,
+                message,
+            },
+        };
+        try {
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    ...(this.config.gatewayApiKey
+                        ? { authorization: `Bearer ${this.config.gatewayApiKey}` }
+                        : {}),
+                },
+                body: JSON.stringify(payload),
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                this.logger.warn({ status: res.status, statusText: res.statusText, body: text }, 'Progress reporting failed');
+            }
+        }
+        catch (err) {
+            this.logger.warn({ err }, 'Progress reporting threw');
+        }
+    }
+}
+
+/**
+ * Croner-based scheduler that discovers the stalest meta candidate each tick
+ * and enqueues it for synthesis.
+ *
+ * @module scheduler
+ */
+const MAX_BACKOFF_MULTIPLIER = 4;
+/**
+ * Periodic scheduler that discovers stale meta candidates and enqueues them.
+ *
+ * Supports adaptive backoff when no candidates are found and hot-reloadable
+ * cron expressions via {@link Scheduler.updateSchedule}.
+ */
+class Scheduler {
+    job = null;
+    backoffMultiplier = 1;
+    tickCount = 0;
+    config;
+    queue;
+    logger;
+    watcher;
+    registrar = null;
+    currentExpression;
+    constructor(config, queue, logger, watcher) {
+        this.config = config;
+        this.queue = queue;
+        this.logger = logger;
+        this.watcher = watcher;
+        this.currentExpression = config.schedule;
+    }
+    /** Set the rule registrar for watcher restart detection. */
+    setRegistrar(registrar) {
+        this.registrar = registrar;
+    }
+    /** Start the cron job. */
+    start() {
+        if (this.job)
+            return;
+        this.job = new Cron(this.currentExpression, () => {
+            void this.tick();
+        });
+        this.logger.info({ schedule: this.currentExpression }, 'Scheduler started');
+    }
+    /** Stop the cron job. */
+    stop() {
+        if (!this.job)
+            return;
+        this.job.stop();
+        this.job = null;
+        this.backoffMultiplier = 1;
+        this.logger.info('Scheduler stopped');
+    }
+    /** Hot-reload the cron schedule expression. */
+    updateSchedule(expression) {
+        this.currentExpression = expression;
+        if (this.job) {
+            this.job.stop();
+            this.job = new Cron(expression, () => {
+                void this.tick();
+            });
+            this.logger.info({ schedule: expression }, 'Schedule updated');
+        }
+    }
+    /** Reset backoff multiplier (call after successful synthesis). */
+    resetBackoff() {
+        if (this.backoffMultiplier > 1) {
+            this.logger.debug('Backoff reset after successful synthesis');
+        }
+        this.backoffMultiplier = 1;
+    }
+    /** Whether the scheduler is currently running. */
+    get isRunning() {
+        return this.job !== null;
+    }
+    /** Next scheduled tick time, or null if not running. */
+    get nextRunAt() {
+        if (!this.job)
+            return null;
+        return this.job.nextRun() ?? null;
+    }
+    /**
+     * Single tick: discover stalest candidate and enqueue it.
+     *
+     * Skips if the queue is currently processing. Applies adaptive backoff
+     * when no candidates are found.
+     */
+    async tick() {
+        this.tickCount++;
+        // Apply backoff: skip ticks when backing off
+        if (this.backoffMultiplier > 1 &&
+            this.tickCount % this.backoffMultiplier !== 0) {
+            this.logger.trace({
+                backoffMultiplier: this.backoffMultiplier,
+                tickCount: this.tickCount,
+            }, 'Skipping tick (backoff)');
+            return;
+        }
+        const candidate = await this.discoverStalest();
+        if (!candidate) {
+            this.backoffMultiplier = Math.min(this.backoffMultiplier * 2, MAX_BACKOFF_MULTIPLIER);
+            this.logger.debug({ backoffMultiplier: this.backoffMultiplier }, 'No stale candidates found, increasing backoff');
+            return;
+        }
+        this.queue.enqueue(candidate);
+        this.logger.info({ path: candidate }, 'Enqueued stale candidate');
+        // Opportunistic watcher restart detection
+        if (this.registrar) {
+            try {
+                const statusRes = await fetch(new URL('/status', this.config.watcherUrl), {
+                    signal: AbortSignal.timeout(3000),
+                });
+                if (statusRes.ok) {
+                    const status = (await statusRes.json());
+                    if (typeof status.uptime === 'number') {
+                        await this.registrar.checkAndReregister(status.uptime);
+                    }
+                }
+            }
+            catch {
+                // Watcher unreachable — skip uptime check
+            }
+        }
+    }
+    /**
+     * Discover the stalest meta candidate via watcher.
+     */
+    async discoverStalest() {
+        try {
+            const result = await listMetas(this.config, this.watcher);
+            const stale = result.entries
+                .filter((e) => e.stalenessSeconds > 0)
+                .map((e) => ({
+                node: e.node,
+                meta: e.meta,
+                actualStaleness: e.stalenessSeconds,
+            }));
+            return discoverStalestPath(stale, this.config.depthWeight);
+        }
+        catch (err) {
+            this.logger.warn({ err }, 'Failed to discover stalest candidate');
+            return null;
+        }
+    }
+}
+
+/**
+ * Single-threaded synthesis queue with priority support and deduplication.
+ *
+ * The scheduler enqueues the stalest candidate each tick. HTTP-triggered
+ * synthesis requests get priority (inserted at front). A path appears at
+ * most once in the queue; re-triggering returns the current position.
+ *
+ * @module queue
+ */
+const DEPTH_WARNING_THRESHOLD = 3;
+/**
+ * Single-threaded synthesis queue.
+ *
+ * Only one synthesis runs at a time. Priority items are inserted at the
+ * front of the queue. Duplicate paths are rejected with their current
+ * position returned.
+ */
+class SynthesisQueue {
+    queue = [];
+    currentItem = null;
+    processing = false;
+    logger;
+    onEnqueueCallback = null;
+    /**
+     * Create a new SynthesisQueue.
+     *
+     * @param logger - Pino logger instance.
+     */
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Set a callback to invoke when a new (non-duplicate) item is enqueued.
+     */
+    onEnqueue(callback) {
+        this.onEnqueueCallback = callback;
+    }
+    /**
+     * Add a path to the synthesis queue.
+     *
+     * @param path - Meta path to synthesize.
+     * @param priority - If true, insert at front of queue.
+     * @returns Position and whether the path was already queued.
+     */
+    enqueue(path, priority = false) {
+        // Check if currently being synthesized.
+        if (this.currentItem?.path === path) {
+            return { position: 0, alreadyQueued: true };
+        }
+        // Check if already in queue.
+        const existingIndex = this.queue.findIndex((item) => item.path === path);
+        if (existingIndex !== -1) {
+            return { position: existingIndex, alreadyQueued: true };
+        }
+        const item = {
+            path,
+            priority,
+            enqueuedAt: new Date().toISOString(),
+        };
+        if (priority) {
+            this.queue.unshift(item);
+        }
+        else {
+            this.queue.push(item);
+        }
+        if (this.queue.length > DEPTH_WARNING_THRESHOLD) {
+            this.logger.warn({ depth: this.queue.length }, 'Queue depth exceeds threshold');
+        }
+        const position = this.queue.findIndex((i) => i.path === path);
+        this.onEnqueueCallback?.();
+        return { position, alreadyQueued: false };
+    }
+    /**
+     * Remove and return the next item from the queue.
+     *
+     * @returns The next QueueItem, or undefined if the queue is empty.
+     */
+    dequeue() {
+        const item = this.queue.shift();
+        if (item) {
+            this.currentItem = item;
+        }
+        return item;
+    }
+    /** Mark the currently-running synthesis as complete. */
+    complete() {
+        this.currentItem = null;
+    }
+    /** Number of items waiting in the queue (excludes current). */
+    get depth() {
+        return this.queue.length;
+    }
+    /** The item currently being synthesized, or null. */
+    get current() {
+        return this.currentItem;
+    }
+    /** A shallow copy of the queued items. */
+    get items() {
+        return [...this.queue];
+    }
+    /**
+     * Check whether a path is in the queue or currently being synthesized.
+     *
+     * @param path - Meta path to look up.
+     * @returns True if the path is queued or currently running.
+     */
+    has(path) {
+        if (this.currentItem?.path === path)
+            return true;
+        return this.queue.some((item) => item.path === path);
+    }
+    /**
+     * Get the 0-indexed position of a path in the queue.
+     *
+     * @param path - Meta path to look up.
+     * @returns Position index, or null if not found in the queue.
+     */
+    getPosition(path) {
+        const index = this.queue.findIndex((item) => item.path === path);
+        return index === -1 ? null : index;
+    }
+    /**
+     * Return a snapshot of queue state for the /status endpoint.
+     *
+     * @returns Queue depth and item list.
+     */
+    getState() {
+        return {
+            depth: this.queue.length,
+            items: this.queue.map((item) => ({
+                path: item.path,
+                priority: item.priority,
+                enqueuedAt: item.enqueuedAt,
+            })),
+        };
+    }
+    /**
+     * Process queued items one at a time until the queue is empty.
+     *
+     * Re-entry is prevented: if already processing, the call returns
+     * immediately. Errors are logged and do not block subsequent items.
+     *
+     * @param synthesizeFn - Async function that performs synthesis for a path.
+     */
+    async processQueue(synthesizeFn) {
+        if (this.processing)
+            return;
+        this.processing = true;
+        try {
+            let item = this.dequeue();
+            while (item) {
+                try {
+                    await synthesizeFn(item.path);
+                }
+                catch (err) {
+                    this.logger.error({ path: item.path, err }, 'Synthesis failed');
+                }
+                this.complete();
+                item = this.dequeue();
+            }
+        }
+        finally {
+            this.processing = false;
+        }
+    }
+}
+
+/**
+ * GET /config/validate — return sanitized service configuration.
+ *
+ * @module routes/configValidate
+ */
+function registerConfigValidateRoute(app, deps) {
+    app.get('/config/validate', () => {
+        const sanitized = {
+            ...deps.config,
+            gatewayApiKey: deps.config.gatewayApiKey ? '[REDACTED]' : undefined,
+        };
+        return sanitized;
+    });
+}
+
+/**
+ * GET /metas — list metas with optional filters.
+ * GET /metas/:path — single meta detail.
+ *
+ * @module routes/metas
+ */
+const metasQuerySchema = z.object({
+    pathPrefix: z.string().optional(),
+    hasError: z
+        .enum(['true', 'false'])
+        .transform((v) => v === 'true')
+        .optional(),
+    staleHours: z
+        .string()
+        .transform(Number)
+        .pipe(z.number().positive())
+        .optional(),
+    neverSynthesized: z
+        .enum(['true', 'false'])
+        .transform((v) => v === 'true')
+        .optional(),
+    locked: z
+        .enum(['true', 'false'])
+        .transform((v) => v === 'true')
+        .optional(),
+    fields: z.string().optional(),
+});
+const metaDetailQuerySchema = z.object({
+    fields: z.string().optional(),
+    includeArchive: z
+        .union([
+        z.enum(['true', 'false']).transform((v) => v === 'true'),
+        z.string().transform(Number).pipe(z.number().int().nonnegative()),
+    ])
+        .optional(),
+});
+/** Compute summary stats from a filtered set of MetaEntries. */
+function computeFilteredSummary(entries) {
+    let staleCount = 0;
+    let errorCount = 0;
+    let neverSynthCount = 0;
+    let stalestPath = null;
+    let stalestSeconds = -1;
+    let lastSynthesizedPath = null;
+    let lastSynthesizedAt = null;
+    let totalArchitectTokens = 0;
+    let totalBuilderTokens = 0;
+    let totalCriticTokens = 0;
+    for (const e of entries) {
+        if (e.stalenessSeconds > 0)
+            staleCount++;
+        if (e.hasError)
+            errorCount++;
+        if (e.stalenessSeconds === Infinity)
+            neverSynthCount++;
+        if (e.stalenessSeconds > stalestSeconds) {
+            stalestSeconds = e.stalenessSeconds;
+            stalestPath = e.path;
+        }
+        if (e.lastSynthesized &&
+            (!lastSynthesizedAt || e.lastSynthesized > lastSynthesizedAt)) {
+            lastSynthesizedAt = e.lastSynthesized;
+            lastSynthesizedPath = e.path;
+        }
+        totalArchitectTokens += e.architectTokens ?? 0;
+        totalBuilderTokens += e.builderTokens ?? 0;
+        totalCriticTokens += e.criticTokens ?? 0;
+    }
+    return {
+        total: entries.length,
+        stale: staleCount,
+        errors: errorCount,
+        neverSynthesized: neverSynthCount,
+        stalestPath,
+        lastSynthesizedPath,
+        lastSynthesizedAt,
+        tokens: {
+            architect: totalArchitectTokens,
+            builder: totalBuilderTokens,
+            critic: totalCriticTokens,
+        },
+    };
+}
+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);
+        let entries = result.entries;
+        // Apply filters
+        if (query.pathPrefix) {
+            entries = entries.filter((e) => e.path.includes(query.pathPrefix));
+        }
+        if (query.hasError !== undefined) {
+            entries = entries.filter((e) => e.hasError === query.hasError);
+        }
+        if (query.neverSynthesized !== undefined) {
+            entries = entries.filter((e) => (e.stalenessSeconds === Infinity) === query.neverSynthesized);
+        }
+        if (query.locked !== undefined) {
+            entries = entries.filter((e) => e.locked === query.locked);
+        }
+        if (typeof query.staleHours === 'number') {
+            entries = entries.filter((e) => e.stalenessSeconds >= query.staleHours * 3600);
+        }
+        // Summary (computed from filtered entries)
+        const summary = computeFilteredSummary(entries);
+        // Field projection
+        const fieldList = query.fields?.split(',');
+        const defaultFields = [
+            'path',
+            'depth',
+            'emphasis',
+            'stalenessSeconds',
+            'lastSynthesized',
+            'hasError',
+            'locked',
+            'architectTokens',
+            'builderTokens',
+            'criticTokens',
+        ];
+        const projectedFields = fieldList ?? defaultFields;
+        const metas = entries.map((e) => {
+            const full = {
+                path: e.path,
+                depth: e.depth,
+                emphasis: e.emphasis,
+                stalenessSeconds: e.stalenessSeconds === Infinity
+                    ? null
+                    : Math.round(e.stalenessSeconds),
+                lastSynthesized: e.lastSynthesized,
+                hasError: e.hasError,
+                locked: e.locked,
+                architectTokens: e.architectTokens,
+                builderTokens: e.builderTokens,
+                criticTokens: e.criticTokens,
+            };
+            const projected = {};
+            for (const f of projectedFields) {
+                if (f in full)
+                    projected[f] = full[f];
+            }
+            return projected;
+        });
+        return { summary, metas };
+    });
+    app.get('/metas/:path', async (request, reply) => {
+        const query = metaDetailQuerySchema.parse(request.query);
+        const { config, watcher } = deps;
+        const targetPath = normalizePath(decodeURIComponent(request.params.path));
+        const result = await listMetas(config, watcher);
+        const targetNode = findNode(result.tree, targetPath);
+        if (!targetNode) {
+            return reply.status(404).send({
+                error: 'NOT_FOUND',
+                message: 'Meta path not found: ' + targetPath,
+            });
+        }
+        const meta = JSON.parse(readFileSync(join(targetNode.metaPath, 'meta.json'), 'utf8'));
+        // Field projection
+        const defaultExclude = new Set([
+            '_architect',
+            '_builder',
+            '_critic',
+            '_content',
+            '_feedback',
+        ]);
+        const fieldList = query.fields?.split(',');
+        const projectMeta = (m) => {
+            if (fieldList) {
+                const r = {};
+                for (const f of fieldList)
+                    r[f] = m[f];
+                return r;
+            }
+            const r = {};
+            for (const [k, v] of Object.entries(m)) {
+                if (!defaultExclude.has(k))
+                    r[k] = v;
+            }
+            return r;
+        };
+        // Compute scope
+        const { scopeFiles, allFiles } = await getScopeFiles(targetNode, watcher);
+        // Compute staleness
+        const metaTyped = meta;
+        const staleSeconds = metaTyped._generatedAt
+            ? Math.round((Date.now() - new Date(metaTyped._generatedAt).getTime()) / 1000)
+            : null;
+        const score = computeStalenessScore(staleSeconds, metaTyped._depth ?? 0, metaTyped._emphasis ?? 1, config.depthWeight);
+        const response = {
+            path: targetNode.metaPath,
+            meta: projectMeta(meta),
+            scope: {
+                ownedFiles: scopeFiles.length,
+                childMetas: targetNode.children.length,
+                totalFiles: allFiles.length,
+            },
+            staleness: {
+                seconds: staleSeconds,
+                score: Math.round(score * 100) / 100,
+            },
+        };
+        // Archive
+        if (query.includeArchive) {
+            const archiveFiles = listArchiveFiles(targetNode.metaPath);
+            const limit = typeof query.includeArchive === 'number'
+                ? query.includeArchive
+                : archiveFiles.length;
+            const selected = archiveFiles.slice(-limit).reverse();
+            response.archive = selected.map((af) => {
+                const raw = readFileSync(af, 'utf8');
+                return projectMeta(JSON.parse(raw));
+            });
+        }
+        return response;
+    });
+}
+
+/**
+ * GET /preview — dry-run synthesis preview.
+ *
+ * @module routes/preview
+ */
+function registerPreviewRoute(app, deps) {
+    app.get('/preview', async (request, reply) => {
+        const { config, watcher } = deps;
+        const query = request.query;
+        let result;
+        try {
+            result = await listMetas(config, watcher);
+        }
+        catch {
+            return reply.status(503).send({
+                error: 'SERVICE_UNAVAILABLE',
+                message: 'Watcher unreachable — cannot compute preview',
+            });
+        }
+        let targetNode;
+        if (query.path) {
+            const normalized = normalizePath(query.path);
+            targetNode = findNode(result.tree, normalized);
+            if (!targetNode) {
+                return {
+                    error: 'NOT_FOUND',
+                    message: 'Meta path not found: ' + query.path,
+                };
+            }
+        }
+        else {
+            // Select stalest candidate
+            const stale = result.entries
+                .filter((e) => e.stalenessSeconds > 0)
+                .map((e) => ({
+                node: e.node,
+                meta: e.meta,
+                actualStaleness: e.stalenessSeconds,
+            }));
+            const stalestPath = discoverStalestPath(stale, config.depthWeight);
+            if (!stalestPath) {
+                return { message: 'No stale metas found. Nothing to synthesize.' };
+            }
+            targetNode = findNode(result.tree, stalestPath);
+        }
+        const meta = JSON.parse(readFileSync(join(targetNode.metaPath, 'meta.json'), 'utf8'));
+        // Scope files
+        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 = await getDeltaFiles(targetNode, watcher, meta._generatedAt, scopeFiles);
+        // EMA token estimates
+        const estimatedTokens = {
+            architect: meta._architectTokensAvg ?? meta._architectTokens ?? 0,
+            builder: meta._builderTokensAvg ?? meta._builderTokens ?? 0,
+            critic: meta._criticTokensAvg ?? meta._criticTokens ?? 0,
+        };
+        // Compute staleness
+        const stalenessSeconds = meta._generatedAt
+            ? Math.round((Date.now() - new Date(meta._generatedAt).getTime()) / 1000)
+            : null;
+        const stalenessScore = computeStalenessScore(stalenessSeconds, meta._depth ?? 0, meta._emphasis ?? 1, config.depthWeight);
+        return {
+            path: targetNode.metaPath,
+            staleness: {
+                seconds: stalenessSeconds,
+                score: Math.round(stalenessScore * 100) / 100,
+            },
+            architectWillRun: architectTriggered,
+            architectReason: [
+                ...(!meta._builder ? ['no cached builder (first run)'] : []),
+                ...(structureChanged ? ['structure changed'] : []),
+                ...(steerChanged ? ['steer changed'] : []),
+                ...((meta._synthesisCount ?? 0) >= config.architectEvery
+                    ? ['periodic refresh']
+                    : []),
+            ].join(', ') || 'not triggered',
+            scope: {
+                ownedFiles: scopeFiles.length,
+                childMetas: targetNode.children.length,
+                deltaFiles: deltaFiles
+                    .slice(0, 50)
+                    .map((f) => ({ path: f, action: 'modified' })),
+                deltaCount: deltaFiles.length,
+            },
+            estimatedTokens,
+        };
+    });
+}
+
+/**
+ * POST /seed — create a .meta/ directory with an empty meta.json.
+ *
+ * @module routes/seed
+ */
+const seedBodySchema = z.object({
+    path: z.string().min(1),
+});
+function registerSeedRoute(app, deps) {
+    app.post('/seed', (request, reply) => {
+        const body = seedBodySchema.parse(request.body);
+        const metaDir = resolveMetaDir(body.path);
+        if (existsSync(metaDir)) {
+            return reply.status(409).send({
+                error: 'CONFLICT',
+                message: `.meta directory already exists at ${body.path}`,
+            });
+        }
+        deps.logger.info({ metaDir }, 'creating .meta directory');
+        mkdirSync(metaDir, { recursive: true });
+        const metaJson = { _id: randomUUID() };
+        const metaJsonPath = join(metaDir, 'meta.json');
+        deps.logger.info({ metaJsonPath }, 'writing meta.json');
+        writeFileSync(metaJsonPath, JSON.stringify(metaJson, null, 2) + '\n');
+        return reply.status(201).send({
+            status: 'created',
+            path: body.path,
+            metaDir,
+            _id: metaJson._id,
+        });
+    });
+}
+
+/**
+ * GET /status — service health and status overview.
+ *
+ * On-demand dependency health checks (lightweight ping).
+ *
+ * @module routes/status
+ */
+async function checkDependency(url, path) {
+    const checkedAt = new Date().toISOString();
+    try {
+        const res = await fetch(new URL(path, url), {
+            signal: AbortSignal.timeout(3000),
+        });
+        return { url, status: res.ok ? 'ok' : 'error', checkedAt };
+    }
+    catch {
+        return { url, status: 'unreachable', checkedAt };
+    }
+}
+function registerStatusRoute(app, deps) {
+    app.get('/status', async () => {
+        const { config, queue, scheduler, stats, watcher } = deps;
+        // On-demand dependency checks
+        const [watcherHealth, gatewayHealth] = await Promise.all([
+            checkDependency(config.watcherUrl, '/status'),
+            checkDependency(config.gatewayUrl, '/api/status'),
+        ]);
+        const degraded = watcherHealth.status !== 'ok' || gatewayHealth.status !== 'ok';
+        // Determine status
+        let status;
+        if (deps.shuttingDown) {
+            status = 'stopping';
+        }
+        else if (queue.current) {
+            status = 'synthesizing';
+        }
+        else if (degraded) {
+            status = 'degraded';
+        }
+        else {
+            status = 'idle';
+        }
+        // Metas summary from listMetas (already computed)
+        let metasSummary = { total: 0, stale: 0, errors: 0, neverSynthesized: 0 };
+        try {
+            const result = await listMetas(config, watcher);
+            metasSummary = {
+                total: result.summary.total,
+                stale: result.summary.stale,
+                errors: result.summary.errors,
+                neverSynthesized: result.summary.neverSynthesized,
+            };
+        }
+        catch {
+            // Watcher unreachable — leave zeros
+        }
+        return {
+            service: 'jeeves-meta',
+            version: '0.4.0',
+            uptime: process.uptime(),
+            status,
+            currentTarget: queue.current?.path ?? null,
+            queue: queue.getState(),
+            stats: {
+                totalSyntheses: stats.totalSyntheses,
+                totalTokens: stats.totalTokens,
+                totalErrors: stats.totalErrors,
+                lastCycleDurationMs: stats.lastCycleDurationMs,
+                lastCycleAt: stats.lastCycleAt,
+            },
+            schedule: {
+                expression: config.schedule,
+                nextAt: scheduler?.nextRunAt?.toISOString() ?? null,
+            },
+            dependencies: {
+                watcher: watcherHealth,
+                gateway: gatewayHealth,
+            },
+            metas: metasSummary,
+        };
+    });
+}
+
+/**
+ * POST /synthesize route handler.
+ *
+ * @module routes/synthesize
+ */
+const synthesizeBodySchema = z.object({
+    path: z.string().optional(),
+});
+/** Register the POST /synthesize route. */
+function registerSynthesizeRoute(app, deps) {
+    app.post('/synthesize', async (request, reply) => {
+        const body = synthesizeBodySchema.parse(request.body);
+        const { config, watcher, queue } = deps;
+        let targetPath;
+        if (body.path) {
+            targetPath = body.path;
+        }
+        else {
+            // Discover stalest candidate
+            let result;
+            try {
+                result = await listMetas(config, watcher);
+            }
+            catch {
+                return reply.status(503).send({
+                    error: 'SERVICE_UNAVAILABLE',
+                    message: 'Watcher unreachable — cannot discover candidates',
+                });
+            }
+            const stale = result.entries
+                .filter((e) => e.stalenessSeconds > 0)
+                .map((e) => ({
+                node: e.node,
+                meta: e.meta,
+                actualStaleness: e.stalenessSeconds,
+            }));
+            const stalest = discoverStalestPath(stale, config.depthWeight);
+            if (!stalest) {
+                return reply.code(200).send({
+                    status: 'skipped',
+                    message: 'No stale metas found. Nothing to synthesize.',
+                });
+            }
+            targetPath = stalest;
+        }
+        const result = queue.enqueue(targetPath, body.path !== undefined);
+        return reply.code(202).send({
+            status: 'accepted',
+            path: targetPath,
+            queuePosition: result.position,
+            alreadyQueued: result.alreadyQueued,
+        });
+    });
+}
+
+/**
+ * POST /unlock — remove .lock from a .meta/ directory.
+ *
+ * @module routes/unlock
+ */
+const unlockBodySchema = z.object({
+    path: z.string().min(1),
+});
+function registerUnlockRoute(app, deps) {
+    app.post('/unlock', (request, reply) => {
+        const body = unlockBodySchema.parse(request.body);
+        const metaDir = resolveMetaDir(body.path);
+        const lockPath = join(metaDir, '.lock');
+        if (!existsSync(lockPath)) {
+            return reply.status(409).send({
+                error: 'ALREADY_UNLOCKED',
+                message: `No lock file at ${body.path} (already unlocked)`,
+            });
+        }
+        deps.logger.info({ lockPath }, 'removing lock file');
+        unlinkSync(lockPath);
+        return reply.status(200).send({
+            status: 'unlocked',
+            path: body.path,
+        });
+    });
+}
+
+/**
+ * Route registration for jeeves-meta service.
+ *
+ * @module routes
+ */
+/** Register all HTTP routes on the Fastify instance. */
+function registerRoutes(app, deps) {
+    // Global error handler for validation + watcher errors
+    app.setErrorHandler((error, _request, reply) => {
+        if (error.validation) {
+            return reply
+                .status(400)
+                .send({ error: 'BAD_REQUEST', message: error.message });
+        }
+        if (error.statusCode === 404) {
+            return reply
+                .status(404)
+                .send({ error: 'NOT_FOUND', message: error.message });
+        }
+        deps.logger.error(error, 'Unhandled route error');
+        return reply
+            .status(500)
+            .send({ error: 'INTERNAL_ERROR', message: error.message });
+    });
+    registerStatusRoute(app, deps);
+    registerMetasRoutes(app, deps);
+    registerSynthesizeRoute(app, deps);
+    registerPreviewRoute(app, deps);
+    registerSeedRoute(app, deps);
+    registerUnlockRoute(app, deps);
+    registerConfigValidateRoute(app, deps);
+}
+
+/**
+ * Virtual rule registration with jeeves-watcher.
+ *
+ * Service registers inference rules at startup (with retry) and
+ * re-registers opportunistically when watcher restart is detected.
+ *
+ * @module rules
+ */
+const SOURCE = 'jeeves-meta';
+const MAX_RETRIES = 10;
+const RETRY_BASE_MS = 2000;
+/**
+ * Convert a `Record<string, unknown>` config property into watcher
+ * schema `set` directives: `{ key: { set: value } }` per entry.
+ */
+function toSchemaSetDirectives(props) {
+    return Object.fromEntries(Object.entries(props).map(([k, v]) => [k, { set: v }]));
+}
+/** Build the three virtual rule definitions. */
+function buildMetaRules(config) {
+    return [
+        {
+            name: 'meta-current',
+            description: 'Live jeeves-meta .meta/meta.json files',
+            match: {
+                properties: {
+                    file: {
+                        properties: {
+                            path: { type: 'string', glob: '**/.meta/meta.json' },
+                        },
+                    },
+                },
+            },
+            schema: [
+                'base',
+                {
+                    properties: {
+                        ...toSchemaSetDirectives(config.metaProperty),
+                        meta_id: { type: 'string', set: '{{json._id}}' },
+                        meta_steer: { type: 'string', set: '{{json._steer}}' },
+                        meta_depth: { type: 'number', set: '{{json._depth}}' },
+                        meta_emphasis: { type: 'number', set: '{{json._emphasis}}' },
+                        meta_synthesis_count: {
+                            type: 'integer',
+                            set: '{{json._synthesisCount}}',
+                        },
+                        meta_structure_hash: {
+                            type: 'string',
+                            set: '{{json._structureHash}}',
+                        },
+                        meta_architect_tokens: {
+                            type: 'integer',
+                            set: '{{json._architectTokens}}',
+                        },
+                        meta_builder_tokens: {
+                            type: 'integer',
+                            set: '{{json._builderTokens}}',
+                        },
+                        meta_critic_tokens: {
+                            type: 'integer',
+                            set: '{{json._criticTokens}}',
+                        },
+                        meta_error_step: {
+                            type: 'string',
+                            set: '{{json._error.step}}',
+                        },
+                        generated_at_unix: {
+                            type: 'integer',
+                            set: '{{toUnix json._generatedAt}}',
+                        },
+                        has_error: {
+                            type: 'boolean',
+                            set: '{{#if json._error}}true{{else}}false{{/if}}',
+                        },
+                    },
+                },
+            ],
+            render: {
+                frontmatter: [
+                    'meta_id',
+                    'meta_steer',
+                    'generated_at_unix',
+                    'meta_depth',
+                    'meta_emphasis',
+                    'meta_architect_tokens',
+                    'meta_builder_tokens',
+                    'meta_critic_tokens',
+                ],
+                body: [{ path: 'json._content', heading: 1, label: 'Synthesis' }],
+            },
+            renderAs: 'md',
+        },
+        {
+            name: 'meta-archive',
+            description: 'Archived jeeves-meta .meta/archive snapshots',
+            match: {
+                properties: {
+                    file: {
+                        properties: {
+                            path: { type: 'string', glob: '**/.meta/archive/*.json' },
+                        },
+                    },
+                },
+            },
+            schema: [
+                'base',
+                {
+                    properties: {
+                        ...toSchemaSetDirectives(config.metaArchiveProperty),
+                        meta_id: { type: 'string', set: '{{json._id}}' },
+                        archived: { type: 'boolean', set: 'true' },
+                        archived_at: { type: 'string', set: '{{json._archivedAt}}' },
+                    },
+                },
+            ],
+            render: {
+                frontmatter: ['meta_id', 'archived', 'archived_at'],
+                body: [
+                    {
+                        path: 'json._content',
+                        heading: 1,
+                        label: 'Synthesis (archived)',
+                    },
+                ],
+            },
+            renderAs: 'md',
+        },
+        {
+            name: 'meta-config',
+            description: 'jeeves-meta configuration file',
+            match: {
+                properties: {
+                    file: {
+                        properties: {
+                            path: { type: 'string', glob: '**/jeeves-meta.config.json' },
+                        },
+                    },
+                },
+            },
+            schema: ['base', { properties: { domains: { set: ['meta-config'] } } }],
+            render: {
+                frontmatter: [
+                    'watcherUrl',
+                    'gatewayUrl',
+                    'architectEvery',
+                    'depthWeight',
+                    'maxArchive',
+                    'maxLines',
+                ],
+                body: [
+                    {
+                        path: 'json.defaultArchitect',
+                        heading: 2,
+                        label: 'Default Architect Prompt',
+                    },
+                    {
+                        path: 'json.defaultCritic',
+                        heading: 2,
+                        label: 'Default Critic Prompt',
+                    },
+                ],
+            },
+            renderAs: 'md',
+        },
+    ];
+}
+/**
+ * Manages virtual rule registration with watcher.
+ *
+ * - Registers at startup with exponential retry
+ * - Tracks watcher uptime for restart detection
+ * - Re-registers opportunistically when uptime decreases
+ */
+class RuleRegistrar {
+    config;
+    logger;
+    watcherClient;
+    lastWatcherUptime = null;
+    registered = false;
+    constructor(config, logger, watcher) {
+        this.config = config;
+        this.logger = logger;
+        this.watcherClient = watcher;
+    }
+    /** Whether rules have been successfully registered. */
+    get isRegistered() {
+        return this.registered;
+    }
+    /**
+     * Register rules with watcher. Retries with exponential backoff.
+     * Non-blocking — logs errors but never throws.
+     */
+    async register() {
+        const rules = buildMetaRules(this.config);
+        for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+            try {
+                await this.watcherClient.registerRules(SOURCE, rules);
+                this.registered = true;
+                this.logger.info('Virtual rules registered with watcher');
+                return;
+            }
+            catch (err) {
+                const delayMs = RETRY_BASE_MS * Math.pow(2, attempt);
+                this.logger.warn({ attempt: attempt + 1, delayMs, err }, 'Rule registration failed, retrying');
+                await new Promise((r) => setTimeout(r, delayMs));
+            }
+        }
+        this.logger.error('Rule registration failed after max retries — service degraded');
+    }
+    /**
+     * Check watcher uptime and re-register if it decreased (restart detected).
+     *
+     * @param currentUptime - Current watcher uptime in seconds.
+     */
+    async checkAndReregister(currentUptime) {
+        if (this.lastWatcherUptime !== null &&
+            currentUptime < this.lastWatcherUptime) {
+            this.logger.info({ previous: this.lastWatcherUptime, current: currentUptime }, 'Watcher restart detected — re-registering rules');
+            this.registered = false;
+            await this.register();
+        }
+        this.lastWatcherUptime = currentUptime;
+    }
+}
+
+/**
+ * Minimal Fastify HTTP server for jeeves-meta service.
+ *
+ * @module server
+ */
+/**
+ * Create and configure the Fastify server.
+ *
+ * @param options - Server creation options.
+ * @returns Configured Fastify instance (not yet listening).
+ */
+function createServer(options) {
+    const app = Fastify({ logger: options.logger });
+    registerRoutes(app, {
+        config: options.config,
+        logger: options.logger,
+        queue: options.queue,
+        watcher: options.watcher,
+        scheduler: options.scheduler,
+        stats: options.stats,
+    });
+    return app;
+}
+
+/**
+ * Graceful shutdown handler.
+ *
+ * On SIGTERM/SIGINT: stops scheduler, drains queue, cleans up locks.
+ *
+ * @module shutdown
+ */
+/**
+ * Register shutdown handlers for SIGTERM and SIGINT.
+ *
+ * Flow:
+ * 1. Stop scheduler (no new ticks)
+ * 2. If synthesis in progress, release its lock
+ * 3. Close Fastify server
+ * 4. Exit
+ */
+function registerShutdownHandlers(deps) {
+    let shuttingDown = false;
+    const shutdown = async (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        deps.logger.info({ signal }, 'Shutdown signal received');
+        // Signal stopping state to /status
+        if (deps.routeDeps) {
+            deps.routeDeps.shuttingDown = true;
+        }
+        // 1. Stop scheduler
+        if (deps.scheduler) {
+            deps.scheduler.stop();
+            deps.logger.info('Scheduler stopped');
+        }
+        // 2. Release lock for in-progress synthesis
+        const current = deps.queue.current;
+        if (current) {
+            try {
+                releaseLock(current.path);
+                deps.logger.info({ path: current.path }, 'Released lock for in-progress synthesis');
+            }
+            catch {
+                deps.logger.warn({ path: current.path }, 'Failed to release lock during shutdown');
+            }
+        }
+        // 3. Close server
+        try {
+            await deps.server.close();
+            deps.logger.info('HTTP server closed');
+        }
+        catch (err) {
+            deps.logger.error(err, 'Error closing HTTP server');
+        }
+        process.exit(0);
+    };
+    process.on('SIGTERM', () => void shutdown('SIGTERM'));
+    process.on('SIGINT', () => void shutdown('SIGINT'));
+}
+
+/**
+ * HTTP implementation of the WatcherClient interface.
+ *
+ * Talks to jeeves-watcher's POST /scan and POST /rules endpoints
+ * with retry and exponential backoff.
+ *
+ * @module watcher-client/HttpWatcherClient
+ */
+/** Default retry configuration. */
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_BACKOFF_BASE_MS = 1000;
+const DEFAULT_BACKOFF_FACTOR = 4;
+/** Check if an error is transient (worth retrying). */
+function isTransient(status) {
+    return status >= 500 || status === 408 || status === 429;
+}
+/**
+ * HTTP-based WatcherClient implementation with retry.
+ */
+class HttpWatcherClient {
+    baseUrl;
+    maxRetries;
+    backoffBaseMs;
+    backoffFactor;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.backoffBaseMs = options.backoffBaseMs ?? DEFAULT_BACKOFF_BASE_MS;
+        this.backoffFactor = options.backoffFactor ?? DEFAULT_BACKOFF_FACTOR;
+    }
+    /** POST JSON with retry. */
+    async post(endpoint, body) {
+        const url = this.baseUrl + endpoint;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+            });
+            if (res.ok) {
+                return res.json();
+            }
+            if (!isTransient(res.status) || attempt === this.maxRetries) {
+                const text = await res.text();
+                throw new Error(`Watcher ${endpoint} failed: HTTP ${res.status.toString()} - ${text}`);
+            }
+            // Exponential backoff
+            const delayMs = this.backoffBaseMs * Math.pow(this.backoffFactor, attempt);
+            await sleep(delayMs);
+        }
+        // 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 },
+            });
+        }
+        // Translate modifiedAfter into a Qdrant range filter on modified_at
+        if (params.modifiedAfter !== undefined) {
+            mustClauses.push({
+                key: 'modified_at',
+                range: { gt: params.modifiedAfter },
+            });
+        }
+        const filter = { must: mustClauses };
+        const body = { filter };
+        if (params.fields !== undefined) {
+            body.fields = params.fields;
+        }
+        if (params.limit !== undefined) {
+            body.limit = params.limit;
+        }
+        if (params.cursor !== undefined) {
+            body.cursor = params.cursor;
+        }
+        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 });
+    }
+}
+
+/**
+ * Jeeves Meta Service — knowledge synthesis HTTP service for the Jeeves platform.
+ *
+ * @packageDocumentation
+ */
+// ── Archive ──
+/**
+ * Bootstrap the service: create logger, build server, start listening,
+ * wire scheduler, queue processing, rule registration, config hot-reload,
+ * startup lock cleanup, and shutdown.
+ *
+ * @param config - Validated service configuration.
+ * @param configPath - Optional path to config file for hot-reload.
+ */
+async function startService(config, configPath) {
+    const logger = createLogger({
+        level: config.logging.level,
+        file: config.logging.file,
+    });
+    // Wire synthesis executor + watcher
+    const watcher = new HttpWatcherClient({ baseUrl: config.watcherUrl });
+    const executor = new GatewayExecutor({
+        gatewayUrl: config.gatewayUrl,
+        apiKey: config.gatewayApiKey,
+    });
+    // Runtime stats (mutable, shared with routes)
+    const stats = {
+        totalSyntheses: 0,
+        totalTokens: 0,
+        totalErrors: 0,
+        lastCycleDurationMs: null,
+        lastCycleAt: null,
+    };
+    const queue = new SynthesisQueue(logger);
+    // Scheduler (needs watcher for discovery)
+    const scheduler = new Scheduler(config, queue, logger, watcher);
+    const routeDeps = {
+        config,
+        logger,
+        queue,
+        watcher,
+        scheduler,
+        stats,
+    };
+    const server = createServer({
+        logger,
+        config,
+        queue,
+        watcher,
+        scheduler,
+        stats,
+    });
+    // Start HTTP server
+    try {
+        await server.listen({ port: config.port, host: '0.0.0.0' });
+        logger.info({ port: config.port }, 'Service listening');
+    }
+    catch (err) {
+        logger.error(err, 'Failed to start service');
+        process.exit(1);
+    }
+    // Progress reporter — uses shared config reference so hot-reload propagates
+    const progress = new ProgressReporter(config, logger);
+    // Wire queue processing — synthesize one meta per dequeue
+    const synthesizeFn = async (path) => {
+        const startMs = Date.now();
+        let cycleTokens = 0;
+        await progress.report({
+            type: 'synthesis_start',
+            metaPath: path,
+        });
+        try {
+            const results = await orchestrate(config, executor, watcher, path, async (evt) => {
+                // Track token stats from phase completions
+                if (evt.type === 'phase_complete' && evt.tokens) {
+                    stats.totalTokens += evt.tokens;
+                    cycleTokens += evt.tokens;
+                }
+                await progress.report(evt);
+            });
+            // orchestrate() always returns exactly one result
+            const result = results[0];
+            const durationMs = Date.now() - startMs;
+            // Update stats
+            stats.totalSyntheses++;
+            stats.lastCycleDurationMs = durationMs;
+            stats.lastCycleAt = new Date().toISOString();
+            if (result.error) {
+                stats.totalErrors++;
+                await progress.report({
+                    type: 'error',
+                    metaPath: path,
+                    error: result.error.message,
+                });
+            }
+            else {
+                scheduler.resetBackoff();
+                await progress.report({
+                    type: 'synthesis_complete',
+                    metaPath: path,
+                    tokens: cycleTokens,
+                    durationMs,
+                });
+            }
+        }
+        catch (err) {
+            stats.totalErrors++;
+            const message = err instanceof Error ? err.message : String(err);
+            await progress.report({
+                type: 'error',
+                metaPath: path,
+                error: message,
+            });
+            throw err;
+        }
+    };
+    // Auto-process queue when new items arrive
+    queue.onEnqueue(() => {
+        void queue.processQueue(synthesizeFn);
+    });
+    // Startup: clean stale locks (gap #16)
+    try {
+        const metaResult = await listMetas(config, watcher);
+        const metaPaths = metaResult.entries.map((e) => e.node.metaPath);
+        cleanupStaleLocks(metaPaths, logger);
+    }
+    catch (err) {
+        logger.warn({ err }, 'Could not clean stale locks (watcher may be down)');
+    }
+    // Start scheduler
+    scheduler.start();
+    // Rule registration (fire-and-forget with retries)
+    const registrar = new RuleRegistrar(config, logger, watcher);
+    scheduler.setRegistrar(registrar);
+    void registrar.register();
+    // Config hot-reload (gap #12)
+    if (configPath) {
+        watchFile(configPath, { interval: 5000 }, () => {
+            try {
+                const newConfig = loadServiceConfig(configPath);
+                // Hot-reloadable fields: schedule, reportChannel, logging level
+                if (newConfig.schedule !== config.schedule) {
+                    scheduler.updateSchedule(newConfig.schedule);
+                    logger.info({ schedule: newConfig.schedule }, 'Schedule hot-reloaded');
+                }
+                if (newConfig.reportChannel !== config.reportChannel) {
+                    // Mutate shared config reference for progress reporter
+                    config.reportChannel =
+                        newConfig.reportChannel;
+                    logger.info({ reportChannel: newConfig.reportChannel }, 'reportChannel hot-reloaded');
+                }
+                if (newConfig.logging.level !== config.logging.level) {
+                    logger.level = newConfig.logging.level;
+                    logger.info({ level: newConfig.logging.level }, 'Log level hot-reloaded');
+                }
+            }
+            catch (err) {
+                logger.warn({ err }, 'Config hot-reload failed');
+            }
+        });
+    }
+    // Shutdown handlers
+    registerShutdownHandlers({
+        server,
+        scheduler,
+        queue,
+        logger,
+        routeDeps,
+    });
+    logger.info('Service fully initialized');
+}
+
+/**
+ * Commander CLI for jeeves-meta service.
+ *
+ * @module cli
+ */
+const program = new Command();
+program.name('jeeves-meta').description('Jeeves Meta synthesis service');
+// ─── start ──────────────────────────────────────────────────────────
+program
+    .command('start')
+    .description('Start the HTTP service')
+    .requiredOption('-c, --config <path>', 'Path to config JSON file')
+    .action(async (opts) => {
+    const configPath = resolveConfigPath(['-c', opts.config]);
+    const config = loadServiceConfig(configPath);
+    await startService(config, configPath);
+});
+// ─── API client helpers ─────────────────────────────────────────────
+function apiUrl(port, path) {
+    return `http://127.0.0.1:${String(port)}${path}`;
+}
+async function apiGet(port, path) {
+    const res = await fetch(apiUrl(port, path));
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`${String(res.status)} ${res.statusText}: ${text}`);
+    }
+    return res.json();
+}
+async function apiPost(port, path, body) {
+    const res = await fetch(apiUrl(port, path), {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`${String(res.status)} ${res.statusText}: ${text}`);
+    }
+    return res.json();
+}
+// ─── status ─────────────────────────────────────────────────────────
+program
+    .command('status')
+    .description('Show service status')
+    .option('-p, --port <port>', 'Service port', '1938')
+    .action(async (opts) => {
+    try {
+        const data = await apiGet(parseInt(opts.port, 10), '/status');
+        console.log(JSON.stringify(data, null, 2));
+    }
+    catch (err) {
+        console.error('Service unreachable:', err.message);
+        process.exit(1);
+    }
+});
+// ─── list ───────────────────────────────────────────────────────────
+program
+    .command('list')
+    .description('List all discovered meta entities')
+    .option('-p, --port <port>', 'Service port', '1938')
+    .action(async (opts) => {
+    try {
+        const data = await apiGet(parseInt(opts.port, 10), '/metas');
+        console.log(JSON.stringify(data, null, 2));
+    }
+    catch (err) {
+        console.error('Error:', err.message);
+        process.exit(1);
+    }
+});
+// ─── detail ─────────────────────────────────────────────────────────
+program
+    .command('detail <path>')
+    .description('Show full detail for a single meta entity')
+    .option('-p, --port <port>', 'Service port', '1938')
+    .action(async (metaPath, opts) => {
+    try {
+        const encoded = encodeURIComponent(metaPath);
+        const data = await apiGet(parseInt(opts.port, 10), `/metas/${encoded}`);
+        console.log(JSON.stringify(data, null, 2));
+    }
+    catch (err) {
+        console.error('Error:', err.message);
+        process.exit(1);
+    }
+});
+// ─── preview ────────────────────────────────────────────────────────
+program
+    .command('preview')
+    .description('Dry-run: preview inputs for next synthesis cycle')
+    .option('-p, --port <port>', 'Service port', '1938')
+    .option('--path <path>', 'Specific meta path to preview')
+    .action(async (opts) => {
+    try {
+        const qs = opts.path ? '?path=' + encodeURIComponent(opts.path) : '';
+        const data = await apiGet(parseInt(opts.port, 10), '/preview' + qs);
+        console.log(JSON.stringify(data, null, 2));
+    }
+    catch (err) {
+        console.error('Error:', err.message);
+        process.exit(1);
+    }
+});
+// ─── synthesize ─────────────────────────────────────────────────────
+program
+    .command('synthesize')
+    .description('Trigger synthesis (enqueues work)')
+    .option('-p, --port <port>', 'Service port', '1938')
+    .option('--path <path>', 'Specific meta path to synthesize')
+    .action(async (opts) => {
+    try {
+        const body = opts.path ? { path: opts.path } : {};
+        const data = await apiPost(parseInt(opts.port, 10), '/synthesize', body);
+        console.log(JSON.stringify(data, null, 2));
+    }
+    catch (err) {
+        console.error('Error:', err.message);
+        process.exit(1);
+    }
+});
+// ─── seed ───────────────────────────────────────────────────────────
+program
+    .command('seed <path>')
+    .description('Create .meta/ directory + meta.json for a path')
+    .option('-p, --port <port>', 'Service port', '1938')
+    .action(async (metaPath, opts) => {
+    try {
+        const data = await apiPost(parseInt(opts.port, 10), '/seed', {
+            path: metaPath,
+        });
+        console.log(JSON.stringify(data, null, 2));
+    }
+    catch (err) {
+        console.error('Error:', err.message);
+        process.exit(1);
+    }
+});
+// ─── unlock ─────────────────────────────────────────────────────────
+program
+    .command('unlock <path>')
+    .description('Remove .lock file from a meta entity')
+    .option('-p, --port <port>', 'Service port', '1938')
+    .action(async (metaPath, opts) => {
+    try {
+        const data = await apiPost(parseInt(opts.port, 10), '/unlock', {
+            path: metaPath,
+        });
+        console.log(JSON.stringify(data, null, 2));
+    }
+    catch (err) {
+        console.error('Error:', err.message);
+        process.exit(1);
+    }
+});
+// ─── validate ───────────────────────────────────────────────────────
+program
+    .command('validate')
+    .description('Validate current or candidate config')
+    .option('-p, --port <port>', 'Service port', '1938')
+    .option('-c, --config <path>', 'Validate a candidate config file locally')
+    .action(async (opts) => {
+    try {
+        if (opts.config) {
+            // Local validation — parse candidate file through Zod schema
+            const { loadServiceConfig } = await Promise.resolve().then(function () { return configLoader; });
+            const configPath = opts.config;
+            const config = loadServiceConfig(configPath);
+            const sanitized = {
+                ...config,
+                gatewayApiKey: config.gatewayApiKey ? '[REDACTED]' : undefined,
+            };
+            console.log(JSON.stringify(sanitized, null, 2));
+        }
+        else {
+            // Remote — query running service
+            const data = await apiGet(parseInt(opts.port, 10), '/config/validate');
+            console.log(JSON.stringify(data, null, 2));
+        }
+    }
+    catch (err) {
+        console.error('Error:', err.message);
+        process.exit(1);
+    }
+});
+// ─── service install/uninstall ──────────────────────────────────────
+const service = program
+    .command('service')
+    .description('Generate service install/uninstall instructions');
+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')
+    .action((options) => {
+    const { name } = options;
+    const configFlag = options.config ? ` -c "${options.config}"` : '';
+    if (process.platform === 'win32') {
+        console.log('# NSSM install (Windows)');
+        console.log(`  nssm install ${name} node "%APPDATA%\\npm\\node_modules\\@karmaniverous\\jeeves-meta\\dist\\cli\\jeeves-meta\\index.js" start${configFlag}`);
+        console.log(`  nssm set ${name} AppDirectory "%CD%"`);
+        console.log(`  nssm set ${name} DisplayName "Jeeves Meta"`);
+        console.log(`  nssm set ${name} Description "Meta synthesis service"`);
+        console.log(`  nssm set ${name} Start SERVICE_AUTO_START`);
+        console.log(`  nssm start ${name}`);
+        return;
+    }
+    if (process.platform === 'darwin') {
+        const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>com.jeeves.meta</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/local/bin/jeeves-meta</string>
+    <string>start</string>${options.config ? `\n    <string>-c</string>\n    <string>${options.config}</string>` : ''}
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>/tmp/${name}.stdout.log</string>
+  <key>StandardErrorPath</key><string>/tmp/${name}.stderr.log</string>
+</dict>
+</plist>`;
+        console.log('# launchd plist (macOS)');
+        console.log(`# ~/Library/LaunchAgents/com.jeeves.meta.plist`);
+        console.log(plist);
+        console.log();
+        console.log('# install');
+        console.log(`  launchctl load ~/Library/LaunchAgents/com.jeeves.meta.plist`);
+        return;
+    }
+    // Linux (systemd)
+    const unit = [
+        '[Unit]',
+        'Description=Jeeves Meta - Synthesis Service',
+        'After=network.target',
+        '',
+        '[Service]',
+        'Type=simple',
+        'WorkingDirectory=%h',
+        `ExecStart=/usr/bin/env jeeves-meta start${configFlag}`,
+        'Restart=on-failure',
+        '',
+        '[Install]',
+        'WantedBy=default.target',
+    ].join('\n');
+    console.log('# systemd unit file (Linux)');
+    console.log(`# ~/.config/systemd/user/${name}.service`);
+    console.log(unit);
+    console.log();
+    console.log('# install');
+    console.log(`  systemctl --user daemon-reload`);
+    console.log(`  systemctl --user enable --now ${name}.service`);
+}));
+// 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')
+    .action((options) => {
+    const { name } = options;
+    if (process.platform === 'win32') {
+        console.log('# NSSM start (Windows)');
+        console.log(`  nssm start ${name}`);
+        return;
+    }
+    if (process.platform === 'darwin') {
+        console.log('# launchd start (macOS)');
+        console.log(`  launchctl load ~/Library/LaunchAgents/com.jeeves.meta.plist`);
+        return;
+    }
+    console.log('# systemd start (Linux)');
+    console.log(`  systemctl --user start ${name}.service`);
+}));
+// stop command
+service.addCommand(new Command('stop')
+    .description('Stop the running service')
+    .option('-n, --name <name>', 'Service name', 'JeevesMeta')
+    .action((options) => {
+    const { name } = options;
+    if (process.platform === 'win32') {
+        console.log('# NSSM stop (Windows)');
+        console.log(`  nssm stop ${name}`);
+        return;
+    }
+    if (process.platform === 'darwin') {
+        console.log('# launchd stop (macOS)');
+        console.log(`  launchctl unload ~/Library/LaunchAgents/com.jeeves.meta.plist`);
+        return;
+    }
+    console.log('# systemd stop (Linux)');
+    console.log(`  systemctl --user stop ${name}.service`);
+}));
+// 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')
+    .action(async (opts) => {
+    try {
+        const data = await apiGet(parseInt(opts.port, 10), '/status');
+        console.log(JSON.stringify(data, null, 2));
+    }
+    catch (err) {
+        console.error('Service unreachable:', err.message);
+        process.exit(1);
+    }
+}));
+service.addCommand(new Command('remove')
+    .description('Print remove instructions for a system service')
+    .option('-n, --name <name>', 'Service name', 'JeevesMeta')
+    .action((options) => {
+    const { name } = options;
+    if (process.platform === 'win32') {
+        console.log('# NSSM remove (Windows)');
+        console.log(`  nssm stop ${name}`);
+        console.log(`  nssm remove ${name} confirm`);
+        return;
+    }
+    if (process.platform === 'darwin') {
+        console.log('# launchd remove (macOS)');
+        console.log(`  launchctl unload ~/Library/LaunchAgents/com.jeeves.meta.plist`);
+        console.log(`  rm ~/Library/LaunchAgents/com.jeeves.meta.plist`);
+        return;
+    }
+    console.log('# systemd remove (Linux)');
+    console.log(`  systemctl --user disable --now ${name}.service`);
+    console.log(`# rm ~/.config/systemd/user/${name}.service`);
+    console.log(`  systemctl --user daemon-reload`);
+}));
+program.parse();