@karmaniverous/jeeves-meta 0.15.2 → 0.15.4

package/dist/index.d.ts

@@ -418,6 +418,231 @@ declare const SERVICE_VERSION: string;
 /** Register all custom meta commands on the parent program. */
 declare function registerCustomCliCommands(program: Command): void;
 
+/**
+ * Types for meta discovery and ownership tree.
+ *
+ * @module discovery/types
+ */
+/** A discovered meta node in the ownership tree. */
+interface MetaNode {
+    /** Absolute path to the .meta directory. */
+    metaPath: string;
+    /** Absolute path to the parent directory that this meta owns. */
+    ownerPath: string;
+    /** Depth in the ownership tree (root = 0). */
+    treeDepth: number;
+    /** Child meta nodes (subtrees with their own .meta/). */
+    children: MetaNode[];
+    /** Parent meta node, or null for roots. */
+    parent: MetaNode | null;
+}
+/** The full ownership tree discovered from watchPaths. */
+interface OwnershipTree {
+    /** All discovered meta nodes, keyed by metaPath. */
+    nodes: Map<string, MetaNode>;
+    /** Root nodes (metas with no parent meta). */
+    roots: MetaNode[];
+}
+
+/**
+ * Unified meta listing: scan, dedup, enrich.
+ *
+ * Single source of truth for all consumers that need a list of metas
+ * with enriched metadata. Replaces duplicated scan+dedup logic in
+ * plugin tools, CLI, and prompt injection.
+ *
+ * @module discovery/listMetas
+ */
+
+/** Enriched meta entry returned by listMetas(). */
+interface MetaEntry {
+    /** Normalized .meta/ directory path. */
+    path: string;
+    /** Tree depth (0 = leaf, higher = more abstract). */
+    depth: number;
+    /** Scheduling emphasis multiplier. */
+    emphasis: number;
+    /** Seconds since last synthesis, or Infinity if never synthesized. */
+    stalenessSeconds: number;
+    /** ISO timestamp of last synthesis, or null. */
+    lastSynthesized: string | null;
+    /** Whether the last synthesis had an error. */
+    hasError: boolean;
+    /** Whether this meta is currently locked. */
+    locked: boolean;
+    /** Whether this meta is disabled (skipped during staleness scheduling). */
+    disabled: boolean;
+    /** Cumulative architect tokens, or null if never run. */
+    architectTokens: number | null;
+    /** Cumulative builder tokens, or null if never run. */
+    builderTokens: number | null;
+    /** Cumulative critic tokens, or null if never run. */
+    criticTokens: number | null;
+    /** Number of direct children in the ownership tree. */
+    children: number;
+    /** The underlying MetaNode from the ownership tree. */
+    node: MetaNode;
+    /** The parsed meta.json content. */
+    meta: MetaJson;
+}
+/** Summary statistics computed from the meta list. */
+interface MetaListSummary {
+    total: number;
+    stale: number;
+    errors: number;
+    locked: number;
+    disabled: number;
+    neverSynthesized: number;
+    tokens: {
+        architect: number;
+        builder: number;
+        critic: number;
+    };
+    stalestPath: string | null;
+    lastSynthesizedPath: string | null;
+    lastSynthesizedAt: string | null;
+}
+/** Full result from listMetas(). */
+interface MetaListResult {
+    summary: MetaListSummary;
+    entries: MetaEntry[];
+    tree: OwnershipTree;
+}
+/**
+ * Discover, deduplicate, and enrich all metas.
+ *
+ * This is the single consolidated function that replaces all duplicated
+ * scan+dedup+enrich logic across the codebase. All enrichment comes from
+ * reading meta.json on disk (the canonical source).
+ *
+ * @param config - Validated synthesis config.
+ * @param watcher - Watcher HTTP client for discovery.
+ * @returns Enriched meta list with summary statistics and ownership tree.
+ */
+declare function listMetas(config: MetaConfig, watcher: WatcherClient): Promise<MetaListResult>;
+
+/**
+ * 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.
+ */
+declare function discoverMetas(watcher: WatcherClient): Promise<string[]>;
+
+/**
+ * Build the ownership tree from discovered .meta/ paths.
+ *
+ * Each .meta/ directory owns its parent directory and all descendants,
+ * except subtrees that contain their own .meta/. For those subtrees,
+ * the parent meta consumes the child meta's synthesis output.
+ *
+ * @module discovery/ownershipTree
+ */
+
+/**
+ * Build an ownership tree from an array of .meta/ directory paths.
+ *
+ * @param metaPaths - Absolute paths to .meta/ directories.
+ * @returns The ownership tree with parent/child relationships.
+ */
+declare function buildOwnershipTree(metaPaths: string[]): OwnershipTree;
+/**
+ * Find a node in the ownership tree by meta path or owner path.
+ *
+ * @param tree - The ownership tree to search.
+ * @param targetPath - Path to search for (meta path or owner path).
+ * @returns The matching node, or undefined if not found.
+ */
+declare function findNode(tree: OwnershipTree, targetPath: string): MetaNode | undefined;
+
+/**
+ * Pino logger factory.
+ *
+ * @module logger
+ */
+
+/** Minimal logger interface accepted by library functions. */
+interface MinimalLogger {
+    debug: (obj: Record<string, unknown>, msg: string) => void;
+    info: (obj: Record<string, unknown>, msg: string) => void;
+    warn: (obj: Record<string, unknown>, msg: string) => void;
+    error: (obj: Record<string, unknown>, msg: string) => void;
+}
+/** Logger configuration options. */
+interface LoggerConfig {
+    /** Log level (default: 'info'). */
+    level?: string;
+    /** Optional file path to write logs to. */
+    file?: string;
+}
+/**
+ * Create a pino logger instance.
+ *
+ * @param config - Optional logger configuration.
+ * @returns Configured pino logger.
+ */
+declare function createLogger(config?: LoggerConfig): pino.Logger;
+
+/**
+ * Compute the file scope owned by a meta node.
+ *
+ * A meta owns: parent dir + all descendants, minus:
+ * - Its own .meta/ subtree (outputs, not inputs)
+ * - Child meta ownerPath subtrees (except their .meta/meta.json for rollups)
+ *
+ * All filesystem enumeration delegated to the watcher's `/walk` endpoint.
+ *
+ * @module discovery/scope
+ */
+
+/**
+ * Get the scope path prefix for a meta node.
+ */
+declare function getScopePrefix(node: MetaNode): string;
+/**
+ * Filter a list of file paths to only those in scope for a meta node.
+ *
+ * Excludes:
+ * - The node's own .meta/ subtree (synthesis outputs are not scope inputs)
+ * - Child meta ownerPath subtrees (except child .meta/meta.json for rollups)
+ *
+ * Watcher walk returns normalized forward-slash paths.
+ */
+declare function filterInScope(node: MetaNode, files: string[]): string[];
+
+/**
+ * In-memory cache for listMetas results with TTL and concurrent refresh guard.
+ *
+ * @module cache
+ */
+
+/**
+ * Caches listMetas results to avoid expensive repeated filesystem walks.
+ * Supports concurrent refresh coalescing and manual invalidation.
+ */
+declare class MetaCache {
+    private result;
+    private updatedAt;
+    private refreshPromise;
+    /** Get cached result or refresh if stale. */
+    get(config: ServiceConfig, watcher: WatcherClient): Promise<MetaListResult>;
+    /** Force-expire the cache so next get() triggers a refresh. */
+    invalidate(): void;
+    private refresh;
+}
+
 /**
  * Hybrid 3-layer synthesis queue.
  *
@@ -648,9 +873,10 @@ declare class Scheduler {
     private readonly queue;
     private readonly logger;
     private readonly watcher;
+    private readonly cache;
     private registrar;
     private currentExpression;
-    constructor(config: ServiceConfig, queue: SynthesisQueue, logger: Logger, watcher: HttpWatcherClient);
+    constructor(config: ServiceConfig, queue: SynthesisQueue, logger: Logger, watcher: HttpWatcherClient, cache: MetaCache);
     /** Set the rule registrar for watcher restart detection. */
     setRegistrar(registrar: RuleRegistrar): void;
     /** Start the cron job. */
