@karmaniverous/jeeves-meta 0.1.0 → 0.2.0

package/dist/cli.js

@@ -0,0 +1,2013 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+import { readFileSync, readdirSync, unlinkSync, mkdirSync, writeFileSync, existsSync, statSync } from 'node:fs';
+import { dirname, join, relative, sep, resolve } from 'node:path';
+import { z } from 'zod';
+import { randomUUID, createHash } from 'node:crypto';
+
+/**
+ * Zod schema for jeeves-meta configuration.
+ *
+ * Consumers load config however they want (file, env, constructor).
+ * The library validates via this schema.
+ *
+ * @module schema/config
+ */
+/** Zod schema for jeeves-meta configuration. */
+const synthConfigSchema = z.object({
+    /** Filesystem paths to watch for .meta/ directories. */
+    watchPaths: z.array(z.string()).min(1),
+    /** Watcher service base URL. */
+    watcherUrl: z.url(),
+    /** OpenClaw gateway base URL for subprocess spawning. */
+    gatewayUrl: z.url().default('http://127.0.0.1:3000'),
+    /** 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),
+    /** Resolved architect system prompt text. */
+    defaultArchitect: z.string(),
+    /** Resolved critic system prompt text. */
+    defaultCritic: z.string(),
+    /**
+     * When true, skip unchanged candidates and iterate to the next-stalest
+     * until finding one with actual changes. Skipped candidates get their
+     * _generatedAt bumped to prevent re-selection next cycle.
+     */
+    skipUnchanged: z.boolean().default(true),
+    /** Number of metas to synthesize per invocation. */
+    batchSize: z.number().int().min(1).default(1),
+});
+
+/**
+ * Structured error from a synthesis step failure.
+ *
+ * @module schema/error
+ */
+/** Zod schema for synthesis step errors. */
+const synthErrorSchema = 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: synthErrorSchema.optional(),
+})
+    .loose();
+
+/**
+ * Load and resolve jeeves-meta config with \@file: indirection.
+ *
+ * @module configLoader
+ */
+/**
+ * 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');
+}
+/**
+ * Load synth config from a JSON file, resolving \@file: references.
+ *
+ * @param configPath - Path to jeeves-meta.config.json.
+ * @returns Validated SynthConfig with resolved prompt strings.
+ */
+function loadSynthConfig(configPath) {
+    const raw = JSON.parse(readFileSync(configPath, 'utf8'));
+    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 synthConfigSchema.parse(raw);
+}
+/**
+ * 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) {
+    // Check --config flag
+    const configIdx = args.indexOf('--config');
+    if (configIdx !== -1 && args[configIdx + 1]) {
+        return args[configIdx + 1];
+    }
+    // Check env var
+    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.');
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Archive module — snapshot creation, pruning, and reading.
+ *
+ * @module archive
+ */
+
+var index$1 = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    createSnapshot: createSnapshot,
+    listArchiveFiles: listArchiveFiles,
+    pruneArchive: pruneArchive,
+    readLatestArchive: readLatestArchive
+});
+
+/**
+ * Ensure meta.json exists in each .meta/ directory.
+ *
+ * If meta.json is missing, creates it with a generated UUID.
+ *
+ * @module discovery/ensureMetaJson
+ */
+/**
+ * Ensure meta.json exists at the given .meta/ path.
+ *
+ * @param metaPath - Absolute path to a .meta/ directory.
+ * @returns The meta.json content (existing or newly created).
+ */
+function ensureMetaJson(metaPath) {
+    const filePath = join(metaPath, 'meta.json');
+    if (existsSync(filePath)) {
+        const raw = readFileSync(filePath, 'utf8');
+        return JSON.parse(raw);
+    }
+    // Create the archive subdirectory while we're at it
+    const archivePath = join(metaPath, 'archive');
+    if (!existsSync(archivePath)) {
+        mkdirSync(archivePath, { recursive: true });
+    }
+    const meta = { _id: randomUUID() };
+    writeFileSync(filePath, JSON.stringify(meta, null, 2) + '\n');
+    return meta;
+}
+
+/**
+ * Glob watchPaths for .meta/ directories.
+ *
+ * Walks each watchPath recursively, collecting directories named '.meta'
+ * that contain (or will contain) a meta.json file.
+ *
+ * @module discovery/globMetas
+ */
+/**
+ * Recursively find all .meta/ directories under the given paths.
+ *
+ * @param watchPaths - Root directories to search.
+ * @returns Array of absolute paths to .meta/ directories.
+ */
+function globMetas(watchPaths) {
+    const results = [];
+    function walk(dir) {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return; // Skip unreadable directories
+        }
+        for (const entry of entries) {
+            const full = join(dir, entry);
+            let stat;
+            try {
+                stat = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (!stat.isDirectory())
+                continue;
+            if (entry === '.meta') {
+                results.push(full);
+            }
+            else {
+                walk(full);
+            }
+        }
+    }
+    for (const wp of watchPaths) {
+        walk(wp);
+    }
+    return results;
+}
+
+/**
+ * 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
+ */
+/** Normalize path separators to forward slashes for consistent comparison. */
+function normalizePath$1(p) {
+    return p.split(sep).join('/');
+}
+/**
+ * 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$1(mp),
+        ownerPath: normalizePath$1(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);
+}
+
+/**
+ * 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;
+    });
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Build the SynthContext 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 files via watcher scan, excluding child subtrees
+    const allScanFiles = await paginatedScan(watcher, {
+        pathPrefix: node.ownerPath,
+    });
+    const scopeFiles = filterInScope(node, allScanFiles.map((f) => f.file_path));
+    // Delta files: modified since _generatedAt
+    let deltaFiles;
+    if (meta._generatedAt) {
+        const modifiedAfter = Math.floor(new Date(meta._generatedAt).getTime() / 1000);
+        const deltaScanFiles = await paginatedScan(watcher, {
+            pathPrefix: node.ownerPath,
+            modifiedAfter,
+        });
+        deltaFiles = filterInScope(node, deltaScanFiles.map((f) => f.file_path));
+    }
+    else {
+        deltaFiles = scopeFiles; // First run: all files are delta
+    }
+    // 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');
+}
+
+/**
+ * Merge synthesis results into meta.json.
+ *
+ * Preserves human-set fields (_id, _steer, _depth).
+ * Writes engine fields (_generatedAt, _structureHash, etc.).
+ * Validates against schema before writing.
+ *
+ * @module orchestrator/merge
+ */
+/**
+ * Merge results into meta.json and write atomically.
+ *
+ * @param options - Merge options.
+ * @returns The updated MetaJson.
+ * @throws If validation fails (malformed output).
+ */
+function mergeAndWrite(options) {
+    const merged = {
+        // Preserve human-set fields
+        _id: options.current._id,
+        _steer: options.current._steer,
+        _depth: options.current._depth,
+        _emphasis: options.current._emphasis,
+        // Engine fields
+        _architect: options.architect,
+        _builder: options.builder,
+        _critic: options.critic,
+        _generatedAt: new Date().toISOString(),
+        _structureHash: options.structureHash,
+        _synthesisCount: options.synthesisCount,
+        // Token tracking
+        _architectTokens: options.architectTokens,
+        _builderTokens: options.builderTokens,
+        _criticTokens: options.criticTokens,
+        _architectTokensAvg: options.architectTokens !== undefined
+            ? computeEma(options.architectTokens, options.current._architectTokensAvg)
+            : options.current._architectTokensAvg,
+        _builderTokensAvg: options.builderTokens !== undefined
+            ? computeEma(options.builderTokens, options.current._builderTokensAvg)
+            : options.current._builderTokensAvg,
+        _criticTokensAvg: options.criticTokens !== undefined
+            ? computeEma(options.criticTokens, options.current._criticTokensAvg)
+            : options.current._criticTokensAvg,
+        // Content from builder
+        _content: options.builderOutput?.content ?? options.current._content,
+        // Feedback from critic
+        _feedback: options.feedback ?? options.current._feedback,
+        // Error handling
+        _error: options.error ?? undefined,
+        // Spread structured fields from builder
+        ...options.builderOutput?.fields,
+    };
+    // Clean up undefined optional fields
+    if (merged._steer === undefined)
+        delete merged._steer;
+    if (merged._depth === undefined)
+        delete merged._depth;
+    if (merged._emphasis === undefined)
+        delete merged._emphasis;
+    if (merged._architectTokens === undefined)
+        delete merged._architectTokens;
+    if (merged._builderTokens === undefined)
+        delete merged._builderTokens;
+    if (merged._criticTokens === undefined)
+        delete merged._criticTokens;
+    if (merged._architectTokensAvg === undefined)
+        delete merged._architectTokensAvg;
+    if (merged._builderTokensAvg === undefined)
+        delete merged._builderTokensAvg;
+    if (merged._criticTokensAvg === undefined)
+        delete merged._criticTokensAvg;
+    if (merged._error === undefined)
+        delete merged._error;
+    if (merged._content === undefined)
+        delete merged._content;
+    if (merged._feedback === undefined)
+        delete merged._feedback;
+    // Validate
+    const result = metaJsonSchema.safeParse(merged);
+    if (!result.success) {
+        throw new Error(`Meta validation failed: ${result.error.message}`);
+    }
+    // Write atomically
+    const filePath = join(options.metaPath, 'meta.json');
+    writeFileSync(filePath, JSON.stringify(result.data, null, 2) + '\n');
+    return result.data;
+}
+
+/**
+ * Shared error utilities.
+ *
+ * @module errors
+ */
+/**
+ * Wrap an unknown caught value into a SynthError.
+ *
+ * @param step - Which synthesis step failed.
+ * @param err - The caught error value.
+ * @param code - Error classification code.
+ * @returns A structured SynthError.
+ */
+function toSynthError(step, err, code = 'FAILED') {
+    return {
+        step,
+        code,
+        message: err instanceof Error ? err.message : String(err),
+    };
+}
+
+/**
+ * File-system lock for preventing concurrent synthesis on the same meta.
+ *
+ * Lock file: .meta/.lock containing PID + timestamp.
+ * Stale timeout: 30 minutes.
+ *
+ * @module lock
+ */
+const LOCK_FILE = '.lock';
+const STALE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+/**
+ * Attempt to acquire a lock on a .meta directory.
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @returns True if lock was acquired, false if already locked (non-stale).
+ */
+function acquireLock(metaPath) {
+    const lockPath = join(metaPath, LOCK_FILE);
+    if (existsSync(lockPath)) {
+        try {
+            const raw = readFileSync(lockPath, 'utf8');
+            const data = JSON.parse(raw);
+            const lockAge = Date.now() - new Date(data.startedAt).getTime();
+            if (lockAge < STALE_TIMEOUT_MS) {
+                return false; // Lock is active
+            }
+            // Stale lock — fall through to overwrite
+        }
+        catch {
+            // Corrupt lock file — overwrite
+        }
+    }
+    const lock = {
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+    };
+    writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n');
+    return true;
+}
+/**
+ * Release a lock on a .meta directory.
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ */
+function releaseLock(metaPath) {
+    const lockPath = join(metaPath, LOCK_FILE);
+    try {
+        unlinkSync(lockPath);
+    }
+    catch {
+        // Already removed or never existed
+    }
+}
+/**
+ * Check if a .meta directory is currently locked (non-stale).
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @returns True if locked and not stale.
+ */
+function isLocked(metaPath) {
+    const lockPath = join(metaPath, LOCK_FILE);
+    if (!existsSync(lockPath))
+        return false;
+    try {
+        const raw = readFileSync(lockPath, 'utf8');
+        const data = JSON.parse(raw);
+        const lockAge = Date.now() - new Date(data.startedAt).getTime();
+        return lockAge < STALE_TIMEOUT_MS;
+    }
+    catch {
+        return false; // Corrupt lock = not locked
+    }
+}
+
+/**
+ * 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('\\', '/');
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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),
+        };
+    });
+}
+
+/**
+ * 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');
+}
+
+/**
+ * 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: merge, snapshot, prune. */
+function finalizeCycle(metaPath, current, config, architect, builder, critic, builderOutput, feedback, structureHash, synthesisCount, error, architectTokens, builderTokens, criticTokens) {
+    const updated = mergeAndWrite({
+        metaPath,
+        current,
+        architect,
+        builder,
+        critic,
+        builderOutput,
+        feedback,
+        structureHash,
+        synthesisCount,
+        error,
+        architectTokens,
+        builderTokens,
+        criticTokens,
+    });
+    createSnapshot(metaPath, updated);
+    pruneArchive(metaPath, config.maxArchive);
+    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) {
+    // Step 1: Discover
+    const metaPaths = globMetas(config.watchPaths);
+    if (metaPaths.length === 0)
+        return { synthesized: false };
+    // Ensure all meta.json files exist
+    const metas = new Map();
+    for (const mp of metaPaths) {
+        metas.set(normalizePath(mp), ensureMetaJson(mp));
+    }
+    const tree = buildOwnershipTree(metaPaths);
+    // Steps 3-4: Staleness check + candidate selection
+    const candidates = [];
+    for (const node of tree.nodes.values()) {
+        const meta = metas.get(node.metaPath);
+        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)
+        return { synthesized: false };
+    const { node } = winner;
+    try {
+        // Re-read meta after lock (may have changed)
+        const currentMeta = JSON.parse(readFileSync(join(node.metaPath, 'meta.json'), 'utf8'));
+        const architectPrompt = currentMeta._architect ?? config.defaultArchitect;
+        const criticPrompt = currentMeta._critic ?? config.defaultCritic;
+        // Step 5: Structure hash
+        const scopePrefix = getScopePrefix(node);
+        const allScanFiles = await paginatedScan(watcher, {
+            pathPrefix: scopePrefix,
+        });
+        const allFilePaths = allScanFiles.map((f) => f.file_path);
+        // Structure hash uses scope-filtered files (excluding child subtrees)
+        // so changes in child scopes don't trigger parent architect re-runs
+        const scopeFiles = filterInScope(node, allFilePaths);
+        const newStructureHash = computeStructureHash(scopeFiles);
+        const structureChanged = newStructureHash !== currentMeta._structureHash;
+        // Step 6: Steer change detection
+        const latestArchive = readLatestArchive(node.metaPath);
+        const steerChanged = hasSteerChanged(currentMeta._steer, latestArchive?._steer, Boolean(latestArchive));
+        // Step 7: Compute context
+        const ctx = await buildContextPackage(node, currentMeta, watcher);
+        // 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 {
+                const architectTask = buildArchitectTask(ctx, currentMeta, config);
+                const architectResult = await executor.spawn(architectTask, {
+                    timeout: config.architectTimeout,
+                });
+                builderBrief = parseArchitectOutput(architectResult.output);
+                architectTokens = architectResult.tokens;
+                synthesisCount = 0;
+            }
+            catch (err) {
+                stepError = toSynthError('architect', err);
+                if (!currentMeta._builder) {
+                    // No cached builder — cycle fails
+                    finalizeCycle(node.metaPath, currentMeta, config, architectPrompt, '', criticPrompt, null, null, newStructureHash, synthesisCount, 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 {
+            const builderTask = buildBuilderTask(ctx, metaForBuilder, config);
+            const builderResult = await executor.spawn(builderTask, {
+                timeout: config.builderTimeout,
+            });
+            builderOutput = parseBuilderOutput(builderResult.output);
+            builderTokens = builderResult.tokens;
+            synthesisCount++;
+        }
+        catch (err) {
+            stepError = toSynthError('builder', err);
+            return { synthesized: true, metaPath: node.metaPath, error: stepError };
+        }
+        // Step 10: Critic
+        const metaForCritic = {
+            ...currentMeta,
+            _content: builderOutput.content,
+        };
+        let feedback = null;
+        try {
+            const criticTask = buildCriticTask(ctx, metaForCritic, config);
+            const criticResult = await executor.spawn(criticTask, {
+                timeout: config.criticTimeout,
+            });
+            feedback = parseCriticOutput(criticResult.output);
+            criticTokens = criticResult.tokens;
+            stepError = null; // Clear any architect error on full success
+        }
+        catch (err) {
+            stepError = stepError ?? toSynthError('critic', err);
+        }
+        // Steps 11-12: Merge, archive, prune
+        finalizeCycle(node.metaPath, currentMeta, config, architectPrompt, builderBrief, criticPrompt, builderOutput, feedback, newStructureHash, synthesisCount, stepError, architectTokens, builderTokens, criticTokens);
+        return {
+            synthesized: true,
+            metaPath: node.metaPath,
+            error: stepError ?? undefined,
+        };
+    }
+    finally {
+        // Step 13: Release lock
+        releaseLock(node.metaPath);
+    }
+}
+/**
+ * Run synthesis cycles up to batchSize.
+ *
+ * Calls orchestrateOnce() in a loop, stopping when batchSize is reached
+ * or no more candidates are available.
+ *
+ * @param config - Validated synthesis config.
+ * @param executor - Pluggable LLM executor.
+ * @param watcher - Watcher HTTP client.
+ * @returns Array of results, one per cycle attempted.
+ */
+async function orchestrate(config, executor, watcher) {
+    const results = [];
+    for (let i = 0; i < config.batchSize; i++) {
+        const result = await orchestrateOnce(config, executor, watcher);
+        results.push(result);
+        if (!result.synthesized)
+            break; // No more candidates
+    }
+    return results;
+}
+
+/**
+ * SynthExecutor implementation using the OpenClaw gateway HTTP API.
+ *
+ * Lives in the library package so both plugin and runner can import it.
+ * Spawns sub-agent sessions via the gateway, polls for completion,
+ * and extracts output text.
+ *
+ * @module executor/GatewayExecutor
+ */
+const DEFAULT_POLL_INTERVAL_MS = 5000;
+const DEFAULT_TIMEOUT_MS = 600_000; // 10 minutes
+/** Sleep helper. */
+function sleep$1(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * SynthExecutor that spawns OpenClaw sessions via the gateway HTTP API.
+ *
+ * Used by both the OpenClaw plugin (in-process tool calls) and the
+ * runner/CLI (external invocation). Constructs from `gatewayUrl` and
+ * optional `apiKey` — typically sourced from `SynthConfig`.
+ */
+class GatewayExecutor {
+    gatewayUrl;
+    apiKey;
+    pollIntervalMs;
+    constructor(options = {}) {
+        this.gatewayUrl = (options.gatewayUrl ?? 'http://127.0.0.1:3000').replace(/\/+$/, '');
+        this.apiKey = options.apiKey;
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    }
+    async spawn(task, options) {
+        const timeoutMs = (options?.timeout ?? DEFAULT_TIMEOUT_MS / 1000) * 1000;
+        const deadline = Date.now() + timeoutMs;
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (this.apiKey) {
+            headers['Authorization'] = 'Bearer ' + this.apiKey;
+        }
+        const spawnRes = await fetch(this.gatewayUrl + '/api/sessions/spawn', {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                task,
+                mode: 'run',
+                model: options?.model,
+                runTimeoutSeconds: options?.timeout,
+            }),
+        });
+        if (!spawnRes.ok) {
+            const text = await spawnRes.text();
+            throw new Error('Gateway spawn failed: HTTP ' +
+                spawnRes.status.toString() +
+                ' - ' +
+                text);
+        }
+        const spawnData = (await spawnRes.json());
+        if (!spawnData.sessionKey) {
+            throw new Error('Gateway spawn returned no sessionKey: ' + JSON.stringify(spawnData));
+        }
+        const { sessionKey } = spawnData;
+        // Poll for completion
+        while (Date.now() < deadline) {
+            await sleep$1(this.pollIntervalMs);
+            const historyRes = await fetch(this.gatewayUrl +
+                '/api/sessions/' +
+                encodeURIComponent(sessionKey) +
+                '/history?limit=50', { headers });
+            if (!historyRes.ok)
+                continue;
+            const history = (await historyRes.json());
+            if (history.status === 'completed' || history.status === 'done') {
+                // Extract token usage from session-level or message-level usage
+                let tokens;
+                if (history.usage?.totalTokens) {
+                    tokens = history.usage.totalTokens;
+                }
+                else {
+                    // Sum message-level usage as fallback
+                    let sum = 0;
+                    for (const msg of history.messages ?? []) {
+                        if (msg.usage?.totalTokens)
+                            sum += msg.usage.totalTokens;
+                    }
+                    if (sum > 0)
+                        tokens = sum;
+                }
+                // Extract the last assistant message as output
+                const messages = history.messages ?? [];
+                for (let i = messages.length - 1; i >= 0; i--) {
+                    if (messages[i].role === 'assistant' && messages[i].content) {
+                        return { output: messages[i].content, tokens };
+                    }
+                }
+                return { output: '', tokens };
+            }
+        }
+        throw new Error('Synthesis subprocess timed out after ' + timeoutMs.toString() + 'ms');
+    }
+}
+
+/**
+ * HTTP implementation of the WatcherClient interface.
+ *
+ * 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;
+/** Sleep for a given number of milliseconds. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** 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) {
+        const body = {};
+        if (params.pathPrefix !== undefined) {
+            body.pathPrefix = params.pathPrefix;
+        }
+        if (params.filter !== undefined) {
+            body.filter = params.filter;
+        }
+        if (params.modifiedAfter !== undefined) {
+            body.modifiedAfter = params.modifiedAfter;
+        }
+        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 result = await this.post('/scan', body);
+        return result;
+    }
+    async registerRules(source, rules) {
+        await this.post('/rules/register', { source, rules });
+    }
+    async unregisterRules(source) {
+        await this.post('/rules/unregister', { source });
+    }
+}
+
+/**
+ * Knowledge synthesis engine for the Jeeves platform.
+ *
+ * @packageDocumentation
+ */
+
+var index = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    GatewayExecutor: GatewayExecutor,
+    HttpWatcherClient: HttpWatcherClient,
+    acquireLock: acquireLock,
+    actualStaleness: actualStaleness,
+    buildArchitectTask: buildArchitectTask,
+    buildBuilderTask: buildBuilderTask,
+    buildContextPackage: buildContextPackage,
+    buildCriticTask: buildCriticTask,
+    buildOwnershipTree: buildOwnershipTree,
+    computeEffectiveStaleness: computeEffectiveStaleness,
+    computeEma: computeEma,
+    computeStructureHash: computeStructureHash,
+    createSnapshot: createSnapshot,
+    ensureMetaJson: ensureMetaJson,
+    filterInScope: filterInScope,
+    findNode: findNode,
+    getScopePrefix: getScopePrefix,
+    globMetas: globMetas,
+    hasSteerChanged: hasSteerChanged,
+    isArchitectTriggered: isArchitectTriggered,
+    isLocked: isLocked,
+    isStale: isStale,
+    listArchiveFiles: listArchiveFiles,
+    loadSynthConfig: loadSynthConfig,
+    mergeAndWrite: mergeAndWrite,
+    metaJsonSchema: metaJsonSchema,
+    normalizePath: normalizePath,
+    orchestrate: orchestrate,
+    paginatedScan: paginatedScan,
+    parseArchitectOutput: parseArchitectOutput,
+    parseBuilderOutput: parseBuilderOutput,
+    parseCriticOutput: parseCriticOutput,
+    pruneArchive: pruneArchive,
+    readLatestArchive: readLatestArchive,
+    releaseLock: releaseLock,
+    resolveConfigPath: resolveConfigPath,
+    selectCandidate: selectCandidate,
+    synthConfigSchema: synthConfigSchema,
+    synthErrorSchema: synthErrorSchema,
+    toSynthError: toSynthError
+});
+
+/**
+ * jeeves-meta CLI — ad hoc invocation, debugging, and maintenance.
+ *
+ * Usage:
+ *   npx \@karmaniverous/jeeves-meta <command> [options]
+ *
+ * Config resolution: --config <path> or JEEVES_META_CONFIG env var.
+ *
+ * @module cli
+ */
+const args = process.argv.slice(2);
+const command = args.find((a) => !a.startsWith('-'));
+const jsonOutput = args.includes('--json');
+function usage() {
+    console.log(`jeeves-meta — Knowledge synthesis engine CLI
+
+Usage: npx @karmaniverous/jeeves-meta <command> [options]
+
+Commands:
+  status                          Summary: total, stale, errors, tokens
+  list [--prefix <p>] [--filter <f>]  List metas with summary
+  detail <path> [--archive <n>]   Full detail for a single meta
+  preview [--path <p>]            Dry-run: what would the next cycle do
+  synthesize [--path <p>] [--batch <n>]  Run synthesis cycle(s)
+  seed <path>                     Create .meta/ directory with fresh meta.json
+  unlock <path>                   Force-remove stale .lock file
+  validate                        Validate config + check service reachability
+  config show                     Dump resolved config
+
+Root options:
+  --config <path>   Path to jeeves-meta.config.json (or JEEVES_META_CONFIG env)
+  --json            Output as JSON
+`);
+}
+function output(data) {
+    if (jsonOutput) {
+        console.log(JSON.stringify(data, null, 2));
+    }
+    else if (typeof data === 'string') {
+        console.log(data);
+    }
+    else {
+        console.log(JSON.stringify(data, null, 2));
+    }
+}
+function runStatus(config) {
+    const metaPaths = globMetas(config.watchPaths);
+    const tree = buildOwnershipTree(metaPaths);
+    let stale = 0;
+    let errors = 0;
+    let locked = 0;
+    let neverSynth = 0;
+    let archTokens = 0;
+    let buildTokens = 0;
+    let critTokens = 0;
+    for (const node of tree.nodes.values()) {
+        const meta = ensureMetaJson(node.metaPath);
+        const s = actualStaleness(meta);
+        if (s > 0)
+            stale++;
+        if (meta._error)
+            errors++;
+        if (isLocked(normalizePath(node.metaPath)))
+            locked++;
+        if (!meta._generatedAt)
+            neverSynth++;
+        if (meta._architectTokens)
+            archTokens += meta._architectTokens;
+        if (meta._builderTokens)
+            buildTokens += meta._builderTokens;
+        if (meta._criticTokens)
+            critTokens += meta._criticTokens;
+    }
+    output({
+        total: tree.nodes.size,
+        stale,
+        errors,
+        locked,
+        neverSynthesized: neverSynth,
+        tokens: { architect: archTokens, builder: buildTokens, critic: critTokens },
+    });
+}
+function runList(config) {
+    const prefix = getArg('--prefix');
+    const filter = getArg('--filter');
+    const metaPaths = globMetas(config.watchPaths);
+    const tree = buildOwnershipTree(metaPaths);
+    const rows = [];
+    for (const node of tree.nodes.values()) {
+        if (prefix && !node.metaPath.includes(prefix))
+            continue;
+        const meta = ensureMetaJson(node.metaPath);
+        const s = actualStaleness(meta);
+        const hasError = Boolean(meta._error);
+        const isLockedNow = isLocked(normalizePath(node.metaPath));
+        if (filter === 'hasError' && !hasError)
+            continue;
+        if (filter === 'stale' && s <= 0)
+            continue;
+        if (filter === 'locked' && !isLockedNow)
+            continue;
+        if (filter === 'never' && meta._generatedAt)
+            continue;
+        rows.push({
+            path: node.metaPath,
+            depth: meta._depth ?? node.treeDepth,
+            staleness: s === Infinity ? 'never' : String(Math.round(s)) + 's',
+            hasError,
+            locked: isLockedNow,
+            children: node.children.length,
+        });
+    }
+    output({ total: rows.length, items: rows });
+}
+async function runDetail(config) {
+    const targetPath = args.find((a) => !a.startsWith('-') && a !== 'detail');
+    if (!targetPath) {
+        console.error('Usage: jeeves-meta detail <path> [--archive <n>]');
+        process.exit(1);
+    }
+    const archiveArg = getArg('--archive');
+    const metaPaths = globMetas(config.watchPaths);
+    const tree = buildOwnershipTree(metaPaths);
+    const normalized = normalizePath(targetPath);
+    const node = findNode(tree, normalized);
+    if (!node) {
+        console.error('Meta not found: ' + targetPath);
+        process.exit(1);
+    }
+    const meta = ensureMetaJson(node.metaPath);
+    const result = { meta };
+    if (archiveArg) {
+        const { listArchiveFiles } = await Promise.resolve().then(function () { return index$1; });
+        const archiveFiles = listArchiveFiles(node.metaPath);
+        const limit = parseInt(archiveArg, 10) || archiveFiles.length;
+        const selected = archiveFiles.slice(-limit).reverse();
+        result.archive = selected.map((af) => {
+            const raw = readFileSync(join(node.metaPath, 'archive', af), 'utf8');
+            return JSON.parse(raw);
+        });
+    }
+    output(result);
+}
+async function runPreview(config) {
+    const targetPath = getArg('--path');
+    const { filterInScope, paginatedScan, readLatestArchive, computeStructureHash, selectCandidate, } = await Promise.resolve().then(function () { return index; });
+    const metaPaths = globMetas(config.watchPaths);
+    const tree = buildOwnershipTree(metaPaths);
+    const watcher = new HttpWatcherClient({ baseUrl: config.watcherUrl });
+    let targetNode;
+    if (targetPath) {
+        const normalized = normalizePath(targetPath);
+        targetNode = findNode(tree, normalized);
+        if (!targetNode) {
+            console.error('Meta not found: ' + targetPath);
+            process.exit(1);
+        }
+    }
+    else {
+        const candidates = [];
+        for (const node of tree.nodes.values()) {
+            const meta = ensureMetaJson(node.metaPath);
+            const s = actualStaleness(meta);
+            if (s > 0)
+                candidates.push({ node, meta, actualStaleness: s });
+        }
+        const weighted = computeEffectiveStaleness(candidates, config.depthWeight);
+        const winner = selectCandidate(weighted);
+        if (!winner) {
+            output({ message: 'No stale metas found.' });
+            return;
+        }
+        targetNode = winner.node;
+    }
+    const meta = ensureMetaJson(targetNode.metaPath);
+    const allFiles = await paginatedScan(watcher, {
+        pathPrefix: targetNode.ownerPath,
+    });
+    const scopeFiles = filterInScope(targetNode, allFiles.map((f) => f.file_path));
+    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);
+    output({
+        target: targetNode.metaPath,
+        ownerPath: targetNode.ownerPath,
+        depth: meta._depth ?? targetNode.treeDepth,
+        staleness: actualStaleness(meta) === Infinity
+            ? 'never'
+            : String(Math.round(actualStaleness(meta))) + 's',
+        scopeFiles: scopeFiles.length,
+        structureChanged,
+        steerChanged,
+        architectTriggered,
+    });
+}
+async function runSynthesize(config) {
+    const targetPath = getArg('--path');
+    const batchArg = getArg('--batch');
+    const effectiveConfig = {
+        ...config,
+        ...(targetPath
+            ? { watchPaths: [targetPath.replace(/[/\\]\.meta[/\\]?$/, '')] }
+            : {}),
+        ...(batchArg ? { batchSize: parseInt(batchArg, 10) } : {}),
+    };
+    const executor = new GatewayExecutor({
+        gatewayUrl: config.gatewayUrl,
+        apiKey: config.gatewayApiKey,
+    });
+    const watcher = new HttpWatcherClient({ baseUrl: config.watcherUrl });
+    const results = await orchestrate(effectiveConfig, executor, watcher);
+    const synthesized = results.filter((r) => r.synthesized);
+    output({
+        synthesizedCount: synthesized.length,
+        results: synthesized.map((r) => ({
+            metaPath: r.metaPath,
+            error: r.error ?? null,
+        })),
+    });
+}
+async function runSeed() {
+    const { mkdirSync, writeFileSync: writeFs } = await import('node:fs');
+    const { randomUUID } = await import('node:crypto');
+    const targetPath = args.find((a) => !a.startsWith('-') && a !== 'seed');
+    if (!targetPath) {
+        console.error('Usage: jeeves-meta seed <path>');
+        process.exit(1);
+    }
+    const metaDir = targetPath.endsWith('.meta')
+        ? targetPath
+        : join(targetPath, '.meta');
+    mkdirSync(metaDir, { recursive: true });
+    const metaFile = join(metaDir, 'meta.json');
+    writeFs(metaFile, JSON.stringify({ _id: randomUUID() }, null, 2) + '\n');
+    output({ created: metaFile });
+}
+async function runUnlock() {
+    const { unlinkSync } = await import('node:fs');
+    const targetPath = args.find((a) => !a.startsWith('-') && a !== 'unlock');
+    if (!targetPath) {
+        console.error('Usage: jeeves-meta unlock <path>');
+        process.exit(1);
+    }
+    const metaDir = targetPath.endsWith('.meta')
+        ? targetPath
+        : join(targetPath, '.meta');
+    const lockFile = join(metaDir, '.lock');
+    try {
+        unlinkSync(lockFile);
+        output({ unlocked: metaDir });
+    }
+    catch {
+        output({ message: 'No lock file found at ' + lockFile });
+    }
+}
+async function runValidate(config) {
+    const checks = {};
+    // Check watcher
+    try {
+        const res = await fetch(config.watcherUrl + '/status', {
+            signal: AbortSignal.timeout(5000),
+        });
+        checks.watcher = res.ok
+            ? 'OK (' + config.watcherUrl + ')'
+            : 'HTTP ' + res.status.toString();
+    }
+    catch {
+        checks.watcher = 'UNREACHABLE (' + config.watcherUrl + ')';
+    }
+    // Check gateway
+    try {
+        const res = await fetch(config.gatewayUrl + '/api/status', {
+            signal: AbortSignal.timeout(5000),
+        });
+        checks.gateway = res.ok
+            ? 'OK (' + config.gatewayUrl + ')'
+            : 'HTTP ' + res.status.toString();
+    }
+    catch {
+        checks.gateway = 'UNREACHABLE (' + config.gatewayUrl + ')';
+    }
+    // Check watch paths
+    const metaPaths = globMetas(config.watchPaths);
+    checks.metas = String(metaPaths.length) + ' .meta/ directories found';
+    output({ config: 'valid', checks });
+}
+function runConfigShow(config) {
+    // Show config with prompts truncated for readability
+    const display = {
+        ...config,
+        defaultArchitect: config.defaultArchitect.slice(0, 100) +
+            '... (' +
+            String(config.defaultArchitect.length) +
+            ' chars)',
+        defaultCritic: config.defaultCritic.slice(0, 100) +
+            '... (' +
+            String(config.defaultCritic.length) +
+            ' chars)',
+    };
+    output(display);
+}
+function getArg(flag) {
+    const idx = args.indexOf(flag);
+    if (idx !== -1 && args[idx + 1])
+        return args[idx + 1];
+    return undefined;
+}
+async function main() {
+    if (!command ||
+        command === 'help' ||
+        args.includes('--help') ||
+        args.includes('-h')) {
+        usage();
+        return;
+    }
+    // Commands that don't need config
+    if (command === 'seed') {
+        await runSeed();
+        return;
+    }
+    if (command === 'unlock') {
+        await runUnlock();
+        return;
+    }
+    // All other commands need config
+    let configPath;
+    try {
+        configPath = resolveConfigPath(args);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+    let config;
+    try {
+        config = loadSynthConfig(resolve(configPath));
+    }
+    catch (err) {
+        console.error('Failed to load config:', err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+    switch (command) {
+        case 'status':
+            runStatus(config);
+            break;
+        case 'list':
+            runList(config);
+            break;
+        case 'detail':
+            await runDetail(config);
+            break;
+        case 'preview':
+            await runPreview(config);
+            break;
+        case 'synthesize':
+            await runSynthesize(config);
+            break;
+        case 'validate':
+            await runValidate(config);
+            break;
+        case 'config':
+            if (args.includes('show')) {
+                runConfigShow(config);
+            }
+            else if (args.includes('check')) {
+                await runValidate(config);
+            }
+            else {
+                console.error('Unknown config subcommand. Use: config show, config check');
+                process.exit(1);
+            }
+            break;
+        default:
+            console.error('Unknown command: ' + command);
+            usage();
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});