@karmaniverous/jeeves 0.4.6 → 0.5.0

package/dist/index.js

@@ -1,14 +1,15 @@
-import { writeFileSync, renameSync, unlinkSync, existsSync, readFileSync, mkdirSync, rmSync, readdirSync, copyFileSync, cpSync } from 'node:fs';
-import { join, dirname, resolve } from 'node:path';
+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 { 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 { valid, gte, gt } from 'semver';
+import { packageDirectorySync } from 'package-directory';
 import { homedir } from 'node:os';
-import { z } from 'zod';
-import { execSync } from 'node:child_process';
+import cp, { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { packageDirectorySync } from 'package-directory';
+import crypto from 'node:crypto';
 
 /**
  * Comment markers for managed content blocks.
@@ -68,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.
@@ -88,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. */
@@ -176,14 +183,14 @@ const PLATFORM_COMPONENTS = [
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.4.5` 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.5';
+const CORE_VERSION = '0.4.7';
 
 /**
  * Workspace and config root initialization.
@@ -556,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;
 }
@@ -1120,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.
  *
@@ -1239,13 +1620,9 @@ function patchConfig(config, pluginId, mode) {
 }
 
 /**
- * Factory for the standard `-openclaw` plugin installer CLI.
+ * Internal helpers for the plugin installer CLI.
  *
- * @remarks
- * Produces a Commander program with `install` and `uninstall` commands
- * that handle the full plugin lifecycle: copy dist to extensions,
- * patch OpenClaw config, manage HEARTBEAT entries, and clean up
- * managed sections on uninstall.
+ * @module
  */
 /**
  * Derive a component name from a plugin ID.
@@ -1260,7 +1637,7 @@ function deriveComponentName(pluginId) {
     return pluginId.replace(/^jeeves-/, '').replace(/-openclaw$/, '');
 }
 /**
- * Copy all files from source directory to destination.
+ * Copy all files from source directory to destination, recursively.
  *
  * @param srcDir - Source directory.
  * @param destDir - Destination directory.
@@ -1294,6 +1671,12 @@ function readJsonFile(filePath) {
         return {};
     }
 }
+
+/**
+ * Factory for the standard `-openclaw` plugin installer CLI.
+ *
+ * @module
+ */
 /**
  * Create a standard plugin installer CLI program.
  *
@@ -1319,6 +1702,16 @@ function createPluginCli(options) {
         const extensionsDir = join(openClawHome, 'extensions', pluginId);
         console.log(`Copying dist to ${extensionsDir}...`);
         copyDistFiles(distDir, extensionsDir);
+        // Copy package.json and openclaw.plugin.json from package root
+        const pkgRoot = packageDirectorySync({ cwd: distDir });
+        if (pkgRoot) {
+            for (const file of ['package.json', 'openclaw.plugin.json']) {
+                const src = join(pkgRoot, file);
+                if (existsSync(src)) {
+                    copyFileSync(src, join(extensionsDir, file));
+                }
+            }
+        }
         console.log('  ✓ Dist files copied');
         // 2. Patch openclaw.json
         console.log('Patching OpenClaw config...');
@@ -1347,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;
@@ -1362,7 +1755,6 @@ function createPluginCli(options) {
                         : '';
                     const parsed = parseHeartbeat(existing);
                     const fullName = `jeeves-${componentName}`;
-                    // Only add if not already present
                     const hasEntry = parsed.entries.some((e) => e.name === fullName);
                     if (!hasEntry) {
                         parsed.entries.push({
@@ -1378,10 +1770,36 @@ 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 {
+            init({
+                workspacePath: opts.workspace ?? '.',
+                configRoot: opts.configRoot,
+            });
+            const pkgJsonPath = join(extensionsDir, 'package.json');
+            const pkgJson = readJsonFile(pkgJsonPath);
+            const pluginVersion = typeof pkgJson.version === 'string' ? pkgJson.version : undefined;
+            writeComponentVersion(getCoreConfigDir(), {
+                componentName,
+                pluginPackage,
+                pluginVersion,
+            });
+            console.log('  ✓ Component version written');
+        }
+        catch {
+            console.log('  ⚠ Could not write component version');
         }
         console.log();
         console.log(`✅ ${pluginPackage} installed.`);
@@ -1411,10 +1829,9 @@ function createPluginCli(options) {
         }
         // 3. Remove TOOLS.md section
         try {
-            const cfgRoot = opts.configRoot;
             const ws = opts.workspace;
             if (ws) {
-                init({ workspacePath: ws, configRoot: cfgRoot });
+                init({ workspacePath: ws, configRoot: opts.configRoot });
                 const sectionId = componentName.charAt(0).toUpperCase() + componentName.slice(1);
                 const toolsPath = join(ws, WORKSPACE_FILES.tools);
                 if (existsSync(toolsPath)) {
@@ -1431,10 +1848,9 @@ function createPluginCli(options) {
         }
         // 4. Remove component-versions.json entry
         try {
-            const cfgRoot = opts.configRoot;
             init({
                 workspacePath: opts.workspace ?? '.',
-                configRoot: cfgRoot,
+                configRoot: opts.configRoot,
             });
             removeComponentVersion(getCoreConfigDir(), componentName);
             console.log('  ✓ Component version entry removed');
@@ -1770,7 +2186,7 @@ function isExecError(err) {
  * (Windows), systemd (Linux), or launchd (macOS) based on platform.
  */
 /** Exec helper that returns stdout. */
-function run(cmd) {
+function run$1(cmd) {
     return execSync(cmd, {
         encoding: 'utf-8',
         timeout: 30_000,
@@ -1823,31 +2239,31 @@ function createWindowsManager(descriptor) {
             const cmdArgs = descriptor.startCommand(cfgPath);
             const appPath = cmdArgs[0];
             const appArgs = cmdArgs.slice(1).join(' ');
-            run(`nssm install ${svcName} ${appPath}`);
+            run$1(`nssm install ${svcName} ${appPath}`);
             if (appArgs) {
-                run(`nssm set ${svcName} AppParameters ${appArgs}`);
+                run$1(`nssm set ${svcName} AppParameters ${appArgs}`);
             }
-            run(`nssm set ${svcName} AppStdout ${join(homedir(), `${svcName}.log`)}`);
-            run(`nssm set ${svcName} AppStderr ${join(homedir(), `${svcName}.log`)}`);
-            run(`nssm set ${svcName} AppRotateFiles 1`);
-            run(`nssm set ${svcName} AppRotateBytes 1048576`);
+            run$1(`nssm set ${svcName} AppStdout ${join(homedir(), `${svcName}.log`)}`);
+            run$1(`nssm set ${svcName} AppStderr ${join(homedir(), `${svcName}.log`)}`);
+            run$1(`nssm set ${svcName} AppRotateFiles 1`);
+            run$1(`nssm set ${svcName} AppRotateBytes 1048576`);
         },
         uninstall(options) {
             const svcName = resolveServiceName(descriptor, options);
             runQuiet(`nssm stop ${svcName}`);
-            run(`nssm remove ${svcName} confirm`);
+            run$1(`nssm remove ${svcName} confirm`);
         },
         start(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`nssm start ${svcName}`);
+            run$1(`nssm start ${svcName}`);
         },
         stop(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`nssm stop ${svcName}`);
+            run$1(`nssm stop ${svcName}`);
         },
         restart(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`nssm restart ${svcName}`);
+            run$1(`nssm restart ${svcName}`);
         },
         status(options) {
             const svcName = resolveServiceName(descriptor, options);
@@ -1892,8 +2308,8 @@ function createLinuxManager(descriptor) {
             const cmdArgs = descriptor.startCommand(cfgPath);
             mkdirSync(unitDir, { recursive: true });
             writeFileSync(unitPath(svcName), buildSystemdUnit(svcName, cmdArgs));
-            run('systemctl --user daemon-reload');
-            run(`systemctl --user enable ${svcName}.service`);
+            run$1('systemctl --user daemon-reload');
+            run$1(`systemctl --user enable ${svcName}.service`);
         },
         uninstall(options) {
             const svcName = resolveServiceName(descriptor, options);
@@ -1906,15 +2322,15 @@ function createLinuxManager(descriptor) {
         },
         start(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`systemctl --user start ${svcName}.service`);
+            run$1(`systemctl --user start ${svcName}.service`);
         },
         stop(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`systemctl --user stop ${svcName}.service`);
+            run$1(`systemctl --user stop ${svcName}.service`);
         },
         restart(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`systemctl --user restart ${svcName}.service`);
+            run$1(`systemctl --user restart ${svcName}.service`);
         },
         status(options) {
             const svcName = resolveServiceName(descriptor, options);
@@ -1978,16 +2394,16 @@ function createMacOSManager(descriptor) {
         },
         start(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`launchctl load ${plistPath(svcName)}`);
+            run$1(`launchctl load ${plistPath(svcName)}`);
         },
         stop(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`launchctl unload ${plistPath(svcName)}`);
+            run$1(`launchctl unload ${plistPath(svcName)}`);
         },
         restart(options) {
             const svcName = resolveServiceName(descriptor, options);
             runQuiet(`launchctl unload ${plistPath(svcName)}`);
-            run(`launchctl load ${plistPath(svcName)}`);
+            run$1(`launchctl load ${plistPath(svcName)}`);
         },
         status(options) {
             const svcName = resolveServiceName(descriptor, options);
@@ -2016,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.
  *
@@ -2457,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')
@@ -2468,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) {
@@ -2482,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);
         });
     }
@@ -2995,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.
  *
@@ -3439,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;
+    }
+}
 /**
- * Orchestrates managed content writing for a single Jeeves component.
+ * 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}`);
+    }
+}
+
+/**
+ * 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() {
@@ -3495,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',
@@ -3511,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,
@@ -3519,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);
@@ -3631,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);
 }
 
 /**
@@ -3678,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.
  *
@@ -3736,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());
 }
 
 /**
@@ -3967,6 +4619,33 @@ function createPluginToolset(descriptor) {
     return [statusTool, configTool, configApplyTool, serviceTool];
 }
 
+/**
+ * Resolve the version of a package from its `import.meta.url`.
+ *
+ * @module
+ */
+/**
+ * Get the version string from the nearest `package.json` relative to the
+ * caller's module URL.
+ *
+ * @param importMetaUrl - The `import.meta.url` of the calling module.
+ * @returns The `version` field, or `'unknown'` on any error.
+ */
+function getPackageVersion(importMetaUrl) {
+    try {
+        const dir = fileURLToPath(importMetaUrl);
+        const pkgRoot = packageDirectorySync({ cwd: dir });
+        if (!pkgRoot)
+            return 'unknown';
+        const raw = readFileSync(join(pkgRoot, 'package.json'), 'utf-8');
+        const pkg = JSON.parse(raw);
+        return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+
 /**
  * Plugin resolution helpers for the OpenClaw plugin SDK.
  *
@@ -4038,4 +4717,378 @@ function resolveOptionalPluginSetting(api, pluginId, key, envVar) {
     return undefined;
 }
 
-export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_BIND_ADDRESS, DEFAULT_CORE_VERSION, DEFAULT_PORTS, HEARTBEAT_HEADING, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, atomicWrite, buildHeartbeatSection, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, getBindAddress, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, jaccard, jeevesComponentDescriptorSchema, needsCleanup, ok, orchestrateHeartbeat, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, refreshPlatformContent, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, seedContent, shingles, shouldWrite, updateManagedSection, withFileLock, writeComponentVersion, writeHeartbeatSection };
+/**
+ * Shared filesystem utilities for runner job scripts.
+ *
+ * @module
+ */
+// ========== Time & UUID ==========
+/** Return current time as ISO 8601 string. */
+function nowIso() {
+    return new Date().toISOString();
+}
+/** Generate a random UUID v4. */
+function uuid() {
+    return crypto.randomUUID();
+}
+// ========== File System ==========
+/** Create a directory and any missing parents. */
+function ensureDir(p) {
+    fs.mkdirSync(p, { recursive: true });
+}
+/** Read and parse a JSON file, returning `fallback` on any error. */
+function readJson(p, fallback) {
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return fallback;
+    }
+}
+/** Atomically write a JSON file (write to .tmp, then rename). */
+function writeJsonAtomic(p, obj) {
+    ensureDir(path.dirname(p));
+    const tmp = p + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + '\n', 'utf8');
+    fs.renameSync(tmp, p);
+}
+/** Append a single JSON object as a JSONL line. */
+function appendJsonl(p, obj) {
+    ensureDir(path.dirname(p));
+    fs.appendFileSync(p, JSON.stringify(obj) + '\n', 'utf8');
+}
+/** Read a JSONL file into an array of parsed objects. */
+function readJsonl(p) {
+    try {
+        const content = fs.readFileSync(p, 'utf8');
+        return content
+            .split('\n')
+            .filter((line) => line.trim())
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+/** Overwrite a file with an array of objects as JSONL. */
+function writeJsonl(p, entries) {
+    ensureDir(path.dirname(p));
+    const content = entries.map((e) => JSON.stringify(e)).join('\n') + '\n';
+    fs.writeFileSync(p, content, 'utf8');
+}
+// ========== Process Control ==========
+/** Synchronous sleep using Atomics.wait. */
+function sleepMs(ms) {
+    const sab = new SharedArrayBuffer(4);
+    const ia = new Int32Array(sab);
+    Atomics.wait(ia, 0, 0, ms);
+}
+/** Async sleep via setTimeout. */
+function sleepAsync(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+// ========== Env File Loader ==========
+/** Load a .env-style key=value file into process.env. */
+function loadEnvFile(envPath) {
+    if (!fs.existsSync(envPath))
+        throw new Error(`Missing secret file: ${envPath}`);
+    for (const line of fs.readFileSync(envPath, 'utf8').split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const idx = trimmed.indexOf('=');
+        if (idx > 0) {
+            process.env[trimmed.slice(0, idx).trim()] = trimmed.slice(idx + 1).trim();
+        }
+    }
+}
+// ========== CLI Arg Parsing ==========
+/** Parse --key=value arguments from argv into a record. */
+function parseArgs(argv = process.argv.slice(2)) {
+    const args = {};
+    for (const arg of argv) {
+        const match = /^--([^=]+)=(.*)$/.exec(arg);
+        if (match) {
+            args[match[1]] = match[2];
+        }
+    }
+    return args;
+}
+/** Get the value following a named flag, or a default. */
+function getArg(argv, name, defaultValue) {
+    const i = argv.indexOf(name);
+    if (i >= 0 && i + 1 < argv.length)
+        return argv[i + 1];
+    return defaultValue;
+}
+
+/**
+ * Google API auth helpers for runner job scripts.
+ * Supports OAuth refresh tokens and service account impersonation.
+ *
+ * @module
+ */
+// ========== JWT / Service Account ==========
+function base64url(buf) {
+    return buf
+        .toString('base64')
+        .replace(/=/g, '')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_');
+}
+function createJwt(serviceAccount, scopes, subject) {
+    const now = Math.floor(Date.now() / 1000);
+    const header = { alg: 'RS256', typ: 'JWT' };
+    const payload = {
+        iss: serviceAccount.client_email,
+        sub: subject,
+        scope: scopes.join(' '),
+        aud: serviceAccount.token_uri,
+        iat: now,
+        exp: now + 3600,
+    };
+    const headerB64 = base64url(Buffer.from(JSON.stringify(header)));
+    const payloadB64 = base64url(Buffer.from(JSON.stringify(payload)));
+    const unsigned = `${headerB64}.${payloadB64}`;
+    const sign = crypto.createSign('RSA-SHA256');
+    sign.update(unsigned);
+    const signature = base64url(sign.sign(serviceAccount.private_key));
+    return `${unsigned}.${signature}`;
+}
+async function getServiceAccountToken(serviceAccount, scopes, subject) {
+    const jwt = createJwt(serviceAccount, scopes, subject);
+    const resp = await fetch(serviceAccount.token_uri, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+            assertion: jwt,
+        }),
+    });
+    if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(`Service account token failed (${String(resp.status)}): ${body}`);
+    }
+    const data = (await resp.json());
+    return data.access_token;
+}
+// ========== OAuth Refresh ==========
+async function getOAuthToken(refreshToken, client) {
+    const resp = await fetch('https://oauth2.googleapis.com/token', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            client_id: client.client_id,
+            client_secret: client.client_secret,
+            refresh_token: refreshToken,
+            grant_type: 'refresh_token',
+        }),
+    });
+    if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(`OAuth token refresh failed (${String(resp.status)}): ${body}`);
+    }
+    const data = (await resp.json());
+    return data.access_token;
+}
+// ========== Unified Auth ==========
+/**
+ * Create a Google auth helper with the given configuration.
+ * Returns a function that resolves an access token for a given account and scopes.
+ */
+function createGoogleAuth(options) {
+    const { clientCredentialsPath, credentialsDir, serviceAccountDir } = options;
+    let _oauthClient = null;
+    function getOAuthClient() {
+        if (!_oauthClient) {
+            _oauthClient = JSON.parse(fs.readFileSync(clientCredentialsPath, 'utf8'));
+        }
+        return _oauthClient;
+    }
+    /**
+     * Get an access token for the given account and scopes.
+     */
+    async function getAccessToken(account, scopes) {
+        if (account.serviceAccount) {
+            const saDir = serviceAccountDir ?? credentialsDir;
+            const saPath = typeof account.serviceAccount === 'string'
+                ? account.serviceAccount
+                : path.join(saDir, account.serviceAccount.file);
+            const sa = JSON.parse(fs.readFileSync(saPath, 'utf8'));
+            return getServiceAccountToken(sa, scopes, account.email);
+        }
+        if (account.tokenFile) {
+            const tokenPath = path.join(credentialsDir, account.tokenFile);
+            const tokenData = JSON.parse(fs.readFileSync(tokenPath, 'utf8'));
+            return getOAuthToken(tokenData.refresh_token, getOAuthClient());
+        }
+        throw new Error(`No auth method configured for ${account.email}`);
+    }
+    return {
+        /** Get an access token for the given account and scopes. */
+        getAccessToken,
+    };
+}
+
+/**
+ * Shared crash-handler wrapper for runner job scripts.
+ * Catches uncaught errors, logs them, and exits with code 1.
+ *
+ * @module
+ */
+/**
+ * Wrap a script's main function with crash handling.
+ * On uncaught errors, appends to `_crash.log` in `crashDir` and exits.
+ *
+ * @param name - Script identifier for the crash log.
+ * @param fn - Main function to execute (sync or async).
+ * @param crashDir - Directory for crash logs (default: current working directory).
+ */
+function runScript(name, fn, crashDir = process.cwd()) {
+    const execute = () => {
+        const result = fn();
+        if (result instanceof Promise) {
+            result.catch((err) => {
+                handleCrash(name, err, crashDir);
+            });
+        }
+    };
+    try {
+        execute();
+    }
+    catch (err) {
+        handleCrash(name, err, crashDir);
+    }
+}
+function handleCrash(name, err, crashDir) {
+    const message = err instanceof Error ? (err.stack ?? err.message) : String(err);
+    const entry = `[${new Date().toISOString()}] CRASH (${name}): ${message}\n`;
+    try {
+        fs.mkdirSync(crashDir, { recursive: true });
+        fs.appendFileSync(path.join(crashDir, '_crash.log'), entry);
+    }
+    catch {
+        // Best effort — don't crash the crash handler.
+    }
+    console.error(entry);
+    process.exit(1);
+}
+
+/**
+ * Shell execution utilities for runner job scripts.
+ *
+ * @module
+ */
+/**
+ * Run a command synchronously and return trimmed stdout.
+ * Throws on non-zero exit code.
+ */
+function run(cmd, args, opts = {}) {
+    const r = cp.spawnSync(cmd, args, {
+        encoding: 'utf8',
+        maxBuffer: 50 * 1024 * 1024,
+        ...opts,
+    });
+    if (r.error)
+        throw r.error;
+    const stdout = r.stdout || '';
+    const stderr = r.stderr || '';
+    if (r.status !== 0) {
+        const msg = (stderr || stdout).trim();
+        throw new Error(`${cmd} ${args.join(' ')} failed (exit ${String(r.status)}): ${msg}`);
+    }
+    return stdout.trim();
+}
+/**
+ * Run a command with automatic retries on transient failures.
+ * Uses exponential backoff between attempts.
+ */
+function runWithRetry(cmd, args, opts = {}) {
+    const { retries = 2, backoffMs = 5000, isRetryable, ...runOpts } = opts;
+    let lastErr;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            return run(cmd, args, runOpts);
+        }
+        catch (e) {
+            lastErr = e;
+            const msg = e instanceof Error ? e.message : String(e);
+            const retryable = isRetryable
+                ? isRetryable(e)
+                : /context deadline exceeded|timed out|timeout/i.test(msg);
+            if (!retryable || attempt === retries)
+                throw lastErr;
+            sleepMs(backoffMs * Math.pow(2, attempt));
+        }
+    }
+    throw lastErr;
+}
+
+/**
+ * Slack channel → workspace mapping cache.
+ * Resolves which Slack workspace owns a given channel.
+ *
+ * @module
+ */
+let _cache = null;
+let _dirty = false;
+let _cachePath = '';
+function loadCache(cachePath) {
+    if (!_cache || _cachePath !== cachePath) {
+        _cachePath = cachePath;
+        try {
+            _cache = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+        }
+        catch {
+            _cache = {};
+        }
+    }
+    return _cache;
+}
+/** Flush pending cache changes to disk. */
+function saveCache() {
+    if (_dirty && _cache && _cachePath) {
+        fs.writeFileSync(_cachePath, JSON.stringify(_cache, null, 2) + '\n');
+        _dirty = false;
+    }
+}
+async function queryChannelWorkspace(channelId, token, defaultWorkspace) {
+    const url = `https://slack.com/api/conversations.info?channel=${channelId}`;
+    try {
+        const res = await fetch(url, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!res.ok)
+            return defaultWorkspace;
+        const j = (await res.json());
+        if (!j.ok)
+            return defaultWorkspace;
+        const shared = j.channel?.shared_team_ids ?? [];
+        if (shared.length > 0 && !shared.includes(defaultWorkspace)) {
+            return shared[0];
+        }
+        return defaultWorkspace;
+    }
+    catch {
+        return defaultWorkspace;
+    }
+}
+/**
+ * Resolve the workspace team ID that owns a Slack channel.
+ * Results are cached to disk.
+ *
+ * @param channelId - Slack channel ID.
+ * @param token - Slack bot token for API calls.
+ * @param options - Cache path and default workspace.
+ */
+async function getChannelWorkspace(channelId, token, options) {
+    const cache = loadCache(options.cachePath);
+    if (cache[channelId])
+        return cache[channelId];
+    const teamId = await queryChannelWorkspace(channelId, token, options.defaultWorkspace);
+    cache[channelId] = teamId;
+    _dirty = true;
+    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 };