@karmaniverous/jeeves-meta 0.11.3 → 0.12.0

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { Command } from 'commander';
+import { JeevesComponentDescriptor } from '@karmaniverous/jeeves';
 import pino, { Logger } from 'pino';
 import * as fastify from 'fastify';
 import { FastifyInstance, FastifyBaseLogger } from 'fastify';
@@ -32,6 +34,160 @@ declare function listArchiveFiles(metaPath: string): string[];
  */
 declare function pruneArchive(metaPath: string, maxArchive: number): Promise<number>;
 
+/**
+ * Per-cycle context package computed by the orchestrator.
+ *
+ * Shared inputs that multiple subprocesses need are computed once
+ * and serialized into each subprocess's task prompt.
+ *
+ * @module interfaces/MetaContext
+ */
+/**
+ * Context package for a single synthesis cycle.
+ *
+ * The orchestrator computes this once per cycle from the meta path,
+ * ownership tree, watcher walk results, and filesystem reads.
+ */
+interface MetaContext {
+    /** Absolute path to the .meta directory. */
+    path: string;
+    /** All files in scope (absolute paths). */
+    scopeFiles: string[];
+    /** Files changed since _generatedAt (absolute paths). */
+    deltaFiles: string[];
+    /** Child _content outputs, keyed by relative path. */
+    childMetas: Record<string, unknown>;
+    /** Cross-referenced meta _content outputs, keyed by owner path. */
+    crossRefMetas: Record<string, unknown>;
+    /** _content from the last cycle, or null on first run. */
+    previousContent: string | null;
+    /** _feedback from the last cycle, or null on first run. */
+    previousFeedback: string | null;
+    /** Current _steer value, or null if unset. */
+    steer: string | null;
+    /** _state from the last cycle, or null on first run. */
+    previousState: unknown;
+    /** Archive snapshot file paths (for steer change detection, etc.). */
+    archives: string[];
+}
+
+/**
+ * Pluggable executor interface for LLM subprocess invocation.
+ *
+ * @module interfaces/MetaExecutor
+ */
+/** Options for spawning a synthesis subprocess. */
+interface MetaSpawnOptions {
+    /** Model override for this subprocess. */
+    model?: string;
+    /** Timeout in seconds. */
+    timeout?: number;
+    /** Label for the spawned session. */
+    label?: string;
+    /** Thinking level (e.g. "low", "medium", "high"). */
+    thinking?: string;
+}
+/** Result of a spawn call, including optional token usage. */
+interface MetaSpawnResult {
+    /** Subprocess output text. */
+    output: string;
+    /** Token count for this call, if available from the executor. */
+    tokens?: number;
+}
+/**
+ * Interface for spawning synthesis subprocesses.
+ *
+ * The executor abstracts the LLM invocation mechanism. The orchestrator
+ * calls spawn() sequentially for architect, builder, and critic steps.
+ * Each call blocks until the subprocess completes and returns its result.
+ */
+interface MetaExecutor {
+    /**
+     * Spawn a subprocess with the given task prompt.
+     *
+     * @param task - Full task prompt for the subprocess.
+     * @param options - Optional model and timeout overrides.
+     * @returns The subprocess result with output and optional token count.
+     */
+    spawn(task: string, options?: MetaSpawnOptions): Promise<MetaSpawnResult>;
+}
+
+/**
+ * Abstraction over the jeeves-watcher HTTP API.
+ *
+ * The service uses this for filesystem enumeration (POST /walk),
+ * virtual rule registration (POST /rules/register), and archive reads
+ * via filter-only point scans (POST /scan).
+ *
+ * @module interfaces/WatcherClient
+ */
+/** An inference rule to register with the watcher. */
+interface InferenceRuleSpec {
+    /** Rule name. */
+    name: string;
+    /** Rule description. */
+    description: string;
+    /** JSON Schema match criteria. */
+    match: Record<string, unknown>;
+    /** Schema array with set keywords. */
+    schema: unknown[];
+    /** Declarative render config. */
+    render?: Record<string, unknown>;
+    /** Handlebars template name. */
+    template?: string;
+    /** Render output format. */
+    renderAs?: string;
+}
+/** Request shape for watcher scan queries. */
+interface WatcherScanRequest {
+    filter: Record<string, unknown>;
+    limit?: number;
+    cursor?: string;
+    fields?: string[];
+    countOnly?: boolean;
+}
+/** A single point returned from watcher scan. */
+interface WatcherScanPoint {
+    id?: string | number;
+    payload?: Record<string, unknown>;
+}
+/** Response shape for watcher scan queries. */
+interface WatcherScanResult {
+    points: WatcherScanPoint[];
+    cursor: string | null;
+}
+/**
+ * Interface for watcher HTTP operations.
+ *
+ * Implementations handle retry with backoff internally.
+ */
+interface WatcherClient {
+    /**
+     * Register virtual inference rules with the watcher.
+     *
+     * @param source - Source identifier (e.g. 'jeeves-meta').
+     * @param rules - Array of inference rules to register.
+     */
+    registerRules(source: string, rules: InferenceRuleSpec[]): Promise<void>;
+    /**
+     * Walk filesystem using glob patterns.
+     *
+     * @param globs - Array of glob patterns to match against.
+     * @returns Promise resolving to array of matching file paths.
+     */
+    walk(globs: string[]): Promise<string[]>;
+    /**
+     * Run a filter-only point scan against the watcher index.
+     *
+     * Optional so narrow test doubles do not need to implement archive-read
+     * support unless a test exercises that path.
+     *
+     * @param request - Scan filter, pagination, and projection options.
+     * @returns Matching points and the next cursor.
+     */
+    scan?(request: WatcherScanRequest): Promise<WatcherScanResult>;
+}
+
 /**
  * Zod schema for jeeves-meta service configuration.
  *
@@ -210,156 +366,329 @@ declare const SERVICE_NAME = "jeeves-meta";
 declare const SERVICE_VERSION: string;
 
 /**
- * Load and resolve jeeves-meta service config.
+ * Custom CLI commands for the jeeves-meta service.
  *
- * Supports \@file: indirection and environment-variable substitution (dollar-brace pattern).
+ * Registered via `descriptor.customCliCommands` and added to the
+ * standard service CLI produced by `createServiceCli`.
  *
- * @module configLoader
+ * @module customCliCommands
  */
 
