@vellumai/assistant 0.7.1 → 0.7.2

package/src/config/feature-flag-registry.json

@@ -9,14 +9,6 @@
       "description": "Automatically trigger conversation analysis on the same cadence as memory extraction (batch threshold, idle debounce, end-of-conversation). The analysis agent has full tool access and writes back to memory and skills without user approval.",
       "defaultEnabled": false
     },
-    {
-      "id": "browser",
-      "scope": "assistant",
-      "key": "browser",
-      "label": "Browser",
-      "description": "Enable browser skill prerequisites section in the system prompt",
-      "defaultEnabled": true
-    },
     {
       "id": "user-hosted-enabled",
       "scope": "client",
@@ -41,29 +33,13 @@
       "description": "Enable the entire email integration: email CLI commands, email channel, domain registration, sequences, email readiness probes, invite adapters, and the email-setup skill",
       "defaultEnabled": false
     },
-    {
-      "id": "app-builder-multifile",
-      "scope": "assistant",
-      "key": "app-builder-multifile",
-      "label": "App Builder Multi-file",
-      "description": "Enable multi-file TSX app creation with esbuild compilation instead of single-HTML apps",
-      "defaultEnabled": true
-    },
-    {
-      "id": "mobile-pairing",
-      "scope": "client",
-      "key": "mobile-pairing",
-      "label": "Mobile Pairing",
-      "description": "Show the Mobile (iOS) pairing card in Settings > Account",
-      "defaultEnabled": false
-    },
     {
       "id": "settings-developer-nav",
-      "scope": "assistant",
+      "scope": "client",
       "key": "settings-developer-nav",
       "label": "Settings Developer Nav",
       "description": "Control Developer nav visibility in macOS settings",
-      "defaultEnabled": true
+      "defaultEnabled": false
     },
     {
       "id": "developer-menu-items",
@@ -105,54 +81,6 @@
       "description": "Surface credential grant and audit inspection endpoints for reviewing active grants and access logs",
       "defaultEnabled": false
     },
-    {
-      "id": "ces-managed-sidecar",
-      "scope": "assistant",
-      "key": "ces-managed-sidecar",
-      "label": "CES Managed Sidecar Transport",
-      "description": "Use managed sidecar transport for CES communication when running in a containerized environment",
-      "defaultEnabled": true
-    },
-    {
-      "id": "ces-credential-backend",
-      "scope": "assistant",
-      "key": "ces-credential-backend",
-      "label": "CES Credential Backend",
-      "description": "Route credential reads and writes through the CES process instead of accessing the encrypted store directly",
-      "defaultEnabled": true
-    },
-    {
-      "id": "settings-billing",
-      "scope": "client",
-      "key": "settings-billing",
-      "label": "Billing Settings Tab",
-      "description": "Show the Billing tab in Settings when signed in, displaying credits balance and top-up",
-      "defaultEnabled": true
-    },
-    {
-      "id": "referral-codes",
-      "scope": "client",
-      "key": "referral-codes",
-      "label": "Referral Codes",
-      "description": "Surface the Earn Credits referral entry points (sidebar drawer row and Billing tab button) that open the referral modal",
-      "defaultEnabled": true
-    },
-    {
-      "id": "managed-sign-in",
-      "scope": "client",
-      "key": "managed-sign-in",
-      "label": "Managed Sign In",
-      "description": "Enable managed (organization-hosted) sign-in flow in the onboarding experience",
-      "defaultEnabled": true
-    },
-    {
-      "id": "conversation-starters",
-      "scope": "assistant",
-      "key": "conversation-starters",
-      "label": "Recommended Starts",
-      "description": "Show a curated row of recommended starting actions on the empty conversation page, ordered by relevance as confident first-click options",
-      "defaultEnabled": true
-    },
     {
       "id": "deploy-to-vercel",
       "scope": "assistant",
@@ -193,37 +121,13 @@
       "description": "Auto-expand completed tool call step groups instead of showing them collapsed",
       "defaultEnabled": false
     },
