@karmaniverous/jeeves-meta 0.12.4 → 0.13.1

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

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import fs, { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync, mkdirSync, statSync, readdirSync, watchFile } from 'node:fs';
-import path, { join, dirname, relative, posix, resolve } from 'node:path';
+import path, { join, dirname, basename, relative, posix, resolve } from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
 import require$$0$4 from 'path';
 import require$$0$3 from 'fs';
 import require$$0$1 from 'constants';
@@ -9,13 +10,12 @@ import require$$4 from 'util';
 import require$$5 from 'assert';
 import require$$2 from 'events';
 import vm from 'vm';
+import { z } from 'zod';
 import * as commander from 'commander';
 import { homedir, tmpdir } from 'node:os';
-import { z } from 'zod';
 import { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { readFile, unlink, mkdir, writeFile, copyFile } from 'node:fs/promises';
-import { randomUUID, createHash } from 'node:crypto';
 import pino from 'pino';
 import Handlebars from 'handlebars';
 import { Cron } from 'croner';
@@ -7017,6 +7017,32 @@ const COMPONENT_CONFIG_PREFIX = 'jeeves-';
 /** Core config file name. */
 const CONFIG_FILE = 'config.json';
 
+/**
+ * Default port assignments for Jeeves platform services.
+ *
+ * @remarks
+ * Each port number is a historical reference:
+ * - 1934: Wodehouse's *Thank You, Jeeves*; Popper's *Logic of Scientific Discovery*
+ * - 1936: Turing's "On Computable Numbers"; Church's lambda calculus
+ * - 1937: Turing's paper in *Proceedings of the London Mathematical Society*
+ * - 1938: Wodehouse's *The Code of the Woosters*; Shannon's relay/switching paper
+ */
+/** Default port for jeeves-server. */
+const SERVER_PORT = 1934;
+/** Default port for jeeves-watcher. */
+const WATCHER_PORT = 1936;
+/** Default port for jeeves-runner. */
+const RUNNER_PORT = 1937;
+/** Default port for jeeves-meta. */
+const META_PORT = 1938;
+/** Map of service names to their default ports. */
+const DEFAULT_PORTS = {
+    server: SERVER_PORT,
+    watcher: WATCHER_PORT,
+    runner: RUNNER_PORT,
+    meta: META_PORT,
+};
+
 /**
  * Workspace and config root initialization.
  *
@@ -7062,30 +7088,64 @@ function getComponentConfigDir(componentName) {
         throw new Error('jeeves-core: init() must be called first');
     return join(state.configRoot, `${COMPONENT_CONFIG_PREFIX}${componentName}`);
 }
+/** Maximum rename retry attempts on EPERM. */
+const ATOMIC_WRITE_MAX_RETRIES = 3;
+/** Delay between EPERM retries in milliseconds. */
+const ATOMIC_WRITE_RETRY_DELAY_MS = 100;
 /**
  * Write content to a file atomically via a temp file + rename.
  *
+ * @remarks
+ * Retries the rename up to three times on EPERM (Windows file-handle
+ * contention) with a 100 ms synchronous delay between attempts.
+ *
  * @param filePath - Absolute path to the target file.
  * @param content - Content to write.
  */
 function atomicWrite(filePath, content) {
     const dir = dirname(filePath);
-    const tempPath = join(dir, `.${String(Date.now())}.tmp`);
+    const base = basename(filePath, '.md');
+    const tempPath = join(dir, `.${base}.${String(Date.now())}.${randomUUID().slice(0, 8)}.tmp`);
     writeFileSync(tempPath, content, 'utf-8');
-    try {
-        renameSync(tempPath, filePath);
-    }
-    catch (err) {
+    for (let attempt = 0; attempt < ATOMIC_WRITE_MAX_RETRIES; attempt++) {
         try {
-            unlinkSync(tempPath);
+            renameSync(tempPath, filePath);
+            return;
         }
-        catch {
-            /* best-effort cleanup */
+        catch (err) {
+            const isEperm = err instanceof Error &&
+                'code' in err &&
+                err.code === 'EPERM';
+            if (!isEperm || attempt === ATOMIC_WRITE_MAX_RETRIES - 1) {
+                try {
+                    unlinkSync(tempPath);
+                }
+                catch {
+                    /* best-effort cleanup */
+                }
+                throw err;
+            }
+            // Synchronous sleep before retry (acceptable in atomic write context)
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ATOMIC_WRITE_RETRY_DELAY_MS);
         }
-        throw err;
     }
 }
 
+/**
+ * Shared internal utility functions.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Extract a human-readable message from an unknown caught value.
+ *
+ * @param err - The caught value (typically `unknown`).
+ * @returns The error message string.
+ */
+function getErrorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+
 /**
  * Factory for a framework-agnostic config apply HTTP handler.
  *
@@ -7138,8 +7198,7 @@ function readConfigFile(filePath) {
         return JSON.parse(raw);
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.warn(`jeeves-core: Could not read config file ${filePath}: ${msg}`);
+        console.warn(`jeeves-core: Could not read config file ${filePath}: ${getErrorMessage(err)}`);
         return {};
     }
 }
@@ -7188,10 +7247,9 @@ function createConfigApplyHandler(descriptor) {
             atomicWrite(configPath, json);
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
             return {
                 status: 500,
-                body: { error: `Failed to write config: ${message}` },
+                body: { error: `Failed to write config: ${getErrorMessage(err)}` },
             };
         }
         // Call onConfigApply callback if defined
@@ -7200,12 +7258,11 @@ function createConfigApplyHandler(descriptor) {
                 await descriptor.onConfigApply(validatedConfig);
             }
             catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
                 return {
                     status: 200,
                     body: {
                         applied: true,
-                        warning: `Config written but callback failed: ${message}`,
+                        warning: `Config written but callback failed: ${getErrorMessage(err)}`,
                         config: validatedConfig,
                     },
                 };
@@ -7288,8 +7345,7 @@ function createStatusHandler(options) {
                 health = await options.getHealth();
             }
             catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                health = { error: message };
+                health = { error: getErrorMessage(err) };
                 overallStatus = 'degraded';
             }
         }
@@ -7305,6 +7361,70 @@ function createStatusHandler(options) {
         };
     };
 }
+/** Core shared config section. */
+const workspaceCoreConfigSchema = z
+    .object({
+    /** Workspace root path. */
+    workspace: z.string().optional().describe('Workspace root path'),
+    /** Platform config root path. */
+    configRoot: z.string().optional().describe('Platform config root path'),
+    /** OpenClaw gateway URL. */
+    gatewayUrl: z.string().optional().describe('OpenClaw gateway URL'),
+})
+    .partial();
+/** Memory shared config section. */
+const workspaceMemoryConfigSchema = z
+    .object({
+    /** MEMORY.md character budget. */
+    budget: z.number().int().positive().optional().describe('Memory budget'),
+    /** Warning threshold as a fraction of budget. */
+    warningThreshold: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe('Memory warning threshold'),
+    /** Staleness threshold in days. */
+    staleDays: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Memory staleness threshold in days'),
+})
+    .partial();
+/** Workspace config Zod schema. */
+z.object({
+    /** JSON Schema pointer for IDE autocomplete. */
+    $schema: z.string().optional().describe('JSON Schema pointer'),
+    /** Core shared defaults. */
+    core: workspaceCoreConfigSchema.optional(),
+    /** Memory hygiene shared defaults. */
+    memory: workspaceMemoryConfigSchema.optional(),
+});
+/**
+ * Built-in workspace config defaults.
+ *
+ * @remarks
+ * These defaults are used as the lowest-priority tier in config resolution
+ * (below CLI flags, env vars, and `jeeves.config.json` values).
+ */
+const WORKSPACE_CONFIG_DEFAULTS = {
+    core: {
+        workspace: '.',
+        configRoot: './config'}};
+
+/**
+ * Shared CLI defaults and resolution for Jeeves CLI commands.
+ *
+ * @remarks
+ * All root CLI commands share workspace/config-root resolution. Values follow
+ * the shared precedence model: flags → env → jeeves.config.json → defaults.
+ */
+/** Default workspace path. */
+const DEFAULT_WORKSPACE = WORKSPACE_CONFIG_DEFAULTS.core.workspace;
+/** Default config root path. */
+const DEFAULT_CONFIG_ROOT = WORKSPACE_CONFIG_DEFAULTS.core.configRoot;
 
 function getDefaultExportFromCjs (x) {
 	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
@@ -7690,7 +7810,7 @@ function isExecError(err) {
  * (Windows), systemd (Linux), or launchd (macOS) based on platform.
  */
 /** Exec helper that returns stdout. */
-function run(cmd) {
+function run$1(cmd) {
     return execSync(cmd, {
         encoding: 'utf-8',
         timeout: 30_000,
@@ -7743,31 +7863,31 @@ function createWindowsManager(descriptor) {
             const cmdArgs = descriptor.startCommand(cfgPath);
             const appPath = cmdArgs[0];
             const appArgs = cmdArgs.slice(1).join(' ');
-            run(`nssm install ${svcName} ${appPath}`);
+            run$1(`nssm install ${svcName} ${appPath}`);
             if (appArgs) {
-                run(`nssm set ${svcName} AppParameters ${appArgs}`);
+                run$1(`nssm set ${svcName} AppParameters ${appArgs}`);
             }
-            run(`nssm set ${svcName} AppStdout ${join(homedir(), `${svcName}.log`)}`);
-            run(`nssm set ${svcName} AppStderr ${join(homedir(), `${svcName}.log`)}`);
-            run(`nssm set ${svcName} AppRotateFiles 1`);
-            run(`nssm set ${svcName} AppRotateBytes 1048576`);
+            run$1(`nssm set ${svcName} AppStdout ${join(homedir(), `${svcName}.log`)}`);
+            run$1(`nssm set ${svcName} AppStderr ${join(homedir(), `${svcName}.log`)}`);
+            run$1(`nssm set ${svcName} AppRotateFiles 1`);
+            run$1(`nssm set ${svcName} AppRotateBytes 1048576`);
         },
         uninstall(options) {
             const svcName = resolveServiceName(descriptor, options);
             runQuiet(`nssm stop ${svcName}`);
-            run(`nssm remove ${svcName} confirm`);
+            run$1(`nssm remove ${svcName} confirm`);
         },
         start(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`nssm start ${svcName}`);
+            run$1(`nssm start ${svcName}`);
         },
         stop(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`nssm stop ${svcName}`);
+            run$1(`nssm stop ${svcName}`);
         },
         restart(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`nssm restart ${svcName}`);
+            run$1(`nssm restart ${svcName}`);
         },
         status(options) {
             const svcName = resolveServiceName(descriptor, options);
@@ -7812,8 +7932,8 @@ function createLinuxManager(descriptor) {
             const cmdArgs = descriptor.startCommand(cfgPath);
             mkdirSync(unitDir, { recursive: true });
             writeFileSync(unitPath(svcName), buildSystemdUnit(svcName, cmdArgs));
-            run('systemctl --user daemon-reload');
-            run(`systemctl --user enable ${svcName}.service`);
+            run$1('systemctl --user daemon-reload');
+            run$1(`systemctl --user enable ${svcName}.service`);
         },
         uninstall(options) {
             const svcName = resolveServiceName(descriptor, options);
@@ -7826,15 +7946,15 @@ function createLinuxManager(descriptor) {
         },
         start(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`systemctl --user start ${svcName}.service`);
+            run$1(`systemctl --user start ${svcName}.service`);
         },
         stop(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`systemctl --user stop ${svcName}.service`);
+            run$1(`systemctl --user stop ${svcName}.service`);
         },
         restart(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`systemctl --user restart ${svcName}.service`);
+            run$1(`systemctl --user restart ${svcName}.service`);
         },
         status(options) {
             const svcName = resolveServiceName(descriptor, options);
@@ -7898,16 +8018,16 @@ function createMacOSManager(descriptor) {
         },
         start(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`launchctl load ${plistPath(svcName)}`);
+            run$1(`launchctl load ${plistPath(svcName)}`);
         },
         stop(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`launchctl unload ${plistPath(svcName)}`);
+            run$1(`launchctl unload ${plistPath(svcName)}`);
         },
         restart(options) {
             const svcName = resolveServiceName(descriptor, options);
             runQuiet(`launchctl unload ${plistPath(svcName)}`);
-            run(`launchctl load ${plistPath(svcName)}`);
+            run$1(`launchctl load ${plistPath(svcName)}`);
         },
         status(options) {
             const svcName = resolveServiceName(descriptor, options);
@@ -7936,19 +8056,6 @@ function createServiceManager(descriptor) {
     }
 }
 
-/**
- * Shared CLI defaults and option registration for Jeeves CLI commands.
- *
- * @remarks
- * All three CLI commands (install, uninstall, status) share the same
- * `--workspace` and `--config-root` options with the same defaults.
- * This module centralizes them to eliminate duplication.
- */
-/** Default workspace path (current directory). */
-const DEFAULT_WORKSPACE = '.';
-/** Default config root path. */
-const DEFAULT_CONFIG_ROOT = './config';
-
 /**
  * Factory for the standard Jeeves service CLI.
  *
@@ -7957,6 +8064,10 @@ const DEFAULT_CONFIG_ROOT = './config';
  * a component descriptor. Components add domain-specific commands
  * via `descriptor.customCliCommands`.
  */
+function handleCommandError(action, err) {
+    console.error(`${action} failed: ${getErrorMessage(err)}`);
+    process.exitCode = 1;
+}
 /**
  * Create a standard service CLI program from a component descriptor.
  *
@@ -8009,8 +8120,7 @@ function createServiceCli(descriptor) {
             console.log(JSON.stringify(result, null, 2));
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Service unreachable: ${msg}`);
+            console.error(`Service unreachable: ${getErrorMessage(err)}`);
             process.exitCode = 1;
         }
     });
@@ -8028,8 +8138,7 @@ function createServiceCli(descriptor) {
             console.log(JSON.stringify(result, null, 2));
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Config query failed: ${msg}`);
+            console.error(`Config query failed: ${getErrorMessage(err)}`);
             process.exitCode = 1;
         }
     });
@@ -8045,8 +8154,7 @@ function createServiceCli(descriptor) {
             console.log('Config is valid.');
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Validation failed: ${msg}`);
+            console.error(`Validation failed: ${getErrorMessage(err)}`);
             process.exitCode = 1;
         }
     });
@@ -8083,8 +8191,7 @@ function createServiceCli(descriptor) {
             console.log(JSON.stringify(result, null, 2));
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Config apply failed: ${msg}`);
+            console.error(`Config apply failed: ${getErrorMessage(err)}`);
             process.exitCode = 1;
         }
     });
@@ -8121,9 +8228,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}" installed.`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Install failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Install', err);
         }
     });
     serviceCmd
@@ -8136,9 +8241,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}" uninstalled.`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Uninstall failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Uninstall', err);
         }
     });
     serviceCmd
@@ -8151,9 +8254,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}" started.`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Start failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Start', err);
         }
     });
     serviceCmd
@@ -8166,9 +8267,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}" stopped.`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Stop failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Stop', err);
         }
     });
     serviceCmd
@@ -8181,9 +8280,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}" restarted.`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Restart failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Restart', err);
         }
     });
     serviceCmd
@@ -8196,9 +8293,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}": ${state}`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Status failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Status', err);
         }
     });
     // Apply custom CLI commands if provided
@@ -8283,6 +8378,38 @@ function loadConfig(configDir) {
     }
 }
 
+/**
+ * Service URL resolution.
+ *
+ * @remarks
+ * Resolves the URL for a named Jeeves service using the following
+ * resolution order:
+ * 1. Consumer's own component config
+ * 2. Core config (`{configRoot}/jeeves-core/config.json`)
+ * 3. Default port constants
+ */
+/**
+ * Resolve the URL for a named Jeeves service.
+ *
+ * @param serviceName - The service name (e.g., 'watcher', 'runner').
+ * @param consumerName - Optional consumer component name for config override.
+ * @returns The resolved service URL.
+ * @throws Error if `init()` has not been called or the service is unknown.
+ */
+function getServiceUrl(serviceName, consumerName) {
+    // 2. Check core config
+    const coreDir = getCoreConfigDir();
+    const coreConfig = loadConfig(coreDir);
+    const coreUrl = coreConfig?.services[serviceName]?.url;
+    if (coreUrl)
+        return coreUrl;
+    // 3. Fall back to port constants
+    const port = DEFAULT_PORTS[serviceName];
+    {
+        return `http://127.0.0.1:${String(port)}`;
+    }
+}
+
 /**
  * Resolve the bind address for a Jeeves service.
  *
@@ -8320,6 +8447,10 @@ function getBindAddress(componentName) {
     // Tier 4: Default
     return DEFAULT_BIND_ADDRESS;
 }
+/** Async sleep via setTimeout. */
+function sleepAsync(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
 
 /**
  * Shared live config hot-reload support.
@@ -8337,7 +8468,6 @@ function getBindAddress(componentName) {
  */
 const RESTART_REQUIRED_FIELDS = [
     'port',
-    'host',
     'watcherUrl',
     'gatewayUrl',
     'gatewayApiKey',
@@ -8449,8 +8579,6 @@ const autoSeedRuleSchema = z.object({
 const serviceConfigSchema = metaConfigSchema.extend({
     /** HTTP port for the service (default: 1938). */
     port: z.number().int().min(1).max(65535).default(1938),
-    /** Bind address for the HTTP server (default: 127.0.0.1). */
-    host: z.string().default('127.0.0.1'),
     /** Cron schedule for synthesis cycles (default: every 30 min). */
     schedule: z.string().default('*/30 * * * *'),
     /** Optional channel identifier for reporting. */
@@ -8810,6 +8938,174 @@ async function readMetaJson(metaPath) {
     return JSON.parse(raw);
 }
 
+/**
+ * Escape special glob characters in a path so it can be used as a literal
+ * prefix in glob patterns.
+ *
+ * Glob metacharacters `* ? [ ] { } ( ) !` are escaped with a backslash so
+ * that paths containing parentheses (e.g. Slack channel IDs) or other
+ * special characters are matched literally by the watcher's walk endpoint.
+ *
+ * @module escapeGlob
+ */
+/**
+ * Escape glob metacharacters in a string using character-class wrapping.
+ *
+ * Backslash escaping (`\(`) does not work reliably on Windows where `\` is
+ * the path separator. Instead, each metacharacter is wrapped in a character
+ * class (e.g. `(` → `[(]`) which is universally supported by glob libraries.
+ *
+ * Square brackets themselves are escaped as `[[]` and `[]]`.
+ *
+ * @param s - Raw path string.
+ * @returns String with glob metacharacters wrapped in character classes.
+ */
+function escapeGlob(s) {
+    return s.replace(/[*?[\]{}()!]/g, (ch) => `[${ch}]`);
+}
+
+/**
+ * Filter file paths by modification time.
+ *
+ * Shared utility for staleness detection and delta file enumeration.
+ * Uses `fs.statSync` for fast local mtime checks on known paths.
+ *
+ * @module mtimeFilter
+ */
+/**
+ * Check if any file in the list was modified after the given timestamp.
+ *
+ * Short-circuits on first match for efficiency (staleness checks).
+ *
+ * @param files - Array of file paths to check.
+ * @param afterMs - Timestamp in milliseconds. Files with `mtimeMs > afterMs` match.
+ * @returns True if any file was modified after the timestamp.
+ */
+function hasModifiedAfter(files, afterMs) {
+    for (const filePath of files) {
+        try {
+            if (statSync(filePath).mtimeMs > afterMs)
+                return true;
+        }
+        catch {
+            // Unreadable file — skip
+        }
+    }
+    return false;
+}
+/**
+ * Filter files to only those modified after the given timestamp.
+ *
+ * @param files - Array of file paths to filter.
+ * @param afterMs - Timestamp in milliseconds. Files with `mtimeMs > afterMs` are included.
+ * @returns Filtered array of file paths.
+ */
+function filterModifiedAfter(files, afterMs) {
+    return files.filter((filePath) => {
+        try {
+            return statSync(filePath).mtimeMs > afterMs;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+
+/**
+ * Staleness detection via watcher walk.
+ *
+ * A meta is stale when any watched file in its scope was modified after
+ * `_generatedAt`.
+ *
+ * @module scheduling/staleness
+ */
+/**
+ * Check if a meta is stale.
+ *
+ * Uses watcher `/walk` to enumerate watched files under the scope prefix,
+ * then applies a local mtime check (fast) to detect any modifications since
+ * `_generatedAt`. Short-circuits on first match.
+ *
+ * @param scopePrefix - Path prefix for this meta's scope.
+ * @param meta - Current meta.json content.
+ * @param watcher - WatcherClient instance.
+ * @returns True if any file in scope was modified after `_generatedAt`.
+ */
+async function isStale(scopePrefix, meta, watcher) {
+    if (!meta._generatedAt)
+        return true; // Never synthesized = stale
+    const files = await watcher.walk([`${escapeGlob(scopePrefix)}/**`]);
+    // Exclude .meta/ subtree — synthesis outputs must not trigger staleness.
+    // Handle both forward and back slashes for cross-platform compatibility.
+    const metaSep = /[/\\]\.meta(?:[/\\]|$)/;
+    const filtered = files.filter((f) => !metaSep.test(f));
+    return hasModifiedAfter(filtered, new Date(meta._generatedAt).getTime());
+}
+/** Maximum staleness for never-synthesized metas (1 year in seconds). */
+const MAX_STALENESS_SECONDS = 365 * 86_400;
+/**
+ * Compute actual staleness in seconds (now minus _generatedAt).
+ *
+ * Never-synthesized metas are capped at {@link MAX_STALENESS_SECONDS}
+ * (1 year) so that depth weighting can differentiate them. Without
+ * bounding, `Infinity * depthFactor` = `Infinity` for all depths.
+ *
+ * @param meta - Current meta.json content.
+ * @returns Staleness in seconds, capped at 1 year for never-synthesized metas.
+ */
+function actualStaleness(meta) {
+    if (!meta._generatedAt)
+        return MAX_STALENESS_SECONDS;
+    const generatedMs = new Date(meta._generatedAt).getTime();
+    return Math.min((Date.now() - generatedMs) / 1000, MAX_STALENESS_SECONDS);
+}
+/**
+ * Check whether the architect step should be triggered.
+ *
+ * @param meta - Current meta.json.
+ * @param structureChanged - Whether the structure hash changed.
+ * @param steerChanged - Whether the steer directive changed.
+ * @param architectEvery - Config: run architect every N cycles.
+ * @returns True if the architect step should run.
+ */
+function isArchitectTriggered(meta, structureChanged, steerChanged, architectEvery) {
+    return (!meta._builder ||
+        structureChanged ||
+        steerChanged ||
+        (meta._synthesisCount ?? 0) >= architectEvery);
+}
+/**
+ * Detect whether the steer directive changed since the last archive.
+ *
+ * @param currentSteer - Current _steer value (or undefined).
+ * @param archiveSteer - Archive _steer value (or undefined).
+ * @param hasArchive - Whether an archive snapshot exists.
+ * @returns True if steer changed.
+ */
+function hasSteerChanged(currentSteer, archiveSteer, hasArchive) {
+    if (!hasArchive)
+        return Boolean(currentSteer);
+    return currentSteer !== archiveSteer;
+}
+/**
+ * Compute a normalized staleness score (0–1) for display purposes.
+ *
+ * Uses the same depth/emphasis weighting as candidate selection,
+ * normalized to a 30-day window.
+ *
+ * @param stalenessSeconds - Raw staleness in seconds (null = never synthesized).
+ * @param depth - Meta tree depth.
+ * @param emphasis - Scheduling emphasis multiplier.
+ * @param depthWeight - Depth weighting exponent from config.
+ * @returns Normalized score between 0 and 1.
+ */
+function computeStalenessScore(stalenessSeconds, depth, emphasis, depthWeight) {
+    if (stalenessSeconds === null)
+        return 1;
+    const depthFactor = Math.pow(1 + depthWeight, depth);
+    return Math.min(1, (stalenessSeconds * depthFactor * emphasis) / (30 * 86400));
+}
+
 /**
  * Build the ownership tree from discovered .meta/ paths.
  *
@@ -8892,8 +9188,6 @@ function findNode(tree, targetPath) {
  *
  * @module discovery/listMetas
  */
-/** Maximum staleness for never-synthesized metas (1 year in seconds). */
-const MAX_STALENESS_SECONDS$1 = 365 * 86_400;
 /**
  * Discover, deduplicate, and enrich all metas.
  *
@@ -8929,7 +9223,7 @@ async function listMetas(config, watcher) {
         // Compute staleness
         let stalenessSeconds;
         if (neverSynth) {
-            stalenessSeconds = MAX_STALENESS_SECONDS$1;
+            stalenessSeconds = MAX_STALENESS_SECONDS;
         }
         else {
             const genAt = new Date(meta._generatedAt).getTime();
@@ -8962,79 +9256,6 @@ async function listMetas(config, watcher) {
     };
 }
 
-/**
- * Escape special glob characters in a path so it can be used as a literal
- * prefix in glob patterns.
- *
- * Glob metacharacters `* ? [ ] { } ( ) !` are escaped with a backslash so
- * that paths containing parentheses (e.g. Slack channel IDs) or other
- * special characters are matched literally by the watcher's walk endpoint.
- *
- * @module escapeGlob
- */
-/**
- * Escape glob metacharacters in a string using character-class wrapping.
- *
- * Backslash escaping (`\(`) does not work reliably on Windows where `\` is
- * the path separator. Instead, each metacharacter is wrapped in a character
- * class (e.g. `(` → `[(]`) which is universally supported by glob libraries.
- *
- * Square brackets themselves are escaped as `[[]` and `[]]`.
- *
- * @param s - Raw path string.
- * @returns String with glob metacharacters wrapped in character classes.
- */
-function escapeGlob(s) {
-    return s.replace(/[*?[\]{}()!]/g, (ch) => `[${ch}]`);
-}
-
-/**
- * Filter file paths by modification time.
- *
- * Shared utility for staleness detection and delta file enumeration.
- * Uses `fs.statSync` for fast local mtime checks on known paths.
- *
- * @module mtimeFilter
- */
-/**
- * Check if any file in the list was modified after the given timestamp.
- *
- * Short-circuits on first match for efficiency (staleness checks).
- *
- * @param files - Array of file paths to check.
- * @param afterMs - Timestamp in milliseconds. Files with `mtimeMs > afterMs` match.
- * @returns True if any file was modified after the timestamp.
- */
-function hasModifiedAfter(files, afterMs) {
-    for (const filePath of files) {
-        try {
-            if (statSync(filePath).mtimeMs > afterMs)
-                return true;
-        }
-        catch {
-            // Unreadable file — skip
-        }
-    }
-    return false;
-}
-/**
- * Filter files to only those modified after the given timestamp.
- *
- * @param files - Array of file paths to filter.
- * @param afterMs - Timestamp in milliseconds. Files with `mtimeMs > afterMs` are included.
- * @returns Filtered array of file paths.
- */
-function filterModifiedAfter(files, afterMs) {
-    return files.filter((filePath) => {
-        try {
-            return statSync(filePath).mtimeMs > afterMs;
-        }
-        catch {
-            return false;
-        }
-    });
-}
-
 /**
  * Compute the file scope owned by a meta node.
  *
@@ -9111,11 +9332,6 @@ function getDeltaFiles(generatedAt, scopeFiles) {
     return filterModifiedAfter(scopeFiles, new Date(generatedAt).getTime());
 }
 
-/** Sleep for a given number of milliseconds. */
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 /**
  * Error thrown when a spawned subprocess is aborted via AbortController.
  *
@@ -9270,7 +9486,7 @@ class GatewayExecutor {
                 JSON.stringify(spawnResult));
         }
         // Step 2: Poll for completion via sessions_history
-        await sleep(3000);
+        await sleepAsync(3000);
         while (Date.now() < deadline) {
             // Check for abort before each poll iteration
             if (this.controller.signal.aborted) {
@@ -9334,7 +9550,7 @@ class GatewayExecutor {
             catch {
                 // Transient poll failure — keep trying
             }
-            await sleep(this.pollIntervalMs);
+            await sleepAsync(this.pollIntervalMs);
         }
         throw new SpawnTimeoutError('Synthesis subprocess timed out after ' + timeoutMs.toString() + 'ms', outputPath);
     }
@@ -10195,101 +10411,6 @@ function discoverStalestPath(candidates, depthWeight) {
     return winner?.node.metaPath ?? null;
 }
 
-/**
- * Staleness detection via watcher walk.
- *
- * A meta is stale when any watched file in its scope was modified after
- * `_generatedAt`.
- *
- * @module scheduling/staleness
- */
-/**
- * Check if a meta is stale.
- *
- * Uses watcher `/walk` to enumerate watched files under the scope prefix,
- * then applies a local mtime check (fast) to detect any modifications since
- * `_generatedAt`. Short-circuits on first match.
- *
- * @param scopePrefix - Path prefix for this meta's scope.
- * @param meta - Current meta.json content.
- * @param watcher - WatcherClient instance.
- * @returns True if any file in scope was modified after `_generatedAt`.
- */
-async function isStale(scopePrefix, meta, watcher) {
-    if (!meta._generatedAt)
-        return true; // Never synthesized = stale
-    const files = await watcher.walk([`${escapeGlob(scopePrefix)}/**`]);
-    // Exclude .meta/ subtree — synthesis outputs must not trigger staleness.
-    // Handle both forward and back slashes for cross-platform compatibility.
-    const metaSep = /[/\\]\.meta(?:[/\\]|$)/;
-    const filtered = files.filter((f) => !metaSep.test(f));
-    return hasModifiedAfter(filtered, new Date(meta._generatedAt).getTime());
-}
-/** Maximum staleness for never-synthesized metas (1 year in seconds). */
-const MAX_STALENESS_SECONDS = 365 * 86_400;
-/**
- * Compute actual staleness in seconds (now minus _generatedAt).
- *
- * Never-synthesized metas are capped at {@link MAX_STALENESS_SECONDS}
- * (1 year) so that depth weighting can differentiate them. Without
- * bounding, `Infinity * depthFactor` = `Infinity` for all depths.
- *
- * @param meta - Current meta.json content.
- * @returns Staleness in seconds, capped at 1 year for never-synthesized metas.
- */
-function actualStaleness(meta) {
-    if (!meta._generatedAt)
-        return MAX_STALENESS_SECONDS;
-    const generatedMs = new Date(meta._generatedAt).getTime();
-    return Math.min((Date.now() - generatedMs) / 1000, MAX_STALENESS_SECONDS);
-}
-/**
- * Check whether the architect step should be triggered.
- *
- * @param meta - Current meta.json.
- * @param structureChanged - Whether the structure hash changed.
- * @param steerChanged - Whether the steer directive changed.
- * @param architectEvery - Config: run architect every N cycles.
- * @returns True if the architect step should run.
- */
-function isArchitectTriggered(meta, structureChanged, steerChanged, architectEvery) {
-    return (!meta._builder ||
-        structureChanged ||
-        steerChanged ||
-        (meta._synthesisCount ?? 0) >= architectEvery);
-}
-/**
- * Detect whether the steer directive changed since the last archive.
- *
- * @param currentSteer - Current _steer value (or undefined).
- * @param archiveSteer - Archive _steer value (or undefined).
- * @param hasArchive - Whether an archive snapshot exists.
- * @returns True if steer changed.
- */
-function hasSteerChanged(currentSteer, archiveSteer, hasArchive) {
-    if (!hasArchive)
-        return Boolean(currentSteer);
-    return currentSteer !== archiveSteer;
-}
-/**
- * Compute a normalized staleness score (0–1) for display purposes.
- *
- * Uses the same depth/emphasis weighting as candidate selection,
- * normalized to a 30-day window.
- *
- * @param stalenessSeconds - Raw staleness in seconds (null = never synthesized).
- * @param depth - Meta tree depth.
- * @param emphasis - Scheduling emphasis multiplier.
- * @param depthWeight - Depth weighting exponent from config.
- * @returns Normalized score between 0 and 1.
- */
-function computeStalenessScore(stalenessSeconds, depth, emphasis, depthWeight) {
-    if (stalenessSeconds === null)
-        return 1;
-    const depthFactor = Math.pow(1 + depthWeight, depth);
-    return Math.min(1, (stalenessSeconds * depthFactor * emphasis) / (30 * 86400));
-}
-
 /**
  * Shared error utilities.
  *
@@ -11350,7 +11471,10 @@ function buildMetaRules(config) {
                 properties: {
                     file: {
                         properties: {
-                            path: { type: 'string', glob: '**/jeeves-meta.config.json' },
+                            path: {
+                                type: 'string',
+                                glob: '**/jeeves-meta{.config.json,/config.json}',
+                            },
                         },
                     },
                 },
@@ -12511,7 +12635,7 @@ class HttpWatcherClient {
             }
             // Exponential backoff
             const delayMs = this.backoffBaseMs * Math.pow(this.backoffFactor, attempt);
-            await sleep(delayMs);
+            await sleepAsync(delayMs);
         }
         // Unreachable, but TypeScript needs it
         throw new Error('Retry exhausted');
@@ -12730,7 +12854,11 @@ async function startService(config, configPath) {
  */
 /** Build the full API URL for a given port string and path. */
 function apiUrl(port, apiPath) {
-    return `http://127.0.0.1:${port}${apiPath}`;
+    const url = new URL(apiPath, getServiceUrl('meta'));
+    if (port !== DEFAULT_PORT_STR) {
+        url.port = port;
+    }
+    return url.toString();
 }
 /** Wrap an async CLI action with consistent error handling. */
 function withErrorHandling(fn, label) {