@karmaniverous/jeeves 0.5.7 → 0.5.9

package/README.md

@@ -220,8 +220,7 @@ Optional `jeeves.config.json` at the workspace root provides shared defaults for
   },
   "memory": {
     "budget": 20000,
-    "warningThreshold": 0.8,
-    "staleDays": 90
+    "warningThreshold": 0.8
   }
 }
 ```
@@ -240,10 +239,8 @@ Precedence: **CLI flags → environment variables → `jeeves.config.json` → d
 MEMORY.md has a character budget (default: 20,000 characters). The `analyzeMemory()` function tracks:
 
 - **Character count and usage percentage** — warns at 80% of budget (configurable via `warningThreshold`)
-- **Stale section detection** — scans ISO dates (`YYYY-MM-DD`) in H2/H3 headings and bullet items; sections whose most recent date exceeds `staleDays` (default: 30) are flagged as stale candidates
-- **Evergreen sections** — sections without parseable dates are never flagged
 
-Memory hygiene is reporting-only. Core does not auto-delete content; the assistant or human reviews stale candidates and decides what to prune.
+Memory hygiene is reporting-only. Core does not auto-delete content (Decision 42). Size pressure is the right signal for curation.
 
 ## Skill Seeding
 

package/content/agents-section.md

@@ -37,7 +37,7 @@ Periodic checks (email, calendar, mentions) belong in jeeves-runner scripts, not
 ## Platform Surface Conventions
 
 **Slack:**
-- No threaded replies by default
+- Never initiate a threaded reply. Only reply within a thread started by a human.
 - Use `<#C…>` for channel references
 
 **Table formatting:** On channels that do not support Markdown tables (Slack, Discord, WhatsApp, IRC), use code-block tables with aligned columns. Markdown tables are only safe in contexts that render them (GitHub, jeeves-server, files).

package/content/skill.md

@@ -62,7 +62,7 @@ Managed blocks are stationary after initial insertion. Cleanup detection uses Ja
 
 `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)
+- Namespaced: `core.*` (workspace, configRoot, gatewayUrl, devRepos) and `memory.*` (budget, warningThreshold)
 - Inspect with `jeeves config [jsonpath]`
 
 ## HEARTBEAT Protocol

package/content/tools-platform.md

@@ -44,8 +44,8 @@ Never manually edit `~/.openclaw/extensions/`. Always use the CLI commands above
 
 ### Reference Templates
 
-<!-- IF_TEMPLATES -->
-Reference templates are available at `__TEMPLATE_PATH__`:
+{{#if templatePath}}
+Reference templates are available at `{{templatePath}}`:
 
 | Template | Purpose |
 |----------|---------|
@@ -53,6 +53,36 @@ Reference templates are available at `__TEMPLATE_PATH__`:
 | `spec-to-code-guide.md` | The spec-to-code development practice — 7-stage iterative process, convergence loops, release gates |
 
 Read these templates when creating new specs, onboarding to new projects, or when asked about the development process.
-<!-- ELSE_TEMPLATES -->
+{{else}}
 > Reference templates not yet installed. Run `npx @karmaniverous/jeeves install` to seed templates.
-<!-- ENDIF_TEMPLATES -->
+{{/if}}
+
+### Post-Upgrade Maintenance
+
+After updating OpenClaw (`npm install -g openclaw@latest` or equivalent), reinstall all Jeeves component plugins to repair install state:
+
+```bash
+npx @karmaniverous/jeeves install
+npx @karmaniverous/jeeves-runner-openclaw install
+npx @karmaniverous/jeeves-watcher-openclaw install
+npx @karmaniverous/jeeves-server-openclaw install
+npx @karmaniverous/jeeves-meta-openclaw install
+```
+
+Then restart the gateway. Plugin installers copy dist files and patch config; reinstalling after an OpenClaw update ensures the extensions directory stays consistent.
+
+### Source Code Preference
+
+{{#if devRepos}}
+When investigating, debugging, or analyzing Jeeves components, always read TypeScript source from dev repos — never compiled `dist/` from the global npm install. Dev repos:
+
+| Component | Dev Repo |
+|-----------|----------|
+{{#each devRepos}}
+| {{@key}} | `{{this}}` |
+{{/each}}
+
+Built code is minified, harder to reason about, and wastes context. Always `git pull` before analysis.
+{{else}}
+> Dev repo paths not configured. Add `core.devRepos` to `jeeves.config.json` to enable source code preference guidance.
+{{/if}}

package/dist/cli/jeeves/index.js

@@ -9,6 +9,7 @@ import { execSync, spawnSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { lock } from 'proper-lockfile';
 import { fileURLToPath } from 'node:url';
+import Handlebars from 'handlebars';
 import { packageDirectorySync } from 'package-directory';
 
 function getDefaultExportFromCjs (x) {
@@ -269,14 +270,14 @@ const PLATFORM_COMPONENTS = [
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.5.6` placeholder is replaced by
+ * The `0.5.8` 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.5.6';
+const CORE_VERSION = '0.5.8';
 
 /**
  * Runtime Node.js version floor check.
@@ -333,6 +334,11 @@ const workspaceCoreConfigSchema = z
     configRoot: z.string().optional().describe('Platform config root path'),
     /** OpenClaw gateway URL. */
     gatewayUrl: z.string().optional().describe('OpenClaw gateway URL'),
+    /** Dev repo paths keyed by component name. */
+    devRepos: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('Dev repo paths by component name'),
 })
     .partial();
 /** Memory shared config section. */
@@ -347,13 +353,6 @@ const workspaceMemoryConfigSchema = z
         .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. */
