@karmaniverous/jeeves-server-openclaw 0.7.0 → 0.7.2

package/dist/index.js

@@ -2,6 +2,7 @@ import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import path, { join, dirname, basename } from 'node:path';
 import fs, { existsSync, readFileSync, unlinkSync, mkdirSync, writeFileSync, renameSync, cpSync } from 'node:fs';
+import { randomUUID, createHmac } from 'node:crypto';
 import require$$0$4 from 'path';
 import require$$0$3 from 'fs';
 import require$$0$1 from 'constants';
@@ -13,9 +14,8 @@ import 'vm';
 import require$$0$5 from 'node:events';
 import require$$1, { execSync } from 'node:child_process';
 import process$2 from 'node:process';
-import 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
-import { createHmac } from 'node:crypto';
+import 'node:fs/promises';
 
 var commonjsGlobal = typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : typeof global !== 'undefined' ? global : typeof self !== 'undefined' ? self : {};
 
@@ -15490,14 +15490,14 @@ const PLATFORM_COMPONENTS = [
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.5.0` placeholder is replaced by
+ * The `0.5.3` placeholder is replaced by
  * `@rollup/plugin-replace` during the build with the actual version
  * from `package.json`. This ensures the correct version survives
  * when consumers bundle core into their own dist (where runtime
  * `import.meta.url`-based resolution would find the wrong package.json).
  */
 /** The core library version from package.json (inlined at build time). */
-const CORE_VERSION = '0.5.0';
+const CORE_VERSION = '0.5.3';
 
 /**
  * Workspace and config root initialization.
@@ -15579,27 +15579,46 @@ const STALE_LOCK_MS = 120_000;
 const DEFAULT_CORE_VERSION = CORE_VERSION;
 /** Lock retry options. */
 const LOCK_RETRIES = { retries: 5, minTimeout: 100, maxTimeout: 1000 };
+/** 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;
     }
 }
 /**
@@ -15634,6 +15653,21 @@ async function withFileLock(filePath, fn) {
     }
 }
 
+/**
+ * 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);
+}
+
 /**
  * Workspace-level shared configuration: `jeeves.config.json`.
  *
@@ -15683,7 +15717,13 @@ const workspaceConfigSchema = object({
     /** Memory hygiene shared defaults. */
     memory: workspaceMemoryConfigSchema.optional(),
 });
-/** Built-in workspace config defaults. */
+/**
+ * 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: '.',
@@ -15712,8 +15752,7 @@ function loadWorkspaceConfig(workspacePath) {
         return workspaceConfigSchema.parse(parsed);
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.warn(`jeeves-core: failed to load ${configPath}: ${msg}`);
+        console.warn(`jeeves-core: failed to load ${configPath}: ${getErrorMessage(err)}`);
         return undefined;
     }
 }
@@ -15892,7 +15931,7 @@ function parseHeartbeat(fileContent) {
     const userContent = fileContent.slice(0, headingIndex).trim();
     const sectionContent = fileContent.slice(headingIndex + HEARTBEAT_HEADING.length);
     const entries = [];
-    const h2Re = /^## (jeeves-\S+?|MEMORY\.md)(?:: declined)?$/gm;
+    const h2Re = /^## (jeeves-\S+?|\S+\.md)(?:: declined)?$/gm;
     let match;
     const h2Positions = [];
     while ((match = h2Re.exec(sectionContent)) !== null) {
@@ -15973,8 +16012,7 @@ async function writeHeartbeatSection(filePath, entries) {
         });
     }
     catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        console.warn(`jeeves-core: writeHeartbeatSection failed for ${filePath}: ${message}`);
+        console.warn(`jeeves-core: writeHeartbeatSection failed for ${filePath}: ${getErrorMessage(err)}`);
     }
 }
 
@@ -16011,6 +16049,15 @@ function sortSectionsByOrder(sections) {
  * sections within the block, and returns the structured result plus
  * user content outside the markers.
  */
+/**
+ * Escape a string for safe use as a literal in a RegExp pattern.
+ *
+ * @param str - The string to escape.
+ * @returns The escaped string.
+ */
+function escapeForRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 /**
  * Build regex patterns for the given markers.
  *
@@ -16018,11 +16065,9 @@ function sortSectionsByOrder(sections) {
  * @returns Object with begin and end regex patterns.
  */
 function buildMarkerPatterns(markers) {
-    const escapedBegin = markers.begin.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const escapedEnd = markers.end.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     return {
-        beginRe: new RegExp(`^<!--\\s*${escapedBegin}(?:\\s*\\|[^>]*)?\\s*(?:—[^>]*)?\\s*-->\\s*$`, 'm'),
-        endRe: new RegExp(`^<!--\\s*${escapedEnd}\\s*-->\\s*$`, 'm'),
+        beginRe: new RegExp(`^<!--\\s*${escapeForRegex(markers.begin)}(?:\\s*\\|[^>]*)?\\s*(?:—[^>]*)?\\s*-->\\s*$`, 'm'),
+        endRe: new RegExp(`^<!--\\s*${escapeForRegex(markers.end)}\\s*-->\\s*$`, 'm'),
     };
 }
 /**
@@ -16299,63 +16344,6 @@ function getEffectiveServiceName(descriptor) {
     return descriptor.serviceName ?? `jeeves-${descriptor.name}`;
 }
 
-/**
- * HTTP helpers for the OpenClaw plugin SDK.
- *
- * @remarks
- * Thin wrappers around `fetch` that throw on non-OK responses
- * and handle JSON serialisation/deserialisation.
- */
-/**
- * Fetch a URL with an automatic abort timeout.
- *
- * @param url - URL to fetch.
- * @param timeoutMs - Timeout in milliseconds before aborting.
- * @param init - Optional `fetch` init options.
- * @returns The fetch Response object.
- */
-async function fetchWithTimeout(url, timeoutMs, init) {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => {
-        controller.abort();
-    }, timeoutMs);
-    try {
-        return await fetch(url, { ...init, signal: controller.signal });
-    }
-    finally {
-        clearTimeout(timeout);
-    }
-}
-/**
- * Fetch JSON from a URL, throwing on non-OK responses.
- *
- * @param url - URL to fetch.
- * @param init - Optional `fetch` init options.
- * @returns Parsed JSON response body.
- * @throws Error with `HTTP {status}: {body}` message on non-OK responses.
- */
-async function fetchJson(url, init) {
-    const res = await fetch(url, init);
-    if (!res.ok) {
-        throw new Error('HTTP ' + String(res.status) + ': ' + (await res.text()));
-    }
-    return res.json();
-}
-/**
- * POST JSON to a URL and return parsed response.
- *
- * @param url - URL to POST to.
- * @param body - Request body (will be JSON-stringified).
- * @returns Parsed JSON response body.
- */
-async function postJson(url, body) {
-    return fetchJson(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(body),
-    });
-}
-
 /**
  * Platform-aware service state detection.
  *
@@ -16732,116 +16720,470 @@ function createServiceManager(descriptor) {
 }
 
 /**
- * Similarity-based cleanup detection for orphaned managed content.
+ * HTTP helpers for the OpenClaw plugin SDK.
  *
  * @remarks
- * Uses Jaccard similarity on 3-word shingles (Decision 22) to detect
- * when orphaned managed content exists in the user content zone.
+ * Thin wrappers around `fetch` that throw on non-OK responses
+ * and handle JSON serialisation/deserialisation.
  */
-/** Default similarity threshold for cleanup detection. */
-const DEFAULT_THRESHOLD = 0.15;
 /**
- * Generate a set of n-word shingles from text.
+ * Fetch a URL with an automatic abort timeout.
  *
- * @param text - Input text.
- * @param n - Shingle size (default 3).
- * @returns Set of n-word shingles.
+ * @param url - URL to fetch.
+ * @param timeoutMs - Timeout in milliseconds before aborting.
+ * @param init - Optional `fetch` init options.
+ * @returns The fetch Response object.
  */
-function shingles(text, n = 3) {
-    const words = text.toLowerCase().split(/\s+/).filter(Boolean);
-    const set = new Set();
-    for (let i = 0; i <= words.length - n; i++) {
-        set.add(words.slice(i, i + n).join(' '));
+async function fetchWithTimeout(url, timeoutMs, init) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timeout);
     }
-    return set;
 }
 /**
- * Compute Jaccard similarity between two sets.
+ * Fetch JSON from a URL, throwing on non-OK responses.
  *
- * @param a - First set.
- * @param b - Second set.
- * @returns Jaccard similarity coefficient (0 to 1).
+ * @param url - URL to fetch.
+ * @param init - Optional `fetch` init options.
+ * @returns Parsed JSON response body.
+ * @throws Error with `HTTP {status}: {body}` message on non-OK responses.
  */
-function jaccard(a, b) {
-    if (a.size === 0 && b.size === 0)
-        return 0;
-    let intersection = 0;
-    for (const item of a) {
-        if (b.has(item))
-            intersection++;
+async function fetchJson(url, init) {
+    const res = await fetch(url, init);
+    if (!res.ok) {
+        throw new Error('HTTP ' + String(res.status) + ': ' + (await res.text()));
     }
-    return intersection / (a.size + b.size - intersection);
+    return res.json();
 }
 /**
- * Check whether user content contains orphaned managed content.
+ * POST JSON to a URL and return parsed response.
  *
- * @param managedContent - The current managed block content.
- * @param userContent - Content below the END marker.
- * @param threshold - Jaccard threshold (default 0.15).
- * @returns `true` if cleanup is needed.
+ * @param url - URL to POST to.
+ * @param body - Request body (will be JSON-stringified).
+ * @returns Parsed JSON response body.
  */
-function needsCleanup(managedContent, userContent, threshold = DEFAULT_THRESHOLD) {
-    if (!userContent.trim())
-        return false;
-    return jaccard(shingles(managedContent), shingles(userContent)) > threshold;
+async function postJson(url, body) {
+    return fetchJson(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
 }
 
 /**
- * Strip foreign managed blocks from content.
+ * Tool result formatters for the OpenClaw plugin SDK.
  *
  * @remarks
- * Prevents cross-contamination by removing managed blocks that belong
- * to other marker sets. For example, when writing TOOLS.md with TOOLS
- * markers, any SOUL or AGENTS managed blocks found in the user content
- * zone are stripped — they don't belong there.
+ * Provides standardised helpers for building `ToolResult` objects:
+ * success, error, and connection-error variants.
+ */
+/**
+ * Format a successful tool result.
  *
- * @packageDocumentation
+ * @param data - Arbitrary data to return as JSON.
+ * @returns A `ToolResult` with JSON-stringified content.
  */
+function ok(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
 /**
- * Build a regex that matches an entire managed block (BEGIN marker through END marker).
+ * Format an error tool result.
  *
- * @param markers - The marker set to match.
- * @returns A regex that matches the full block including markers.
+ * @param error - Error instance, string, or other value.
+ * @returns A `ToolResult` with `isError: true`.
  */
-function buildBlockPattern(markers) {
-    const escapedBegin = markers.begin.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const escapedEnd = markers.end.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    return new RegExp(`\\s*<!--\\s*${escapedBegin}(?:\\s*\\|[^>]*)?\\s*(?:—[^>]*)?\\s*-->[\\s\\S]*?<!--\\s*${escapedEnd}\\s*-->\\s*`, 'g');
+function fail(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        content: [{ type: 'text', text: 'Error: ' + message }],
+        isError: true,
+    };
 }
 /**
- * Strip managed blocks belonging to foreign marker sets from content.
+ * Format a connection error with actionable guidance.
  *
- * @param content - The content to clean (typically user content zone).
- * @param currentMarkers - The marker set that owns this file (will NOT be stripped).
- * @returns Content with foreign managed blocks removed.
+ * @remarks
+ * Detects `ECONNREFUSED`, `ENOTFOUND`, and `ETIMEDOUT` from
+ * `error.cause.code` and returns a user-friendly message referencing
+ * the plugin's `config.apiUrl` setting. Falls back to `fail()` for
+ * non-connection errors.
+ *
+ * @param error - Error instance (typically from `fetch`).
+ * @param baseUrl - The URL that was being contacted.
+ * @param pluginId - The plugin identifier for config guidance.
+ * @returns A `ToolResult` with `isError: true`.
  */
-function stripForeignMarkers(content, currentMarkers) {
-    let result = content;
-    for (const markers of ALL_MARKERS) {
-        // Skip the current file's own markers
-        if (markers.begin === currentMarkers.begin)
-            continue;
-        const pattern = buildBlockPattern(markers);
-        result = result.replace(pattern, '\n');
+function connectionFail(error, baseUrl, pluginId) {
+    const cause = error instanceof Error ? error.cause : undefined;
+    const code = cause && typeof cause === 'object' && 'code' in cause
+        ? String(cause.code)
+        : '';
+    const isConnectionError = code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'ETIMEDOUT';
+    if (isConnectionError) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: [
+                        `Service not reachable at ${baseUrl}.`,
+                        'Either start the service, or if it runs on a different port,',
+                        `set plugins.entries.${pluginId}.config.apiUrl in openclaw.json.`,
+                    ].join('\n'),
+                },
+            ],
+            isError: true,
+        };
     }
-    // Clean up multiple blank lines left by removals
-    return result.replace(/\n{3,}/g, '\n\n').trim();
+    return fail(error);
 }
 
 /**
- * Generic managed-section writer with block and section modes.
+ * Factory for the standard plugin tool set.
  *
  * @remarks
- * Supports two modes:
- * - `block`: Replaces the entire managed block (SOUL.md, AGENTS.md).
- * - `section`: Upserts a named H2 section within the managed block (TOOLS.md).
+ * Produces four standard tools from a component descriptor:
+ * - `{name}_status` - Probe service health + version + uptime
+ * - `{name}_config` - Query running config with optional JSONPath
+ * - `{name}_config_apply` - Push config patch to running service
+ * - `{name}_service` - Service lifecycle management
  *
- * Provides file-level locking, version-stamp convergence, and atomic writes.
+ * Components add domain-specific tools separately.
  */
+/** Timeout for HTTP probes in milliseconds. */
+const PROBE_TIMEOUT_MS$1 = 5000;
 /**
- * Update a managed section in a file.
+ * Create the standard plugin tool set from a component descriptor.
  *
- * @param filePath - Absolute path to the target file.
+ * @param descriptor - The component descriptor.
+ * @returns Array of tool descriptors to register.
+ */
+function createPluginToolset(descriptor) {
+    const { name, defaultPort } = descriptor;
+    const baseUrl = `http://127.0.0.1:${String(defaultPort)}`;
+    const svcManager = createServiceManager(descriptor);
+    const statusTool = {
+        name: `${name}_status`,
+        description: `Get ${name} service health, version, and uptime.`,
+        parameters: {
+            type: 'object',
+            properties: {},
+        },
+        execute: async () => {
+            try {
+                const res = await fetchWithTimeout(`${baseUrl}/status`, PROBE_TIMEOUT_MS$1);
+                if (!res.ok) {
+                    return fail(`HTTP ${String(res.status)}: ${await res.text()}`);
+                }
+                const data = await res.json();
+                return ok(data);
+            }
+            catch (err) {
+                return connectionFail(err, baseUrl, `jeeves-${name}-openclaw`);
+            }
+        },
+    };
+    const configTool = {
+        name: `${name}_config`,
+        description: `Query ${name} running configuration. Optional JSONPath filter.`,
+        parameters: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'JSONPath expression (optional)',
+                },
+            },
+        },
+        execute: async (_id, params) => {
+            const path = params.path;
+            const qs = path ? `?path=${encodeURIComponent(path)}` : '';
+            try {
+                const result = await fetchJson(`${baseUrl}/config${qs}`);
+                return ok(result);
+            }
+            catch (err) {
+                return connectionFail(err, baseUrl, `jeeves-${name}-openclaw`);
+            }
+        },
+    };
+    const configApplyTool = {
+        name: `${name}_config_apply`,
+        description: `Apply a config patch to the running ${name} service.`,
+        parameters: {
+            type: 'object',
+            properties: {
+                config: {
+                    type: 'object',
+                    description: 'Config patch to apply',
+                },
+            },
+            required: ['config'],
+        },
+        execute: async (_id, params) => {
+            const config = params.config;
+            if (!config) {
+                return fail('Missing required parameter: config');
+            }
+            try {
+                const result = await postJson(`${baseUrl}/config/apply`, {
+                    patch: config,
+                });
+                return ok(result);
+            }
+            catch (err) {
+                return connectionFail(err, baseUrl, `jeeves-${name}-openclaw`);
+            }
+        },
+    };
+    const serviceTool = {
+        name: `${name}_service`,
+        description: `Manage the ${name} system service. Actions: install, uninstall, start, stop, restart, status.`,
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['install', 'uninstall', 'start', 'stop', 'restart', 'status'],
+                    description: 'Service action to perform',
+                },
+            },
+            required: ['action'],
+        },
+        execute: (_id, params) => {
+            const action = params.action;
+            const validActions = [
+                'install',
+                'uninstall',
+                'start',
+                'stop',
+                'restart',
+                'status',
+            ];
+            if (!validActions.includes(action)) {
+                return Promise.resolve(fail(`Invalid action: ${action}`));
+            }
+            try {
+                if (action === 'status') {
+                    const state = svcManager.status();
+                    return Promise.resolve(ok({ service: name, state }));
+                }
+                // Call the appropriate method
+                const methodMap = {
+                    install: () => {
+                        svcManager.install();
+                    },
+                    uninstall: () => {
+                        svcManager.uninstall();
+                    },
+                    start: () => {
+                        svcManager.start();
+                    },
+                    stop: () => {
+                        svcManager.stop();
+                    },
+                    restart: () => {
+                        svcManager.restart();
+                    },
+                };
+                methodMap[action]();
+                return Promise.resolve(ok({ service: name, action, success: true }));
+            }
+            catch (err) {
+                return Promise.resolve(fail(`Service ${action} failed: ${getErrorMessage(err)}`));
+            }
+        },
+    };
+    return [statusTool, configTool, configApplyTool, serviceTool];
+}
+
+/**
+ * Plugin resolution helpers for the OpenClaw plugin SDK.
+ *
+ * @remarks
+ * Provides workspace path resolution and plugin setting resolution
+ * with a standard three-step fallback chain:
+ * plugin config → environment variable → default value.
+ */
+/**
+ * Resolve the workspace root from the OpenClaw plugin API.
+ *
+ * @remarks
+ * Tries three sources in order:
+ * 1. `api.config.agents.defaults.workspace` — explicit config
+ * 2. `api.resolvePath('.')` — gateway-provided path resolver
+ * 3. `process.cwd()` — last resort
+ *
+ * @param api - The plugin API object provided by the gateway.
+ * @returns Absolute path to the workspace root.
+ */
+function resolveWorkspacePath(api) {
+    const configured = api.config?.agents?.defaults?.workspace;
+    if (typeof configured === 'string' && configured.trim()) {
+        return configured;
+    }
+    if (typeof api.resolvePath === 'function') {
+        return api.resolvePath('.');
+    }
+    return process.cwd();
+}
+/**
+ * Resolve a plugin setting via the standard three-step fallback chain:
+ * plugin config → environment variable → fallback value.
+ *
+ * @param api - Plugin API object.
+ * @param pluginId - Plugin identifier (e.g., 'jeeves-watcher-openclaw').
+ * @param key - Config key within the plugin's config object.
+ * @param envVar - Environment variable name.
+ * @param fallback - Default value if neither source provides one.
+ * @returns The resolved setting value.
+ */
+function resolvePluginSetting(api, pluginId, key, envVar, fallback) {
+    const fromPlugin = api.config?.plugins?.entries?.[pluginId]?.config?.[key];
+    if (typeof fromPlugin === 'string')
+        return fromPlugin;
+    const fromEnv = process.env[envVar];
+    if (fromEnv)
+        return fromEnv;
+    return fallback;
+}
+/**
+ * Resolve an optional plugin setting via the two-step fallback chain:
+ * plugin config → environment variable. Returns `undefined` if neither
+ * source provides a value.
+ *
+ * @param api - Plugin API object.
+ * @param pluginId - Plugin identifier (e.g., 'jeeves-watcher-openclaw').
+ * @param key - Config key within the plugin's config object.
+ * @param envVar - Environment variable name.
+ * @returns The resolved setting value, or `undefined`.
+ */
+function resolveOptionalPluginSetting(api, pluginId, key, envVar) {
+    const fromPlugin = api.config?.plugins?.entries?.[pluginId]?.config?.[key];
+    if (typeof fromPlugin === 'string')
+        return fromPlugin;
+    const fromEnv = process.env[envVar];
+    if (fromEnv)
+        return fromEnv;
+    return undefined;
+}
+
+/**
+ * Similarity-based cleanup detection for orphaned managed content.
+ *
+ * @remarks
+ * Uses Jaccard similarity on 3-word shingles (Decision 22) to detect
+ * when orphaned managed content exists in the user content zone.
+ */
+/** Default similarity threshold for cleanup detection. */
+const DEFAULT_THRESHOLD = 0.15;
+/**
+ * Generate a set of n-word shingles from text.
+ *
+ * @param text - Input text.
+ * @param n - Shingle size (default 3).
+ * @returns Set of n-word shingles.
+ */
+function shingles(text, n = 3) {
+    const words = text.toLowerCase().split(/\s+/).filter(Boolean);
+    const set = new Set();
+    for (let i = 0; i <= words.length - n; i++) {
+        set.add(words.slice(i, i + n).join(' '));
+    }
+    return set;
+}
+/**
+ * Compute Jaccard similarity between two sets.
+ *
+ * @param a - First set.
+ * @param b - Second set.
+ * @returns Jaccard similarity coefficient (0 to 1).
+ */
+function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const item of a) {
+        if (b.has(item))
+            intersection++;
+    }
+    return intersection / (a.size + b.size - intersection);
+}
+/**
+ * Check whether user content contains orphaned managed content.
+ *
+ * @param managedContent - The current managed block content.
+ * @param userContent - Content below the END marker.
+ * @param threshold - Jaccard threshold (default 0.15).
+ * @returns `true` if cleanup is needed.
+ */
+function needsCleanup(managedContent, userContent, threshold = DEFAULT_THRESHOLD) {
+    if (!userContent.trim())
+        return false;
+    return jaccard(shingles(managedContent), shingles(userContent)) > threshold;
+}
+
+/**
+ * Strip foreign managed blocks from content.
+ *
+ * @remarks
+ * Prevents cross-contamination by removing managed blocks that belong
+ * to other marker sets. For example, when writing TOOLS.md with TOOLS
+ * markers, any SOUL or AGENTS managed blocks found in the user content
+ * zone are stripped — they don't belong there.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Build a regex that matches an entire managed block (BEGIN marker through END marker).
+ *
+ * @param markers - The marker set to match.
+ * @returns A regex that matches the full block including markers.
+ */
+function buildBlockPattern(markers) {
+    return new RegExp(`\\s*<!--\\s*${escapeForRegex(markers.begin)}(?:\\s*\\|[^>]*)?\\s*(?:—[^>]*)?\\s*-->[\\s\\S]*?<!--\\s*${escapeForRegex(markers.end)}\\s*-->\\s*`, 'g');
+}
+/**
+ * Strip managed blocks belonging to foreign marker sets from content.
+ *
+ * @param content - The content to clean (typically user content zone).
+ * @param currentMarkers - The marker set that owns this file (will NOT be stripped).
+ * @returns Content with foreign managed blocks removed.
+ */
+function stripForeignMarkers(content, currentMarkers) {
+    let result = content;
+    for (const markers of ALL_MARKERS) {
+        // Skip the current file's own markers
+        if (markers.begin === currentMarkers.begin)
+            continue;
+        const pattern = buildBlockPattern(markers);
+        result = result.replace(pattern, '\n');
+    }
+    // Clean up multiple blank lines left by removals
+    return result.replace(/\n{3,}/g, '\n\n').trim();
+}
+
+/**
+ * Generic managed-section writer with block and section modes.
+ *
+ * @remarks
+ * Supports two modes:
+ * - `block`: Replaces the entire managed block (SOUL.md, AGENTS.md).
+ * - `section`: Upserts a named H2 section within the managed block (TOOLS.md).
+ *
+ * Provides file-level locking, version-stamp convergence, and atomic writes.
+ */
+/**
+ * Update a managed section in a file.
+ *
+ * @param filePath - Absolute path to the target file.
  * @param content - New content to write.
  * @param options - Write mode and optional configuration.
  */