+/** Register all custom meta commands on the parent program. */
+declare function registerCustomCliCommands(program: Command): void;
+
 /**
- * Resolve config path from --config flag or JEEVES_META_CONFIG env var.
+ * Single-threaded synthesis queue with priority support and deduplication.
  *
- * @param args - CLI arguments (process.argv.slice(2)).
- * @returns Resolved config path.
- * @throws If no config path found.
+ * The scheduler enqueues the stalest candidate each tick. HTTP-triggered
+ * synthesis requests get priority (inserted at front). A path appears at
+ * most once in the queue; re-triggering returns the current position.
+ *
+ * @module queue
  */
-declare function resolveConfigPath(args: string[]): string;
+
+/** A queued synthesis work item. */
+interface QueueItem {
+    path: string;
+    priority: boolean;
+    enqueuedAt: string;
+}
+/** Result returned by {@link SynthesisQueue.enqueue}. */
+interface EnqueueResult {
+    position: number;
+    alreadyQueued: boolean;
+}
+/** Snapshot of queue state for the /status endpoint. */
+interface QueueState {
+    depth: number;
+    items: Array<{
+        path: string;
+        priority: boolean;
+        enqueuedAt: string;
+    }>;
+}
 /**
- * Load service config from a JSON file.
- *
- * Resolves \@file: references for defaultArchitect and defaultCritic,
- * and substitutes environment-variable placeholders throughout.
+ * Single-threaded synthesis queue.
  *
- * @param configPath - Path to config JSON file.
- * @returns Validated ServiceConfig.
+ * Only one synthesis runs at a time. Priority items are inserted at the
+ * front of the queue. Duplicate paths are rejected with their current
+ * position returned.
  */
