@karmaniverous/jeeves 0.3.0 → 0.4.0

package/dist/cli/jeeves/index.js

@@ -1,20 +1,51 @@
 #!/usr/bin/env node
-#!/usr/bin/env node
-import require$$0 from 'commander';
+import * as commander from 'commander';
 import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, cpSync, rmSync } from 'node:fs';
 import { join, dirname } from 'node:path';
+import { gte } from 'semver';
+import 'node:child_process';
 import { z } from 'zod';
+import { lock } from 'proper-lockfile';
 import { fileURLToPath } from 'node:url';
 import { packageDirectorySync } from 'package-directory';
-import { lock } from 'proper-lockfile';
-import { gte } from 'semver';
 
 function getDefaultExportFromCjs (x) {
 	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
 }
 
+function getAugmentedNamespace(n) {
+  if (Object.prototype.hasOwnProperty.call(n, '__esModule')) return n;
+  var f = n.default;
+	if (typeof f == "function") {
+		var a = function a () {
+			var isInstance = false;
+      try {
+        isInstance = this instanceof a;
+      } catch {}
+			if (isInstance) {
+        return Reflect.construct(f, arguments, this.constructor);
+			}
+			return f.apply(this, arguments);
+		};
+		a.prototype = f.prototype;
+  } else a = {};
+  Object.defineProperty(a, '__esModule', {value: true});
+	Object.keys(n).forEach(function (k) {
+		var d = Object.getOwnPropertyDescriptor(n, k);
+		Object.defineProperty(a, k, d.get ? d : {
+			enumerable: true,
+			get: function () {
+				return n[k];
+			}
+		});
+	});
+	return a;
+}
+
 var extraTypings = {exports: {}};
 
