discoclaw 0.1.0

package/dist/cron/run-stats.js

@@ -0,0 +1,265 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+export const CADENCE_TAGS = ['yearly', 'frequent', 'hourly', 'daily', 'weekly', 'monthly'];
+export const CURRENT_VERSION = 3;
+// ---------------------------------------------------------------------------
+// Stable Cron ID generation
+// ---------------------------------------------------------------------------
+export function generateCronId() {
+    return `cron-${crypto.randomBytes(4).toString('hex')}`;
+}
+export function parseCronIdFromContent(content) {
+    const match = content.match(/\[cronId:(cron-[a-f0-9]+)\]/);
+    return match ? match[1] : null;
+}
+class WriteMutex {
+    queue = [];
+    running = false;
+    async run(fn) {
+        return new Promise((resolve, reject) => {
+            this.queue.push({ fn, resolve, reject });
+            if (!this.running)
+                void this.drain();
+        });
+    }
+    async drain() {
+        this.running = true;
+        while (this.queue.length > 0) {
+            const entry = this.queue.shift();
+            try {
+                await entry.fn();
+                entry.resolve();
+            }
+            catch (err) {
+                entry.reject(err);
+            }
+        }
+        this.running = false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Store implementation
+// ---------------------------------------------------------------------------
+export function emptyStore() {
+    return { version: CURRENT_VERSION, updatedAt: Date.now(), jobs: {} };
+}
+function emptyRecord(cronId, threadId) {
+    return {
+        cronId,
+        threadId,
+        runCount: 0,
+        lastRunAt: null,
+        lastRunStatus: null,
+        cadence: null,
+        purposeTags: [],
+        disabled: false,
+        model: null,
+    };
+}
+export class CronRunStats {
+    store;
+    filePath;
+    mutex = new WriteMutex();
+    // Secondary index: threadId → cronId for O(1) lookups.
+    threadIndex = new Map();
+    // Secondary index: statusMessageId → cronId for O(1) recovery lookups.
+    statusMessageIndex = new Map();
+    // Secondary index: webhookSourceId → cronId for O(1) webhook routing.
+    sourceIndex = new Map();
+    constructor(store, filePath) {
+        this.store = store;
+        this.filePath = filePath;
+        this.rebuildThreadIndex();
+    }
+    rebuildThreadIndex() {
+        this.threadIndex.clear();
+        this.statusMessageIndex.clear();
+        this.sourceIndex.clear();
+        for (const rec of Object.values(this.store.jobs)) {
+            this.threadIndex.set(rec.threadId, rec.cronId);
+            if (rec.statusMessageId) {
+                this.statusMessageIndex.set(rec.statusMessageId, rec.cronId);
+            }
+            if (rec.webhookSourceId) {
+                this.sourceIndex.set(rec.webhookSourceId, rec.cronId);
+            }
+        }
+    }
+    getStore() {
+        return this.store;
+    }
+    getRecord(cronId) {
+        return this.store.jobs[cronId];
+    }
+    getRecordByThreadId(threadId) {
+        const cronId = this.threadIndex.get(threadId);
+        return cronId ? this.store.jobs[cronId] : undefined;
+    }
+    getRecordByStatusMessageId(statusMessageId) {
+        const cronId = this.statusMessageIndex.get(statusMessageId);
+        return cronId ? this.store.jobs[cronId] : undefined;
+    }
+    getRecordBySourceId(sourceId) {
+        const cronId = this.sourceIndex.get(sourceId);
+        return cronId ? this.store.jobs[cronId] : undefined;
+    }
+    async upsertRecord(cronId, threadId, updates) {
+        let record;
+        await this.mutex.run(async () => {
+            // Enforce sourceId uniqueness before mutating state.
+            const incomingSourceId = updates?.webhookSourceId;
+            if (incomingSourceId !== undefined) {
+                const claimant = this.sourceIndex.get(incomingSourceId);
+                if (claimant && claimant !== cronId) {
+                    throw new Error(`webhookSourceId "${incomingSourceId}" is already claimed by cronId "${claimant}"`);
+                }
+            }
+            const existing = this.store.jobs[cronId];
+            if (existing) {
+                const prevStatusMessageId = existing.statusMessageId;
+                const prevSourceId = existing.webhookSourceId;
+                // If threadId changed, remove old index entry.
+                if (existing.threadId !== threadId) {
+                    this.threadIndex.delete(existing.threadId);
+                }
+                if (updates)
+                    Object.assign(existing, updates);
+                existing.threadId = threadId;
+                if (prevStatusMessageId && prevStatusMessageId !== existing.statusMessageId) {
+                    this.statusMessageIndex.delete(prevStatusMessageId);
+                }
+                if (prevSourceId && prevSourceId !== existing.webhookSourceId) {
+                    this.sourceIndex.delete(prevSourceId);
+                }
+                record = existing;
+            }
+            else {
+                record = { ...emptyRecord(cronId, threadId), ...updates };
+                this.store.jobs[cronId] = record;
+            }
+            this.threadIndex.set(threadId, cronId);
+            if (record.statusMessageId) {
+                this.statusMessageIndex.set(record.statusMessageId, cronId);
+            }
+            if (record.webhookSourceId) {
+                this.sourceIndex.set(record.webhookSourceId, cronId);
+            }
+            this.store.updatedAt = Date.now();
+            await this.flush();
+        });
+        return record;
+    }
+    async recordRun(cronId, status, errorMessage) {
+        await this.mutex.run(async () => {
+            const rec = this.store.jobs[cronId];
+            if (!rec)
+                return;
+            rec.runCount++;
+            rec.lastRunAt = new Date().toISOString();
+            rec.lastRunStatus = status;
+            if (status === 'error' && errorMessage) {
+                rec.lastErrorMessage = errorMessage.slice(0, 200);
+            }
+            else {
+                delete rec.lastErrorMessage;
+            }
+            this.store.updatedAt = Date.now();
+            await this.flush();
+        });
+    }
+    async removeRecord(cronId) {
+        let removed = false;
+        await this.mutex.run(async () => {
+            const rec = this.store.jobs[cronId];
+            if (rec) {
+                this.threadIndex.delete(rec.threadId);
+                if (rec.statusMessageId)
+                    this.statusMessageIndex.delete(rec.statusMessageId);
+                if (rec.webhookSourceId)
+                    this.sourceIndex.delete(rec.webhookSourceId);
+                delete this.store.jobs[cronId];
+                this.store.updatedAt = Date.now();
+                removed = true;
+                await this.flush();
+            }
+        });
+        return removed;
+    }
+    async removeByThreadId(threadId) {
+        let removed = false;
+        await this.mutex.run(async () => {
+            for (const [cronId, rec] of Object.entries(this.store.jobs)) {
+                if (rec.threadId === threadId) {
+                    this.threadIndex.delete(threadId);
+                    if (rec.statusMessageId)
+                        this.statusMessageIndex.delete(rec.statusMessageId);
+                    if (rec.webhookSourceId)
+                        this.sourceIndex.delete(rec.webhookSourceId);
+                    delete this.store.jobs[cronId];
+                    removed = true;
+                }
+            }
+            if (removed) {
+                this.store.updatedAt = Date.now();
+                await this.flush();
+            }
+        });
+        return removed;
+    }
+    async flush() {
+        const dir = path.dirname(this.filePath);
+        await fs.mkdir(dir, { recursive: true });
+        const tmp = `${this.filePath}.tmp.${process.pid}`;
+        await fs.writeFile(tmp, JSON.stringify(this.store, null, 2) + '\n', 'utf8');
+        await fs.rename(tmp, this.filePath);
+    }
+}
+// ---------------------------------------------------------------------------
+// Load / create
+// ---------------------------------------------------------------------------
+export async function loadRunStats(filePath) {
+    let store;
+    try {
+        const raw = await fs.readFile(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed &&
+            typeof parsed === 'object' &&
+            'version' in parsed &&
+            'jobs' in parsed &&
+            typeof parsed.jobs === 'object') {
+            store = parsed;
+        }
+        else {
+            store = emptyStore();
+        }
+    }
+    catch {
+        store = emptyStore();
+    }
+    // Sequential version-migration guards — see docs/data-migration.md for the convention.
+    // Each block handles exactly one step; transformations are additive only.
+    // Migrate v1 → v2: backfill triggerType on existing records (additive, no data loss).
+    if (store.version === 1) {
+        for (const rec of Object.values(store.jobs)) {
+            if (!rec.triggerType)
+                rec.triggerType = 'schedule';
+        }
+        store.version = 2;
+    }
+    // Migrate v2 → v3: ensure triggerType is set on any records that lack it
+    // (records created via upsertRecord without an explicit triggerType update).
+    if (store.version === 2) {
+        for (const rec of Object.values(store.jobs)) {
+            if (!rec.triggerType)
+                rec.triggerType = 'schedule';
+        }
+        store.version = 3;
+    }
+    // Add future migration blocks here:
+    //   if (store.version === 3) { /* transform fields */; store.version = 4; }
+    return new CronRunStats(store, filePath);
+}

package/dist/cron/run-stats.test.js

@@ -0,0 +1,160 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { loadRunStats, emptyStore, generateCronId, parseCronIdFromContent, } from './run-stats.js';
+let tmpDir;
+let statsPath;
+beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'cron-stats-'));
+    statsPath = path.join(tmpDir, 'cron-run-stats.json');
+});
+afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+});
+describe('generateCronId', () => {
+    it('produces cron-prefixed hex IDs', () => {
+        const id = generateCronId();
+        expect(id).toMatch(/^cron-[a-f0-9]{8}$/);
+    });
+    it('generates unique IDs', () => {
+        const ids = new Set(Array.from({ length: 100 }, () => generateCronId()));
+        expect(ids.size).toBe(100);
+    });
+});
+describe('parseCronIdFromContent', () => {
+    it('extracts cronId from status message content', () => {
+        const content = '📊 **Cron Status** [cronId:cron-a1b2c3d4]\n**Last run:** ...';
+        expect(parseCronIdFromContent(content)).toBe('cron-a1b2c3d4');
+    });
+    it('returns null when no cronId token present', () => {
+        expect(parseCronIdFromContent('Just some text')).toBeNull();
+    });
+    it('returns null for empty content', () => {
+        expect(parseCronIdFromContent('')).toBeNull();
+    });
+});
+describe('CronRunStats', () => {
+    it('creates empty store on missing file', async () => {
+        const stats = await loadRunStats(statsPath);
+        const store = stats.getStore();
+        expect(store.version).toBe(3);
+        expect(Object.keys(store.jobs)).toHaveLength(0);
+    });
+    it('upserts and retrieves records by cronId', async () => {
+        const stats = await loadRunStats(statsPath);
+        const rec = await stats.upsertRecord('cron-test1', 'thread-1');
+        expect(rec.cronId).toBe('cron-test1');
+        expect(rec.threadId).toBe('thread-1');
+        expect(rec.runCount).toBe(0);
+        const fetched = stats.getRecord('cron-test1');
+        expect(fetched).toBeDefined();
+        expect(fetched.threadId).toBe('thread-1');
+    });
+    it('upserts with partial updates', async () => {
+        const stats = await loadRunStats(statsPath);
+        await stats.upsertRecord('cron-test2', 'thread-2');
+        const updated = await stats.upsertRecord('cron-test2', 'thread-2', { cadence: 'daily', model: 'haiku' });
+        expect(updated.cadence).toBe('daily');
+        expect(updated.model).toBe('haiku');
+    });
+    it('retrieves records by threadId', async () => {
+        const stats = await loadRunStats(statsPath);
+        await stats.upsertRecord('cron-a', 'thread-100');
+        const rec = stats.getRecordByThreadId('thread-100');
+        expect(rec).toBeDefined();
+        expect(rec.cronId).toBe('cron-a');
+    });
+    it('retrieves records by statusMessageId', async () => {
+        const stats = await loadRunStats(statsPath);
+        await stats.upsertRecord('cron-b', 'thread-200', { statusMessageId: 'status-1' });
+        const rec = stats.getRecordByStatusMessageId('status-1');
+        expect(rec).toBeDefined();
+        expect(rec.cronId).toBe('cron-b');
+    });
+    it('returns undefined for unknown cronId', async () => {
+        const stats = await loadRunStats(statsPath);
+        expect(stats.getRecord('nonexistent')).toBeUndefined();
+    });
+    it('returns undefined for unknown threadId', async () => {
+        const stats = await loadRunStats(statsPath);
+        expect(stats.getRecordByThreadId('nonexistent')).toBeUndefined();
+    });
+    it('returns undefined for unknown statusMessageId', async () => {
+        const stats = await loadRunStats(statsPath);
+        expect(stats.getRecordByStatusMessageId('missing')).toBeUndefined();
+    });
+    it('records successful runs', async () => {
+        const stats = await loadRunStats(statsPath);
+        await stats.upsertRecord('cron-r1', 'thread-r1');
+        await stats.recordRun('cron-r1', 'success');
+        const rec = stats.getRecord('cron-r1');
+        expect(rec.runCount).toBe(1);
+        expect(rec.lastRunStatus).toBe('success');
+        expect(rec.lastRunAt).toBeTruthy();
+        expect(rec.lastErrorMessage).toBeUndefined();
+    });
+    it('records error runs with capped message', async () => {
+        const stats = await loadRunStats(statsPath);
+        await stats.upsertRecord('cron-r2', 'thread-r2');
+        const longMsg = 'x'.repeat(300);
+        await stats.recordRun('cron-r2', 'error', longMsg);
+        const rec = stats.getRecord('cron-r2');
+        expect(rec.runCount).toBe(1);
+        expect(rec.lastRunStatus).toBe('error');
+        expect(rec.lastErrorMessage).toHaveLength(200);
+    });
+    it('increments runCount across multiple runs', async () => {
+        const stats = await loadRunStats(statsPath);
+        await stats.upsertRecord('cron-r3', 'thread-r3');
+        await stats.recordRun('cron-r3', 'success');
+        await stats.recordRun('cron-r3', 'success');
+        await stats.recordRun('cron-r3', 'error', 'oops');
+        const rec = stats.getRecord('cron-r3');
+        expect(rec.runCount).toBe(3);
+        expect(rec.lastRunStatus).toBe('error');
+    });
+    it('removes record by cronId', async () => {
+        const stats = await loadRunStats(statsPath);
+        await stats.upsertRecord('cron-del', 'thread-del');
+        const removed = await stats.removeRecord('cron-del');
+        expect(removed).toBe(true);
+        expect(stats.getRecord('cron-del')).toBeUndefined();
+    });
+    it('returns false when removing nonexistent cronId', async () => {
+        const stats = await loadRunStats(statsPath);
+        const removed = await stats.removeRecord('nope');
+        expect(removed).toBe(false);
+    });
+    it('removes record by threadId', async () => {
+        const stats = await loadRunStats(statsPath);
+        await stats.upsertRecord('cron-dt', 'thread-dt');
+        const removed = await stats.removeByThreadId('thread-dt');
+        expect(removed).toBe(true);
+        expect(stats.getRecordByThreadId('thread-dt')).toBeUndefined();
+    });
+    it('persists to disk and survives reload', async () => {
+        const stats = await loadRunStats(statsPath);
+        await stats.upsertRecord('cron-persist', 'thread-p', { cadence: 'weekly', purposeTags: ['monitoring'] });
+        await stats.recordRun('cron-persist', 'success');
+        const stats2 = await loadRunStats(statsPath);
+        const rec = stats2.getRecord('cron-persist');
+        expect(rec).toBeDefined();
+        expect(rec.cadence).toBe('weekly');
+        expect(rec.runCount).toBe(1);
+        expect(rec.purposeTags).toEqual(['monitoring']);
+    });
+    it('no-ops recordRun for unknown cronId', async () => {
+        const stats = await loadRunStats(statsPath);
+        await stats.recordRun('nonexistent', 'success');
+        // Should not throw
+    });
+});
+describe('emptyStore', () => {
+    it('returns valid initial structure', () => {
+        const store = emptyStore();
+        expect(store.version).toBe(3);
+        expect(store.updatedAt).toBeGreaterThan(0);
+        expect(Object.keys(store.jobs)).toHaveLength(0);
+    });
+});

