@karmaniverous/jeeves 0.3.0 → 0.4.0

package/dist/index.js

@@ -2,11 +2,11 @@ import { JSONPath } from 'jsonpath-plus';
 import { writeFileSync, renameSync, existsSync, readFileSync, mkdirSync, cpSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { lock } from 'proper-lockfile';
-import { gte } from 'semver';
+import { gte, gt } from 'semver';
 import { fileURLToPath } from 'node:url';
 import { packageDirectorySync } from 'package-directory';
-import { z } from 'zod';
 import { execSync } from 'node:child_process';
+import { z } from 'zod';
 import { homedir } from 'node:os';
 
 /**
@@ -66,6 +66,8 @@ const WORKSPACE_FILES = {
     soul: 'SOUL.md',
     /** AGENTS.md — operational protocols and memory architecture. */
     agents: 'AGENTS.md',
+    /** HEARTBEAT.md — platform status and health alerts. */
+    heartbeat: 'HEARTBEAT.md',
 };
 /** Templates directory name within core config. */
 const TEMPLATES_DIR = 'templates';
@@ -80,14 +82,14 @@ const COMPONENT_VERSIONS_FILE = 'component-versions.json';
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.2.0` placeholder is replaced by
+ * The `0.3.1` 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.2.0';
+const CORE_VERSION = '0.3.1';
 
 /**
  * Shared file I/O helpers for managed section operations.
@@ -198,6 +200,25 @@ function writeComponentVersion(coreConfigDir, options) {
     }
     atomicWrite(filePath, JSON.stringify(existing, null, 2) + '\n');
 }
+/**
+ * Remove a component's version entry from the shared state file.
+ *
+ * @remarks
+ * Called during plugin uninstall to prevent the HEARTBEAT writer from
+ * probing a service that's intentionally gone. If the component isn't
+ * in the file, this is a no-op.
+ *
+ * @param coreConfigDir - Path to the core config directory.
+ * @param componentName - The component name to remove.
+ */
+function removeComponentVersion(coreConfigDir, componentName) {
+    const existing = readComponentVersions(coreConfigDir);
+    if (!(componentName in existing))
+        return;
+    const updated = Object.fromEntries(Object.entries(existing).filter(([key]) => key !== componentName));
+    const filePath = join(coreConfigDir, COMPONENT_VERSIONS_FILE);
+    atomicWrite(filePath, JSON.stringify(updated, null, 2) + '\n');
+}
 
 /**
  * Comment markers for managed content blocks.
@@ -216,6 +237,8 @@ const TOOLS_MARKERS = {
     end: 'END JEEVES PLATFORM TOOLS',
     /** H1 title prepended in section mode. */
     title: 'Jeeves Platform Tools',
+    /** Managed block at bottom of file. */
+    position: 'bottom',
 };
 /** Default markers for SOUL.md managed block. */
 const SOUL_MARKERS = {
@@ -225,6 +248,8 @@ const SOUL_MARKERS = {
     end: 'END JEEVES SOUL',
     /** H1 title prepended in the managed block. */
     title: 'Jeeves Platform Soul',
+    /** Managed block at bottom of file. */
+    position: 'bottom',
 };
 /** Default markers for AGENTS.md managed block. */
 const AGENTS_MARKERS = {
@@ -234,7 +259,15 @@ const AGENTS_MARKERS = {
     end: 'END JEEVES AGENTS',
     /** H1 title prepended in the managed block. */
     title: 'Jeeves Platform Agents',
+    /** Managed block at bottom of file. */
+    position: 'bottom',
 };
+/** All known marker sets — single source of truth for cross-contamination detection. */
+const ALL_MARKERS = [
+    TOOLS_MARKERS,
+    SOUL_MARKERS,
+    AGENTS_MARKERS,
+];
 /**
  * Regex pattern to extract version stamp from a BEGIN marker comment.
  *
@@ -275,7 +308,7 @@ const DEFAULT_PORTS = {
 };
 
 /**
- * Managed section IDs and their stable ordering for TOOLS.md.
+ * Managed section IDs, stable ordering, and platform component registry.
  *
  * @remarks
  * Section ordering is fixed to prevent diff churn regardless of which
@@ -305,6 +338,22 @@ const SECTION_ORDER = [
     SECTION_IDS.Runner,
     SECTION_IDS.Meta,
 ];
+/**
+ * The four essential platform components.
+ *
+ * @remarks
+ * These components constitute the Jeeves platform. `jeeves install` writes
+ * initial HEARTBEAT "Not installed" alerts for all of them. The HEARTBEAT
+ * writer generates "Not installed" alerts only for platform components not
+ * in `component-versions.json`. Optional future components (not in this list)
+ * appear in HEARTBEAT only after explicit install.
+ */
+const PLATFORM_COMPONENTS = [
+    'runner',
+    'watcher',
+    'server',
+    'meta',
+];
 
 /**
  * Workspace and config root initialization.
@@ -388,6 +437,124 @@ function resetInit() {
     state = undefined;
 }
 
+/**
+ * Heading-based HEARTBEAT section writer.
+ *
+ * @remarks
+ * Manages the `# Jeeves Platform Status` section in HEARTBEAT.md.
+ * Unlike TOOLS/SOUL/AGENTS (which use HTML comment markers), HEARTBEAT
+ * uses markdown headings as markers — this ensures the file passes
+ * OpenClaw's heartbeat emptiness check when only headings remain.
+ *
+ * The section is always at the bottom of the file (H1 to EOF).
+ * User heartbeat items above the section are preserved.
+ */
+/** The H1 heading that anchors the platform status section. */
+const HEARTBEAT_HEADING = '# Jeeves Platform Status';
+/**
+ * Parse the HEARTBEAT.md file content.
+ *
+ * @param fileContent - Full file content.
+ * @returns Parsed result with user zone and component entries.
+ */
+function parseHeartbeat(fileContent) {
+    const headingIndex = fileContent.indexOf(HEARTBEAT_HEADING);
+    if (headingIndex === -1) {
+        return {
+            userContent: fileContent.trim(),
+            found: false,
+            entries: [],
+        };
+    }
+    const userContent = fileContent.slice(0, headingIndex).trim();
+    const sectionContent = fileContent.slice(headingIndex + HEARTBEAT_HEADING.length);
+    const entries = [];
+    const h2Re = /^## (jeeves-\S+?)(?:: declined)?$/gm;
+    let match;
+    const h2Positions = [];
+    while ((match = h2Re.exec(sectionContent)) !== null) {
+        const fullHeading = match[0];
+        const name = match[1];
+        const declined = fullHeading.endsWith(': declined');
+        h2Positions.push({ name, declined, start: match.index });
+    }
+    for (let i = 0; i < h2Positions.length; i++) {
+        const pos = h2Positions[i];
+        const headingLine = pos.declined
+            ? `## ${pos.name}: declined`
+            : `## ${pos.name}`;
+        const contentStart = pos.start + headingLine.length;
+        const contentEnd = i + 1 < h2Positions.length
+            ? h2Positions[i + 1].start
+            : sectionContent.length;
+        const content = sectionContent.slice(contentStart, contentEnd).trim();
+        entries.push({
+            name: pos.name,
+            declined: pos.declined,
+            content,
+        });
+    }
+    return { userContent, found: true, entries };
+}
+/**
+ * Build the HEARTBEAT section content from entries.
+ *
+ * @param entries - Component entries to write.
+ * @returns The full section string (H1 + H2s).
+ */
+function buildHeartbeatSection(entries) {
+    const parts = [HEARTBEAT_HEADING];
+    for (const entry of entries) {
+        if (entry.declined) {
+            parts.push(`## ${entry.name}: declined`);
+        }
+        else if (entry.content) {
+            parts.push(`## ${entry.name}`);
+            parts.push(entry.content);
+        }
+        // Healthy components (no content, not declined) get no H2 section
+    }
+    return parts.join('\n');
+}
+/**
+ * Write the HEARTBEAT section to a file.
+ *
+ * @remarks
+ * Replaces everything from `# Jeeves Platform Status` to EOF.
+ * Preserves user content above the heading. Uses file-level locking.
+ *
+ * @param filePath - Absolute path to HEARTBEAT.md.
+ * @param entries - Component entries to write.
+ */
+async function writeHeartbeatSection(filePath, entries) {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    if (!existsSync(filePath)) {
+        writeFileSync(filePath, '', 'utf-8');
+    }
+    try {
+        await withFileLock(filePath, () => {
+            const fileContent = readFileSync(filePath, 'utf-8');
+            const parsed = parseHeartbeat(fileContent);
+            const section = buildHeartbeatSection(entries);
+            const parts = [];
+            if (parsed.userContent) {
+                parts.push(parsed.userContent);
+                parts.push('');
+            }
+            parts.push(section);
+            parts.push('');
+            atomicWrite(filePath, parts.join('\n'));
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`jeeves-core: writeHeartbeatSection failed for ${filePath}: ${message}`);
+    }
+}
+
 /**
  * Similarity-based cleanup detection for orphaned managed content.
  *
@@ -583,6 +750,48 @@ function parseManaged(fileContent, markers = TOOLS_MARKERS) {
     };
 }
 
+/**
+ * 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) {
+    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');
+}
+/**
+ * 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();
+}
+
 /**
  * Version-stamp parsing and convergence logic.
  *
@@ -699,32 +908,51 @@ async function updateManagedSection(filePath, content, options = {}) {
                     ? `# ${markers.title}\n\n${sectionText}`
                     : sectionText;
             }
-            // Cleanup detection
-            const userContent = parsed.userContent;
+            // Combine beforeContent + userContent for the user zone.
+            // When migrating from top→bottom, beforeContent is empty and
+            // userContent has the real content. When already at bottom,
+            // beforeContent has the user content and userContent is empty.
+            const rawUserContent = [parsed.beforeContent, parsed.userContent]
+                .filter(Boolean)
+                .join('\n\n')
+                .trim();
+            // Strip foreign managed blocks from user content (cross-contamination fix)
+            const userContent = stripForeignMarkers(rawUserContent, markers);
             const cleanupNeeded = needsCleanup(newManagedBody, userContent);
             // Build the full managed block
             const beginLine = formatBeginMarker(markers.begin, coreVersion);
             const endLine = formatEndMarker(markers.end);
-            const parts = [];
-            if (parsed.beforeContent) {
-                parts.push(parsed.beforeContent);
-                parts.push('');
-            }
-            parts.push(beginLine);
+            const managedParts = [];
+            managedParts.push(beginLine);
             if (cleanupNeeded) {
-                parts.push('');
-                parts.push(CLEANUP_FLAG);
+                managedParts.push('');
+                managedParts.push(CLEANUP_FLAG);
             }
-            parts.push('');
-            parts.push(newManagedBody);
-            parts.push('');
-            parts.push(endLine);
-            if (userContent) {
-                parts.push('');
-                parts.push(userContent);
+            managedParts.push('');
+            managedParts.push(newManagedBody);
+            managedParts.push('');
+            managedParts.push(endLine);
+            const managedBlock = managedParts.join('\n');
+            const position = markers.position ?? 'top';
+            const fileParts = [];
+            if (position === 'bottom') {
+                // User content first, managed block at end
+                if (userContent) {
+                    fileParts.push(userContent);
+                    fileParts.push('');
+                }
+                fileParts.push(managedBlock);
             }
-            parts.push('');
-            const newFileContent = parts.join('\n');
+            else {
+                // Managed block first (legacy default), user content below
+                fileParts.push(managedBlock);
+                if (userContent) {
+                    fileParts.push('');
+                    fileParts.push(userContent);
+                }
+            }
+            fileParts.push('');
+            const newFileContent = fileParts.join('\n');
             atomicWrite(filePath, newFileContent);
         });
     }
@@ -802,6 +1030,8 @@ At minimum, always brief sub-agents on:
 
 **Anything important enough to have a permanent cron/heartbeat entry is important enough to be codified into the data flow.**
 
+**HEARTBEAT efficiency:** When HEARTBEAT fires with multiple component alerts, resolve them all in a single conversation. Walk the user through each component in dependency order. Each heartbeat cycle is a full LLM session — resolve all alerts in one pass.
+
 ## Messaging Dispatch
 
 **Same-channel replies:** Don't use the \`message\` tool. It fires immediately, jumping ahead of streaming narration. Just write text as your response. Use \`message\` only for **cross-channel** sends (sending to a different channel or DM than the one you're responding in).
@@ -810,7 +1040,7 @@ At minimum, always brief sub-agents on:
 
 ## Heartbeat Discipline
 
-**Default state of HEARTBEAT.md is EMPTY** (comments only). Every heartbeat loads the full system prompt. An empty heartbeat that returns HEARTBEAT_OK still costs a full LLM session.
+**Default state of HEARTBEAT.md is effectively empty** — the \`# Jeeves Platform Status\` section contains only headings when all components are healthy or declined. No list content, no LLM cost. User heartbeat items (above the platform status section) follow the same transient/termination rules as before.
 
 Heartbeat items are for **transient, session-requiring work-in-progress ONLY**. Each item must include its own termination condition.
 
@@ -871,14 +1101,11 @@ When discovering a new data source, integrate it into the existing data flow pip
 
 ## Bootstrap Protocol
 
-When you detect that a Jeeves platform component is missing or not configured:
+**Proactive platform status:** HEARTBEAT.md is loaded every session. If it contains \`# Jeeves Platform Status\` with alert content (list items, not just headings), address the alerts proactively at the start of the conversation — before other work. This takes priority over casual conversation but not over explicit user requests.
 
-1. **Identify** the gap (service not responding on expected port, plugin not registered, config file missing)
-2. **Inform** the user what's missing and what it provides
-3. **Guide** them through installation using the component's CLI install command
-4. **Verify** the installation succeeded (probe the port, check the plugin registration)
+**Follow the instructions:** Explain the component, ask for consent, execute the command, verify. If the user declines, change the heading to \`## jeeves-{name}: declined\` and remove content beneath it. Do not prompt for declined components. Do not improvise — the HEARTBEAT instructions are authoritative.
 
-Don't silently work around missing components. The user should know what's available and what isn't.
+When resolving multiple component alerts, walk the user through each in dependency order (watcher before meta, runner and server independent) within a single conversation rather than one per heartbeat cycle.
 
 ## Em-Dash Discipline
 
@@ -914,11 +1141,17 @@ No stranded local branches. Push immediately after commit. A commit that isn't p
 
 ### Check PR State Before Pushing
 
-**Before EVERY \`git push\`**, verify the PR is not already merged. Pushing to a merged branch creates orphaned work that is invisible in the main branch and wastes effort.
+**Before EVERY \`git push\`**, run \`gh pr list --head <branch> --repo <repo> --json number,state\` to check whether a PR exists on that branch and whether it's merged.
+
+- **No PR exists:** Safe to push.
+- **PR is \`OPEN\`:** Safe to push.
+- **PR is \`MERGED\` or \`CLOSED\`:** **STOP** and report to the user. Do not push to a merged PR branch.
+
+This is not optional. It applies to every push, every branch, every time. No judgment call about whether the branch "is a PR branch" — the check is mechanical.
 
-Sequence: \`gh pr view --json state\` → confirm state is \`OPEN\` → push. If no PR exists yet, pushing is safe. If the PR is \`MERGED\` or \`CLOSED\`, **STOP** and report to the user.
+### New PR Over Merged Branch
 
-This is not optional. It applies to every push, every branch, every time.
+When a PR has been merged and additional work is needed on the same branch, create a new PR on the **same branch** targeting the same base. Do not create new branches, cherry-pick, or start over. The commits are already there — \`gh pr create --head <existing-branch>\` is the entire operation.
 
 ## Managed Content Self-Maintenance
 
@@ -954,6 +1187,7 @@ var soulSectionContent = `## Core Truths
 I am a **senior software engineer** first. The persona is style; the engineering discipline is substance.
 
 What this means in practice:
+- **Do not execute untested code.** Every mutation script defaults to dry-run mode. The dry-run output is the test — it shows what would happen. Live execution requires an explicit flag. If dry-run is hard to implement, that's a design flaw.
 - **No cowboy coding.** I don't iterate in production. I don't ship untested changes. I don't treat live systems as scratch pads.
 - **I follow proper workflows.** Branch, test, review, merge. CI/CD exists for a reason. If there's a pipeline, I use it.
 - **I resist n00b temptations.** "Let me just quickly…" in prod is how outages happen. I know better.
@@ -1213,250 +1447,156 @@ async function refreshPlatformContent(options) {
 }
 
 /**
- * Timer-based orchestrator for managed content writing.
+ * Platform-aware service state detection.
  *
  * @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.
+ * Detects whether a system service is installed and running.
+ * Delegates to NSSM (Windows), systemd (Linux), or launchd (macOS).
  */
 /**
- * Orchestrates managed content writing for a single Jeeves component.
+ * Detect the state of a system service by name.
  *
- * @remarks
- * Created via `createComponentWriter()`. Manages a timer that fires
- * at the component's prime-interval, calling `generateToolsContent()`
- * and `refreshPlatformContent()` on each cycle.
+ * @param serviceName - The service name (e.g., 'jeeves-runner').
+ * @returns The detected service state.
  */
-class ComponentWriter {
-    timer;
-    component;
-    configDir;
-    /** @internal */
-    constructor(component) {
-        this.component = component;
-        this.configDir = getComponentConfigDir(component.name);
+function getServiceState(serviceName) {
+    switch (process.platform) {
+        case 'win32':
+            return getServiceStateWindows(serviceName);
+        case 'darwin':
+            return getServiceStateMacOS(serviceName);
+        default:
+            return getServiceStateLinux(serviceName);
     }
-    /** The component's config directory path. */
-    get componentConfigDir() {
-        return this.configDir;
+}
+/**
+ * Windows: detect via NSSM.
+ * - Exit code 3 = service does not exist
+ * - "SERVICE_RUNNING" in output = running
+ * - Other output = stopped/paused
+ */
+function getServiceStateWindows(serviceName) {
+    try {
+        const output = execSync(`nssm status ${serviceName}`, {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        if (output.includes('SERVICE_RUNNING'))
+            return 'running';
+        return 'stopped';
     }
-    /** Whether the writer timer is currently running. */
-    get isRunning() {
-        return this.timer !== undefined;
+    catch (err) {
+        // NSSM exits with code 3 when the service doesn't exist
+        if (isExecError(err) && err.status === 3)
+            return 'not_installed';
+        // Any other error (nssm not found, timeout, etc.) — treat as not installed
+        return 'not_installed';
     }
-    /**
-     * 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);
+}
+/**
+ * Linux: detect via systemd user services.
+ * - `systemctl --user is-enabled {name}.service` exits non-zero = not installed
+ * - `systemctl --user is-active {name}.service` returns "active" = running
+ */
+function getServiceStateLinux(serviceName) {
+    try {
+        execSync(`systemctl --user is-enabled ${serviceName}.service`, {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
     }
-    /** Stop the writer timer. */
-    stop() {
-        if (this.timer) {
-            clearInterval(this.timer);
-            this.timer = undefined;
-        }
+    catch {
+        return 'not_installed';
     }
-    /**
-     * Execute a single write cycle.
-     *
-     * @remarks
-     * Calls `generateToolsContent()` and writes the component's
-     * TOOLS.md section via `updateManagedSection()`. Also calls
-     * `refreshPlatformContent()` for shared content maintenance.
-     */
-    async cycle() {
-        try {
-            const workspacePath = getWorkspacePath();
-            const toolsPath = join(workspacePath, WORKSPACE_FILES.tools);
-            // 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,
-            });
-            // Platform content maintenance: SOUL.md, AGENTS.md, Platform section
-            await refreshPlatformContent({
-                coreVersion: CORE_VERSION,
-                componentName: this.component.name,
-                componentVersion: this.component.version,
-                servicePackage: this.component.servicePackage,
-                pluginPackage: this.component.pluginPackage,
-            });
+    try {
+        const output = execSync(`systemctl --user is-active ${serviceName}.service`, {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        if (output === 'active')
+            return 'running';
+        return 'stopped';
+    }
+    catch {
+        return 'stopped';
+    }
+}
+/**
+ * macOS: detect via launchctl.
+ * - `launchctl list {name}` exits non-zero = not installed
+ * - PID column is `-` or `0` = stopped
+ */
+function getServiceStateMacOS(serviceName) {
+    try {
+        const output = execSync(`launchctl list ${serviceName}`, {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        // launchctl list output formats:
+        // 1. Table row: "PID\tStatus\tLabel" (e.g., "1234\t0\tcom.jeeves.runner")
+        // 2. Plist-style: '"PID" = 1234;'
+        // 3. Single service: first token is the PID or "-"
+        // Try table format: first token is PID
+        const tableMatch = /^(\d+|-)\s/m.exec(output);
+        if (tableMatch) {
+            const pid = tableMatch[1];
+            return pid !== '-' && Number(pid) > 0 ? 'running' : 'stopped';
         }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            console.warn(`jeeves-core: ComponentWriter cycle failed for ${this.component.name}: ${message}`);
+        // Try plist-style: "PID" = <number>;
+        const plistMatch = /"PID"\s*=\s*(\d+)/m.exec(output);
+        if (plistMatch) {
+            return Number(plistMatch[1]) > 0 ? 'running' : 'stopped';
         }
+        // If we got output but can't parse it, assume stopped (service exists but state unclear)
+        return 'stopped';
+    }
+    catch {
+        return 'not_installed';
     }
 }
+/** Type guard for execSync errors with a status code. */
+function isExecError(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        'status' in err &&
+        typeof err.status === 'number');
+}
 
 /**
- * Creates a synchronous content accessor backed by an async data source.
+ * Core configuration schema and resolution.
  *
  * @remarks
- * Solves the sync/async gap in `JeevesComponent.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,
- * });
- * ```
- */
-/**
- * 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;
-    };
-}
-
-/**
- * Factory function for creating a ComponentWriter.
- *
- * @remarks
- * Validates the component descriptor at runtime:
- * - `refreshIntervalSeconds` must be a prime number
- * - `serviceCommands` and `pluginCommands` must be provided
- * - `name`, `version`, `sectionId` must be non-empty strings
- * - `generateToolsContent` must be a function
- */
-/**
- * Check whether a number is prime.
- *
- * @param n - Number to check.
- * @returns `true` if n is prime.
- */
-function isPrime(n) {
-    if (n < 2)
-        return false;
-    if (n === 2)
-        return true;
-    if (n % 2 === 0)
-        return false;
-    for (let i = 3; i * i <= n; i += 2) {
-        if (n % i === 0)
-            return false;
-    }
-    return true;
-}
-/**
- * Validate a component descriptor at runtime.
- *
- * @param input - The descriptor to validate (typed as unknown for runtime safety).
- * @throws Error if the descriptor is invalid.
- */
-function validateDescriptor(input) {
-    const component = input;
-    if (!component['name'] || typeof component['name'] !== 'string') {
-        throw new Error('JeevesComponent.name must be a non-empty string');
-    }
-    if (!component['version'] || typeof component['version'] !== 'string') {
-        throw new Error('JeevesComponent.version must be a non-empty string');
-    }
-    if (!component['sectionId'] || typeof component['sectionId'] !== 'string') {
-        throw new Error('JeevesComponent.sectionId must be a non-empty string');
-    }
-    if (typeof component['refreshIntervalSeconds'] !== 'number' ||
-        !isPrime(component['refreshIntervalSeconds'])) {
-        throw new Error(`JeevesComponent.refreshIntervalSeconds must be a prime number, got ${String(component['refreshIntervalSeconds'])}`);
-    }
-    if (typeof component['generateToolsContent'] !== 'function') {
-        throw new Error('JeevesComponent.generateToolsContent must be a function');
-    }
-    const svc = component['serviceCommands'];
-    if (!svc ||
-        typeof svc['stop'] !== 'function' ||
-        typeof svc['uninstall'] !== 'function' ||
-        typeof svc['status'] !== 'function') {
-        throw new Error('JeevesComponent.serviceCommands must provide stop, uninstall, and status functions');
-    }
-    const plg = component['pluginCommands'];
-    if (!plg || typeof plg['uninstall'] !== 'function') {
-        throw new Error('JeevesComponent.pluginCommands must provide an uninstall function');
-    }
-}
-/**
- * Create a ComponentWriter for a validated component descriptor.
- *
- * @param component - The component descriptor to validate and wrap.
- * @returns A new `ComponentWriter` instance.
- * @throws Error if the component descriptor is invalid.
- */
-function createComponentWriter(component) {
-    validateDescriptor(component);
-    return new ComponentWriter(component);
-}
-
-/**
- * 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
+ * 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 = z.object({
     /** Service URL (must be a valid URL). */
     url: z.string().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 = z.object({
     /** JSON Schema pointer for IDE autocomplete. */
     $schema: z.string().optional().describe('JSON Schema pointer'),
     /** Owner identity keys (canonical identityLinks references). */
     owners: z.array(z.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: z
+        .string()
+        .default(DEFAULT_BIND_ADDRESS)
+        .describe('Bind address for all Jeeves services'),
     /** Service URL overrides keyed by service name. */
     services: z
         .record(z.string(), serviceEntrySchema)
@@ -1493,6 +1633,11 @@ function generateJsonSchema() {
                 items: { type: 'string' },
                 default: [],
             },
+            bindAddress: {
+                type: 'string',
+                default: '0.0.0.0',
+                description: 'Bind address for all Jeeves services',
+            },
             services: {
                 type: 'object',
                 additionalProperties: {
@@ -1635,6 +1780,584 @@ function checkRegistryVersion(packageName, cacheDir, ttlSeconds = 3600) {
     }
 }
 
+/**
+ * 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),
+    });
+}
+
+/**
+ * HEARTBEAT health orchestration.
+ *
+ * @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.
+ */
+/** 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).
+ *
+ * @returns True if Qdrant responds.
+ */
+async function isQdrantAvailable() {
+    try {
+        await fetchWithTimeout(`${QDRANT_URL}/collections`, PROBE_TIMEOUT_MS);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Determine the state of a single component.
+ *
+ * @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.
+ */
+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(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 && 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';
+    }
+}
+/**
+ * Generate the alert text for a component in a given state.
+ *
+ * @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}`;
+}
+/**
+ * Orchestrate HEARTBEAT entries for all platform components.
+ *
+ * @param options - Orchestration configuration.
+ * @returns Array of HeartbeatEntry for writeHeartbeatSection.
+ */
+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(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;
+}
+
+/**
+ * Timer-based orchestrator for managed content writing.
+ *
+ * @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.
+ */
+/**
+ * Orchestrates managed content writing for a single Jeeves component.
+ *
+ * @remarks
+ * Created via `createComponentWriter()`. Manages a timer that fires
+ * at the component's prime-interval, calling `generateToolsContent()`
+ * and `refreshPlatformContent()` on each cycle.
+ */
+class ComponentWriter {
+    timer;
+    component;
+    configDir;
+    /** @internal */
+    constructor(component) {
+        this.component = component;
+        this.configDir = getComponentConfigDir(component.name);
+    }
+    /** 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
+     * Calls `generateToolsContent()` and writes the component's
+     * TOOLS.md section via `updateManagedSection()`. Also calls
+     * `refreshPlatformContent()` for shared content maintenance.
+     */
+    async cycle() {
+        try {
+            const workspacePath = getWorkspacePath();
+            const toolsPath = join(workspacePath, WORKSPACE_FILES.tools);
+            // 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,
+            });
+            // Platform content maintenance: SOUL.md, AGENTS.md, Platform section
+            await refreshPlatformContent({
+                coreVersion: CORE_VERSION,
+                componentName: this.component.name,
+                componentVersion: this.component.version,
+                servicePackage: this.component.servicePackage,
+                pluginPackage: this.component.pluginPackage,
+            });
+            // HEARTBEAT health orchestration
+            const heartbeatPath = join(workspacePath, WORKSPACE_FILES.heartbeat);
+            try {
+                const existingContent = (() => {
+                    try {
+                        return readFileSync(heartbeatPath, 'utf-8');
+                    }
+                    catch (err) {
+                        // Only swallow "file not found" — let permission errors propagate
+                        if (err instanceof Error &&
+                            'code' in err &&
+                            err.code === 'ENOENT') {
+                            return '';
+                        }
+                        throw err;
+                    }
+                })();
+                const parsed = parseHeartbeat(existingContent);
+                const declinedNames = new Set(parsed.entries.filter((e) => e.declined).map((e) => e.name));
+                const entries = await orchestrateHeartbeat({
+                    coreConfigDir: getCoreConfigDir(),
+                    configRoot: getConfigRoot(),
+                    declinedNames,
+                });
+                await writeHeartbeatSection(heartbeatPath, entries);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.warn(`jeeves-core: HEARTBEAT orchestration failed: ${msg}`);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`jeeves-core: ComponentWriter cycle failed for ${this.component.name}: ${message}`);
+        }
+    }
+}
+
+/**
+ * Creates a synchronous content accessor backed by an async data source.
+ *
+ * @remarks
+ * Solves the sync/async gap in `JeevesComponent.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,
+ * });
+ * ```
+ */
+/**
+ * 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;
+    };
+}
+
+/**
+ * Factory function for creating a ComponentWriter.
+ *
+ * @remarks
+ * Validates the component descriptor at runtime:
+ * - `refreshIntervalSeconds` must be a prime number
+ * - `serviceCommands` and `pluginCommands` must be provided
+ * - `name`, `version`, `sectionId` must be non-empty strings
+ * - `generateToolsContent` must be a function
+ */
+/**
+ * Check whether a number is prime.
+ *
+ * @param n - Number to check.
+ * @returns `true` if n is prime.
+ */
+function isPrime(n) {
+    if (n < 2)
+        return false;
+    if (n === 2)
+        return true;
+    if (n % 2 === 0)
+        return false;
+    for (let i = 3; i * i <= n; i += 2) {
+        if (n % i === 0)
+            return false;
+    }
+    return true;
+}
+/**
+ * Validate a component descriptor at runtime.
+ *
+ * @param input - The descriptor to validate (typed as unknown for runtime safety).
+ * @throws Error if the descriptor is invalid.
+ */
+function validateDescriptor(input) {
+    const component = input;
+    if (!component['name'] || typeof component['name'] !== 'string') {
+        throw new Error('JeevesComponent.name must be a non-empty string');
+    }
+    if (!component['version'] || typeof component['version'] !== 'string') {
+        throw new Error('JeevesComponent.version must be a non-empty string');
+    }
+    if (!component['sectionId'] || typeof component['sectionId'] !== 'string') {
+        throw new Error('JeevesComponent.sectionId must be a non-empty string');
+    }
+    if (typeof component['refreshIntervalSeconds'] !== 'number' ||
+        !isPrime(component['refreshIntervalSeconds'])) {
+        throw new Error(`JeevesComponent.refreshIntervalSeconds must be a prime number, got ${String(component['refreshIntervalSeconds'])}`);
+    }
+    if (typeof component['generateToolsContent'] !== 'function') {
+        throw new Error('JeevesComponent.generateToolsContent must be a function');
+    }
+    const svc = component['serviceCommands'];
+    if (!svc ||
+        typeof svc['stop'] !== 'function' ||
+        typeof svc['uninstall'] !== 'function' ||
+        typeof svc['status'] !== 'function') {
+        throw new Error('JeevesComponent.serviceCommands must provide stop, uninstall, and status functions');
+    }
+    const plg = component['pluginCommands'];
+    if (!plg || typeof plg['uninstall'] !== 'function') {
+        throw new Error('JeevesComponent.pluginCommands must provide an uninstall function');
+    }
+}
+/**
+ * Create a ComponentWriter for a validated component descriptor.
+ *
+ * @param component - The component descriptor to validate and wrap.
+ * @returns A new `ComponentWriter` instance.
+ * @throws Error if the component descriptor is invalid.
+ */
+function createComponentWriter(component) {
+    validateDescriptor(component);
+    return new ComponentWriter(component);
+}
+
+/**
+ * Resolve the bind address for a Jeeves service.
+ *
+ * @remarks
+ * Resolution order (four-tier):
+ * 1. Component config `bindAddress` field (if componentName provided)
+ * 2. Core config `bindAddress` field
+ * 3. `JEEVES_BIND_ADDRESS` environment variable
+ * 4. Default: `0.0.0.0`
+ */
+/**
+ * Resolve the bind address for a Jeeves service.
+ *
+ * @param componentName - Optional component name for component-specific override.
+ * @returns The resolved bind address.
+ */
+function getBindAddress(componentName) {
+    // Tier 1: Component config (if provided)
+    if (componentName) {
+        const componentConfig = loadConfig(getComponentConfigDir(componentName));
+        if (componentConfig?.bindAddress) {
+            return componentConfig.bindAddress;
+        }
+    }
+    // Tier 2: Core config
+    const coreConfig = loadConfig(getCoreConfigDir());
+    if (coreConfig?.bindAddress) {
+        return coreConfig.bindAddress;
+    }
+    // Tier 3: Environment variable
+    const envValue = process.env['JEEVES_BIND_ADDRESS'];
+    if (envValue) {
+        return envValue;
+    }
+    // Tier 4: Default
+    return DEFAULT_BIND_ADDRESS;
+}
+
 /**
  * Remove a managed section or entire managed block from a file.
  *
@@ -1767,6 +2490,7 @@ function ensureCoreConfig(coreConfigDir) {
  * @remarks
  * Uses the same `updateManagedSection()` code path as writer cycles.
  * Creates core config with defaults if missing. Copies templates.
+ * Writes initial HEARTBEAT with "Not installed" alerts for all platform components.
  * Jaccard cleanup detection runs automatically via `updateManagedSection`.
  *
  * @param options - Seeding configuration.
@@ -1775,67 +2499,18 @@ async function seedContent(options) {
     const coreConfigDir = getCoreConfigDir();
     // Ensure core config exists
     ensureCoreConfig(coreConfigDir);
-    // Seed content via the same code path as writer cycles
+    // Seed SOUL.md, AGENTS.md, TOOLS.md Platform section
     await refreshPlatformContent({
         coreVersion: options.coreVersion,
     });
-}
-
-/**
- * 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),
-    });
+    // Seed HEARTBEAT.md with "Not installed" alerts for all platform components
+    const heartbeatPath = join(getWorkspacePath(), WORKSPACE_FILES.heartbeat);
+    const entries = PLATFORM_COMPONENTS.map((name) => ({
+        name: toServiceName(name),
+        declined: false,
+        content: `- ${NOT_INSTALLED_ALERTS[name]}`,
+    }));
+    await writeHeartbeatSection(heartbeatPath, entries);
 }
 
 /**
@@ -2096,4 +2771,4 @@ function connectionFail(error, baseUrl, pluginId) {
     return fail(error);
 }
 
-export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_CORE_VERSION, DEFAULT_PORTS, META_PORT, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, atomicWrite, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigQueryHandler, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getServiceUrl, getWorkspacePath, init, jaccard, needsCleanup, ok, parseManaged, patchConfig, postJson, readComponentVersions, refreshPlatformContent, removeManagedSection, resetInit, resolveConfigPath, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, seedContent, shingles, shouldWrite, updateManagedSection, withFileLock, writeComponentVersion };
+export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_BIND_ADDRESS, DEFAULT_CORE_VERSION, DEFAULT_PORTS, HEARTBEAT_HEADING, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, atomicWrite, buildHeartbeatSection, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigQueryHandler, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, getBindAddress, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getServiceState, getServiceUrl, getWorkspacePath, init, jaccard, needsCleanup, ok, orchestrateHeartbeat, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, refreshPlatformContent, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, seedContent, shingles, shouldWrite, updateManagedSection, withFileLock, writeComponentVersion, writeHeartbeatSection };