-    {
-      "id": "show-thinking-blocks",
-      "scope": "client",
-      "key": "show-thinking-blocks",
-      "label": "Show Thinking Blocks",
-      "description": "Display the assistant's thinking/reasoning inline in chat messages as collapsible blocks",
-      "defaultEnabled": true
-    },
-    {
-      "id": "inline-skill-commands",
-      "scope": "assistant",
-      "key": "inline-skill-commands",
-      "label": "Inline Skill Command Expansion",
-      "description": "Enable secure inline skill command expansion via !`command` syntax, with version-pinned approval and sandboxed execution at skill load time",
-      "defaultEnabled": true
-    },
-    {
-      "id": "channel-voice-transcription",
-      "scope": "assistant",
-      "key": "channel-voice-transcription",
-      "label": "Channel Voice Transcription",
-      "description": "Auto-transcribe voice/audio messages received from channels (Telegram, WhatsApp) before processing",
-      "defaultEnabled": true
-    },
     {
       "id": "sounds",
       "scope": "assistant",
       "key": "sounds",
       "label": "Sounds",
       "description": "Enable the Sounds tab in Settings and all app sound playback (event sounds, random ambient sounds)",
-      "defaultEnabled": true
+      "defaultEnabled": false
     },
     {
       "id": "message-tts",
@@ -239,7 +143,7 @@
       "key": "backward-releases",
       "label": "Backward Releases",
       "description": "Show older versions in the version picker, allowing rollback to previous releases",
-      "defaultEnabled": true
+      "defaultEnabled": false
     },
     {
       "id": "voice-mode",
@@ -281,14 +185,6 @@
       "description": "Enable assistant sandboxing via Apple Containers on macOS 26+, providing a lightweight native sandbox without third-party dependencies",
       "defaultEnabled": false
     },
-    {
-      "id": "tool-result-truncation",
-      "scope": "assistant",
-      "key": "tool-result-truncation",
-      "label": "Post-Turn Tool Result Truncation",
-      "description": "Truncate large tool results after each assistant turn, persisting full content to disk for on-demand re-reads",
-      "defaultEnabled": true
-    },
     {
       "id": "managed-gemini-embeddings-enabled",
       "scope": "assistant",
@@ -305,14 +201,6 @@
       "description": "Show the 'Fork from here' option in message overflow menus",
       "defaultEnabled": false
     },
-    {
-      "id": "onboarding-pre-chat",
-      "scope": "client",
-      "key": "onboarding-pre-chat",
-      "label": "Pre-Chat Onboarding Flow",
-      "description": "Gates the 3-screen pre-chat onboarding flow (tools, tasks/tone, name exchange) shown before the first conversation",
-      "defaultEnabled": true
-    },
     {
       "id": "home-tab",
       "scope": "client",
@@ -321,14 +209,6 @@
       "description": "Replace the knowledge graph top-level tab with a new Home page showing relationship progression, facts, and capability tiers",
       "defaultEnabled": false
     },
-    {
-      "id": "channel-avatar-sync",
-      "scope": "assistant",
-      "key": "channel-avatar-sync",
-      "label": "Channel Avatar Sync",
-      "description": "Automatically sync the assistant's avatar to connected channels (Slack) when the avatar changes or a new channel is connected",
-      "defaultEnabled": true
-    },
     {
       "id": "meet",
       "scope": "assistant",
@@ -345,20 +225,12 @@
       "description": "Show a live HUD in the top-right of the conversation with scroll geometry, velocity, update rate, and anchor-preserver activity. Developer diagnostic for investigating scroll jank.",
       "defaultEnabled": false
     },
-    {
-      "id": "message-height-cache",
-      "scope": "client",
-      "key": "message-height-cache",
-      "label": "Message Height Cache",
-      "description": "Swap the transcript's LazyVStack for a plain VStack so scrollContentHeight is the true sum of row heights (no LazyVStack estimator drift). Row frames are not pinned — the earlier frame-pinning approach was removed because it caused overlap when rows grew past their first measurement (streaming, expanding thinking blocks). Tradeoff: eager layout — every row measures up-front, which can stall for many seconds to minutes on very long conversations.",
-      "defaultEnabled": true
-    },
     {
       "id": "coding-agents-panel",
       "scope": "client",
       "key": "coding-agents-panel",
       "label": "Coding Agents Panel",
-      "description": "Gate native macOS/iOS Coding Agents panel entry points and inline ACP session deep links.",
+      "description": "Gate native macOS Coding Agents panel entry points and inline ACP session deep links.",
       "defaultEnabled": false
     },
     {
@@ -384,6 +256,22 @@
       "label": "Account Deletion",
       "description": "Surfaces the user-initiated account deletion flow in client settings.",
       "defaultEnabled": false
+    },
+    {
+      "id": "app-control",
+      "scope": "assistant",
+      "key": "app-control",
+      "label": "App Control",
+      "description": "Enable the app-control skill (per-app screenshot + raw input bypassing AX tree)",
+      "defaultEnabled": false
+    },
+    {
+      "id": "analyze-conversation",
+      "scope": "assistant",
+      "key": "analyze-conversation",
+      "label": "Analyze Conversation",
+      "description": "Show the 'Analyze' / 'Analyze conversation' option in conversation context menus and the conversation title actions dropdown.",
+      "defaultEnabled": false
     }
   ]
 }