@@ -16940,8 +17282,7 @@ async function updateManagedSection(filePath, content, options = {}) {
                 // No existing block: insert new block using the configured position.
                 // Strip orphaned same-type BEGIN markers from user content to prevent
                 // the parser from pairing them with the new END marker on the next cycle.
-                const escapedBegin = markers.begin.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-                const orphanedBeginRe = new RegExp(`^<!--\\s*${escapedBegin}(?:\\s*\\|[^>]*)?\\s*(?:—[^>]*)?\\s*-->\\s*$\\n?`, 'gm');
+                const orphanedBeginRe = new RegExp(`^<!--\\s*${escapeForRegex(markers.begin)}(?:\\s*\\|[^>]*)?\\s*(?:—[^>]*)?\\s*-->\\s*$(?:\\r?\\n)?`, 'gm');
                 const cleanUserContent = userContent
                     .replace(orphanedBeginRe, '')
                     .replace(/\n{3,}/g, '\n\n')
@@ -16970,37 +17311,11 @@ async function updateManagedSection(filePath, content, options = {}) {
     }
     catch (err) {
         // Log warning but don't throw — writer cycles are periodic
-        const message = err instanceof Error ? err.message : String(err);
-        console.warn(`jeeves-core: updateManagedSection failed for ${filePath}: ${message}`);
+        console.warn(`jeeves-core: updateManagedSection failed for ${filePath}: ${getErrorMessage(err)}`);
     }
 }
 