@@ -682,277 +908,73 @@ declare class Scheduler {
 }
 
 /**
- * Shared live config hot-reload support.
- *
- * Used by both file-watch reloads in bootstrap and POST /config/apply
- * via the component descriptor's onConfigApply callback.
- *
- * @module configHotReload
- */
-
-/**
- * Fields that require a service restart to take effect.
- *
- * Shared between the descriptor's `onConfigApply` and the file-watcher
- * hot-reload in `bootstrap.ts`.
- */
-declare const RESTART_REQUIRED_FIELDS: readonly ["port", "watcherUrl", "gatewayUrl", "gatewayApiKey", "defaultArchitect", "defaultCritic"];
-
-/**
- * Load and resolve jeeves-meta service config.
- *
- * Supports \@file: indirection and environment-variable substitution (dollar-brace pattern).
- *
- * @module configLoader
- */
-
-/**
- * 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.
- */
-declare function migrateConfigPath(configRoot: string, warn?: (msg: string) => void): void;
-/**
- * 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.
- */
-declare function resolveConfigPath(args: string[]): string;
-/**
- * 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.
- */
-declare function loadServiceConfig(configPath: string): ServiceConfig;
-
-/**
- * Jeeves component descriptor for jeeves-meta.
- *
- * Single source of truth consumed by the service CLI, plugin writer, and
- * config-apply pipeline.
- *
- * @module descriptor
- */
-
-/**
- * Parsed jeeves-meta component descriptor.
- */
-declare const metaDescriptor: JeevesComponentDescriptor;
-
-/**
- * Types for meta discovery and ownership tree.
- *
- * @module discovery/types
- */
-/** A discovered meta node in the ownership tree. */
-interface MetaNode {
-    /** Absolute path to the .meta directory. */
-    metaPath: string;
-    /** Absolute path to the parent directory that this meta owns. */
-    ownerPath: string;
-    /** Depth in the ownership tree (root = 0). */
-    treeDepth: number;
-    /** Child meta nodes (subtrees with their own .meta/). */
-    children: MetaNode[];
-    /** Parent meta node, or null for roots. */
-    parent: MetaNode | null;
-}
-/** The full ownership tree discovered from watchPaths. */
-interface OwnershipTree {
-    /** All discovered meta nodes, keyed by metaPath. */
-    nodes: Map<string, MetaNode>;
-    /** Root nodes (metas with no parent meta). */
-    roots: MetaNode[];
-}
-
-/**
- * Unified meta listing: scan, dedup, enrich.
- *
- * Single source of truth for all consumers that need a list of metas
- * with enriched metadata. Replaces duplicated scan+dedup logic in
- * plugin tools, CLI, and prompt injection.
- *
- * @module discovery/listMetas
- */
-
-/** Enriched meta entry returned by listMetas(). */
-interface MetaEntry {
-    /** Normalized .meta/ directory path. */
-    path: string;
-    /** Tree depth (0 = leaf, higher = more abstract). */
-    depth: number;
-    /** Scheduling emphasis multiplier. */
-    emphasis: number;
-    /** Seconds since last synthesis, or Infinity if never synthesized. */
-    stalenessSeconds: number;
-    /** ISO timestamp of last synthesis, or null. */
-    lastSynthesized: string | null;
-    /** Whether the last synthesis had an error. */
-    hasError: boolean;
-    /** Whether this meta is currently locked. */
-    locked: boolean;
-    /** Whether this meta is disabled (skipped during staleness scheduling). */
-    disabled: boolean;
-    /** Cumulative architect tokens, or null if never run. */
-    architectTokens: number | null;
-    /** Cumulative builder tokens, or null if never run. */
-    builderTokens: number | null;
-    /** Cumulative critic tokens, or null if never run. */
-    criticTokens: number | null;
-    /** Number of direct children in the ownership tree. */
-    children: number;
-    /** The underlying MetaNode from the ownership tree. */
-    node: MetaNode;
-    /** The parsed meta.json content. */
-    meta: MetaJson;
-}
-/** Summary statistics computed from the meta list. */
-interface MetaListSummary {
-    total: number;
-    stale: number;
-    errors: number;
-    locked: number;
-    disabled: number;
-    neverSynthesized: number;
-    tokens: {
-        architect: number;
-        builder: number;
-        critic: number;
-    };
-    stalestPath: string | null;
-    lastSynthesizedPath: string | null;
-    lastSynthesizedAt: string | null;
-}
-/** Full result from listMetas(). */
-interface MetaListResult {
-    summary: MetaListSummary;
-    entries: MetaEntry[];
-    tree: OwnershipTree;
-}
-/**
- * Discover, deduplicate, and enrich all metas.
- *
- * This is the single consolidated function that replaces all duplicated
- * scan+dedup+enrich logic across the codebase. All enrichment comes from
- * reading meta.json on disk (the canonical source).
- *
- * @param config - Validated synthesis config.
- * @param watcher - Watcher HTTP client for discovery.
- * @returns Enriched meta list with summary statistics and ownership tree.
- */
-declare function listMetas(config: MetaConfig, watcher: WatcherClient): Promise<MetaListResult>;
-
-/**
- * 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.
- */
-declare function discoverMetas(watcher: WatcherClient): Promise<string[]>;
-
-/**
- * Build the ownership tree from discovered .meta/ paths.
- *
- * Each .meta/ directory owns its parent directory and all descendants,
- * except subtrees that contain their own .meta/. For those subtrees,
- * the parent meta consumes the child meta's synthesis output.
- *
- * @module discovery/ownershipTree
- */
-
-/**
- * Build an ownership tree from an array of .meta/ directory paths.
+ * Shared live config hot-reload support.
  *
- * @param metaPaths - Absolute paths to .meta/ directories.
- * @returns The ownership tree with parent/child relationships.
- */
-declare function buildOwnershipTree(metaPaths: string[]): OwnershipTree;
-/**
- * Find a node in the ownership tree by meta path or owner path.
+ * Used by both file-watch reloads in bootstrap and POST /config/apply
+ * via the component descriptor's onConfigApply callback.
  *
- * @param tree - The ownership tree to search.
- * @param targetPath - Path to search for (meta path or owner path).
- * @returns The matching node, or undefined if not found.
+ * @module configHotReload
  */