package/src/config/loader.ts

@@ -49,6 +49,34 @@ function cloneDefaultConfig(): AssistantConfig {
   return applyNestedDefaults({});
 }
 
+/**
+ * Returns deployment-context-aware config defaults that override schema
+ * defaults for platform-managed assistants. Only applied when initializing
+ * a fresh config (config.json does not yet exist).
+ *
+ * IS_PLATFORM is set by the Vellum platform launcher for all hosted
+ * assistant deployments. Local, Docker, and bare-metal assistants are
+ * unaffected.
+ */
+function getDeploymentContextDefaults(): Record<string, unknown> {
+  if (process.env.IS_PLATFORM !== "true" && process.env.IS_PLATFORM !== "1") {
+    return {};
+  }
+  const managed = { mode: "managed" as const };
+  return {
+    services: {
+      inference: managed,
+      "image-generation": managed,
+      "web-search": managed,
+      "google-oauth": managed,
+      "outlook-oauth": managed,
+      "linear-oauth": managed,
+      "github-oauth": managed,
+      "notion-oauth": managed,
+    },
+  };
+}
+
 /**
  * Build a filesystem-safe ISO-8601 timestamp for use in quarantine filenames.
  * Replaces `:` (invalid on Windows, confusing on macOS Finder) with `-` so the
@@ -237,6 +265,11 @@ const DEPRECATED_FIELDS: Record<string, string> = {
   "permissions.autoApproveUpTo":
     "permissions.autoApproveUpTo has been removed. The gateway now controls all " +
     "auto-approve thresholds. The field will be removed from your config file.",
+  "memory.jobs.batchSize":
+    "memory.jobs.batchSize has been removed. The memory job worker now uses " +
+    "per-lane concurrency caps (slowLlmConcurrency, fastConcurrency, " +
+    "embedConcurrency) instead of a single batch size. " +
+    "The field will be removed from your config file.",
 };
 
 /**
@@ -289,42 +322,6 @@ function deleteNestedKeyByDotPath(
   deleteNestedKey(obj, keys);
 }
 
-/**
- * Deep-merge missing keys from `defaults` into `target`.
- * Only adds keys that do not already exist in `target`; never overwrites.
- * Returns true if any key was added.
- */
-export function deepMergeMissing(
-  target: Record<string, unknown>,
-  defaults: Record<string, unknown>,
-): boolean {
-  let changed = false;
-  for (const key of Object.keys(defaults)) {
-    if (!(key in target)) {
-      target[key] = defaults[key];
-      changed = true;
-    } else if (
-      defaults[key] != null &&
-      typeof defaults[key] === "object" &&
-      !Array.isArray(defaults[key]) &&
-      target[key] != null &&
-      typeof target[key] === "object" &&
-      !Array.isArray(target[key])
-    ) {
-      // Recurse into nested objects
-      if (
-        deepMergeMissing(
-          target[key] as Record<string, unknown>,
-          defaults[key] as Record<string, unknown>,
-        )
-      ) {
-        changed = true;
-      }
-    }
-  }
-  return changed;
-}
-
 /**
  * Recursively strip `null` leaves from a plain-object value, returning a
  * deep clone with all `null`-valued keys removed at every nesting level.
@@ -409,47 +406,14 @@ export function deepMergeOverwrite(
   }
 }
 
-/**
- * Read the existing config.json from disk, merge any missing schema-default
- * keys, and rewrite only when there is an effective change.
- */
-function backfillConfigDefaults(
-  configPath: string,
-  fullDefaults: Record<string, unknown>,
-): void {
-  let raw: unknown;
-  try {
-    raw = JSON.parse(readFileSync(configPath, "utf-8"));
-  } catch {
-    return; // Unreadable file — skip backfill
-  }
-
-  // Only backfill into plain objects (not arrays, strings, etc.)
-  if (raw == null || typeof raw !== "object" || Array.isArray(raw)) {
-    return;
-  }
-
-  deepMergeMissing(raw as Record<string, unknown>, fullDefaults);
-  // Compare serialized JSON to decide whether a write is needed.
-  // deepMergeMissing can report false-positive mutations (e.g. setting a key
-  // to a value identical to what was already there), so comparing the final
-  // JSON avoids a hot-loop where writing triggers the config-watcher which
-  // reloads and backfills again endlessly.
-  const newJson = JSON.stringify(raw, null, 2) + "\n";
-  const existingJson = readFileSync(configPath, "utf-8");
-  if (newJson !== existingJson) {
-    writeFileSync(configPath, newJson);
-    log.info("Backfilled missing config defaults in %s", configPath);
-  }
-}
-
 /**
  * Merge default workspace config from the file referenced by
  * VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH into the workspace config on disk.
  *
- * Called once at daemon startup (before the first loadConfig()) so the
- * defaults are persisted to the workspace config file alongside any
- * schema-level defaults that loadConfig() backfills.
+ * Called once at daemon startup (before the first loadConfig()) so platform
+ * overrides are persisted to disk before the daemon's first config read.
+ * Schema defaults are no longer materialized into the file on load — the
+ * in-memory `loadConfig()` cache applies them at access time instead.
  */
 export function mergeDefaultWorkspaceConfig(): void {
   const defaultConfigPath = process.env.VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH;
@@ -587,26 +551,45 @@ export function loadConfig(): AssistantConfig {
       }
     }
 