package/dist/cron/scheduler.js

@@ -0,0 +1,97 @@
+import { Cron } from 'croner';
+export class CronScheduler {
+    jobs = new Map();
+    handler;
+    log;
+    constructor(handler, log) {
+        this.handler = handler;
+        this.log = log;
+    }
+    register(id, threadId, guildId, name, def, cronId) {
+        const existing = this.jobs.get(id);
+        const isScheduled = def.triggerType === 'schedule';
+        // Create the job shell first; create the cron timer only for schedule-type automations.
+        const job = { id, cronId: cronId ?? existing?.cronId ?? '', threadId, guildId, name, def, cron: null, running: false };
+        if (isScheduled) {
+            // Construct timer first so invalid schedules don't clobber an existing job.
+            // schedule is always defined when triggerType === 'schedule'.
+            const cron = new Cron(def.schedule, { timezone: def.timezone }, () => {
+                // Fire-and-forget: errors handled inside the handler.
+                void this.handler(job);
+            });
+            job.cron = cron;
+        }
+        if (existing) {
+            existing.cron?.stop();
+            existing.cron = null;
+            this.jobs.delete(id);
+        }
+        this.jobs.set(id, job);
+        this.log?.info({ jobId: id, triggerType: def.triggerType ?? 'schedule', schedule: def.schedule, timezone: def.timezone }, 'cron:registered');
+        return job;
+    }
+    unregister(id) {
+        const job = this.jobs.get(id);
+        if (!job)
+            return false;
+        job.cron?.stop();
+        job.cron = null;
+        this.jobs.delete(id);
+        this.log?.info({ jobId: id }, 'cron:unregistered');
+        return true;
+    }
+    disable(id) {
+        const job = this.jobs.get(id);
+        if (!job)
+            return false;
+        job.cron?.stop();
+        job.cron = null;
+        this.log?.info({ jobId: id }, 'cron:disabled');
+        return true;
+    }
+    enable(id) {
+        const job = this.jobs.get(id);
+        if (!job)
+            return false;
+        const isScheduled = job.def.triggerType === 'schedule';
+        job.cron?.stop();
+        if (isScheduled) {
+            // Recreate the cron instance to (re)start scheduling.
+            // schedule is always defined when triggerType === 'schedule'.
+            job.cron = new Cron(job.def.schedule, { timezone: job.def.timezone }, () => {
+                void this.handler(job);
+            });
+        }
+        else {
+            job.cron = null;
+        }
+        this.log?.info({ jobId: id }, 'cron:enabled');
+        return true;
+    }
+    reload(id, newDef) {
+        const existing = this.jobs.get(id);
+        if (!existing)
+            return null;
+        return this.register(id, existing.threadId, existing.guildId, existing.name, newDef);
+    }
+    getJob(id) {
+        return this.jobs.get(id);
+    }
+    listJobs() {
+        return Array.from(this.jobs.values()).map((job) => ({
+            id: job.id,
+            name: job.name,
+            schedule: job.def.schedule,
+            timezone: job.def.timezone,
+            nextRun: job.cron?.nextRun() ?? null,
+        }));
+    }
+    stopAll() {
+        for (const job of this.jobs.values()) {
+            job.cron?.stop();
+            job.cron = null;
+        }
+        this.jobs.clear();
+        this.log?.info('cron:stopAll');
+    }
+}

