test(cron): add model fallback regression coverage

CHANGELOG.md

@@ -40,6 +40,7 @@ Docs: https://docs.openclaw.ai
 - Slack: restrict forwarded-attachment ingestion to explicit shared-message attachments and skip non-Slack forwarded `image_url` fetches, preventing non-forward attachment unfurls from polluting inbound agent context while preserving forwarded message handling.
 - Feishu: detect bot mentions in post messages with embedded docs when `message.mentions` is empty. (#18074) Thanks @popomore.
 - Agents/Sessions: align session lock watchdog hold windows with run and compaction timeout budgets (plus grace), preventing valid long-running turns from being force-unlocked mid-run while still recovering hung lock owners. (#18060)
+- Cron: preserve default model fallbacks for cron agent runs when only `model.primary` is overridden, so failover still follows configured fallbacks unless explicitly cleared with `fallbacks: []`. (#18210) Thanks @mahsumaktas.
 - Cron/Heartbeat: canonicalize session-scoped reminder `sessionKey` routing and preserve explicit flat `sessionKey` cron tool inputs, preventing enqueue/wake namespace drift for session-targeted reminders. (#18637) Thanks @vignesh07.
 - Cron/Webhooks: reuse existing session IDs for webhook/cron runs when the session key is stable and still fresh, preserving conversation history. (#18031) Thanks @Operative-001.
 - Cron: prevent spin loops when cron jobs complete within the scheduled second by advancing the next run and enforcing a minimum refire gap. (#18073) Thanks @widingmarcus-cyber.

docs/gateway/configuration-reference.md

@@ -991,7 +991,7 @@ scripts/sandbox-browser-setup.sh   # optional browser image
 
 - `id`: stable agent id (required).
 - `default`: when multiple are set, first wins (warning logged). If none set, first list entry is default.
-- `model`: string form overrides `primary` only; object form `{ primary, fallbacks }` overrides both (`[]` disables global fallbacks).
+- `model`: string form overrides `primary` only; object form `{ primary, fallbacks }` overrides both (`[]` disables global fallbacks). Cron jobs that only override `primary` still inherit default fallbacks unless you set `fallbacks: []`.
 - `identity.avatar`: workspace-relative path, `http(s)` URL, or `data:` URI.
 - `identity` derives defaults: `ackReaction` from `emoji`, `mentionPatterns` from `name`/`emoji`.
 - `subagents.allowAgents`: allowlist of agent ids for `sessions_spawn` (`["*"]` = any; default: same agent only).

src/cron/isolated-agent/run.model-fallback-preservation.test.ts

@@ -1,106 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { AgentDefaultsConfig } from "../../config/types.js";
-
-/**
- * Tests for the model merge fix in runCronIsolatedAgentTurn.
- *
- * Bug: When an agent config defines `model: { primary: "..." }` without
- * `fallbacks`, the merge into `agentCfg` replaced the entire model object
- * from defaults—losing `fallbacks`.  This caused cron jobs to have only
- * one model candidate (the pinned model) plus the global primary, skipping
- * all intermediate fallbacks.
- *
- * Fix: Spread the existing `agentCfg.model` before applying the override,
- * so keys like `fallbacks` from `agents.defaults.model` survive when the
- * agent only overrides `primary`.
- */
-describe("agent model override preserves default fallbacks", () => {
-  // Simulates the merge logic extracted from run.ts lines 148–159
-  function mergeAgentModel(
-    defaults: AgentDefaultsConfig,
-    overrideModel: { primary?: string; fallbacks?: string[] } | string | undefined,
-  ): AgentDefaultsConfig {
-    const agentCfg: AgentDefaultsConfig = { ...defaults };
-
-    // --- FIX: merge instead of replace ---
-    const existingModel =
-      agentCfg.model && typeof agentCfg.model === "object" ? agentCfg.model : {};
-    if (typeof overrideModel === "string") {
-      agentCfg.model = { ...existingModel, primary: overrideModel };
-    } else if (overrideModel) {
-      agentCfg.model = { ...existingModel, ...overrideModel };
-    }
-    return agentCfg;
-  }
-
-  const defaultFallbacks = [
-    "anthropic/claude-opus-4-6",
-    "google-gemini-cli/gemini-3-pro-preview",
-    "nvidia/deepseek-ai/deepseek-v3.2",
-  ];
-
-  const defaults: AgentDefaultsConfig = {
-    model: {
-      primary: "openai-codex/gpt-5.3-codex",
-      fallbacks: defaultFallbacks,
-    },
-  };
-
-  it("preserves fallbacks when agent overrides primary as string", () => {
-    const result = mergeAgentModel(defaults, "anthropic/claude-sonnet-4-5");
-    const model = result.model as { primary?: string; fallbacks?: string[] };
-
-    expect(model.primary).toBe("anthropic/claude-sonnet-4-5");
-    expect(model.fallbacks).toEqual(defaultFallbacks);
-  });
-
-  it("preserves fallbacks when agent overrides primary as object", () => {
-    const result = mergeAgentModel(defaults, {
-      primary: "anthropic/claude-sonnet-4-5",
-    });
-    const model = result.model as { primary?: string; fallbacks?: string[] };
-
-    expect(model.primary).toBe("anthropic/claude-sonnet-4-5");
-    expect(model.fallbacks).toEqual(defaultFallbacks);
-  });
-
-  it("allows agent to explicitly override fallbacks", () => {
-    const customFallbacks = ["nvidia/deepseek-ai/deepseek-v3.2"];
-    const result = mergeAgentModel(defaults, {
-      primary: "anthropic/claude-sonnet-4-5",
-      fallbacks: customFallbacks,
-    });
-    const model = result.model as { primary?: string; fallbacks?: string[] };
-
-    expect(model.primary).toBe("anthropic/claude-sonnet-4-5");
-    expect(model.fallbacks).toEqual(customFallbacks);
-  });
-
-  it("allows agent to explicitly clear fallbacks with empty array", () => {
-    const result = mergeAgentModel(defaults, {
-      primary: "anthropic/claude-sonnet-4-5",
-      fallbacks: [],
-    });
-    const model = result.model as { primary?: string; fallbacks?: string[] };
-
-    expect(model.primary).toBe("anthropic/claude-sonnet-4-5");
-    expect(model.fallbacks).toEqual([]);
-  });
-
-  it("leaves model untouched when override is undefined", () => {
-    const result = mergeAgentModel(defaults, undefined);
-    const model = result.model as { primary?: string; fallbacks?: string[] };
-
-    expect(model.primary).toBe("openai-codex/gpt-5.3-codex");
-    expect(model.fallbacks).toEqual(defaultFallbacks);
-  });
-
-  it("handles missing defaults model gracefully", () => {
-    const emptyDefaults: AgentDefaultsConfig = {};
-    const result = mergeAgentModel(emptyDefaults, "anthropic/claude-sonnet-4-5");
-    const model = result.model as { primary?: string; fallbacks?: string[] };
-
-    expect(model.primary).toBe("anthropic/claude-sonnet-4-5");
-    expect(model.fallbacks).toBeUndefined();
-  });
-});

src/cron/isolated-agent/run.skill-filter.test.ts

@@ -1,12 +1,14 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { runWithModelFallback } from "../../agents/model-fallback.js";
 
 // ---------- mocks ----------
 
 const buildWorkspaceSkillSnapshotMock = vi.fn();
+const resolveAgentConfigMock = vi.fn();
 const resolveAgentSkillsFilterMock = vi.fn();
 
 vi.mock("../../agents/agent-scope.js", () => ({
-  resolveAgentConfig: vi.fn().mockReturnValue(undefined),
+  resolveAgentConfig: resolveAgentConfigMock,
   resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent-dir"),
   resolveAgentModelFallbacksOverride: vi.fn().mockReturnValue(undefined),
   resolveAgentWorkspaceDir: vi.fn().mockReturnValue("/tmp/workspace"),
@@ -50,6 +52,8 @@ vi.mock("../../agents/model-fallback.js", () => ({
   }),
 }));
 
+const runWithModelFallbackMock = vi.mocked(runWithModelFallback);
+
 vi.mock("../../agents/pi-embedded.js", () => ({
   runEmbeddedPiAgent: vi.fn().mockResolvedValue({
     payloads: [{ text: "test output" }],
@@ -205,6 +209,7 @@ describe("runCronIsolatedAgentTurn — skill filter", () => {
       resolvedSkills: [],
       version: 42,
     });
+    resolveAgentConfigMock.mockReturnValue(undefined);
     resolveAgentSkillsFilterMock.mockReturnValue(undefined);
     // Fresh session object per test — prevents mutation leaking between tests
     resolveCronSessionMock.mockReturnValue({
@@ -342,4 +347,66 @@ describe("runCronIsolatedAgentTurn — skill filter", () => {
     expect(result.status).toBe("ok");
     expect(buildWorkspaceSkillSnapshotMock).not.toHaveBeenCalled();
   });
+
+  describe("model fallbacks", () => {
+    const defaultFallbacks = [
+      "anthropic/claude-opus-4-6",
+      "google-gemini-cli/gemini-3-pro-preview",
+      "nvidia/deepseek-ai/deepseek-v3.2",
+    ];
+
+    it("preserves defaults when agent overrides primary as string", async () => {
+      resolveAgentConfigMock.mockReturnValue({ model: "anthropic/claude-sonnet-4-5" });
+
+      const result = await runCronIsolatedAgentTurn(
+        makeParams({
+          cfg: {
+            agents: {
+              defaults: {
+                model: { primary: "openai-codex/gpt-5.3-codex", fallbacks: defaultFallbacks },
+              },
+            },
+          },
+          agentId: "scout",
+        }),
+      );
+
+      expect(result.status).toBe("ok");
+      expect(runWithModelFallbackMock).toHaveBeenCalledOnce();
+      const callCfg = runWithModelFallbackMock.mock.calls[0][0].cfg;
+      const model = callCfg?.agents?.defaults?.model as
+        | { primary?: string; fallbacks?: string[] }
+        | undefined;
+      expect(model?.primary).toBe("anthropic/claude-sonnet-4-5");
+      expect(model?.fallbacks).toEqual(defaultFallbacks);
+    });
+
+    it("preserves defaults when agent overrides primary in object form", async () => {
+      resolveAgentConfigMock.mockReturnValue({
+        model: { primary: "anthropic/claude-sonnet-4-5" },
+      });
+
+      const result = await runCronIsolatedAgentTurn(
+        makeParams({
+          cfg: {
+            agents: {
+              defaults: {
+                model: { primary: "openai-codex/gpt-5.3-codex", fallbacks: defaultFallbacks },
+              },
+            },
+          },
+          agentId: "scout",
+        }),
+      );
+
+      expect(result.status).toBe("ok");
+      expect(runWithModelFallbackMock).toHaveBeenCalledOnce();
+      const callCfg = runWithModelFallbackMock.mock.calls[0][0].cfg;
+      const model = callCfg?.agents?.defaults?.model as
+        | { primary?: string; fallbacks?: string[] }
+        | undefined;
+      expect(model?.primary).toBe("anthropic/claude-sonnet-4-5");
+      expect(model?.fallbacks).toEqual(defaultFallbacks);
+    });
+  });
 });