-    // If the config file didn't exist, write the full defaults to disk so
-    // users can discover and edit all available options.
-    // If it existed, backfill any missing schema keys from defaults without
-    // overwriting existing user values.
-    try {
-      const dir = dirname(configPath);
-      if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-      }
-      // Strip dataDir (runtime-derived) from the persisted config
-      const { dataDir: _, ...persistable } = config;
-
-      if (!configFileExisted) {
+    // First-launch seed only: when config.json does not exist, write the full
+    // schema defaults to disk so users can discover and edit all available
+    // options. When the file already exists, leave it alone — disk represents
+    // user intent, while the in-memory `cached: AssistantConfig` (above) has
+    // all schema defaults applied via `applyNestedDefaults`/`validateWithSchema`,
+    // so consumers calling `getConfig().memory.v2.bm25_b` continue to receive
+    // the schema default whenever the field is absent on disk.
+    //
+    // The previous behavior — eagerly merging missing keys back into the file
+    // on every load — silently baked stale defaults into existing users'
+    // config.json. Once a default landed in the file, future schema-default
+    // changes were inert because the merge only filled absent keys and never
+    // reconciled existing values. Contract: disk = user intent, in-memory
+    // cache = effective values.
+    if (!configFileExisted) {
+      try {
+        const dir = dirname(configPath);
+        if (!existsSync(dir)) {
+          mkdirSync(dir, { recursive: true });
+        }
+        // Strip dataDir (runtime-derived) from the persisted config
+        const { dataDir: _, ...persistable } = config;
+
+        // Layer deployment context defaults on top of schema defaults.
+        // These are overrides the daemon derives from its environment (e.g.
+        // IS_PLATFORM → all service modes = "managed"). Schema defaults
+        // remain the fallback for non-platform deployments.
+        const contextDefaults = getDeploymentContextDefaults();
+        if (Object.keys(contextDefaults).length > 0) {
+          deepMergeOverwrite(
+            persistable as Record<string, unknown>,
+            contextDefaults,
+          );
+        }
         writeFileSync(configPath, JSON.stringify(persistable, null, 2) + "\n");
         log.info("Wrote default config to %s", configPath);
-      } else {
-        backfillConfigDefaults(configPath, persistable);
+      } catch (err) {
+        log.warn({ err }, "Failed to write default config file");
       }
-    } catch (err) {
-      log.warn({ err }, "Failed to write/backfill config file");
     }
 
     cached = config;
@@ -636,15 +619,6 @@ function isManagedGeminiFFEnabled(config: AssistantConfig): boolean {
   }
 }
 
-export function saveConfig(config: AssistantConfig): void {
-  ensureMigratedDataDir();
-  const configPath = getConfigPath();
-
-  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
-
-  cached = config;
-}
-
 export function getConfig(): AssistantConfig {
   return loadConfig();
 }

package/src/config/sanitize-for-transfer.ts