-declare function loadServiceConfig(configPath: string): ServiceConfig;
+declare class SynthesisQueue {
+    private queue;
+    private currentItem;
+    private processing;
+    private logger;
+    private onEnqueueCallback;
+    /**
+     * Create a new SynthesisQueue.
+     *
+     * @param logger - Pino logger instance.
+     */
+    constructor(logger: Logger);
+    /**
+     * Set a callback to invoke when a new (non-duplicate) item is enqueued.
+     */
+    onEnqueue(callback: () => void): void;
+    /**
+     * Add a path to the synthesis queue.
+     *
+     * @param path - Meta path to synthesize.
+     * @param priority - If true, insert at front of queue.
+     * @returns Position and whether the path was already queued.
+     */
+    enqueue(path: string, priority?: boolean): EnqueueResult;
+    /**
+     * Remove and return the next item from the queue.
+     *
+     * @returns The next QueueItem, or undefined if the queue is empty.
+     */
+    dequeue(): QueueItem | undefined;
+    /** Mark the currently-running synthesis as complete. */
+    complete(): void;
+    /** Number of items waiting in the queue (excludes current). */
+    get depth(): number;
+    /** The item currently being synthesized, or null. */
+    get current(): QueueItem | null;
+    /** A shallow copy of the queued items. */
+    get items(): QueueItem[];
+    /** A shallow copy of the pending items (alias for items). */
+    get pending(): QueueItem[];
+    /**
+     * Remove all pending items from the queue.
+     *
+     * Does not affect the currently-running item.
+     *
+     * @returns The number of items removed.
+     */
+    clear(): number;
+    /**
+     * Check whether a path is in the queue or currently being synthesized.
+     *
+     * @param path - Meta path to look up.
+     * @returns True if the path is queued or currently running.
+     */
+    has(path: string): boolean;
+    /**
+     * Get the 0-indexed position of a path in the queue.
+     *
+     * @param path - Meta path to look up.
+     * @returns Position index, or null if not found in the queue.
+     */
+    getPosition(path: string): number | null;
+    /**
+     * Return a snapshot of queue state for the /status endpoint.
+     *
+     * @returns Queue depth and item list.
+     */
+    getState(): QueueState;
+    /**
+     * Process queued items one at a time until the queue is empty.
+     *
+     * Re-entry is prevented: if already processing, the call returns
+     * immediately. Errors are logged and do not block subsequent items.
+     *
+     * @param synthesizeFn - Async function that performs synthesis for a path.
+     */
+    processQueue(synthesizeFn: (path: string) => Promise<void>): Promise<void>;
+}
 
 /**
- * Per-cycle context package computed by the orchestrator.
+ * Virtual rule registration with jeeves-watcher.
  *
- * Shared inputs that multiple subprocesses need are computed once
- * and serialized into each subprocess's task prompt.
+ * Service registers inference rules at startup (with retry) and
+ * re-registers opportunistically when watcher restart is detected.
  *
- * @module interfaces/MetaContext
+ * @module rules
  */
+
 /**
- * Context package for a single synthesis cycle.
+ * Manages virtual rule registration with watcher.
  *
- * The orchestrator computes this once per cycle from the meta path,
- * ownership tree, watcher walk results, and filesystem reads.
+ * - Registers at startup with exponential retry
+ * - Tracks watcher uptime for restart detection
+ * - Re-registers opportunistically when uptime decreases
  */