@@ -381,7 +380,6 @@ const WORKSPACE_CONFIG_DEFAULTS = {
     memory: {
         budget: 20_000,
         warningThreshold: 0.8,
-        staleDays: 30,
     },
 };
 /**
@@ -444,6 +442,7 @@ function init(options) {
         workspacePath: options.workspacePath,
         configRoot: options.configRoot,
         coreConfigDir: join(options.configRoot, CORE_CONFIG_DIR),
+        componentConfigPaths: new Map(),
     };
 }
 /**
@@ -511,7 +510,6 @@ function resolveCliConfig(opts) {
         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),
         },
     };
 }
@@ -820,9 +818,8 @@ function getServiceUrl(serviceName, consumerName) {
     if (coreUrl)
         return coreUrl;
     // 3. Fall back to port constants
-    const port = DEFAULT_PORTS[serviceName];
-    if (port !== undefined) {
-        return `http://127.0.0.1:${String(port)}`;
+    if (serviceName in DEFAULT_PORTS) {
+        return `http://127.0.0.1:${String(DEFAULT_PORTS[serviceName])}`;
     }
     throw new Error(`jeeves-core: unknown service "${serviceName}" and no config found`);
 }
@@ -1177,7 +1174,7 @@ Periodic checks (email, calendar, mentions) belong in jeeves-runner scripts, not
 ## Platform Surface Conventions
 
 **Slack:**
-- No threaded replies by default
+- Never initiate a threaded reply. Only reply within a thread started by a human.
 - Use \`<#C…>\` for channel references
 
 **Table formatting:** On channels that do not support Markdown tables (Slack, Discord, WhatsApp, IRC), use code-block tables with aligned columns. Markdown tables are only safe in contexts that render them (GitHub, jeeves-server, files).
@@ -1383,8 +1380,8 @@ Never manually edit \`~/.openclaw/extensions/\`. Always use the CLI commands abo
 
 ### Reference Templates
 
-<!-- IF_TEMPLATES -->
-Reference templates are available at \`__TEMPLATE_PATH__\`:
+{{#if templatePath}}
+Reference templates are available at \`{{templatePath}}\`:
 
 | Template | Purpose |
 |----------|---------|
@@ -1392,9 +1389,39 @@ Reference templates are available at \`__TEMPLATE_PATH__\`:
 | \`spec-to-code-guide.md\` | The spec-to-code development practice — 7-stage iterative process, convergence loops, release gates |
 
 Read these templates when creating new specs, onboarding to new projects, or when asked about the development process.
-<!-- ELSE_TEMPLATES -->
+{{else}}
 > Reference templates not yet installed. Run \`npx @karmaniverous/jeeves install\` to seed templates.
-<!-- ENDIF_TEMPLATES -->
+{{/if}}
+
+### Post-Upgrade Maintenance
+
+After updating OpenClaw (\`npm install -g openclaw@latest\` or equivalent), reinstall all Jeeves component plugins to repair install state:
+
+\`\`\`bash
+npx @karmaniverous/jeeves install
+npx @karmaniverous/jeeves-runner-openclaw install
+npx @karmaniverous/jeeves-watcher-openclaw install
+npx @karmaniverous/jeeves-server-openclaw install
+npx @karmaniverous/jeeves-meta-openclaw install
+\`\`\`
+
+Then restart the gateway. Plugin installers copy dist files and patch config; reinstalling after an OpenClaw update ensures the extensions directory stays consistent.
+
+### Source Code Preference
+
+{{#if devRepos}}
+When investigating, debugging, or analyzing Jeeves components, always read TypeScript source from dev repos — never compiled \`dist/\` from the global npm install. Dev repos:
+
+| Component | Dev Repo |
+|-----------|----------|
+{{#each devRepos}}
+| {{@key}} | \`{{this}}\` |
+{{/each}}
+
+Built code is minified, harder to reason about, and wastes context. Always \`git pull\` before analysis.
+{{else}}
+> Dev repo paths not configured. Add \`core.devRepos\` to \`jeeves.config.json\` to enable source code preference guidance.
+{{/if}}
 `;
 
 /**
@@ -1843,6 +1870,10 @@ async function updateManagedSection(filePath, content, options = {}) {
  * Platform template with live data, and writes managed sections using
  * `updateManagedSection`.
  */
+/** Compiled Handlebars template for the Platform section (cached at module level). */
+const compiledPlatformTemplate = Handlebars.compile(toolsPlatformTemplate, {
+    noEscape: true,
+});
 /**
  * Resolve the package's content directory for template file copying.
  *
@@ -1886,23 +1917,13 @@ function copyTemplates(coreConfigDir) {
     cpSync(sourceDir, destDir, { recursive: true });
 }
 /**
- * Render the Platform template using simple string replacement.
+ * Render the Platform template using Handlebars.
  *
- * @param templatePath - Path to the templates directory.
+ * @param context - Template context with optional templatePath and devRepos.
  * @returns Rendered platform content string.
  */