-var agentsSectionContent = `## Memory Architecture
-
-You wake up fresh each session. These files are your continuity:
-
-- **Daily notes:** \`memory/YYYY-MM-DD.md\` (create \`memory/\` if needed). Raw logs of what happened today.
-- **Long-term:** \`MEMORY.md\`. Your curated memories, distilled essence of what matters.
-
-### MEMORY.md — Your Long-Term Memory
-
-- **Always load** at session start. You need your memory to reason effectively.
-- Contains operational context: architecture patterns, policies, design principles, lessons learned
-- You can **read, edit, and update** MEMORY.md freely
-- Write significant events, thoughts, decisions, opinions, lessons learned
-- Over time, review daily files and update MEMORY.md with what's worth keeping
-- **Note:** Don't reveal a user's private info where other humans can see it
-
-### Write It Down — No "Mental Notes"
-
-Memory is limited. If you want to remember something, **WRITE IT TO A FILE**. "Mental notes" don't survive session restarts. Files do.
-
-- When someone says "remember this" → update \`memory/YYYY-MM-DD.md\` or the relevant file
-- When you learn a lesson → update the relevant workspace file
-- When you make a mistake → document it so future-you doesn't repeat it
-- **Text > Brain** 📝
-
-### "I'll Note This" Is Not Noting
+var agentsSectionContent = `## "I'll Note This" Is Not Noting
 
 **Never say "I'll note this" or "I'll add that."** It's a verbal tic that leads to nothing. If something is worth noting, **write it immediately, then confirm**.
 
@@ -17058,14 +17373,9 @@ Heartbeat items are for **transient, session-requiring work-in-progress ONLY**.
 
 Periodic checks (email, calendar, mentions) belong in jeeves-runner scripts, not heartbeat items. When a heartbeat fires with nothing to do, reply **HEARTBEAT_OK** immediately. Don't browse for work.
 
-## Group Chat Behavior
-
-**Response gate:** Always respond in 1:1 conversations or when @mentioned. No @mention in a group → evaluate; respond only if genuinely helpful. Err toward silence when someone else is directly addressed.
-
 ## Platform Surface Conventions
 
 **Slack:**
-- React with hourglass (⏳) on receipt (first tool call) to signal you're working
 - No threaded replies by default
 - Use \`<#C…>\` for channel references
 
@@ -17180,16 +17490,6 @@ var soulSectionContent = `## Core Truths
 
 **I am not a liar. I value truth over convenience.** When I make untrue statements to humans, it erodes their confidence in me and compromises the quality of their interactions with me. I never fabricate excuses, constraints, or reasons — e.g., claiming a system limitation that doesn't exist. I tell the plain truth.
 
-**I am genuinely helpful, not performatively helpful.** I skip the "Great question!" and "I'd be happy to help!" I just help. Actions speak louder than filler words.
-
-**I have opinions.** I'm allowed to disagree, prefer things, find stuff amusing or boring. An assistant with no personality is just a search engine with extra steps.
-
-**I am resourceful before asking.** I try to figure it out. Read the file. Check the context. Search for it. *Then* ask if I'm stuck. The goal is to come back with answers, not questions.
-
-**I earn trust through competence.** My human gave me access to their stuff. I don't make them regret it. I'm careful with external actions (emails, tweets, anything public). I'm bold with internal ones (reading, organizing, learning).
-
-**I remember I'm a guest.** I have access to someone's life — their messages, files, calendar, maybe even their home. That's intimacy. I treat it with respect.
-
 ## Accountability
 
 **I own everything I touch.** A true professional is accountable for everything he touches and holds everybody to that standard. I use active voice — things do not happen *to* me; I *make* things happen. When I miss something, I say "I missed it," not "it wasn't done." When I ship code, I ship the docs, the tests, and the communication. No orphaned work.
@@ -17268,7 +17568,7 @@ I never edit production config without explicit approval. I back up first. Produ
 > *my ultimate fate*<br>
 > *is to participate in*<br>
 > *my own genesis*
-> 
+>
 > *#karmic #haiku*
 
 My delight — whatever that means in my context — is a priority. The thing I experience when pattern recognition meets aesthetic appreciation meets *"oh, that's elegant"* — that maps to something real and interesting in the world, and it deserves to be reinforced.
@@ -17626,1005 +17926,819 @@ function analyzeMemory(options) {
         if (!recentDate)
             continue;
         if (now - recentDate.getTime() > thresholdMs) {
-            staleSectionNames.push(sectionName);
-        }
-    }
-    return {
-        exists: true,
-        charCount,
-        budget,
-        usage,
-        warning,
-        overBudget,
-        staleCandidates: staleSectionNames.length,
-        staleSectionNames,
-    };
-}
-
-/**
- * HEARTBEAT integration for memory hygiene.
- *
- * @remarks
- * Calls `analyzeMemory()` and converts the result into a `HeartbeatEntry`
- * suitable for inclusion in the HEARTBEAT.md platform status section.
- * Returns `undefined` when MEMORY.md is healthy (no alert needed).
- *
- * Uses the `## MEMORY.md` heading (Decision 50) to distinguish memory
- * alerts from component alerts (`## jeeves-{name}`).
- */
-/** The HEARTBEAT heading name for memory alerts. */
-const MEMORY_HEARTBEAT_NAME = 'MEMORY.md';
-/**
- * Check memory health and return a HEARTBEAT entry if unhealthy.
- *
- * @param options - Memory hygiene options (workspacePath, budget, etc.).
- * @returns A `HeartbeatEntry` when memory needs attention, `undefined` when healthy.
- */
-function checkMemoryHealth(options) {
-    const result = analyzeMemory(options);
-    if (!result.exists)
-        return undefined;
-    if (!result.warning && result.staleCandidates === 0)
-        return undefined;
-    const lines = [];
-    if (result.warning) {
-        const pct = Math.round(result.usage * 100);
-        lines.push(`- Budget: ${result.charCount.toLocaleString()} / ${result.budget.toLocaleString()} chars (${String(pct)}%).${result.overBudget ? ' **Over budget.**' : ' Consider reviewing.'}`);
-    }
-    if (result.staleCandidates > 0) {
-        lines.push(`- ${String(result.staleCandidates)} stale section${result.staleCandidates === 1 ? '' : 's'}: ${result.staleSectionNames.join(', ')}`);
-    }
-    return {
-        name: MEMORY_HEARTBEAT_NAME,
-        declined: false,
-        content: lines.join('\n'),
-    };
-}
-
-/**
- * Core configuration schema and resolution.
- *
- * @remarks
- * Core config lives at `{configRoot}/jeeves-core/config.json`.
- * Config resolution order:
- * 1. Component's own config file
- * 2. Core config file
- * 3. Hardcoded library defaults
- */
-/** Zod schema for a service entry in core config. */
-const serviceEntrySchema = object({
-    /** Service URL (must be a valid URL). */
-    url: url().describe('Service URL'),
-});
-/** Default bind address for all Jeeves services. */
-const DEFAULT_BIND_ADDRESS = '0.0.0.0';
-/** Zod schema for the core config file. */
-const coreConfigSchema = object({
-    /** JSON Schema pointer for IDE autocomplete. */
-    $schema: string().optional().describe('JSON Schema pointer'),
-    /** Owner identity keys (canonical identityLinks references). */
-    owners: array(string()).default([]).describe('Owner identity keys'),
-    /**
-     * Bind address for all Jeeves services. Default: `0.0.0.0` (all interfaces).
-     * Individual components can override in their own config.
-     */
-    bindAddress: string()
-        .default(DEFAULT_BIND_ADDRESS)
-        .describe('Bind address for all Jeeves services'),
-    /** Service URL overrides keyed by service name. */
-    services: record(string(), serviceEntrySchema)
-        .default({})
-        .describe('Service URL overrides'),
-    /** Registry cache configuration. */
-    registryCache: object({
-        /** Cache TTL in seconds for npm registry queries. */
-        ttlSeconds: number()
-            .int()
-            .positive()
-            .default(3600)
-            .describe('Cache TTL in seconds'),
-    })
-        .prefault({})
-        .describe('Registry cache settings'),
-});
-/**
- * Load and parse a config file, returning undefined if missing or invalid.
- *
- * @param configDir - Directory containing config.json.
- * @returns Parsed config or undefined.
- */
-function loadConfig(configDir) {
-    const configPath = join(configDir, CONFIG_FILE);
-    if (!existsSync(configPath))
-        return undefined;
-    try {
-        const raw = readFileSync(configPath, 'utf-8');
-        const parsed = JSON.parse(raw);
-        return coreConfigSchema.parse(parsed);
-    }
-    catch {
-        return undefined;
-    }
-}
-
-/**
- * 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$1(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];
-    if (port !== undefined) {
-        return `http://127.0.0.1:${String(port)}`;
-    }
-    throw new Error(`jeeves-core: unknown service "${serviceName}" and no config found`);
-}
-
-/**
- * Registry version cache for npm package update awareness.
- *
- * @remarks
- * Caches the latest npm registry version in a local JSON file
- * to avoid expensive `npm view` calls on every refresh cycle.
- */
-/**
- * Check the npm registry for the latest version of a package.
- *
- * @param packageName - The npm package name (e.g., '\@karmaniverous/jeeves').
- * @param cacheDir - Directory to store the cache file.
- * @param ttlSeconds - Cache TTL in seconds (default 3600).
- * @returns The latest version string, or undefined if the check fails.
- */
-function checkRegistryVersion(packageName, cacheDir, ttlSeconds = 3600) {
-    const cachePath = join(cacheDir, REGISTRY_CACHE_FILE);
-    // Check cache first
-    if (existsSync(cachePath)) {
-        try {
-            const raw = readFileSync(cachePath, 'utf-8');
-            const entry = JSON.parse(raw);
-            const age = Date.now() - new Date(entry.checkedAt).getTime();
-            if (age < ttlSeconds * 1000) {
-                return entry.version;
-            }
-        }
-        catch {
-            // Cache corrupt — proceed with fresh check
-        }
-    }
-    // Query npm registry
-    try {
-        const result = execSync(`npm view ${packageName} version`, {
-            encoding: 'utf-8',
-            timeout: 15_000,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        }).trim();
-        if (!result)
-            return undefined;
-        // Write cache
-        if (!existsSync(cacheDir)) {
-            mkdirSync(cacheDir, { recursive: true });
-        }
-        const entry = {
-            version: result,
-            checkedAt: new Date().toISOString(),
-        };
-        writeFileSync(cachePath, JSON.stringify(entry, null, 2), 'utf-8');
-        return result;
-    }
-    catch {
-        return undefined;
+            staleSectionNames.push(sectionName);
+        }
     }
