clementine-agent 1.18.141 → 1.18.143

package/dist/cli/dashboard.js

@@ -39309,11 +39309,23 @@ async function refreshWorkflows() {
     var r = await apiFetch('/api/workflows');
     var data = await r.json();
     var workflows = data.workflows || [];
+    // 1.18.142 — Soft-deprecation banner. Always shown when there's at least
+    // one workflow on disk, hidden when the user has fully migrated. New
+    // users who never had workflows in the first place see a different empty
+    // state pointing them at Skills.
+    var banner = '';
+    if (workflows.length > 0) {
+      banner = '<div class="card" style="margin-bottom:14px;padding:12px 14px;background:var(--accent-glow);border-left:3px solid var(--accent)">' +
+        '<div style="font-weight:600;margin-bottom:4px">Workflows are being phased out → Skills</div>' +
+        '<div style="font-size:13px;color:var(--text-secondary);line-height:1.5">' +
+        'Skills cover the same use cases with better composability and the new builder. Use the <strong>Migrate</strong> button on any workflow row below to convert it into a vanilla Anthropic skill folder. Your existing workflows keep firing until you migrate them — nothing breaks.' +
+        '</div></div>';
+    }
     if (workflows.length === 0) {
-      containers.forEach(function(c) { c.innerHTML = '<div class="empty-state">No workflows defined. Create .md files in vault/00-System/workflows/</div>'; });
+      containers.forEach(function(c) { c.innerHTML = '<div class="empty-state">No workflows defined. <strong>Skills are the way forward</strong> — create one from the Skills tab. Workflow .md files in vault/00-System/workflows/ still work for legacy setups.</div>'; });
       return;
     }
-    var html = '';
+    var html = banner;
     workflows.forEach(function(wf) {
       var triggerLabel = wf.trigger && wf.trigger.schedule ? describeCron(wf.trigger.schedule) || wf.trigger.schedule : 'Manual only';
       var stepCount = wf.steps ? wf.steps.length : 0;
@@ -39324,6 +39336,7 @@ async function refreshWorkflows() {
       html += '<span class="badge ' + (wf.enabled ? 'badge-green' : 'badge-gray') + '" style="font-size:10px">' + (wf.enabled ? 'Enabled' : 'Disabled') + '</span>';
       html += '<button class="btn btn-sm" onclick="runWorkflow(\\x27' + esc(wf.name) + '\\x27)" style="font-size:10px;color:var(--green)">Run</button>';
       html += '<button class="btn btn-sm" onclick="showWorkflowRuns(\\x27' + esc(wf.name) + '\\x27)" style="font-size:10px">History</button>';
+      html += '<button class="btn btn-sm" onclick="migrateWorkflowToSkill(\\x27' + esc(wf.name) + '\\x27)" style="font-size:10px;color:var(--accent)" title="Convert this workflow into a vanilla Anthropic skill folder. Original is renamed to .md.migrated, kept on disk for rollback.">Migrate → Skill</button>';
       html += '</div>';
       html += '<div class="card-body">';
       if (wf.description) html += '<div style="font-size:13px;color:var(--text-secondary);margin-bottom:8px">' + esc(wf.description) + '</div>';
@@ -39367,6 +39380,30 @@ async function runWorkflow(name) {
   } catch(e) { toast(String(e), 'error'); }
 }
 
+// 1.18.142 — Convert a workflow into a vanilla skill folder, then refresh
+// the list so the migrated workflow disappears (its .md is renamed to
+// .md.migrated server-side and parseAllWorkflows stops picking it up).
+async function migrateWorkflowToSkill(name) {
+  if (!confirm('Migrate "' + name + '" into a skill folder?\n\n' +
+    '• A new skill will be created at vault/00-System/skills/<slug>/SKILL.md\n' +
+    '• The original workflow .md will be renamed to .md.migrated (kept for rollback)\n' +
+    '• The workflow stops firing; the skill is ready to schedule from the Skills tab')) return;
+  try {
+    var r = await apiFetch('/api/workflows/' + encodeURIComponent(name) + '/migrate-to-skill', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+    var d = await r.json();
+    if (d.ok) {
+      toast('Migrated "' + name + '" → skill "' + (d.skill && d.skill.name || '?') + '"' + (d.warning ? ' (' + d.warning + ')' : ''));
+      refreshWorkflows();
+    } else {
+      toast(d.error || 'Migration failed', 'error');
+    }
+  } catch(e) { toast(String(e), 'error'); }
+}
+
 async function showWorkflowRuns(name) {
   var safeId = 'wf-runs-' + name.replace(/[^a-zA-Z0-9]/g, '_');
   var panel = document.getElementById(safeId);

package/dist/cli/routes/workflows.js

@@ -3,7 +3,7 @@
  */
 import { Router } from 'express';
 import express from 'express';
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, renameSync } from 'node:fs';
 import path from 'node:path';
 export function workflowsRouter(deps) {
     const router = Router();
@@ -68,6 +68,104 @@ export function workflowsRouter(deps) {
             res.status(500).json({ ok: false, error: String(e) });
         }
     });
+    /**
+     * 1.18.142 — Migrate a workflow into a vanilla Anthropic skill folder.
+     *
+     * Skills are subsuming workflows. To let users move at their own pace
+     * without breaking the workflow runtime, this endpoint converts ONE
+     * workflow at a time and renames the original .md → .md.migrated so
+     * the workflow runner stops picking it up but the file is still on
+     * disk for rollback.
+     *
+     * Conversion: workflow.name → skill name (slugified to Anthropic
+     * regex), workflow.description → skill description, raw workflow
+     * markdown body → skill procedure body (steps + synthesis prompt are
+     * preserved as documentation; runtime is the SDK reading the body).
+     * Frontmatter is rebuilt from scratch by writeSkill, so legacy
+     * workflow YAML doesn't leak into the new skill.
+     */
+    router.post('/:name/migrate-to-skill', express.json(), async (req, res) => {
+        try {
+            const name = decodeURIComponent(req.params.name);
+            const { parseAllWorkflows } = await import('../../agent/workflow-runner.js');
+            const { writeSkill } = await import('../../agent/skill-store.js');
+            const matter = (await import('gray-matter')).default;
+            // Find the workflow across global + agent scopes
+            const candidates = [];
+            if (existsSync(workflowsDir)) {
+                for (const wf of parseAllWorkflows(workflowsDir)) {
+                    if (wf.name === name)
+                        candidates.push({ wf });
+                }
+            }
+            if (existsSync(agentsBase)) {
+                for (const slug of readdirSync(agentsBase).filter(d => !d.startsWith('_'))) {
+                    const wfDir = path.join(agentsBase, slug, 'workflows');
+                    if (!existsSync(wfDir))
+                        continue;
+                    for (const wf of parseAllWorkflows(wfDir)) {
+                        if (wf.name === name)
+                            candidates.push({ wf, agentSlug: slug });
+                    }
+                }
+            }
+            if (candidates.length === 0) {
+                res.status(404).json({ ok: false, error: 'Workflow not found: ' + name });
+                return;
+            }
+            const { wf, agentSlug } = candidates[0];
+            // Slugify the workflow name to the Anthropic regex
+            const slug = name.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 64);
+            if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(slug)) {
+                res.status(400).json({ ok: false, error: `Workflow name "${name}" cannot be slugified to Anthropic regex` });
+                return;
+            }
+            // Build the skill body from the workflow's raw markdown body. The
+            // workflow runner's frontmatter is dropped — writeSkill rebuilds
+            // a clementine.* block from scratch. Steps and synthesis live as
+            // markdown for the SDK to read directly.
+            const raw = readFileSync(wf.sourceFile, 'utf-8');
+            const parsed = matter(raw);
+            const body = parsed.content.trim() || `Migrated from workflow "${name}". Add a procedure here.`;
+            const description = wf.description || `Migrated from workflow ${name}`;
+            let written;
+            try {
+                written = writeSkill({
+                    name: slug,
+                    title: wf.name,
+                    description,
+                    body,
+                    source: 'imported',
+                    agentSlug,
+                });
+            }
+            catch (err) {
+                res.status(409).json({ ok: false, error: String(err instanceof Error ? err.message : err) });
+                return;
+            }
+            // Rename the original .md → .md.migrated so parseAllWorkflows
+            // stops picking it up. File stays on disk for rollback.
+            const migratedPath = wf.sourceFile + '.migrated';
+            try {
+                renameSync(wf.sourceFile, migratedPath);
+            }
+            catch (err) {
+                // Skill is already written; surface the rename failure but don't
+                // roll back — the user can manually delete the .md if needed.
+                res.json({
+                    ok: true,
+                    skill: written,
+                    warning: `Skill created but original workflow file rename failed: ${String(err)}`,
+                });
+                return;
+            }
+            broadcastEvent({ type: 'workflow_migrated', data: { workflowName: name, skillSlug: slug, agentSlug } });
+            res.json({ ok: true, skill: written, originalRenamedTo: migratedPath });
+        }
+        catch (e) {
+            res.status(500).json({ ok: false, error: String(e) });
+        }
+    });
     router.get('/:name/runs', (_req, res) => {
         try {
             const name = decodeURIComponent(_req.params.name);

package/dist/gateway/agent-heartbeat-scheduler.d.ts

@@ -3,6 +3,18 @@
  * the user's team. Runs autonomously alongside Clementine's own
  * HeartbeatScheduler.
  *
+ * Why this is its own scheduler (NOT a unified base class):
+ *   - It has NO loop. Unlike HeartbeatScheduler (setInterval) and
+ *     CronScheduler (node-cron), this one is ticked externally by
+ *     whatever orchestrator manages the agent fleet. Its `tick()` is a
+ *     pure function of state + signals.
+ *   - Its scheduling decision is *adaptive* (computeNextInterval) based
+ *     on the previous tick's outcome — not a fixed cadence. Forcing it
+ *     into a generic "interval-based" base would lose this behavior.
+ *
+ * Shared with the other schedulers: only the JSON state-file load/save
+ * pattern, factored into ./scheduler-state.ts in 1.18.143.
+ *
  * Phase 2 — cheap path only. No LLM call. The tick loads state, scans
  * three signals (pending delegated tasks, recent goal updates, recent
  * cron completions), updates fingerprint, and persists state.

package/dist/gateway/agent-heartbeat-scheduler.js

@@ -3,6 +3,18 @@
  * the user's team. Runs autonomously alongside Clementine's own
  * HeartbeatScheduler.
  *
+ * Why this is its own scheduler (NOT a unified base class):
+ *   - It has NO loop. Unlike HeartbeatScheduler (setInterval) and
+ *     CronScheduler (node-cron), this one is ticked externally by
+ *     whatever orchestrator manages the agent fleet. Its `tick()` is a
+ *     pure function of state + signals.
+ *   - Its scheduling decision is *adaptive* (computeNextInterval) based
+ *     on the previous tick's outcome — not a fixed cadence. Forcing it
+ *     into a generic "interval-based" base would lose this behavior.
+ *
+ * Shared with the other schedulers: only the JSON state-file load/save
+ * pattern, factored into ./scheduler-state.ts in 1.18.143.
+ *
  * Phase 2 — cheap path only. No LLM call. The tick loads state, scans
  * three signals (pending delegated tasks, recent goal updates, recent
  * cron completions), updates fingerprint, and persists state.
@@ -11,11 +23,12 @@
  * agent's profile) when the fingerprint indicates a real signal change.
  */
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync, } from 'node:fs';
 import path from 'node:path';
 import pino from 'pino';
 import { AGENTS_DIR, BASE_DIR } from '../config.js';
 import { listAllGoals } from '../tools/shared.js';
+import { loadStateFile, saveStateFile } from './scheduler-state.js';
 const logger = pino({ name: 'clementine.agent-heartbeat' });
 const DEFAULT_INTERVAL_MIN = 30;
 const MIN_INTERVAL_MIN = 5;
@@ -81,43 +94,32 @@ export class AgentHeartbeatScheduler {
     }
     /** Read persisted state, or return a fresh state ready to tick now. */
     loadState() {
-        try {
-            if (existsSync(this.stateFile)) {
-                const raw = JSON.parse(readFileSync(this.stateFile, 'utf-8'));
-                const validKinds = ['acted', 'quiet', 'silent', 'override'];
-                const kind = validKinds.includes(raw.lastTickKind)
-                    ? raw.lastTickKind
-                    : undefined;
-                return {
-                    slug: this.slug,
-                    lastTickAt: String(raw.lastTickAt ?? ''),
-                    nextCheckAt: String(raw.nextCheckAt ?? new Date().toISOString()),
-                    silentTickCount: Number(raw.silentTickCount ?? 0),
-                    fingerprint: String(raw.fingerprint ?? ''),
-                    ...(raw.lastSignalSummary ? { lastSignalSummary: raw.lastSignalSummary } : {}),
-                    ...(kind ? { lastTickKind: kind } : {}),
-                };
-            }
-        }
-        catch (err) {
-            logger.warn({ err, slug: this.slug }, 'Failed to load agent heartbeat state — starting fresh');
-        }
-        return {
+        const fresh = {
             slug: this.slug,
             lastTickAt: '',
             nextCheckAt: new Date().toISOString(),
             silentTickCount: 0,
             fingerprint: '',
         };
+        return loadStateFile(this.stateFile, fresh, (raw) => {
+            const r = raw;
+            const validKinds = ['acted', 'quiet', 'silent', 'override'];
+            const kind = validKinds.includes(r.lastTickKind)
+                ? r.lastTickKind
+                : undefined;
+            return {
+                slug: this.slug,
+                lastTickAt: String(r.lastTickAt ?? ''),
+                nextCheckAt: String(r.nextCheckAt ?? new Date().toISOString()),
+                silentTickCount: Number(r.silentTickCount ?? 0),
+                fingerprint: String(r.fingerprint ?? ''),
+                ...(r.lastSignalSummary ? { lastSignalSummary: r.lastSignalSummary } : {}),
+                ...(kind ? { lastTickKind: kind } : {}),
+            };
+        });
     }
     saveState(state) {
-        try {
-            mkdirSync(path.dirname(this.stateFile), { recursive: true });
-            writeFileSync(this.stateFile, JSON.stringify(state, null, 2));
-        }
-        catch (err) {
-            logger.warn({ err, slug: this.slug }, 'Failed to save agent heartbeat state — non-fatal');
-        }
+        saveStateFile(this.stateFile, state);
     }
     /** True if the agent is due for a tick. */
     isDue(now = new Date()) {

package/dist/gateway/cron-scheduler.d.ts

@@ -1,10 +1,28 @@
 /**
  * Clementine TypeScript — Cron scheduler (autonomous execution).
  *
- * CronScheduler: precise scheduled tasks using node-cron
+ * CronScheduler: precise per-job scheduled tasks using node-cron. Each
+ * cron job (defined in CRON.md or via the schedule registry) gets its
+ * own ScheduledTask instance with that job's cron expression, so the
+ * scheduling primitive here is fundamentally different from the
+ * fixed-interval HeartbeatScheduler and the externally-ticked
+ * AgentHeartbeatScheduler.
  *
- * Also contains shared parsers (parseCronJobs, parseAgentCronJobs, validateCronYaml),
- * retry helpers, CronRunLog, and daily-note logging utilities used by both schedulers.
+ * Why this is its own scheduler (NOT a unified base class):
+ *   - One node-cron task per job. CronScheduler maintains the
+ *     scheduledTasks/workflowTasks maps; a generic base class would
+ *     have to model "N independent timers" which the other two don't
+ *     need.
+ *   - Owns crash-safe idempotency (cron-running.json), workflow
+ *     execution, file watching, trigger directories, broken-job
+ *     tracking. None of these belong in a generic base.
+ *
+ * Also contains shared parsers (parseCronJobs, parseAgentCronJobs,
+ * validateCronYaml), retry helpers, CronRunLog, and daily-note logging
+ * utilities used by both schedulers.
+ *
+ * Shared with the other schedulers: only the JSON state-file load/save
+ * pattern, factored into ./scheduler-state.ts in 1.18.143.
  */
 import type { CronJobDefinition, CronRunEntry, SelfImproveConfig, SelfImproveExperiment, SelfImproveState, WorkflowDefinition } from '../types.js';
 import type { NotificationDispatcher } from './notifications.js';

package/dist/gateway/cron-scheduler.js

@@ -1,13 +1,31 @@
 /**
  * Clementine TypeScript — Cron scheduler (autonomous execution).
  *
- * CronScheduler: precise scheduled tasks using node-cron
+ * CronScheduler: precise per-job scheduled tasks using node-cron. Each
+ * cron job (defined in CRON.md or via the schedule registry) gets its
+ * own ScheduledTask instance with that job's cron expression, so the
+ * scheduling primitive here is fundamentally different from the
+ * fixed-interval HeartbeatScheduler and the externally-ticked
+ * AgentHeartbeatScheduler.
  *
- * Also contains shared parsers (parseCronJobs, parseAgentCronJobs, validateCronYaml),
- * retry helpers, CronRunLog, and daily-note logging utilities used by both schedulers.
+ * Why this is its own scheduler (NOT a unified base class):
+ *   - One node-cron task per job. CronScheduler maintains the
+ *     scheduledTasks/workflowTasks maps; a generic base class would
+ *     have to model "N independent timers" which the other two don't
+ *     need.
+ *   - Owns crash-safe idempotency (cron-running.json), workflow
+ *     execution, file watching, trigger directories, broken-job
+ *     tracking. None of these belong in a generic base.
+ *
+ * Also contains shared parsers (parseCronJobs, parseAgentCronJobs,
+ * validateCronYaml), retry helpers, CronRunLog, and daily-note logging
+ * utilities used by both schedulers.
+ *
+ * Shared with the other schedulers: only the JSON state-file load/save
+ * pattern, factored into ./scheduler-state.ts in 1.18.143.
  */
 import { execSync } from 'node:child_process';
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, watchFile, unwatchFile, writeFileSync, } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, watchFile, unwatchFile, writeFileSync, } from 'node:fs';
 import path from 'node:path';
 import cron from 'node-cron';
 import matter from 'gray-matter';
@@ -15,6 +33,7 @@ import pino from 'pino';
 import { CRON_FILE, WORKFLOWS_DIR, AGENTS_DIR, DAILY_NOTES_DIR, BASE_DIR, DISCORD_OWNER_ID, GOALS_DIR, CRON_REFLECTIONS_DIR, ADVISOR_LOG_PATH, TIMEZONE, } from '../config.js';
 import { listAllGoals, findGoalPath, readGoalById } from '../tools/shared.js';
 import { listSchedules } from '../agent/schedule-registry.js';
+import { saveStateFile } from './scheduler-state.js';
 import { scanner } from '../security/scanner.js';
 import { parseAllWorkflows as parseAllWorkflowsSync } from '../agent/workflow-runner.js';
 import { SelfImproveLoop } from '../agent/self-improve.js';
@@ -579,20 +598,13 @@ export class CronScheduler {
      * rename so a crash mid-write cannot corrupt the file.
      */
     persistRunningJobs(metaByName) {
-        try {
-            const entries = [...this.runningJobs].map(name => ({
-                jobName: name,
-                startedAt: metaByName?.get(name)?.startedAt ?? new Date().toISOString(),
-                runId: metaByName?.get(name)?.runId ?? '',
-                pid: process.pid,
-            }));
-            const tmp = CronScheduler.RUNNING_JOBS_FILE + '.tmp';
-            writeFileSync(tmp, JSON.stringify(entries, null, 2));
-            renameSync(tmp, CronScheduler.RUNNING_JOBS_FILE);
-        }
-        catch (err) {
-            logger.debug({ err }, 'Failed to persist running-jobs file');
-        }
+        const entries = [...this.runningJobs].map(name => ({
+            jobName: name,
+            startedAt: metaByName?.get(name)?.startedAt ?? new Date().toISOString(),
+            runId: metaByName?.get(name)?.runId ?? '',
+            pid: process.pid,
+        }));
+        saveStateFile(CronScheduler.RUNNING_JOBS_FILE, entries, { atomic: true });
     }
     /**
      * On startup, read the persisted running-jobs file. Any entries present

package/dist/gateway/heartbeat-scheduler.d.ts

@@ -1,8 +1,21 @@
 /**
  * Clementine TypeScript — Heartbeat scheduler.
  *
- * HeartbeatScheduler: periodic general check-ins using setInterval.
- * Channel-agnostic — sends notifications via the NotificationDispatcher.
+ * HeartbeatScheduler: periodic general check-ins using setInterval
+ * (one tick every HEARTBEAT_INTERVAL_MINUTES, default 30 min, gated to
+ * the HEARTBEAT_ACTIVE_START..ACTIVE_END window). Channel-agnostic —
+ * sends notifications via the NotificationDispatcher.
+ *
+ * Why this is its own scheduler (NOT a unified base class):
+ *   - It uses a fixed setInterval. Different scheduling primitive than
+ *     CronScheduler (which uses node-cron per-job) and AgentHeartbeat
+ *     Scheduler (which is ticked externally — has no loop of its own).
+ *   - It owns autonomous concerns: insight engine, proactive ledger,
+ *     dense-vector backfill, salience decay, episodic consolidation.
+ *     None of these belong in a generic scheduler base.
+ *
+ * Shared with the other two schedulers: only the JSON state-file
+ * load/save pattern, factored into ./scheduler-state.ts in 1.18.143.
  */
 import type { HeartbeatWorkItem } from '../types.js';
 import type { CronScheduler } from './cron-scheduler.js';

package/dist/gateway/heartbeat-scheduler.js

@@ -1,8 +1,21 @@
 /**
  * Clementine TypeScript — Heartbeat scheduler.
  *
- * HeartbeatScheduler: periodic general check-ins using setInterval.
- * Channel-agnostic — sends notifications via the NotificationDispatcher.
+ * HeartbeatScheduler: periodic general check-ins using setInterval
+ * (one tick every HEARTBEAT_INTERVAL_MINUTES, default 30 min, gated to
+ * the HEARTBEAT_ACTIVE_START..ACTIVE_END window). Channel-agnostic —
+ * sends notifications via the NotificationDispatcher.
+ *
+ * Why this is its own scheduler (NOT a unified base class):
+ *   - It uses a fixed setInterval. Different scheduling primitive than
+ *     CronScheduler (which uses node-cron per-job) and AgentHeartbeat
+ *     Scheduler (which is ticked externally — has no loop of its own).
+ *   - It owns autonomous concerns: insight engine, proactive ledger,
+ *     dense-vector backfill, salience decay, episodic consolidation.
+ *     None of these belong in a generic scheduler base.
+ *
+ * Shared with the other two schedulers: only the JSON state-file
+ * load/save pattern, factored into ./scheduler-state.ts in 1.18.143.
  */
 import { createHash, randomBytes } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
@@ -11,6 +24,7 @@ import matter from 'gray-matter';
 import pino from 'pino';
 import { HEARTBEAT_FILE, TASKS_FILE, INBOX_DIR, DAILY_NOTES_DIR, HEARTBEAT_INTERVAL_MINUTES, HEARTBEAT_ACTIVE_START, HEARTBEAT_ACTIVE_END, BASE_DIR, GOALS_DIR, AGENTS_DIR, HEARTBEAT_WORK_QUEUE_FILE, DISCORD_OWNER_ID, } from '../config.js';
 import { findGoalPath, listAllGoals } from '../tools/shared.js';
+import { loadStateFile, saveStateFile } from './scheduler-state.js';
 import { gatherInsightSignals, buildInsightPrompt, parseInsightResponse, canSendInsight, recordInsightSent, recordInsightAcked, maybeIncreaseCooldown, } from '../agent/insight-engine.js';
 import { decideDailyPlanPriority, decideDiscoveredWorkItem, decideGoalAdvancement, decisionShouldCreateGoalTrigger, decisionShouldQueueHeartbeatWork, } from '../agent/proactive-engine.js';
 import { recentDecisions, recordDecision, recordDecisionOutcome, wasRecentlyDecided, } from '../agent/proactive-ledger.js';
@@ -1144,23 +1158,10 @@ export class HeartbeatScheduler {
         return parsed.content;
     }
     loadState() {
-        if (existsSync(this.stateFile)) {
-            try {
-                return JSON.parse(readFileSync(this.stateFile, 'utf-8'));
-            }
-            catch {
-                logger.warn('Failed to load heartbeat state — starting fresh');
-            }
-        }
-        return { fingerprint: '', details: {}, timestamp: '' };
+        return loadStateFile(this.stateFile, { fingerprint: '', details: {}, timestamp: '' });
     }
     saveState() {
-        try {
-            writeFileSync(this.stateFile, JSON.stringify(this.lastState, null, 2));
-        }
-        catch (err) {
-            logger.warn({ err }, 'Failed to save heartbeat state');
-        }
+        saveStateFile(this.stateFile, this.lastState);
     }
     computeStateFingerprint() {
         const details = {};

package/dist/gateway/scheduler-state.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Scheduler state-file helpers (1.18.143)
+ *
+ * Three schedulers each persist a JSON state file (heartbeat,
+ * cron-running-jobs, per-agent heartbeat). Before this module they
+ * each reimplemented "try parse, fall back on error" + "write JSON,
+ * log on error". The patterns are tiny but they were drifting (some
+ * had `mkdirSync`, some had atomic write-then-rename, some had
+ * neither — and a future addition would have copied yet another
+ * variant).
+ *
+ * This module is the single source of truth for both shapes:
+ *
+ *   loadStateFile(path, default, validator?)
+ *     — read JSON, fall back to default on missing/invalid file,
+ *       optionally run a validator that can clean/coerce the parsed
+ *       payload before returning it.
+ *
+ *   saveStateFile(path, state, opts)
+ *     — ensure parent dir exists, then either plain
+ *       writeFileSync (default) or atomic write-then-rename for
+ *       crash-safe persistence (set `atomic: true`).
+ *
+ * Both swallow filesystem errors and log a warning — the schedulers
+ * treat persistence as best-effort (a missing/corrupt state file
+ * means "start fresh", not "crash"). Callers that need failure
+ * surfaced should check the boolean return on saveStateFile.
+ */
+/**
+ * Read a JSON state file. Returns `defaultValue` if the file is
+ * missing, unreadable, or fails JSON parse. Optional validator runs
+ * after parse and can return a cleaned-up version (e.g. coerce
+ * missing fields, drop invalid values).
+ */
+export declare function loadStateFile<T>(filePath: string, defaultValue: T, validator?: (raw: unknown) => T): T;
+export interface SaveStateOptions {
+    /**
+     * If true, write to `<file>.tmp` then rename — guarantees the on-disk
+     * file is either the previous state or the new state, never a half-
+     * written file. Use for state that must survive crashes mid-write
+     * (cron-running.json relies on this for idempotency).
+     */
+    atomic?: boolean;
+}
+/**
+ * Write a JSON state file. Creates the parent directory if missing.
+ * Returns true on success, false on failure (always logs a warning
+ * on failure — caller doesn't need to log again).
+ */
+export declare function saveStateFile<T>(filePath: string, state: T, opts?: SaveStateOptions): boolean;
+//# sourceMappingURL=scheduler-state.d.ts.map

package/dist/gateway/scheduler-state.js

@@ -0,0 +1,75 @@
+/**
+ * Scheduler state-file helpers (1.18.143)
+ *
+ * Three schedulers each persist a JSON state file (heartbeat,
+ * cron-running-jobs, per-agent heartbeat). Before this module they
+ * each reimplemented "try parse, fall back on error" + "write JSON,
+ * log on error". The patterns are tiny but they were drifting (some
+ * had `mkdirSync`, some had atomic write-then-rename, some had
+ * neither — and a future addition would have copied yet another
+ * variant).
+ *
+ * This module is the single source of truth for both shapes:
+ *
+ *   loadStateFile(path, default, validator?)
+ *     — read JSON, fall back to default on missing/invalid file,
+ *       optionally run a validator that can clean/coerce the parsed
+ *       payload before returning it.
+ *
+ *   saveStateFile(path, state, opts)
+ *     — ensure parent dir exists, then either plain
+ *       writeFileSync (default) or atomic write-then-rename for
+ *       crash-safe persistence (set `atomic: true`).
+ *
+ * Both swallow filesystem errors and log a warning — the schedulers
+ * treat persistence as best-effort (a missing/corrupt state file
+ * means "start fresh", not "crash"). Callers that need failure
+ * surfaced should check the boolean return on saveStateFile.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import pino from 'pino';
+const logger = pino({ name: 'clementine.scheduler-state' });
+/**
+ * Read a JSON state file. Returns `defaultValue` if the file is
+ * missing, unreadable, or fails JSON parse. Optional validator runs
+ * after parse and can return a cleaned-up version (e.g. coerce
+ * missing fields, drop invalid values).
+ */
+export function loadStateFile(filePath, defaultValue, validator) {
+    try {
+        if (!existsSync(filePath))
+            return defaultValue;
+        const raw = JSON.parse(readFileSync(filePath, 'utf-8'));
+        return validator ? validator(raw) : raw;
+    }
+    catch (err) {
+        logger.warn({ err, filePath }, 'Failed to load state file — starting fresh');
+        return defaultValue;
+    }
+}
+/**
+ * Write a JSON state file. Creates the parent directory if missing.
+ * Returns true on success, false on failure (always logs a warning
+ * on failure — caller doesn't need to log again).
+ */
+export function saveStateFile(filePath, state, opts = {}) {
+    try {
+        mkdirSync(path.dirname(filePath), { recursive: true });
+        const json = JSON.stringify(state, null, 2);
+        if (opts.atomic) {
+            const tmp = filePath + '.tmp';
+            writeFileSync(tmp, json);
+            renameSync(tmp, filePath);
+        }
+        else {
+            writeFileSync(filePath, json);
+        }
+        return true;
+    }
+    catch (err) {
+        logger.warn({ err, filePath }, 'Failed to save state file');
+        return false;
+    }
+}
+//# sourceMappingURL=scheduler-state.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.18.141",
+  "version": "1.18.143",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",