discoclaw 0.5.2 → 0.5.3

package/dist/cron/chain.js

@@ -0,0 +1,5 @@
+"use strict";
+// This file has been intentionally removed.
+// Chain logic lives directly in executor.ts (fireChainedJobs) and
+// actions-crons.ts (parseAndValidateChain, detectChainCycle).
+// See: ws-1077 audit fix.

package/dist/cron/chain.test.js

@@ -0,0 +1,226 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { fireChainedJobs } from './executor.js';
+import { loadRunStats } from './run-stats.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function mockLog() {
+    return { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+}
+let tmpDir;
+beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'chain-test-'));
+});
+afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true, maxRetries: 3 });
+});
+async function makeStatsStore() {
+    return loadRunStats(path.join(tmpDir, 'stats.json'));
+}
+function makeDownstreamJob(cronId, threadId) {
+    return {
+        id: threadId,
+        cronId,
+        threadId,
+        guildId: 'guild-1',
+        name: `Job ${cronId}`,
+        def: { triggerType: 'schedule', schedule: '0 0 * * *', timezone: 'UTC', channel: 'general', prompt: 'test' },
+        cron: null,
+        running: false,
+    };
+}
+function makeMinimalCtx(statsStore, overrides) {
+    return {
+        client: {},
+        runtime: { id: 'claude_code', capabilities: new Set(), async *invoke() { } },
+        model: 'haiku',
+        cwd: '/tmp',
+        tools: [],
+        timeoutMs: 30_000,
+        status: null,
+        log: mockLog(),
+        discordActionsEnabled: false,
+        actionFlags: {
+            channels: false, messaging: false, guild: false, moderation: false,
+            polls: false, tasks: false, crons: false, botProfile: false,
+            forge: false, plan: false, memory: false, config: false, defer: false, voice: false,
+        },
+        statsStore,
+        ...overrides,
+    };
+}
+// ---------------------------------------------------------------------------
+// fireChainedJobs
+// ---------------------------------------------------------------------------
+describe('fireChainedJobs', () => {
+    it('does nothing when getSchedulerJob is not set', async () => {
+        const store = await makeStatsStore();
+        await store.upsertRecord('upstream', 'thread-up', { chain: ['downstream'] });
+        await store.upsertRecord('downstream', 'thread-down', {});
+        const ctx = makeMinimalCtx(store);
+        // No getSchedulerJob → early return
+        await fireChainedJobs('upstream', ctx);
+        const rec = store.getRecord('downstream');
+        // State should NOT have been forwarded
+        expect(rec?.state).toBeUndefined();
+    });
+    it('does nothing when statsStore is not set', async () => {
+        const ctx = makeMinimalCtx(undefined, { statsStore: undefined });
+        // Should not throw
+        await fireChainedJobs('upstream', ctx);
+    });
+    it('does nothing when the upstream job has no chain', async () => {
+        const store = await makeStatsStore();
+        await store.upsertRecord('upstream', 'thread-up', {});
+        const getSchedulerJob = vi.fn();
+        const ctx = makeMinimalCtx(store, { getSchedulerJob });
+        await fireChainedJobs('upstream', ctx);
+        expect(getSchedulerJob).not.toHaveBeenCalled();
+    });
+    it('does nothing when chain is empty array', async () => {
+        const store = await makeStatsStore();
+        await store.upsertRecord('upstream', 'thread-up', { chain: [] });
+        const getSchedulerJob = vi.fn();
+        const ctx = makeMinimalCtx(store, { getSchedulerJob });
+        await fireChainedJobs('upstream', ctx);
+        expect(getSchedulerJob).not.toHaveBeenCalled();
+    });
+    it('forwards __upstream state to downstream job', async () => {
+        const store = await makeStatsStore();
+        const upstreamState = { lastSeenTag: 'v2.3.1', items: [1, 2, 3] };
+        await store.upsertRecord('upstream', 'thread-up', {
+            chain: ['downstream'],
+            state: upstreamState,
+        });
+        await store.upsertRecord('downstream', 'thread-down', {
+            state: { existingKey: 'preserved' },
+        });
+        const downstreamJob = makeDownstreamJob('downstream', 'thread-down');
+        const getSchedulerJob = vi.fn().mockReturnValue(downstreamJob);
+        const ctx = makeMinimalCtx(store, { getSchedulerJob });
+        await fireChainedJobs('upstream', ctx);
+        const rec = store.getRecord('downstream');
+        expect(rec?.state).toEqual({
+            existingKey: 'preserved',
+            __upstream: { fromCronId: 'upstream', state: upstreamState },
+        });
+    });
+    it('forwards empty state as __upstream when upstream has no state', async () => {
+        const store = await makeStatsStore();
+        await store.upsertRecord('upstream', 'thread-up', { chain: ['downstream'] });
+        await store.upsertRecord('downstream', 'thread-down', {});
+        const downstreamJob = makeDownstreamJob('downstream', 'thread-down');
+        const getSchedulerJob = vi.fn().mockReturnValue(downstreamJob);
+        const ctx = makeMinimalCtx(store, { getSchedulerJob });
+        await fireChainedJobs('upstream', ctx);
+        const rec = store.getRecord('downstream');
+        expect(rec?.state).toEqual({
+            __upstream: { fromCronId: 'upstream', state: {} },
+        });
+    });
+    it('skips downstream when record is not found', async () => {
+        const store = await makeStatsStore();
+        await store.upsertRecord('upstream', 'thread-up', { chain: ['nonexistent'] });
+        const getSchedulerJob = vi.fn();
+        const log = mockLog();
+        const ctx = makeMinimalCtx(store, { getSchedulerJob, log });
+        await fireChainedJobs('upstream', ctx);
+        expect(getSchedulerJob).not.toHaveBeenCalled();
+        expect(log.warn).toHaveBeenCalledWith(expect.objectContaining({ downstream: 'nonexistent' }), expect.stringContaining('record not found'));
+    });
+    it('skips downstream when scheduler job is not found', async () => {
+        const store = await makeStatsStore();
+        await store.upsertRecord('upstream', 'thread-up', { chain: ['downstream'] });
+        await store.upsertRecord('downstream', 'thread-down', {});
+        const getSchedulerJob = vi.fn().mockReturnValue(undefined);
+        const log = mockLog();
+        const ctx = makeMinimalCtx(store, { getSchedulerJob, log });
+        await fireChainedJobs('upstream', ctx);
+        expect(log.warn).toHaveBeenCalledWith(expect.objectContaining({ downstream: 'downstream' }), expect.stringContaining('scheduler job not found'));
+    });
+    it('fires multiple downstream jobs independently', async () => {
+        const store = await makeStatsStore();
+        await store.upsertRecord('upstream', 'thread-up', {
+            chain: ['down-a', 'down-b'],
+            state: { data: 42 },
+        });
+        await store.upsertRecord('down-a', 'thread-a', {});
+        await store.upsertRecord('down-b', 'thread-b', {});
+        const jobA = makeDownstreamJob('down-a', 'thread-a');
+        const jobB = makeDownstreamJob('down-b', 'thread-b');
+        const getSchedulerJob = vi.fn((threadId) => {
+            if (threadId === 'thread-a')
+                return jobA;
+            if (threadId === 'thread-b')
+                return jobB;
+            return undefined;
+        });
+        const log = mockLog();
+        const ctx = makeMinimalCtx(store, { getSchedulerJob, log });
+        await fireChainedJobs('upstream', ctx);
+        // Both should have __upstream state forwarded
+        const recA = store.getRecord('down-a');
+        const recB = store.getRecord('down-b');
+        expect(recA?.state?.__upstream).toEqual({ fromCronId: 'upstream', state: { data: 42 } });
+        expect(recB?.state?.__upstream).toEqual({ fromCronId: 'upstream', state: { data: 42 } });
+        // Both should have been logged as fired
+        expect(log.info).toHaveBeenCalledWith(expect.objectContaining({ downstream: 'down-a' }), expect.stringContaining('downstream fired'));
+        expect(log.info).toHaveBeenCalledWith(expect.objectContaining({ downstream: 'down-b' }), expect.stringContaining('downstream fired'));
+    });
+    it('logs warning and skips downstream when chain depth >= 10', async () => {
+        const store = await makeStatsStore();
+        await store.upsertRecord('upstream', 'thread-up', { chain: ['downstream'] });
+        await store.upsertRecord('downstream', 'thread-down', {});
+        const getSchedulerJob = vi.fn();
+        const log = mockLog();
+        const ctx = makeMinimalCtx(store, { getSchedulerJob, log, chainDepth: 10 });
+        await fireChainedJobs('upstream', ctx);
+        expect(log.warn).toHaveBeenCalledWith(expect.objectContaining({ cronId: 'upstream', chainDepth: 10 }), expect.stringContaining('depth limit'));
+        // getSchedulerJob should never be called — we returned early
+        expect(getSchedulerJob).not.toHaveBeenCalled();
+    });
+    it('increments chain depth for downstream execution context', async () => {
+        const store = await makeStatsStore();
+        await store.upsertRecord('upstream', 'thread-up', {
+            chain: ['downstream'],
+            state: { x: 1 },
+        });
+        await store.upsertRecord('downstream', 'thread-down', {});
+        const downstreamJob = makeDownstreamJob('downstream', 'thread-down');
+        const getSchedulerJob = vi.fn().mockReturnValue(downstreamJob);
+        const log = mockLog();
+        const ctx = makeMinimalCtx(store, { getSchedulerJob, log, chainDepth: 5 });
+        await fireChainedJobs('upstream', ctx);
+        // The function should have fired (depth 5 < 10)
+        expect(log.info).toHaveBeenCalledWith(expect.objectContaining({ downstream: 'downstream' }), expect.stringContaining('downstream fired'));
+    });
+    it('handles state forward failure gracefully', async () => {
+        const store = await makeStatsStore();
+        await store.upsertRecord('upstream', 'thread-up', {
+            chain: ['downstream'],
+            state: { data: 1 },
+        });
+        await store.upsertRecord('downstream', 'thread-down', {});
+        // Mock upsertRecord to fail on state forwarding
+        const originalUpsert = store.upsertRecord.bind(store);
+        let callCount = 0;
+        vi.spyOn(store, 'upsertRecord').mockImplementation(async (...args) => {
+            callCount++;
+            // Fail on the state-forwarding call (the one during fireChainedJobs)
+            if (callCount > 0)
+                throw new Error('disk full');
+            return originalUpsert(...args);
+        });
+        const downstreamJob = makeDownstreamJob('downstream', 'thread-down');
+        const getSchedulerJob = vi.fn().mockReturnValue(downstreamJob);
+        const log = mockLog();
+        const ctx = makeMinimalCtx(store, { getSchedulerJob, log });
+        await fireChainedJobs('upstream', ctx);
+        // Should log a warning but still fire downstream
+        expect(log.warn).toHaveBeenCalledWith(expect.objectContaining({ downstream: 'downstream' }), expect.stringContaining('state forward failed'));
+        expect(log.info).toHaveBeenCalledWith(expect.objectContaining({ downstream: 'downstream' }), expect.stringContaining('downstream fired'));
+    });
+});

