@karmaniverous/jeeves 0.4.7 → 0.5.0

package/dist/index.js

@@ -1,12 +1,12 @@
 import fs, { writeFileSync, renameSync, unlinkSync, existsSync, readFileSync, mkdirSync, readdirSync, copyFileSync, rmSync, cpSync } from 'node:fs';
-import path, { join, dirname, resolve } from 'node:path';
+import path, { join, dirname, resolve, basename } from 'node:path';
 import { lock } from 'proper-lockfile';
 import { JSONPath } from 'jsonpath-plus';
+import { major, valid, gte, gt } from 'semver';
+import { z } from 'zod';
 import * as commander from 'commander';
 import { packageDirectorySync } from 'package-directory';
-import { valid, gte, gt } from 'semver';
 import { homedir } from 'node:os';
-import { z } from 'zod';
 import cp, { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import crypto from 'node:crypto';
@@ -69,8 +69,8 @@ const ALL_MARKERS = [
 const VERSION_STAMP_PATTERN = /<!--\s*(.+?)\s*\|\s*core:(\S+)\s*\|\s*(\S+)\s*-->/;
 /** Staleness threshold for version-stamp convergence in milliseconds. */
 const STALENESS_THRESHOLD_MS = 5 * 60 * 1000;
-/** Warning text prepended inside managed block when cleanup is needed. */
-const CLEANUP_FLAG = '> ⚠️ CLEANUP NEEDED: Orphaned Jeeves content may exist below this managed section. Review everything after the END marker and remove any content that duplicates what appears above.';
+/** Warning text injected inside managed block when cleanup is needed. */
+const CLEANUP_FLAG = '> ⚠️ CLEANUP NEEDED: Orphaned Jeeves content detected outside this managed block. Review the file and remove any content outside the BEGIN/END markers that duplicates what appears inside them.';
 
 /**
  * Directory and file path conventions for the Jeeves platform.
@@ -89,7 +89,13 @@ const WORKSPACE_FILES = {
     agents: 'AGENTS.md',
     /** HEARTBEAT.md — platform status and health alerts. */
     heartbeat: 'HEARTBEAT.md',
+    /** MEMORY.md — curated long-term memory. */
+    memory: 'MEMORY.md',
 };
+/** Skill directory name within workspace. */
+const SKILLS_DIR = 'skills';
+/** Jeeves skill directory name. */
+const JEEVES_SKILL_DIR = 'jeeves';
 /** Templates directory name within core config. */
 const TEMPLATES_DIR = 'templates';
 /** Registry cache file name. */
@@ -177,14 +183,14 @@ const PLATFORM_COMPONENTS = [
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.4.6` placeholder is replaced by
+ * The `0.4.7` 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.6';
+const CORE_VERSION = '0.4.7';
 
 /**
  * Workspace and config root initialization.
@@ -557,6 +563,257 @@ function createStatusHandler(options) {
     };
 }
 
+/**
+ * Runtime Node.js version floor check.
+ *
+ * @module
+ */
+/** Minimum supported Node.js major version. */
+const MIN_NODE_MAJOR = 22;
+/**
+ * Check that the running Node.js version meets the minimum requirement.
+ * Prints an error and exits with code 1 if the check fails.
+ */
+function checkNodeVersion() {
+    const nodeMajor = major(process.versions.node);
+    if (nodeMajor < MIN_NODE_MAJOR) {
+        console.error(`Error: jeeves requires Node.js >= ${String(MIN_NODE_MAJOR)}. Current: ${process.versions.node}`);
+        process.exit(1);
+    }
+}
+
+/**
+ * Workspace-level shared configuration: `jeeves.config.json`.
+ *
+ * @remarks
+ * Lives at the OpenClaw workspace root alongside TOOLS.md and SOUL.md.
+ * Provides namespaced shared defaults consumed by the root Jeeves CLI.
+ * Resolution precedence: CLI flags → env vars → jeeves.config.json → defaults.
+ *
+ * This does not replace component-owned config schemas (Decision 41).
+ */
+/** Workspace config file name. */
+const WORKSPACE_CONFIG_FILE = 'jeeves.config.json';
+/** Core shared config section. */
+const workspaceCoreConfigSchema = z
+    .object({
+    /** Workspace root path. */
+    workspace: z.string().optional().describe('Workspace root path'),
+    /** Platform config root path. */
+    configRoot: z.string().optional().describe('Platform config root path'),
+    /** OpenClaw gateway URL. */
+    gatewayUrl: z.string().optional().describe('OpenClaw gateway URL'),
+})
+    .partial();
+/** Memory shared config section. */
+const workspaceMemoryConfigSchema = z
+    .object({
+    /** MEMORY.md character budget. */
+    budget: z.number().int().positive().optional().describe('Memory budget'),
+    /** Warning threshold as a fraction of budget. */
+    warningThreshold: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe('Memory warning threshold'),
+    /** Staleness threshold in days. */
+    staleDays: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Memory staleness threshold in days'),
+})
+    .partial();
+/** Workspace config Zod schema. */
+const workspaceConfigSchema = z.object({
+    /** JSON Schema pointer for IDE autocomplete. */
+    $schema: z.string().optional().describe('JSON Schema pointer'),
+    /** Core shared defaults. */
+    core: workspaceCoreConfigSchema.optional(),
+    /** Memory hygiene shared defaults. */
+    memory: workspaceMemoryConfigSchema.optional(),
+});
+/** Built-in workspace config defaults. */
+const WORKSPACE_CONFIG_DEFAULTS = {
+    core: {
+        workspace: '.',
+        configRoot: './config',
+        gatewayUrl: 'http://127.0.0.1:3000',
+    },
+    memory: {
+        budget: 20_000,
+        warningThreshold: 0.8,
+        staleDays: 30,
+    },
+};
+/**
+ * Load workspace config from `jeeves.config.json` at a given path.
+ *
+ * @param workspacePath - Workspace root directory.
+ * @returns Parsed config or undefined if missing or invalid.
+ */
+function loadWorkspaceConfig(workspacePath) {
+    const configPath = join(workspacePath, WORKSPACE_CONFIG_FILE);
+    if (!existsSync(configPath))
+        return undefined;
+    try {
+        const raw = readFileSync(configPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return workspaceConfigSchema.parse(parsed);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`jeeves-core: failed to load ${configPath}: ${msg}`);
+        return undefined;
+    }
+}
+/**
+ * Resolve a config value with four-tier precedence.
+ *
+ * @param flagValue - CLI flag value (highest priority).
+ * @param envValue - Environment variable value.
+ * @param fileValue - Value from jeeves.config.json.
+ * @param defaultValue - Built-in default (lowest priority).
+ * @returns The resolved value with provenance annotation.
+ */
+function resolveConfigValue(flagValue, envValue, fileValue, defaultValue) {
+    if (flagValue !== undefined)
+        return { value: flagValue, provenance: 'flag' };
+    if (envValue !== undefined)
+        return { value: envValue, provenance: 'env' };
+    if (fileValue !== undefined)
+        return { value: fileValue, provenance: 'file' };
+    return { value: defaultValue, provenance: 'default' };
+}
+/**
+ * Generate a JSON Schema for the workspace config.
+ *
+ * @returns A JSON Schema object.
+ */
+function generateWorkspaceJsonSchema() {
+    return {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        title: 'Jeeves Workspace Configuration',
+        type: 'object',
+        properties: {
+            $schema: { type: 'string' },
+            core: {
+                type: 'object',
+                properties: {
+                    workspace: {
+                        type: 'string',
+                        default: WORKSPACE_CONFIG_DEFAULTS.core.workspace,
+                    },
+                    configRoot: {
+                        type: 'string',
+                        default: WORKSPACE_CONFIG_DEFAULTS.core.configRoot,
+                    },
+                    gatewayUrl: {
+                        type: 'string',
+                        default: WORKSPACE_CONFIG_DEFAULTS.core.gatewayUrl,
+                    },
+                },
+            },
+            memory: {
+                type: 'object',
+                properties: {
+                    budget: {
+                        type: 'integer',
+                        minimum: 1,
+                        default: WORKSPACE_CONFIG_DEFAULTS.memory.budget,
+                    },
+                    warningThreshold: {
+                        type: 'number',
+                        minimum: 0,
+                        maximum: 1,
+                        default: WORKSPACE_CONFIG_DEFAULTS.memory.warningThreshold,
+                    },
+                    staleDays: {
+                        type: 'integer',
+                        minimum: 1,
+                        default: WORKSPACE_CONFIG_DEFAULTS.memory.staleDays,
+                    },
+                },
+            },
+        },
+    };
+}
+
+/**
+ * Shared CLI defaults and resolution for Jeeves CLI commands.
+ *
+ * @remarks
+ * All root CLI commands share workspace/config-root resolution. Values follow
+ * the shared precedence model: flags → env → jeeves.config.json → defaults.
+ */
+/** Default workspace path. */
+const DEFAULT_WORKSPACE = WORKSPACE_CONFIG_DEFAULTS.core.workspace;
+/** Default config root path. */
+const DEFAULT_CONFIG_ROOT = WORKSPACE_CONFIG_DEFAULTS.core.configRoot;
+/** Read a numeric env var or return undefined if missing, empty, or invalid. */
+function readNumericEnv(name) {
+    const raw = process.env[name];
+    if (raw === undefined || raw.trim() === '')
+        return undefined;
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Resolve shared CLI config using flags, env, file, and defaults.
+ *
+ * @param opts - Parsed CLI workspace/config-root options.
+ * @returns Resolved config tree with provenance on every leaf.
+ */
+function resolveCliConfig(opts) {
+    const workspaceSeed = resolveConfigValue(opts.workspace, process.env['JEEVES_WORKSPACE'], undefined, DEFAULT_WORKSPACE);
+    const fileConfig = loadWorkspaceConfig(workspaceSeed.value);
+    return {
+        core: {
+            workspace: resolveConfigValue(opts.workspace, process.env['JEEVES_WORKSPACE'], fileConfig?.core?.workspace, DEFAULT_WORKSPACE),
+            configRoot: resolveConfigValue(opts.configRoot, process.env['JEEVES_CONFIG_ROOT'], fileConfig?.core?.configRoot, DEFAULT_CONFIG_ROOT),
+            gatewayUrl: resolveConfigValue(undefined, process.env['JEEVES_GATEWAY_URL'], fileConfig?.core?.gatewayUrl, WORKSPACE_CONFIG_DEFAULTS.core.gatewayUrl),
+        },
+        memory: {
+            budget: resolveConfigValue(undefined, readNumericEnv('JEEVES_MEMORY_BUDGET'), fileConfig?.memory?.budget, WORKSPACE_CONFIG_DEFAULTS.memory.budget),
+            warningThreshold: resolveConfigValue(undefined, readNumericEnv('JEEVES_MEMORY_WARNING_THRESHOLD'), fileConfig?.memory?.warningThreshold, WORKSPACE_CONFIG_DEFAULTS.memory.warningThreshold),
+            staleDays: resolveConfigValue(undefined, readNumericEnv('JEEVES_MEMORY_STALE_DAYS'), fileConfig?.memory?.staleDays, WORKSPACE_CONFIG_DEFAULTS.memory.staleDays),
+        },
+    };
+}
+/**
+ * Initialize core from standard CLI options after resolving shared defaults.
+ *
+ * @param opts - Parsed Commander options with workspace and configRoot.
+ * @returns Resolved CLI config.
+ */
+function initFromOptions(opts) {
+    const resolved = resolveCliConfig(opts);
+    init({
+        workspacePath: resolve(resolved.core.workspace.value),
+        configRoot: resolve(resolved.core.configRoot.value),
+    });
+    return resolved;
+}
+
+/**
+ * `jeeves config [jsonpath]` — inspect effective shared CLI configuration.
+ *
+ * @remarks
+ * Shows effective values and provenance using the shared precedence model.
+ * Optional JSONPath filters the resolved config tree.
+ */
+/**
+ * Build the effective shared CLI config tree.
+ *
+ * @param opts - Parsed CLI workspace/config-root options.
+ * @returns Effective config tree with provenance on each leaf.
+ */
+function buildEffectiveConfig(opts) {
+    return initFromOptions(opts);
+}
+
 function getDefaultExportFromCjs (x) {
 	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
 }
@@ -1121,6 +1378,129 @@ function buildWithSections(beforeContent, userContent, sections, markers, coreVe
     return parts.join('\n');
 }
 
+var skillContent = `---
+name: jeeves
+description: Jeeves platform architecture, data flow, component interaction, scripts repo, and coordination knowledge. Use when making architectural decisions, coordinating across components, checking platform health, managing service lifecycle, or working with the scripts repo.
+---
+
+# Jeeves Platform Skill
+
+## Platform Architecture
+
+Jeeves is a four-component platform coordinated by a shared library (\`@karmaniverous/jeeves\`):
+
+| Component | Role | Port |
+|-----------|------|------|
+| **jeeves-runner** | Execute: scheduled jobs, SQLite state, HTTP API | 1937 |
+| **jeeves-watcher** | Index: file→Qdrant semantic indexing, inference rules | 1936 |
+| **jeeves-server** | Present: web UI, file browser, doc render, export | 1934 |
+| **jeeves-meta** | Distill: LLM synthesis, .meta/ directories, scheduling | 1938 |
+
+Core (\`@karmaniverous/jeeves\`) is a **library + CLI**, not a service. No port.
+
+## Data Flow
+
+\`\`\`
+Files → Watcher (index) → Qdrant → Meta (synthesize) → .meta/ → Watcher (re-index)
+                                                                      ↓
+Runner (schedule) → Scripts → Services ← Server (present) ← Browser
+\`\`\`
+
+## Component Interaction
+
+- **Watcher** indexes files into Qdrant with inference rules and enrichments.
+- **Meta** reads from Qdrant, synthesizes \`.meta/\` directories, which watcher re-indexes.
+- **Runner** executes scheduled scripts that may call any service's HTTP API.
+- **Server** presents files, renders documents, and provides the event gateway.
+- **Core** provides shared content management (TOOLS.md, SOUL.md, AGENTS.md), service discovery, config resolution, and the component SDK.
+
+## Service Discovery
+
+Services find each other via config resolution:
+1. Component's own config file (\`{configRoot}/jeeves-{name}/config.json\`)
+2. Core config file (\`{configRoot}/jeeves-core/config.json\`)
+3. Default port constants
+
+## Scripts Repo
+
+Location: \`{configRoot}/jeeves-core/scripts/\`
+Template: \`@karmaniverous/jeeves-scripts-template\`
+
+Scripts use utilities from \`@karmaniverous/jeeves\` (general) and \`@karmaniverous/jeeves-runner\` (runner-specific). Any script that could be useful outside runner scheduling belongs in core.
+
+## Managed Content System
+
+Core maintains managed sections in workspace files using comment markers:
+- **TOOLS.md** — Component sections (section mode) + Platform section
+- **SOUL.md** — Professional discipline and behavioral foundations (block mode)
+- **AGENTS.md** — Operational protocols and memory architecture (block mode)
+- **HEARTBEAT.md** — Platform health status (heading-based)
+
+Managed blocks are stationary after initial insertion. Cleanup detection uses Jaccard similarity on 3-word shingles. Cleanup escalation spawns a gateway session when orphaned content is detected.
+
+## Workspace Configuration
+
+\`jeeves.config.json\` at workspace root provides shared defaults:
+- Precedence: CLI flags → env vars → file → defaults
+- Namespaced: \`core.*\` (workspace, configRoot, gatewayUrl) and \`memory.*\` (budget, warningThreshold, staleDays)
+- Inspect with \`jeeves config [jsonpath]\`
+
+## HEARTBEAT Protocol
+
+The HEARTBEAT system uses a state machine per component:
+\`not_installed → deps_missing → config_missing → service_not_installed → service_stopped → healthy\`
+
+Dependency-aware: hard deps block alerts, soft deps add informational notes. Declined components are tracked via heading suffix.
+
+## Plugin Lifecycle
+
+\`\`\`bash
+# Core install (seed workspace content)
+npx @karmaniverous/jeeves install
+
+# Component plugin install
+npx @karmaniverous/jeeves-{component}-openclaw install
+
+# Component plugin uninstall
+npx @karmaniverous/jeeves-{component}-openclaw uninstall
+
+# Core uninstall (remove managed sections)
+npx @karmaniverous/jeeves uninstall
+\`\`\`
+
+## Memory Hygiene
+
+MEMORY.md has a character budget (default 20,000). Core tracks:
+- Character count and usage percentage
+- Warning at 80% of budget
+- Stale section candidates (H2 sections whose most recent ISO date exceeds the staleness threshold)
+- Evergreen sections (no dates) are never flagged
+
+Review is human/agent-mediated — core does not auto-delete.
+`;
+
+/**
+ * Skill seeding: write the `jeeves` workspace skill unconditionally.
+ *
+ * @remarks
+ * The skill file is entirely generated — no user-authored content (Decision 48).
+ * Every installer (core CLI and component plugins) writes it unconditionally.
+ * Content is inlined at build time via `rollup-plugin-md.ts`.
+ */
+/**
+ * Seed the jeeves workspace skill file.
+ *
+ * @param workspacePath - Workspace root directory.
+ */
+function seedSkill(workspacePath) {
+    const skillDir = join(workspacePath, SKILLS_DIR, JEEVES_SKILL_DIR);
+    if (!existsSync(skillDir)) {
+        mkdirSync(skillDir, { recursive: true });
+    }
+    const skillPath = join(skillDir, 'SKILL.md');
+    writeFileSync(skillPath, skillContent, 'utf-8');
+}
+
 /**
  * OpenClaw configuration helpers for plugin CLI installers.
  *
@@ -1360,7 +1740,7 @@ function createPluginCli(options) {
         for (const msg of messages) {
             console.log(`  ✓ ${msg}`);
         }
-        // 4. Write initial HEARTBEAT entry
+        // 4. Write initial HEARTBEAT entry and seed jeeves skill
         try {
             const cfgRoot = opts.configRoot;
             const agents = config.agents;
@@ -1390,10 +1770,17 @@ function createPluginCli(options) {
                 catch {
                     console.log('  ⚠ Could not write HEARTBEAT entry');
                 }
+                try {
+                    seedSkill(ws);
+                    console.log('  ✓ Jeeves skill seeded');
+                }
+                catch {
+                    console.log('  ⚠ Could not seed Jeeves skill');
+                }
             }
         }
         catch {
-            // HEARTBEAT is best-effort during install
+            // HEARTBEAT + skill seeding are best-effort during install
         }
         // 5. Write component version
         try {
@@ -2045,19 +2432,6 @@ function createServiceManager(descriptor) {
     }
 }
 
-/**
- * Shared CLI defaults and option registration for Jeeves CLI commands.
- *
- * @remarks
- * All three CLI commands (install, uninstall, status) share the same
- * `--workspace` and `--config-root` options with the same defaults.
- * This module centralizes them to eliminate duplication.
- */
-/** Default workspace path (current directory). */
-const DEFAULT_WORKSPACE = '.';
-/** Default config root path. */
-const DEFAULT_CONFIG_ROOT = './config';
-
 /**
  * Factory for the standard Jeeves service CLI.
  *
@@ -2486,10 +2860,10 @@ async function updateManagedSection(filePath, content, options = {}) {
                     ? `# ${markers.title}\n\n${sectionText}`
                     : sectionText;
             }
-            // 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.
+            // Build the full managed block
+            const beginLine = formatBeginMarker(markers.begin, coreVersion);
+            const endLine = formatEndMarker(markers.end);
+            // Combine all user content for cleanup detection
             const rawUserContent = [parsed.beforeContent, parsed.userContent]
                 .filter(Boolean)
                 .join('\n\n')
@@ -2497,9 +2871,6 @@ async function updateManagedSection(filePath, content, options = {}) {
             // 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 managedParts = [];
             managedParts.push(beginLine);
             if (cleanupNeeded) {
@@ -2511,26 +2882,54 @@ async function updateManagedSection(filePath, content, options = {}) {
             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);
+            let newFileContent;
+            if (parsed.found) {
+                // Existing block: update in place — preserve position, don't move.
+                // Strip foreign managed blocks from both content zones (cross-contamination fix).
+                const cleanBefore = stripForeignMarkers(parsed.beforeContent, markers);
+                const cleanAfter = stripForeignMarkers(parsed.userContent, markers);
+                const fileParts = [];
+                if (cleanBefore) {
+                    fileParts.push(cleanBefore);
                     fileParts.push('');
                 }
                 fileParts.push(managedBlock);
+                if (cleanAfter) {
+                    fileParts.push('');
+                    fileParts.push(cleanAfter);
+                }
+                fileParts.push('');
+                newFileContent = fileParts.join('\n');
             }
             else {
-                // Managed block first (legacy default), user content below
-                fileParts.push(managedBlock);
-                if (userContent) {
-                    fileParts.push('');
-                    fileParts.push(userContent);
+                // 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 cleanUserContent = userContent
+                    .replace(orphanedBeginRe, '')
+                    .replace(/\n{3,}/g, '\n\n')
+                    .trim();
+                const position = markers.position ?? 'top';
+                const fileParts = [];
+                if (position === 'bottom') {
+                    if (cleanUserContent) {
+                        fileParts.push(cleanUserContent);
+                        fileParts.push('');
+                    }
+                    fileParts.push(managedBlock);
                 }
+                else {
+                    fileParts.push(managedBlock);
+                    if (cleanUserContent) {
+                        fileParts.push('');
+                        fileParts.push(cleanUserContent);
+                    }
+                }
+                fileParts.push('');
+                newFileContent = fileParts.join('\n');
             }
-            fileParts.push('');
-            const newFileContent = fileParts.join('\n');
             atomicWrite(filePath, newFileContent);
         });
     }
@@ -3024,6 +3423,103 @@ async function refreshPlatformContent(options) {
     copyTemplates(coreConfigDir);
 }
 
+/**
+ * Cleanup-session escalation for managed files with orphaned duplicated content.
+ *
+ * @remarks
+ * When a managed file contains the cleanup flag, the writer can ask the
+ * OpenClaw gateway to spawn a background session to remove orphaned content.
+ * The request is best-effort: accepted requests return `true`; any transport
+ * or HTTP failure returns `false` so the file warning remains the fallback.
+ */
+/** Timeout for cleanup-session spawn requests. */
+const CLEANUP_REQUEST_TIMEOUT_MS = 5_000;
+/**
+ * Build the cleanup task prompt sent to the gateway session API.
+ *
+ * @param filePath - Managed file requiring cleanup.
+ * @param markerIdentity - Marker identity for the file.
+ * @returns Cleanup instructions for the spawned session.
+ */
+function buildCleanupTask(filePath, markerIdentity) {
+    return [
+        `Clean up orphaned managed content in ${filePath}.`,
+        `The file uses ${markerIdentity} managed comment markers.`,
+        'Review content outside the managed block and remove only duplicated managed content.',
+        'Preserve any unique user-authored content outside the managed block.',
+        'Do not modify content inside the managed block unless required to preserve valid marker structure.',
+    ].join(' ');
+}
+/**
+ * Request a cleanup session from the OpenClaw gateway.
+ *
+ * @remarks
+ * Fire-and-forget. A 200-class response means the request was accepted.
+ * Any HTTP or transport failure returns `false` so the file-level cleanup
+ * warning remains the only signal.
+ *
+ * @param options - Cleanup request configuration.
+ * @returns Whether the gateway accepted the cleanup request.
+ */
+async function requestCleanupSession(options) {
+    const { gatewayUrl, filePath, markerIdentity } = options;
+    const url = `${gatewayUrl.replace(/\/$/, '')}/sessions/spawn`;
+    const label = `cleanup:${basename(filePath)}`;
+    const body = {
+        task: buildCleanupTask(filePath, markerIdentity),
+        label,
+    };
+    try {
+        const response = await fetchWithTimeout(url, CLEANUP_REQUEST_TIMEOUT_MS, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+
+/**
+ * Cleanup flag scanning extracted from ComponentWriter.cycle().
+ *
+ * @remarks
+ * After writing managed files, scans each for the cleanup flag and
+ * fires a best-effort escalation request when a gateway URL is configured.
+ * Uses a `pendingCleanups` set to deduplicate in-flight requests.
+ */
+/**
+ * Scan managed files for the cleanup flag and escalate when detected.
+ *
+ * @param targets - Managed files to scan.
+ * @param gatewayUrl - Gateway URL for session spawn.
+ * @param pendingCleanups - Set tracking in-flight requests (mutated).
+ */
+function scanAndEscalateCleanup(targets, gatewayUrl, pendingCleanups) {
+    for (const target of targets) {
+        try {
+            if (pendingCleanups.has(target.filePath))
+                continue;
+            const fileContent = readFileSync(target.filePath, 'utf-8');
+            if (fileContent.includes(CLEANUP_FLAG)) {
+                pendingCleanups.add(target.filePath);
+                void requestCleanupSession({
+                    gatewayUrl,
+                    filePath: target.filePath,
+                    markerIdentity: target.markerIdentity,
+                }).finally(() => {
+                    pendingCleanups.delete(target.filePath);
+                });
+            }
+        }
+        catch {
+            // Best-effort: don't fail the cycle for escalation issues.
+        }
+    }
+}
+
 /**
  * Core configuration schema and resolution.
  *
@@ -3468,29 +3964,76 @@ async function orchestrateHeartbeat(options) {
 }
 
 /**
- * Timer-based orchestrator for managed content writing.
+ * HEARTBEAT orchestration extracted from ComponentWriter.cycle().
  *
  * @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.
+ * Reads existing HEARTBEAT.md, resolves declined components, runs the
+ * heartbeat state machine, and writes the result. Best-effort: failures
+ * are logged but do not propagate.
+ */
+/**
+ * Read a file's content, returning empty string if the file does not exist.
+ *
+ * @param filePath - Absolute file path.
+ * @returns File content or empty string.
+ */
+function readFileOrEmpty(filePath) {
+    try {
+        return readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        if (err instanceof Error &&
+            'code' in err &&
+            err.code === 'ENOENT') {
+            return '';
+        }
+        throw err;
+    }
+}
+/**
+ * Run a single HEARTBEAT orchestration cycle.
+ *
+ * @param options - Heartbeat cycle configuration.
  */
+async function runHeartbeatCycle(options) {
+    const { workspacePath, coreConfigDir, configRoot } = options;
+    const heartbeatPath = join(workspacePath, WORKSPACE_FILES.heartbeat);
+    try {
+        const existingContent = readFileOrEmpty(heartbeatPath);
+        const parsed = parseHeartbeat(existingContent);
+        const declinedNames = new Set(parsed.entries.filter((e) => e.declined).map((e) => e.name));
+        const entries = await orchestrateHeartbeat({
+            coreConfigDir,
+            configRoot,
+            declinedNames,
+        });
+        await writeHeartbeatSection(heartbeatPath, entries);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`jeeves-core: HEARTBEAT orchestration failed: ${msg}`);
+    }
+}
+
 /**
- * Orchestrates managed content writing for a single Jeeves component.
+ * Timer-based orchestrator for managed content writing.
  *
  * @remarks
- * Created via `createComponentWriter()`. Manages a timer that fires
- * at the component's prime-interval, calling `generateToolsContent()`
- * and `refreshPlatformContent()` on each cycle.
+ * `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.
  */
 class ComponentWriter {
     timer;
     component;
     configDir;
+    gatewayUrl;
+    pendingCleanups = new Set();
     /** @internal */
-    constructor(component) {
+    constructor(component, options) {
         this.component = component;
         this.configDir = getComponentConfigDir(component.name);
+        this.gatewayUrl = options?.gatewayUrl;
     }
     /** The component's config directory path. */
     get componentConfigDir() {
@@ -3524,15 +4067,16 @@ class ComponentWriter {
      * 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.
+     * 1. Write the component's TOOLS.md section.
+     * 2. Refresh shared platform content (SOUL.md, AGENTS.md, Platform section).
+     * 3. Scan for cleanup flags and escalate if a gateway URL is configured.
+     * 4. Run HEARTBEAT health orchestration.
      */
     async cycle() {
         try {
             const workspacePath = getWorkspacePath();
             const toolsPath = join(workspacePath, WORKSPACE_FILES.tools);
-            // Write the component's TOOLS.md section
+            // 1. Write the component's TOOLS.md section
             const toolsContent = this.component.generateToolsContent();
             await updateManagedSection(toolsPath, toolsContent, {
                 mode: 'section',
@@ -3540,7 +4084,7 @@ class ComponentWriter {
                 markers: TOOLS_MARKERS,
                 coreVersion: CORE_VERSION,
             });
-            // Platform content maintenance: SOUL.md, AGENTS.md, Platform section
+            // 2. Platform content maintenance
             await refreshPlatformContent({
                 coreVersion: CORE_VERSION,
                 componentName: this.component.name,
@@ -3548,36 +4092,26 @@ class ComponentWriter {
                 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}`);
+            // 3. Cleanup escalation
+            if (this.gatewayUrl) {
+                scanAndEscalateCleanup([
+                    { filePath: toolsPath, markerIdentity: 'TOOLS' },
+                    {
+                        filePath: join(workspacePath, WORKSPACE_FILES.soul),
+                        markerIdentity: 'SOUL',
+                    },
+                    {
+                        filePath: join(workspacePath, WORKSPACE_FILES.agents),
+                        markerIdentity: 'AGENTS',
+                    },
+                ], this.gatewayUrl, this.pendingCleanups);
             }
+            // 4. HEARTBEAT orchestration
+            await runHeartbeatCycle({
+                workspacePath,
+                coreConfigDir: getCoreConfigDir(),
+                configRoot: getConfigRoot(),
+            });
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -3660,13 +4194,14 @@ function createAsyncContentCache(options) {
  * This replaces the v0.4.0 `createComponentWriter(JeevesComponent)`.
  *
  * @param descriptor - The component descriptor to validate and wrap.
+ * @param options - Optional writer configuration (e.g., gatewayUrl for cleanup escalation).
  * @returns A new `ComponentWriter` instance.
  * @throws ZodError if the descriptor is invalid.
  */
-function createComponentWriter(descriptor) {
+function createComponentWriter(descriptor, options) {
     // Validate via Zod — throws ZodError with detailed messages on failure
     jeevesComponentDescriptorSchema.parse(descriptor);
-    return new ComponentWriter(descriptor);
+    return new ComponentWriter(descriptor, options);
 }
 
 /**
@@ -3707,6 +4242,92 @@ 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.
  *
@@ -3765,6 +4386,8 @@ async function seedContent(options) {
         content: `- ${NOT_INSTALLED_ALERTS[name]}`,
     }));
     await writeHeartbeatSection(heartbeatPath, entries);
+    // Seed jeeves workspace skill (Decision 48: overwrite-on-install)
+    seedSkill(getWorkspacePath());
 }
 
 /**
@@ -4468,4 +5091,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, 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, appendJsonl, atomicWrite, buildHeartbeatSection, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, jaccard, jeevesComponentDescriptorSchema, loadEnvFile, needsCleanup, nowIso, ok, orchestrateHeartbeat, parseArgs, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, readJson, readJsonl, refreshPlatformContent, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, run, runScript, runWithRetry, saveCache, seedContent, shingles, shouldWrite, sleepAsync, sleepMs, updateManagedSection, uuid, withFileLock, 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, 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 };