-declare function findNode(tree: OwnershipTree, targetPath: string): MetaNode | undefined;
 
 /**
- * Pino logger factory.
+ * Fields that require a service restart to take effect.
  *
- * @module logger
+ * Shared between the descriptor's `onConfigApply` and the file-watcher
+ * hot-reload in `bootstrap.ts`.
  */
+declare const RESTART_REQUIRED_FIELDS: readonly ["port", "watcherUrl", "gatewayUrl", "gatewayApiKey", "defaultArchitect", "defaultCritic"];
 
-/** Minimal logger interface accepted by library functions. */
-interface MinimalLogger {
-    debug: (obj: Record<string, unknown>, msg: string) => void;
-    info: (obj: Record<string, unknown>, msg: string) => void;
-    warn: (obj: Record<string, unknown>, msg: string) => void;
-    error: (obj: Record<string, unknown>, msg: string) => void;
-}
-/** Logger configuration options. */
-interface LoggerConfig {
-    /** Log level (default: 'info'). */
-    level?: string;
-    /** Optional file path to write logs to. */
-    file?: string;
-}
 /**
- * Create a pino logger instance.
+ * Load and resolve jeeves-meta service config.
  *
- * @param config - Optional logger configuration.
- * @returns Configured pino logger.
+ * Supports \@file: indirection and environment-variable substitution (dollar-brace pattern).
+ *
+ * @module configLoader
  */