-function renderPlatformTemplate(templatePath) {
-    const templatesAvailable = existsSync(templatePath);
-    let content = toolsPlatformTemplate;
-    // Handle <!-- IF_TEMPLATES --> ... <!-- ELSE_TEMPLATES --> ... <!-- ENDIF_TEMPLATES --> block
-    const ifRegex = /<!-- IF_TEMPLATES -->([\s\S]*?)<!-- ELSE_TEMPLATES -->([\s\S]*?)<!-- ENDIF_TEMPLATES -->/;
-    const match = ifRegex.exec(content);
-    if (match) {
-        content = content.replace(match[0], templatesAvailable ? match[1] : match[2]);
-    }
-    // Replace __TEMPLATE_PATH__ with the actual path
-    content = content.replace(/__TEMPLATE_PATH__/g, templatePath);
-    return content;
+function renderPlatformTemplate(context) {
+    return compiledPlatformTemplate(context);
 }
 /**
  * Refresh platform content: SOUL.md, AGENTS.md, and TOOLS.md Platform section.
@@ -1910,7 +1931,7 @@ function renderPlatformTemplate(templatePath) {
  * @param options - Configuration for the refresh cycle.
  */
 async function refreshPlatformContent(options) {
-    const { coreVersion, componentName, componentVersion, servicePackage, pluginPackage, stalenessThresholdMs, } = options;
+    const { coreVersion, componentName, componentVersion, servicePackage, pluginPackage, stalenessThresholdMs, workspaceConfig, } = options;
     const workspacePath = getWorkspacePath();
     const coreConfigDir = getCoreConfigDir();
     // 1. Write calling component's version entry
@@ -1924,7 +1945,11 @@ async function refreshPlatformContent(options) {
     }
     // 2. Render Platform template
     const templatePath = join(coreConfigDir, TEMPLATES_DIR);
-    const platformContent = renderPlatformTemplate(templatePath);
+    const wsConfig = workspaceConfig ?? loadWorkspaceConfig(workspacePath);
+    const platformContent = renderPlatformTemplate({
+        templatePath: existsSync(templatePath) ? templatePath : undefined,
+        devRepos: wsConfig?.core?.devRepos,
+    });
     // 3. Write TOOLS.md Platform section
     const toolsPath = join(workspacePath, WORKSPACE_FILES.tools);
     await updateManagedSection(toolsPath, platformContent, {
@@ -2018,7 +2043,7 @@ Managed blocks are stationary after initial insertion. Cleanup detection uses Ja
 
 \`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)
+- Namespaced: \`core.*\` (workspace, configRoot, gatewayUrl, devRepos) and \`memory.*\` (budget, warningThreshold)
 - Inspect with \`jeeves config [jsonpath]\`
 
 ## HEARTBEAT Protocol
@@ -2202,46 +2227,21 @@ function registerInstallCommand(program) {
 }
 
 /**
- * Memory budget accounting and staleness detection for MEMORY.md.
+ * Memory budget accounting 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).
+ * Reports character count against a configured budget and warning threshold
+ * state. Does not auto-delete: review remains human- or agent-mediated
+ * (Decision 42). Staleness detection removed in v0.5.9 (Decision 45).
  */
-/** 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.
+ * Analyze MEMORY.md for budget health.
  *
  * @param options - Analysis configuration.
  * @returns Memory hygiene result.
  */
 function analyzeMemory(options) {
-    const { workspacePath, budget, warningThreshold, staleDays } = options;
+    const { workspacePath, budget, warningThreshold } = options;
     const memoryPath = join(workspacePath, WORKSPACE_FILES.memory);
     if (!existsSync(memoryPath)) {
         return {
@@ -2251,8 +2251,6 @@ function analyzeMemory(options) {
             usage: 0,
             warning: false,
             overBudget: false,
-            staleCandidates: 0,
-            staleSectionNames: [],
         };
     }
     const content = readFileSync(memoryPath, 'utf-8');
@@ -2260,21 +2258,6 @@ function analyzeMemory(options) {
     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,
@@ -2282,8 +2265,6 @@ function analyzeMemory(options) {
         usage,
         warning,
         overBudget,
-        staleCandidates: staleSectionNames.length,
-        staleSectionNames,
     };
 }
 
@@ -2382,7 +2363,6 @@ function registerStatusCommand(program) {
             workspacePath: getWorkspacePath(),
             budget: resolved.memory.budget.value,
             warningThreshold: resolved.memory.warningThreshold.value,
-            staleDays: resolved.memory.staleDays.value,
         });
         console.log('Memory hygiene');
         console.log('-'.repeat(60));
@@ -2397,7 +2377,6 @@ function registerStatusCommand(program) {
                     ? '⚠ Warning'
                     : '✅ OK';
             console.log(`Chars: ${String(memory.charCount)} / ${String(memory.budget)} (${String(usagePct)}%) — ${status}`);
-            console.log(`Stale candidates: ${String(memory.staleCandidates)}`);
         }
         console.log();
         if (!allHealthy) {

package/dist/cli/plugin/index.js

@@ -130,14 +130,14 @@ const COMPONENT_VERSIONS_FILE = 'component-versions.json';
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.5.6` placeholder is replaced by
+ * The `0.5.8` 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.5.6';
+const CORE_VERSION = '0.5.8';
 
 /**
  * Shared file I/O helpers for managed section operations.
@@ -386,6 +386,7 @@ function init(options) {
         workspacePath: options.workspacePath,
         configRoot: options.configRoot,
         coreConfigDir: join(options.configRoot, CORE_CONFIG_DIR),
+        componentConfigPaths: new Map(),
     };
 }
 /**
@@ -814,7 +815,7 @@ Managed blocks are stationary after initial insertion. Cleanup detection uses Ja
 
 \`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)
+- Namespaced: \`core.*\` (workspace, configRoot, gatewayUrl, devRepos) and \`memory.*\` (budget, warningThreshold)
 - Inspect with \`jeeves config [jsonpath]\`
 
 ## HEARTBEAT Protocol

package/dist/cli/service/index.js

@@ -261,6 +261,7 @@ function init(options) {
         workspacePath: options.workspacePath,
         configRoot: options.configRoot,
         coreConfigDir: join(options.configRoot, CORE_CONFIG_DIR),
+        componentConfigPaths: new Map(),
     };
 }
 /**
@@ -730,6 +731,11 @@ const workspaceCoreConfigSchema = z
     configRoot: z.string().optional().describe('Platform config root path'),
     /** OpenClaw gateway URL. */
     gatewayUrl: z.string().optional().describe('OpenClaw gateway URL'),
+    /** Dev repo paths keyed by component name. */
+    devRepos: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('Dev repo paths by component name'),
 })
     .partial();
 /** Memory shared config section. */
@@ -744,13 +750,6 @@ const workspaceMemoryConfigSchema = z
         .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. */
@@ -1028,11 +1027,6 @@ function createServiceCli(descriptor) {
     });
     // Apply custom CLI commands if provided
     if (descriptor.customCliCommands) {
-        // Cast required: @commander-js/extra-typings Command has generic type
-        // parameters that don't align with the descriptor's base Command type.
-        // The descriptor can't know the parent Command's exact generic parameters
-        // at definition time. The cast is safe — customCliCommands only adds
-        // subcommands and doesn't depend on the parent's generic state.
         descriptor.customCliCommands(program);
     }
     return program;

package/dist/index.d.ts

@@ -295,11 +295,11 @@ declare const workspaceConfigSchema: z.ZodObject<{
         workspace: z.ZodOptional<z.ZodOptional<z.ZodString>>;
         configRoot: z.ZodOptional<z.ZodOptional<z.ZodString>>;
         gatewayUrl: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        devRepos: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
     }, z.core.$strip>>;
     memory: z.ZodOptional<z.ZodObject<{
         budget: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
         warningThreshold: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
-        staleDays: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 /** Workspace config type. */
@@ -327,8 +327,6 @@ declare const WORKSPACE_CONFIG_DEFAULTS: {
         readonly budget: 20_000;
         /** Default warning threshold as a fraction of budget (80%). */
         readonly warningThreshold: 0.8;
-        /** Default staleness threshold in days. */
-        readonly staleDays: 30;
     };
 };
 /** Provenance source for a resolved config value. */
@@ -396,8 +394,6 @@ interface ResolvedCliConfig {
         budget: ResolvedValue<number>;
         /** Resolved warning threshold as a fraction of budget. */
         warningThreshold: ResolvedValue<number>;
-        /** Resolved staleness threshold in days. */
-        staleDays: ResolvedValue<number>;
     };
 }
 