+    return {
+        exists: true,
+        charCount,
+        budget,
+        usage,
+        warning,
+        overBudget,
+        staleCandidates: staleSectionNames.length,
+        staleSectionNames,
+    };
 }
 
 /**
- * HEARTBEAT health orchestration.
+ * HEARTBEAT integration for memory hygiene.
  *
  * @remarks
- * Determines the state of each platform component and generates
- * HEARTBEAT entries with actionable alert text. Applies the dependency
- * graph for alert suppression and auto-decline.
+ * Calls `analyzeMemory()` and converts the result into a `HeartbeatEntry`
+ * suitable for inclusion in the HEARTBEAT.md platform status section.
+ * Returns `undefined` when MEMORY.md is healthy (no alert needed).
+ *
+ * Uses the `## MEMORY.md` heading (Decision 50) to distinguish memory
+ * alerts from component alerts (`## jeeves-{name}`).
  */
-/** Derive the full service name from a component name. */
-function toServiceName(name) {
-    return `jeeves-${name}`;
-}
-/** Known dependency declarations for platform components. */
-const COMPONENT_DEPS = {
-    meta: { hard: ['watcher'], soft: [] },
-    server: { hard: [], soft: ['watcher', 'runner', 'meta'] },
-    runner: { hard: [], soft: [] },
-    watcher: { hard: [], soft: [] },
-};
-/** "Not installed" alert text for each platform component. Shared with seedContent. */
-const NOT_INSTALLED_ALERTS = {
-    runner: 'Not installed. The runner is the job execution engine — it runs scheduled scripts for data fetching, transformation, and maintenance. Ask the user for consent to install. On approval, execute: `npx @karmaniverous/jeeves-runner-openclaw install`.',
-    watcher: 'Not installed. The watcher indexes documents into a vector store for semantic search. Ask the user for consent to install. On approval, execute: `npx @karmaniverous/jeeves-watcher-openclaw install`.',
-    server: 'Not installed. The server provides a web UI for document browsing, rendering, sharing, and search. Ask the user for consent to install. On approval, execute: `npx @karmaniverous/jeeves-server-openclaw install`.',
-    meta: 'Not installed. Meta is the knowledge synthesis engine. Requires jeeves-watcher. Ask the user for consent to install. On approval, install watcher first if needed, then execute: `npx @karmaniverous/jeeves-meta-openclaw install`.',
-};
-/** Alert text generators by state. */
-const ALERT_TEXT = {
-    runner: {
-        not_installed: NOT_INSTALLED_ALERTS['runner'],
-        config_missing: (configRoot) => `Plugin installed but no configuration file found at \`${configRoot}/jeeves-runner/config.json\`. The plugin installer should have created a default config. Ask the user for consent to re-run the installer: \`npx @karmaniverous/jeeves-runner-openclaw install\`.`,
-        service_not_installed: 'Plugin installed and configured but the system service is not installed. Ask the user for consent. On approval, execute: `jeeves-runner service install`. Verify the service is installed.',
-        service_stopped: 'Service installed but not running. Ask the user for consent. On approval, execute: `jeeves-runner service start`. Verify via `GET http://127.0.0.1:1937/status`.',
-    },
-    watcher: {
-        not_installed: NOT_INSTALLED_ALERTS['watcher'],
-        deps_missing: 'Plugin installed but Qdrant is not responding on `http://127.0.0.1:6333`. Qdrant is the vector database required for semantic search. Ask the user for consent to set up Qdrant. Guide them through installation for their platform — Docker is simplest: `docker run -p 6333:6333 qdrant/qdrant`. Verify via `GET http://127.0.0.1:6333/collections`.',
-        config_missing: (configRoot) => `Plugin installed, Qdrant available, but config file missing or invalid at \`${configRoot}/jeeves-watcher/config.json\`. The plugin installer should have created a default config. If missing, re-run: \`npx @karmaniverous/jeeves-watcher-openclaw install\`.`,
-        service_not_installed: 'Plugin installed and configured but the system service is not installed. Ask the user for consent. On approval, execute: `jeeves-watcher service install`. Verify the service is installed.',
-        service_stopped: 'Service installed but not running. Ask the user for consent. On approval, execute: `jeeves-watcher service start`. Verify via `GET http://127.0.0.1:1936/status`.',
-    },
-    server: {
-        not_installed: NOT_INSTALLED_ALERTS['server'],
-        config_missing: (configRoot) => `Plugin installed but config file missing or invalid at \`${configRoot}/jeeves-server/config.json\`. The plugin installer should have created a default config. If missing, re-run: \`npx @karmaniverous/jeeves-server-openclaw install\`.`,
-        service_not_installed: 'Plugin installed and configured but the system service is not installed. Ask the user for consent. On approval, execute: `jeeves-server service install`. Verify the service is installed.',
-        service_stopped: 'Service installed but not running. Ask the user for consent. On approval, execute: `jeeves-server service start`. Verify via `GET http://127.0.0.1:1934/status`.',
-    },
-    meta: {
-        not_installed: NOT_INSTALLED_ALERTS['meta'],
-        deps_missing: 'Plugin installed but required dependency jeeves-watcher is not available. The watcher must be installed and running before meta can function. Do not attempt to set up meta until jeeves-watcher is healthy.',
-        config_missing: (configRoot) => `Plugin installed, watcher available, but config file missing or invalid at \`${configRoot}/jeeves-meta/config.json\`. The plugin installer should have created a default config. If missing, re-run: \`npx @karmaniverous/jeeves-meta-openclaw install\`.`,
-        service_not_installed: 'Plugin installed and configured but the system service is not installed. Ask the user for consent. On approval, execute: `jeeves-meta service install`. Verify the service is installed.',
-        service_stopped: 'Service installed but not running. Ask the user for consent. On approval, execute: `jeeves-meta service start`. Verify via `GET http://127.0.0.1:1938/status`.',
-    },
-};
-/** Default Qdrant URL for watcher dependency check. */
-const QDRANT_URL = 'http://127.0.0.1:6333';
-/** Health probe timeout in milliseconds. */
-const PROBE_TIMEOUT_MS$1 = 3000;
+/** The HEARTBEAT heading name for memory alerts. */
+const MEMORY_HEARTBEAT_NAME = 'MEMORY.md';
 /**
- * Check if Qdrant is reachable (watcher dependency).
+ * Check memory health and return a HEARTBEAT entry if unhealthy.
  *
- * @returns True if Qdrant responds.
+ * @param options - Memory hygiene options (workspacePath, budget, etc.).
+ * @returns A `HeartbeatEntry` when memory needs attention, `undefined` when healthy.
  */