package/dist/cron/cron-prompt.js

@@ -12,8 +12,12 @@
  * Expand {{channel}} and {{channelId}} placeholders in a cron prompt template.
  * All occurrences are replaced; unrecognized placeholders are left intact.
  */
-export function expandCronPlaceholders(text, channel, channelId) {
-    return text.replaceAll('{{channel}}', channel).replaceAll('{{channelId}}', channelId);
+export function expandCronPlaceholders(text, channel, channelId, state) {
+    const stateJson = JSON.stringify(state ?? {});
+    return text
+        .replaceAll('{{channel}}', channel)
+        .replaceAll('{{channelId}}', channelId)
+        .replaceAll('{{state}}', stateJson);
 }
 // ---------------------------------------------------------------------------
 // Prompt body builder
@@ -29,8 +33,8 @@ export function expandCronPlaceholders(text, channel, channelId) {
  *  - Silent-mode sentinel instruction
  */
 export function buildCronPromptBody(input) {
-    const { jobName, promptTemplate, channel, channelId = '', silent, routingMode, availableChannels, } = input;
-    const expandedPrompt = expandCronPlaceholders(promptTemplate, channel, channelId);
+    const { jobName, promptTemplate, channel, channelId = '', silent, routingMode, availableChannels, state, } = input;
+    const expandedPrompt = expandCronPlaceholders(promptTemplate, channel, channelId, state);
     const segments = [
         `You are executing a scheduled cron job named "${jobName}".`,
         `Instruction: ${expandedPrompt}`,
@@ -49,6 +53,24 @@ export function buildCronPromptBody(input) {
             segments.push('IMPORTANT: If there is nothing actionable to report, respond with exactly `HEARTBEAT_OK` and nothing else.');
         }
     }
+    // Inject persistent state section when state is present and non-empty.
+    if (state && Object.keys(state).length > 0) {
+        const STATE_CHAR_LIMIT = 4000;
+        let serialized = JSON.stringify(state, null, 2);
+        if (serialized.length > STATE_CHAR_LIMIT) {
+            serialized = serialized.slice(0, STATE_CHAR_LIMIT) + '\n... (state truncated)';
+        }
+        segments.push([
+            '## Persistent State',
+            '',
+            'The following state was persisted from your previous run:',
+            '```json',
+            serialized,
+            '```',
+            'If you need to update the persisted state for the next run, emit a `<cron-state>{...}</cron-state>` block ' +
+                'containing a JSON object with the full updated state. The emitted object fully replaces the existing state — include all keys you want to keep. Only emit this block if the state needs to change.',
+        ].join('\n'));
+    }
     return segments.join('\n\n');
 }
 // ---------------------------------------------------------------------------

package/dist/cron/cron-prompt.test.js

@@ -242,3 +242,81 @@ describe('buildCronPromptBody — placeholder expansion', () => {
         expect(body).toContain('Channel alerts with ID ch-5.');
     });
 });