-interface MetaContext {
-    /** Absolute path to the .meta directory. */
-    path: string;
-    /** All files in scope (absolute paths). */
-    scopeFiles: string[];
-    /** Files changed since _generatedAt (absolute paths). */
-    deltaFiles: string[];
-    /** Child _content outputs, keyed by relative path. */
-    childMetas: Record<string, unknown>;
-    /** Cross-referenced meta _content outputs, keyed by owner path. */
-    crossRefMetas: Record<string, unknown>;
-    /** _content from the last cycle, or null on first run. */
-    previousContent: string | null;
-    /** _feedback from the last cycle, or null on first run. */
-    previousFeedback: string | null;
-    /** Current _steer value, or null if unset. */
-    steer: string | null;
-    /** _state from the last cycle, or null on first run. */
-    previousState: unknown;
-    /** Archive snapshot file paths (for steer change detection, etc.). */
-    archives: string[];
+declare class RuleRegistrar {
+    private readonly config;
+    private readonly logger;
+    private readonly watcherClient;
+    private lastWatcherUptime;
+    private registered;
+    constructor(config: MetaConfig, logger: Logger, watcher: WatcherClient);
+    /** Whether rules have been successfully registered. */
+    get isRegistered(): boolean;
+    /**
+     * Register rules with watcher. Retries with exponential backoff.
+     * Non-blocking — logs errors but never throws.
+     */
+    register(): Promise<void>;
+    /**
+     * Check watcher uptime and re-register if it decreased (restart detected).
+     *
+     * @param currentUptime - Current watcher uptime in seconds.
+     */
+    checkAndReregister(currentUptime: number): Promise<void>;
 }
 
 /**
- * Pluggable executor interface for LLM subprocess invocation.
+ * HTTP implementation of the WatcherClient interface.
  *
- * @module interfaces/MetaExecutor
+ * Talks to jeeves-watcher's POST /walk and POST /rules/register endpoints
+ * with retry and exponential backoff.
+ *
+ * @module watcher-client/HttpWatcherClient
  */
-/** Options for spawning a synthesis subprocess. */
-interface MetaSpawnOptions {
-    /** Model override for this subprocess. */
-    model?: string;
-    /** Timeout in seconds. */
-    timeout?: number;
-    /** Label for the spawned session. */
-    label?: string;
-    /** Thinking level (e.g. "low", "medium", "high"). */
-    thinking?: string;
+
+/** Options for creating an HttpWatcherClient. */
+interface HttpWatcherClientOptions {
+    /** Base URL for the watcher service (e.g. "http://localhost:1936"). */
+    baseUrl: string;
+    /** Maximum retry attempts for transient failures. Default: 3. */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff. Default: 1000. */
+    backoffBaseMs?: number;
+    /** Multiplier for backoff. Default: 4 (1s, 4s, 16s). */
+    backoffFactor?: number;
+    /** Per-request timeout in ms. Default: 10000. */
+    timeoutMs?: number;
 }
-/** Result of a spawn call, including optional token usage. */
-interface MetaSpawnResult {
-    /** Subprocess output text. */
-    output: string;
-    /** Token count for this call, if available from the executor. */
-    tokens?: number;
+/**
+ * HTTP-based WatcherClient implementation with retry.
+ */
+declare class HttpWatcherClient implements WatcherClient {
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly backoffBaseMs;
+    private readonly backoffFactor;
+    private readonly timeoutMs;
+    constructor(options: HttpWatcherClientOptions);
+    /** POST JSON with retry. */
+    private post;
+    registerRules(source: string, rules: InferenceRuleSpec[]): Promise<void>;
+    walk(globs: string[]): Promise<string[]>;
+    scan(request: WatcherScanRequest): Promise<WatcherScanResult>;
 }
+
 /**
- * Interface for spawning synthesis subprocesses.
+ * Croner-based scheduler that discovers the stalest meta candidate each tick
+ * and enqueues it for synthesis.
  *
- * The executor abstracts the LLM invocation mechanism. The orchestrator
- * calls spawn() sequentially for architect, builder, and critic steps.
- * Each call blocks until the subprocess completes and returns its result.
+ * @module scheduler
  */
-interface MetaExecutor {
+
+/**
+ * Periodic scheduler that discovers stale meta candidates and enqueues them.
+ *
+ * Supports adaptive backoff when no candidates are found and hot-reloadable
+ * cron expressions via {@link Scheduler.updateSchedule}.
+ */
+declare class Scheduler {
+    private job;
+    private backoffMultiplier;
+    private tickCount;
+    private readonly config;
+    private readonly queue;
+    private readonly logger;
+    private readonly watcher;
+    private registrar;
+    private currentExpression;
+    constructor(config: ServiceConfig, queue: SynthesisQueue, logger: Logger, watcher: HttpWatcherClient);
+    /** Set the rule registrar for watcher restart detection. */
+    setRegistrar(registrar: RuleRegistrar): void;
+    /** Start the cron job. */
+    start(): void;
+    /** Stop the cron job. */
+    stop(): void;
+    /** Hot-reload the cron schedule expression. */
+    updateSchedule(expression: string): void;
+    /** Reset backoff multiplier (call after successful synthesis). */
+    resetBackoff(): void;
+    /** Whether the scheduler is currently running. */
+    get isRunning(): boolean;
+    /** Next scheduled tick time, or null if not running. */
+    get nextRunAt(): Date | null;
     /**
-     * Spawn a subprocess with the given task prompt.
+     * Single tick: discover stalest candidate and enqueue it.
      *
-     * @param task - Full task prompt for the subprocess.
-     * @param options - Optional model and timeout overrides.
-     * @returns The subprocess result with output and optional token count.
+     * Skips if the queue is currently processing. Applies adaptive backoff
+     * when no candidates are found.
      */
-    spawn(task: string, options?: MetaSpawnOptions): Promise<MetaSpawnResult>;
+    private tick;
+    /**
+     * Discover the stalest meta candidate via watcher.
+     */
+    private discoverStalest;
 }
 
 /**
- * Abstraction over the jeeves-watcher HTTP API.
+ * Shared live config hot-reload support.
  *
- * The service uses this for filesystem enumeration (POST /walk)
- * and virtual rule registration (POST /rules/register).
+ * Used by both file-watch reloads in bootstrap and POST /config/apply
+ * via the component descriptor's onConfigApply callback.
  *
- * @module interfaces/WatcherClient
+ * @module configHotReload
  */
-/** An inference rule to register with the watcher. */
-interface InferenceRuleSpec {
-    /** Rule name. */
-    name: string;
-    /** Rule description. */
-    description: string;
-    /** JSON Schema match criteria. */
-    match: Record<string, unknown>;
-    /** Schema array with set keywords. */
-    schema: unknown[];
-    /** Declarative render config. */
-    render?: Record<string, unknown>;
-    /** Handlebars template name. */
-    template?: string;
-    /** Render output format. */
-    renderAs?: string;
-}
+
+/**
+ * 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", "host", "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;
+
 /**
- * Interface for watcher HTTP operations.
+ * Jeeves component descriptor for jeeves-meta.
  *
- * Implementations handle retry with backoff internally.
+ * Single source of truth consumed by the service CLI, plugin writer, and
+ * config-apply pipeline.
+ *
+ * @module descriptor
  */
-interface WatcherClient {
-    /**
-     * Register virtual inference rules with the watcher.
-     *
-     * @param source - Source identifier (e.g. 'jeeves-meta').
-     * @param rules - Array of inference rules to register.
-     */
-    registerRules(source: string, rules: InferenceRuleSpec[]): Promise<void>;
-    /**
-     * Walk filesystem using glob patterns.
-     *
-     * @param globs - Array of glob patterns to match against.
-     * @returns Promise resolving to array of matching file paths.
-     */
-    walk(globs: string[]): Promise<string[]>;
-}
+
+/**
+ * Parsed jeeves-meta component descriptor.
+ */
+declare const metaDescriptor: JeevesComponentDescriptor;
 
 /**
  * Types for meta discovery and ownership tree.
@@ -731,11 +1060,16 @@ declare class GatewayExecutor implements MetaExecutor {
     private readonly apiKey;
     private readonly pollIntervalMs;
     private readonly workspaceDir;
+    private controller;
     constructor(options?: GatewayExecutorOptions);
+    /** Remove a temp output file if it exists. */
+    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;
+    /** Abort the currently running spawn, if any. */
+    abort(): void;
     spawn(task: string, options?: MetaSpawnOptions): Promise<MetaSpawnResult>;
 }
 
@@ -1065,239 +1399,6 @@ declare function isArchitectTriggered(meta: MetaJson, structureChanged: boolean,
  */
 declare function hasSteerChanged(currentSteer: string | undefined, archiveSteer: string | undefined, hasArchive: boolean): boolean;
 
-/**
- * Single-threaded synthesis queue with priority support and deduplication.
- *
- * The scheduler enqueues the stalest candidate each tick. HTTP-triggered
- * synthesis requests get priority (inserted at front). A path appears at
- * most once in the queue; re-triggering returns the current position.
- *
- * @module queue
- */
-
-/** A queued synthesis work item. */
-interface QueueItem {
-    path: string;
-    priority: boolean;
-    enqueuedAt: string;
-}
-/** Result returned by {@link SynthesisQueue.enqueue}. */
-interface EnqueueResult {
-    position: number;
-    alreadyQueued: boolean;
-}
-/** Snapshot of queue state for the /status endpoint. */
-interface QueueState {
-    depth: number;
-    items: Array<{
-        path: string;
-        priority: boolean;
-        enqueuedAt: string;
-    }>;
-}
-/**
- * Single-threaded synthesis queue.
- *
- * Only one synthesis runs at a time. Priority items are inserted at the
- * front of the queue. Duplicate paths are rejected with their current
- * position returned.
- */
-declare class SynthesisQueue {
-    private queue;
-    private currentItem;
-    private processing;
-    private logger;
-    private onEnqueueCallback;
-    /**
-     * Create a new SynthesisQueue.
-     *
-     * @param logger - Pino logger instance.
-     */
-    constructor(logger: Logger);
-    /**
-     * Set a callback to invoke when a new (non-duplicate) item is enqueued.
-     */
-    onEnqueue(callback: () => void): void;
-    /**
-     * Add a path to the synthesis queue.
-     *
-     * @param path - Meta path to synthesize.
-     * @param priority - If true, insert at front of queue.
-     * @returns Position and whether the path was already queued.
-     */
-    enqueue(path: string, priority?: boolean): EnqueueResult;
-    /**
-     * Remove and return the next item from the queue.
-     *
-     * @returns The next QueueItem, or undefined if the queue is empty.
-     */
-    dequeue(): QueueItem | undefined;
-    /** Mark the currently-running synthesis as complete. */
-    complete(): void;
-    /** Number of items waiting in the queue (excludes current). */
-    get depth(): number;
-    /** The item currently being synthesized, or null. */
-    get current(): QueueItem | null;
-    /** A shallow copy of the queued items. */
-    get items(): QueueItem[];
-    /**
-     * Check whether a path is in the queue or currently being synthesized.
-     *
-     * @param path - Meta path to look up.
-     * @returns True if the path is queued or currently running.
-     */
-    has(path: string): boolean;
-    /**
-     * Get the 0-indexed position of a path in the queue.
-     *
-     * @param path - Meta path to look up.
-     * @returns Position index, or null if not found in the queue.
-     */
-    getPosition(path: string): number | null;
-    /**
-     * Return a snapshot of queue state for the /status endpoint.
-     *
-     * @returns Queue depth and item list.
-     */
-    getState(): QueueState;
-    /**
-     * Process queued items one at a time until the queue is empty.
-     *
-     * Re-entry is prevented: if already processing, the call returns
-     * immediately. Errors are logged and do not block subsequent items.
-     *
-     * @param synthesizeFn - Async function that performs synthesis for a path.
-     */
-    processQueue(synthesizeFn: (path: string) => Promise<void>): Promise<void>;
-}
-
-/**
- * Virtual rule registration with jeeves-watcher.
- *
- * Service registers inference rules at startup (with retry) and
- * re-registers opportunistically when watcher restart is detected.
- *
- * @module rules
- */
-
-/**
- * Manages virtual rule registration with watcher.
- *
- * - Registers at startup with exponential retry
- * - Tracks watcher uptime for restart detection
- * - Re-registers opportunistically when uptime decreases
- */
-declare class RuleRegistrar {
-    private readonly config;
-    private readonly logger;
-    private readonly watcherClient;
-    private lastWatcherUptime;
-    private registered;
-    constructor(config: MetaConfig, logger: Logger, watcher: WatcherClient);
-    /** Whether rules have been successfully registered. */
-    get isRegistered(): boolean;
-    /**
-     * Register rules with watcher. Retries with exponential backoff.
-     * Non-blocking — logs errors but never throws.
-     */
-    register(): Promise<void>;
-    /**
-     * Check watcher uptime and re-register if it decreased (restart detected).
-     *
-     * @param currentUptime - Current watcher uptime in seconds.
-     */
-    checkAndReregister(currentUptime: number): Promise<void>;
-}
-
-/**
- * HTTP implementation of the WatcherClient interface.
- *
- * Talks to jeeves-watcher's POST /walk and POST /rules/register endpoints
- * with retry and exponential backoff.
- *
- * @module watcher-client/HttpWatcherClient
- */
-
-/** Options for creating an HttpWatcherClient. */
-interface HttpWatcherClientOptions {
-    /** Base URL for the watcher service (e.g. "http://localhost:1936"). */
-    baseUrl: string;
-    /** Maximum retry attempts for transient failures. Default: 3. */
-    maxRetries?: number;
-    /** Base delay in ms for exponential backoff. Default: 1000. */
-    backoffBaseMs?: number;
-    /** Multiplier for backoff. Default: 4 (1s, 4s, 16s). */
-    backoffFactor?: number;
-    /** Per-request timeout in ms. Default: 10000. */
-    timeoutMs?: number;
-}
-/**
- * HTTP-based WatcherClient implementation with retry.
- */
-declare class HttpWatcherClient implements WatcherClient {
-    private readonly baseUrl;
-    private readonly maxRetries;
-    private readonly backoffBaseMs;
-    private readonly backoffFactor;
-    private readonly timeoutMs;
-    constructor(options: HttpWatcherClientOptions);
-    /** POST JSON with retry. */
-    private post;
-    registerRules(source: string, rules: InferenceRuleSpec[]): Promise<void>;
-    walk(globs: string[]): Promise<string[]>;
-}
-
-/**
- * Croner-based scheduler that discovers the stalest meta candidate each tick
- * and enqueues it for synthesis.
- *
- * @module scheduler
- */
-
-/**
- * Periodic scheduler that discovers stale meta candidates and enqueues them.
- *
- * Supports adaptive backoff when no candidates are found and hot-reloadable
- * cron expressions via {@link Scheduler.updateSchedule}.
- */
-declare class Scheduler {
-    private job;
-    private backoffMultiplier;
-    private tickCount;
-    private readonly config;
-    private readonly queue;
-    private readonly logger;
-    private readonly watcher;
-    private registrar;
-    private currentExpression;
-    constructor(config: ServiceConfig, queue: SynthesisQueue, logger: Logger, watcher: HttpWatcherClient);
-    /** Set the rule registrar for watcher restart detection. */
-    setRegistrar(registrar: RuleRegistrar): void;
-    /** Start the cron job. */
-    start(): void;
-    /** Stop the cron job. */
-    stop(): void;
-    /** Hot-reload the cron schedule expression. */
-    updateSchedule(expression: string): void;
-    /** Reset backoff multiplier (call after successful synthesis). */
-    resetBackoff(): void;
-    /** Whether the scheduler is currently running. */
-    get isRunning(): boolean;
-    /** Next scheduled tick time, or null if not running. */
-    get nextRunAt(): Date | null;
-    /**
-     * Single tick: discover stalest candidate and enqueue it.
-     *
-     * Skips if the queue is currently processing. Applies adaptive backoff
-     * when no candidates are found.
-     */
-    private tick;
-    /**
-     * Discover the stalest meta candidate via watcher.
-     */
-    private discoverStalest;
-}
-
 /**
  * Route registration for jeeves-meta service.
  *
@@ -1317,11 +1418,13 @@ interface RouteDeps {
     config: ServiceConfig;
     logger: Logger;
     queue: SynthesisQueue;
-    watcher: HttpWatcherClient;
+    watcher: WatcherClient;
     scheduler: Scheduler | null;
     stats: ServiceStats;
     /** Rule registrar for reporting registration state in /status. */
     registrar?: RuleRegistrar;
+    /** Executor instance for abort support. */
+    executor?: Pick<GatewayExecutor, 'abort'>;
     /** Set to true during graceful shutdown. */
     shuttingDown?: boolean;
 }
@@ -1416,5 +1519,5 @@ declare function registerShutdownHandlers(deps: ShutdownDeps): void;
  */
 declare function startService(config: ServiceConfig, configPath?: string): Promise<void>;
 
-export { DEFAULT_PORT, DEFAULT_PORT_STR, GatewayExecutor, HttpWatcherClient, ProgressReporter, 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, metaErrorSchema, metaJsonSchema, normalizePath, orchestrate, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, readLockState, registerRoutes, registerShutdownHandlers, releaseLock, resolveConfigPath, resolveMetaDir, selectCandidate, serviceConfigSchema, sleep, 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, OrchestrateResult, OwnershipTree, ProgressCallback, ProgressEvent, ProgressPhase, ProgressReporterConfig, QueueItem, QueueState, RouteDeps, ServerOptions, ServiceConfig, ServiceStats, StalenessCandidate, WatcherClient };
+export { DEFAULT_PORT, DEFAULT_PORT_STR, GatewayExecutor, HttpWatcherClient, 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, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, readLockState, registerCustomCliCommands, registerRoutes, registerShutdownHandlers, releaseLock, resolveConfigPath, resolveMetaDir, selectCandidate, serviceConfigSchema, sleep, 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, OrchestrateResult, OwnershipTree, ProgressCallback, ProgressEvent, ProgressPhase, ProgressReporterConfig, QueueItem, QueueState, RouteDeps, ServerOptions, ServiceConfig, ServiceStats, StalenessCandidate, WatcherClient, WatcherScanPoint, WatcherScanRequest, WatcherScanResult };