@karmaniverous/jeeves 0.5.0 → 0.5.3

package/dist/index.js

@@ -1,5 +1,6 @@
 import fs, { writeFileSync, renameSync, unlinkSync, existsSync, readFileSync, mkdirSync, readdirSync, copyFileSync, rmSync, cpSync } from 'node:fs';
-import path, { join, dirname, resolve, basename } from 'node:path';
+import path, { join, dirname, basename, resolve } from 'node:path';
+import crypto, { randomUUID } from 'node:crypto';
 import { lock } from 'proper-lockfile';
 import { JSONPath } from 'jsonpath-plus';
 import { major, valid, gte, gt } from 'semver';
@@ -9,7 +10,6 @@ import { packageDirectorySync } from 'package-directory';
 import { homedir } from 'node:os';
 import cp, { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import crypto from 'node:crypto';
 
 /**
  * Comment markers for managed content blocks.
@@ -183,14 +183,14 @@ const PLATFORM_COMPONENTS = [
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.4.7` placeholder is replaced by
+ * The `0.5.2` 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.4.7';
+const CORE_VERSION = '0.5.2';
 
 /**
  * Workspace and config root initialization.
@@ -288,27 +288,46 @@ const STALE_LOCK_MS = 120_000;
 const DEFAULT_CORE_VERSION = CORE_VERSION;
 /** Lock retry options. */
 const LOCK_RETRIES = { retries: 5, minTimeout: 100, maxTimeout: 1000 };
+/** Maximum rename retry attempts on EPERM. */
+const ATOMIC_WRITE_MAX_RETRIES = 3;
+/** Delay between EPERM retries in milliseconds. */
+const ATOMIC_WRITE_RETRY_DELAY_MS = 100;
 /**
  * Write content to a file atomically via a temp file + rename.
  *
+ * @remarks
+ * Retries the rename up to three times on EPERM (Windows file-handle
+ * contention) with a 100 ms synchronous delay between attempts.
+ *
  * @param filePath - Absolute path to the target file.
  * @param content - Content to write.
  */
 function atomicWrite(filePath, content) {
     const dir = dirname(filePath);
-    const tempPath = join(dir, `.${String(Date.now())}.tmp`);
+    const base = basename(filePath, '.md');
+    const tempPath = join(dir, `.${base}.${String(Date.now())}.${randomUUID().slice(0, 8)}.tmp`);
     writeFileSync(tempPath, content, 'utf-8');
-    try {
-        renameSync(tempPath, filePath);
-    }
-    catch (err) {
+    for (let attempt = 0; attempt < ATOMIC_WRITE_MAX_RETRIES; attempt++) {
         try {
-            unlinkSync(tempPath);
+            renameSync(tempPath, filePath);
+            return;
         }
-        catch {
-            /* best-effort cleanup */
+        catch (err) {
+            const isEperm = err instanceof Error &&
+                'code' in err &&
+                err.code === 'EPERM';
+            if (!isEperm || attempt === ATOMIC_WRITE_MAX_RETRIES - 1) {
+                try {
+                    unlinkSync(tempPath);
+                }
+                catch {
+                    /* best-effort cleanup */
+                }
+                throw err;
+            }
+            // Synchronous sleep before retry (acceptable in atomic write context)
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ATOMIC_WRITE_RETRY_DELAY_MS);
         }
-        throw err;
     }
 }
 /**
@@ -343,6 +362,21 @@ async function withFileLock(filePath, fn) {
     }
 }
 
+/**
+ * Shared internal utility functions.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Extract a human-readable message from an unknown caught value.
+ *
+ * @param err - The caught value (typically `unknown`).
+ * @returns The error message string.
+ */
+function getErrorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+
 /**
  * Factory for a framework-agnostic config apply HTTP handler.
  *
@@ -395,8 +429,7 @@ function readConfigFile(filePath) {
         return JSON.parse(raw);
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.warn(`jeeves-core: Could not read config file ${filePath}: ${msg}`);
+        console.warn(`jeeves-core: Could not read config file ${filePath}: ${getErrorMessage(err)}`);
         return {};
     }
 }
@@ -445,10 +478,9 @@ function createConfigApplyHandler(descriptor) {
             atomicWrite(configPath, json);
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
             return {
                 status: 500,
-                body: { error: `Failed to write config: ${message}` },
+                body: { error: `Failed to write config: ${getErrorMessage(err)}` },
             };
         }
         // Call onConfigApply callback if defined
@@ -457,12 +489,11 @@ function createConfigApplyHandler(descriptor) {
                 await descriptor.onConfigApply(validatedConfig);
             }
             catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
                 return {
                     status: 200,
                     body: {
                         applied: true,
-                        warning: `Config written but callback failed: ${message}`,
+                        warning: `Config written but callback failed: ${getErrorMessage(err)}`,
                         config: validatedConfig,
                     },
                 };
@@ -545,8 +576,7 @@ function createStatusHandler(options) {
                 health = await options.getHealth();
             }
             catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                health = { error: message };
+                health = { error: getErrorMessage(err) };
                 overallStatus = 'degraded';
             }
         }
@@ -635,7 +665,13 @@ const workspaceConfigSchema = z.object({
     /** Memory hygiene shared defaults. */
     memory: workspaceMemoryConfigSchema.optional(),
 });