+// ---------------------------------------------------------------------------
+// expandCronPlaceholders — {{state}} placeholder
+// ---------------------------------------------------------------------------
+describe('expandCronPlaceholders — {{state}} placeholder', () => {
+    it('expands {{state}} to JSON string of provided state', () => {
+        const result = expandCronPlaceholders('Current state: {{state}}', 'general', 'ch-1', { counter: 3, lastSeen: '2026-02-28' });
+        expect(result).toContain('"counter":3');
+        expect(result).toContain('"lastSeen":"2026-02-28"');
+        expect(result).not.toContain('{{state}}');
+    });
+    it('expands {{state}} to empty object JSON when state is undefined', () => {
+        const result = expandCronPlaceholders('State: {{state}}', 'general', 'ch-1');
+        expect(result).toBe('State: {}');
+    });
+    it('expands {{state}} to empty object JSON when state is empty', () => {
+        const result = expandCronPlaceholders('State: {{state}}', 'general', 'ch-1', {});
+        expect(result).toBe('State: {}');
+    });
+});
+// ---------------------------------------------------------------------------
+// buildCronPromptBody — persistent state
+// ---------------------------------------------------------------------------
+describe('buildCronPromptBody — persistent state', () => {
+    it('includes Persistent State section when state is non-empty', () => {
+        const body = buildCronPromptBody({
+            jobName: 'Stateful Job',
+            promptTemplate: 'Check for updates.',
+            channel: 'general',
+            state: { lastCheck: '2026-02-27', items: [1, 2, 3] },
+        });
+        expect(body).toContain('## Persistent State');
+        expect(body).toContain('"lastCheck": "2026-02-27"');
+        expect(body).toContain('<cron-state>');
+    });
+    it('omits Persistent State section when state is undefined', () => {
+        const body = buildCronPromptBody({
+            jobName: 'Stateless Job',
+            promptTemplate: 'Say hello.',
+            channel: 'general',
+        });
+        expect(body).not.toContain('Persistent State');
+        expect(body).not.toContain('<cron-state>');
+    });
+    it('omits Persistent State section when state is empty object', () => {
+        const body = buildCronPromptBody({
+            jobName: 'Empty State Job',
+            promptTemplate: 'Say hello.',
+            channel: 'general',
+            state: {},
+        });
+        expect(body).not.toContain('Persistent State');
+        expect(body).not.toContain('<cron-state>');
+    });
+    it('truncates very large state objects', () => {
+        const largeState = {};
+        for (let i = 0; i < 500; i++) {
+            largeState[`key_${i}`] = 'x'.repeat(20);
+        }
+        const body = buildCronPromptBody({
+            jobName: 'Large State Job',
+            promptTemplate: 'Process data.',
+            channel: 'general',
+            state: largeState,
+        });
+        expect(body).toContain('## Persistent State');
+        expect(body).toContain('(state truncated)');
+    });
+    it('includes cron-state emit instruction in the state section', () => {
+        const body = buildCronPromptBody({
+            jobName: 'Job',
+            promptTemplate: 'Do stuff.',
+            channel: 'general',
+            state: { v: 1 },
+        });
+        expect(body).toContain('<cron-state>');
+        expect(body).toContain('update');
+    });
+});

package/dist/cron/executor.js

@@ -20,6 +20,50 @@ async function recordError(ctx, job, msg) {
         }
     }
 }