package/dist/cron/scheduler.test.js

@@ -0,0 +1,112 @@
+import { describe, expect, it, vi, afterEach } from 'vitest';
+import { CronScheduler } from './scheduler.js';
+function makeDef(overrides) {
+    return {
+        triggerType: 'schedule',
+        schedule: '0 7 * * 1-5',
+        timezone: 'UTC',
+        channel: 'general',
+        prompt: 'Say hello.',
+        ...overrides,
+    };
+}
+function mockLog() {
+    return { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+}
+describe('CronScheduler', () => {
+    let scheduler;
+    const handler = vi.fn();
+    afterEach(() => {
+        scheduler?.stopAll();
+        handler.mockReset();
+    });
+    it('registers and lists a job', () => {
+        scheduler = new CronScheduler(handler, mockLog());
+        const def = makeDef();
+        scheduler.register('t1', 't1', 'g1', 'Test Job', def);
+        const jobs = scheduler.listJobs();
+        expect(jobs).toHaveLength(1);
+        expect(jobs[0].id).toBe('t1');
+        expect(jobs[0].name).toBe('Test Job');
+        expect(jobs[0].schedule).toBe('0 7 * * 1-5');
+        expect(jobs[0].nextRun).toBeInstanceOf(Date);
+    });
+    it('unregisters a job', () => {
+        scheduler = new CronScheduler(handler, mockLog());
+        scheduler.register('t1', 't1', 'g1', 'Job', makeDef());
+        expect(scheduler.listJobs()).toHaveLength(1);
+        const removed = scheduler.unregister('t1');
+        expect(removed).toBe(true);
+        expect(scheduler.listJobs()).toHaveLength(0);
+    });
+    it('unregister returns false for unknown id', () => {
+        scheduler = new CronScheduler(handler);
+        expect(scheduler.unregister('nope')).toBe(false);
+    });
+    it('disable stops the cron without removing it', () => {
+        scheduler = new CronScheduler(handler, mockLog());
+        scheduler.register('t1', 't1', 'g1', 'Job', makeDef());
+        const disabled = scheduler.disable('t1');
+        expect(disabled).toBe(true);
+        // Job still listed.
+        const jobs = scheduler.listJobs();
+        expect(jobs).toHaveLength(1);
+        expect(jobs[0].nextRun).toBeNull();
+    });
+    it('enable re-starts a disabled job', () => {
+        scheduler = new CronScheduler(handler, mockLog());
+        scheduler.register('t1', 't1', 'g1', 'Job', makeDef());
+        scheduler.disable('t1');
+        const enabled = scheduler.enable('t1');
+        expect(enabled).toBe(true);
+        // Next run should be populated again.
+        const jobs = scheduler.listJobs();
+        expect(jobs[0].nextRun).toBeInstanceOf(Date);
+    });
+    it('reload replaces the definition', () => {
+        scheduler = new CronScheduler(handler, mockLog());
+        scheduler.register('t1', 't1', 'g1', 'Job', makeDef({ schedule: '0 7 * * *' }));
+        const newDef = makeDef({ schedule: '0 9 * * 1-5' });
+        scheduler.reload('t1', newDef);
+        const jobs = scheduler.listJobs();
+        expect(jobs[0].schedule).toBe('0 9 * * 1-5');
+    });
+    it('reload returns null for unknown id', () => {
+        scheduler = new CronScheduler(handler);
+        expect(scheduler.reload('nope', makeDef())).toBeNull();
+    });
+    it('register replaces existing job with same id', () => {
+        scheduler = new CronScheduler(handler, mockLog());
+        scheduler.register('t1', 't1', 'g1', 'Job A', makeDef());
+        scheduler.register('t1', 't1', 'g1', 'Job B', makeDef({ schedule: '0 12 * * *' }));
+        const jobs = scheduler.listJobs();
+        expect(jobs).toHaveLength(1);
+        expect(jobs[0].name).toBe('Job B');
+    });
+    it('stopAll clears everything', () => {
+        scheduler = new CronScheduler(handler, mockLog());
+        scheduler.register('t1', 't1', 'g1', 'A', makeDef());
+        scheduler.register('t2', 't2', 'g1', 'B', makeDef());
+        scheduler.stopAll();
+        expect(scheduler.listJobs()).toHaveLength(0);
+    });
+    it('getJob returns the job by id', () => {
+        scheduler = new CronScheduler(handler);
+        scheduler.register('t1', 't1', 'g1', 'Job', makeDef());
+        const job = scheduler.getJob('t1');
+        expect(job).toBeDefined();
+        expect(job?.name).toBe('Job');
+    });
+    it('fires handler on cron tick', async () => {
+        scheduler = new CronScheduler(handler);
+        // Use a schedule that fires every second — croner doesn't support seconds in 5-field,
+        // but we can test by directly calling the handler via the cron callback approach.
+        // Instead, let's directly test by registering with a very frequent schedule and waiting.
+        // For unit tests, we'll verify registration wiring is correct via the handler mock.
+        const def = makeDef({ schedule: '* * * * *' }); // every minute — too slow for unit test
+        const job = scheduler.register('t1', 't1', 'g1', 'Job', def);
+        // Verify the job was created and handler is wired (we can't easily wait for a minute).
+        expect(job.cron).not.toBeNull();
+        expect(job.id).toBe('t1');
+    });
+});

package/dist/cron/tag-map.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs/promises';
+/**
+ * Strict tag-map loader for the cron subsystem.
+ * Unlike the permissive task runtime tag-map loader, this throws on any failure
+ * (read error, invalid JSON, wrong shape) so callers can handle it explicitly.
+ */
+export async function loadCronTagMapStrict(tagMapPath) {
+    const raw = await fs.readFile(tagMapPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`tag-map.json must be a JSON object, got ${Array.isArray(parsed) ? 'array' : typeof parsed}`);
+    }
+    const map = {};
+    for (const [key, val] of Object.entries(parsed)) {
+        if (typeof val !== 'string') {
+            throw new Error(`tag-map.json value for "${key}" must be a string, got ${typeof val}`);
+        }
+        map[key] = val;
+    }
+    return map;
+}
+/**
+ * Reload tag-map.json and mutate the existing TagMap in-place.
+ * Same validate-then-mutate pattern as the task runtime loader:
+ * only mutates after full validation, throws on any failure so callers
+ * can catch and preserve the existing cached map.
+ * Returns the new tag count.
+ */
+export async function reloadCronTagMapInPlace(tagMapPath, tagMap) {
+    const raw = await fs.readFile(tagMapPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`tag-map.json must be a JSON object, got ${Array.isArray(parsed) ? 'array' : typeof parsed}`);
+    }
+    const newMap = {};
+    for (const [key, val] of Object.entries(parsed)) {
+        if (typeof val !== 'string') {
+            throw new Error(`tag-map.json value for "${key}" must be a string, got ${typeof val}`);
+        }
+        newMap[key] = val;
+    }
+    // Only mutate after full validation
+    for (const key of Object.keys(tagMap))
+        delete tagMap[key];
+    Object.assign(tagMap, newMap);
+    return Object.keys(tagMap).length;
+}