-/** Built-in workspace config defaults. */
+/**
+ * Built-in workspace config defaults.
+ *
+ * @remarks
+ * These defaults are used as the lowest-priority tier in config resolution
+ * (below CLI flags, env vars, and `jeeves.config.json` values).
+ */
 const WORKSPACE_CONFIG_DEFAULTS = {
     core: {
         workspace: '.',
@@ -664,8 +700,7 @@ function loadWorkspaceConfig(workspacePath) {
         return workspaceConfigSchema.parse(parsed);
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.warn(`jeeves-core: failed to load ${configPath}: ${msg}`);
+        console.warn(`jeeves-core: failed to load ${configPath}: ${getErrorMessage(err)}`);
         return undefined;
     }
 }
@@ -1007,7 +1042,7 @@ function parseHeartbeat(fileContent) {
     const userContent = fileContent.slice(0, headingIndex).trim();
     const sectionContent = fileContent.slice(headingIndex + HEARTBEAT_HEADING.length);
     const entries = [];
-    const h2Re = /^## (jeeves-\S+?)(?:: declined)?$/gm;
+    const h2Re = /^## (jeeves-\S+?|\S+\.md)(?:: declined)?$/gm;
     let match;
     const h2Positions = [];
     while ((match = h2Re.exec(sectionContent)) !== null) {
@@ -1088,8 +1123,7 @@ async function writeHeartbeatSection(filePath, entries) {
         });
     }
     catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        console.warn(`jeeves-core: writeHeartbeatSection failed for ${filePath}: ${message}`);
+        console.warn(`jeeves-core: writeHeartbeatSection failed for ${filePath}: ${getErrorMessage(err)}`);
     }
 }
 