+const MAX_CHAIN_DEPTH = 10;
+export async function fireChainedJobs(cronId, ctx) {
+    const chainDepth = ctx.chainDepth ?? 0;
+    if (chainDepth >= MAX_CHAIN_DEPTH) {
+        ctx.log?.warn({ cronId, chainDepth }, 'chain:depth limit reached, skipping downstream');
+        return;
+    }
+    if (!ctx.statsStore || !ctx.getSchedulerJob)
+        return;
+    const record = ctx.statsStore.getRecord(cronId);
+    if (!record?.chain || record.chain.length === 0)
+        return;
+    const upstreamState = record.state;
+    for (const downstreamCronId of record.chain) {
+        const downstreamRecord = ctx.statsStore.getRecord(downstreamCronId);
+        if (!downstreamRecord) {
+            ctx.log?.warn({ cronId, downstream: downstreamCronId }, 'chain:downstream record not found, skipping');
+            continue;
+        }
+        const downstreamJob = ctx.getSchedulerJob(downstreamRecord.threadId);
+        if (!downstreamJob) {
+            ctx.log?.warn({ cronId, downstream: downstreamCronId, threadId: downstreamRecord.threadId }, 'chain:downstream scheduler job not found, skipping');
+            continue;
+        }
+        // Merge __upstream into downstream job's persisted state so the prompt's {{state}} includes handoff data.
+        try {
+            const forwardedState = {
+                ...(downstreamRecord.state ?? {}),
+                __upstream: { fromCronId: cronId, state: upstreamState ?? {} },
+            };
+            await ctx.statsStore.upsertRecord(downstreamCronId, downstreamRecord.threadId, { state: forwardedState });
+            ctx.log?.info({ cronId, downstream: downstreamCronId }, 'chain:state forwarded');
+        }
+        catch (err) {
+            ctx.log?.warn({ err, cronId, downstream: downstreamCronId }, 'chain:state forward failed');
+        }
+        // Fire-and-forget with incremented chain depth.
+        const downstreamCtx = { ...ctx, chainDepth: chainDepth + 1 };
+        void executeCronJob(downstreamJob, downstreamCtx).catch((err) => {
+            ctx.log?.warn({ err, cronId, downstream: downstreamCronId }, 'chain:downstream execution failed');
+        });
+        ctx.log?.info({ cronId, downstream: downstreamCronId }, 'chain:downstream fired');
+    }
+}
 export async function executeCronJob(job, ctx) {
     const metrics = globalMetrics;
     let cancelRequested = false;
@@ -110,6 +154,7 @@ export async function executeCronJob(job, ctx) {
                 channelId: channelForSend.id,
                 silent: preRunRecord?.silent,
                 routingMode: preRunRecord?.routingMode === 'json' ? 'json' : undefined,
+                state: preRunRecord?.state,
             });
         const tools = await resolveEffectiveTools({
             workspaceCwd: ctx.cwd,
@@ -208,7 +253,31 @@ export async function executeCronJob(job, ctx) {
         }
         metrics.recordInvokeResult('cron', Date.now() - t0, true);
         ctx.log?.info({ flow: 'cron', jobId: job.id, ms: Date.now() - t0, ok: true }, 'obs.invoke.end');
-        const output = finalText || deltaText;
+        let output = finalText || deltaText;
+        // Extract <cron-state> blocks from the output — last one wins.
+        const cronStateRegex = /<cron-state>([\s\S]*?)<\/cron-state>/g;
+        let cronStateMatch;
+        let lastCronStateJson;
+        while ((cronStateMatch = cronStateRegex.exec(output)) !== null) {
+            lastCronStateJson = cronStateMatch[1];
+        }
+        if (lastCronStateJson !== undefined && ctx.statsStore && job.cronId) {
+            try {
+                const parsedState = JSON.parse(lastCronStateJson.trim());
+                if (parsedState && typeof parsedState === 'object' && !Array.isArray(parsedState)) {
+                    await ctx.statsStore.upsertRecord(job.cronId, job.threadId, { state: parsedState });
+                    ctx.log?.info({ jobId: job.id, cronId: job.cronId }, 'cron:exec persisted updated state');
+                }
+                else {
+                    ctx.log?.warn({ jobId: job.id, cronId: job.cronId }, 'cron:exec <cron-state> was not a JSON object, ignoring');
+                }
+            }
+            catch (stateErr) {
+                ctx.log?.warn({ err: stateErr, jobId: job.id, cronId: job.cronId }, 'cron:exec <cron-state> parse failed, ignoring');
+            }
+            // Strip all <cron-state> blocks from the output text.
+            output = output.replace(/<cron-state>[\s\S]*?<\/cron-state>/g, '').trim();
+        }
         if (!output.trim() && collectedImages.length === 0) {
             metrics.increment('cron.run.skipped');
             ctx.log?.warn({ jobId: job.id }, 'cron:exec empty output');
@@ -219,6 +288,7 @@ export async function executeCronJob(job, ctx) {
                 catch {
                     // Best-effort.
                 }
+                void fireChainedJobs(job.cronId, ctx);
             }
             return;
         }
@@ -310,6 +380,7 @@ export async function executeCronJob(job, ctx) {
                 catch {
                     // Best-effort.
                 }
+                void fireChainedJobs(job.cronId, ctx);
             }
             metrics.increment('cron.run.success');
             return;
@@ -326,6 +397,7 @@ export async function executeCronJob(job, ctx) {
                 catch {
                     // Best-effort.
                 }
+                void fireChainedJobs(job.cronId, ctx);
             }
             metrics.increment('cron.run.success');
             return;
@@ -366,6 +438,7 @@ export async function executeCronJob(job, ctx) {
             catch (statsErr) {
                 ctx.log?.warn({ err: statsErr, jobId: job.id }, 'cron:exec stats record failed');
             }
+            void fireChainedJobs(job.cronId, ctx);
         }
     }
     catch (err) {

package/dist/cron/executor.test.js

@@ -1003,3 +1003,105 @@ describe('executeCronJob allowedActions filtering', () => {
         executeDiscordActionsSpy.mockRestore();
     });
 });