-declare function createLogger(config?: LoggerConfig): pino.Logger;
 
 /**
- * Compute the file scope owned by a meta node.
+ * Migrate legacy config path to the new canonical location.
  *
- * A meta owns: parent dir + all descendants, minus:
- * - Its own .meta/ subtree (outputs, not inputs)
- * - Child meta ownerPath subtrees (except their .meta/meta.json for rollups)
+ * 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.
  *
- * All filesystem enumeration delegated to the watcher's `/walk` endpoint.
+ * @param configRoot - Root directory for configuration files.
+ * @param warn - Optional callback for logging the migration warning.
+ */
+declare function migrateConfigPath(configRoot: string, warn?: (msg: string) => void): void;
+/**
+ * Resolve config path from --config flag or JEEVES_META_CONFIG env var.
  *
- * @module discovery/scope
+ * @param args - CLI arguments (process.argv.slice(2)).
+ * @returns Resolved config path.
+ * @throws If no config path found.
  */
-
+declare function resolveConfigPath(args: string[]): string;
 /**
- * Get the scope path prefix for a meta node.
+ * 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.
  */
-declare function getScopePrefix(node: MetaNode): string;
+declare function loadServiceConfig(configPath: string): ServiceConfig;
+
 /**
- * Filter a list of file paths to only those in scope for a meta node.
+ * Jeeves component descriptor for jeeves-meta.
  *
- * Excludes:
- * - The node's own .meta/ subtree (synthesis outputs are not scope inputs)
- * - Child meta ownerPath subtrees (except child .meta/meta.json for rollups)
+ * Single source of truth consumed by the service CLI, plugin writer, and
+ * config-apply pipeline.
  *
- * Watcher walk returns normalized forward-slash paths.
+ * @module descriptor
  */
