@karmaniverous/jeeves-meta 0.15.3 → 0.15.4

package/dist/index.js

@@ -1,4 +1,4 @@
-import fs, { readdirSync, readFileSync, existsSync, writeFileSync, renameSync, unlinkSync, mkdirSync, copyFileSync, statSync, watchFile } from 'node:fs';
+import fs, { readdirSync, readFileSync, existsSync, writeFileSync, renameSync, unlinkSync, statSync, mkdirSync, copyFileSync, watchFile } from 'node:fs';
 import path, { join, dirname, resolve, basename, relative, posix } from 'node:path';
 import { unlink, readFile, mkdir, writeFile, copyFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
@@ -8116,381 +8116,120 @@ function registerCustomCliCommands(program) {
 }
 
 /**
- * Shared live config hot-reload support.
+ * Compute summary statistics from an array of MetaEntry objects.
  *
- * Used by both file-watch reloads in bootstrap and POST /config/apply
- * via the component descriptor's onConfigApply callback.
+ * Shared between listMetas() (full list) and route handlers (filtered lists).
  *
- * @module configHotReload
+ * @module discovery/computeSummary
  */
 /**
- * Fields that require a service restart to take effect.
+ * Compute summary statistics from a list of meta entries.
  *
- * Shared between the descriptor's `onConfigApply` and the file-watcher
- * hot-reload in `bootstrap.ts`.
+ * @param entries - Enriched meta entries (full or filtered).
+ * @param depthWeight - Config depth weight for effective staleness calculation.
+ * @returns Aggregated summary statistics.
  */
-const RESTART_REQUIRED_FIELDS = [
-    'port',
-    'watcherUrl',
-    'gatewayUrl',
-    'gatewayApiKey',
-    'defaultArchitect',
-    'defaultCritic',
-];
-let runtime = null;
-/** Register the active service runtime for config-apply hot reload. */
-function registerConfigHotReloadRuntime(nextRuntime) {
-    runtime = nextRuntime;
-}
-/** Apply hot-reloadable config changes to the live shared config object. */
-function applyHotReloadedConfig(newConfig) {
-    if (!runtime)
-        return;
-    const { config, logger, scheduler } = runtime;
-    for (const field of RESTART_REQUIRED_FIELDS) {
-        const oldVal = config[field];
-        const nextVal = newConfig[field];
-        if (oldVal !== nextVal) {
-            logger.warn({ field, oldValue: oldVal, newValue: nextVal }, 'Config field changed but requires restart to take effect');
-        }
-    }
-    if (newConfig.schedule !== config.schedule) {
-        scheduler?.updateSchedule(newConfig.schedule);
-        config.schedule = newConfig.schedule;
-        logger.info({ schedule: newConfig.schedule }, 'Schedule hot-reloaded');
-    }
-    if (newConfig.logging.level !== config.logging.level) {
-        logger.level = newConfig.logging.level;
-        config.logging.level = newConfig.logging.level;
-        logger.info({ level: newConfig.logging.level }, 'Log level hot-reloaded');
-    }
-    const restartSet = new Set(RESTART_REQUIRED_FIELDS);
-    for (const key of Object.keys(newConfig)) {
-        if (restartSet.has(key) || key === 'logging' || key === 'schedule') {
-            continue;
+function computeSummary(entries, depthWeight) {
+    let staleCount = 0;
+    let errorCount = 0;
+    let lockedCount = 0;
+    let disabledCount = 0;
+    let neverSynthesizedCount = 0;
+    let totalArchitectTokens = 0;
+    let totalBuilderTokens = 0;
+    let totalCriticTokens = 0;
+    let stalestPath = null;
+    let stalestEffective = -1;
+    let lastSynthesizedPath = null;
+    let lastSynthesizedAt = null;
+    for (const e of entries) {
+        if (e.stalenessSeconds > 0)
+            staleCount++;
+        if (e.hasError)
+            errorCount++;
+        if (e.locked)
+            lockedCount++;
+        if (e.disabled)
+            disabledCount++;
+        if (e.lastSynthesized === null)
+            neverSynthesizedCount++;
+        totalArchitectTokens += e.architectTokens ?? 0;
+        totalBuilderTokens += e.builderTokens ?? 0;
+        totalCriticTokens += e.criticTokens ?? 0;
+        // Track last synthesized
+        if (e.lastSynthesized &&
+            (!lastSynthesizedAt || e.lastSynthesized > lastSynthesizedAt)) {
+            lastSynthesizedAt = e.lastSynthesized;
+            lastSynthesizedPath = e.path;
         }
-        const oldVal = config[key];
-        const nextVal = newConfig[key];
-        if (JSON.stringify(oldVal) !== JSON.stringify(nextVal)) {
-            config[key] = nextVal;
-            logger.info({ field: key }, 'Config field hot-reloaded');
+        // Track stalest (effective staleness for scheduling)
+        const depthFactor = Math.pow(1 + depthWeight, e.depth);
+        const effectiveStaleness = e.stalenessSeconds * depthFactor * e.emphasis;
+        if (effectiveStaleness > stalestEffective) {
+            stalestEffective = effectiveStaleness;
+            stalestPath = e.path;
         }
     }
+    return {
+        total: entries.length,
+        stale: staleCount,
+        errors: errorCount,
+        locked: lockedCount,
+        disabled: disabledCount,
+        neverSynthesized: neverSynthesizedCount,
+        tokens: {
+            architect: totalArchitectTokens,
+            builder: totalBuilderTokens,
+            critic: totalCriticTokens,
+        },
+        stalestPath,
+        lastSynthesizedPath,
+        lastSynthesizedAt,
+    };
 }
 
 /**
- * Zod schema for jeeves-meta service configuration.
+ * Discover .meta/ directories via watcher `/walk` endpoint.
  *
- * The service config is a strict superset of the core (library-compatible) meta config.
+ * Uses filesystem enumeration through the watcher (not Qdrant) to find
+ * all `.meta/meta.json` files and returns deduplicated meta directory paths.
  *
- * @module schema/config
+ * @module discovery/discoverMetas
  */
-/** 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(180),
-    /** Builder subprocess timeout in seconds. */
-    builderTimeout: z.number().int().min(60).default(360),
-    /** Critic subprocess timeout in seconds. */
-    criticTimeout: z.number().int().min(30).default(240),
-    /** Thinking level for spawned synthesis sessions. */
-    thinking: z.string().default('low'),
-    /** Resolved architect system prompt text. Falls back to built-in default. */
-    defaultArchitect: z.string().optional(),
-    /** Resolved critic system prompt text. Falls back to built-in default. */
-    defaultCritic: z.string().optional(),
-    /** 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 a single auto-seed policy rule. */
-const autoSeedRuleSchema = z.object({
-    /** Glob pattern matched against watcher walk results. */
-    match: z.string(),
-    /** Optional steering prompt for seeded metas. */
-    steer: z.string().optional(),
-    /** Optional cross-references for seeded metas. */
-    crossRefs: z.array(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 * * * *'),
-    /** Messaging channel name (e.g. 'slack'). Legacy: also used as target if reportTarget is unset. */
-    reportChannel: z.string().optional(),
-    /** Channel/user ID to send progress messages to. */
-    reportTarget: z.string().optional(),
-    /** Optional base URL for the service, used to construct entity links in progress reports. */
-    serverBaseUrl: z.string().optional(),
-    /** Interval in ms for periodic watcher health check. 0 = disabled. Default: 60000. */
-    watcherHealthIntervalMs: z.number().int().min(0).default(60_000),
-    /** Logging configuration. */
-    logging: loggingSchema.default(() => loggingSchema.parse({})),
-    /**
-     * Auto-seed policy: declarative rules for auto-creating .meta/ directories.
-     * Rules are evaluated in order; last match wins for steer/crossRefs.
-     */
-    autoSeed: z.array(autoSeedRuleSchema).optional().default([]),
-});
-
 /**
- * Load and resolve jeeves-meta service config.
- *
- * Supports \@file: indirection and environment-variable substitution (dollar-brace pattern).
+ * Discover all .meta/ directories via watcher walk.
  *
- * @module configLoader
- */
-/**
- * Deep-walk a value, replacing `\${VAR\}` patterns with process.env values.
+ * Uses the watcher's `/walk` endpoint to find all `.meta/meta.json` files
+ * and returns deduplicated meta directory paths.
  *
- * @param value - Arbitrary JSON-compatible value.
- * @returns Value with env-var placeholders resolved.
+ * @param watcher - WatcherClient for walk queries.
+ * @returns Array of normalized .meta/ directory paths.
  */
-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;
+async function discoverMetas(watcher) {
+    const allPaths = await watcher.walk(['**/.meta/meta.json']);
+    // Deduplicate by .meta/ directory path (handles multi-chunk files)
+    const seen = new Set();
+    const metaPaths = [];
+    for (const filePath of allPaths) {
+        const fp = normalizePath(filePath);
+        // Derive .meta/ directory from file_path (strip /meta.json)
+        const metaPath = fp.replace(/\/meta\.json$/, '');
+        if (seen.has(metaPath))
+            continue;
+        seen.add(metaPath);
+        metaPaths.push(metaPath);
     }
-    return value;
+    return metaPaths;
 }
+
 /**
- * Resolve \@file: references in a config value.
+ * File-system lock for preventing concurrent synthesis on the same meta.
  *
- * @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');
-}
-/**
- * Migrate legacy config path to the new canonical location.
- *
- * If the old path `{configRoot}/jeeves-meta.config.json` exists and the new
- * path `{configRoot}/jeeves-meta/config.json` does NOT exist, copies the file
- * to the new location and logs a warning.
- *
- * @param configRoot - Root directory for configuration files.
- * @param warn - Optional callback for logging the migration warning.
- */
-function migrateConfigPath(configRoot, warn) {
-    const oldPath = join(configRoot, 'jeeves-meta.config.json');
-    const newDir = join(configRoot, 'jeeves-meta');
-    const newPath = join(newDir, 'config.json');
-    if (existsSync(oldPath) && !existsSync(newPath)) {
-        mkdirSync(newDir, { recursive: true });
-        copyFileSync(oldPath, newPath);
-        const message = `Migrated config from ${oldPath} to ${newPath}. The old file can be removed.`;
-        if (warn) {
-            warn(message);
-        }
-        else {
-            console.warn(`[jeeves-meta] ${message}`);
-        }
-    }
-}
-/**
- * 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);
-}
-
-/**
- * Compute summary statistics from an array of MetaEntry objects.
- *
- * Shared between listMetas() (full list) and route handlers (filtered lists).
- *
- * @module discovery/computeSummary
- */
-/**
- * Compute summary statistics from a list of meta entries.
- *
- * @param entries - Enriched meta entries (full or filtered).
- * @param depthWeight - Config depth weight for effective staleness calculation.
- * @returns Aggregated summary statistics.
- */
-function computeSummary(entries, depthWeight) {
-    let staleCount = 0;
-    let errorCount = 0;
-    let lockedCount = 0;
-    let disabledCount = 0;
-    let neverSynthesizedCount = 0;
-    let totalArchitectTokens = 0;
-    let totalBuilderTokens = 0;
-    let totalCriticTokens = 0;
-    let stalestPath = null;
-    let stalestEffective = -1;
-    let lastSynthesizedPath = null;
-    let lastSynthesizedAt = null;
-    for (const e of entries) {
-        if (e.stalenessSeconds > 0)
-            staleCount++;
-        if (e.hasError)
-            errorCount++;
-        if (e.locked)
-            lockedCount++;
-        if (e.disabled)
-            disabledCount++;
-        if (e.lastSynthesized === null)
-            neverSynthesizedCount++;
-        totalArchitectTokens += e.architectTokens ?? 0;
-        totalBuilderTokens += e.builderTokens ?? 0;
-        totalCriticTokens += e.criticTokens ?? 0;
-        // Track last synthesized
-        if (e.lastSynthesized &&
-            (!lastSynthesizedAt || e.lastSynthesized > lastSynthesizedAt)) {
-            lastSynthesizedAt = e.lastSynthesized;
-            lastSynthesizedPath = e.path;
-        }
-        // Track stalest (effective staleness for scheduling)
-        const depthFactor = Math.pow(1 + depthWeight, e.depth);
-        const effectiveStaleness = e.stalenessSeconds * depthFactor * e.emphasis;
-        if (effectiveStaleness > stalestEffective) {
-            stalestEffective = effectiveStaleness;
-            stalestPath = e.path;
-        }
-    }
-    return {
-        total: entries.length,
-        stale: staleCount,
-        errors: errorCount,
-        locked: lockedCount,
-        disabled: disabledCount,
-        neverSynthesized: neverSynthesizedCount,
-        tokens: {
-            architect: totalArchitectTokens,
-            builder: totalBuilderTokens,
-            critic: totalCriticTokens,
-        },
-        stalestPath,
-        lastSynthesizedPath,
-        lastSynthesizedAt,
-    };
-}
-
-/**
- * Discover .meta/ directories via watcher `/walk` endpoint.
- *
- * Uses filesystem enumeration through the watcher (not Qdrant) to find
- * all `.meta/meta.json` files and returns deduplicated meta directory paths.
- *
- * @module discovery/discoverMetas
- */
-/**
- * Discover all .meta/ directories via watcher walk.
- *
- * Uses the watcher's `/walk` endpoint to find all `.meta/meta.json` files
- * and returns deduplicated meta directory paths.
- *
- * @param watcher - WatcherClient for walk queries.
- * @returns Array of normalized .meta/ directory paths.
- */
-async function discoverMetas(watcher) {
-    const allPaths = await watcher.walk(['**/.meta/meta.json']);
-    // Deduplicate by .meta/ directory path (handles multi-chunk files)
-    const seen = new Set();
-    const metaPaths = [];
-    for (const filePath of allPaths) {
-        const fp = normalizePath(filePath);
-        // Derive .meta/ directory from file_path (strip /meta.json)
-        const metaPath = fp.replace(/\/meta\.json$/, '');
-        if (seen.has(metaPath))
-            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
+ * 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';
 /**
@@ -9030,1483 +8769,928 @@ function getDeltaFiles(generatedAt, scopeFiles) {
 }
 
 /**
- * Error thrown when a spawned subprocess is aborted via AbortController.
+ * In-memory cache for listMetas results with TTL and concurrent refresh guard.
  *
- * @module executor/SpawnAbortedError
+ * @module cache
  */
-/** Error indicating a spawn was deliberately aborted. */
-class SpawnAbortedError extends Error {
-    constructor(message = 'Synthesis was aborted') {
-        super(message);
-        this.name = 'SpawnAbortedError';
-    }
-}
-
+const TTL_MS = 60_000;
 /**
- * Error thrown when a spawned subprocess times out.
- *
- * Carries the output file path so callers can attempt partial output recovery.
- *
- * @module executor/SpawnTimeoutError
+ * Caches listMetas results to avoid expensive repeated filesystem walks.
+ * Supports concurrent refresh coalescing and manual invalidation.
  */
-/** Error indicating a spawn timeout with a recoverable output path. */
-class SpawnTimeoutError extends Error {
-    /** Path to the (possibly partial) output file written before timeout. */
-    outputPath;
-    constructor(message, outputPath) {
-        super(message);
-        this.name = 'SpawnTimeoutError';
-        this.outputPath = outputPath;
+class MetaCache {
+    result = null;
+    updatedAt = 0;
+    refreshPromise = null;
+    /** Get cached result or refresh if stale. */
+    async get(config, watcher) {
+        if (this.result && Date.now() - this.updatedAt < TTL_MS) {
+            return this.result;
+        }
+        return this.refresh(config, watcher);
+    }
+    /** Force-expire the cache so next get() triggers a refresh. */
+    invalidate() {
+        this.updatedAt = 0;
+    }
+    async refresh(config, watcher) {
+        if (this.refreshPromise)
+            return this.refreshPromise;
+        this.refreshPromise = listMetas(config, watcher)
+            .then((result) => {
+            this.result = result;
+            this.updatedAt = Date.now();
+            return result;
+        })
+            .finally(() => {
+            this.refreshPromise = null;
+        });
+        return this.refreshPromise;
     }
 }
 
 /**
- * MetaExecutor implementation using the OpenClaw gateway HTTP API.
+ * Shared live config hot-reload support.
  *
- * 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.
+ * Used by both file-watch reloads in bootstrap and POST /config/apply
+ * via the component descriptor's onConfigApply callback.
  *
- * @module executor/GatewayExecutor
+ * @module configHotReload
  */
-const DEFAULT_POLL_INTERVAL_MS = 5000;
-const DEFAULT_TIMEOUT_MS$1 = 600_000; // 10 minutes
 /**
- * MetaExecutor that spawns OpenClaw sessions via the gateway's
- * `/tools/invoke` endpoint.
+ * Fields that require a service restart to take effect.
  *
- * 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`.
+ * Shared between the descriptor's `onConfigApply` and the file-watcher
+ * hot-reload in `bootstrap.ts`.
  */
-class GatewayExecutor {
-    gatewayUrl;
-    apiKey;
-    pollIntervalMs;
-    workspaceDir;
-    controller = new AbortController();
-    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;
-        this.workspaceDir = options.workspaceDir ?? join(tmpdir(), 'jeeves-meta');
-    }
-    /** Remove a temp output file if it exists. */
-    cleanupOutputFile(outputPath) {
-        try {
-            if (existsSync(outputPath))
-                unlinkSync(outputPath);
-        }
-        catch {
-            /* best-effort cleanup */
-        }
-    }
-    /** Invoke a gateway tool via the /tools/invoke HTTP endpoint. */
-    async invoke(tool, args, sessionKey) {
-        const headers = {
-            'Content-Type': 'application/json',
-        };
-        if (this.apiKey) {
-            headers['Authorization'] = 'Bearer ' + this.apiKey;
-        }
-        const body = { tool, args };
-        if (sessionKey)
-            body.sessionKey = sessionKey;
-        const res = await fetch(this.gatewayUrl + '/tools/invoke', {
-            method: 'POST',
-            headers,
-            body: JSON.stringify(body),
-        });
-        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;
-    }
-    /** Look up totalTokens for a session via sessions_list. */
-    async getSessionTokens(sessionKey) {
-        try {
-            const result = await this.invoke('sessions_list', {
-                limit: 20,
-                messageLimit: 0,
-            });
-            const sessions = (result.result?.details?.sessions ??
-                result.result?.sessions ??
-                []);
-            const match = sessions.find((s) => s.key === sessionKey);
-            return match?.totalTokens ?? undefined;
-        }
-        catch {
-            return undefined;
+const RESTART_REQUIRED_FIELDS = [
+    'port',
+    'watcherUrl',
+    'gatewayUrl',
+    'gatewayApiKey',
+    'defaultArchitect',
+    'defaultCritic',
+];
+let runtime = null;
+/** Register the active service runtime for config-apply hot reload. */
+function registerConfigHotReloadRuntime(nextRuntime) {
+    runtime = nextRuntime;
+}
+/** Apply hot-reloadable config changes to the live shared config object. */
+function applyHotReloadedConfig(newConfig) {
+    if (!runtime)
+        return;
+    const { config, logger, scheduler } = runtime;
+    for (const field of RESTART_REQUIRED_FIELDS) {
+        const oldVal = config[field];
+        const nextVal = newConfig[field];
+        if (oldVal !== nextVal) {
+            logger.warn({ field, oldValue: oldVal, newValue: nextVal }, 'Config field changed but requires restart to take effect');
         }
     }
-    /** Whether this executor has been aborted by the operator. */
-    get aborted() {
-        return this.controller.signal.aborted;
+    if (newConfig.schedule !== config.schedule) {
+        scheduler?.updateSchedule(newConfig.schedule);
+        config.schedule = newConfig.schedule;
+        logger.info({ schedule: newConfig.schedule }, 'Schedule hot-reloaded');
     }
-    /** Abort the currently running spawn, if any. */
-    abort() {
-        this.controller.abort();
+    if (newConfig.logging.level !== config.logging.level) {
+        logger.level = newConfig.logging.level;
+        config.logging.level = newConfig.logging.level;
+        logger.info({ level: newConfig.logging.level }, 'Log level hot-reloaded');
     }
-    async spawn(task, options) {
-        // Fresh controller for each spawn call
-        this.controller = new AbortController();
-        const timeoutSeconds = options?.timeout ?? DEFAULT_TIMEOUT_MS$1 / 1000;
-        const timeoutMs = timeoutSeconds * 1000;
-        const deadline = Date.now() + timeoutMs;
-        // Ensure workspace dir exists
-        if (!existsSync(this.workspaceDir)) {
-            mkdirSync(this.workspaceDir, { recursive: true });
-        }
-        // Generate unique output path for file-based output
-        const outputId = randomUUID();
-        const outputPath = this.workspaceDir + '/output-' + outputId + '.json';
-        // Append file output instruction to the task
-        const taskWithOutput = task +
-            '\n\n## OUTPUT DELIVERY\n\n' +
-            'Write your complete output to a file using the Write tool at:\n' +
-            outputPath +
-            '\n\n' +
-            'After writing the file, reply with ONLY: NO_REPLY';
-        // Step 1: Spawn the sub-agent session (unique label per cycle to avoid
-        // "label already in use" errors — gateway labels persist after session completion)
-        const labelBase = options?.label ?? 'jeeves-meta-synthesis';
-        const label = labelBase + '-' + outputId.slice(0, 8);
-        const spawnResult = await this.invoke('sessions_spawn', {
-            task: taskWithOutput,
-            label,
-            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));
+    const restartSet = new Set(RESTART_REQUIRED_FIELDS);
+    for (const key of Object.keys(newConfig)) {
+        if (restartSet.has(key) || key === 'logging' || key === 'schedule') {
+            continue;
         }
-        // Step 2: Poll for completion via sessions_history
-        await sleepAsync(3000);
-        while (Date.now() < deadline) {
-            // Check for abort before each poll iteration
-            if (this.controller.signal.aborted) {
-                this.cleanupOutputFile(outputPath);
-                throw new SpawnAbortedError();
-            }
-            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') {
-                        // Fetch token usage from session metadata
-                        const tokens = await this.getSessionTokens(sessionKey);
-                        // Read output from file (sub-agent wrote it via Write tool)
-                        if (existsSync(outputPath)) {
-                            try {
-                                const output = readFileSync(outputPath, 'utf8');
-                                return { output, tokens };
-                            }
-                            finally {
-                                try {
-                                    unlinkSync(outputPath);
-                                }
-                                catch {
-                                    /* cleanup best-effort */
-                                }
-                            }
-                        }
-                        // Fallback: extract from message content if file wasn't written
-                        for (let i = msgArray.length - 1; i >= 0; i--) {
-                            const msg = msgArray[i];
-                            if (msg.role === 'assistant' && msg.content) {
-                                const text = typeof msg.content === 'string'
-                                    ? msg.content
-                                    : Array.isArray(msg.content)
-                                        ? msg.content
-                                            .filter((b) => b.type === 'text' && b.text)
-                                            .map((b) => b.text)
-                                            .join('\n')
-                                        : '';
-                                if (text)
-                                    return { output: text, tokens };
-                            }
-                        }
-                        return { output: '', tokens };
-                    }
-                }
-            }
-            catch {
-                // Transient poll failure — keep trying
-            }
-            await sleepAsync(this.pollIntervalMs);
+        const oldVal = config[key];
+        const nextVal = newConfig[key];
+        if (JSON.stringify(oldVal) !== JSON.stringify(nextVal)) {
+            config[key] = nextVal;
+            logger.info({ field: key }, 'Config field hot-reloaded');
         }
-        throw new SpawnTimeoutError('Synthesis subprocess timed out after ' + timeoutMs.toString() + 'ms', outputPath);
     }
 }
 
 /**
- * Pino logger factory.
+ * Zod schema for jeeves-meta service configuration.
  *
- * @module logger
- */
-/**
- * Create a pino logger instance.
+ * The service config is a strict superset of the core (library-compatible) meta config.
  *
- * @param config - Optional logger configuration.
- * @returns Configured pino logger.
+ * @module schema/config
  */
-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 });
-}
+/** 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(180),
+    /** Builder subprocess timeout in seconds. */
+    builderTimeout: z.number().int().min(60).default(360),
+    /** Critic subprocess timeout in seconds. */
+    criticTimeout: z.number().int().min(30).default(240),
+    /** Thinking level for spawned synthesis sessions. */
+    thinking: z.string().default('low'),
+    /** Resolved architect system prompt text. Falls back to built-in default. */
+    defaultArchitect: z.string().optional(),
+    /** Resolved critic system prompt text. Falls back to built-in default. */
+    defaultCritic: z.string().optional(),
+    /** 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 a single auto-seed policy rule. */
+const autoSeedRuleSchema = z.object({
+    /** Glob pattern matched against watcher walk results. */
+    match: z.string(),
+    /** Optional steering prompt for seeded metas. */
+    steer: z.string().optional(),
+    /** Optional cross-references for seeded metas. */
+    crossRefs: z.array(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 * * * *'),
+    /** Messaging channel name (e.g. 'slack'). Legacy: also used as target if reportTarget is unset. */
+    reportChannel: z.string().optional(),
+    /** Channel/user ID to send progress messages to. */
+    reportTarget: z.string().optional(),
+    /** Optional base URL for the service, used to construct entity links in progress reports. */
+    serverBaseUrl: z.string().optional(),
+    /** Interval in ms for periodic watcher health check. 0 = disabled. Default: 60000. */
+    watcherHealthIntervalMs: z.number().int().min(0).default(60_000),
+    /** Logging configuration. */
+    logging: loggingSchema.default(() => loggingSchema.parse({})),
+    /**
+     * Auto-seed policy: declarative rules for auto-creating .meta/ directories.
+     * Rules are evaluated in order; last match wins for steer/crossRefs.
+     */
+    autoSeed: z.array(autoSeedRuleSchema).optional().default([]),
+});
 
 /**
- * Built-in default prompts for the synthesis pipeline.
+ * Load and resolve jeeves-meta service config.
  *
- * Prompts ship as .md files bundled into dist/prompts/ via rollup-plugin-copy.
- * Loaded at runtime relative to the compiled module location.
- *
- * Users can override via `defaultArchitect` / `defaultCritic` in the service
- * config. Most installations should use the built-in defaults.
- *
- * @module prompts
- */
-const packageRoot = packageDirectorySync({
-    cwd: fileURLToPath(import.meta.url),
-});
-const promptDir = join(packageRoot, 'dist', 'prompts');
-/** Built-in default architect prompt. */
-const DEFAULT_ARCHITECT_PROMPT = readFileSync(join(promptDir, 'architect.md'), 'utf8');
-/** Built-in default critic prompt. */
-const DEFAULT_CRITIC_PROMPT = readFileSync(join(promptDir, 'critic.md'), 'utf8');
-
-/**
- * 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');
-}
-/**
- * Read a meta.json file and extract its `_content` field.
- *
- * @param metaJsonPath - Absolute path to a meta.json file.
- * @returns The `_content` string, or null if missing/unreadable.
- */
-async function readMetaContent(metaJsonPath) {
-    try {
-        const raw = await readFile(metaJsonPath, 'utf8');
-        const meta = JSON.parse(raw);
-        return meta._content ?? null;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * 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, logger) {
-    // Scope and delta files via watcher walk
-    const scopeStart = Date.now();
-    const { scopeFiles } = await getScopeFiles(node, watcher, logger);
-    const deltaFiles = getDeltaFiles(meta._generatedAt, scopeFiles);
-    logger?.debug({
-        scopeFiles: scopeFiles.length,
-        deltaFiles: deltaFiles.length,
-        durationMs: Date.now() - scopeStart,
-    }, 'scope and delta files computed');
-    // Child meta outputs (parallel reads)
-    const childMetas = {};
-    const childEntries = await Promise.all(node.children.map(async (child) => {
-        const content = await readMetaContent(join(child.metaPath, 'meta.json'));
-        return [child.ownerPath, content];
-    }));
-    for (const [path, content] of childEntries) {
-        childMetas[path] = content;
-    }
-    // Cross-referenced meta outputs (parallel reads)
-    const crossRefMetas = {};
-    const seen = new Set();
-    const crossRefPaths = [];
-    for (const refPath of meta._crossRefs ?? []) {
-        if (refPath === node.ownerPath || refPath === node.metaPath)
-            continue;
-        if (seen.has(refPath))
-            continue;
-        seen.add(refPath);
-        crossRefPaths.push(refPath);
-    }
-    const crossRefEntries = await Promise.all(crossRefPaths.map(async (refPath) => {
-        const content = await readMetaContent(join(refPath, '.meta', 'meta.json'));
-        return [refPath, content];
-    }));
-    for (const [path, content] of crossRefEntries) {
-        crossRefMetas[path] = content;
-    }
-    // Archive paths
-    const archives = listArchiveFiles(node.metaPath);
-    return {
-        path: node.metaPath,
-        scopeFiles,
-        deltaFiles,
-        childMetas,
-        crossRefMetas,
-        previousContent: meta._content ?? null,
-        previousFeedback: meta._feedback ?? null,
-        steer: meta._steer ?? null,
-        previousState: meta._state ?? null,
-        archives,
-    };
-}
-
-/**
- * Build task prompts for each synthesis step.
- *
- * Prompts are compiled as Handlebars templates with access to config,
- * meta, and scope context. The architect can write template expressions
- * into its _builder output; these resolve when the builder task is compiled.
+ * Supports \@file: indirection and environment-variable substitution (dollar-brace pattern).
  *
- * @module orchestrator/buildTask
+ * @module configLoader
  */
-/** Build the template context from synthesis inputs. */
-function buildTemplateContext(ctx, meta, config) {
-    return {
-        config,
-        meta,
-        scope: {
-            fileCount: ctx.scopeFiles.length,
-            deltaCount: ctx.deltaFiles.length,
-            childCount: Object.keys(ctx.childMetas).length,
-            crossRefCount: Object.keys(ctx.crossRefMetas).length,
-        },
-    };
-}
 /**
- * Compile a string as a Handlebars template with the given context.
- * Returns the original string unchanged if compilation fails.
- */
-function compileTemplate(text, context) {
-    try {
-        return Handlebars.compile(text, { noEscape: true })(context);
-    }
-    catch {
-        return text;
-    }
-}
-/** Append a keyed record of meta outputs as subsections, if non-empty. */
-function appendMetaSections(sections, heading, metas) {
-    if (Object.keys(metas).length === 0)
-        return;
-    sections.push('', heading);
-    for (const [path, content] of Object.entries(metas)) {
-        sections.push(`### ${path}`, typeof content === 'string' ? content : '(not yet synthesized)');
-    }
-}
-/** 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,
-        includeCrossRefs: 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) {
-        appendMetaSections(sections, '## CHILD META OUTPUTS', ctx.childMetas);
-    }
-    if (opts.includeCrossRefs) {
-        appendMetaSections(sections, '## CROSS-REFERENCED METAS', ctx.crossRefMetas);
-    }
-}
-/**
- * Build the architect task prompt.
+ * Deep-walk a value, replacing `\${VAR\}` patterns with process.env values.
  *
- * @param ctx - Synthesis context.
- * @param meta - Current meta.json.
- * @param config - Synthesis config.
- * @returns The architect task prompt string.
+ * @param value - Arbitrary JSON-compatible value.
+ * @returns Value with env-var placeholders resolved.
  */
-function buildArchitectTask(ctx, meta, config) {
-    const sections = [
-        `# jeeves-meta · ARCHITECT · ${ctx.path}`,
-        '',
-        meta._architect ?? config.defaultArchitect ?? DEFAULT_ARCHITECT_PROMPT,
-        '',
-        '## 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);
+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;
+        });
     }
-    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.');
+    if (Array.isArray(value)) {
+        return value.map(substituteEnvVars);
     }
-    return compileTemplate(sections.join('\n'), buildTemplateContext(ctx, meta, config));
-}
-/**
- * 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 = [
-        `# jeeves-meta · BUILDER · ${ctx.path}`,
-        '',
-        '## 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}`),
-    ];
-    if (ctx.previousState != null) {
-        sections.push('', '## PREVIOUS STATE', 'The following opaque state was returned by the previous synthesis cycle.', 'Use it to continue progressive work. Update `_state` in your output to', 'reflect your progress.', '', '```json', JSON.stringify(ctx.previousState, null, 2), '```');
+    if (value !== null && typeof value === 'object') {
+        const result = {};
+        for (const [key, val] of Object.entries(value)) {
+            result[key] = substituteEnvVars(val);
+        }
+        return result;
     }
-    appendSharedSections(sections, ctx, {
-        includeSteer: false,
-        feedbackHeading: '## FEEDBACK FROM CRITIC',
-    });
-    sections.push('', '## OUTPUT FORMAT', '', 'Respond with ONLY a JSON object. No explanation, no markdown fences, no text before or after.', '', 'Required schema:', '{', '  "type": "object",', '  "required": ["_content"],', '  "properties": {', '    "_content": { "type": "string", "description": "Markdown narrative synthesis" },', '    "_state": { "description": "Opaque state object for progressive work across cycles" }', '  },', '  "additionalProperties": true', '}', '', 'Add any structured fields that capture important facts about this entity', '(e.g. status, risks, dependencies, metrics). Use descriptive key names without underscore prefix.', 'The _content field is the only required key — everything else is domain-driven.', '_state is optional: set it to carry state across synthesis cycles for progressive work.', '', 'DIAGRAMS: When diagrams would aid understanding, use PlantUML in fenced code blocks (```plantuml).', 'PlantUML is rendered natively by the serving infrastructure. NEVER use ASCII art diagrams.');
-    return compileTemplate(sections.join('\n'), buildTemplateContext(ctx, meta, config));
-}
-/**
- * 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 = [
-        `# jeeves-meta · CRITIC · ${ctx.path}`,
-        '',
-        meta._critic ?? config.defaultCritic ?? DEFAULT_CRITIC_PROMPT,
-        '',
-        '## 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,
-        includeCrossRefs: false,
-    });
-    sections.push('', '## OUTPUT FORMAT', 'Return your evaluation as Markdown text. Be specific and actionable.');
-    return compileTemplate(sections.join('\n'), buildTemplateContext(ctx, meta, config));
+    return value;
 }
-
-/**
- * Exponential moving average helper for token tracking.
- *
- * @module ema
- */
-const DEFAULT_DECAY = 0.3;
 /**
- * Compute exponential moving average.
+ * Resolve \@file: references in a config value.
  *
- * @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.
+ * @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 computeEma(current, previous, decay = DEFAULT_DECAY) {
-    if (previous === undefined)
-        return current;
-    return decay * current + (1 - decay) * previous;
+function resolveFileRef(value, baseDir) {
+    if (!value.startsWith('@file:'))
+        return value;
+    const filePath = join(baseDir, value.slice(6));
+    return readFileSync(filePath, 'utf8');
 }
-
-/**
- * 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.
+ * Migrate legacy config path to the new canonical location.
  *
- * Reserved properties are underscore-prefixed and engine-managed.
- * All other keys are open schema (builder output).
+ * If the old path `{configRoot}/jeeves-meta.config.json` exists and the new
+ * path `{configRoot}/jeeves-meta/config.json` does NOT exist, copies the file
+ * to the new location and logs a warning.
  *
- * @module schema/meta
+ * @param configRoot - Root directory for configuration files.
+ * @param warn - Optional callback for logging the migration warning.
  */
-/** Valid states for a synthesis phase. */
-const phaseStatuses = [
-    'fresh',
-    'stale',
-    'pending',
-    'running',
-    'failed',
-];
-/** Zod schema for a per-phase status value. */
-const phaseStatusSchema = z.enum(phaseStatuses);
-/** Zod schema for the per-meta phase state record. */
-const phaseStateSchema = z.object({
-    architect: phaseStatusSchema,
-    builder: phaseStatusSchema,
-    critic: phaseStatusSchema,
-});
-/** Zod schema for the reserved (underscore-prefixed) meta.json properties. */
-const metaJsonSchema = z
-    .object({
-    /** Stable identity. Auto-generated on first synthesis if not provided. */
-    _id: z.uuid().optional(),
-    /** Human-provided steering prompt. Optional. */
-    _steer: z.string().optional(),
-    /**
-     * Explicit cross-references to other meta owner paths.
-     * Referenced metas' _content is included as architect/builder context.
-     */
-    _crossRefs: z.array(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(),
-    /**
-     * Opaque state carried across synthesis cycles for progressive work.
-     * Set by the builder, passed back as context on next cycle.
-     */
-    _state: z.unknown().optional(),
-    /**
-     * Structured error from last cycle. Present when a step failed.
-     * Cleared on successful cycle.
-     */
-    _error: metaErrorSchema.optional(),
-    /** When true, this meta is skipped during staleness scheduling. Manual trigger still works. */
-    _disabled: z.boolean().optional(),
-    /**
-     * Per-phase state machine record. Engine-managed.
-     * Keyed by phase name (architect, builder, critic) with status values.
-     * Persisted to survive ticks; derived on first load for back-compat.
-     */
-    _phaseState: phaseStateSchema.optional(),
-})
-    .loose();
-
+function migrateConfigPath(configRoot, warn) {
+    const oldPath = join(configRoot, 'jeeves-meta.config.json');
+    const newDir = join(configRoot, 'jeeves-meta');
+    const newPath = join(newDir, 'config.json');
+    if (existsSync(oldPath) && !existsSync(newPath)) {
+        mkdirSync(newDir, { recursive: true });
+        copyFileSync(oldPath, newPath);
+        const message = `Migrated config from ${oldPath} to ${newPath}. The old file can be removed.`;
+        if (warn) {
+            warn(message);
+        }
+        else {
+            console.warn(`[jeeves-meta] ${message}`);
+        }
+    }
+}
+/**
+ * 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.');
+}
 /**
- * Merge synthesis results into meta.json.
+ * Load service config from a JSON file.
  *
- * Preserves human-set fields (_id, _steer, _depth).
- * Writes engine fields (_generatedAt, _structureHash, etc.).
- * Validates against schema before writing.
+ * Resolves \@file: references for defaultArchitect and defaultCritic,
+ * and substitutes environment-variable placeholders throughout.
  *
- * @module orchestrator/merge
+ * @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);
+}
+
 /**
- * Merge results into meta.json and write atomically.
+ * Error thrown when a spawned subprocess is aborted via AbortController.
  *
- * @param options - Merge options.
- * @returns The updated MetaJson.
- * @throws If validation fails (malformed output).
+ * @module executor/SpawnAbortedError
  */
-async function mergeAndWrite(options) {
-    const merged = {
-        // Preserve human-set fields (auto-generate _id on first synthesis)
-        _id: options.current._id ?? randomUUID(),
-        _steer: options.current._steer,
-        _depth: options.current._depth,
-        _emphasis: options.current._emphasis,
-        // Engine fields
-        _architect: options.architect,
-        _builder: options.builder,
-        _critic: options.critic,
-        _generatedAt: options.stateOnly
-            ? options.current._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 (stateOnly preserves previous content)
-        _content: options.stateOnly
-            ? options.current._content
-            : (options.builderOutput?.content ?? options.current._content),
-        // Feedback from critic
-        _feedback: options.feedback ?? options.current._feedback,
-        // Progressive state
-        _state: options.state,
-        // Error handling
-        _error: options.error ?? undefined,
-        // Phase state machine
-        _phaseState: options.phaseState,
-        // 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._state === undefined)
-        delete merged._state;
-    if (merged._error === undefined)
-        delete merged._error;
-    if (merged._content === undefined)
-        delete merged._content;
-    if (merged._feedback === undefined)
-        delete merged._feedback;
-    if (merged._phaseState === undefined)
-        delete merged._phaseState;
-    // Validate
-    const result = metaJsonSchema.safeParse(merged);
-    if (!result.success) {
-        throw new Error(`Meta validation failed: ${result.error.message}`);
+/** Error indicating a spawn was deliberately aborted. */
+class SpawnAbortedError extends Error {
+    constructor(message = 'Synthesis was aborted') {
+        super(message);
+        this.name = 'SpawnAbortedError';
     }
-    // Write to specified path (lock staging) or default meta.json
-    const filePath = options.outputPath ?? join(options.metaPath, 'meta.json');
-    await writeFile(filePath, JSON.stringify(result.data, null, 2) + '\n');
-    return result.data;
 }
 
 /**
- * Build a minimal MetaNode from a known meta path using watcher walk.
+ * Error thrown when a spawned subprocess times out.
  *
- * Used for targeted synthesis (when a specific path is requested) to avoid
- * the full discovery + ownership tree build. Discovers only immediate child
- * `.meta/` directories.
+ * Carries the output file path so callers can attempt partial output recovery.
  *
- * @module discovery/buildMinimalNode
+ * @module executor/SpawnTimeoutError
  */
+/** Error indicating a spawn timeout with a recoverable output path. */
+class SpawnTimeoutError extends Error {
+    /** Path to the (possibly partial) output file written before timeout. */
+    outputPath;
+    constructor(message, outputPath) {
+        super(message);
+        this.name = 'SpawnTimeoutError';
+        this.outputPath = outputPath;
+    }
+}
+
 /**
- * Build a minimal MetaNode for a known meta path.
+ * MetaExecutor implementation using the OpenClaw gateway HTTP API.
  *
- * Walks the owner directory for child `.meta/meta.json` files and constructs
- * a shallow ownership tree (self + direct children only).
+ * 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.
  *
- * @param metaPath - Absolute path to the `.meta/` directory.
- * @param watcher - WatcherClient for filesystem enumeration.
- * @returns MetaNode with direct children wired.
+ * @module executor/GatewayExecutor
  */
-async function buildMinimalNode(metaPath, watcher) {
-    const normalized = normalizePath(metaPath);
-    const ownerPath = posix.dirname(normalized);
-    // Find child metas using watcher walk.
-    // We include only *direct* children (nearest descendants in the ownership tree)
-    // to match the ownership semantics used elsewhere.
-    const rawMetaJsonPaths = await watcher.walk([
-        `${escapeGlob(ownerPath)}/**/.meta/meta.json`,
-    ]);
-    const candidateMetaPaths = [
-        ...new Set(rawMetaJsonPaths.map((p) => posix.dirname(normalizePath(p)))),
-    ].filter((p) => p !== normalized);
-    const candidates = candidateMetaPaths
-        .map((mp) => ({ metaPath: mp, ownerPath: posix.dirname(mp) }))
-        .sort((a, b) => a.ownerPath.length - b.ownerPath.length);
-    const directChildren = [];
-    for (const c of candidates) {
-        const nestedUnderExisting = directChildren.some((d) => c.ownerPath === d.ownerPath ||
-            c.ownerPath.startsWith(d.ownerPath + '/'));
-        if (!nestedUnderExisting)
-            directChildren.push(c);
+const DEFAULT_POLL_INTERVAL_MS = 5000;
+const DEFAULT_TIMEOUT_MS$1 = 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;
+    workspaceDir;
+    controller = new AbortController();
+    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;
+        this.workspaceDir = options.workspaceDir ?? join(tmpdir(), 'jeeves-meta');
     }
-    const children = directChildren.map((c) => ({
-        metaPath: c.metaPath,
-        ownerPath: c.ownerPath,
-        treeDepth: 1,
-        children: [],
-        parent: null,
-    }));
-    const node = {
-        metaPath: normalized,
-        ownerPath,
-        treeDepth: 0,
-        children,
-        parent: null,
-    };
-    for (const child of children) {
-        child.parent = node;
+    /** Remove a temp output file if it exists. */
+    cleanupOutputFile(outputPath) {
+        try {
+            if (existsSync(outputPath))
+                unlinkSync(outputPath);
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+    }
+    /** Invoke a gateway tool via the /tools/invoke HTTP endpoint. */
+    async invoke(tool, args, sessionKey) {
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (this.apiKey) {
+            headers['Authorization'] = 'Bearer ' + this.apiKey;
+        }
+        const body = { tool, args };
+        if (sessionKey)
+            body.sessionKey = sessionKey;
+        const res = await fetch(this.gatewayUrl + '/tools/invoke', {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+        });
+        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;
+    }
+    /** Look up session metadata (tokens, completion status) via sessions_list. */
+    async getSessionInfo(sessionKey) {
+        try {
+            const result = await this.invoke('sessions_list', {
+                limit: 200,
+                messageLimit: 0,
+            });
+            const sessions = (result.result?.details?.sessions ??
+                result.result?.sessions ??
+                []);
+            const match = sessions.find((s) => s.key === sessionKey);
+            if (!match) {
+                // Session absent from list — likely cleaned up after completion.
+                // With limit=200 this is reliable; a false positive here only
+                // means we read the output file slightly early (still correct
+                // if the file exists).
+                return { completed: true };
+            }
+            const done = match.status === 'completed' || match.status === 'done';
+            return { tokens: match.totalTokens, completed: done };
+        }
+        catch {
+            return { completed: false };
+        }
+    }
+    /** Whether this executor has been aborted by the operator. */
+    get aborted() {
+        return this.controller.signal.aborted;
+    }
+    /** Abort the currently running spawn, if any. */
+    abort() {
+        this.controller.abort();
+    }
+    async spawn(task, options) {
+        // Fresh controller for each spawn call
+        this.controller = new AbortController();
+        const timeoutSeconds = options?.timeout ?? DEFAULT_TIMEOUT_MS$1 / 1000;
+        const timeoutMs = timeoutSeconds * 1000;
+        const deadline = Date.now() + timeoutMs;
+        // Ensure workspace dir exists
+        if (!existsSync(this.workspaceDir)) {
+            mkdirSync(this.workspaceDir, { recursive: true });
+        }
+        // Generate unique output path for file-based output
+        const outputId = randomUUID();
+        const outputPath = this.workspaceDir + '/output-' + outputId + '.json';
+        // Append file output instruction to the task
+        const taskWithOutput = task +
+            '\n\n## OUTPUT DELIVERY\n\n' +
+            'Write your complete output to a file using the Write tool at:\n' +
+            outputPath +
+            '\n\n' +
+            'After writing the file, reply with ONLY: NO_REPLY';
+        // Step 1: Spawn the sub-agent session (unique label per cycle to avoid
+        // "label already in use" errors — gateway labels persist after session completion)
+        const labelBase = options?.label ?? 'jeeves-meta-synthesis';
+        const label = labelBase + '-' + outputId.slice(0, 8);
+        const spawnResult = await this.invoke('sessions_spawn', {
+            task: taskWithOutput,
+            label,
+            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 sleepAsync(3000);
+        while (Date.now() < deadline) {
+            // Check for abort before each poll iteration
+            if (this.controller.signal.aborted) {
+                this.cleanupOutputFile(outputPath);
+                throw new SpawnAbortedError();
+            }
+            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;
+                // Check 1: terminal stop reason in history
+                let historyDone = false;
+                if (msgArray.length > 0) {
+                    const lastMsg = msgArray[msgArray.length - 1];
+                    if (lastMsg.role === 'assistant' &&
+                        lastMsg.stopReason &&
+                        lastMsg.stopReason !== 'toolUse' &&
+                        lastMsg.stopReason !== 'error') {
+                        historyDone = true;
+                    }
+                }
+                // Check 2: session completion status via sessions_list
+                const sessionInfo = await this.getSessionInfo(sessionKey);
+                if (historyDone || sessionInfo.completed) {
+                    const tokens = sessionInfo.tokens;
+                    // Read output from file (sub-agent wrote it via Write tool)
+                    if (existsSync(outputPath)) {
+                        try {
+                            const output = readFileSync(outputPath, 'utf8');
+                            return { output, tokens };
+                        }
+                        finally {
+                            try {
+                                unlinkSync(outputPath);
+                            }
+                            catch {
+                                /* cleanup best-effort */
+                            }
+                        }
+                    }
+                    // Fallback: extract from message content if file wasn't written
+                    for (let i = msgArray.length - 1; i >= 0; i--) {
+                        const msg = msgArray[i];
+                        if (msg.role === 'assistant' && msg.content) {
+                            const text = typeof msg.content === 'string'
+                                ? msg.content
+                                : Array.isArray(msg.content)
+                                    ? msg.content
+                                        .filter((b) => b.type === 'text' && b.text)
+                                        .map((b) => b.text)
+                                        .join('\n')
+                                    : '';
+                            if (text)
+                                return { output: text, tokens };
+                        }
+                    }
+                    return { output: '', tokens };
+                }
+            }
+            catch {
+                // Transient poll failure — keep trying
+            }
+            await sleepAsync(this.pollIntervalMs);
+        }
+        throw new SpawnTimeoutError('Synthesis subprocess timed out after ' + timeoutMs.toString() + 'ms', outputPath);
     }
-    return node;
 }
 
 /**
- * Weighted staleness formula for candidate selection.
+ * Pino logger factory.
  *
- * effectiveStaleness = actualStaleness * (normalizedDepth + 1) ^ (depthWeight * emphasis)
+ * @module logger
+ */
+/**
+ * Create a pino logger instance.
  *
- * @module scheduling/weightedFormula
+ * @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 });
+}
+
 /**
- * Compute effective staleness for a set of candidates.
+ * Built-in default prompts for the synthesis pipeline.
  *
- * Normalizes depths so the minimum becomes 0, then applies the formula:
- * effectiveStaleness = actualStaleness * (normalizedDepth + 1) ^ (depthWeight * emphasis)
+ * Prompts ship as .md files bundled into dist/prompts/ via rollup-plugin-copy.
+ * Loaded at runtime relative to the compiled module location.
  *
- * Per-meta _emphasis (default 1) multiplies depthWeight, allowing individual
- * metas to tune how much their tree position affects scheduling.
+ * Users can override via `defaultArchitect` / `defaultCritic` in the service
+ * config. Most installations should use the built-in defaults.
  *
- * @param candidates - Array of \{ node, meta, actualStaleness \}.
- * @param depthWeight - Exponent for depth weighting (0 = pure staleness).
- * @returns Same array with effectiveStaleness computed.
+ * @module prompts
  */
-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),
-        };
-    });
-}
+const packageRoot = packageDirectorySync({
+    cwd: fileURLToPath(import.meta.url),
+});
+const promptDir = join(packageRoot, 'dist', 'prompts');
+/** Built-in default architect prompt. */
+const DEFAULT_ARCHITECT_PROMPT = readFileSync(join(promptDir, 'architect.md'), 'utf8');
+/** Built-in default critic prompt. */
+const DEFAULT_CRITIC_PROMPT = readFileSync(join(promptDir, 'critic.md'), 'utf8');
 
 /**
- * Select the best synthesis candidate from stale metas.
+ * Build the MetaContext for a synthesis cycle.
  *
- * Picks the meta with highest effective staleness.
+ * Computes shared inputs once: scope files, delta files, child meta outputs,
+ * previous content/feedback, steer, and archive paths.
  *
- * @module scheduling/selectCandidate
+ * @module orchestrator/contextPackage
  */
 /**
- * Select the candidate with the highest effective staleness.
+ * Condense a file list into glob-like summaries.
+ * Groups by directory + extension pattern.
  *
- * @param candidates - Array of candidates with computed effective staleness.
- * @returns The winning candidate, or null if no candidates.
+ * @param files - Array of file paths.
+ * @param maxIndividual - Show individual files up to this count.
+ * @returns Condensed summary string.
  */
-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];
-        }
+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);
     }
-    return best;
+    // 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');
 }
 /**
- * Extract stale candidates from a list and return the stalest path.
- *
- * Consolidates the repeated pattern of:
- *   filter → computeEffectiveStaleness → selectCandidate → return path
+ * Read a meta.json file and extract its `_content` field.
  *
- * @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.
+ * @param metaJsonPath - Absolute path to a meta.json file.
+ * @returns The `_content` string, or null if missing/unreadable.
  */
-function discoverStalestPath(candidates, depthWeight) {
-    const weighted = computeEffectiveStaleness(candidates, depthWeight);
-    const winner = selectCandidate(weighted);
-    return winner?.node.metaPath ?? null;
+async function readMetaContent(metaJsonPath) {
+    try {
+        const raw = await readFile(metaJsonPath, 'utf8');
+        const meta = JSON.parse(raw);
+        return meta._content ?? null;
+    }
+    catch {
+        return null;
+    }
 }
-
-/**
- * Shared error utilities.
- *
- * @module errors
- */
 /**
- * Wrap an unknown caught value into a MetaError.
+ * Build the context package for a synthesis cycle.
  *
- * @param step - Which synthesis step failed.
- * @param err - The caught error value.
- * @param code - Error classification code.
- * @returns A structured MetaError.
+ * @param node - The meta node being synthesized.
+ * @param meta - Current meta.json content.
+ * @param watcher - WatcherClient for scope enumeration.
+ * @returns The computed context package.
  */
-function toMetaError(step, err, code = 'FAILED') {
+async function buildContextPackage(node, meta, watcher, logger) {
+    // Scope and delta files via watcher walk
+    const scopeStart = Date.now();
+    const { scopeFiles } = await getScopeFiles(node, watcher, logger);
+    const deltaFiles = getDeltaFiles(meta._generatedAt, scopeFiles);
+    logger?.debug({
+        scopeFiles: scopeFiles.length,
+        deltaFiles: deltaFiles.length,
+        durationMs: Date.now() - scopeStart,
+    }, 'scope and delta files computed');
+    // Child meta outputs (parallel reads)
+    const childMetas = {};
+    const childEntries = await Promise.all(node.children.map(async (child) => {
+        const content = await readMetaContent(join(child.metaPath, 'meta.json'));
+        return [child.ownerPath, content];
+    }));
+    for (const [path, content] of childEntries) {
+        childMetas[path] = content;
+    }
+    // Cross-referenced meta outputs (parallel reads)
+    const crossRefMetas = {};
+    const seen = new Set();
+    const crossRefPaths = [];
+    for (const refPath of meta._crossRefs ?? []) {
+        if (refPath === node.ownerPath || refPath === node.metaPath)
+            continue;
+        if (seen.has(refPath))
+            continue;
+        seen.add(refPath);
+        crossRefPaths.push(refPath);
+    }
+    const crossRefEntries = await Promise.all(crossRefPaths.map(async (refPath) => {
+        const content = await readMetaContent(join(refPath, '.meta', 'meta.json'));
+        return [refPath, content];
+    }));
+    for (const [path, content] of crossRefEntries) {
+        crossRefMetas[path] = content;
+    }
+    // Archive paths
+    const archives = listArchiveFiles(node.metaPath);
     return {
-        step,
-        code,
-        message: err instanceof Error ? err.message : String(err),
+        path: node.metaPath,
+        scopeFiles,
+        deltaFiles,
+        childMetas,
+        crossRefMetas,
+        previousContent: meta._content ?? null,
+        previousFeedback: meta._feedback ?? null,
+        steer: meta._steer ?? null,
+        previousState: meta._state ?? null,
+        archives,
     };
 }
 
 /**
- * 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');
-}
-
-/**
- * Lock-staged cycle finalization: write to .lock, copy to meta.json, archive, prune.
- *
- * @module orchestrator/finalizeCycle
- */
-/** Finalize a cycle using lock staging: write to .lock → copy to meta.json + archive → delete .lock. */
-async function finalizeCycle(opts) {
-    const lockPath = join(opts.metaPath, '.lock');
-    const metaJsonPath = join(opts.metaPath, 'meta.json');
-    // Stage: write merged result to .lock (sequential — ordering matters)
-    const updated = await 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,
-        state: opts.state,
-        stateOnly: opts.stateOnly,
-    });
-    // Commit: copy .lock → meta.json
-    await copyFile(lockPath, metaJsonPath);
-    // Archive + prune from the committed meta.json (sequential)
-    await createSnapshot(opts.metaPath, updated);
-    await pruneArchive(opts.metaPath, opts.config.maxArchive);
-    // .lock is cleaned up by the finally block (releaseLock)
-    return updated;
-}
-
-/**
- * Parse subprocess outputs for each synthesis step.
- *
- * - Architect: returns text \> _builder
- * - Builder: returns JSON \> _content + structured fields
- * - Critic: returns text \> _feedback
+ * Build task prompts for each synthesis step.
  *
- * @module orchestrator/parseOutput
- */
-/**
- * Parse architect output. The architect returns a task brief as text.
+ * Prompts are compiled as Handlebars templates with access to config,
+ * meta, and scope context. The architect can write template expressions
+ * into its _builder output; these resolve when the builder task is compiled.
  *
- * @param output - Raw subprocess output.
- * @returns The task brief string.
+ * @module orchestrator/buildTask
  */
-function parseArchitectOutput(output) {
-    return output.trim();
+Handlebars.registerHelper('gt', (a, b) => a > b);
+/** Build the template context from synthesis inputs. */
+function buildTemplateContext(ctx, meta, config) {
+    return {
+        config,
+        meta,
+        scope: {
+            fileCount: ctx.scopeFiles.length,
+            deltaCount: ctx.deltaFiles.length,
+            childCount: Object.keys(ctx.childMetas).length,
+            crossRefCount: Object.keys(ctx.crossRefMetas).length,
+        },
+    };
 }
 /**
- * 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.
+ * Compile a string as a Handlebars template with the given context.
+ * Returns the original string unchanged if compilation fails.
  */
-function parseBuilderOutput(output) {
-    const trimmed = output.trim();
-    // Strategy 1: Try to parse the entire output as JSON directly
-    const direct = tryParseJson(trimmed);
-    if (direct)
-        return direct;
-    // Strategy 2: Try all fenced code blocks (last match first — models often narrate then output)
-    const fencePattern = /```(?:json)?\s*([\s\S]*?)```/g;
-    const fenceMatches = [];
-    let match;
-    while ((match = fencePattern.exec(trimmed)) !== null) {
-        fenceMatches.push(match[1].trim());
+function compileTemplate(text, context) {
+    try {
+        return Handlebars.compile(text, { noEscape: true })(context);
     }
-    // Try last fence first (most likely to be the actual output)
-    for (let i = fenceMatches.length - 1; i >= 0; i--) {
-        const result = tryParseJson(fenceMatches[i]);
-        if (result)
-            return result;
+    catch {
+        return text;
     }
-    // Strategy 3: Find outermost { ... } braces
-    const firstBrace = trimmed.indexOf('{');
-    const lastBrace = trimmed.lastIndexOf('}');
-    if (firstBrace !== -1 && lastBrace > firstBrace) {
-        const result = tryParseJson(trimmed.substring(firstBrace, lastBrace + 1));
-        if (result)
-            return result;
+}
+/** Append a keyed record of meta outputs as subsections, if non-empty. */
+function appendMetaSections(sections, heading, metas) {
+    if (Object.keys(metas).length === 0)
+        return;
+    sections.push('', heading);
+    for (const [path, content] of Object.entries(metas)) {
+        sections.push(`### ${path}`, typeof content === 'string' ? content : '(not yet synthesized)');
     }
-    // Fallback: treat entire output as content
-    return { content: trimmed, fields: {} };
 }
-/** Try to parse a string as JSON and extract builder output fields. */
-function tryParseJson(str) {
-    try {
-        const raw = JSON.parse(str);
-        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
-            return null;
-        }
-        const parsed = raw;
-        // Extract _content
-        const content = typeof parsed['_content'] === 'string'
-            ? parsed['_content']
-            : typeof parsed['content'] === 'string'
-                ? parsed['content']
-                : null;
-        if (content === null)
-            return null;
-        // Extract _state (the ONLY underscore key the builder is allowed to set)
-        const state = '_state' in parsed ? parsed['_state'] : undefined;
-        // 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, ...(state !== undefined ? { state } : {}) };
+/** 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,
+        includeCrossRefs: true,
+        ...options,
+    };
+    if (opts.includeSteer && ctx.steer) {
+        sections.push('', '## STEERING PROMPT', ctx.steer);
     }
-    catch {
-        return null;
+    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) {
+        appendMetaSections(sections, '## CHILD META OUTPUTS', ctx.childMetas);
+    }
+    if (opts.includeCrossRefs) {
+        appendMetaSections(sections, '## CROSS-REFERENCED METAS', ctx.crossRefMetas);
     }
 }
 /**
- * Parse critic output. The critic returns evaluation text.
+ * Build the architect task prompt.
  *
- * @param output - Raw subprocess output.
- * @returns The feedback string.
+ * @param ctx - Synthesis context.
+ * @param meta - Current meta.json.
+ * @param config - Synthesis config.
+ * @returns The architect task prompt string.
  */
-function parseCriticOutput(output) {
-    return output.trim();
+function buildArchitectTask(ctx, meta, config) {
+    const sections = [
+        `# jeeves-meta · ARCHITECT · ${ctx.path}`,
+        '',
+        meta._architect ?? config.defaultArchitect ?? DEFAULT_ARCHITECT_PROMPT,
+        '',
+        '## 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 compileTemplate(sections.join('\n'), buildTemplateContext(ctx, meta, config));
 }
-
-/**
- * Timeout recovery — salvage partial builder state after a SpawnTimeoutError.
- *
- * @module orchestrator/timeoutRecovery
- */
 /**
- * Attempt to recover partial state from a timed-out builder spawn.
+ * Build the builder task prompt.
  *
- * Returns an {@link OrchestrateResult} if state was salvaged, or `null`
- * if the caller should fall through to a hard failure.
+ * @param ctx - Synthesis context.
+ * @param meta - Current meta.json.
+ * @param config - Synthesis config.
+ * @returns The builder task prompt string.
  */
-async function attemptTimeoutRecovery(opts) {
-    const { err, currentMeta, metaPath, config, builderBrief, structureHash, synthesisCount, } = opts;
-    let partialOutput = null;
-    try {
-        const raw = await readFile(err.outputPath, 'utf8');
-        partialOutput = parseBuilderOutput(raw);
-    }
-    catch {
-        // Could not read partial output — fall through to hard failure
-    }
-    if (partialOutput?.state !== undefined) {
-        const currentState = JSON.stringify(currentMeta._state);
-        const newState = JSON.stringify(partialOutput.state);
-        if (newState !== currentState) {
-            const timeoutError = {
-                step: 'builder',
-                code: 'TIMEOUT',
-                message: err.message,
-            };
-            await finalizeCycle({
-                metaPath,
-                current: currentMeta,
-                config,
-                architect: currentMeta._architect ?? '',
-                builder: builderBrief,
-                critic: currentMeta._critic ?? '',
-                builderOutput: null,
-                feedback: null,
-                structureHash,
-                synthesisCount,
-                error: timeoutError,
-                state: partialOutput.state,
-                stateOnly: true,
-            });
-            return {
-                synthesized: true,
-                metaPath,
-                error: timeoutError,
-            };
-        }
+function buildBuilderTask(ctx, meta, config) {
+    const sections = [
+        `# jeeves-meta · BUILDER · ${ctx.path}`,
+        '',
+        '## 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}`),
+    ];
+    if (ctx.previousState != null) {
+        sections.push('', '## PREVIOUS STATE', 'The following opaque state was returned by the previous synthesis cycle.', 'Use it to continue progressive work. Update `_state` in your output to', 'reflect your progress.', '', '```json', JSON.stringify(ctx.previousState, null, 2), '```');
     }
-    return null;
+    appendSharedSections(sections, ctx, {
+        includeSteer: false,
+        feedbackHeading: '## FEEDBACK FROM CRITIC',
+    });
+    sections.push('', '## OUTPUT FORMAT', '', 'Respond with ONLY a JSON object. No explanation, no markdown fences, no text before or after.', '', 'Required schema:', '{', '  "type": "object",', '  "required": ["_content"],', '  "properties": {', '    "_content": { "type": "string", "description": "Markdown narrative synthesis" },', '    "_state": { "description": "Opaque state object for progressive work across cycles" }', '  },', '  "additionalProperties": true', '}', '', 'Add any structured fields that capture important facts about this entity', '(e.g. status, risks, dependencies, metrics). Use descriptive key names without underscore prefix.', 'The _content field is the only required key — everything else is domain-driven.', '_state is optional: set it to carry state across synthesis cycles for progressive work.', '', 'DIAGRAMS: When diagrams would aid understanding, use PlantUML in fenced code blocks (```plantuml).', 'PlantUML is rendered natively by the serving infrastructure. NEVER use ASCII art diagrams.');
+    return compileTemplate(sections.join('\n'), buildTemplateContext(ctx, meta, config));
 }
-
 /**
- * Single-node synthesis pipeline — architect, builder, critic.
+ * Build the critic task prompt.
  *
- * @module orchestrator/synthesizeNode
+ * @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.
  */
-/** Run the architect/builder/critic pipeline on a single node. */
-async function synthesizeNode(node, currentMeta, config, executor, watcher, onProgress, logger) {
-    // Step 5-6: Steer change detection
-    const latestArchive = await 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, logger);
-    // Skip empty-scope entities that have no prior content.
-    // Without scope files, child metas, or cross-refs there is nothing for
-    // the architect/builder to work with and the cycle will either time out
-    // or produce empty output.
-    const hasScope = ctx.scopeFiles.length > 0 ||
-        Object.keys(ctx.childMetas).length > 0 ||
-        Object.keys(ctx.crossRefMetas).length > 0;
-    if (!hasScope && !currentMeta._content) {
-        // Bump _generatedAt so this entity doesn't keep winning the staleness
-        // race every cycle. It will be re-evaluated when files appear.
-        // Uses lock-staging for atomic write consistency.
-        currentMeta._generatedAt = new Date().toISOString();
-        const lockPath = join(node.metaPath, '.lock');
-        const metaJsonPath = join(node.metaPath, 'meta.json');
-        await writeFile(lockPath, JSON.stringify(currentMeta, null, 2));
-        await copyFile(lockPath, metaJsonPath);
-        logger?.debug({ path: node.ownerPath }, 'Skipping empty-scope entity');
-        return { synthesized: false };
-    }
-    // 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;
-    // Shared base options for all finalizeCycle calls.
-    // Note: synthesisCount is excluded because it mutates during the pipeline.
-    const baseFinalizeOptions = {
-        metaPath: node.metaPath,
-        current: currentMeta,
-        config,
-        architect: currentMeta._architect ?? '',
-        critic: currentMeta._critic ?? '',
-        structureHash: newStructureHash,
-    };
-    if (architectTriggered) {
-        try {
-            await onProgress?.({
-                type: 'phase_start',
-                path: node.ownerPath,
-                phase: 'architect',
-            });
-            const phaseStart = Date.now();
-            const architectTask = buildArchitectTask(ctx, currentMeta, config);
-            const architectResult = await executor.spawn(architectTask, {
-                thinking: config.thinking,
-                timeout: config.architectTimeout,
-                label: 'meta-architect',
-            });
-            builderBrief = parseArchitectOutput(architectResult.output);
-            architectTokens = architectResult.tokens;
-            synthesisCount = 0;
-            await onProgress?.({
-                type: 'phase_complete',
-                path: node.ownerPath,
-                phase: 'architect',
-                tokens: architectTokens,
-                durationMs: Date.now() - phaseStart,
-            });
-        }
-        catch (err) {
-            stepError = toMetaError('architect', err);
-            if (!currentMeta._builder) {
-                // No cached builder — cycle fails
-                await finalizeCycle({
-                    ...baseFinalizeOptions,
-                    builder: '',
-                    builderOutput: null,
-                    feedback: null,
-                    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;
-    try {
-        await onProgress?.({
-            type: 'phase_start',
-            path: node.ownerPath,
-            phase: 'builder',
-        });
-        const builderStart = Date.now();
-        const builderTask = buildBuilderTask(ctx, metaForBuilder, config);
-        const builderResult = await executor.spawn(builderTask, {
-            thinking: config.thinking,
-            timeout: config.builderTimeout,
-            label: 'meta-builder',
-        });
-        builderOutput = parseBuilderOutput(builderResult.output);
-        builderTokens = builderResult.tokens;
-        synthesisCount++;
-        await onProgress?.({
-            type: 'phase_complete',
-            path: node.ownerPath,
-            phase: 'builder',
-            tokens: builderTokens,
-            durationMs: Date.now() - builderStart,
-        });
-    }
-    catch (err) {
-        if (err instanceof SpawnTimeoutError) {
-            const recovered = await attemptTimeoutRecovery({
-                err,
-                currentMeta,
-                metaPath: node.metaPath,
-                config,
-                builderBrief,
-                structureHash: newStructureHash,
-                synthesisCount,
-            });
-            if (recovered)
-                return recovered;
-        }
-        stepError = toMetaError('builder', err);
-        await finalizeCycle({
-            ...baseFinalizeOptions,
-            builder: builderBrief,
-            builderOutput: null,
-            feedback: null,
-            synthesisCount,
-            error: stepError,
-        });
-        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',
-            path: node.ownerPath,
-            phase: 'critic',
-        });
-        const criticStart = Date.now();
-        const criticTask = buildCriticTask(ctx, metaForCritic, config);
-        const criticResult = await executor.spawn(criticTask, {
-            thinking: config.thinking,
-            timeout: config.criticTimeout,
-            label: 'meta-critic',
-        });
-        feedback = parseCriticOutput(criticResult.output);
-        criticTokens = criticResult.tokens;
-        stepError = null; // Clear any architect error on full success
-        await onProgress?.({
-            type: 'phase_complete',
-            path: node.ownerPath,
-            phase: 'critic',
-            tokens: criticTokens,
-            durationMs: Date.now() - criticStart,
-        });
-    }
-    catch (err) {
-        stepError = stepError ?? toMetaError('critic', err);
-    }
-    // Steps 11-12: Merge, archive, prune
-    await finalizeCycle({
-        ...baseFinalizeOptions,
-        builder: builderBrief,
-        builderOutput,
-        feedback,
-        synthesisCount,
-        error: stepError,
-        architectTokens,
-        builderTokens,
-        criticTokens,
-        state: builderOutput.state,
+function buildCriticTask(ctx, meta, config) {
+    const sections = [
+        `# jeeves-meta · CRITIC · ${ctx.path}`,
+        '',
+        meta._critic ?? config.defaultCritic ?? DEFAULT_CRITIC_PROMPT,
+        '',
+        '## 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,
+        includeCrossRefs: false,
     });
-    return {
-        synthesized: true,
-        metaPath: node.metaPath,
-        error: stepError ?? undefined,
-    };
+    sections.push('', '## OUTPUT FORMAT', 'Return your evaluation as Markdown text. Be specific and actionable.');
+    return compileTemplate(sections.join('\n'), buildTemplateContext(ctx, meta, config));
 }
 
 /**
- * Main orchestration entry point — discovery, scheduling, candidate selection.
+ * Build a minimal MetaNode from a known meta path using watcher walk.
+ *
+ * Used for targeted synthesis (when a specific path is requested) to avoid
+ * the full discovery + ownership tree build. Discovers only immediate child
+ * `.meta/` directories.
  *
- * @module orchestrator/orchestrate
+ * @module discovery/buildMinimalNode
  */
-async function orchestrateOnce(config, executor, watcher, targetPath, onProgress, logger) {
-    // When targetPath is provided, skip the expensive full discovery scan.
-    // Build a minimal node from the filesystem instead.
-    if (targetPath) {
-        const normalizedTarget = normalizePath(targetPath);
-        const targetMetaJson = join(normalizedTarget, 'meta.json');
-        if (!existsSync(targetMetaJson))
-            return { synthesized: false };
-        const node = await buildMinimalNode(normalizedTarget, watcher);
-        if (!acquireLock(node.metaPath))
-            return { synthesized: false };
-        try {
-            const currentMeta = await readMetaJson(normalizedTarget);
-            return await synthesizeNode(node, currentMeta, config, executor, watcher, onProgress, logger);
-        }
-        finally {
-            releaseLock(node.metaPath);
-        }
-    }
-    // Full discovery path (scheduler-driven, no specific target)
-    // Step 1: Discover via watcher walk
-    const discoveryStart = Date.now();
-    const metaPaths = await discoverMetas(watcher);
-    logger?.debug({ paths: metaPaths.length, durationMs: Date.now() - discoveryStart }, 'discovery complete');
-    if (metaPaths.length === 0)
-        return { synthesized: false };
-    // Read meta.json for each discovered meta
-    const metas = new Map();
-    for (const mp of metaPaths) {
-        try {
-            metas.set(normalizePath(mp), await readMetaJson(mp));
-        }
-        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);
-    // Steps 3-4: Staleness check + candidate selection
-    const candidates = [];
-    for (const treeNode of tree.nodes.values()) {
-        const meta = metas.get(treeNode.metaPath);
-        if (!meta)
-            continue;
-        const staleness = actualStaleness(meta);
-        if (staleness > 0) {
-            candidates.push({ node: treeNode, 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 freshMeta = await readMetaJson(candidate.node.metaPath);
-            freshMeta._generatedAt = new Date().toISOString();
-            await writeFile(join(candidate.node.metaPath, 'meta.json'), 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.node;
-    try {
-        const currentMeta = await readMetaJson(node.metaPath);
-        return await synthesizeNode(node, currentMeta, config, executor, watcher, onProgress, logger);
-    }
-    finally {
-        // Step 13: Release lock
-        releaseLock(node.metaPath);
-    }
-}
 /**
- * Run a single synthesis cycle.
+ * Build a minimal MetaNode for a known meta path.
  *
- * Selects the stalest candidate (or a specific target) and runs the
- * full architect/builder/critic pipeline.
+ * Walks the owner directory for child `.meta/meta.json` files and constructs
+ * a shallow ownership tree (self + direct children only).
  *
- * @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.
+ * @param metaPath - Absolute path to the `.meta/` directory.
+ * @param watcher - WatcherClient for filesystem enumeration.
+ * @returns MetaNode with direct children wired.
  */
-async function orchestrate(config, executor, watcher, targetPath, onProgress, logger) {
-    const result = await orchestrateOnce(config, executor, watcher, targetPath, onProgress, logger);
-    return [result];
+async function buildMinimalNode(metaPath, watcher) {
+    const normalized = normalizePath(metaPath);
+    const ownerPath = posix.dirname(normalized);
+    // Find child metas using watcher walk.
+    // We include only *direct* children (nearest descendants in the ownership tree)
+    // to match the ownership semantics used elsewhere.
+    const rawMetaJsonPaths = await watcher.walk([
+        `${escapeGlob(ownerPath)}/**/.meta/meta.json`,
+    ]);
+    const candidateMetaPaths = [
+        ...new Set(rawMetaJsonPaths.map((p) => posix.dirname(normalizePath(p)))),
+    ].filter((p) => p !== normalized);
+    const candidates = candidateMetaPaths
+        .map((mp) => ({ metaPath: mp, ownerPath: posix.dirname(mp) }))
+        .sort((a, b) => a.ownerPath.length - b.ownerPath.length);
+    const directChildren = [];
+    for (const c of candidates) {
+        const nestedUnderExisting = directChildren.some((d) => c.ownerPath === d.ownerPath ||
+            c.ownerPath.startsWith(d.ownerPath + '/'));
+        if (!nestedUnderExisting)
+            directChildren.push(c);
+    }
+    const children = directChildren.map((c) => ({
+        metaPath: c.metaPath,
+        ownerPath: c.ownerPath,
+        treeDepth: 1,
+        children: [],
+        parent: null,
+    }));
+    const node = {
+        metaPath: normalized,
+        ownerPath,
+        treeDepth: 0,
+        children,
+        parent: null,
+    };
+    for (const child of children) {
+        child.parent = node;
+    }
+    return node;
 }
 
 /**
@@ -10560,6 +9744,41 @@ function enforceInvariant(state) {
     }
     return result;
 }
+// ── Invalidation cascades ──────────────────────────────────────────────
+/**
+ * Architect invalidated: architect → pending; builder, critic → stale.
+ * Triggers: _structureHash change, _steer change, _architect change,
+ * _crossRefs declaration change, _synthesisCount \>= architectEvery.
+ */
+function invalidateArchitect(state) {
+    return enforceInvariant({
+        architect: state.architect === 'failed' ? 'failed' : 'pending',
+        builder: state.builder === 'fresh' ? 'stale' : state.builder,
+        critic: state.critic === 'fresh' ? 'stale' : state.critic,
+    });
+}
+/**
+ * Builder invalidated (scope mtime or cross-ref _content change):
+ * builder → pending; critic → stale.
+ * Only applies when architect is fresh; otherwise, builder stays stale.
+ */
+function invalidateBuilder(state) {
+    if (state.architect !== 'fresh') {
+        // Architect is not fresh — builder stays stale (or whatever it is)
+        return enforceInvariant({
+            ...state,
+            builder: state.builder === 'fresh' || state.builder === 'stale'
+                ? 'stale'
+                : state.builder,
+            critic: state.critic === 'fresh' ? 'stale' : state.critic,
+        });
+    }
+    return enforceInvariant({
+        ...state,
+        builder: state.builder === 'failed' ? 'failed' : 'pending',
+        critic: state.critic === 'fresh' ? 'stale' : state.critic,
+    });
+}
 // ── Phase success transitions ──────────────────────────────────────────
 /**
  * Architect completes successfully.
@@ -10728,7 +9947,9 @@ function derivePhaseState(meta, inputs) {
     }
     // Check architect invalidation (when inputs are provided)
     if (inputs) {
-        const architectInvalidated = inputs.structureChanged ||
+        // Progressive metas: structure changes invalidate builder, not architect
+        const structureInvalidatesArchitect = inputs.structureChanged && meta._state === undefined;
+        const architectInvalidated = structureInvalidatesArchitect ||
             inputs.steerChanged ||
             inputs.architectChanged ||
             inputs.crossRefsChanged ||
@@ -10740,6 +9961,14 @@ function derivePhaseState(meta, inputs) {
                 critic: 'stale',
             };
         }
+        // Progressive meta with structure change: builder-only invalidation
+        if (inputs.structureChanged && meta._state !== undefined) {
+            return {
+                architect: 'fresh',
+                builder: 'pending',
+                critic: 'stale',
+            };
+        }
     }
     // Has _builder but no _content: builder is pending
     if (meta._builder && !meta._content) {
@@ -10761,6 +9990,154 @@ function derivePhaseState(meta, inputs) {
     return freshPhaseState();
 }
 
+/**
+ * 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');
+}
+
+/**
+ * Per-tick invalidation pass.
+ *
+ * Computes architect-invalidating and builder-invalidating inputs for a meta,
+ * then applies the cascade to update _phaseState.
+ *
+ * @module phaseState/invalidate
+ */
+/**
+ * Compute invalidation inputs and apply cascade for a single meta.
+ *
+ * @param meta - Current meta.json content with existing _phaseState.
+ * @param scopeFiles - Sorted file list from scope.
+ * @param config - MetaConfig for architectEvery.
+ * @param node - MetaNode for archive access.
+ * @param crossRefMetas - Map of cross-ref owner paths to their current _content.
+ * @param archiveCrossRefContent - Map of cross-ref owner paths to their archived _content.
+ * @returns Updated phase state and invalidation details.
+ */
+async function computeInvalidation(meta, scopeFiles, config, node, crossRefMetas, archiveCrossRefContent) {
+    let phaseState = meta._phaseState ?? {
+        architect: 'fresh',
+        builder: 'fresh',
+        critic: 'fresh',
+    };
+    // ── Architect-level inputs ──
+    const structureHash = computeStructureHash(scopeFiles);
+    const structureChanged = structureHash !== meta._structureHash;
+    const latestArchive = await readLatestArchive(node.metaPath);
+    const steerChanged = hasSteerChanged(meta._steer, latestArchive?._steer, Boolean(latestArchive));
+    // _architect change: compare current vs. archive
+    const architectChanged = latestArchive
+        ? (meta._architect ?? '') !== (latestArchive._architect ?? '')
+        : Boolean(meta._architect);
+    // _crossRefs declaration change
+    const currentRefs = (meta._crossRefs ?? []).slice().sort().join(',');
+    const archiveRefs = (latestArchive?._crossRefs ?? [])
+        .slice()
+        .sort()
+        .join(',');
+    const crossRefsDeclChanged = latestArchive
+        ? currentRefs !== archiveRefs
+        : currentRefs.length > 0;
+    const architectInvalidators = [];
+    if (structureChanged) {
+        if (meta._state !== undefined) {
+            // Progressive entity: new files → builder only (cursor handles incremental)
+            phaseState = invalidateBuilder(phaseState);
+        }
+        else {
+            architectInvalidators.push('structureHash');
+        }
+    }
+    if (steerChanged)
+        architectInvalidators.push('steer');
+    if (architectChanged)
+        architectInvalidators.push('_architect');
+    if (crossRefsDeclChanged)
+        architectInvalidators.push('_crossRefs');
+    if ((meta._synthesisCount ?? 0) >= config.architectEvery) {
+        architectInvalidators.push('architectEvery');
+    }
+    // First-run check: no _builder means architect must run
+    const firstRun = !meta._builder;
+    if (architectInvalidators.length > 0 || firstRun) {
+        phaseState = invalidateArchitect(phaseState);
+    }
+    // ── Builder-level inputs ──
+    // Scope file mtime check — if any file newer than _generatedAt
+    const scopeMtimeMax = null;
+    // Note: actual mtime check is done by the caller or via isStale;
+    // here we just detect cross-ref content changes for the cascade.
+    // Cross-ref _content change (builder-invalidating)
+    let crossRefContentChanged = false;
+    return {
+        phaseState,
+        architectInvalidators,
+        stalenessInputs: {
+            structureHash,
+            steerChanged,
+            architectChanged,
+            crossRefsDeclChanged,
+            scopeMtimeMax,
+            crossRefContentChanged,
+        },
+        structureHash,
+        steerChanged,
+    };
+}
+
+/**
+ * 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),
+        };
+    });
+}
+
 /**
  * Corpus-wide phase scheduler.
  *
@@ -10773,18 +10150,30 @@ function derivePhaseState(meta, inputs) {
 /**
  * Build phase candidates from listMetas entries.
  *
- * Derives phase state and auto-retries failed phases for each entry.
+ * Derives phase state, auto-retries failed phases, and applies Tier 1
+ * cheap-invalidation (no I/O) for metas with persisted _phaseState.
  * Used by orchestratePhase, queue route, and status route.
  */
-function buildPhaseCandidates(entries) {
-    return entries.map((entry) => ({
-        node: entry.node,
-        meta: entry.meta,
-        phaseState: retryAllFailed(derivePhaseState(entry.meta)),
-        actualStaleness: entry.stalenessSeconds,
-        locked: entry.locked,
-        disabled: entry.disabled,
-    }));
+function buildPhaseCandidates(entries, architectEvery) {
+    return entries.map((entry) => {
+        let ps = retryAllFailed(derivePhaseState(entry.meta));
+        // Tier 1 cheap invalidation for metas with persisted _phaseState
+        if (entry.meta._phaseState) {
+            const needsArchitect = !entry.meta._builder ||
+                (entry.meta._synthesisCount ?? 0) >= architectEvery;
+            if (needsArchitect && ps.architect === 'fresh') {
+                ps = { architect: 'pending', builder: 'stale', critic: 'stale' };
+            }
+        }
+        return {
+            node: entry.node,
+            meta: entry.meta,
+            phaseState: ps,
+            actualStaleness: entry.stalenessSeconds,
+            locked: entry.locked,
+            disabled: entry.disabled,
+        };
+    });
 }
 /**
  * Rank all eligible phase candidates by priority.
@@ -10837,14 +10226,132 @@ function rankPhaseCandidates(metas, depthWeight) {
     return candidates;
 }
 /**
- * Select the best phase candidate across the corpus.
+ * Select the best phase candidate across the corpus.
+ *
+ * @param metas - Array of (node, meta, phaseState, stalenessSeconds) tuples.
+ * @param depthWeight - Config depthWeight for staleness tiebreak.
+ * @returns The winning candidate, or null if no phase is ready.
+ */
+function selectPhaseCandidate(metas, depthWeight) {
+    return rankPhaseCandidates(metas, depthWeight)[0] ?? null;
+}
+
+/**
+ * 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),
+    };
+}
+
+/**
+ * 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();
+    // Strategy 1: Try to parse the entire output as JSON directly
+    const direct = tryParseJson(trimmed);
+    if (direct)
+        return direct;
+    // Strategy 2: Try all fenced code blocks (last match first — models often narrate then output)
+    const fencePattern = /```(?:json)?\s*([\s\S]*?)```/g;
+    const fenceMatches = [];
+    let match;
+    while ((match = fencePattern.exec(trimmed)) !== null) {
+        fenceMatches.push(match[1].trim());
+    }
+    // Try last fence first (most likely to be the actual output)
+    for (let i = fenceMatches.length - 1; i >= 0; i--) {
+        const result = tryParseJson(fenceMatches[i]);
+        if (result)
+            return result;
+    }
+    // Strategy 3: Find outermost { ... } braces
+    const firstBrace = trimmed.indexOf('{');
+    const lastBrace = trimmed.lastIndexOf('}');
+    if (firstBrace !== -1 && lastBrace > firstBrace) {
+        const result = tryParseJson(trimmed.substring(firstBrace, lastBrace + 1));
+        if (result)
+            return result;
+    }
+    // Fallback: treat entire output as content
+    return { content: trimmed, fields: {} };
+}
+/** Try to parse a string as JSON and extract builder output fields. */
+function tryParseJson(str) {
+    try {
+        const raw = JSON.parse(str);
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+            return null;
+        }
+        const parsed = raw;
+        // Extract _content
+        const content = typeof parsed['_content'] === 'string'
+            ? parsed['_content']
+            : typeof parsed['content'] === 'string'
+                ? parsed['content']
+                : null;
+        if (content === null)
+            return null;
+        // Extract _state (the ONLY underscore key the builder is allowed to set)
+        const state = '_state' in parsed ? parsed['_state'] : undefined;
+        // 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, ...(state !== undefined ? { state } : {}) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse critic output. The critic returns evaluation text.
  *
- * @param metas - Array of (node, meta, phaseState, stalenessSeconds) tuples.
- * @param depthWeight - Config depthWeight for staleness tiebreak.
- * @returns The winning candidate, or null if no phase is ready.
+ * @param output - Raw subprocess output.
+ * @returns The feedback string.
  */
-function selectPhaseCandidate(metas, depthWeight) {
-    return rankPhaseCandidates(metas, depthWeight)[0] ?? null;
+function parseCriticOutput(output) {
+    return output.trim();
 }
 
 /**
@@ -11105,7 +10612,7 @@ async function orchestratePhase(config, executor, watcher, targetPath, onProgres
     if (metaResult.entries.length === 0)
         return { executed: false };
     // Build candidates with phase state (including invalidation + auto-retry)
-    const candidates = buildPhaseCandidates(metaResult.entries);
+    const candidates = buildPhaseCandidates(metaResult.entries, config.architectEvery);
     // Select best phase candidate
     const winner = selectPhaseCandidate(candidates, config.depthWeight);
     if (!winner) {
@@ -11780,46 +11287,6 @@ function buildMetaRules(config) {
             },
             renderAs: 'md',
         },
-        {
-            name: 'meta-config',
-            description: 'jeeves-meta configuration file',
-            match: {
-                properties: {
-                    file: {
-                        properties: {
-                            path: {
-                                type: 'string',
-                                glob: '**/jeeves-meta{.config.json,/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',
-        },
     ];
 }
 /**
@@ -12063,13 +11530,15 @@ class Scheduler {
     queue;
     logger;
     watcher;
+    cache;
     registrar = null;
     currentExpression;
-    constructor(config, queue, logger, watcher) {
+    constructor(config, queue, logger, watcher, cache) {
         this.config = config;
         this.queue = queue;
         this.logger = logger;
         this.watcher = watcher;
+        this.cache = cache;
         this.currentExpression = config.schedule;
     }
     /** Set the rule registrar for watcher restart detection. */
@@ -12186,8 +11655,8 @@ class Scheduler {
      */
     async discoverNextPhase() {
         try {
-            const result = await listMetas(this.config, this.watcher);
-            const candidates = buildPhaseCandidates(result.entries);
+            const result = await this.cache.get(this.config, this.watcher);
+            const candidates = buildPhaseCandidates(result.entries, this.config.architectEvery);
             const winner = selectPhaseCandidate(candidates, this.config.depthWeight);
             if (!winner)
                 return null;
@@ -12612,11 +12081,11 @@ function registerMetasUpdateRoute(app, deps) {
  */
 function registerPreviewRoute(app, deps) {
     app.get('/preview', async (request, reply) => {
-        const { config, watcher } = deps;
+        const { config, watcher, cache } = deps;
         const query = request.query;
         let result;
         try {
-            result = await listMetas(config, watcher);
+            result = await cache.get(config, watcher);
         }
         catch {
             return reply.status(503).send({
@@ -12636,40 +12105,24 @@ function registerPreviewRoute(app, deps) {
             }
         }
         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) {
+            // Select best phase candidate
+            const candidates = buildPhaseCandidates(result.entries, config.architectEvery);
+            const winner = selectPhaseCandidate(candidates, config.depthWeight);
+            if (!winner) {
                 return { message: 'No stale metas found. Nothing to synthesize.' };
             }
-            targetNode = findNode(result.tree, stalestPath);
+            targetNode = findNode(result.tree, winner.node.metaPath);
         }
         const meta = await readMetaJson(targetNode.metaPath);
         // Scope files
         const { scopeFiles } = await getScopeFiles(targetNode, watcher);
-        const structureHash = computeStructureHash(scopeFiles);
+        // Compute invalidation inputs (DRY: reuse phaseState/invalidate logic)
+        const invalidation = await computeInvalidation(meta, scopeFiles, config, targetNode);
+        const { architectInvalidators, stalenessInputs } = invalidation;
+        const { structureHash } = invalidation;
         const structureChanged = structureHash !== meta._structureHash;
-        const latestArchive = await readLatestArchive(targetNode.metaPath);
-        const steerChanged = hasSteerChanged(meta._steer, latestArchive?._steer, Boolean(latestArchive));
-        // _architect change detection
-        const architectChanged = latestArchive
-            ? (meta._architect ?? '') !== (latestArchive._architect ?? '')
-            : Boolean(meta._architect);
-        // _crossRefs declaration change detection
-        const currentRefs = (meta._crossRefs ?? []).slice().sort().join(',');
-        const archiveRefs = (latestArchive?._crossRefs ?? [])
-            .slice()
-            .sort()
-            .join(',');
-        const crossRefsDeclChanged = latestArchive
-            ? currentRefs !== archiveRefs
-            : currentRefs.length > 0;
+        const { steerChanged } = invalidation;
+        const { architectChanged, crossRefsDeclChanged } = stalenessInputs;
         const architectTriggered = isArchitectTriggered(meta, structureChanged, steerChanged, config.architectEvery);
         // Delta files
         const deltaFiles = getDeltaFiles(meta._generatedAt, scopeFiles);
@@ -12694,30 +12147,6 @@ function registerPreviewRoute(app, deps) {
         });
         const owedPhase = getOwedPhase(phaseState);
         const priorityBand = getPriorityBand(phaseState);
-        // Architect invalidators
-        const architectInvalidators = [];
-        if (owedPhase === 'architect') {
-            if (structureChanged)
-                architectInvalidators.push('structureHash');
-            if (steerChanged)
-                architectInvalidators.push('steer');
-            if (architectChanged)
-                architectInvalidators.push('_architect');
-            if (crossRefsDeclChanged)
-                architectInvalidators.push('_crossRefs');
-            if ((meta._synthesisCount ?? 0) >= config.architectEvery) {
-                architectInvalidators.push('architectEvery');
-            }
-        }
-        // Staleness inputs
-        const stalenessInputs = {
-            structureHash,
-            steerChanged,
-            architectChanged,
-            crossRefsDeclChanged,
-            scopeMtimeMax: null,
-            crossRefContentChanged: false,
-        };
         return {
             path: targetNode.metaPath,
             staleness: {
@@ -12791,8 +12220,8 @@ function registerQueueRoutes(app, deps) {
         // ranked by scheduler priority (computed on read, not persisted)
         let automatic = [];
         try {
-            const metaResult = await listMetas(deps.config, deps.watcher);
-            const candidates = buildPhaseCandidates(metaResult.entries);
+            const metaResult = await deps.cache.get(deps.config, deps.watcher);
+            const candidates = buildPhaseCandidates(metaResult.entries, deps.config.architectEvery);
             const ranked = rankPhaseCandidates(candidates, deps.config.depthWeight);
             automatic = ranked.map((c) => ({
                 path: c.node.metaPath,
@@ -12987,7 +12416,7 @@ function registerStatusRoute(app, deps) {
         name: SERVICE_NAME,
         version: SERVICE_VERSION,
         getHealth: async () => {
-            const { config, queue, scheduler, stats, watcher } = deps;
+            const { config, queue, scheduler, stats, watcher, cache } = deps;
             // On-demand dependency checks
             const [watcherHealth, gatewayHealth] = await Promise.all([
                 checkWatcher(config.watcherUrl),
@@ -13001,7 +12430,7 @@ function registerStatusRoute(app, deps) {
             };
             let nextPhase = null;
             try {
-                const metaResult = await listMetas(config, watcher);
+                const metaResult = await cache.get(config, watcher);
                 // Count raw phase states (before retry) for display
                 for (const entry of metaResult.entries) {
                     const ps = derivePhaseState(entry.meta);
@@ -13010,7 +12439,7 @@ function registerStatusRoute(app, deps) {
                     }
                 }
                 // Build candidates (with auto-retry) for scheduling
-                const candidates = buildPhaseCandidates(metaResult.entries);
+                const candidates = buildPhaseCandidates(metaResult.entries, config.architectEvery);
                 // Find next phase candidate
                 const winner = selectPhaseCandidate(candidates, config.depthWeight);
                 if (winner) {
@@ -13073,7 +12502,7 @@ const synthesizeBodySchema = z.object({
 function registerSynthesizeRoute(app, deps) {
     app.post('/synthesize', async (request, reply) => {
         const body = synthesizeBodySchema.parse(request.body);
-        const { config, watcher, queue } = deps;
+        const { config, watcher, queue, cache } = deps;
         if (body.path) {
             // Path-targeted trigger: create override entry
             const targetPath = resolveMetaDir(body.path);
@@ -13110,7 +12539,7 @@ function registerSynthesizeRoute(app, deps) {
         // Corpus-wide trigger: discover stalest candidate
         let result;
         try {
-            result = await listMetas(config, watcher);
+            result = await cache.get(config, watcher);
         }
         catch {
             return reply.status(503).send({
@@ -13118,20 +12547,15 @@ function registerSynthesizeRoute(app, deps) {
                 message: 'Watcher unreachable — cannot discover candidates',
             });
         }
-        const stale = result.entries
-            .filter((e) => e.stalenessSeconds > 0 && !e.disabled)
-            .map((e) => ({
-            node: e.node,
-            meta: e.meta,
-            actualStaleness: e.stalenessSeconds,
-        }));
-        const stalest = discoverStalestPath(stale, config.depthWeight);
-        if (!stalest) {
+        const candidates = buildPhaseCandidates(result.entries, config.architectEvery);
+        const winner = selectPhaseCandidate(candidates, config.depthWeight);
+        if (!winner) {
             return reply.code(200).send({
                 status: 'skipped',
                 message: 'No stale metas found. Nothing to synthesize.',
             });
         }
+        const stalest = winner.node.metaPath;
         const enqueueResult = queue.enqueue(stalest);
         return reply.code(202).send({
             status: 'accepted',
@@ -13232,6 +12656,18 @@ function createServer(options) {
     // Fastify 5 requires `loggerInstance` for external pino loggers
     const app = Fastify({
         loggerInstance: options.logger,
+        requestTimeout: 30_000,
+    });
+    // Readiness gate: return 503 while service is initializing
+    app.addHook('onRequest', async (request, reply) => {
+        if (options.deps.ready)
+            return;
+        const url = request.url;
+        if (url === '/config' || url.startsWith('/config/apply'))
+            return;
+        return reply
+            .status(503)
+            .send({ status: 'starting', message: 'Service initializing' });
     });
     registerRoutes(app, options.deps);
     return app;
@@ -13407,8 +12843,9 @@ async function startService(config, configPath) {
         lastCycleAt: null,
     };
     const queue = new SynthesisQueue(logger);
+    const cache = new MetaCache();
     // Scheduler (needs watcher for discovery)
-    const scheduler = new Scheduler(config, queue, logger, watcher);
+    const scheduler = new Scheduler(config, queue, logger, watcher, cache);
     const routeDeps = {
         config,
         logger,
@@ -13416,6 +12853,8 @@ async function startService(config, configPath) {
         watcher,
         scheduler,
         stats,
+        cache,
+        ready: false,
         executor,
         configPath,
     };
@@ -13466,6 +12905,9 @@ async function startService(config, configPath) {
                 }
                 await progress.report(evt);
             }, logger);
+            // Invalidate cache only when a phase was actually executed
+            if (result.executed)
+                cache.invalidate();
             const durationMs = Date.now() - startMs;
             if (!result.executed) {
                 logger.debug({ path: ownerPath }, 'Phase skipped (fully fresh or locked)');
@@ -13529,9 +12971,13 @@ async function startService(config, configPath) {
     scheduler.setRegistrar(registrar);
     routeDeps.registrar = registrar;
     void registrar.register().then(() => {
+        routeDeps.ready = true;
         if (registrar.isRegistered) {
             void verifyRuleApplication(watcher, logger);
         }
+    }, () => {
+        // Registration failed after max retries — mark ready anyway
+        routeDeps.ready = true;
     });
     // Periodic watcher health check (independent of scheduler)
     const healthCheck = new WatcherHealthCheck({
@@ -13613,4 +13059,152 @@ const metaDescriptor = jeevesComponentDescriptorSchema.parse({
     customCliCommands: registerCustomCliCommands,
 });
 
-export { DEFAULT_PORT, DEFAULT_PORT_STR, GatewayExecutor, HttpWatcherClient, MAX_STALENESS_SECONDS, ProgressReporter, RESTART_REQUIRED_FIELDS, RuleRegistrar, SERVICE_NAME, SERVICE_VERSION, Scheduler, SynthesisQueue, acquireLock, actualStaleness, buildArchitectTask, buildBuilderTask, buildContextPackage, buildCriticTask, buildOwnershipTree, cleanupStaleLocks, computeEffectiveStaleness, computeEma, computeStructureHash, createLogger, createServer, createSnapshot, discoverMetas, filterInScope, findNode, formatProgressEvent, getScopePrefix, hasSteerChanged, isArchitectTriggered, isLocked, isStale, listArchiveFiles, listMetas, loadServiceConfig, mergeAndWrite, metaConfigSchema, metaDescriptor, metaErrorSchema, metaJsonSchema, migrateConfigPath, normalizePath, orchestrate, orchestratePhase, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, readLockState, registerCustomCliCommands, registerRoutes, registerShutdownHandlers, releaseLock, resolveConfigPath, resolveMetaDir, runArchitect, runBuilder, runCritic, selectCandidate, serviceConfigSchema, sleepAsync as sleep, startService, toMetaError, verifyRuleApplication };
+/**
+ * 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;
+}
+
+/**
+ * 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
+ */
+/** Valid states for a synthesis phase. */
+const phaseStatuses = [
+    'fresh',
+    'stale',
+    'pending',
+    'running',
+    'failed',
+];
+/** Zod schema for a per-phase status value. */
+const phaseStatusSchema = z.enum(phaseStatuses);
+/** Zod schema for the per-meta phase state record. */
+const phaseStateSchema = z.object({
+    architect: phaseStatusSchema,
+    builder: phaseStatusSchema,
+    critic: phaseStatusSchema,
+});
+/** Zod schema for the reserved (underscore-prefixed) meta.json properties. */
+const metaJsonSchema = z
+    .object({
+    /** Stable identity. Auto-generated on first synthesis if not provided. */
+    _id: z.uuid().optional(),
+    /** Human-provided steering prompt. Optional. */
+    _steer: z.string().optional(),
+    /**
+     * Explicit cross-references to other meta owner paths.
+     * Referenced metas' _content is included as architect/builder context.
+     */
+    _crossRefs: z.array(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(),
+    /**
+     * Opaque state carried across synthesis cycles for progressive work.
+     * Set by the builder, passed back as context on next cycle.
+     */
+    _state: z.unknown().optional(),
+    /**
+     * Structured error from last cycle. Present when a step failed.
+     * Cleared on successful cycle.
+     */
+    _error: metaErrorSchema.optional(),
+    /** When true, this meta is skipped during staleness scheduling. Manual trigger still works. */
+    _disabled: z.boolean().optional(),
+    /**
+     * Per-phase state machine record. Engine-managed.
+     * Keyed by phase name (architect, builder, critic) with status values.
+     * Persisted to survive ticks; derived on first load for back-compat.
+     */
+    _phaseState: phaseStateSchema.optional(),
+})
+    .loose();
+
+export { DEFAULT_PORT, DEFAULT_PORT_STR, GatewayExecutor, HttpWatcherClient, MAX_STALENESS_SECONDS, ProgressReporter, RESTART_REQUIRED_FIELDS, RuleRegistrar, SERVICE_NAME, SERVICE_VERSION, Scheduler, SynthesisQueue, acquireLock, actualStaleness, buildArchitectTask, buildBuilderTask, buildContextPackage, buildCriticTask, buildOwnershipTree, cleanupStaleLocks, computeEffectiveStaleness, computeEma, computeStructureHash, createLogger, createServer, createSnapshot, discoverMetas, filterInScope, findNode, formatProgressEvent, getScopePrefix, hasSteerChanged, isArchitectTriggered, isLocked, isStale, listArchiveFiles, listMetas, loadServiceConfig, metaConfigSchema, metaDescriptor, metaErrorSchema, metaJsonSchema, migrateConfigPath, normalizePath, orchestratePhase, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, readLockState, registerCustomCliCommands, registerRoutes, registerShutdownHandlers, releaseLock, resolveConfigPath, resolveMetaDir, runArchitect, runBuilder, runCritic, serviceConfigSchema, sleepAsync as sleep, startService, toMetaError, verifyRuleApplication };