+// ---------------------------------------------------------------------------
+// <cron-state> extraction and persistence
+// ---------------------------------------------------------------------------
+describe('executeCronJob cron-state extraction', () => {
+    let statsDir;
+    beforeEach(async () => {
+        statsDir = await fs.mkdtemp(path.join(os.tmpdir(), 'executor-cron-state-'));
+    });
+    afterEach(async () => {
+        await fs.rm(statsDir, { recursive: true, force: true });
+    });
+    it('extracts <cron-state> block and persists state via upsertRecord', async () => {
+        const statsPath = path.join(statsDir, 'stats.json');
+        const statsStore = await loadRunStats(statsPath);
+        await statsStore.upsertRecord('cron-test0001', 'thread-1');
+        const response = 'Here is the report.\n<cron-state>{"lastSeen":"2026-02-28","count":5}</cron-state>';
+        const ctx = makeCtx({ statsStore, runtime: makeMockRuntime(response) });
+        const job = makeJob();
+        await executeCronJob(job, ctx);
+        const rec = statsStore.getRecord('cron-test0001');
+        expect(rec.state).toEqual({ lastSeen: '2026-02-28', count: 5 });
+    });
+    it('strips <cron-state> blocks from the output sent to Discord', async () => {
+        const statsPath = path.join(statsDir, 'stats.json');
+        const statsStore = await loadRunStats(statsPath);
+        await statsStore.upsertRecord('cron-test0001', 'thread-1');
+        const response = 'Report content here.\n<cron-state>{"v":1}</cron-state>';
+        const ctx = makeCtx({ statsStore, runtime: makeMockRuntime(response) });
+        const job = makeJob();
+        await executeCronJob(job, ctx);
+        const guild = ctx.client.guilds.cache.get('guild-1');
+        const channel = guild.channels.cache.get('general');
+        expect(channel.send).toHaveBeenCalled();
+        const sentContent = channel.send.mock.calls[0][0].content;
+        expect(sentContent).not.toContain('<cron-state>');
+        expect(sentContent).toContain('Report content here.');
+    });
+    it('uses the last <cron-state> block when multiple are present', async () => {
+        const statsPath = path.join(statsDir, 'stats.json');
+        const statsStore = await loadRunStats(statsPath);
+        await statsStore.upsertRecord('cron-test0001', 'thread-1');
+        const response = [
+            'Part 1.',
+            '<cron-state>{"v":1}</cron-state>',
+            'Part 2.',
+            '<cron-state>{"v":2,"final":true}</cron-state>',
+        ].join('\n');
+        const ctx = makeCtx({ statsStore, runtime: makeMockRuntime(response) });
+        const job = makeJob();
+        await executeCronJob(job, ctx);
+        const rec = statsStore.getRecord('cron-test0001');
+        expect(rec.state).toEqual({ v: 2, final: true });
+    });
+    it('ignores invalid JSON in <cron-state> block gracefully', async () => {
+        const statsPath = path.join(statsDir, 'stats.json');
+        const statsStore = await loadRunStats(statsPath);
+        await statsStore.upsertRecord('cron-test0001', 'thread-1', { state: { old: true } });
+        const response = 'Output here.\n<cron-state>not valid json</cron-state>';
+        const ctx = makeCtx({ statsStore, runtime: makeMockRuntime(response) });
+        const job = makeJob();
+        await executeCronJob(job, ctx);
+        // State should remain unchanged after invalid parse.
+        const rec = statsStore.getRecord('cron-test0001');
+        expect(rec.state).toEqual({ old: true });
+        expect(ctx.log?.warn).toHaveBeenCalledWith(expect.objectContaining({ jobId: 'thread-1' }), 'cron:exec <cron-state> parse failed, ignoring');
+    });
+    it('ignores non-object JSON in <cron-state> block (e.g. array)', async () => {
+        const statsPath = path.join(statsDir, 'stats.json');
+        const statsStore = await loadRunStats(statsPath);
+        await statsStore.upsertRecord('cron-test0001', 'thread-1');
+        const response = 'Output here.\n<cron-state>[1,2,3]</cron-state>';
+        const ctx = makeCtx({ statsStore, runtime: makeMockRuntime(response) });
+        const job = makeJob();
+        await executeCronJob(job, ctx);
+        const rec = statsStore.getRecord('cron-test0001');
+        expect(rec.state).toBeUndefined();
+        expect(ctx.log?.warn).toHaveBeenCalledWith(expect.objectContaining({ jobId: 'thread-1' }), 'cron:exec <cron-state> was not a JSON object, ignoring');
+    });
+    it('passes existing state to the prompt via preRunRecord', async () => {
+        const statsPath = path.join(statsDir, 'stats.json');
+        const statsStore = await loadRunStats(statsPath);
+        await statsStore.upsertRecord('cron-test0001', 'thread-1', {
+            state: { counter: 42, lastItem: 'xyz' },
+        });
+        let capturedPrompt = '';
+        const runtime = {
+            id: 'claude_code',
+            capabilities: new Set(['streaming_text']),
+            async *invoke(opts) {
+                capturedPrompt = opts.prompt;
+                yield { type: 'text_final', text: 'Done.' };
+                yield { type: 'done' };
+            },
+        };
+        const ctx = makeCtx({ statsStore, runtime });
+        const job = makeJob();
+        await executeCronJob(job, ctx);
+        expect(capturedPrompt).toContain('Persistent State');
+        expect(capturedPrompt).toContain('"counter": 42');
+        expect(capturedPrompt).toContain('"lastItem": "xyz"');
+    });
+});

package/dist/cron/run-stats.js

@@ -5,7 +5,7 @@ import crypto from 'node:crypto';
 // Types
 // ---------------------------------------------------------------------------
 export const CADENCE_TAGS = ['yearly', 'frequent', 'hourly', 'daily', 'weekly', 'monthly'];
-export const CURRENT_VERSION = 8;
+export const CURRENT_VERSION = 10;
 // ---------------------------------------------------------------------------
 // Stable Cron ID generation
 // ---------------------------------------------------------------------------