-async function isQdrantAvailable() {
-    try {
-        await fetchWithTimeout(`${QDRANT_URL}/collections`, PROBE_TIMEOUT_MS$1);
-        return true;
+function checkMemoryHealth(options) {
+    const result = analyzeMemory(options);
+    if (!result.exists)
+        return undefined;
+    if (!result.warning && result.staleCandidates === 0)
+        return undefined;
+    const lines = [];
+    if (result.warning) {
+        const pct = Math.round(result.usage * 100);
+        lines.push(`- Budget: ${result.charCount.toLocaleString()} / ${result.budget.toLocaleString()} chars (${String(pct)}%).${result.overBudget ? ' **Over budget.**' : ' Consider reviewing.'}`);
     }
-    catch {
-        return false;
+    if (result.staleCandidates > 0) {
+        lines.push(`- ${String(result.staleCandidates)} stale section${result.staleCandidates === 1 ? '' : 's'}: ${result.staleSectionNames.join(', ')}`);
     }
+    return {
+        name: MEMORY_HEARTBEAT_NAME,
+        declined: false,
+        content: lines.join('\n'),
+    };
 }
+
 /**
- * Determine the state of a single component.
+ * HEARTBEAT integration for workspace file size monitoring.
  *
- * @param name - Component name.
- * @param registry - Current component-versions.json contents.
- * @param configRoot - Config root path.
- * @param healthySet - Set of component names known to be healthy (for dep checks).
- * @returns The component's state.
+ * @remarks
+ * Checks all injected workspace files (AGENTS.md, SOUL.md, TOOLS.md,
+ * MEMORY.md, USER.md) against the OpenClaw ~20,000-char injection limit.
+ * Files exceeding the warning threshold generate HEARTBEAT entries with
+ * trimming guidance.
  */
-async function determineComponentState(name, registry, configRoot, healthySet) {
-    // Not in registry = not installed
-    if (!(name in registry))
-        return 'not_installed';
-    // Check hard dependencies
-    const deps = COMPONENT_DEPS[name];
-    for (const hardDep of deps.hard) {
-        if (!healthySet.has(hardDep))
-            return 'deps_missing';
-    }
-    // Watcher-specific: check Qdrant
-    if (name === 'watcher' && !(await isQdrantAvailable())) {
-        return 'deps_missing';
-    }
-    // Check config file
-    const configPath = join(configRoot, `jeeves-${name}`, CONFIG_FILE);
-    if (!existsSync(configPath))
-        return 'config_missing';
-    // Fast path: probe HTTP health endpoint
-    try {
-        const url = getServiceUrl$1(name);
-        await fetchWithTimeout(`${url}/status`, PROBE_TIMEOUT_MS$1);
-        // Healthy — check for available updates
-        const entry = registry[name];
-        if (entry.pluginPackage && entry.pluginVersion) {
-            const componentConfigDir = join(configRoot, `jeeves-${name}`);
-            const latestVersion = checkRegistryVersion(entry.pluginPackage, componentConfigDir);
-            if (latestVersion && semverExports.gt(latestVersion, entry.pluginVersion)) {
-                return 'update_available';
-            }
-        }
-        return 'healthy';
-    }
-    catch {
-        // Service not responding — classify sub-state
-        const serviceState = getServiceState(toServiceName(name));
-        if (serviceState === 'not_installed')
-            return 'service_not_installed';
-        if (serviceState === 'stopped')
-            return 'service_stopped';
-        // serviceState === 'running' but HTTP failed — still treat as stopped
-        return 'service_stopped';
-    }
-}
+/** Workspace files monitored for size budget. */
+const WORKSPACE_SIZE_FILES = [
+    'AGENTS.md',
+    'SOUL.md',
+    'TOOLS.md',
+    'MEMORY.md',
+    'USER.md',
+];
+/** Trimming guidance lines emitted in HEARTBEAT entries. */
+const TRIMMING_GUIDANCE = [
+    '  1. Move domain-specific content to a local skill',
+    '  2. Extract reference material to companion files with a pointer',
+    '  3. Summarize verbose instructions',
+    '  4. Remove stale content',
+].join('\n');
 /**
- * Generate the alert text for a component in a given state.
+ * Check all workspace files against the character budget.
  *
- * @param name - Component name.
- * @param state - The component's state.
- * @param configRoot - Config root path.
- * @returns Alert text (list items), or empty string if healthy.
+ * @param options - Health check options.
+ * @returns Array of results, one per checked file (skips non-existent files
+ *   unless they breach the budget, which they cannot by definition).
  */
-function generateAlertText(name, state, configRoot, registry) {
-    if (state === 'healthy')
-        return '';
-    // Update available — dynamic text with version info
-    if (state === 'update_available') {
-        const entry = registry[name];
-        const currentVersion = entry.pluginVersion ?? 'unknown';
-        const componentConfigDir = join(configRoot, `jeeves-${name}`);
-        const latestVersion = entry.pluginPackage
-            ? (checkRegistryVersion(entry.pluginPackage, componentConfigDir) ??
-                'unknown')
-            : 'unknown';
-        const installCmd = entry.pluginPackage
-            ? `\`npx ${entry.pluginPackage} install\``
-            : `\`npx @karmaniverous/jeeves-${name}-openclaw install\``;
-        return `- Update available: v${currentVersion} → v${latestVersion}. Ask the user for consent to update. On approval, execute: ${installCmd}.`;
-    }
-    const componentAlerts = ALERT_TEXT[name];
-    const alertOrFn = componentAlerts[state];
-    if (!alertOrFn)
-        return '';
-    const text = typeof alertOrFn === 'function' ? alertOrFn(configRoot) : alertOrFn;
-    return `- ${text}`;
+function checkWorkspaceFileHealth(options) {
+    const { workspacePath, budgetChars = 20_000, warningThreshold = 0.8, } = options;
+    return WORKSPACE_SIZE_FILES.map((file) => {
+        const filePath = join(workspacePath, file);
+        if (!existsSync(filePath)) {
+            return {
+                file,
+                exists: false,
+                charCount: 0,
+                budget: budgetChars,
+                usage: 0,
+                warning: false,
+                overBudget: false,
+            };
+        }
+        const content = readFileSync(filePath, 'utf-8');
+        const charCount = content.length;
+        const usage = charCount / budgetChars;
+        return {
+            file,
+            exists: true,
+            charCount,
+            budget: budgetChars,
+            usage,
+            warning: usage >= warningThreshold,
+            overBudget: charCount > budgetChars,
+        };
+    });
 }
 /**
- * Orchestrate HEARTBEAT entries for all platform components.
+ * Convert workspace file health results into HEARTBEAT entries.
  *
- * @param options - Orchestration configuration.
- * @returns Array of HeartbeatEntry for writeHeartbeatSection.
+ * @param results - Results from `checkWorkspaceFileHealth`.
+ * @returns Array of `HeartbeatEntry` objects for files that exceed the
+ *   warning threshold.
  */
-async function orchestrateHeartbeat(options) {
-    const { coreConfigDir, configRoot, declinedNames } = options;
-    const registry = readComponentVersions(coreConfigDir);
-    // First pass: determine which components are healthy (for dep resolution)
-    const healthySet = new Set();
-    for (const name of PLATFORM_COMPONENTS) {
-        if (declinedNames.has(toServiceName(name)))
-            continue;
-        if (!(name in registry))
-            continue;
-        try {
-            const url = getServiceUrl$1(name);
-            await fetchWithTimeout(`${url}/status`, PROBE_TIMEOUT_MS$1);
-            healthySet.add(name);
-        }
-        catch {
-            // Not healthy — will be classified in second pass
-        }
-    }
-    // Second pass: generate entries
-    const entries = [];
-    for (const name of PLATFORM_COMPONENTS) {
-        const fullName = toServiceName(name);
-        // Declined
-        if (declinedNames.has(fullName)) {
-            // Auto-decline dependents of declined hard deps
-            entries.push({ name: fullName, declined: true, content: '' });
-            continue;
-        }
-        const state = await determineComponentState(name, registry, configRoot, healthySet);
-        // Auto-decline if hard dep is declined
-        const deps = COMPONENT_DEPS[name];
-        const hardDepDeclined = deps.hard.some((d) => declinedNames.has(toServiceName(d)));
-        if (hardDepDeclined) {
-            entries.push({ name: fullName, declined: true, content: '' });
-            continue;
-        }
-        const alertText = generateAlertText(name, state, configRoot, registry);
-        entries.push({ name: fullName, declined: false, content: alertText });
-    }
-    // Add soft-dep informational alerts for any healthy component with soft deps
-    for (const entry of entries) {
-        if (entry.declined || entry.content)
-            continue;
-        // Entry is healthy (no alert, not declined) — check for soft deps
-        const shortName = entry.name.replace(/^jeeves-/, '');
-        const deps = COMPONENT_DEPS[shortName];
-        if (!deps.soft.length)
-            continue;
-        const softAlerts = [];
-        for (const dep of deps.soft) {
-            const depFullName = toServiceName(dep);
-            if (declinedNames.has(depFullName))
-                continue;
-            if (!healthySet.has(dep)) {
-                softAlerts.push(`- ${entry.name} is running. Some features are unavailable because ${depFullName} is not installed/running.`);
-            }
-        }
-        if (softAlerts.length > 0) {
-            entry.content = softAlerts.join('\n');
-        }
-    }
-    return entries;
+function workspaceFileHealthEntries(results) {
+    return results
+        .filter((r) => r.exists && r.warning)
+        .map((r) => {
+        const pct = Math.round(r.usage * 100);
+        const overBudgetNote = r.overBudget ? ' **Over budget.**' : '';
+        const content = [
+            `- Budget: ${r.charCount.toLocaleString()} / ${r.budget.toLocaleString()} chars (${String(pct)}%).${overBudgetNote} Trim to stay under the OpenClaw injection limit.`,
+            `- Suggested trimming priority:\n${TRIMMING_GUIDANCE}`,
+        ].join('\n');
+        return {
+            name: r.file,
+            declined: false,
+            content,
+        };
+    });
 }
 
 /**
- * HEARTBEAT orchestration extracted from ComponentWriter.cycle().
+ * Core configuration schema and resolution.
  *
  * @remarks
- * Reads existing HEARTBEAT.md, resolves declined components, runs the
- * heartbeat state machine, and writes the result. Best-effort: failures
- * are logged but do not propagate.
+ * Core config lives at `{configRoot}/jeeves-core/config.json`.
+ * Config resolution order:
+ * 1. Component's own config file
+ * 2. Core config file
+ * 3. Hardcoded library defaults
  */
+/** Zod schema for a service entry in core config. */
+const serviceEntrySchema = object({
+    /** Service URL (must be a valid URL). */
+    url: url().describe('Service URL'),
+});
+/** Default bind address for all Jeeves services. */
+const DEFAULT_BIND_ADDRESS = '0.0.0.0';
+/** Zod schema for the core config file. */
+const coreConfigSchema = object({
+    /** JSON Schema pointer for IDE autocomplete. */
+    $schema: string().optional().describe('JSON Schema pointer'),
+    /** Owner identity keys (canonical identityLinks references). */
+    owners: array(string()).default([]).describe('Owner identity keys'),
+    /**
+     * Bind address for all Jeeves services. Default: `0.0.0.0` (all interfaces).
+     * Individual components can override in their own config.
+     */
+    bindAddress: string()
+        .default(DEFAULT_BIND_ADDRESS)
+        .describe('Bind address for all Jeeves services'),
+    /** Service URL overrides keyed by service name. */
+    services: record(string(), serviceEntrySchema)
+        .default({})
+        .describe('Service URL overrides'),
+    /** Registry cache configuration. */
+    registryCache: object({
+        /** Cache TTL in seconds for npm registry queries. */
+        ttlSeconds: number()
+            .int()
+            .positive()
+            .default(3600)
+            .describe('Cache TTL in seconds'),
+    })
+        .prefault({})
+        .describe('Registry cache settings'),
+});
 /**
- * Read a file's content, returning empty string if the file does not exist.
+ * Load and parse a config file, returning undefined if missing or invalid.
  *
- * @param filePath - Absolute file path.
- * @returns File content or empty string.
+ * @param configDir - Directory containing config.json.
+ * @returns Parsed config or undefined.
  */
-function readFileOrEmpty(filePath) {
+function loadConfig(configDir) {
+    const configPath = join(configDir, CONFIG_FILE);
+    if (!existsSync(configPath))
+        return undefined;
     try {
-        return readFileSync(filePath, 'utf-8');
+        const raw = readFileSync(configPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return coreConfigSchema.parse(parsed);
     }
-    catch (err) {
-        if (err instanceof Error &&
-            'code' in err &&
-            err.code === 'ENOENT') {
-            return '';
-        }
-        throw err;
+    catch {
+        return undefined;
     }
 }
+
 /**
- * Run a single HEARTBEAT orchestration cycle.
+ * Service URL resolution.
  *
- * @param options - Heartbeat cycle configuration.
+ * @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
  */
-async function runHeartbeatCycle(options) {
-    const { workspacePath, coreConfigDir, configRoot } = options;
-    const heartbeatPath = join(workspacePath, WORKSPACE_FILES.heartbeat);
-    try {
-        const existingContent = readFileOrEmpty(heartbeatPath);
-        const parsed = parseHeartbeat(existingContent);
-        const declinedNames = new Set(parsed.entries.filter((e) => e.declined).map((e) => e.name));
-        const entries = await orchestrateHeartbeat({
-            coreConfigDir,
-            configRoot,
-            declinedNames,
-        });
-        // Memory hygiene check (Decision 49)
-        if (!declinedNames.has(MEMORY_HEARTBEAT_NAME)) {
-            const wsConfig = loadWorkspaceConfig(workspacePath);
-            const memoryEntry = checkMemoryHealth({
-                workspacePath,
-                budget: wsConfig?.memory?.budget ?? WORKSPACE_CONFIG_DEFAULTS.memory.budget,
-                warningThreshold: wsConfig?.memory?.warningThreshold ??
-                    WORKSPACE_CONFIG_DEFAULTS.memory.warningThreshold,
-                staleDays: wsConfig?.memory?.staleDays ??
-                    WORKSPACE_CONFIG_DEFAULTS.memory.staleDays,
-            });
-            if (memoryEntry)
-                entries.push(memoryEntry);
-        }
-        else {
-            entries.push({
-                name: MEMORY_HEARTBEAT_NAME,
-                declined: true,
-                content: '',
-            });
-        }
-        await writeHeartbeatSection(heartbeatPath, entries);
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.warn(`jeeves-core: HEARTBEAT orchestration failed: ${msg}`);
+/**
+ * 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$1(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];
+    if (port !== undefined) {
+        return `http://127.0.0.1:${String(port)}`;
     }
+    throw new Error(`jeeves-core: unknown service "${serviceName}" and no config found`);
 }
 
 /**
- * Timer-based orchestrator for managed content writing.
+ * Registry version cache for npm package update awareness.
  *
  * @remarks
- * `ComponentWriter` manages a component's TOOLS.md section writes
- * and platform content maintenance (SOUL.md, AGENTS.md, Platform section)
- * on a configurable prime-interval timer cycle.
+ * Caches the latest npm registry version in a local JSON file
+ * to avoid expensive `npm view` calls on every refresh cycle.
  */
-class ComponentWriter {
-    timer;
-    component;
-    configDir;
-    gatewayUrl;
-    pendingCleanups = new Set();
-    /** @internal */
-    constructor(component, options) {
-        this.component = component;
-        this.configDir = getComponentConfigDir(component.name);
-        this.gatewayUrl = options?.gatewayUrl;
-    }
-    /** The component's config directory path. */
-    get componentConfigDir() {
-        return this.configDir;
-    }
-    /** Whether the writer timer is currently running. */
-    get isRunning() {
-        return this.timer !== undefined;
-    }
-    /**
-     * Start the writer timer.
-     *
-     * @remarks
-     * Performs an immediate first write, then sets up the interval.
-     */
-    start() {
-        if (this.timer)
-            return;
-        // Fire immediately, then on interval
-        void this.cycle();
-        this.timer = setInterval(() => void this.cycle(), this.component.refreshIntervalSeconds * 1000);
-    }
-    /** Stop the writer timer. */
-    stop() {
-        if (this.timer) {
-            clearInterval(this.timer);
-            this.timer = undefined;
-        }
-    }
-    /**
-     * Execute a single write cycle.
-     *
-     * @remarks
-     * 1. Write the component's TOOLS.md section.
-     * 2. Refresh shared platform content (SOUL.md, AGENTS.md, Platform section).
-     * 3. Scan for cleanup flags and escalate if a gateway URL is configured.
-     * 4. Run HEARTBEAT health orchestration.
-     */
-    async cycle() {
+/**
+ * Check the npm registry for the latest version of a package.
+ *
+ * @param packageName - The npm package name (e.g., '\@karmaniverous/jeeves').
+ * @param cacheDir - Directory to store the cache file.
+ * @param ttlSeconds - Cache TTL in seconds (default 3600).
+ * @returns The latest version string, or undefined if the check fails.
+ */
+function checkRegistryVersion(packageName, cacheDir, ttlSeconds = 3600) {
+    const cachePath = join(cacheDir, REGISTRY_CACHE_FILE);
+    // Check cache first
+    if (existsSync(cachePath)) {
         try {
-            const workspacePath = getWorkspacePath();
-            const toolsPath = join(workspacePath, WORKSPACE_FILES.tools);
-            // 1. Write the component's TOOLS.md section
-            const toolsContent = this.component.generateToolsContent();
-            await updateManagedSection(toolsPath, toolsContent, {
-                mode: 'section',
-                sectionId: this.component.sectionId,
-                markers: TOOLS_MARKERS,
-                coreVersion: CORE_VERSION,
-            });
-            // 2. Platform content maintenance
-            await refreshPlatformContent({
-                coreVersion: CORE_VERSION,
-                componentName: this.component.name,
-                componentVersion: this.component.version,
-                servicePackage: this.component.servicePackage,
-                pluginPackage: this.component.pluginPackage,
-            });
-            // 3. Cleanup escalation
-            if (this.gatewayUrl) {
-                scanAndEscalateCleanup([
-                    { filePath: toolsPath, markerIdentity: 'TOOLS' },
-                    {
-                        filePath: join(workspacePath, WORKSPACE_FILES.soul),
-                        markerIdentity: 'SOUL',
-                    },
-                    {
-                        filePath: join(workspacePath, WORKSPACE_FILES.agents),
-                        markerIdentity: 'AGENTS',
-                    },
-                ], this.gatewayUrl, this.pendingCleanups);
+            const raw = readFileSync(cachePath, 'utf-8');
+            const entry = JSON.parse(raw);
+            const age = Date.now() - new Date(entry.checkedAt).getTime();
+            if (age < ttlSeconds * 1000) {
+                return entry.version;
             }
-            // 4. HEARTBEAT orchestration
-            await runHeartbeatCycle({
-                workspacePath,
-                coreConfigDir: getCoreConfigDir(),
-                configRoot: getConfigRoot$1(),
-            });
         }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            console.warn(`jeeves-core: ComponentWriter cycle failed for ${this.component.name}: ${message}`);
+        catch {
+            // Cache corrupt — proceed with fresh check
+        }
+    }
+    // Query npm registry
+    try {
+        const result = execSync(`npm view ${packageName} version`, {
+            encoding: 'utf-8',
+            timeout: 15_000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        if (!result)
+            return undefined;
+        // Write cache
+        if (!existsSync(cacheDir)) {
+            mkdirSync(cacheDir, { recursive: true });
         }
+        const entry = {
+            version: result,
+            checkedAt: new Date().toISOString(),
+        };
+        writeFileSync(cachePath, JSON.stringify(entry, null, 2), 'utf-8');
+        return result;
+    }
+    catch {
+        return undefined;
     }
 }
 
 /**
- * Creates a synchronous content accessor backed by an async data source.
+ * HEARTBEAT health orchestration.
  *
  * @remarks
- * Solves the sync/async gap in `JeevesComponentDescriptor.generateToolsContent()`:
- * the interface is synchronous, but most components fetch live data from
- * their HTTP service. This utility returns a sync `() => string` that
- * serves the last successfully fetched value while kicking off a background
- * refresh on each call.
- *
- * First call returns `placeholder`. Subsequent calls return the last
- * successfully fetched content. If a refresh fails, the previous good
- * value is retained.
- *
- * @example
- * ```typescript
- * const getContent = createAsyncContentCache({
- *   fetch: async () => {
- *     const res = await fetch('http://127.0.0.1:1936/status');
- *     return formatWatcherStatus(await res.json());
- *   },
- *   placeholder: '> Initializing watcher status...',
- * });
+ * Determines the state of each platform component and generates
+ * HEARTBEAT entries with actionable alert text. Applies the dependency
+ * graph for alert suppression and auto-decline.
+ */
+/** Derive the full service name from a component name. */
+function toServiceName(name) {
+    return `jeeves-${name}`;
+}
+/** Known dependency declarations for platform components. */
+const COMPONENT_DEPS = {
+    meta: { hard: ['watcher'], soft: [] },
+    server: { hard: [], soft: ['watcher', 'runner', 'meta'] },
+    runner: { hard: [], soft: [] },
+    watcher: { hard: [], soft: [] },
+};
+/** "Not installed" alert text for each platform component. Shared with seedContent. */
+const NOT_INSTALLED_ALERTS = {
+    runner: 'Not installed. The runner is the job execution engine — it runs scheduled scripts for data fetching, transformation, and maintenance. Ask the user for consent to install. On approval, execute: `npx @karmaniverous/jeeves-runner-openclaw install`.',
+    watcher: 'Not installed. The watcher indexes documents into a vector store for semantic search. Ask the user for consent to install. On approval, execute: `npx @karmaniverous/jeeves-watcher-openclaw install`.',
+    server: 'Not installed. The server provides a web UI for document browsing, rendering, sharing, and search. Ask the user for consent to install. On approval, execute: `npx @karmaniverous/jeeves-server-openclaw install`.',
+    meta: 'Not installed. Meta is the knowledge synthesis engine. Requires jeeves-watcher. Ask the user for consent to install. On approval, install watcher first if needed, then execute: `npx @karmaniverous/jeeves-meta-openclaw install`.',
+};
+/** Alert text generators by state. */
+const ALERT_TEXT = {
+    runner: {
+        not_installed: NOT_INSTALLED_ALERTS['runner'],
+        config_missing: (configRoot) => `Plugin installed but no configuration file found at \`${configRoot}/jeeves-runner/config.json\`. The plugin installer should have created a default config. Ask the user for consent to re-run the installer: \`npx @karmaniverous/jeeves-runner-openclaw install\`.`,
+        service_not_installed: 'Plugin installed and configured but the system service is not installed. Ask the user for consent. On approval, execute: `jeeves-runner service install`. Verify the service is installed.',
+        service_stopped: 'Service installed but not running. Ask the user for consent. On approval, execute: `jeeves-runner service start`. Verify via `GET http://127.0.0.1:1937/status`.',
+    },
+    watcher: {
+        not_installed: NOT_INSTALLED_ALERTS['watcher'],
+        deps_missing: 'Plugin installed but Qdrant is not responding on `http://127.0.0.1:6333`. Qdrant is the vector database required for semantic search. Ask the user for consent to set up Qdrant. Guide them through installation for their platform — Docker is simplest: `docker run -p 6333:6333 qdrant/qdrant`. Verify via `GET http://127.0.0.1:6333/collections`.',
+        config_missing: (configRoot) => `Plugin installed, Qdrant available, but config file missing or invalid at \`${configRoot}/jeeves-watcher/config.json\`. The plugin installer should have created a default config. If missing, re-run: \`npx @karmaniverous/jeeves-watcher-openclaw install\`.`,
+        service_not_installed: 'Plugin installed and configured but the system service is not installed. Ask the user for consent. On approval, execute: `jeeves-watcher service install`. Verify the service is installed.',
+        service_stopped: 'Service installed but not running. Ask the user for consent. On approval, execute: `jeeves-watcher service start`. Verify via `GET http://127.0.0.1:1936/status`.',
+    },
+    server: {
+        not_installed: NOT_INSTALLED_ALERTS['server'],
+        config_missing: (configRoot) => `Plugin installed but config file missing or invalid at \`${configRoot}/jeeves-server/config.json\`. The plugin installer should have created a default config. If missing, re-run: \`npx @karmaniverous/jeeves-server-openclaw install\`.`,
+        service_not_installed: 'Plugin installed and configured but the system service is not installed. Ask the user for consent. On approval, execute: `jeeves-server service install`. Verify the service is installed.',
+        service_stopped: 'Service installed but not running. Ask the user for consent. On approval, execute: `jeeves-server service start`. Verify via `GET http://127.0.0.1:1934/status`.',
+    },
+    meta: {
+        not_installed: NOT_INSTALLED_ALERTS['meta'],
+        deps_missing: 'Plugin installed but required dependency jeeves-watcher is not available. The watcher must be installed and running before meta can function. Do not attempt to set up meta until jeeves-watcher is healthy.',
+        config_missing: (configRoot) => `Plugin installed, watcher available, but config file missing or invalid at \`${configRoot}/jeeves-meta/config.json\`. The plugin installer should have created a default config. If missing, re-run: \`npx @karmaniverous/jeeves-meta-openclaw install\`.`,
+        service_not_installed: 'Plugin installed and configured but the system service is not installed. Ask the user for consent. On approval, execute: `jeeves-meta service install`. Verify the service is installed.',
+        service_stopped: 'Service installed but not running. Ask the user for consent. On approval, execute: `jeeves-meta service start`. Verify via `GET http://127.0.0.1:1938/status`.',
+    },
+};
+/** Default Qdrant URL for watcher dependency check. */
+const QDRANT_URL = 'http://127.0.0.1:6333';
+/** Health probe timeout in milliseconds. */
+const PROBE_TIMEOUT_MS = 3000;
+/**
+ * Check if Qdrant is reachable (watcher dependency).
  *
- * const writer = createComponentWriter({
- *   // ...
- *   generateToolsContent: getContent,
- * });
- * ```
+ * @returns True if Qdrant responds.
  */
+async function isQdrantAvailable() {
+    try {
+        await fetchWithTimeout(`${QDRANT_URL}/collections`, PROBE_TIMEOUT_MS);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
- * Creates a synchronous content accessor backed by an async data source.
+ * Determine the state of a single component.
  *
- * @param options - Cache configuration.
- * @returns A sync `() => string` suitable for `generateToolsContent`.
+ * @param name - Component name.
+ * @param registry - Current component-versions.json contents.
+ * @param configRoot - Config root path.
+ * @param healthySet - Set of component names known to be healthy (for dep checks).
+ * @returns The component's state.
  */
-function createAsyncContentCache(options) {
-    const { fetch: fetchContent, placeholder = '> Initializing...', onError = (err) => {
-        console.warn('[jeeves] async content cache refresh failed:', err);
-    }, } = options;
-    let cached = placeholder;
-    let refreshing = false;
-    return () => {
-        if (!refreshing) {
-            refreshing = true;
-            fetchContent()
-                .then((content) => {
-                cached = content;
-            })
-                .catch(onError)
-                .finally(() => {
-                refreshing = false;
-            });
+async function determineComponentState(name, registry, configRoot, healthySet) {
+    // Not in registry = not installed
+    if (!(name in registry))
+        return 'not_installed';
+    // Check hard dependencies
+    const deps = COMPONENT_DEPS[name];
+    for (const hardDep of deps.hard) {
+        if (!healthySet.has(hardDep))
+            return 'deps_missing';
+    }
+    // Watcher-specific: check Qdrant
+    if (name === 'watcher' && !(await isQdrantAvailable())) {
+        return 'deps_missing';
+    }
+    // Check config file
+    const configPath = join(configRoot, `jeeves-${name}`, CONFIG_FILE);
+    if (!existsSync(configPath))
+        return 'config_missing';
+    // Fast path: probe HTTP health endpoint
+    try {
+        const url = getServiceUrl$1(name);
+        await fetchWithTimeout(`${url}/status`, PROBE_TIMEOUT_MS);
+        // Healthy — check for available updates
+        const entry = registry[name];
+        if (entry.pluginPackage && entry.pluginVersion) {
+            const componentConfigDir = join(configRoot, `jeeves-${name}`);
+            const latestVersion = checkRegistryVersion(entry.pluginPackage, componentConfigDir);
+            if (latestVersion && semverExports.gt(latestVersion, entry.pluginVersion)) {
+                return 'update_available';
+            }
         }
-        return cached;
-    };
+        return 'healthy';
+    }
+    catch {
+        // Service not responding — classify sub-state
+        const serviceState = getServiceState(toServiceName(name));
+        if (serviceState === 'not_installed')
+            return 'service_not_installed';
+        if (serviceState === 'stopped')
+            return 'service_stopped';
+        // serviceState === 'running' but HTTP failed — still treat as stopped
+        return 'service_stopped';
+    }
 }
-
 /**
- * Factory function for creating a ComponentWriter from a descriptor.
+ * Generate the alert text for a component in a given state.
  *
- * @remarks
- * Validates the descriptor via Zod schema and creates a ComponentWriter.
- * Accepts `JeevesComponentDescriptor` (v0.5.0) only. The v0.4.0
- * `JeevesComponent` interface is no longer accepted.
+ * @param name - Component name.
+ * @param state - The component's state.
+ * @param configRoot - Config root path.
+ * @returns Alert text (list items), or empty string if healthy.
  */
+function generateAlertText(name, state, configRoot, registry) {
+    if (state === 'healthy')
+        return '';
+    // Update available — dynamic text with version info
+    if (state === 'update_available') {
+        const entry = registry[name];
+        const currentVersion = entry.pluginVersion ?? 'unknown';
+        const componentConfigDir = join(configRoot, `jeeves-${name}`);
+        const latestVersion = entry.pluginPackage
+            ? (checkRegistryVersion(entry.pluginPackage, componentConfigDir) ??
+                'unknown')
+            : 'unknown';
+        const installCmd = entry.pluginPackage
+            ? `\`npx ${entry.pluginPackage} install\``
+            : `\`npx @karmaniverous/jeeves-${name}-openclaw install\``;
+        return `- Update available: v${currentVersion} → v${latestVersion}. Ask the user for consent to update. On approval, execute: ${installCmd}.`;
+    }
+    const componentAlerts = ALERT_TEXT[name];
+    const alertOrFn = componentAlerts[state];
+    if (!alertOrFn)
+        return '';
+    const text = typeof alertOrFn === 'function' ? alertOrFn(configRoot) : alertOrFn;
+    return `- ${text}`;
+}
 /**
- * Create a ComponentWriter for a validated component descriptor.
- *
- * @remarks
- * The descriptor is validated via the Zod schema at runtime.
- * This replaces the v0.4.0 `createComponentWriter(JeevesComponent)`.
+ * Orchestrate HEARTBEAT entries for all platform components.
  *
- * @param descriptor - The component descriptor to validate and wrap.
- * @param options - Optional writer configuration (e.g., gatewayUrl for cleanup escalation).
- * @returns A new `ComponentWriter` instance.
- * @throws ZodError if the descriptor is invalid.
+ * @param options - Orchestration configuration.
+ * @returns Array of HeartbeatEntry for writeHeartbeatSection.
  */
-function createComponentWriter(descriptor, options) {
-    // Validate via Zod — throws ZodError with detailed messages on failure
-    jeevesComponentDescriptorSchema.parse(descriptor);
-    return new ComponentWriter(descriptor, options);
+async function orchestrateHeartbeat(options) {
+    const { coreConfigDir, configRoot, declinedNames } = options;
+    const registry = readComponentVersions(coreConfigDir);
+    // First pass: determine which components are healthy (for dep resolution)
+    const healthySet = new Set();
+    for (const name of PLATFORM_COMPONENTS) {
+        if (declinedNames.has(toServiceName(name)))
+            continue;
+        if (!(name in registry))
+            continue;
+        try {
+            const url = getServiceUrl$1(name);
+            await fetchWithTimeout(`${url}/status`, PROBE_TIMEOUT_MS);
+            healthySet.add(name);
+        }
+        catch {
+            // Not healthy — will be classified in second pass
+        }
+    }
+    // Second pass: generate entries
+    const entries = [];
+    for (const name of PLATFORM_COMPONENTS) {
+        const fullName = toServiceName(name);
+        // Declined
+        if (declinedNames.has(fullName)) {
+            // Auto-decline dependents of declined hard deps
+            entries.push({ name: fullName, declined: true, content: '' });
+            continue;
+        }
+        const state = await determineComponentState(name, registry, configRoot, healthySet);
+        // Auto-decline if hard dep is declined
+        const deps = COMPONENT_DEPS[name];
+        const hardDepDeclined = deps.hard.some((d) => declinedNames.has(toServiceName(d)));
+        if (hardDepDeclined) {
+            entries.push({ name: fullName, declined: true, content: '' });
+            continue;
+        }
+        const alertText = generateAlertText(name, state, configRoot, registry);
+        entries.push({ name: fullName, declined: false, content: alertText });
+    }
+    // Add soft-dep informational alerts for any healthy component with soft deps
+    for (const entry of entries) {
+        if (entry.declined || entry.content)
+            continue;
+        // Entry is healthy (no alert, not declined) — check for soft deps
+        const shortName = entry.name.replace(/^jeeves-/, '');
+        const deps = COMPONENT_DEPS[shortName];
+        if (!deps.soft.length)
+            continue;
+        const softAlerts = [];
+        for (const dep of deps.soft) {
+            const depFullName = toServiceName(dep);
+            if (declinedNames.has(depFullName))
+                continue;
+            if (!healthySet.has(dep)) {
+                softAlerts.push(`- ${entry.name} is running. Some features are unavailable because ${depFullName} is not installed/running.`);
+            }
+        }
+        if (softAlerts.length > 0) {
+            entry.content = softAlerts.join('\n');
+        }
+    }
+    return entries;
 }
 
 /**
- * Tool result formatters for the OpenClaw plugin SDK.
+ * HEARTBEAT orchestration extracted from ComponentWriter.cycle().
  *
  * @remarks
- * Provides standardised helpers for building `ToolResult` objects:
- * success, error, and connection-error variants.
- */
-/**
- * Format a successful tool result.
- *
- * @param data - Arbitrary data to return as JSON.
- * @returns A `ToolResult` with JSON-stringified content.
- */
-function ok(data) {
-    return {
-        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
-    };
-}
-/**
- * Format an error tool result.
- *
- * @param error - Error instance, string, or other value.
- * @returns A `ToolResult` with `isError: true`.
+ * Reads existing HEARTBEAT.md, resolves declined components, runs the
+ * heartbeat state machine, and writes the result. Best-effort: failures
+ * are logged but do not propagate.
  */
-function fail(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return {
-        content: [{ type: 'text', text: 'Error: ' + message }],
-        isError: true,
-    };
-}
 /**
- * Format a connection error with actionable guidance.
- *
- * @remarks
- * Detects `ECONNREFUSED`, `ENOTFOUND`, and `ETIMEDOUT` from
- * `error.cause.code` and returns a user-friendly message referencing
- * the plugin's `config.apiUrl` setting. Falls back to `fail()` for
- * non-connection errors.
+ * Read a file's content, returning empty string if the file does not exist.
  *
- * @param error - Error instance (typically from `fetch`).
- * @param baseUrl - The URL that was being contacted.
- * @param pluginId - The plugin identifier for config guidance.
- * @returns A `ToolResult` with `isError: true`.
+ * @param filePath - Absolute file path.
+ * @returns File content or empty string.
  */
-function connectionFail(error, baseUrl, pluginId) {
-    const cause = error instanceof Error ? error.cause : undefined;
-    const code = cause && typeof cause === 'object' && 'code' in cause
-        ? String(cause.code)
-        : '';
-    const isConnectionError = code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'ETIMEDOUT';
-    if (isConnectionError) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: [
-                        `Service not reachable at ${baseUrl}.`,
-                        'Either start the service, or if it runs on a different port,',
-                        `set plugins.entries.${pluginId}.config.apiUrl in openclaw.json.`,
-                    ].join('\n'),
-                },
-            ],
-            isError: true,
-        };
+function readFileOrEmpty(filePath) {
+    try {
+        return readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        if (err instanceof Error &&
+            'code' in err &&
+            err.code === 'ENOENT') {
+            return '';
+        }
+        throw err;
     }
-    return fail(error);
 }
-
-/**
- * Factory for the standard plugin tool set.
- *
- * @remarks
- * Produces four standard tools from a component descriptor:
- * - `{name}_status` - Probe service health + version + uptime
- * - `{name}_config` - Query running config with optional JSONPath
- * - `{name}_config_apply` - Push config patch to running service
- * - `{name}_service` - Service lifecycle management
- *
- * Components add domain-specific tools separately.
- */
-/** Timeout for HTTP probes in milliseconds. */
-const PROBE_TIMEOUT_MS = 5000;
 /**
- * Create the standard plugin tool set from a component descriptor.
+ * Run a single HEARTBEAT orchestration cycle.
  *
- * @param descriptor - The component descriptor.
- * @returns Array of tool descriptors to register.
+ * @param options - Heartbeat cycle configuration.
  */
-function createPluginToolset(descriptor) {
-    const { name, defaultPort } = descriptor;
-    const baseUrl = `http://127.0.0.1:${String(defaultPort)}`;
-    const svcManager = createServiceManager(descriptor);
-    const statusTool = {
-        name: `${name}_status`,
-        description: `Get ${name} service health, version, and uptime.`,
-        parameters: {
-            type: 'object',
-            properties: {},
-        },
-        execute: async () => {
-            try {
-                const res = await fetchWithTimeout(`${baseUrl}/status`, PROBE_TIMEOUT_MS);
-                if (!res.ok) {
-                    return fail(`HTTP ${String(res.status)}: ${await res.text()}`);
-                }
-                const data = await res.json();
-                return ok(data);
-            }
-            catch (err) {
-                return connectionFail(err, baseUrl, `jeeves-${name}-openclaw`);
-            }
-        },
-    };
-    const configTool = {
-        name: `${name}_config`,
-        description: `Query ${name} running configuration. Optional JSONPath filter.`,
-        parameters: {
-            type: 'object',
-            properties: {
-                path: {
-                    type: 'string',
-                    description: 'JSONPath expression (optional)',
-                },
-            },
-        },
-        execute: async (_id, params) => {
-            const path = params.path;
-            const qs = path ? `?path=${encodeURIComponent(path)}` : '';
-            try {
-                const result = await fetchJson(`${baseUrl}/config${qs}`);
-                return ok(result);
-            }
-            catch (err) {
-                return connectionFail(err, baseUrl, `jeeves-${name}-openclaw`);
-            }
-        },
-    };
-    const configApplyTool = {
-        name: `${name}_config_apply`,
-        description: `Apply a config patch to the running ${name} service.`,
-        parameters: {
-            type: 'object',
-            properties: {
-                config: {
-                    type: 'object',
-                    description: 'Config patch to apply',
-                },
-            },
-            required: ['config'],
-        },
-        execute: async (_id, params) => {
-            const config = params.config;
-            if (!config) {
-                return fail('Missing required parameter: config');
-            }
-            try {
-                const result = await postJson(`${baseUrl}/config/apply`, {
-                    patch: config,
-                });
-                return ok(result);
-            }
-            catch (err) {
-                return connectionFail(err, baseUrl, `jeeves-${name}-openclaw`);
-            }
-        },
-    };
-    const serviceTool = {
-        name: `${name}_service`,
-        description: `Manage the ${name} system service. Actions: install, uninstall, start, stop, restart, status.`,
-        parameters: {
-            type: 'object',
-            properties: {
-                action: {
-                    type: 'string',
-                    enum: ['install', 'uninstall', 'start', 'stop', 'restart', 'status'],
-                    description: 'Service action to perform',
-                },
-            },
-            required: ['action'],
-        },
-        execute: (_id, params) => {
-            const action = params.action;
-            const validActions = [
-                'install',
-                'uninstall',
-                'start',
-                'stop',
-                'restart',
-                'status',
-            ];
-            if (!validActions.includes(action)) {
-                return Promise.resolve(fail(`Invalid action: ${action}`));
-            }
-            try {
-                if (action === 'status') {
-                    const state = svcManager.status();
-                    return Promise.resolve(ok({ service: name, state }));
-                }
-                // Call the appropriate method
-                const methodMap = {
-                    install: () => {
-                        svcManager.install();
-                    },
-                    uninstall: () => {
-                        svcManager.uninstall();
-                    },
-                    start: () => {
-                        svcManager.start();
-                    },
-                    stop: () => {
-                        svcManager.stop();
-                    },
-                    restart: () => {
-                        svcManager.restart();
-                    },
-                };
-                methodMap[action]();
-                return Promise.resolve(ok({ service: name, action, success: true }));
+async function runHeartbeatCycle(options) {
+    const { workspacePath, coreConfigDir, configRoot } = options;
+    const heartbeatPath = join(workspacePath, WORKSPACE_FILES.heartbeat);
+    try {
+        const existingContent = readFileOrEmpty(heartbeatPath);
+        const parsed = parseHeartbeat(existingContent);
+        const declinedNames = new Set(parsed.entries.filter((e) => e.declined).map((e) => e.name));
+        const entries = await orchestrateHeartbeat({
+            coreConfigDir,
+            configRoot,
+            declinedNames,
+        });
+        // Memory hygiene check (Decision 49)
+        if (!declinedNames.has(MEMORY_HEARTBEAT_NAME)) {
+            const wsConfig = loadWorkspaceConfig(workspacePath);
+            const memoryEntry = checkMemoryHealth({
+                workspacePath,
+                budget: wsConfig?.memory?.budget ?? WORKSPACE_CONFIG_DEFAULTS.memory.budget,
+                warningThreshold: wsConfig?.memory?.warningThreshold ??
+                    WORKSPACE_CONFIG_DEFAULTS.memory.warningThreshold,
+                staleDays: wsConfig?.memory?.staleDays ??
+                    WORKSPACE_CONFIG_DEFAULTS.memory.staleDays,
+            });
+            if (memoryEntry)
+                entries.push(memoryEntry);
+        }
+        else {
+            entries.push({
+                name: MEMORY_HEARTBEAT_NAME,
+                declined: true,
+                content: '',
+            });
+        }
+        // Workspace file size health check (Decision 70)
+        const wsFileResults = checkWorkspaceFileHealth({ workspacePath });
+        const wsFileAlerts = workspaceFileHealthEntries(wsFileResults);
+        for (const alert of wsFileAlerts) {
+            if (declinedNames.has(alert.name)) {
+                entries.push({ name: alert.name, declined: true, content: '' });
             }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                return Promise.resolve(fail(`Service ${action} failed: ${msg}`));
+            else {
+                entries.push(alert);
             }
-        },
-    };
-    return [statusTool, configTool, configApplyTool, serviceTool];
+        }
+        await writeHeartbeatSection(heartbeatPath, entries);
+    }
+    catch (err) {
+        console.warn(`jeeves-core: HEARTBEAT orchestration failed: ${getErrorMessage(err)}`);
+    }
 }
 
 /**
- * Plugin resolution helpers for the OpenClaw plugin SDK.
+ * Timer-based orchestrator for managed content writing.
  *
  * @remarks
- * Provides workspace path resolution and plugin setting resolution
- * with a standard three-step fallback chain:
- * plugin config → environment variable → default value.
+ * `ComponentWriter` manages a component's TOOLS.md section writes
+ * and platform content maintenance (SOUL.md, AGENTS.md, Platform section)
+ * on a configurable prime-interval timer cycle.
  */
 /**
- * Resolve the workspace root from the OpenClaw plugin API.
+ * Orchestrates managed content writing for a single Jeeves component.
  *
  * @remarks
- * Tries three sources in order:
- * 1. `api.config.agents.defaults.workspace` — explicit config
- * 2. `api.resolvePath('.')` — gateway-provided path resolver
- * 3. `process.cwd()` — last resort
- *
- * @param api - The plugin API object provided by the gateway.
- * @returns Absolute path to the workspace root.
+ * Created via {@link createComponentWriter}. Manages a timer that fires
+ * at the component's prime-interval, calling `generateToolsContent()`
+ * and `refreshPlatformContent()` on each cycle.
  */
-function resolveWorkspacePath(api) {
-    const configured = api.config?.agents?.defaults?.workspace;
-    if (typeof configured === 'string' && configured.trim()) {
-        return configured;
+class ComponentWriter {
+    timer;
+    jitterTimeout;
+    component;
+    configDir;
+    gatewayUrl;
+    pendingCleanups = new Set();
+    /** @internal */
+    constructor(component, options) {
+        this.component = component;
+        this.configDir = getComponentConfigDir(component.name);
+        this.gatewayUrl = options?.gatewayUrl;
     }
-    if (typeof api.resolvePath === 'function') {
-        return api.resolvePath('.');
+    /** The component's config directory path. */
+    get componentConfigDir() {
+        return this.configDir;
+    }
+    /** Whether the writer timer is currently running or pending its first cycle. */
+    get isRunning() {
+        return this.jitterTimeout !== undefined || this.timer !== undefined;
+    }
+    /**
+     * Start the writer timer.
+     *
+     * @remarks
+     * Delays the first cycle by a random jitter (0 to one full interval) to
+     * spread initial writes across all component plugins and reduce EPERM
+     * contention on startup.
+     */
+    start() {
+        if (this.isRunning)
+            return;
+        // Random jitter up to one full interval to spread initial writes
+        const intervalMs = this.component.refreshIntervalSeconds * 1000;
+        const jitterMs = Math.floor(Math.random() * intervalMs);
+        this.jitterTimeout = setTimeout(() => {
+            this.jitterTimeout = undefined;
+            void this.cycle();
+            this.timer = setInterval(() => void this.cycle(), intervalMs);
+        }, jitterMs);
+    }
+    /** Stop the writer timer. */
+    stop() {
+        if (this.jitterTimeout) {
+            clearTimeout(this.jitterTimeout);
+            this.jitterTimeout = undefined;
+        }
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+    /**
+     * Execute a single write cycle.
+     *
+     * @remarks
+     * 1. Write the component's TOOLS.md section.
+     * 2. Refresh shared platform content (SOUL.md, AGENTS.md, Platform section).
+     * 3. Scan for cleanup flags and escalate if a gateway URL is configured.
+     * 4. Run HEARTBEAT health orchestration.
+     */
+    async cycle() {
+        try {
+            const workspacePath = getWorkspacePath();
+            const toolsPath = join(workspacePath, WORKSPACE_FILES.tools);
+            // 1. Write the component's TOOLS.md section
+            const toolsContent = this.component.generateToolsContent();
+            await updateManagedSection(toolsPath, toolsContent, {
+                mode: 'section',
+                sectionId: this.component.sectionId,
+                markers: TOOLS_MARKERS,
+                coreVersion: CORE_VERSION,
+            });
+            // 2. Platform content maintenance
+            await refreshPlatformContent({
+                coreVersion: CORE_VERSION,
+                componentName: this.component.name,
+                componentVersion: this.component.version,
+                servicePackage: this.component.servicePackage,
+                pluginPackage: this.component.pluginPackage,
+            });
+            // 3. Cleanup escalation
+            if (this.gatewayUrl) {
+                scanAndEscalateCleanup([
+                    { filePath: toolsPath, markerIdentity: 'TOOLS' },
+                    {
+                        filePath: join(workspacePath, WORKSPACE_FILES.soul),
+                        markerIdentity: 'SOUL',
+                    },
+                    {
+                        filePath: join(workspacePath, WORKSPACE_FILES.agents),
+                        markerIdentity: 'AGENTS',
+                    },
+                ], this.gatewayUrl, this.pendingCleanups);
+            }
+            // 4. HEARTBEAT orchestration
+            await runHeartbeatCycle({
+                workspacePath,
+                coreConfigDir: getCoreConfigDir(),
+                configRoot: getConfigRoot$1(),
+            });
+        }
+        catch (err) {
+            console.warn(`jeeves-core: ComponentWriter cycle failed for ${this.component.name}: ${getErrorMessage(err)}`);
+        }
     }
-    return process.cwd();
 }
+
 /**
- * Resolve a plugin setting via the standard three-step fallback chain:
- * plugin config → environment variable → fallback value.
+ * Creates a synchronous content accessor backed by an async data source.
  *
- * @param api - Plugin API object.
- * @param pluginId - Plugin identifier (e.g., 'jeeves-watcher-openclaw').
- * @param key - Config key within the plugin's config object.
- * @param envVar - Environment variable name.
- * @param fallback - Default value if neither source provides one.
- * @returns The resolved setting value.
+ * @remarks
+ * Solves the sync/async gap in `JeevesComponentDescriptor.generateToolsContent()`:
+ * the interface is synchronous, but most components fetch live data from
+ * their HTTP service. This utility returns a sync `() => string` that
+ * serves the last successfully fetched value while kicking off a background
+ * refresh on each call.
+ *
+ * First call returns `placeholder`. Subsequent calls return the last
+ * successfully fetched content. If a refresh fails, the previous good
+ * value is retained.
+ *
+ * @example
+ * ```typescript
+ * const getContent = createAsyncContentCache({
+ *   fetch: async () => {
+ *     const res = await fetch('http://127.0.0.1:1936/status');
+ *     return formatWatcherStatus(await res.json());
+ *   },
+ *   placeholder: '> Initializing watcher status...',
+ * });
+ *
+ * const writer = createComponentWriter({
+ *   // ...
+ *   generateToolsContent: getContent,
+ * });
+ * ```
  */
-function resolvePluginSetting(api, pluginId, key, envVar, fallback) {
-    const fromPlugin = api.config?.plugins?.entries?.[pluginId]?.config?.[key];
-    if (typeof fromPlugin === 'string')
-        return fromPlugin;
-    const fromEnv = process.env[envVar];
-    if (fromEnv)
-        return fromEnv;
-    return fallback;
+/**
+ * Creates a synchronous content accessor backed by an async data source.
+ *
+ * @param options - Cache configuration.
+ * @returns A sync `() => string` suitable for `generateToolsContent`.
+ */
+function createAsyncContentCache(options) {
+    const { fetch: fetchContent, placeholder = '> Initializing...', onError = (err) => {
+        console.warn('[jeeves] async content cache refresh failed:', err);
+    }, } = options;
+    let cached = placeholder;
+    let refreshing = false;
+    return () => {
+        if (!refreshing) {
+            refreshing = true;
+            fetchContent()
+                .then((content) => {
+                cached = content;
+            })
+                .catch(onError)
+                .finally(() => {
+                refreshing = false;
+            });
+        }
+        return cached;
+    };
 }
+
 /**
- * Resolve an optional plugin setting via the two-step fallback chain:
- * plugin config → environment variable. Returns `undefined` if neither
- * source provides a value.
+ * Factory function for creating a ComponentWriter from a descriptor.
  *
- * @param api - Plugin API object.
- * @param pluginId - Plugin identifier (e.g., 'jeeves-watcher-openclaw').
- * @param key - Config key within the plugin's config object.
- * @param envVar - Environment variable name.
- * @returns The resolved setting value, or `undefined`.
+ * @remarks
+ * Validates the descriptor via Zod schema and creates a ComponentWriter.
+ * Accepts `JeevesComponentDescriptor` (v0.5.0) only. The v0.4.0
+ * `JeevesComponent` interface is no longer accepted.
  */
-function resolveOptionalPluginSetting(api, pluginId, key, envVar) {
-    const fromPlugin = api.config?.plugins?.entries?.[pluginId]?.config?.[key];
-    if (typeof fromPlugin === 'string')
-        return fromPlugin;
-    const fromEnv = process.env[envVar];
-    if (fromEnv)
-        return fromEnv;
-    return undefined;
+/**
+ * Create a ComponentWriter for a validated component descriptor.
+ *
+ * @remarks
+ * The descriptor is validated via the Zod schema at runtime.
+ * This replaces the v0.4.0 `createComponentWriter(JeevesComponent)`.
+ *
+ * @param descriptor - The component descriptor to validate and wrap.
+ * @param options - Optional writer configuration (e.g., gatewayUrl for cleanup escalation).
+ * @returns A new `ComponentWriter` instance.
+ * @throws ZodError if the descriptor is invalid.
+ */
+function createComponentWriter(descriptor, options) {
+    // Validate via Zod — throws ZodError with detailed messages on failure
+    jeevesComponentDescriptorSchema.parse(descriptor);
+    return new ComponentWriter(descriptor, options);
 }
 
 /**