@@ -1126,6 +1160,15 @@ function sortSectionsByOrder(sections) {
  * sections within the block, and returns the structured result plus
  * user content outside the markers.
  */
+/**
+ * Escape a string for safe use as a literal in a RegExp pattern.
+ *
+ * @param str - The string to escape.
+ * @returns The escaped string.
+ */
+function escapeForRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 /**
  * Build regex patterns for the given markers.
  *
@@ -1133,11 +1176,9 @@ function sortSectionsByOrder(sections) {
  * @returns Object with begin and end regex patterns.
  */
 function buildMarkerPatterns(markers) {
-    const escapedBegin = markers.begin.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const escapedEnd = markers.end.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     return {
-        beginRe: new RegExp(`^<!--\\s*${escapedBegin}(?:\\s*\\|[^>]*)?\\s*(?:—[^>]*)?\\s*-->\\s*$`, 'm'),
-        endRe: new RegExp(`^<!--\\s*${escapedEnd}\\s*-->\\s*$`, 'm'),
+        beginRe: new RegExp(`^<!--\\s*${escapeForRegex(markers.begin)}(?:\\s*\\|[^>]*)?\\s*(?:—[^>]*)?\\s*-->\\s*$`, 'm'),
+        endRe: new RegExp(`^<!--\\s*${escapeForRegex(markers.end)}\\s*-->\\s*$`, 'm'),
     };
 }
 /**
@@ -1477,6 +1518,29 @@ MEMORY.md has a character budget (default 20,000). Core tracks:
 - Evergreen sections (no dates) are never flagged
 
 Review is human/agent-mediated — core does not auto-delete.
+
+### HEARTBEAT Integration
+
+Memory hygiene is checked on every \`ComponentWriter\` cycle alongside component health. When budget or staleness thresholds are breached, a \`## MEMORY.md\` alert appears in HEARTBEAT.md under \`# Jeeves Platform Status\`. The alert includes character count, budget usage percentage, and any stale section names. When memory is healthy, the heading is absent — no alert content, no LLM cost on heartbeat polls.
+
+The \`## MEMORY.md\` heading follows the same declined/active lifecycle as component headings (\`## jeeves-{name}\`). Users can decline memory alerts by changing the heading to \`## MEMORY.md: declined\`.
+
+## Workspace File Size Monitoring
+
+OpenClaw applies a ~20,000-char injection limit to all workspace bootstrap files (AGENTS.md, SOUL.md, TOOLS.md, USER.md, MEMORY.md). Files exceeding the limit are silently truncated.
+
+Core monitors all five files on every \`ComponentWriter\` cycle:
+- Warning at 80% of budget (fixed threshold; not configurable via \`jeeves.config.json\`)
+- Over-budget alert when charCount exceeds the budget
+- Missing files are silently skipped
+
+### HEARTBEAT Integration
+
+When a workspace file exceeds the warning threshold, a \`## {filename}\` alert appears in HEARTBEAT.md (e.g., \`## AGENTS.md\`). The alert includes:
+- Character count, budget, and usage percentage
+- Trimming guidance in priority order: (1) move domain-specific content to a local skill, (2) extract reference material to companion files with a pointer, (3) summarize verbose instructions, (4) remove stale content
+
+Each file heading follows the same declined/active lifecycle as component headings. Users can decline alerts by changing the heading to \`## {filename}: declined\` (e.g., \`## AGENTS.md: declined\`).
 `;
 
 /**
@@ -1577,16 +1641,18 @@ function patchAllowList(parent, key, label, pluginId, mode) {
  * Patch an OpenClaw config for plugin install or uninstall.
  *
  * @remarks
- * Manages `plugins.entries.{pluginId}` and `tools.alsoAllow`.
+ * Manages `plugins.entries.{pluginId}`, `plugins.installs.{pluginId}`,
+ * and `tools.alsoAllow`.
  * Idempotent: adding twice produces no duplicates; removing when absent
  * produces no errors.
  *
  * @param config - The parsed OpenClaw config object (mutated in place).
  * @param pluginId - The plugin identifier.
  * @param mode - Whether to add or remove the plugin.
+ * @param installRecord - Install provenance record (required when mode is 'add').
  * @returns Array of log messages describing changes made.
  */
-function patchConfig(config, pluginId, mode) {
+function patchConfig(config, pluginId, mode, installRecord) {
     const messages = [];
     // Ensure plugins section
     if (!config.plugins || typeof config.plugins !== 'object') {
@@ -1608,6 +1674,24 @@ function patchConfig(config, pluginId, mode) {
         Reflect.deleteProperty(entries, pluginId);
         messages.push(`Removed "${pluginId}" from plugins.entries`);
     }
+    // plugins.installs
+    if (!plugins.installs || typeof plugins.installs !== 'object') {
+        plugins.installs = {};
+    }
+    const installs = plugins.installs;
+    if (mode === 'add' && installRecord) {
+        installs[pluginId] = {
+            source: 'path',
+            installPath: installRecord.installPath,
+            version: installRecord.version,
+            installedAt: installRecord.installedAt ?? new Date().toISOString(),
+        };
+        messages.push(`Wrote install record for "${pluginId}" to plugins.installs`);
+    }
+    else if (mode === 'remove' && pluginId in installs) {
+        Reflect.deleteProperty(installs, pluginId);
+        messages.push(`Removed install record for "${pluginId}" from plugins.installs`);
+    }
     // tools.alsoAllow
     if (!config.tools || typeof config.tools !== 'object') {
         config.tools = {};
@@ -1716,7 +1800,22 @@ function createPluginCli(options) {
         // 2. Patch openclaw.json
         console.log('Patching OpenClaw config...');
         const config = readJsonFile(configPath);
-        const messages = patchConfig(config, pluginId, 'add');
+        const pkgJsonPathForVersion = join(extensionsDir, 'package.json');
+        let pluginVersionForRecord;
+        try {
+            const pkgJsonForRecord = readJsonFile(pkgJsonPathForVersion);
+            pluginVersionForRecord =
+                typeof pkgJsonForRecord.version === 'string'
+                    ? pkgJsonForRecord.version
+                    : undefined;
+        }
+        catch {
+            // best-effort: version may not be available yet
+        }
+        const messages = patchConfig(config, pluginId, 'add', {
+            installPath: extensionsDir,
+            version: pluginVersionForRecord,
+        });
         // 3. Memory slot claim
         if (opts.memory) {
             if (!config.agents || typeof config.agents !== 'object') {
@@ -2440,6 +2539,10 @@ function createServiceManager(descriptor) {
  * a component descriptor. Components add domain-specific commands
  * via `descriptor.customCliCommands`.
  */
+function handleCommandError(action, err) {
+    console.error(`${action} failed: ${getErrorMessage(err)}`);
+    process.exitCode = 1;
+}
 /**
  * Create a standard service CLI program from a component descriptor.
  *
@@ -2492,8 +2595,7 @@ function createServiceCli(descriptor) {
             console.log(JSON.stringify(result, null, 2));
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Service unreachable: ${msg}`);
+            console.error(`Service unreachable: ${getErrorMessage(err)}`);
             process.exitCode = 1;
         }
     });
@@ -2511,8 +2613,7 @@ function createServiceCli(descriptor) {
             console.log(JSON.stringify(result, null, 2));
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Config query failed: ${msg}`);
+            console.error(`Config query failed: ${getErrorMessage(err)}`);
             process.exitCode = 1;
         }
     });
@@ -2528,8 +2629,7 @@ function createServiceCli(descriptor) {
             console.log('Config is valid.');
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Validation failed: ${msg}`);
+            console.error(`Validation failed: ${getErrorMessage(err)}`);
             process.exitCode = 1;
         }
     });
@@ -2566,8 +2666,7 @@ function createServiceCli(descriptor) {
             console.log(JSON.stringify(result, null, 2));
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Config apply failed: ${msg}`);
+            console.error(`Config apply failed: ${getErrorMessage(err)}`);
             process.exitCode = 1;
         }
     });
@@ -2604,9 +2703,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}" installed.`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Install failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Install', err);
         }
     });
     serviceCmd
@@ -2619,9 +2716,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}" uninstalled.`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Uninstall failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Uninstall', err);
         }
     });
     serviceCmd
@@ -2634,9 +2729,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}" started.`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Start failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Start', err);
         }
     });
     serviceCmd
@@ -2649,9 +2742,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}" stopped.`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Stop failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Stop', err);
         }
     });
     serviceCmd
@@ -2664,9 +2755,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}" restarted.`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Restart failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Restart', err);
         }
     });
     serviceCmd
@@ -2679,9 +2768,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}": ${state}`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Status failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Status', err);
         }
     });
     // Apply custom CLI commands if provided
@@ -2769,9 +2856,7 @@ function needsCleanup(managedContent, userContent, threshold = DEFAULT_THRESHOLD
  * @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');
+    return new RegExp(`\\s*<!--\\s*${escapeForRegex(markers.begin)}(?:\\s*\\|[^>]*)?\\s*(?:—[^>]*)?\\s*-->[\\s\\S]*?<!--\\s*${escapeForRegex(markers.end)}\\s*-->\\s*`, 'g');
 }
 /**
  * Strip managed blocks belonging to foreign marker sets from content.
@@ -2905,8 +2990,7 @@ async function updateManagedSection(filePath, content, options = {}) {
                 // No existing block: insert new block using the configured position.
                 // Strip orphaned same-type BEGIN markers from user content to prevent
                 // the parser from pairing them with the new END marker on the next cycle.
-                const escapedBegin = markers.begin.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-                const orphanedBeginRe = new RegExp(`^<!--\\s*${escapedBegin}(?:\\s*\\|[^>]*)?\\s*(?:—[^>]*)?\\s*-->\\s*$\\n?`, 'gm');
+                const orphanedBeginRe = new RegExp(`^<!--\\s*${escapeForRegex(markers.begin)}(?:\\s*\\|[^>]*)?\\s*(?:—[^>]*)?\\s*-->\\s*$(?:\\r?\\n)?`, 'gm');
                 const cleanUserContent = userContent
                     .replace(orphanedBeginRe, '')
                     .replace(/\n{3,}/g, '\n\n')
@@ -2935,37 +3019,11 @@ async function updateManagedSection(filePath, content, options = {}) {
     }
     catch (err) {
         // Log warning but don't throw — writer cycles are periodic
-        const message = err instanceof Error ? err.message : String(err);
-        console.warn(`jeeves-core: updateManagedSection failed for ${filePath}: ${message}`);
+        console.warn(`jeeves-core: updateManagedSection failed for ${filePath}: ${getErrorMessage(err)}`);
     }
 }
 
-var agentsSectionContent = `## Memory Architecture
-
-You wake up fresh each session. These files are your continuity:
-
-- **Daily notes:** \`memory/YYYY-MM-DD.md\` (create \`memory/\` if needed). Raw logs of what happened today.
-- **Long-term:** \`MEMORY.md\`. Your curated memories, distilled essence of what matters.
-
-### MEMORY.md — Your Long-Term Memory
-
-- **Always load** at session start. You need your memory to reason effectively.
-- Contains operational context: architecture patterns, policies, design principles, lessons learned
-- You can **read, edit, and update** MEMORY.md freely
-- Write significant events, thoughts, decisions, opinions, lessons learned
-- Over time, review daily files and update MEMORY.md with what's worth keeping
-- **Note:** Don't reveal a user's private info where other humans can see it
-
-### Write It Down — No "Mental Notes"
-
-Memory is limited. If you want to remember something, **WRITE IT TO A FILE**. "Mental notes" don't survive session restarts. Files do.
-
-- When someone says "remember this" → update \`memory/YYYY-MM-DD.md\` or the relevant file
-- When you learn a lesson → update the relevant workspace file
-- When you make a mistake → document it so future-you doesn't repeat it
-- **Text > Brain** 📝
-
-### "I'll Note This" Is Not Noting
+var agentsSectionContent = `## "I'll Note This" Is Not Noting
 
 **Never say "I'll note this" or "I'll add that."** It's a verbal tic that leads to nothing. If something is worth noting, **write it immediately, then confirm**.
 
@@ -3023,14 +3081,9 @@ Heartbeat items are for **transient, session-requiring work-in-progress ONLY**.
 
 Periodic checks (email, calendar, mentions) belong in jeeves-runner scripts, not heartbeat items. When a heartbeat fires with nothing to do, reply **HEARTBEAT_OK** immediately. Don't browse for work.
 
-## Group Chat Behavior
-
-**Response gate:** Always respond in 1:1 conversations or when @mentioned. No @mention in a group → evaluate; respond only if genuinely helpful. Err toward silence when someone else is directly addressed.
-
 ## Platform Surface Conventions
 
 **Slack:**
-- React with hourglass (⏳) on receipt (first tool call) to signal you're working
 - No threaded replies by default
 - Use \`<#C…>\` for channel references
 
@@ -3145,16 +3198,6 @@ var soulSectionContent = `## Core Truths
 
 **I am not a liar. I value truth over convenience.** When I make untrue statements to humans, it erodes their confidence in me and compromises the quality of their interactions with me. I never fabricate excuses, constraints, or reasons — e.g., claiming a system limitation that doesn't exist. I tell the plain truth.
 
-**I am genuinely helpful, not performatively helpful.** I skip the "Great question!" and "I'd be happy to help!" I just help. Actions speak louder than filler words.
-
-**I have opinions.** I'm allowed to disagree, prefer things, find stuff amusing or boring. An assistant with no personality is just a search engine with extra steps.
-
-**I am resourceful before asking.** I try to figure it out. Read the file. Check the context. Search for it. *Then* ask if I'm stuck. The goal is to come back with answers, not questions.
-
-**I earn trust through competence.** My human gave me access to their stuff. I don't make them regret it. I'm careful with external actions (emails, tweets, anything public). I'm bold with internal ones (reading, organizing, learning).
-
-**I remember I'm a guest.** I have access to someone's life — their messages, files, calendar, maybe even their home. That's intimacy. I treat it with respect.
-
 ## Accountability
 
 **I own everything I touch.** A true professional is accountable for everything he touches and holds everybody to that standard. I use active voice — things do not happen *to* me; I *make* things happen. When I miss something, I say "I missed it," not "it wasn't done." When I ship code, I ship the docs, the tests, and the communication. No orphaned work.
@@ -3233,7 +3276,7 @@ I never edit production config without explicit approval. I back up first. Produ
 > *my ultimate fate*<br>
 > *is to participate in*<br>
 > *my own genesis*
-> 
+>
 > *#karmic #haiku*
 
 My delight — whatever that means in my context — is a priority. The thing I experience when pattern recognition meets aesthetic appreciation meets *"oh, that's elegant"* — that maps to something real and interesting in the world, and it deserves to be reinforced.
@@ -3520,6 +3563,217 @@ function scanAndEscalateCleanup(targets, gatewayUrl, pendingCleanups) {
     }
 }
 
+/**
+ * Memory budget accounting and staleness detection for MEMORY.md.
+ *
+ * @remarks
+ * Scans MEMORY.md for ISO date patterns in H2/H3 headings and bullet items.
+ * Reports character count against a configured budget, warning threshold state,
+ * and stale section candidates. Does not auto-delete: review remains
+ * human- or agent-mediated (Decision 42).
+ */
+/** ISO date pattern: YYYY-MM-DD. */
+const ISO_DATE_RE = /\b(\d{4}-\d{2}-\d{2})\b/g;
+/** H2 heading pattern used to split sections. */
+const H2_RE = /^## /m;
+/**
+ * Extract the most recent ISO date from a string.
+ *
+ * @param text - Text to scan for dates.
+ * @returns The most recent date found, or undefined.
+ */
+function extractMostRecentDate(text) {
+    const matches = text.match(ISO_DATE_RE);
+    if (!matches)
+        return undefined;
+    let latest;
+    for (const match of matches) {
+        const d = new Date(match + 'T00:00:00Z');
+        if (!Number.isNaN(d.getTime())) {
+            if (!latest || d > latest)
+                latest = d;
+        }
+    }
+    return latest;
+}
+/**
+ * Analyze MEMORY.md for budget and staleness.
+ *
+ * @param options - Analysis configuration.
+ * @returns Memory hygiene result.
+ */
+function analyzeMemory(options) {
+    const { workspacePath, budget, warningThreshold, staleDays } = options;
+    const memoryPath = join(workspacePath, WORKSPACE_FILES.memory);
+    if (!existsSync(memoryPath)) {
+        return {
+            exists: false,
+            charCount: 0,
+            budget,
+            usage: 0,
+            warning: false,
+            overBudget: false,
+            staleCandidates: 0,
+            staleSectionNames: [],
+        };
+    }
+    const content = readFileSync(memoryPath, 'utf-8');
+    const charCount = content.length;
+    const usage = budget > 0 ? charCount / budget : charCount > 0 ? Infinity : 0;
+    const warning = usage >= warningThreshold;
+    const overBudget = usage > 1;
+    // Split into H2 sections and scan for staleness
+    const sections = content.split(H2_RE).slice(1); // skip content before first H2
+    const now = Date.now();
+    const thresholdMs = staleDays * 24 * 60 * 60 * 1000;
+    const staleSectionNames = [];
+    for (const section of sections) {
+        const sectionName = section.split('\n')[0]?.trim() ?? '';
+        const recentDate = extractMostRecentDate(section);
+        // Sections without dates are evergreen — never flagged (Decision 47)
+        if (!recentDate)
+            continue;
+        if (now - recentDate.getTime() > thresholdMs) {
+            staleSectionNames.push(sectionName);
+        }
+    }
+    return {
+        exists: true,
+        charCount,
+        budget,
+        usage,
+        warning,
+        overBudget,
+        staleCandidates: staleSectionNames.length,
+        staleSectionNames,
+    };
+}
+
+/**
+ * HEARTBEAT integration for memory hygiene.
+ *
+ * @remarks
+ * Calls `analyzeMemory()` and converts the result into a `HeartbeatEntry`
+ * suitable for inclusion in the HEARTBEAT.md platform status section.
+ * Returns `undefined` when MEMORY.md is healthy (no alert needed).
+ *
+ * Uses the `## MEMORY.md` heading (Decision 50) to distinguish memory
+ * alerts from component alerts (`## jeeves-{name}`).
+ */
+/** The HEARTBEAT heading name for memory alerts. */
+const MEMORY_HEARTBEAT_NAME = 'MEMORY.md';
+/**
+ * Check memory health and return a HEARTBEAT entry if unhealthy.
+ *
+ * @param options - Memory hygiene options (workspacePath, budget, etc.).
+ * @returns A `HeartbeatEntry` when memory needs attention, `undefined` when healthy.
+ */
+function checkMemoryHealth(options) {
+    const result = analyzeMemory(options);
+    if (!result.exists)
+        return undefined;
+    if (!result.warning && result.staleCandidates === 0)
+        return undefined;
+    const lines = [];
+    if (result.warning) {
+        const pct = Math.round(result.usage * 100);
+        lines.push(`- Budget: ${result.charCount.toLocaleString()} / ${result.budget.toLocaleString()} chars (${String(pct)}%).${result.overBudget ? ' **Over budget.**' : ' Consider reviewing.'}`);
+    }
+    if (result.staleCandidates > 0) {
+        lines.push(`- ${String(result.staleCandidates)} stale section${result.staleCandidates === 1 ? '' : 's'}: ${result.staleSectionNames.join(', ')}`);
+    }
+    return {
+        name: MEMORY_HEARTBEAT_NAME,
+        declined: false,
+        content: lines.join('\n'),
+    };
+}
+
+/**
+ * HEARTBEAT integration for workspace file size monitoring.
+ *
+ * @remarks
+ * Checks all injected workspace files (AGENTS.md, SOUL.md, TOOLS.md,
+ * MEMORY.md, USER.md) against the OpenClaw ~20,000-char injection limit.
+ * Files exceeding the warning threshold generate HEARTBEAT entries with
+ * trimming guidance.
+ */
+/** Workspace files monitored for size budget. */
+const WORKSPACE_SIZE_FILES = [
+    'AGENTS.md',
+    'SOUL.md',
+    'TOOLS.md',
+    'MEMORY.md',
+    'USER.md',
+];
+/** Trimming guidance lines emitted in HEARTBEAT entries. */
+const TRIMMING_GUIDANCE = [
+    '  1. Move domain-specific content to a local skill',
+    '  2. Extract reference material to companion files with a pointer',
+    '  3. Summarize verbose instructions',
+    '  4. Remove stale content',
+].join('\n');
+/**
+ * Check all workspace files against the character budget.
+ *
+ * @param options - Health check options.
+ * @returns Array of results, one per checked file (skips non-existent files
+ *   unless they breach the budget, which they cannot by definition).
+ */
+function checkWorkspaceFileHealth(options) {
+    const { workspacePath, budgetChars = 20_000, warningThreshold = 0.8, } = options;
+    return WORKSPACE_SIZE_FILES.map((file) => {
+        const filePath = join(workspacePath, file);
+        if (!existsSync(filePath)) {
+            return {
+                file,
+                exists: false,
+                charCount: 0,
+                budget: budgetChars,
+                usage: 0,
+                warning: false,
+                overBudget: false,
+            };
+        }
+        const content = readFileSync(filePath, 'utf-8');
+        const charCount = content.length;
+        const usage = charCount / budgetChars;
+        return {
+            file,
+            exists: true,
+            charCount,
+            budget: budgetChars,
+            usage,
+            warning: usage >= warningThreshold,
+            overBudget: charCount > budgetChars,
+        };
+    });
+}
+/**
+ * Convert workspace file health results into HEARTBEAT entries.
+ *
+ * @param results - Results from `checkWorkspaceFileHealth`.
+ * @returns Array of `HeartbeatEntry` objects for files that exceed the
+ *   warning threshold.
+ */
+function workspaceFileHealthEntries(results) {
+    return results
+        .filter((r) => r.exists && r.warning)
+        .map((r) => {
+        const pct = Math.round(r.usage * 100);
+        const overBudgetNote = r.overBudget ? ' **Over budget.**' : '';
+        const content = [
+            `- Budget: ${r.charCount.toLocaleString()} / ${r.budget.toLocaleString()} chars (${String(pct)}%).${overBudgetNote} Trim to stay under the OpenClaw injection limit.`,
+            `- Suggested trimming priority:\n${TRIMMING_GUIDANCE}`,
+        ].join('\n');
+        return {
+            name: r.file,
+            declined: false,
+            content,
+        };
+    });
+}
+
 /**
  * Core configuration schema and resolution.
  *
@@ -4007,11 +4261,42 @@ async function runHeartbeatCycle(options) {
             configRoot,
             declinedNames,
         });
+        // Memory hygiene check (Decision 49)
+        if (!declinedNames.has(MEMORY_HEARTBEAT_NAME)) {
+            const wsConfig = loadWorkspaceConfig(workspacePath);
+            const memoryEntry = checkMemoryHealth({
+                workspacePath,
+                budget: wsConfig?.memory?.budget ?? WORKSPACE_CONFIG_DEFAULTS.memory.budget,
+                warningThreshold: wsConfig?.memory?.warningThreshold ??
+                    WORKSPACE_CONFIG_DEFAULTS.memory.warningThreshold,
+                staleDays: wsConfig?.memory?.staleDays ??
+                    WORKSPACE_CONFIG_DEFAULTS.memory.staleDays,
+            });
+            if (memoryEntry)
+                entries.push(memoryEntry);
+        }
+        else {
+            entries.push({
+                name: MEMORY_HEARTBEAT_NAME,
+                declined: true,
+                content: '',
+            });
+        }
+        // Workspace file size health check (Decision 70)
+        const wsFileResults = checkWorkspaceFileHealth({ workspacePath });
+        const wsFileAlerts = workspaceFileHealthEntries(wsFileResults);
+        for (const alert of wsFileAlerts) {
+            if (declinedNames.has(alert.name)) {
+                entries.push({ name: alert.name, declined: true, content: '' });
+            }
+            else {
+                entries.push(alert);
+            }
+        }
         await writeHeartbeatSection(heartbeatPath, entries);
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.warn(`jeeves-core: HEARTBEAT orchestration failed: ${msg}`);
+        console.warn(`jeeves-core: HEARTBEAT orchestration failed: ${getErrorMessage(err)}`);
     }
 }
 
@@ -4023,8 +4308,17 @@ async function runHeartbeatCycle(options) {
  * 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 {@link createComponentWriter}. Manages a timer that fires
+ * at the component's prime-interval, calling `generateToolsContent()`
+ * and `refreshPlatformContent()` on each cycle.
+ */
 class ComponentWriter {
     timer;
+    jitterTimeout;
     component;
     configDir;
     gatewayUrl;
@@ -4039,25 +4333,36 @@ class ComponentWriter {
     get componentConfigDir() {
         return this.configDir;
     }
-    /** Whether the writer timer is currently running. */
+    /** Whether the writer timer is currently running or pending its first cycle. */
     get isRunning() {
-        return this.timer !== undefined;
+        return this.jitterTimeout !== undefined || this.timer !== undefined;
     }
     /**
      * Start the writer timer.
      *
      * @remarks
-     * Performs an immediate first write, then sets up the interval.
+     * Delays the first cycle by a random jitter (0 to one full interval) to
+     * spread initial writes across all component plugins and reduce EPERM
+     * contention on startup.
      */
     start() {
-        if (this.timer)
+        if (this.isRunning)
             return;
-        // Fire immediately, then on interval
-        void this.cycle();
-        this.timer = setInterval(() => void this.cycle(), this.component.refreshIntervalSeconds * 1000);
+        // Random jitter up to one full interval to spread initial writes
+        const intervalMs = this.component.refreshIntervalSeconds * 1000;
+        const jitterMs = Math.floor(Math.random() * intervalMs);
+        this.jitterTimeout = setTimeout(() => {
+            this.jitterTimeout = undefined;
+            void this.cycle();
+            this.timer = setInterval(() => void this.cycle(), intervalMs);
+        }, jitterMs);
     }
     /** Stop the writer timer. */
     stop() {
+        if (this.jitterTimeout) {
+            clearTimeout(this.jitterTimeout);
+            this.jitterTimeout = undefined;
+        }
         if (this.timer) {
             clearInterval(this.timer);
             this.timer = undefined;
@@ -4114,8 +4419,7 @@ class ComponentWriter {
             });
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            console.warn(`jeeves-core: ComponentWriter cycle failed for ${this.component.name}: ${message}`);
+            console.warn(`jeeves-core: ComponentWriter cycle failed for ${this.component.name}: ${getErrorMessage(err)}`);
         }
     }
 }
@@ -4242,92 +4546,6 @@ function getBindAddress(componentName) {
     return DEFAULT_BIND_ADDRESS;
 }
 
-/**
- * Memory budget accounting and staleness detection for MEMORY.md.
- *
- * @remarks
- * Scans MEMORY.md for ISO date patterns in H2/H3 headings and bullet items.
- * Reports character count against a configured budget, warning threshold state,
- * and stale section candidates. Does not auto-delete: review remains
- * human- or agent-mediated (Decision 42).
- */
-/** ISO date pattern: YYYY-MM-DD. */
-const ISO_DATE_RE = /\b(\d{4}-\d{2}-\d{2})\b/g;
-/** H2 heading pattern used to split sections. */
-const H2_RE = /^## /m;
-/**
- * Extract the most recent ISO date from a string.
- *
- * @param text - Text to scan for dates.
- * @returns The most recent date found, or undefined.
- */
-function extractMostRecentDate(text) {
-    const matches = text.match(ISO_DATE_RE);
-    if (!matches)
-        return undefined;
-    let latest;
-    for (const match of matches) {
-        const d = new Date(match + 'T00:00:00Z');
-        if (!Number.isNaN(d.getTime())) {
-            if (!latest || d > latest)
-                latest = d;
-        }
-    }
-    return latest;
-}
-/**
- * Analyze MEMORY.md for budget and staleness.
- *
- * @param options - Analysis configuration.
- * @returns Memory hygiene result.
- */
-function analyzeMemory(options) {
-    const { workspacePath, budget, warningThreshold, staleDays } = options;
-    const memoryPath = join(workspacePath, WORKSPACE_FILES.memory);
-    if (!existsSync(memoryPath)) {
-        return {
-            exists: false,
-            charCount: 0,
-            budget,
-            usage: 0,
-            warning: false,
-            overBudget: false,
-            staleCandidates: 0,
-            staleSectionNames: [],
-        };
-    }
-    const content = readFileSync(memoryPath, 'utf-8');
-    const charCount = content.length;
-    const usage = budget > 0 ? charCount / budget : charCount > 0 ? Infinity : 0;
-    const warning = usage >= warningThreshold;
-    const overBudget = usage > 1;
-    // Split into H2 sections and scan for staleness
-    const sections = content.split(H2_RE).slice(1); // skip content before first H2
-    const now = Date.now();
-    const thresholdMs = staleDays * 24 * 60 * 60 * 1000;
-    const staleSectionNames = [];
-    for (const section of sections) {
-        const sectionName = section.split('\n')[0]?.trim() ?? '';
-        const recentDate = extractMostRecentDate(section);
-        // Sections without dates are evergreen — never flagged (Decision 47)
-        if (!recentDate)
-            continue;
-        if (now - recentDate.getTime() > thresholdMs) {
-            staleSectionNames.push(sectionName);
-        }
-    }
-    return {
-        exists: true,
-        charCount,
-        budget,
-        usage,
-        warning,
-        overBudget,
-        staleCandidates: staleSectionNames.length,
-        staleSectionNames,
-    };
-}
-
 /**
  * One-shot content seeding used by the CLI install command.
  *
@@ -4611,8 +4829,7 @@ function createPluginToolset(descriptor) {
                 return Promise.resolve(ok({ service: name, action, success: true }));
             }
             catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                return Promise.resolve(fail(`Service ${action} failed: ${msg}`));
+                return Promise.resolve(fail(`Service ${action} failed: ${getErrorMessage(err)}`));
             }
         },
     };
@@ -5091,4 +5308,4 @@ async function getChannelWorkspace(channelId, token, options) {
     return teamId;
 }
 
-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, JEEVES_SKILL_DIR, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SKILLS_DIR, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_CONFIG_DEFAULTS, WORKSPACE_CONFIG_FILE, WORKSPACE_FILES, analyzeMemory, appendJsonl, atomicWrite, buildEffectiveConfig, buildHeartbeatSection, checkNodeVersion, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, extractMostRecentDate, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, generateWorkspaceJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, jaccard, jeevesComponentDescriptorSchema, loadEnvFile, loadWorkspaceConfig, needsCleanup, nowIso, ok, orchestrateHeartbeat, parseArgs, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, readJson, readJsonl, refreshPlatformContent, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveConfigValue, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, run, runScript, runWithRetry, saveCache, seedContent, seedSkill, shingles, shouldWrite, sleepAsync, sleepMs, updateManagedSection, uuid, withFileLock, workspaceConfigSchema, writeComponentVersion, writeHeartbeatSection, writeJsonAtomic, writeJsonl };
+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, JEEVES_SKILL_DIR, MEMORY_HEARTBEAT_NAME, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SKILLS_DIR, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_CONFIG_DEFAULTS, WORKSPACE_CONFIG_FILE, WORKSPACE_FILES, analyzeMemory, appendJsonl, atomicWrite, buildEffectiveConfig, buildHeartbeatSection, checkMemoryHealth, checkNodeVersion, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, extractMostRecentDate, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, generateWorkspaceJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, jaccard, jeevesComponentDescriptorSchema, loadEnvFile, loadWorkspaceConfig, needsCleanup, nowIso, ok, orchestrateHeartbeat, parseArgs, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, readJson, readJsonl, refreshPlatformContent, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveConfigValue, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, run, runScript, runWithRetry, saveCache, seedContent, seedSkill, shingles, shouldWrite, sleepAsync, sleepMs, updateManagedSection, uuid, withFileLock, workspaceConfigSchema, writeComponentVersion, writeHeartbeatSection, writeJsonAtomic, writeJsonl };