-declare function filterInScope(node: MetaNode, files: string[]): string[];
+
+/**
+ * Parsed jeeves-meta component descriptor.
+ */
+declare const metaDescriptor: JeevesComponentDescriptor;
 
 /**
  * Exponential moving average helper for token tracking.
@@ -1129,8 +1151,8 @@ declare class GatewayExecutor implements MetaExecutor {
     private cleanupOutputFile;
     /** Invoke a gateway tool via the /tools/invoke HTTP endpoint. */
     private invoke;
-    /** Look up totalTokens for a session via sessions_list. */
-    private getSessionTokens;
+    /** Look up session metadata (tokens, completion status) via sessions_list. */
+    private getSessionInfo;
     /** Whether this executor has been aborted by the operator. */
     get aborted(): boolean;
     /** Abort the currently running spawn, if any. */
@@ -1195,107 +1217,6 @@ declare function buildCriticTask(ctx: MetaContext, meta: MetaJson, config: MetaC
  */
 declare function buildContextPackage(node: MetaNode, meta: MetaJson, watcher: WatcherClient, logger?: MinimalLogger): Promise<MetaContext>;
 
-/**
- * Parse subprocess outputs for each synthesis step.
- *
- * - Architect: returns text \> _builder
- * - Builder: returns JSON \> _content + structured fields
- * - Critic: returns text \> _feedback
- *
- * @module orchestrator/parseOutput
- */
-/** Parsed builder output. */
-interface BuilderOutput {
-    /** Narrative synthesis content. */
-    content: string;
-    /** Additional structured fields (non-underscore keys). */
-    fields: Record<string, unknown>;
-    /** Opaque state for progressive synthesis, if provided by the builder. */
-    state?: unknown;
-}
-/**
- * Parse architect output. The architect returns a task brief as text.
- *
- * @param output - Raw subprocess output.
- * @returns The task brief string.
- */
-declare function parseArchitectOutput(output: string): string;
-/**
- * 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.
- */
-declare function parseBuilderOutput(output: string): BuilderOutput;
-/**
- * Parse critic output. The critic returns evaluation text.
- *
- * @param output - Raw subprocess output.
- * @returns The feedback string.
- */
-declare function parseCriticOutput(output: string): string;
-
-/**
- * Merge synthesis results into meta.json.
- *
- * Preserves human-set fields (_id, _steer, _depth).
- * Writes engine fields (_generatedAt, _structureHash, etc.).
- * Validates against schema before writing.
- *
- * @module orchestrator/merge
- */
-
-/** Options for merging synthesis results. */
-interface MergeOptions {
-    /** Path to .meta directory. */
-    metaPath: string;
-    /** Current meta.json content. */
-    current: MetaJson;
-    /** Architect prompt used (or existing). */
-    architect: string;
-    /** Builder task brief (new or cached). */
-    builder: string;
-    /** Critic prompt used (or existing). */
-    critic: string;
-    /** Builder output (content + structured fields), or null if builder failed. */
-    builderOutput: BuilderOutput | null;
-    /** Critic feedback, or null if critic failed. */
-    feedback: string | null;
-    /** New structure hash. */
-    structureHash: string;
-    /** New synthesis count. */
-    synthesisCount: number;
-    /** Error from any step, or null on full success. */
-    error: MetaError | null;
-    /** Token count from architect step. */
-    architectTokens?: number;
-    /** Token count from builder step. */
-    builderTokens?: number;
-    /** Token count from critic step. */
-    criticTokens?: number;
-    /** Override output path (default: metaPath/meta.json). Used for lock staging. */
-    outputPath?: string;
-    /** Opaque state from builder output for progressive synthesis. */
-    state?: unknown;
-    /**
-     * When true, preserve _content and _generatedAt from current meta.
-     * Used for timeout recovery where state advanced but content did not.
-     */
-    stateOnly?: boolean;
-    /** Phase state record to persist. */
-    phaseState?: PhaseState;
-}
-/**
- * Merge results into meta.json and write atomically.
- *
- * @param options - Merge options.
- * @returns The updated MetaJson.
- * @throws If validation fails (malformed output).
- */
-declare function mergeAndWrite(options: MergeOptions): Promise<MetaJson>;
-
 /**
  * Progress reporting via OpenClaw gateway `/tools/invoke` → `message` tool.
  *
@@ -1335,37 +1256,6 @@ declare class ProgressReporter {
     report(event: ProgressEvent): Promise<void>;
 }
 
-/**
- * Main orchestration entry point — discovery, scheduling, candidate selection.
- *
- * @module orchestrator/orchestrate
- */
-
-/** Callback for synthesis progress events. */
-type ProgressCallback$1 = (event: ProgressEvent) => void | Promise<void>;
-/** Result of a single orchestration cycle. */
-interface OrchestrateResult {
-    /** Whether a synthesis was performed. */
-    synthesized: boolean;
-    /** Path to the meta that was synthesized, if any. */
-    metaPath?: string;
-    /** Error if synthesis failed. */
-    error?: MetaError;
-}
-/**
- * Run a single synthesis cycle.
- *
- * Selects the stalest candidate (or a specific target) and runs the
- * full architect/builder/critic pipeline.
- *
- * @param config - Validated synthesis config.
- * @param executor - Pluggable LLM executor.
- * @param watcher - Watcher HTTP client.
- * @param targetPath - Optional: specific meta/owner path to synthesize instead of stalest candidate.
- * @returns Array with a single result.
- */
-declare function orchestrate(config: MetaConfig, executor: MetaExecutor, watcher: WatcherClient, targetPath?: string, onProgress?: ProgressCallback$1, logger?: MinimalLogger): Promise<OrchestrateResult[]>;
-
 /**
  * Per-phase executors for the phase-state machine.
  *
@@ -1430,58 +1320,46 @@ interface OrchestratePhaseResult {
 declare function orchestratePhase(config: MetaConfig, executor: MetaExecutor, watcher: WatcherClient, targetPath?: string, onProgress?: PhaseProgressCallback, logger?: MinimalLogger): Promise<OrchestratePhaseResult>;
 
 /**
- * Weighted staleness formula for candidate selection.
+ * Parse subprocess outputs for each synthesis step.
  *
- * effectiveStaleness = actualStaleness * (normalizedDepth + 1) ^ (depthWeight * emphasis)
+ * - Architect: returns text \> _builder
+ * - Builder: returns JSON \> _content + structured fields
+ * - Critic: returns text \> _feedback
  *
- * @module scheduling/weightedFormula
+ * @module orchestrator/parseOutput
  */
-
-/** A candidate meta with computed staleness. */
-interface StalenessCandidate {
-    /** The meta node. */
-    node: MetaNode;
-    /** Current meta.json content. */
-    meta: MetaJson;
-    /** Actual staleness in seconds. */
-    actualStaleness: number;
-    /** Effective staleness after depth weighting. */
-    effectiveStaleness: number;
+/** Parsed builder output. */
+interface BuilderOutput {
+    /** Narrative synthesis content. */
+    content: string;
+    /** Additional structured fields (non-underscore keys). */
+    fields: Record<string, unknown>;
+    /** Opaque state for progressive synthesis, if provided by the builder. */
+    state?: unknown;
 }
 /**
- * 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.
+ * Parse architect output. The architect returns a task brief as text.
  *
- * @param candidates - Array of \{ node, meta, actualStaleness \}.
- * @param depthWeight - Exponent for depth weighting (0 = pure staleness).
- * @returns Same array with effectiveStaleness computed.
+ * @param output - Raw subprocess output.
+ * @returns The task brief string.
  */
-declare function computeEffectiveStaleness(candidates: Array<{
-    node: MetaNode;
-    meta: MetaJson;
-    actualStaleness: number;
-}>, depthWeight: number): StalenessCandidate[];
-
+declare function parseArchitectOutput(output: string): string;
 /**
- * Select the best synthesis candidate from stale metas.
+ * Parse builder output. The builder returns JSON with _content and optional fields.
  *
- * Picks the meta with highest effective staleness.
+ * Attempts JSON parse first. If that fails, treats the entire output as _content.
  *
- * @module scheduling/selectCandidate
+ * @param output - Raw subprocess output.
+ * @returns Parsed builder output with content and structured fields.
  */
-
+declare function parseBuilderOutput(output: string): BuilderOutput;
 /**
- * Select the candidate with the highest effective staleness.
+ * Parse critic output. The critic returns evaluation text.
  *
- * @param candidates - Array of candidates with computed effective staleness.
- * @returns The winning candidate, or null if no candidates.
+ * @param output - Raw subprocess output.
+ * @returns The feedback string.
  */
-declare function selectCandidate(candidates: StalenessCandidate[]): StalenessCandidate | null;
+declare function parseCriticOutput(output: string): string;
 
 /**
  * Staleness detection via watcher walk.
@@ -1538,6 +1416,44 @@ declare function isArchitectTriggered(meta: MetaJson, structureChanged: boolean,
  */
 declare function hasSteerChanged(currentSteer: string | undefined, archiveSteer: string | undefined, hasArchive: boolean): boolean;
 
+/**
+ * Weighted staleness formula for candidate selection.
+ *
+ * effectiveStaleness = actualStaleness * (normalizedDepth + 1) ^ (depthWeight * emphasis)
+ *
+ * @module scheduling/weightedFormula
+ */
+
+/** A candidate meta with computed staleness. */
+interface StalenessCandidate {
+    /** The meta node. */
+    node: MetaNode;
+    /** Current meta.json content. */
+    meta: MetaJson;
+    /** Actual staleness in seconds. */
+    actualStaleness: number;
+    /** Effective staleness after depth weighting. */
+    effectiveStaleness: number;
+}
+/**
+ * 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.
+ */
+declare function computeEffectiveStaleness(candidates: Array<{
+    node: MetaNode;
+    meta: MetaJson;
+    actualStaleness: number;
+}>, depthWeight: number): StalenessCandidate[];
+
 /**
  * Route registration for jeeves-meta service.
  *
@@ -1560,6 +1476,10 @@ interface RouteDeps {
     watcher: WatcherClient;
     scheduler: Scheduler | null;
     stats: ServiceStats;
+    /** Cached listMetas results with TTL. */
+    cache: MetaCache;
+    /** Service readiness flag — false during startup. */
+    ready: boolean;
     /** Rule registrar for reporting registration state in /status. */
     registrar?: RuleRegistrar;
     /** Executor instance for abort support. */
@@ -1657,5 +1577,5 @@ declare function registerShutdownHandlers(deps: ShutdownDeps): void;
  */
 declare function startService(config: ServiceConfig, configPath?: string): Promise<void>;
 
-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, startService, toMetaError, verifyRuleApplication };
-export type { BuilderOutput, EnqueueResult, GatewayExecutorOptions, HttpWatcherClientOptions, InferenceRuleSpec, LockState, LoggerConfig, MergeOptions, MetaConfig, MetaContext, MetaEntry, MetaError, MetaExecutor, MetaJson, MetaListResult, MetaListSummary, MetaNode, MetaSpawnOptions, MetaSpawnResult, MinimalLogger, OrchestratePhaseResult, OrchestrateResult, OwnershipTree, PhaseProgressCallback, PhaseResult, ProgressCallback$1 as ProgressCallback, ProgressEvent, ProgressPhase, ProgressReporterConfig, QueueItem, QueueState, RouteDeps, ServerOptions, ServiceConfig, ServiceStats, StalenessCandidate, WatcherClient, WatcherScanPoint, WatcherScanRequest, WatcherScanResult };
+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, startService, toMetaError, verifyRuleApplication };
+export type { BuilderOutput, EnqueueResult, GatewayExecutorOptions, HttpWatcherClientOptions, InferenceRuleSpec, LockState, LoggerConfig, MetaConfig, MetaContext, MetaEntry, MetaError, MetaExecutor, MetaJson, MetaListResult, MetaListSummary, MetaNode, MetaSpawnOptions, MetaSpawnResult, MinimalLogger, OrchestratePhaseResult, OwnershipTree, PhaseProgressCallback, PhaseResult, ProgressEvent, ProgressPhase, ProgressReporterConfig, QueueItem, QueueState, RouteDeps, ServerOptions, ServiceConfig, ServiceStats, StalenessCandidate, WatcherClient, WatcherScanPoint, WatcherScanRequest, WatcherScanResult };