@@ -5,6 +5,7 @@
  * Fields removed or reset:
  * - `ingress.publicBaseUrl` → set to `""`
  * - `ingress.enabled` → deleted
+ * - `ingress.publicBaseUrlManagedBy` → deleted
  * - `daemon` → deleted entirely
  * - `skills.load.extraDirs` → set to `[]`
  * - `hostBrowser.cdpInspect.desktopAuto` → deleted **only when the source
@@ -41,6 +42,7 @@ export function sanitizeConfigForTransfer(configJson: string): string {
     const ingress = config.ingress as Record<string, unknown>;
     ingress.publicBaseUrl = "";
     delete ingress.enabled;
+    delete ingress.publicBaseUrlManagedBy;
   }
 
   // Strip daemon entirely

package/src/config/schemas/__tests__/memory-lifecycle.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from "bun:test";
+
+import { MemoryJobsConfigSchema } from "../memory-lifecycle.js";
+
+describe("MemoryJobsConfigSchema", () => {
+  test("parses an empty object to documented defaults", () => {
+    const parsed = MemoryJobsConfigSchema.parse({});
+    expect(parsed).toEqual({
+      workerConcurrency: 2,
+      stalledJobTimeoutMs: 30 * 60 * 1000,
+      slowLlmConcurrency: 1,
+      fastConcurrency: 2,
+      embedConcurrency: 2,
+    });
+  });
+
+  test("derives lane caps from workerConcurrency when only it is set", () => {
+    const parsed = MemoryJobsConfigSchema.parse({ workerConcurrency: 4 });
+    expect(parsed.workerConcurrency).toBe(4);
+    expect(parsed.slowLlmConcurrency).toBe(2);
+    expect(parsed.fastConcurrency).toBe(4);
+    expect(parsed.embedConcurrency).toBe(4);
+  });
+
+  test("floors and clamps slowLlmConcurrency to at least 1 when deriving", () => {
+    const parsed = MemoryJobsConfigSchema.parse({ workerConcurrency: 1 });
+    expect(parsed.slowLlmConcurrency).toBe(1);
+    expect(parsed.fastConcurrency).toBe(1);
+    expect(parsed.embedConcurrency).toBe(1);
+  });
+
+  test("explicit lane cap overrides the derivation", () => {
+    const parsed = MemoryJobsConfigSchema.parse({
+      workerConcurrency: 4,
+      slowLlmConcurrency: 1,
+    });
+    expect(parsed.slowLlmConcurrency).toBe(1);
+    expect(parsed.fastConcurrency).toBe(4);
+    expect(parsed.embedConcurrency).toBe(4);
+  });
+
+  test("explicit lane caps without workerConcurrency keep workerConcurrency default", () => {
+    const parsed = MemoryJobsConfigSchema.parse({
+      slowLlmConcurrency: 3,
+      fastConcurrency: 5,
+      embedConcurrency: 7,
+    });
+    expect(parsed.workerConcurrency).toBe(2);
+    expect(parsed.slowLlmConcurrency).toBe(3);
+    expect(parsed.fastConcurrency).toBe(5);
+    expect(parsed.embedConcurrency).toBe(7);
+  });
+
+  test.each([
+    "slowLlmConcurrency",
+    "fastConcurrency",
+    "embedConcurrency",
+    "workerConcurrency",
+  ] as const)("rejects %s = 0", (field) => {
+    expect(() => MemoryJobsConfigSchema.parse({ [field]: 0 })).toThrow();
+  });
+
+  test.each([
+    "slowLlmConcurrency",
+    "fastConcurrency",
+    "embedConcurrency",
+    "workerConcurrency",
+  ] as const)("rejects negative %s", (field) => {
+    expect(() => MemoryJobsConfigSchema.parse({ [field]: -1 })).toThrow();
+  });
+
+  test.each([
+    "slowLlmConcurrency",
+    "fastConcurrency",
+    "embedConcurrency",
+    "workerConcurrency",
+  ] as const)("rejects non-integer %s", (field) => {
+    expect(() => MemoryJobsConfigSchema.parse({ [field]: 1.5 })).toThrow();
+  });
+});

package/src/config/schemas/__tests__/memory-v2.test.ts