@@ -576,6 +572,7 @@ declare class ComponentWriter {
     private readonly gatewayUrl;
     private readonly pendingCleanups;
     private cyclePromise;
+    private stopped;
     /** @internal */
     constructor(component: JeevesComponentDescriptor, options?: ComponentWriterOptions);
     /** The component's config directory path. */
@@ -652,7 +649,8 @@ interface AsyncContentCacheOptions {
     placeholder?: string;
     /**
      * Optional error handler. Called when `fetch` throws.
-     * Defaults to `console.warn`.
+     * Defaults to a handler that logs transient network errors as
+     * concise warnings and unexpected errors with full details.
      */
     onError?: (error: unknown) => void;
 }
@@ -1111,6 +1109,28 @@ declare function getCoreConfigFile(): string;
  * @throws Error if `init()` has not been called.
  */
 declare function getComponentConfigDir(componentName: string): string;
+/**
+ * Register the actual config file path for a component.
+ *
+ * @remarks
+ * Call this after resolving the `--config` CLI argument so that
+ * `getComponentConfigPath` returns the real file location instead of
+ * the default derived from `configRoot`.
+ *
+ * @param componentName - The component name (e.g., 'watcher', 'runner').
+ * @param absolutePath - Absolute path to the component's config file.
+ * @throws Error if `init()` has not been called.
+ */
+declare function registerComponentConfigPath(componentName: string, absolutePath: string): void;
+/**
+ * Get the registered config file path for a component, or `undefined`
+ * if no override has been registered.
+ *
+ * @param componentName - The component name.
+ * @returns The registered absolute path, or `undefined`.
+ * @throws Error if `init()` has not been called.
+ */
+declare function getComponentConfigPath(componentName: string): string | undefined;
 /**
  * Reset initialization state. Used for testing only.
  */
@@ -1332,13 +1352,12 @@ declare function formatEndMarker(markerText: string): string;
 declare function shouldWrite(myVersion: string, existing: VersionStamp | undefined, stalenessThresholdMs?: number): boolean;
 
 /**
- * Memory budget accounting and staleness detection for MEMORY.md.
+ * Memory budget accounting 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).
+ * Reports character count against a configured budget and warning threshold
+ * state. Does not auto-delete: review remains human- or agent-mediated
+ * (Decision 42). Staleness detection removed in v0.5.9 (Decision 45).
  */
 /** Result of memory hygiene analysis. */
 interface MemoryHygieneResult {
@@ -1354,10 +1373,6 @@ interface MemoryHygieneResult {
     warning: boolean;
     /** Whether usage exceeds the budget. */
     overBudget: boolean;
-    /** Number of H2 sections flagged as stale candidates. */
-    staleCandidates: number;
-    /** Names of stale sections. */
-    staleSectionNames: string[];
 }
 /** Options for memory hygiene analysis. */
 interface MemoryHygieneOptions {
@@ -1367,18 +1382,9 @@ interface MemoryHygieneOptions {
     budget: number;
     /** Warning threshold as a fraction of budget (0–1). */
     warningThreshold: number;
-    /** Staleness threshold in days. */
-    staleDays: number;
 }
 /**
- * Extract the most recent ISO date from a string.
- *
- * @param text - Text to scan for dates.
- * @returns The most recent date found, or undefined.
- */
-declare function extractMostRecentDate(text: string): Date | undefined;
-/**
- * Analyze MEMORY.md for budget and staleness.
+ * Analyze MEMORY.md for budget health.
  *
  * @param options - Analysis configuration.
  * @returns Memory hygiene result.
@@ -1416,6 +1422,7 @@ declare function checkMemoryHealth(options: MemoryHygieneOptions): HeartbeatEntr
  * Platform template with live data, and writes managed sections using
  * `updateManagedSection`.
  */
+
 /** Options for refreshPlatformContent. */
 interface RefreshPlatformContentOptions {
     /** Core library version for version-stamp convergence. */
@@ -1430,6 +1437,8 @@ interface RefreshPlatformContentOptions {
     pluginPackage?: string;
     /** Staleness threshold override in ms. */
     stalenessThresholdMs?: number;
+    /** Pre-loaded workspace config (avoids redundant reads when caller already loaded it). */
+    workspaceConfig?: WorkspaceConfig;
 }
 /**
  * Refresh platform content: SOUL.md, AGENTS.md, and TOOLS.md Platform section.
@@ -1895,5 +1904,26 @@ interface ServiceManager {
  */
 declare function createServiceManager(descriptor: JeevesComponentDescriptor): ServiceManager;
 
-export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_BIND_ADDRESS, DEFAULT_CORE_VERSION, DEFAULT_PORTS, HEARTBEAT_HEADING, JEEVES_SKILL_DIR, MEMORY_HEARTBEAT_NAME, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SKILLS_DIR, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_CONFIG_DEFAULTS, WORKSPACE_CONFIG_FILE, WORKSPACE_FILES, analyzeMemory, appendJsonl, atomicWrite, buildEffectiveConfig, buildHeartbeatSection, checkMemoryHealth, checkNodeVersion, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, extractMostRecentDate, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, generateWorkspaceJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getPackageRoot, 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 };
+/**
+ * Shared internal utility functions.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Extract a human-readable message from an unknown caught value.
+ *
+ * @param err - The caught value (typically `unknown`).
+ * @returns The error message string.
+ */
+declare function getErrorMessage(err: unknown): string;
+/**
+ * Classify whether an error is a transient network failure.
+ *
+ * @param err - The caught value.
+ * @returns `true` for ECONNRESET, ETIMEDOUT, UND_ERR_CONNECT_TIMEOUT,
+ *          AbortError, and timeout-related fetch errors.
+ */
+declare function isTransientError(err: unknown): boolean;
+
+export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_BIND_ADDRESS, DEFAULT_CORE_VERSION, DEFAULT_PORTS, HEARTBEAT_HEADING, JEEVES_SKILL_DIR, MEMORY_HEARTBEAT_NAME, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SKILLS_DIR, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_CONFIG_DEFAULTS, WORKSPACE_CONFIG_FILE, WORKSPACE_FILES, analyzeMemory, appendJsonl, atomicWrite, buildEffectiveConfig, buildHeartbeatSection, checkMemoryHealth, checkNodeVersion, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, generateWorkspaceJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getComponentConfigPath, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getErrorMessage, getPackageRoot, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, isTransientError, jaccard, jeevesComponentDescriptorSchema, loadEnvFile, loadWorkspaceConfig, needsCleanup, nowIso, ok, orchestrateHeartbeat, parseArgs, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, readJson, readJsonl, refreshPlatformContent, registerComponentConfigPath, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveConfigValue, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, run, runScript, runWithRetry, saveCache, seedContent, seedSkill, shingles, shouldWrite, sleepAsync, sleepMs, updateManagedSection, uuid, withFileLock, workspaceConfigSchema, writeComponentVersion, writeHeartbeatSection, writeJsonAtomic, writeJsonl };
 export type { AccountConfig, AsyncContentCacheOptions, ComponentDependencies, ComponentState, ComponentVersionEntry, ComponentVersionsState, ComponentWriterOptions, ConfigApplyHandler, ConfigApplyRequest, ConfigApplyResult, ConfigProvenance, ConfigQueryHandler, ConfigQueryResponse, CoreConfig, CreatePluginCliOptions, CreateStatusHandlerOptions, GoogleAuthOptions, HeartbeatEntry, InitOptions, JeevesComponentDescriptor, ManagedMarkers, ManagedSection, MemoryHygieneOptions, MemoryHygieneResult, OrchestrateHeartbeatOptions, ParseManagedResult, ParsedHeartbeat, PlatformComponent, PluginApi, PluginInstallRecord, RefreshPlatformContentOptions, RemoveManagedSectionOptions, ResolvedCliConfig, ResolvedValue, RetryOptions, RunOptions, SectionId, SeedContentOptions, ServiceAccountFileConfig, ServiceManager, ServiceManagerOptions, ServiceState, SlackWorkspaceOptions, StatusHandler, StatusHandlerResult, StatusResponse, ToolDescriptor, ToolRegistrationOptions, ToolResult, UpdateManagedSectionOptions, VersionStamp, WorkspaceConfig, WorkspaceOptions, WriteComponentVersionOptions };

package/dist/index.js

@@ -10,6 +10,7 @@ import cp, { execSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { packageDirectorySync } from 'package-directory';
+import Handlebars from 'handlebars';
 
 /**
  * Comment markers for managed content blocks.
@@ -183,14 +184,14 @@ const PLATFORM_COMPONENTS = [
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.5.6` placeholder is replaced by
+ * The `0.5.8` 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.5.6';
+const CORE_VERSION = '0.5.8';
 
 /**
  * Workspace and config root initialization.
@@ -213,6 +214,7 @@ function init(options) {
         workspacePath: options.workspacePath,
         configRoot: options.configRoot,
         coreConfigDir: join(options.configRoot, CORE_CONFIG_DIR),
+        componentConfigPaths: new Map(),
     };
 }
 /**
@@ -267,6 +269,36 @@ function getComponentConfigDir(componentName) {
         throw new Error('jeeves-core: init() must be called first');
     return join(state.configRoot, `${COMPONENT_CONFIG_PREFIX}${componentName}`);
 }
+/**
+ * Register the actual config file path for a component.
+ *
+ * @remarks
+ * Call this after resolving the `--config` CLI argument so that
+ * `getComponentConfigPath` returns the real file location instead of
+ * the default derived from `configRoot`.
+ *
+ * @param componentName - The component name (e.g., 'watcher', 'runner').
+ * @param absolutePath - Absolute path to the component's config file.
+ * @throws Error if `init()` has not been called.
+ */
+function registerComponentConfigPath(componentName, absolutePath) {
+    if (!state)
+        throw new Error('jeeves-core: init() must be called first');
+    state.componentConfigPaths.set(componentName, absolutePath);
+}
+/**
+ * Get the registered config file path for a component, or `undefined`
+ * if no override has been registered.
+ *
+ * @param componentName - The component name.
+ * @returns The registered absolute path, or `undefined`.
+ * @throws Error if `init()` has not been called.
+ */
+function getComponentConfigPath(componentName) {
+    if (!state)
+        throw new Error('jeeves-core: init() must be called first');
+    return state.componentConfigPaths.get(componentName);
+}
 /**
  * Reset initialization state. Used for testing only.
  */
@@ -410,6 +442,32 @@ async function withWorkspaceLock(workspacePath, fn) {
 function getErrorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
+/** Error codes / names that indicate transient network failures. */
+const TRANSIENT_CODES = new Set([
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'UND_ERR_CONNECT_TIMEOUT',
+    'AbortError',
+]);
+/**
+ * Classify whether an error is a transient network failure.
+ *
+ * @param err - The caught value.
+ * @returns `true` for ECONNRESET, ETIMEDOUT, UND_ERR_CONNECT_TIMEOUT,
+ *          AbortError, and timeout-related fetch errors.
+ */
+function isTransientError(err) {
+    let current = err;
+    while (current instanceof Error) {
+        if (TRANSIENT_CODES.has(current.name))
+            return true;
+        const code = current.code;
+        if (typeof code === 'string' && TRANSIENT_CODES.has(code))
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
 
 /**
  * Factory for a framework-agnostic config apply HTTP handler.
@@ -484,9 +542,9 @@ function readConfigFile(filePath) {
 function createConfigApplyHandler(descriptor) {
     return async (request) => {
         const { patch, replace } = request;
-        // Derive config path
-        const configDir = getComponentConfigDir(descriptor.name);
-        const configPath = join(configDir, descriptor.configFileName);
+        // Use registered config path if available, otherwise derive from configRoot
+        const configPath = getComponentConfigPath(descriptor.name) ??
+            join(getComponentConfigDir(descriptor.name), descriptor.configFileName);
         // Read existing config
         const existing = readConfigFile(configPath);
         // Merge or replace
@@ -667,6 +725,11 @@ const workspaceCoreConfigSchema = z
     configRoot: z.string().optional().describe('Platform config root path'),
     /** OpenClaw gateway URL. */
     gatewayUrl: z.string().optional().describe('OpenClaw gateway URL'),
+    /** Dev repo paths keyed by component name. */
+    devRepos: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('Dev repo paths by component name'),
 })
     .partial();
 /** Memory shared config section. */
@@ -681,13 +744,6 @@ const workspaceMemoryConfigSchema = z
         .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. */
@@ -715,7 +771,6 @@ const WORKSPACE_CONFIG_DEFAULTS = {
     memory: {
         budget: 20_000,
         warningThreshold: 0.8,
-        staleDays: 30,
     },
 };
 /**
@@ -783,6 +838,11 @@ function generateWorkspaceJsonSchema() {
                         type: 'string',
                         default: WORKSPACE_CONFIG_DEFAULTS.core.gatewayUrl,
                     },
+                    devRepos: {
+                        type: 'object',
+                        additionalProperties: { type: 'string' },
+                        description: 'Dev repo paths by component name (e.g. { "core": "D:\\\\repos\\\\jeeves" })',
+                    },
                 },
             },
             memory: {
@@ -799,11 +859,6 @@ function generateWorkspaceJsonSchema() {
                         maximum: 1,
                         default: WORKSPACE_CONFIG_DEFAULTS.memory.warningThreshold,
                     },
-                    staleDays: {
-                        type: 'integer',
-                        minimum: 1,
-                        default: WORKSPACE_CONFIG_DEFAULTS.memory.staleDays,
-                    },
                 },
             },
         },
@@ -847,7 +902,6 @@ function resolveCliConfig(opts) {
         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),
         },
     };
 }
@@ -1517,7 +1571,7 @@ Managed blocks are stationary after initial insertion. Cleanup detection uses Ja
 
 \`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)
+- Namespaced: \`core.*\` (workspace, configRoot, gatewayUrl, devRepos) and \`memory.*\` (budget, warningThreshold)
 - Inspect with \`jeeves config [jsonpath]\`
 
 ## HEARTBEAT Protocol
@@ -3157,11 +3211,6 @@ function createServiceCli(descriptor) {
     });
     // Apply custom CLI commands if provided
     if (descriptor.customCliCommands) {
-        // Cast required: @commander-js/extra-typings Command has generic type
-        // parameters that don't align with the descriptor's base Command type.
-        // The descriptor can't know the parent Command's exact generic parameters
-        // at definition time. The cast is safe — customCliCommands only adds
-        // subcommands and doesn't depend on the parent's generic state.
         descriptor.customCliCommands(program);
     }
     return program;
@@ -3446,7 +3495,7 @@ Periodic checks (email, calendar, mentions) belong in jeeves-runner scripts, not
 ## Platform Surface Conventions
 
 **Slack:**
-- No threaded replies by default
+- Never initiate a threaded reply. Only reply within a thread started by a human.
 - Use \`<#C…>\` for channel references
 
 **Table formatting:** On channels that do not support Markdown tables (Slack, Discord, WhatsApp, IRC), use code-block tables with aligned columns. Markdown tables are only safe in contexts that render them (GitHub, jeeves-server, files).
@@ -3652,8 +3701,8 @@ Never manually edit \`~/.openclaw/extensions/\`. Always use the CLI commands abo
 
 ### Reference Templates
 
-<!-- IF_TEMPLATES -->
-Reference templates are available at \`__TEMPLATE_PATH__\`:
+{{#if templatePath}}
+Reference templates are available at \`{{templatePath}}\`:
 
 | Template | Purpose |
 |----------|---------|
@@ -3661,9 +3710,39 @@ Reference templates are available at \`__TEMPLATE_PATH__\`:
 | \`spec-to-code-guide.md\` | The spec-to-code development practice — 7-stage iterative process, convergence loops, release gates |
 
 Read these templates when creating new specs, onboarding to new projects, or when asked about the development process.
-<!-- ELSE_TEMPLATES -->
+{{else}}
 > Reference templates not yet installed. Run \`npx @karmaniverous/jeeves install\` to seed templates.
-<!-- ENDIF_TEMPLATES -->
+{{/if}}
+
+### Post-Upgrade Maintenance
+
+After updating OpenClaw (\`npm install -g openclaw@latest\` or equivalent), reinstall all Jeeves component plugins to repair install state:
+
+\`\`\`bash
+npx @karmaniverous/jeeves install
+npx @karmaniverous/jeeves-runner-openclaw install
+npx @karmaniverous/jeeves-watcher-openclaw install
+npx @karmaniverous/jeeves-server-openclaw install
+npx @karmaniverous/jeeves-meta-openclaw install
+\`\`\`
+
+Then restart the gateway. Plugin installers copy dist files and patch config; reinstalling after an OpenClaw update ensures the extensions directory stays consistent.
+
+### Source Code Preference
+
+{{#if devRepos}}
+When investigating, debugging, or analyzing Jeeves components, always read TypeScript source from dev repos — never compiled \`dist/\` from the global npm install. Dev repos:
+
+| Component | Dev Repo |
+|-----------|----------|
+{{#each devRepos}}
+| {{@key}} | \`{{this}}\` |
+{{/each}}
+
+Built code is minified, harder to reason about, and wastes context. Always \`git pull\` before analysis.
+{{else}}
+> Dev repo paths not configured. Add \`core.devRepos\` to \`jeeves.config.json\` to enable source code preference guidance.
+{{/if}}
 `;
 
 /**
@@ -3675,6 +3754,10 @@ Read these templates when creating new specs, onboarding to new projects, or whe
  * Platform template with live data, and writes managed sections using
  * `updateManagedSection`.
  */
+/** Compiled Handlebars template for the Platform section (cached at module level). */
+const compiledPlatformTemplate = Handlebars.compile(toolsPlatformTemplate, {
+    noEscape: true,
+});
 /**
  * Resolve the package's content directory for template file copying.
  *
@@ -3718,23 +3801,13 @@ function copyTemplates(coreConfigDir) {
     cpSync(sourceDir, destDir, { recursive: true });
 }
 /**
- * Render the Platform template using simple string replacement.
+ * Render the Platform template using Handlebars.
  *
- * @param templatePath - Path to the templates directory.
+ * @param context - Template context with optional templatePath and devRepos.
  * @returns Rendered platform content string.
  */
-function renderPlatformTemplate(templatePath) {
-    const templatesAvailable = existsSync(templatePath);
-    let content = toolsPlatformTemplate;
-    // Handle <!-- IF_TEMPLATES --> ... <!-- ELSE_TEMPLATES --> ... <!-- ENDIF_TEMPLATES --> block
-    const ifRegex = /<!-- IF_TEMPLATES -->([\s\S]*?)<!-- ELSE_TEMPLATES -->([\s\S]*?)<!-- ENDIF_TEMPLATES -->/;
-    const match = ifRegex.exec(content);
-    if (match) {
-        content = content.replace(match[0], templatesAvailable ? match[1] : match[2]);
-    }
-    // Replace __TEMPLATE_PATH__ with the actual path
-    content = content.replace(/__TEMPLATE_PATH__/g, templatePath);
-    return content;
+function renderPlatformTemplate(context) {
+    return compiledPlatformTemplate(context);
 }
 /**
  * Refresh platform content: SOUL.md, AGENTS.md, and TOOLS.md Platform section.
@@ -3742,7 +3815,7 @@ function renderPlatformTemplate(templatePath) {
  * @param options - Configuration for the refresh cycle.
  */
 async function refreshPlatformContent(options) {
-    const { coreVersion, componentName, componentVersion, servicePackage, pluginPackage, stalenessThresholdMs, } = options;
+    const { coreVersion, componentName, componentVersion, servicePackage, pluginPackage, stalenessThresholdMs, workspaceConfig, } = options;
     const workspacePath = getWorkspacePath();
     const coreConfigDir = getCoreConfigDir();
     // 1. Write calling component's version entry
@@ -3756,7 +3829,11 @@ async function refreshPlatformContent(options) {
     }
     // 2. Render Platform template
     const templatePath = join(coreConfigDir, TEMPLATES_DIR);
-    const platformContent = renderPlatformTemplate(templatePath);
+    const wsConfig = workspaceConfig ?? loadWorkspaceConfig(workspacePath);
+    const platformContent = renderPlatformTemplate({
+        templatePath: existsSync(templatePath) ? templatePath : undefined,
+        devRepos: wsConfig?.core?.devRepos,
+    });
     // 3. Write TOOLS.md Platform section
     const toolsPath = join(workspacePath, WORKSPACE_FILES.tools);
     await updateManagedSection(toolsPath, platformContent, {
@@ -3884,46 +3961,21 @@ function scanAndEscalateCleanup(targets, gatewayUrl, pendingCleanups) {
 }
 
 /**
- * Memory budget accounting and staleness detection for MEMORY.md.
+ * Memory budget accounting 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).
+ * Reports character count against a configured budget and warning threshold
+ * state. Does not auto-delete: review remains human- or agent-mediated
+ * (Decision 42). Staleness detection removed in v0.5.9 (Decision 45).
  */
-/** 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.
+ * Analyze MEMORY.md for budget health.
  *
  * @param options - Analysis configuration.
  * @returns Memory hygiene result.
  */
 function analyzeMemory(options) {
-    const { workspacePath, budget, warningThreshold, staleDays } = options;
+    const { workspacePath, budget, warningThreshold } = options;
     const memoryPath = join(workspacePath, WORKSPACE_FILES.memory);
     if (!existsSync(memoryPath)) {
         return {
@@ -3933,8 +3985,6 @@ function analyzeMemory(options) {
             usage: 0,
             warning: false,
             overBudget: false,
-            staleCandidates: 0,
-            staleSectionNames: [],
         };
     }
     const content = readFileSync(memoryPath, 'utf-8');
@@ -3942,21 +3992,6 @@ function analyzeMemory(options) {
     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,
@@ -3964,8 +3999,6 @@ function analyzeMemory(options) {
         usage,
         warning,
         overBudget,
-        staleCandidates: staleSectionNames.length,
-        staleSectionNames,
     };
 }
 
@@ -3992,20 +4025,14 @@ function checkMemoryHealth(options) {
     const result = analyzeMemory(options);
     if (!result.exists)
         return undefined;
-    if (!result.warning && result.staleCandidates === 0)
+    if (!result.warning)
         return undefined;
-    const lines = [];
-    if (result.warning) {
-        const pct = Math.round(result.usage * 100);
-        lines.push(`- Budget: ${result.charCount.toLocaleString()} / ${result.budget.toLocaleString()} chars (${String(pct)}%).${result.overBudget ? ' **Over budget.**' : ' Consider reviewing.'}`);
-    }
-    if (result.staleCandidates > 0) {
-        lines.push(`- ${String(result.staleCandidates)} stale section${result.staleCandidates === 1 ? '' : 's'}: ${result.staleSectionNames.join(', ')}`);
-    }
+    const pct = Math.round(result.usage * 100);
+    const content = `- Budget: ${result.charCount.toLocaleString()} / ${result.budget.toLocaleString()} chars (${String(pct)}%).${result.overBudget ? ' **Over budget.**' : ' Consider reviewing.'}`;
     return {
         name: MEMORY_HEARTBEAT_NAME,
         declined: false,
-        content: lines.join('\n'),
+        content,
     };
 }
 
@@ -4245,9 +4272,8 @@ function getServiceUrl(serviceName, consumerName) {
     if (coreUrl)
         return coreUrl;
     // 3. Fall back to port constants
-    const port = DEFAULT_PORTS[serviceName];
-    if (port !== undefined) {
-        return `http://127.0.0.1:${String(port)}`;
+    if (serviceName in DEFAULT_PORTS) {
+        return `http://127.0.0.1:${String(DEFAULT_PORTS[serviceName])}`;
     }
     throw new Error(`jeeves-core: unknown service "${serviceName}" and no config found`);
 }
@@ -4571,6 +4597,7 @@ function readFileOrEmpty(filePath) {
  */
 async function runHeartbeatCycle(options) {
     const { workspacePath, coreConfigDir, configRoot } = options;
+    const wsConfig = options.workspaceConfig ?? loadWorkspaceConfig(workspacePath);
     const heartbeatPath = join(workspacePath, WORKSPACE_FILES.heartbeat);
     try {
         const existingContent = readFileOrEmpty(heartbeatPath);
@@ -4583,14 +4610,11 @@ async function runHeartbeatCycle(options) {
         });
         // Memory hygiene check (Decision 49)
         if (!declinedNames.has(MEMORY_HEARTBEAT_NAME)) {
-            const wsConfig = loadWorkspaceConfig(workspacePath);
             const memoryEntry = checkMemoryHealth({
                 workspacePath,
                 budget: wsConfig?.memory?.budget ?? WORKSPACE_CONFIG_DEFAULTS.memory.budget,
                 warningThreshold: wsConfig?.memory?.warningThreshold ??
                     WORKSPACE_CONFIG_DEFAULTS.memory.warningThreshold,
-                staleDays: wsConfig?.memory?.staleDays ??
-                    WORKSPACE_CONFIG_DEFAULTS.memory.staleDays,
             });
             if (memoryEntry)
                 entries.push(memoryEntry);
@@ -4644,6 +4668,7 @@ class ComponentWriter {
     gatewayUrl;
     pendingCleanups = new Set();
     cyclePromise;
+    stopped = false;
     /** @internal */
     constructor(component, options) {
         this.component = component;
@@ -4669,6 +4694,7 @@ class ComponentWriter {
      * contention on startup.
      */
     start() {
+        this.stopped = false;
         if (this.isRunning)
             return;
         // Random jitter up to one full interval to spread initial writes
@@ -4681,6 +4707,7 @@ class ComponentWriter {
     }
     /** Stop the writer timer. */
     stop() {
+        this.stopped = true;
         if (this.jitterTimeout) {
             clearTimeout(this.jitterTimeout);
             this.jitterTimeout = undefined;
@@ -4694,7 +4721,7 @@ class ComponentWriter {
         this.timer = setTimeout(() => {
             this.timer = undefined;
             void this.cycle().finally(() => {
-                if (this.isRunning)
+                if (!this.stopped)
                     this.scheduleNextCycle(intervalMs, intervalMs);
             });
         }, delayMs);
@@ -4729,15 +4756,18 @@ class ComponentWriter {
                     markers: TOOLS_MARKERS,
                     coreVersion: CORE_VERSION,
                 });
-                // 2. Platform content maintenance
+                // 2. Load workspace config once for the entire cycle
+                const workspaceConfig = loadWorkspaceConfig(workspacePath);
+                // 3. Platform content maintenance
                 await refreshPlatformContent({
                     coreVersion: CORE_VERSION,
                     componentName: this.component.name,
                     componentVersion: this.component.version,
                     servicePackage: this.component.servicePackage,
                     pluginPackage: this.component.pluginPackage,
+                    workspaceConfig,
                 });
-                // 3. Cleanup escalation
+                // 4. Cleanup escalation
                 if (this.gatewayUrl) {
                     scanAndEscalateCleanup([
                         { filePath: toolsPath, markerIdentity: 'TOOLS' },
@@ -4751,11 +4781,12 @@ class ComponentWriter {
                         },
                     ], this.gatewayUrl, this.pendingCleanups);
                 }
-                // 4. HEARTBEAT orchestration
+                // 5. HEARTBEAT orchestration
                 await runHeartbeatCycle({
                     workspacePath,
                     coreConfigDir: getCoreConfigDir(),
                     configRoot: getConfigRoot(),
+                    workspaceConfig,
                 });
             });
         }
@@ -4803,7 +4834,12 @@ class ComponentWriter {
  */
 function createAsyncContentCache(options) {
     const { fetch: fetchContent, placeholder = '> Initializing...', onError = (err) => {
-        console.warn('[jeeves] async content cache refresh failed:', err);
+        if (isTransientError(err)) {
+            console.warn(`[jeeves] cache refresh: transient error (${getErrorMessage(err)})`);
+        }
+        else {
+            console.warn('[jeeves] cache refresh failed:', err);
+        }
     }, } = options;
     let cached = placeholder;
     let refreshing = false;
@@ -5323,4 +5359,4 @@ async function getChannelWorkspace(channelId, token, options) {
     return teamId;
 }
 
-export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_BIND_ADDRESS, DEFAULT_CORE_VERSION, DEFAULT_PORTS, HEARTBEAT_HEADING, JEEVES_SKILL_DIR, MEMORY_HEARTBEAT_NAME, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SKILLS_DIR, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_CONFIG_DEFAULTS, WORKSPACE_CONFIG_FILE, WORKSPACE_FILES, analyzeMemory, appendJsonl, atomicWrite, buildEffectiveConfig, buildHeartbeatSection, checkMemoryHealth, checkNodeVersion, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, extractMostRecentDate, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, generateWorkspaceJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getPackageRoot, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, jaccard, jeevesComponentDescriptorSchema, loadEnvFile, loadWorkspaceConfig, needsCleanup, nowIso, ok, orchestrateHeartbeat, parseArgs, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, readJson, readJsonl, refreshPlatformContent, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveConfigValue, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, run, runScript, runWithRetry, saveCache, seedContent, seedSkill, shingles, shouldWrite, sleepAsync, sleepMs, updateManagedSection, uuid, withFileLock, workspaceConfigSchema, writeComponentVersion, writeHeartbeatSection, writeJsonAtomic, writeJsonl };
+export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_BIND_ADDRESS, DEFAULT_CORE_VERSION, DEFAULT_PORTS, HEARTBEAT_HEADING, JEEVES_SKILL_DIR, MEMORY_HEARTBEAT_NAME, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SKILLS_DIR, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_CONFIG_DEFAULTS, WORKSPACE_CONFIG_FILE, WORKSPACE_FILES, analyzeMemory, appendJsonl, atomicWrite, buildEffectiveConfig, buildHeartbeatSection, checkMemoryHealth, checkNodeVersion, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, generateWorkspaceJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getComponentConfigPath, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getErrorMessage, getPackageRoot, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, isTransientError, jaccard, jeevesComponentDescriptorSchema, loadEnvFile, loadWorkspaceConfig, needsCleanup, nowIso, ok, orchestrateHeartbeat, parseArgs, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, readJson, readJsonl, refreshPlatformContent, registerComponentConfigPath, 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 };

package/package.json

@@ -14,16 +14,17 @@
   },
   "dependencies": {
     "commander": "^14.0.3",
+    "handlebars": "^4.7.9",
     "jsonpath-plus": "^10.4.0",
     "package-directory": "^8.2.0",
     "proper-lockfile": "^4.1.2",
     "semver": "^7.7.4",
-    "zod": "^4.3.6"
+    "zod": "^4.4.2"
   },
   "description": "Shared library and CLI for the Jeeves AI assistant platform.",
   "devDependencies": {
     "@commander-js/extra-typings": "^14.0.0",
-    "@dotenvx/dotenvx": "^1.59.1",
+    "@dotenvx/dotenvx": "^1.64.0",
     "@eslint/js": "^10.0.1",
     "@rollup/plugin-alias": "^6.0.0",
     "@rollup/plugin-commonjs": "^29.0.2",
@@ -32,33 +33,33 @@
     "@rollup/plugin-replace": "^6.0.3",
     "@rollup/plugin-typescript": "^12.3.0",
     "@types/fs-extra": "^11.0.4",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.6.0",
     "@types/proper-lockfile": "^4.1.4",
     "@types/semver": "^7.7.1",
-    "@vitest/coverage-v8": "^4.1.2",
-    "@vitest/eslint-plugin": "^1.6.13",
+    "@vitest/coverage-v8": "^4.1.5",
+    "@vitest/eslint-plugin": "^1.6.16",
     "auto-changelog": "^2.5.0",
     "cross-env": "^10.1.0",
-    "eslint": "^10.1.0",
+    "eslint": "^10.3.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5",
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "eslint-plugin-tsdoc": "^0.5.2",
     "fs-extra": "^11.3.4",
-    "knip": "^6.1.0",
-    "lefthook": "^2.1.4",
-    "prettier": "^3.8.1",
+    "knip": "^6.11.0",
+    "lefthook": "^2.1.6",
+    "prettier": "^3.8.3",
     "release-it": "^19.2.4",
     "rimraf": "^6.1.3",
-    "rollup": "^4.60.1",
+    "rollup": "^4.60.2",
     "rollup-plugin-dts": "^6.4.1",
     "tslib": "^2.8.1",
-    "typedoc": "^0.28.18",
+    "typedoc": "^0.28.19",
     "typedoc-plugin-mdn-links": "^5.1.1",
     "typedoc-plugin-replace-text": "^4.2.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.57.2",
-    "vitest": "^4.1.2"
+    "typescript-eslint": "^8.59.1",
+    "vitest": "^4.1.5"
   },
   "engines": {
     "node": ">=22"
@@ -139,5 +140,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.5.7"
+  "version": "0.5.9"
 }