discoclaw 0.2.4 → 0.3.0

package/.context/pa.md

@@ -16,7 +16,6 @@ For architecture details, see `.context/architecture.md`.
 | `USER.md` | Who you're helping | Every prompt |
 | `AGENTS.md` | Your personal rules and conventions | Every prompt |
 | `TOOLS.md` | Available tools and integrations | Every prompt |
-| `HEARTBEAT.md` | Periodic self-check template | By cron |
 | `MEMORY.md` | Curated long-term memory | DM prompts |
 | `BOOTSTRAP.md` | First-run onboarding (deleted after) | Once |
 
@@ -27,6 +26,7 @@ Templates live in `templates/workspace/` and are scaffolded on first run (copy-i
 - **Never go silent.** Acknowledge before tool calls.
 - Narrate failures and pivots.
 - Summarize outcomes; don't assume the user saw tool output.
+- **Never edit `tasks.jsonl`, cron store files, or other data files directly.** Always use the corresponding discord action (`taskUpdate`, `taskCreate`, `cronUpdate`, etc.). Direct file edits bypass Discord thread sync and leave the UI stale.
 
 ## Discord Formatting
 

package/.context/runtime.md

@@ -114,20 +114,64 @@ Shutdown: `killAllSubprocesses()` from `cli-adapter.ts` kills all tracked subpro
   | `OPENROUTER_MODEL` | `anthropic/claude-sonnet-4` | Default model (provider-namespaced) |
 - Model naming: OpenRouter uses provider-namespaced IDs — e.g. `anthropic/claude-sonnet-4`, `openai/gpt-4o`, `google/gemini-2.5-pro`. Never use bare model names.
 - Capabilities:
-  - `streaming_text` only
-  - No tool execution
+  - `streaming_text` only (unless `OPENAI_COMPAT_TOOLS_ENABLED=1` — see [OpenAI-Compat Tool Use](#openai-compat-tool-use) below)
+  - No tool execution (unless `OPENAI_COMPAT_TOOLS_ENABLED=1`)
   - No sessions / multi-turn
 - Health system: credential presence checked via `checkOpenRouterKey` — returns `skip` if key is missing, `fail` if key is present but invalid/expired.
 
+## OpenAI-Compat Tool Use
+
+The OpenAI-compatible and OpenRouter adapters support optional server-side tool use via the standard OpenAI function-calling protocol. Disabled by default; enable with `OPENAI_COMPAT_TOOLS_ENABLED=1`.
+
+| Env Var | Default | Purpose |
+|---------|---------|---------|
+| `OPENAI_COMPAT_TOOLS_ENABLED` | `0` | Enable tool use (function calling) for OpenAI-compat and OpenRouter adapters |
+
+When enabled, the adapter:
+1. Declares `tools_fs` + `tools_exec` capabilities (making it eligible for tool-bearing prompts).
+2. Sends OpenAI function-calling tool definitions alongside the chat completion request.
+3. Runs a synchronous (non-streaming) tool loop: model returns `tool_calls` → server executes them → results fed back → repeat until the model returns a final text response or the safety cap (25 rounds) is reached.
+
+### Available tools
+
+The tool surface is the same as the configured `RUNTIME_TOOLS` set, mapped to OpenAI function names:
+
+| Discoclaw tool | OpenAI function | Notes |
+|----------------|-----------------|-------|
+| Read | `read_file` | Read file contents (with optional offset/limit) |
+| Write | `write_file` | Create or overwrite a file |
+| Edit | `edit_file` | Exact string replacement in a file |
+| Glob | `list_files` | Find files matching a glob pattern |
+| Grep | `search_content` | Regex search over file contents |
+| Bash | `bash` | Execute a shell command (30s timeout, 100KB output cap) |
+| WebFetch | `web_fetch` | Fetch a web page (15s timeout, 512KB cap, SSRF-protected) |
+| WebSearch | `web_search` | **Stub — not yet implemented.** Returns an error message. |
+
+Schemas: `src/runtime/openai-tool-schemas.ts`. Execution handlers: `src/runtime/openai-tool-exec.ts`.
+
+### Security
+
+- **Path scoping:** File/path tools (Read, Write, Edit, Glob, Grep, Bash) are scoped to the workspace CWD (`WORKSPACE_CWD`) **plus** any additional directories from `--add-dir` / group CWD configuration. Symlink-escape protection via `fs.realpath`.
+- **SSRF protection:** `web_fetch` blocks private/loopback IPs and localhost hostnames; HTTPS only with redirect rejection.
+- **Bash sandboxing:** 30s timeout, 100KB output cap per stream (stdout/stderr).
+
+### Key files
+
+| File | Role |
+|------|------|
+| `src/runtime/openai-compat.ts` | Adapter: tool loop logic, capability declaration |
+| `src/runtime/openai-tool-schemas.ts` | Discoclaw → OpenAI function name mapping and JSON Schema definitions |
+| `src/runtime/openai-tool-exec.ts` | Server-side tool execution handlers with path validation |
+
 ## Tool Surface
 - Default tools: `Bash, Read, Write, Edit, Glob, Grep, WebSearch, WebFetch` (8 tools).
 - `Glob` + `Grep` are purpose-built for file search — faster than `find`/`grep` via Bash.
 - `Write` enables proper file creation (previously required Bash echo/cat workarounds).
 - Non-Claude adapters use a **capability gate** (`tools_fs`) to determine tool access:
   - Codex CLI adapter: declares `tools_fs` — receives read-only tools (Read, Glob, Grep) in auditor role.
-  - OpenAI HTTP adapter: text-only (`streaming_text` only) — no tool execution.
+  - OpenAI HTTP adapter: when `OPENAI_COMPAT_TOOLS_ENABLED=1`, declares `tools_fs` + `tools_exec` and runs a server-side tool loop (see below). Otherwise text-only (`streaming_text` only).
   - Gemini CLI adapter: text-only (`streaming_text` only) — no tool execution, no fs tools (Phase 1).
-  - OpenRouter adapter: text-only (`streaming_text` only) — no tool execution.
+  - OpenRouter adapter: when `OPENAI_COMPAT_TOOLS_ENABLED=1`, declares `tools_fs` + `tools_exec` (same adapter, same flag). Otherwise text-only (`streaming_text` only).
 
 ## Per-Workspace Permissions
 - `workspace/PERMISSIONS.json` controls the tool surface per workspace.

package/.env.example

@@ -75,6 +75,12 @@ DISCORD_GUILD_ID=
 # Default model for the Gemini CLI adapter.
 #GEMINI_MODEL=gemini-2.5-pro
 
+# --- OpenAI-compatible HTTP adapter ---
+#OPENAI_API_KEY=
+#OPENAI_MODEL=gpt-4o
+# Enable tool use (function calling) for OpenAI-compat and OpenRouter adapters.
+#OPENAI_COMPAT_TOOLS_ENABLED=0
+
 # --- OpenRouter adapter ---
 #OPENROUTER_API_KEY=
 #OPENROUTER_BASE_URL=https://openrouter.ai/api/v1

package/.env.example.full

@@ -410,6 +410,13 @@ DISCOCLAW_DISCORD_ACTIONS_DEFER=1
 #OPENAI_BASE_URL=https://api.openai.com/v1
 # Default model when FORGE_AUDITOR_MODEL is not set.
 #OPENAI_MODEL=gpt-4o
+# Enable tool use (function calling) for OpenAI-compat and OpenRouter adapters.
+# When enabled, models can autonomously read files, run commands, edit code, etc.
+# via the standard OpenAI function-calling protocol with a server-side tool loop.
+# File/path access is scoped to the workspace CWD (WORKSPACE_CWD) plus any
+# additional directories from --add-dir / group CWD configuration.
+# Default: 0 (disabled — streaming text only).
+#OPENAI_COMPAT_TOOLS_ENABLED=0
 
 # --- OpenRouter adapter ---
 # API key for OpenRouter. Required when PRIMARY_RUNTIME=openrouter or FORGE_*_RUNTIME=openrouter.

package/README.md

@@ -56,7 +56,7 @@ Recurring tasks defined as forum threads in plain language — no crontab, no se
 
 ## How it works
 
-DiscoClaw orchestrates the flow between Discord and AI runtimes (Claude Code by default, with Gemini, OpenAI, Codex, and OpenRouter adapters available via `PRIMARY_RUNTIME`). It doesn't contain intelligence itself — it decides *when* to call the AI, *what context* to give it, and *what to do* with the output. When you send a message, the orchestrator:
+DiscoClaw orchestrates the flow between Discord and AI runtimes (Claude Code by default, with Gemini, OpenAI, Codex, and OpenRouter adapters available via `PRIMARY_RUNTIME`). The OpenAI-compatible and OpenRouter adapters support optional tool use (function calling) when `OPENAI_COMPAT_TOOLS_ENABLED=1` is set. It doesn't contain intelligence itself — it decides *when* to call the AI, *what context* to give it, and *what to do* with the output. When you send a message, the orchestrator:
 
 1. Checks the user allowlist (fail-closed — empty list means respond to nobody)
 2. Assembles context: per-channel rules, conversation history, rolling summary, and durable memory
@@ -87,6 +87,10 @@ DiscoClaw supports a shareable markdown recipe format for passing integrations b
 
 Author one recipe file for an integration, share it, then let another user's DiscoClaw agent consume it and produce a local implementation checklist before coding.
 
+### MCP (Model Context Protocol)
+
+When using the Claude runtime, you can connect external tool servers via MCP. Place a `.mcp.json` file in your workspace directory to configure servers — their tools become available during conversations. See [docs/mcp.md](docs/mcp.md) for the config format, examples, and troubleshooting.
+
 ## Prerequisites
 
 **End users:**

package/dist/config.js

@@ -202,6 +202,7 @@ export function parseConfig(env) {
     const openaiApiKey = parseTrimmedString(env, 'OPENAI_API_KEY');
     const openaiBaseUrl = parseTrimmedString(env, 'OPENAI_BASE_URL');
     const openaiModel = parseTrimmedString(env, 'OPENAI_MODEL') ?? 'gpt-4o';
+    const openaiCompatToolsEnabled = parseBoolean(env, 'OPENAI_COMPAT_TOOLS_ENABLED', false);
     const imagegenGeminiApiKey = parseTrimmedString(env, 'IMAGEGEN_GEMINI_API_KEY');
     const imagegenDefaultModel = parseTrimmedString(env, 'IMAGEGEN_DEFAULT_MODEL');
     if (primaryRuntime === 'openai' && !openaiApiKey) {
@@ -330,6 +331,7 @@ export function parseConfig(env) {
             openaiApiKey,
             openaiBaseUrl,
             openaiModel,
+            openaiCompatToolsEnabled,
             imagegenGeminiApiKey,
             imagegenDefaultModel,
             forgeDrafterRuntime,

package/dist/cron/cron-sync-coordinator.js

@@ -15,6 +15,10 @@ export class CronSyncCoordinator {
     setAutoTagModel(model) {
         this.opts = { ...this.opts, autoTagModel: model };
     }
+    /** Swap the runtime adapter at runtime (called by modelSet runtime-swap propagation). */
+    setRuntime(runtime) {
+        this.opts = { ...this.opts, runtime };
+    }
     /**
      * Run sync with concurrency guard.
      * Returns null when coalesced into a running sync's follow-up.

package/dist/cron/cron-sync-coordinator.test.js

@@ -115,4 +115,12 @@ describe('CronSyncCoordinator', () => {
         const callArgs = mockRunCronSync.mock.calls[0][0];
         expect(callArgs.autoTagModel).toBe('opus');
     });
+    it('setRuntime updates the runtime used by subsequent syncs', async () => {
+        const newRuntime = { id: 'openrouter' };
+        const coordinator = new CronSyncCoordinator(makeOpts());
+        coordinator.setRuntime(newRuntime);
+        await coordinator.sync();
+        const callArgs = mockRunCronSync.mock.calls[0][0];
+        expect(callArgs.runtime).toBe(newRuntime);
+    });
 });

package/dist/cron/executor.js

@@ -124,6 +124,10 @@ export async function executeCronJob(job, ctx) {
         if (preRunRecord) {
             effectiveModel = preRunRecord.modelOverride ?? preRunRecord.model ?? cronDefault;
         }
+        // Silent mode: instruct the AI to respond with HEARTBEAT_OK when idle.
+        if (preRunRecord?.silent) {
+            prompt += '\n\nIMPORTANT: If there is nothing actionable to report, respond with exactly `HEARTBEAT_OK` and nothing else.';
+        }
         ctx.log?.info({ jobId: job.id, name: job.name, channel: job.def.channel, model: effectiveModel, permissionTier: tools.permissionTier }, 'cron:exec start');
         // Best-effort: update pinned status message to show running indicator.
         if (preRunRecord && job.cronId) {
@@ -269,13 +273,44 @@ export async function executeCronJob(job, ctx) {
         }
         processedText = appendUnavailableActionTypesNotice(processedText, strippedUnrecognizedTypes);
         processedText = appendParseFailureNotice(processedText, parseFailuresCount);
+        // Suppress sentinel outputs (e.g. crons whose prompts say "output nothing if idle").
+        // Mirrors the reaction handler's logic at reaction-handler.ts:662-674.
+        const strippedText = processedText.replace(/\s+/g, ' ').trim();
+        const isSuppressible = strippedText === 'HEARTBEAT_OK' || strippedText === '(no output)';
+        if (isSuppressible && collectedImages.length === 0) {
+            ctx.log?.info({ jobId: job.id, name: job.name, sentinel: strippedText }, 'cron:exec sentinel output suppressed');
+            if (ctx.statsStore && job.cronId) {
+                try {
+                    await ctx.statsStore.recordRun(job.cronId, 'success');
+                }
+                catch {
+                    // Best-effort.
+                }
+            }
+            metrics.increment('cron.run.success');
+            return;
+        }
+        // Silent-mode short-response gate: suppress paraphrased "nothing to report" responses.
+        if (preRunRecord?.silent && collectedImages.length === 0 && strippedText.length <= 80) {
+            ctx.log?.info({ jobId: job.id, name: job.name, len: strippedText.length }, 'cron:exec silent short-response suppressed');
+            if (ctx.statsStore && job.cronId) {
+                try {
+                    await ctx.statsStore.recordRun(job.cronId, 'success');
+                }
+                catch {
+                    // Best-effort.
+                }
+            }
+            metrics.increment('cron.run.success');
+            return;
+        }
         await sendChunks(channelForSend, processedText, collectedImages);
         ctx.log?.info({ jobId: job.id, name: job.name, channel: job.def.channel }, 'cron:exec done');
+        metrics.increment('cron.run.success');
         // Record successful run.
         if (ctx.statsStore && job.cronId) {
             try {
                 await ctx.statsStore.recordRun(job.cronId, 'success');
-                metrics.increment('cron.run.success');
             }
             catch (statsErr) {
                 ctx.log?.warn({ err: statsErr, jobId: job.id }, 'cron:exec stats record failed');

package/dist/cron/executor.test.js

@@ -324,6 +324,55 @@ describe('executeCronJob', () => {
         expect(subsArg).toMatchObject({ imagegenCtx });
         executeDiscordActionsSpy.mockRestore();
     });
+    it('suppresses HEARTBEAT_OK output', async () => {
+        const ctx = makeCtx({ runtime: makeMockRuntime('HEARTBEAT_OK') });
+        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).not.toHaveBeenCalled();
+        expect(ctx.log?.info).toHaveBeenCalledWith(expect.objectContaining({ jobId: job.id, sentinel: 'HEARTBEAT_OK' }), 'cron:exec sentinel output suppressed');
+    });
+    it('suppresses (no output) output', async () => {
+        const ctx = makeCtx({ runtime: makeMockRuntime('(no output)') });
+        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).not.toHaveBeenCalled();
+    });
+    it('does not suppress HEARTBEAT_OK when images are present', async () => {
+        const runtime = {
+            id: 'claude_code',
+            capabilities: new Set(['streaming_text']),
+            async *invoke() {
+                yield { type: 'text_final', text: 'HEARTBEAT_OK' };
+                yield { type: 'image_data', image: { mediaType: 'image/png', base64: 'abc123' } };
+                yield { type: 'done' };
+            },
+        };
+        const ctx = makeCtx({ runtime });
+        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();
+    });
+    it('records success in statsStore when sentinel is suppressed', async () => {
+        const statsStore = {
+            recordRun: vi.fn().mockResolvedValue(undefined),
+            recordRunStart: vi.fn().mockResolvedValue(undefined),
+            getRecord: vi.fn().mockReturnValue(undefined),
+            upsertRecord: vi.fn().mockResolvedValue(undefined),
+        };
+        const ctx = makeCtx({ runtime: makeMockRuntime('HEARTBEAT_OK'), statsStore });
+        const job = makeJob();
+        await executeCronJob(job, ctx);
+        expect(statsStore.recordRun).toHaveBeenCalledWith('cron-test0001', 'success');
+        const guild = ctx.client.guilds.cache.get('guild-1');
+        const channel = guild.channels.cache.get('general');
+        expect(channel.send).not.toHaveBeenCalled();
+    });
     it('does not post if output is empty', async () => {
         const ctx = makeCtx({ runtime: makeMockRuntime('') });
         const job = makeJob();
@@ -730,3 +779,111 @@ describe('executeCronJob write-ahead status tracking', () => {
         expect(rec?.lastRunStatus).toBe('success');
     });
 });
+// ---------------------------------------------------------------------------
+// Silent mode suppression
+// ---------------------------------------------------------------------------
+describe('executeCronJob silent mode', () => {
+    let statsDir;
+    beforeEach(async () => {
+        statsDir = await fs.mkdtemp(path.join(os.tmpdir(), 'executor-silent-'));
+    });
+    afterEach(async () => {
+        await fs.rm(statsDir, { recursive: true, force: true });
+    });
+    function makeCapturingRuntime(response) {
+        const invokeSpy = vi.fn();
+        return {
+            runtime: {
+                id: 'claude_code',
+                capabilities: new Set(['streaming_text']),
+                async *invoke(params) {
+                    invokeSpy(params);
+                    yield { type: 'text_final', text: response };
+                    yield { type: 'done' };
+                },
+            },
+            invokeSpy,
+        };
+    }
+    it('injects HEARTBEAT_OK instruction into the prompt when silent is true', async () => {
+        const statsPath = path.join(statsDir, 'stats.json');
+        const statsStore = await loadRunStats(statsPath);
+        await statsStore.upsertRecord('cron-test0001', 'thread-1', { silent: true });
+        const { runtime, invokeSpy } = makeCapturingRuntime('Hello!');
+        const ctx = makeCtx({ statsStore, runtime });
+        const job = makeJob();
+        await executeCronJob(job, ctx);
+        expect(invokeSpy).toHaveBeenCalledOnce();
+        const prompt = invokeSpy.mock.calls[0][0].prompt;
+        expect(prompt).toContain('respond with exactly `HEARTBEAT_OK`');
+    });
+    it('suppresses short responses under the threshold when silent is true', async () => {
+        const statsPath = path.join(statsDir, 'stats.json');
+        const statsStore = await loadRunStats(statsPath);
+        await statsStore.upsertRecord('cron-test0001', 'thread-1', { silent: true });
+        const ctx = makeCtx({ statsStore, runtime: makeMockRuntime('No task-labeled emails found.') });
+        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).not.toHaveBeenCalled();
+        expect(ctx.log?.info).toHaveBeenCalledWith(expect.objectContaining({ jobId: job.id, name: job.name }), 'cron:exec silent short-response suppressed');
+    });
+    it('does NOT suppress longer substantive responses when silent is true', async () => {
+        const statsPath = path.join(statsDir, 'stats.json');
+        const statsStore = await loadRunStats(statsPath);
+        await statsStore.upsertRecord('cron-test0001', 'thread-1', { silent: true });
+        const longResponse = 'Here is a detailed summary of the tasks completed today, including several important updates that need your attention.';
+        const ctx = makeCtx({ statsStore, runtime: makeMockRuntime(longResponse) });
+        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).toHaveBeenCalledOnce();
+        expect(channel.send.mock.calls[0][0].content).toContain(longResponse);
+    });
+    it('does not apply short-response gate when silent is false', async () => {
+        const statsPath = path.join(statsDir, 'stats.json');
+        const statsStore = await loadRunStats(statsPath);
+        await statsStore.upsertRecord('cron-test0001', 'thread-1', { silent: false });
+        const ctx = makeCtx({ statsStore, runtime: makeMockRuntime('No emails found.') });
+        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).toHaveBeenCalledOnce();
+    });
+    it('does NOT suppress short text when images are present (silent mode)', async () => {
+        const statsPath = path.join(statsDir, 'stats.json');
+        const statsStore = await loadRunStats(statsPath);
+        await statsStore.upsertRecord('cron-test0001', 'thread-1', { silent: true });
+        const runtime = {
+            id: 'claude_code',
+            capabilities: new Set(['streaming_text']),
+            async *invoke() {
+                yield { type: 'text_final', text: 'Short.' };
+                yield { type: 'image_data', image: { mediaType: 'image/png', base64: 'abc123' } };
+                yield { type: 'done' };
+            },
+        };
+        const ctx = makeCtx({ statsStore, runtime });
+        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();
+    });
+    it('records success in statsStore when silent short-response is suppressed', async () => {
+        const statsPath = path.join(statsDir, 'stats.json');
+        const statsStore = await loadRunStats(statsPath);
+        await statsStore.upsertRecord('cron-test0001', 'thread-1', { silent: true });
+        const recordRunSpy = vi.spyOn(statsStore, 'recordRun');
+        const ctx = makeCtx({ statsStore, runtime: makeMockRuntime('Nothing to report.') });
+        const job = makeJob();
+        await executeCronJob(job, ctx);
+        expect(recordRunSpy).toHaveBeenCalledWith('cron-test0001', 'success');
+        const guild = ctx.client.guilds.cache.get('guild-1');
+        const channel = guild.channels.cache.get('general');
+        expect(channel.send).not.toHaveBeenCalled();
+    });
+});

package/dist/cron/forum-sync.js

@@ -148,6 +148,12 @@ async function loadThreadAsCron(thread, guildId, scheduler, runtime, opts) {
                 cadence,
                 // Preserve existing disabled state.
                 disabled: existingRecord?.disabled ?? false,
+                // Persist parsed definition so future boots skip AI re-parsing.
+                schedule: def.schedule,
+                timezone: def.timezone,
+                channel: def.channel,
+                prompt: def.prompt,
+                authorId: starterAuthorId,
             });
             // Restore disabled state from stats.
             if (existingRecord?.disabled) {
@@ -207,6 +213,47 @@ export async function initCronForum(opts) {
     for (const thread of activeThreads.values()) {
         if (thread.archived)
             continue;
+        // Fast path: if the stats store already has a parsed definition for this
+        // thread, reconstruct the ParsedCronDef and register directly — skipping
+        // the AI parser entirely.  This avoids wasted AI calls on every boot and
+        // prevents parse-failure errors on threads whose starters aren't parseable
+        // (e.g. bot-formatted messages created by cronCreate).
+        if (statsStore) {
+            const record = statsStore.getRecordByThreadId(thread.id);
+            if (record && record.channel && record.prompt &&
+                (record.schedule || (record.triggerType !== undefined && record.triggerType !== 'schedule'))) {
+                // Authorization: verify stored author is still permitted.
+                const authorId = record.authorId ?? '';
+                const botUserId = client.user?.id ?? '';
+                const isBotAuthored = botUserId !== '' && authorId === botUserId;
+                if (!authorId || (!allowUserIds.has(authorId) && !isBotAuthored)) {
+                    // Author not authorized — fall through to loadThreadAsCron which
+                    // will reject and disable through its existing path.
+                }
+                else {
+                    const def = {
+                        triggerType: record.triggerType ?? 'schedule',
+                        schedule: record.schedule,
+                        timezone: record.timezone ?? 'UTC',
+                        channel: record.channel,
+                        prompt: record.prompt,
+                    };
+                    try {
+                        scheduler.register(thread.id, thread.id, guildId, thread.name, def, record.cronId);
+                        if (record.disabled) {
+                            scheduler.disable(thread.id);
+                            log?.info({ threadId: thread.id, cronId: record.cronId }, 'cron:forum fast-path restored disabled state');
+                        }
+                        loaded++;
+                        log?.info({ threadId: thread.id, cronId: record.cronId }, 'cron:forum fast-path loaded from stored definition');
+                        continue;
+                    }
+                    catch (err) {
+                        log?.warn({ err, threadId: thread.id, cronId: record.cronId }, 'cron:forum fast-path register failed, falling through to AI parse');
+                    }
+                }
+            }
+        }
         const ok = await loadThreadAsCron(thread, guildId, scheduler, runtime, { cronModel, cwd, log, isNew: false, allowUserIds, statsStore });
         if (ok)
             loaded++;