+var require$$0 = /*@__PURE__*/getAugmentedNamespace(commander);
+
 var hasRequiredExtraTypings;
 
 function requireExtraTypings () {
@@ -85,6 +116,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 = {
@@ -94,6 +127,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 = {
@@ -103,7 +138,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.
  *
@@ -130,6 +173,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';
@@ -165,7 +210,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
@@ -195,19 +240,86 @@ 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',
+];
 
 /**
  * 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';
+
+/**
+ * Workspace and config root initialization.
+ *
+ * @remarks
+ * `init()` must be called once before any other core library functions.
+ * It caches `workspacePath` and `configRoot` at module level.
+ * Core derives all namespaced paths from these values:
+ * - `{configRoot}/jeeves-core/` for core config
+ * - `{configRoot}/jeeves-{name}/` for each component
+ */
+let state;
+/**
+ * Initialize the core library with workspace and config root paths.
+ *
+ * @param options - Workspace and config root paths.
+ */
+function init(options) {
+    state = {
+        workspacePath: options.workspacePath,
+        configRoot: options.configRoot,
+        coreConfigDir: join(options.configRoot, CORE_CONFIG_DIR),
+    };
+}
+/**
+ * Get the cached workspace path.
+ *
+ * @throws Error if `init()` has not been called.
+ */
+function getWorkspacePath() {
+    if (!state)
+        throw new Error('jeeves-core: init() must be called first');
+    return state.workspacePath;
+}
+/**
+ * Get the core config directory path.
+ *
+ * @throws Error if `init()` has not been called.
+ */
+function getCoreConfigDir() {
+    if (!state)
+        throw new Error('jeeves-core: init() must be called first');
+    return state.coreConfigDir;
+}
+
+var init$1 = /*#__PURE__*/Object.freeze({
+	__proto__: null,
+	getCoreConfigDir: getCoreConfigDir,
+	getWorkspacePath: getWorkspacePath,
+	init: init
+});
 
 /**
  * Core configuration schema and resolution.
@@ -224,12 +336,22 @@ 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)
@@ -266,6 +388,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: {
@@ -312,55 +439,313 @@ function loadConfig(configDir) {
 }
 
 /**
- * Workspace and config root initialization.
+ * Service URL resolution.
  *
  * @remarks
- * `init()` must be called once before any other core library functions.
- * It caches `workspacePath` and `configRoot` at module level.
- * Core derives all namespaced paths from these values:
- * - `{configRoot}/jeeves-core/` for core config
- * - `{configRoot}/jeeves-{name}/` for each component
+ * 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
  */
-let state;
 /**
- * Initialize the core library with workspace and config root paths.
+ * Resolve the URL for a named Jeeves service.
  *
- * @param options - Workspace and config root paths.
+ * @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 init(options) {
-    state = {
-        workspacePath: options.workspacePath,
-        configRoot: options.configRoot,
-        coreConfigDir: join(options.configRoot, CORE_CONFIG_DIR),
-    };
+function getServiceUrl(serviceName, consumerName) {
+    // 2. Check core config
+    const coreDir = getCoreConfigDir();
+    const coreConfig = loadConfig(coreDir);
+    const coreUrl = coreConfig?.services[serviceName]?.url;
+    if (coreUrl)
+        return coreUrl;
+    // 3. Fall back to port constants
+    const port = DEFAULT_PORTS[serviceName];
+    if (port !== undefined) {
+        return `http://127.0.0.1:${String(port)}`;
+    }
+    throw new Error(`jeeves-core: unknown service "${serviceName}" and no config found`);
 }
+
 /**
- * Get the cached workspace path.
+ * HTTP helpers for the OpenClaw plugin SDK.
  *
- * @throws Error if `init()` has not been called.
+ * @remarks
+ * Thin wrappers around `fetch` that throw on non-OK responses
+ * and handle JSON serialisation/deserialisation.
  */
-function getWorkspacePath() {
-    if (!state)
-        throw new Error('jeeves-core: init() must be called first');
-    return state.workspacePath;
+/**
+ * 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);
+    }
 }
+
 /**
- * Get the core config directory path.
+ * Shared file I/O helpers for managed section operations.
  *
- * @throws Error if `init()` has not been called.
+ * @remarks
+ * Extracts the atomic write pattern and file-level locking into
+ * reusable utilities, eliminating duplication between
+ * `updateManagedSection` and `removeManagedSection`.
  */
-function getCoreConfigDir() {
-    if (!state)
-        throw new Error('jeeves-core: init() must be called first');
-    return state.coreConfigDir;
+/** Stale lock threshold in ms (2 minutes). */
+const STALE_LOCK_MS = 120_000;
+/** Default core version when none provided. */
+const DEFAULT_CORE_VERSION = CORE_VERSION;
+/** Lock retry options. */
+const LOCK_RETRIES = { retries: 5, minTimeout: 100, maxTimeout: 1000 };
+/**
+ * Write content to a file atomically via a temp file + rename.
+ *
+ * @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`);
+    writeFileSync(tempPath, content, 'utf-8');
+    renameSync(tempPath, filePath);
+}
+/**
+ * Execute a callback while holding a file lock.
+ *
+ * @remarks
+ * Acquires a lock on the file, executes the callback, and releases
+ * the lock in a finally block. The lock uses a 2-minute stale threshold
+ * and retries up to 5 times.
+ *
+ * @param filePath - Absolute path to the file to lock.
+ * @param fn - Async callback to execute while holding the lock.
+ */
+async function withFileLock(filePath, fn) {
+    let release;
+    try {
+        release = await lock(filePath, {
+            stale: STALE_LOCK_MS,
+            retries: LOCK_RETRIES,
+        });
+        await fn();
+    }
+    finally {
+        if (release) {
+            try {
+                await release();
+            }
+            catch {
+                // Lock already released or file deleted — safe to ignore
+            }
+        }
+    }
 }
 
-var init$1 = /*#__PURE__*/Object.freeze({
-	__proto__: null,
-	getCoreConfigDir: getCoreConfigDir,
-	getWorkspacePath: getWorkspacePath,
-	init: init
-});
+/**
+ * Shared component version state file management.
+ *
+ * @remarks
+ * Each `ComponentWriter` cycle writes its component's entry to
+ * `{coreConfigDir}/component-versions.json`. The Platform Handlebars
+ * template reads this file to populate ALL rows in the service health
+ * table, not just the calling component's.
+ */
+/**
+ * Read the component versions state file.
+ *
+ * @param coreConfigDir - Path to the core config directory.
+ * @returns The parsed state, or an empty object if the file doesn't exist.
+ */
+function readComponentVersions(coreConfigDir) {
+    const filePath = join(coreConfigDir, COMPONENT_VERSIONS_FILE);
+    if (!existsSync(filePath))
+        return {};
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Write a component's version entry to the shared state file.
+ *
+ * @remarks
+ * Reads the existing file, merges the new entry, and writes atomically.
+ *
+ * @param coreConfigDir - Path to the core config directory.
+ * @param options - Component version data to write.
+ */
+function writeComponentVersion(coreConfigDir, options) {
+    const existing = readComponentVersions(coreConfigDir);
+    existing[options.componentName] = {
+        pluginVersion: options.pluginVersion,
+        servicePackage: options.servicePackage,
+        pluginPackage: options.pluginPackage,
+        updatedAt: new Date().toISOString(),
+    };
+    const filePath = join(coreConfigDir, COMPONENT_VERSIONS_FILE);
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    atomicWrite(filePath, JSON.stringify(existing, null, 2) + '\n');
+}
+
+/**
+ * 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}`;
+}
+/** "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`.',
+};
+
+/**
+ * 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}`);
+    }
+}
 
 var agentsSectionContent = `## Memory Architecture
 
@@ -429,6 +814,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).
@@ -437,7 +824,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.
 
@@ -498,14 +885,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
 
@@ -541,11 +925,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
 
@@ -581,6 +971,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.
@@ -719,116 +1110,6 @@ Read these templates when creating new specs, onboarding to new projects, or whe
 <!-- ENDIF_TEMPLATES -->
 `;
 
-/**
- * Shared file I/O helpers for managed section operations.
- *
- * @remarks
- * Extracts the atomic write pattern and file-level locking into
- * reusable utilities, eliminating duplication between
- * `updateManagedSection` and `removeManagedSection`.
- */
-/** Stale lock threshold in ms (2 minutes). */
-const STALE_LOCK_MS = 120_000;
-/** Default core version when none provided. */
-const DEFAULT_CORE_VERSION = CORE_VERSION;
-/** Lock retry options. */
-const LOCK_RETRIES = { retries: 5, minTimeout: 100, maxTimeout: 1000 };
-/**
- * Write content to a file atomically via a temp file + rename.
- *
- * @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`);
-    writeFileSync(tempPath, content, 'utf-8');
-    renameSync(tempPath, filePath);
-}
-/**
- * Execute a callback while holding a file lock.
- *
- * @remarks
- * Acquires a lock on the file, executes the callback, and releases
- * the lock in a finally block. The lock uses a 2-minute stale threshold
- * and retries up to 5 times.
- *
- * @param filePath - Absolute path to the file to lock.
- * @param fn - Async callback to execute while holding the lock.
- */
-async function withFileLock(filePath, fn) {
-    let release;
-    try {
-        release = await lock(filePath, {
-            stale: STALE_LOCK_MS,
-            retries: LOCK_RETRIES,
-        });
-        await fn();
-    }
-    finally {
-        if (release) {
-            try {
-                await release();
-            }
-            catch {
-                // Lock already released or file deleted — safe to ignore
-            }
-        }
-    }
-}
-
-/**
- * Shared component version state file management.
- *
- * @remarks
- * Each `ComponentWriter` cycle writes its component's entry to
- * `{coreConfigDir}/component-versions.json`. The Platform Handlebars
- * template reads this file to populate ALL rows in the service health
- * table, not just the calling component's.
- */
-/**
- * Read the component versions state file.
- *
- * @param coreConfigDir - Path to the core config directory.
- * @returns The parsed state, or an empty object if the file doesn't exist.
- */
-function readComponentVersions(coreConfigDir) {
-    const filePath = join(coreConfigDir, COMPONENT_VERSIONS_FILE);
-    if (!existsSync(filePath))
-        return {};
-    try {
-        const raw = readFileSync(filePath, 'utf-8');
-        return JSON.parse(raw);
-    }
-    catch {
-        return {};
-    }
-}
-/**
- * Write a component's version entry to the shared state file.
- *
- * @remarks
- * Reads the existing file, merges the new entry, and writes atomically.
- *
- * @param coreConfigDir - Path to the core config directory.
- * @param options - Component version data to write.
- */
-function writeComponentVersion(coreConfigDir, options) {
-    const existing = readComponentVersions(coreConfigDir);
-    existing[options.componentName] = {
-        pluginVersion: options.pluginVersion,
-        servicePackage: options.servicePackage,
-        pluginPackage: options.pluginPackage,
-        updatedAt: new Date().toISOString(),
-    };
-    const filePath = join(coreConfigDir, COMPONENT_VERSIONS_FILE);
-    const dir = dirname(filePath);
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-    }
-    atomicWrite(filePath, JSON.stringify(existing, null, 2) + '\n');
-}
-
 /**
  * Similarity-based cleanup detection for orphaned managed content.
  *
@@ -1024,6 +1305,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.
  *
@@ -1140,32 +1463,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);
         });
     }
@@ -1333,6 +1675,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.
@@ -1341,10 +1684,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,
     });
+    // 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);
 }
 
 /**
@@ -1401,72 +1752,12 @@ function registerInstallCommand(program) {
         console.log('  - SOUL.md managed section written');
         console.log('  - AGENTS.md managed section written');
         console.log('  - TOOLS.md Platform section written');
+        console.log('  - HEARTBEAT.md platform status written');
         console.log('  - Templates copied to config directory');
         console.log('  - Core config created (if not present)');
     });
 }
 
-/**
- * Service URL resolution.
- *
- * @remarks
- * Resolves the URL for a named Jeeves service using the following
- * resolution order:
- * 1. Consumer's own component config
- * 2. Core config (`{configRoot}/jeeves-core/config.json`)
- * 3. Default port constants
- */
-/**
- * Resolve the URL for a named Jeeves service.
- *
- * @param serviceName - The service name (e.g., 'watcher', 'runner').
- * @param consumerName - Optional consumer component name for config override.
- * @returns The resolved service URL.
- * @throws Error if `init()` has not been called or the service is unknown.
- */
-function getServiceUrl(serviceName, consumerName) {
-    // 2. Check core config
-    const coreDir = getCoreConfigDir();
-    const coreConfig = loadConfig(coreDir);
-    const coreUrl = coreConfig?.services[serviceName]?.url;
-    if (coreUrl)
-        return coreUrl;
-    // 3. Fall back to port constants
-    const port = DEFAULT_PORTS[serviceName];
-    if (port !== undefined) {
-        return `http://127.0.0.1:${String(port)}`;
-    }
-    throw new Error(`jeeves-core: unknown service "${serviceName}" and no config found`);
-}
-
-/**
- * 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);
-    }
-}
-
 /**
  * CLI status command: discover components and probe their health.
  *