@@ -16,10 +16,13 @@ describe("MemoryV2ConfigSchema", () => {
       k: 0.5,
       hops: 2,
       top_k: 20,
+      ann_candidate_limit: null,
       top_k_skills: 5,
       epsilon: 0.01,
-      dense_weight: 0.7,
-      sparse_weight: 0.3,
+      dense_weight: 0.85,
+      sparse_weight: 0.15,
+      bm25_k1: 1.2,
+      bm25_b: 0.4,
       consolidation_interval_hours: 4,
       max_page_chars: 5000,
       consolidation_prompt_path: null,
@@ -155,8 +158,8 @@ describe("MemoryConfigSchema integration with v2 block", () => {
     expect(parsed.v2.enabled).toBe(false);
     expect(parsed.v2.sweep_enabled).toBe(false);
     expect(parsed.v2.d).toBe(0.3);
-    expect(parsed.v2.dense_weight).toBe(0.7);
-    expect(parsed.v2.sparse_weight).toBe(0.3);
+    expect(parsed.v2.dense_weight).toBe(0.85);
+    expect(parsed.v2.sparse_weight).toBe(0.15);
     expect(parsed.v2.top_k_skills).toBe(5);
     expect(parsed.v2.consolidation_interval_hours).toBe(4);
     expect(parsed.v2.max_page_chars).toBe(5000);

package/src/config/schemas/calls.ts

@@ -232,12 +232,3 @@ export const CallsConfigSchema = z
   .describe(
     "Phone call configuration — controls telephony, voice, safety, and call behavior",
   );
-
-export type CallsConfig = z.infer<typeof CallsConfigSchema>;
-export type CallsDisclosureConfig = z.infer<typeof CallsDisclosureConfigSchema>;
-export type CallsSafetyConfig = z.infer<typeof CallsSafetyConfigSchema>;
-export type CallsVoiceConfig = z.infer<typeof CallsVoiceConfigSchema>;
-export type CallerIdentityConfig = z.infer<typeof CallerIdentityConfigSchema>;
-export type CallsVerificationConfig = z.infer<
-  typeof CallsVerificationConfigSchema
->;

package/src/config/schemas/heartbeat.ts

@@ -1,3 +1,4 @@
+import { Cron } from "croner";
 import { z } from "zod";
 
 export const HeartbeatConfigSchema = z
@@ -12,6 +13,20 @@ export const HeartbeatConfigSchema = z
       .positive("heartbeat.intervalMs must be a positive integer")
       .default(6 * 3_600_000)
       .describe("Time between heartbeat checks in milliseconds"),
+    cronExpression: z
+      .string()
+      .nullable()
+      .default(null)
+      .describe(
+        "Cron expression for heartbeat timing. When set, heartbeats fire at the specified clock times instead of using intervalMs.",
+      ),
+    timezone: z
+      .string()
+      .nullable()
+      .default(null)
+      .describe(
+        "Timezone for cron expression evaluation, e.g. 'America/New_York'. Ignored when cronExpression is null.",
+      ),
     activeHoursStart: z
       .number({ error: "heartbeat.activeHoursStart must be a number" })
       .int("heartbeat.activeHoursStart must be an integer")
@@ -80,6 +95,54 @@ export const HeartbeatConfigSchema = z
         message,
       });
     }
+
+    // Validate cronExpression and timezone when cronExpression is set.
+    // Separate the validations so timezone errors are attributed to the
+    // timezone path — if both paths point at cronExpression, the config
+    // loader's delete-and-retry would strip cronExpression but leave the
+    // invalid timezone, cascading to a full defaults reset.
+    if (config.cronExpression != null) {
+      try {
+        new Cron(config.cronExpression, { maxRuns: 0 });
+      } catch (err) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["cronExpression"],
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+      if (config.timezone != null) {
+        try {
+          new Cron(config.cronExpression, {
+            maxRuns: 0,
+            timezone: config.timezone,
+          });
+        } catch {
+          // The cron expression itself is valid (or already flagged above),
+          // so a failure here is from the timezone.
+          try {
+            Intl.DateTimeFormat(undefined, { timeZone: config.timezone });
+          } catch (tzErr) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              path: ["timezone"],
+              message: tzErr instanceof Error ? tzErr.message : String(tzErr),
+            });
+          }
+        }
+      }
+    } else if (config.timezone != null) {
+      // cronExpression is null but timezone is set — validate timezone independently
+      try {
+        Intl.DateTimeFormat(undefined, { timeZone: config.timezone });
+      } catch (err) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["timezone"],
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
   });
 
 export type HeartbeatConfig = z.infer<typeof HeartbeatConfigSchema>;