@@ -135,6 +135,9 @@ export class CronRunStats {
                     if ('allowedActions' in updates && updates.allowedActions === undefined) {
                         delete existing.allowedActions;
                     }
+                    if ('chain' in updates && updates.chain === undefined) {
+                        delete existing.chain;
+                    }
                 }
                 existing.threadId = threadId;
                 if (prevStatusMessageId && prevStatusMessageId !== existing.statusMessageId) {
@@ -317,5 +320,13 @@ export async function loadRunStats(filePath) {
     if (store.version === 7) {
         store.version = 8;
     }
+    // Migrate v8 → v9: no-op — new field (state) is optional and defaults to absent.
+    if (store.version === 8) {
+        store.version = 9;
+    }
+    // Migrate v9 → v10: no-op — new field (chain) is optional and defaults to absent.
+    if (store.version === 9) {
+        store.version = 10;
+    }
     return new CronRunStats(store, filePath);
 }

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

@@ -38,7 +38,7 @@ describe('CronRunStats', () => {
     it('creates empty store on missing file', async () => {
         const stats = await loadRunStats(statsPath);
         const store = stats.getStore();
-        expect(store.version).toBe(8);
+        expect(store.version).toBe(10);
         expect(Object.keys(store.jobs)).toHaveLength(0);
     });
     it('upserts and retrieves records by cronId', async () => {
@@ -92,6 +92,37 @@ describe('CronRunStats', () => {
         expect(rec.allowedActions).toBeUndefined();
         expect('allowedActions' in rec).toBe(false);
     });
+    it('upserts with state and retrieves it', async () => {
+        const stats = await loadRunStats(statsPath);
+        const stateObj = { lastSeen: '2026-02-28', counter: 5 };
+        const rec = await stats.upsertRecord('cron-st1', 'thread-st1', { state: stateObj });
+        expect(rec.state).toEqual(stateObj);
+        const fetched = stats.getRecord('cron-st1');
+        expect(fetched.state).toEqual(stateObj);
+    });
+    it('persists state through disk reload', async () => {
+        const stats = await loadRunStats(statsPath);
+        const stateObj = { items: ['a', 'b'], processed: true };
+        await stats.upsertRecord('cron-st2', 'thread-st2', { state: stateObj });
+        const stats2 = await loadRunStats(statsPath);
+        const rec = stats2.getRecord('cron-st2');
+        expect(rec).toBeDefined();
+        expect(rec.state).toEqual(stateObj);
+    });
+    it('replaces state entirely on subsequent upsert', async () => {
+        const stats = await loadRunStats(statsPath);
+        await stats.upsertRecord('cron-st3', 'thread-st3', { state: { v: 1, old: true } });
+        await stats.upsertRecord('cron-st3', 'thread-st3', { state: { v: 2, new: true } });
+        const rec = stats.getRecord('cron-st3');
+        expect(rec.state).toEqual({ v: 2, new: true });
+        expect(rec.state).not.toHaveProperty('old');
+    });
+    it('defaults to no state when none is provided', async () => {
+        const stats = await loadRunStats(statsPath);
+        await stats.upsertRecord('cron-st4', 'thread-st4');
+        const rec = stats.getRecord('cron-st4');
+        expect(rec.state).toBeUndefined();
+    });
     it('retrieves records by threadId', async () => {
         const stats = await loadRunStats(statsPath);
         await stats.upsertRecord('cron-a', 'thread-100');
@@ -244,7 +275,7 @@ describe('CronRunStats', () => {
 describe('emptyStore', () => {
     it('returns valid initial structure', () => {
         const store = emptyStore();
-        expect(store.version).toBe(8);
+        expect(store.version).toBe(10);
         expect(store.updatedAt).toBeGreaterThan(0);
         expect(Object.keys(store.jobs)).toHaveLength(0);
     });
@@ -271,7 +302,7 @@ describe('loadRunStats version migration', () => {
         };
         await fs.writeFile(statsPath, JSON.stringify(v3Store), 'utf-8');
         const stats = await loadRunStats(statsPath);
-        expect(stats.getStore().version).toBe(8);
+        expect(stats.getStore().version).toBe(10);
         const rec = stats.getRecord('cron-migrated');
         expect(rec).toBeDefined();
         expect(rec.cronId).toBe('cron-migrated');
@@ -301,7 +332,7 @@ describe('loadRunStats version migration', () => {
         };
         await fs.writeFile(statsPath, JSON.stringify(v4Store), 'utf-8');
         const stats = await loadRunStats(statsPath);
-        expect(stats.getStore().version).toBe(8);
+        expect(stats.getStore().version).toBe(10);
         const rec = stats.getRecord('cron-v4');
         expect(rec).toBeDefined();
         expect(rec.cronId).toBe('cron-v4');
@@ -331,7 +362,7 @@ describe('loadRunStats version migration', () => {
         };
         await fs.writeFile(statsPath, JSON.stringify(v5Store), 'utf-8');
         const stats = await loadRunStats(statsPath);
-        expect(stats.getStore().version).toBe(8);
+        expect(stats.getStore().version).toBe(10);
         const rec = stats.getRecord('cron-v5');
         expect(rec).toBeDefined();
         expect(rec.cronId).toBe('cron-v5');
@@ -344,6 +375,37 @@ describe('loadRunStats version migration', () => {
         expect(rec.prompt).toBeUndefined();
         expect(rec.authorId).toBeUndefined();
     });
+    it('migrates a v8 store to v9 with state undefined on existing records', async () => {
+        const v8Store = {
+            version: 8,
+            updatedAt: Date.now(),
+            jobs: {
+                'cron-v8': {
+                    cronId: 'cron-v8',
+                    threadId: 'thread-v8',
+                    runCount: 4,
+                    lastRunAt: '2026-02-01T00:00:00.000Z',
+                    lastRunStatus: 'success',
+                    cadence: 'daily',
+                    purposeTags: ['delta'],
+                    disabled: false,
+                    model: 'sonnet',
+                    triggerType: 'schedule',
+                    silent: true,
+                    routingMode: 'default',
+                    channel: 'general',
+                },
+            },
+        };
+        await fs.writeFile(statsPath, JSON.stringify(v8Store), 'utf-8');
+        const stats = await loadRunStats(statsPath);
+        expect(stats.getStore().version).toBe(10);
+        const rec = stats.getRecord('cron-v8');
+        expect(rec).toBeDefined();
+        expect(rec.cronId).toBe('cron-v8');
+        expect(rec.runCount).toBe(4);
+        expect(rec.state).toBeUndefined();
+    });
     it('migrates a v6 store to v7 with routingMode and allowedActions undefined on existing records', async () => {
         const v6Store = {
             version: 6,
@@ -367,7 +429,7 @@ describe('loadRunStats version migration', () => {
         };
         await fs.writeFile(statsPath, JSON.stringify(v6Store), 'utf-8');
         const stats = await loadRunStats(statsPath);
-        expect(stats.getStore().version).toBe(8);
+        expect(stats.getStore().version).toBe(10);
         const rec = stats.getRecord('cron-v6');
         expect(rec).toBeDefined();
         expect(rec.cronId).toBe('cron-v6');

package/dist/discord/actions-crons.js

@@ -89,6 +89,53 @@ function requestRunningJobCancel(cronCtx, threadId, cronId) {
     }
     return canceled;
 }
+/**
+ * Parse and validate a comma-separated chain string. Returns parsed cronIds or an error message.
+ */
+function parseAndValidateChain(chainStr, statsStore, selfCronId) {
+    if (chainStr === '') {
+        return { ids: [] };
+    }
+    const ids = chainStr.split(',').map((s) => s.trim()).filter(Boolean);
+    if (ids.length === 0) {
+        return { error: 'chain requires at least one cronId if provided' };
+    }
+    // Validate each cronId exists.
+    const missing = ids.filter((id) => !statsStore.getRecord(id));
+    if (missing.length > 0) {
+        return { error: `chain contains unknown cronIds: ${missing.join(', ')}` };
+    }
+    // No self-referencing.
+    if (selfCronId && ids.includes(selfCronId)) {
+        return { error: 'chain cannot reference itself' };
+    }
+    return { ids };
+}
+/**
+ * Detect cycles in the chain graph. Returns true if adding the proposed chain
+ * to `cronId` would create a cycle.
+ */
+function detectChainCycle(cronId, proposedChain, statsStore) {
+    // BFS from each downstream job, checking if we can reach cronId.
+    const visited = new Set();
+    const queue = [...proposedChain];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === cronId)
+            return true;
+        if (visited.has(current))
+            continue;
+        visited.add(current);
+        const rec = statsStore.getRecord(current);
+        if (rec?.chain) {
+            for (const next of rec.chain) {
+                if (!visited.has(next))
+                    queue.push(next);
+            }
+        }
+    }
+    return false;
+}
 // ---------------------------------------------------------------------------
 // Executor
 // ---------------------------------------------------------------------------
@@ -119,6 +166,19 @@ export async function executeCronAction(action, ctx, cronCtx) {
                 }
                 parsedAllowedActions = parts;
             }
+            // Validate chain if provided.
+            let parsedChain;
+            if (action.chain !== undefined) {
+                const chainResult = parseAndValidateChain(action.chain, cronCtx.statsStore);
+                if ('error' in chainResult) {
+                    return { ok: false, error: chainResult.error };
+                }
+                if (chainResult.ids.length > 0) {
+                    // No cycle detection needed on create — this job doesn't exist yet so
+                    // no other job can reference it as a downstream target.
+                    parsedChain = chainResult.ids;
+                }
+            }
             // Create forum thread.
             const forum = await resolveForumChannel(cronCtx.client, cronCtx.forumId);
             if (!forum) {
@@ -209,6 +269,7 @@ export async function executeCronAction(action, ctx, cronCtx) {
                 authorId: cronCtx.client.user?.id,
                 ...(action.routingMode ? { routingMode: action.routingMode } : {}),
                 ...(parsedAllowedActions !== undefined && { allowedActions: parsedAllowedActions }),
+                ...(parsedChain !== undefined && { chain: parsedChain }),
             });
             // Create status message.
             try {
@@ -232,7 +293,7 @@ export async function executeCronAction(action, ctx, cronCtx) {
                 cronCtx.log?.warn({ err, cronId }, 'cron:action:create prompt message failed');
             }
             cronCtx.forumCountSync?.requestUpdate();
-            return { ok: true, summary: `Cron "${action.name}" created (${cronId}), schedule: ${action.schedule}, model: ${model}${action.routingMode ? `, routing: ${action.routingMode}` : ''}` };
+            return { ok: true, summary: `Cron "${action.name}" created (${cronId}), schedule: ${action.schedule}, model: ${model}${action.routingMode ? `, routing: ${action.routingMode}` : ''}${parsedChain ? `, chain: ${parsedChain.join(', ')}` : ''}` };
         }
         case 'cronUpdate': {
             if (!action.cronId) {
@@ -290,6 +351,39 @@ export async function executeCronAction(action, ctx, cronCtx) {
                     changes.push(`allowedActions → ${parts.join(', ')}`);
                 }
             }
+            // Chain override.
+            if (action.chain !== undefined) {
+                if (action.chain === '') {
+                    updates.chain = undefined;
+                    changes.push('chain cleared');
+                }
+                else {
+                    const chainResult = parseAndValidateChain(action.chain, cronCtx.statsStore, action.cronId);
+                    if ('error' in chainResult) {
+                        return { ok: false, error: chainResult.error };
+                    }
+                    if (detectChainCycle(action.cronId, chainResult.ids, cronCtx.statsStore)) {
+                        return { ok: false, error: 'chain would create a cycle' };
+                    }
+                    updates.chain = chainResult.ids;
+                    changes.push(`chain → ${chainResult.ids.join(', ')}`);
+                }
+            }
+            // State override (manual JSON manipulation).
+            if (action.state !== undefined) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(action.state);
+                }
+                catch {
+                    return { ok: false, error: 'state must be valid JSON' };
+                }
+                if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+                    return { ok: false, error: 'state must be a JSON object' };
+                }
+                updates.state = parsed;
+                changes.push('state updated');
+            }
             // Definition changes (schedule, timezone, channel, prompt).
             const newSchedule = action.schedule ?? job.def.schedule ?? '';
             const newTimezone = action.timezone ?? job.def.timezone;
@@ -446,7 +540,8 @@ export async function executeCronAction(action, ctx, cronCtx) {
                 const tags = record?.purposeTags?.join(', ') || '';
                 const nextRun = j.nextRun ? `<t:${Math.floor(j.nextRun.getTime() / 1000)}:R>` : 'N/A';
                 const cronId = fullJob?.cronId ?? '?';
-                return `\`${cronId}\` **${j.name}** | \`${j.schedule}\` | ${displayStatus} | ${model} | ${runs} runs | next: ${nextRun}${tags ? ` | ${tags}` : ''}`;
+                const chained = record?.chain && record.chain.length > 0 ? ' | chained' : '';
+                return `\`${cronId}\` **${j.name}** | \`${j.schedule}\` | ${displayStatus} | ${model} | ${runs} runs | next: ${nextRun}${tags ? ` | ${tags}` : ''}${chained}`;
             });
             return { ok: true, summary: lines.join('\n') };
         }
@@ -484,8 +579,20 @@ export async function executeCronAction(action, ctx, cronCtx) {
                 lines.push(`Tags: ${record.purposeTags.join(', ')}`);
             if (record.allowedActions && record.allowedActions.length > 0)
                 lines.push(`Allowed actions: ${record.allowedActions.join(', ')}`);
+            if (record.chain && record.chain.length > 0) {
+                const chainEntries = record.chain.map((id) => {
+                    const downstream = cronCtx.statsStore.getRecord(id);
+                    const downstreamJob = downstream ? cronCtx.scheduler.getJob(downstream.threadId) : undefined;
+                    return `\`${id}\`${downstreamJob ? ` (${downstreamJob.name})` : ''}`;
+                });
+                lines.push(`Chain: ${chainEntries.join(', ')}`);
+            }
             if (record.lastErrorMessage)
                 lines.push(`Last error: ${record.lastErrorMessage}`);
+            if (record.state && Object.keys(record.state).length > 0) {
+                const stateJson = JSON.stringify(record.state);
+                lines.push(`State: ${stateJson.length > 500 ? stateJson.slice(0, 500) + '... (truncated)' : stateJson}`);
+            }
             // Return full prompt text — prefer the persisted record prompt (always full),
             // falling back to the scheduler def (also full).
             const promptText = record.prompt ?? job?.def.prompt;
@@ -723,6 +830,7 @@ export function cronActionsPromptSection() {
 - \`model\` (optional): "fast", "capable", or "deep" (auto-classified if omitted).
 - \`routingMode\` (optional): Set to \`"json"\` to enable JSON routing mode. In this mode the executor uses the JSON router to dispatch structured responses. The prompt may contain \`{{channel}}\` and \`{{channelId}}\` placeholders which are expanded to the target channel name and ID at runtime.
 - \`allowedActions\` (optional): Comma-separated list of Discord action types this job may emit (e.g., "cronList,cronShow"). Restricts the AI to only these action types during execution. Rejects unrecognized type names. Requires at least one entry if provided.
+- \`chain\` (optional): Comma-separated cronIds of downstream jobs to trigger on successful completion (e.g., "cron-a1b2c3d4,cron-e5f6g7h8"). Creates a multi-step pipeline — the completed job's persisted state is forwarded to downstream jobs. Referenced cronIds must exist. Cycles are rejected.
 
 **cronUpdate** — Update a cron's settings:
 \`\`\`
@@ -733,6 +841,8 @@ export function cronActionsPromptSection() {
 - \`silent\` (optional): Boolean. When true, suppresses short "nothing to report" responses.
 - \`routingMode\` (optional): Set to \`"json"\` to enable JSON routing mode, or omit/pass empty string to clear.
 - \`allowedActions\` (optional): Update the allowed action types list. Empty string clears the restriction.
+- \`chain\` (optional): Update downstream pipeline jobs (comma-separated cronIds). Empty string clears the chain. Cycles are detected and rejected.
+- \`state\` (optional): JSON string to replace the job's persistent state object (e.g., \`"{\\"cursor\\":\\"abc\\"}"\`). Must be a JSON object. Used for manual state manipulation; normally state is managed by the job itself.
 
 **cronList** — List all cron jobs:
 \`\`\`

package/dist/discord/actions-crons.test.js

@@ -663,4 +663,52 @@ describe('executeCronAction', () => {
             expect(result.summary).not.toContain('Allowed actions:');
         }
     });
+    it('cronUpdate with valid state JSON persists it', async () => {
+        const cronCtx = makeCronCtx();
+        const result = await executeCronAction({ type: 'cronUpdate', cronId: 'cron-test0001', state: '{"cursor":"abc","count":5}' }, makeActionCtx(), cronCtx);
+        expect(result.ok).toBe(true);
+        expect(cronCtx.statsStore.upsertRecord).toHaveBeenCalledWith('cron-test0001', 'thread-1', expect.objectContaining({ state: { cursor: 'abc', count: 5 } }));
+    });
+    it('cronUpdate with invalid state JSON returns error', async () => {
+        const cronCtx = makeCronCtx();
+        const result = await executeCronAction({ type: 'cronUpdate', cronId: 'cron-test0001', state: 'not-json' }, makeActionCtx(), cronCtx);
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error).toContain('valid JSON');
+    });
+    it('cronUpdate with non-object state JSON returns error', async () => {
+        const cronCtx = makeCronCtx();
+        const result = await executeCronAction({ type: 'cronUpdate', cronId: 'cron-test0001', state: '[1,2,3]' }, makeActionCtx(), cronCtx);
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error).toContain('JSON object');
+    });
+    it('cronUpdate with empty object state clears state', async () => {
+        const cronCtx = makeCronCtx({
+            statsStore: makeStatsStore([makeRecord({ state: { old: 'value' } })]),
+        });
+        const result = await executeCronAction({ type: 'cronUpdate', cronId: 'cron-test0001', state: '{}' }, makeActionCtx(), cronCtx);
+        expect(result.ok).toBe(true);
+        expect(cronCtx.statsStore.upsertRecord).toHaveBeenCalledWith('cron-test0001', 'thread-1', expect.objectContaining({ state: {} }));
+    });
+    it('cronShow includes state when present', async () => {
+        const cronCtx = makeCronCtx({
+            statsStore: makeStatsStore([makeRecord({ state: { cursor: 'xyz', count: 10 } })]),
+        });
+        const result = await executeCronAction({ type: 'cronShow', cronId: 'cron-test0001' }, makeActionCtx(), cronCtx);
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.summary).toContain('State:');
+            expect(result.summary).toContain('"cursor"');
+            expect(result.summary).toContain('"xyz"');
+        }
+    });
+    it('cronShow omits state when empty', async () => {
+        const cronCtx = makeCronCtx();
+        const result = await executeCronAction({ type: 'cronShow', cronId: 'cron-test0001' }, makeActionCtx(), cronCtx);
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.summary).not.toContain('State:');
+        }
+    });
 });

package/dist/index.js

@@ -1428,6 +1428,7 @@ if (cronEnabled && effectiveCronForum) {
         statsStore: cronStats,
         lockDir: cronLocksDir,
         runControl: cronRunControl,
+        getSchedulerJob: (threadId) => cronScheduler.getJob(threadId),
     };
     savedCronExecCtx = cronExecCtx;
     cronCtx.executorCtx = cronExecCtx;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discoclaw",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Minimal Discord bridge routing messages to AI runtimes",
   "license": "MIT",
   "repository": {