docs: clarify heartbeat empty file behavior (#1535) (thanks @JustYannicc)

Fixed issue where trigger words would disappear when typing or when adding new trigger words. The problem was that `swabbleTriggerWords` changes were triggering `VoiceWakeRuntime.refresh()` which sanitized the array by removing empty strings in real-time.

Solution: Introduced local `@State` buffer `triggerEntries` with stable UUID identifiers for each trigger word entry. User edits now only affect the local state buffer and are synced back to `AppState` on explicit actions (submit, remove, disappear). This prevents premature sanitization during editing.

The local state is loaded on view appear and when the view becomes active, ensuring it stays in sync with `AppState`.

CHANGELOG.md

@@ -2,24 +2,49 @@
 
 Docs: https://docs.clawd.bot
 
-## 2026.1.23
+## 2026.1.23 (Unreleased)
 
 ### Changes
+- Plugins: add optional llm-task JSON-only tool for workflows. (#1498) Thanks @vignesh07.
 - CLI: restart the gateway by default after `clawdbot update`; add `--no-restart` to skip it.
 - CLI: add live auth probes to `clawdbot models status` for per-profile verification.
+- Agents: add Bedrock auto-discovery defaults + config overrides. (#1553) Thanks @fal3.
+- Docs: add cron vs heartbeat decision guide (with Lobster workflow notes). (#1533) Thanks @JustYannicc.
+- Docs: clarify HEARTBEAT.md empty file skips heartbeats, missing file still runs. (#1535) Thanks @JustYannicc.
 - Markdown: add per-channel table conversion (bullets for Signal/WhatsApp, code blocks elsewhere). (#1495) Thanks @odysseus0.
+- Tlon: add Urbit channel plugin (DMs, group mentions, thread replies). (#1544) Thanks @wca4a.
 
 ### Fixes
-- macOS: sync voice wake trigger words on submit/blur in settings. (#1506) Thanks @shiv19.
+- Docker: update gateway command in docker-compose and Hetzner guide. (#1514)
+- Voice wake: auto-save wake words on blur/submit across iOS/Android and align limits with macOS.
+- UI: keep the Control UI sidebar visible while scrolling long pages. (#1515) Thanks @pookNast.
+- UI: cache Control UI markdown rendering + memoize chat text extraction to reduce Safari typing jank.
+- Tailscale: retry serve/funnel with sudo only for permission errors and keep original failure details. (#1551) Thanks @sweepies.
+- Agents: add CLI log hint to "agent failed before reply" messages. (#1550) Thanks @sweepies.
+- Discord: limit autoThread mention bypass to bot-owned threads; keep ack reactions mention-gated. (#1511) Thanks @pvoo.
+- Gateway: accept null optional fields in exec approval requests. (#1511) Thanks @pvoo.
 - TUI: forward unknown slash commands (for example, `/context`) to the Gateway.
 - TUI: include Gateway slash commands in autocomplete and `/help`.
 - CLI: skip usage lines in `clawdbot models status` when provider usage is unavailable.
 - CLI: suppress diagnostic session/run noise during auth probes.
+- CLI: hide auth probe timeout warnings from embedded runs.
+- CLI: render auth probe results as a table in `clawdbot models status`.
+- CLI: suppress probe-only embedded logs unless `--verbose` is set.
+- CLI: move auth probe errors below the table to reduce wrapping.
+- CLI: prevent ANSI color bleed when table cells wrap.
+- CLI: explain when auth profiles are excluded by auth.order in probe details.
+- CLI: drop the em dash when the banner tagline wraps to a second line.
+- CLI: inline auth probe errors in status rows to reduce wrapping.
+- Telegram: render markdown in media captions. (#1478)
+- Agents: honor enqueue overrides for embedded runs to avoid queue deadlocks in tests.
+- Daemon: use platform PATH delimiters when building minimal service paths.
+- Tests: skip embedded runner ordering assertion on Windows to avoid CI timeouts.
 - Linux: include env-configured user bin roots in systemd PATH and align PATH audits. (#1512) Thanks @robbyczgw-cla.
 - TUI: render Gateway slash-command replies as system output (for example, `/context`).
 - Media: preserve PNG alpha when possible; fall back to JPEG when still over size cap. (#1491) Thanks @robbyczgw-cla.
 - Agents: treat plugin-only tool allowlists as opt-ins; keep core tools enabled. (#1467)
 - Exec approvals: persist allowlist entry ids to keep macOS allowlist rows stable. (#1521) Thanks @ngutman.
+- MS Teams (plugin): remove `.default` suffix from Graph scopes to avoid double-appending. (#1507) Thanks @Evizero.
 
 ## 2026.1.22
 

apps/macos/Sources/Clawdbot/VoiceWakeSettings.swift

@@ -22,7 +22,6 @@ struct VoiceWakeSettings: View {
     @State private var micRefreshTask: Task<Void, Never>?
     @State private var availableLocales: [Locale] = []
     @State private var triggerEntries: [TriggerEntry] = []
-    @FocusState private var focusedTriggerEntryID: UUID?
     private let fieldLabelWidth: CGFloat = 140
     private let controlWidth: CGFloat = 240
     private let isPreview = ProcessInfo.processInfo.isPreview
@@ -143,11 +142,6 @@ struct VoiceWakeSettings: View {
             Task { await self.meter.stop() }
             self.syncTriggerEntriesToState()
         }
-        .onChange(of: self.state.swabbleTriggerWords) { _, _ in
-            guard !self.isPreview else { return }
-            guard self.focusedTriggerEntryID == nil else { return }
-            self.loadTriggerEntries()
-        }
     }
 
     private func loadTriggerEntries() {
@@ -183,7 +177,6 @@ struct VoiceWakeSettings: View {
                     HStack(spacing: 8) {
                         TextField("Wake word", text: $entry.value)
                             .textFieldStyle(.roundedBorder)
-                            .focused(self.$focusedTriggerEntryID, equals: entry.id)
                             .onSubmit {
                                 self.syncTriggerEntriesToState()
                             }
@@ -204,10 +197,6 @@ struct VoiceWakeSettings: View {
                     }
                 }
             }
-            .onChange(of: self.focusedTriggerEntryID) { oldValue, newValue in
-                guard oldValue != nil, oldValue != newValue else { return }
-                self.syncTriggerEntriesToState()
-            }
             .frame(maxWidth: .infinity, minHeight: 180, alignment: .topLeading)
             .background(Color(nsColor: .textBackgroundColor))
             .clipShape(RoundedRectangle(cornerRadius: 6))

docs/gateway/heartbeat.md

@@ -159,6 +159,10 @@ If a `HEARTBEAT.md` file exists in the workspace, the default prompt tells the
 agent to read it. Think of it as your “heartbeat checklist”: small, stable, and
 safe to include every 30 minutes.
 
+If `HEARTBEAT.md` exists but is effectively empty (only blank lines and markdown
+headers like `# Heading`), Clawdbot skips the heartbeat run to save API calls.
+If the file is missing, the heartbeat still runs and the model decides what to do.
+
 Keep it tiny (short checklist or reminders) to avoid prompt bloat.
 
 Example `HEARTBEAT.md`:

docs/reference/templates/HEARTBEAT.md

@@ -5,4 +5,5 @@ read_when:
 ---
 # HEARTBEAT.md
 
-Keep this file empty unless you want a tiny checklist. Keep it small.
+# Keep this file empty (or with only comments) to skip heartbeat API calls.
+# Add tasks below when you want the agent to check something periodically.

docs/start/clawd.md

@@ -182,6 +182,8 @@ By default, Clawdbot runs a heartbeat every 30 minutes with the prompt:
 `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`
 Set `agents.defaults.heartbeat.every: "0m"` to disable.
 
+- If `HEARTBEAT.md` exists but is effectively empty (only blank lines and markdown headers like `# Heading`), Clawdbot skips the heartbeat run to save API calls.
+- If the file is missing, the heartbeat still runs and the model decides what to do.
 - If the agent replies with `HEARTBEAT_OK` (optionally with short padding; see `agents.defaults.heartbeat.ackMaxChars`), Clawdbot suppresses outbound delivery for that heartbeat.
 - Heartbeats run full agent turns — shorter intervals burn more tokens.
 

docs/start/faq.md

@@ -971,6 +971,10 @@ Heartbeats run every **30m** by default. Tune or disable them:
 }
 ```
 
+If `HEARTBEAT.md` exists but is effectively empty (only blank lines and markdown
+headers like `# Heading`), Clawdbot skips the heartbeat run to save API calls.
+If the file is missing, the heartbeat still runs and the model decides what to do.
+
 Per-agent overrides use `agents.list[].heartbeat`. Docs: [Heartbeat](/gateway/heartbeat).
 
 ### Do I need to add a “bot account” to a WhatsApp group?

pnpm-lock.yaml

@@ -376,6 +376,8 @@ importers:
         specifier: ^4.3.5
         version: 4.3.5
 
+  extensions/open-prose: {}
+
   extensions/signal: {}
 
   extensions/slack: {}

src/auto-reply/heartbeat.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, it } from "vitest";
 
-import { DEFAULT_HEARTBEAT_ACK_MAX_CHARS, stripHeartbeatToken } from "./heartbeat.js";
+import {
+  DEFAULT_HEARTBEAT_ACK_MAX_CHARS,
+  isHeartbeatContentEffectivelyEmpty,
+  stripHeartbeatToken,
+} from "./heartbeat.js";
 import { HEARTBEAT_TOKEN } from "./tokens.js";
 
 describe("stripHeartbeatToken", () => {
@@ -105,3 +109,76 @@ describe("stripHeartbeatToken", () => {
     });
   });
 });
+
+describe("isHeartbeatContentEffectivelyEmpty", () => {
+  it("returns false for undefined/null (missing file should not skip)", () => {
+    expect(isHeartbeatContentEffectivelyEmpty(undefined)).toBe(false);
+    expect(isHeartbeatContentEffectivelyEmpty(null)).toBe(false);
+  });
+
+  it("returns true for empty string", () => {
+    expect(isHeartbeatContentEffectivelyEmpty("")).toBe(true);
+  });
+
+  it("returns true for whitespace only", () => {
+    expect(isHeartbeatContentEffectivelyEmpty("   ")).toBe(true);
+    expect(isHeartbeatContentEffectivelyEmpty("\n\n\n")).toBe(true);
+    expect(isHeartbeatContentEffectivelyEmpty("  \n  \n  ")).toBe(true);
+    expect(isHeartbeatContentEffectivelyEmpty("\t\t")).toBe(true);
+  });
+
+  it("returns true for header-only content", () => {
+    expect(isHeartbeatContentEffectivelyEmpty("# HEARTBEAT.md")).toBe(true);
+    expect(isHeartbeatContentEffectivelyEmpty("# HEARTBEAT.md\n")).toBe(true);
+    expect(isHeartbeatContentEffectivelyEmpty("# HEARTBEAT.md\n\n")).toBe(true);
+  });
+
+  it("returns true for comments only", () => {
+    expect(isHeartbeatContentEffectivelyEmpty("# Header\n# Another comment")).toBe(true);
+    expect(isHeartbeatContentEffectivelyEmpty("## Subheader\n### Another")).toBe(true);
+  });
+
+  it("returns true for default template content (header + comment)", () => {
+    const defaultTemplate = `# HEARTBEAT.md
+
+Keep this file empty unless you want a tiny checklist. Keep it small.
+`;
+    // Note: The template has actual text content, so it's NOT effectively empty
+    expect(isHeartbeatContentEffectivelyEmpty(defaultTemplate)).toBe(false);
+  });
+
+  it("returns true for header with only empty lines", () => {
+    expect(isHeartbeatContentEffectivelyEmpty("# HEARTBEAT.md\n\n\n")).toBe(true);
+  });
+
+  it("returns false when actionable content exists", () => {
+    expect(isHeartbeatContentEffectivelyEmpty("- Check email")).toBe(false);
+    expect(isHeartbeatContentEffectivelyEmpty("# HEARTBEAT.md\n- Task 1")).toBe(false);
+    expect(isHeartbeatContentEffectivelyEmpty("Remind me to call mom")).toBe(false);
+  });
+
+  it("returns false for content with tasks after header", () => {
+    const content = `# HEARTBEAT.md
+
+- Task 1
+- Task 2
+`;
+    expect(isHeartbeatContentEffectivelyEmpty(content)).toBe(false);
+  });
+
+  it("returns false for mixed content with non-comment text", () => {
+    const content = `# HEARTBEAT.md
+## Tasks
+Check the server logs
+`;
+    expect(isHeartbeatContentEffectivelyEmpty(content)).toBe(false);
+  });
+
+  it("treats markdown headers as comments (effectively empty)", () => {
+    const content = `# HEARTBEAT.md
+## Section 1
+### Subsection
+`;
+    expect(isHeartbeatContentEffectivelyEmpty(content)).toBe(true);
+  });
+});

src/auto-reply/heartbeat.ts

@@ -7,6 +7,38 @@ export const HEARTBEAT_PROMPT =
 export const DEFAULT_HEARTBEAT_EVERY = "30m";
 export const DEFAULT_HEARTBEAT_ACK_MAX_CHARS = 300;
 
+/**
+ * Check if HEARTBEAT.md content is "effectively empty" - meaning it has no actionable tasks.
+ * This allows skipping heartbeat API calls when no tasks are configured.
+ *
+ * A file is considered effectively empty if it contains only:
+ * - Whitespace
+ * - Comment lines (lines starting with #)
+ * - Empty lines
+ *
+ * Note: A missing file returns false (not effectively empty) so the LLM can still
+ * decide what to do. This function is only for when the file exists but has no content.
+ */
+export function isHeartbeatContentEffectivelyEmpty(content: string | undefined | null): boolean {
+  if (content === undefined || content === null) return false;
+  if (typeof content !== "string") return false;
+
+  const lines = content.split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    // Skip empty lines
+    if (!trimmed) continue;
+    // Skip markdown header lines (# followed by space or EOL, ## etc)
+    // This intentionally does NOT skip lines like "#TODO" or "#hashtag" which might be content
+    // (Those aren't valid markdown headers - ATX headers require space after #)
+    if (/^#+(\s|$)/.test(trimmed)) continue;
+    // Found a non-empty, non-comment line - there's actionable content
+    return false;
+  }
+  // All lines were either empty or comments
+  return true;
+}
+
 export function resolveHeartbeatPrompt(raw?: string): string {
   const trimmed = typeof raw === "string" ? raw.trim() : "";
   return trimmed || HEARTBEAT_PROMPT;

src/config/sessions/store.ts

@@ -267,10 +267,9 @@ async function withSessionStoreLock<T>(
   fn: () => Promise<T>,
   opts: SessionStoreLockOptions = {},
 ): Promise<T> {
-  const isFastTest = process.env.CLAWDBOT_TEST_FAST === "1";
-  const timeoutMs = opts.timeoutMs ?? (isFastTest ? 30_000 : 10_000);
+  const timeoutMs = opts.timeoutMs ?? 10_000;
   const pollIntervalMs = opts.pollIntervalMs ?? 25;
-  const staleMs = opts.staleMs ?? (isFastTest ? 5_000 : 30_000);
+  const staleMs = opts.staleMs ?? 30_000;
   const lockPath = `${storePath}.lock`;
   const startedAt = Date.now();
 

src/discord/monitor.test.ts

@@ -377,12 +377,63 @@ describe("discord mention gating", () => {
       resolveDiscordShouldRequireMention({
         isGuildMessage: true,
         isThread: true,
+        botId: "bot123",
+        threadOwnerId: "bot123",
         channelConfig,
         guildInfo,
       }),
     ).toBe(false);
   });
 
+  it("requires mention inside user-created threads with autoThread enabled", () => {
+    const guildInfo: DiscordGuildEntryResolved = {
+      requireMention: true,
+      channels: {
+        general: { allow: true, autoThread: true },
+      },
+    };
+    const channelConfig = resolveDiscordChannelConfig({
+      guildInfo,
+      channelId: "1",
+      channelName: "General",
+      channelSlug: "general",
+    });
+    expect(
+      resolveDiscordShouldRequireMention({
+        isGuildMessage: true,
+        isThread: true,
+        botId: "bot123",
+        threadOwnerId: "user456",
+        channelConfig,
+        guildInfo,
+      }),
+    ).toBe(true);
+  });
+
+  it("requires mention when thread owner is unknown", () => {
+    const guildInfo: DiscordGuildEntryResolved = {
+      requireMention: true,
+      channels: {
+        general: { allow: true, autoThread: true },
+      },
+    };
+    const channelConfig = resolveDiscordChannelConfig({
+      guildInfo,
+      channelId: "1",
+      channelName: "General",
+      channelSlug: "general",
+    });
+    expect(
+      resolveDiscordShouldRequireMention({
+        isGuildMessage: true,
+        isThread: true,
+        botId: "bot123",
+        channelConfig,
+        guildInfo,
+      }),
+    ).toBe(true);
+  });
+
   it("inherits parent channel mention rules for threads", () => {
     const guildInfo: DiscordGuildEntryResolved = {
       requireMention: true,

src/discord/monitor/allow-list.ts

@@ -282,14 +282,33 @@ export function resolveDiscordChannelConfigWithFallback(params: {
 export function resolveDiscordShouldRequireMention(params: {
   isGuildMessage: boolean;
   isThread: boolean;
+  botId?: string | null;
+  threadOwnerId?: string | null;
   channelConfig?: DiscordChannelConfigResolved | null;
   guildInfo?: DiscordGuildEntryResolved | null;
+  /** Pass pre-computed value to avoid redundant checks. */
+  isAutoThreadOwnedByBot?: boolean;
 }): boolean {
   if (!params.isGuildMessage) return false;
-  if (params.isThread && params.channelConfig?.autoThread) return false;
+  // Only skip mention requirement in threads created by the bot (when autoThread is enabled).
+  const isBotThread = params.isAutoThreadOwnedByBot ?? isDiscordAutoThreadOwnedByBot(params);
+  if (isBotThread) return false;
   return params.channelConfig?.requireMention ?? params.guildInfo?.requireMention ?? true;
 }
 
+export function isDiscordAutoThreadOwnedByBot(params: {
+  isThread: boolean;
+  channelConfig?: DiscordChannelConfigResolved | null;
+  botId?: string | null;
+  threadOwnerId?: string | null;
+}): boolean {
+  if (!params.isThread) return false;
+  if (!params.channelConfig?.autoThread) return false;
+  const botId = params.botId?.trim();
+  const threadOwnerId = params.threadOwnerId?.trim();
+  return Boolean(botId && threadOwnerId && botId === threadOwnerId);
+}
+
 export function isDiscordGroupAllowedByPolicy(params: {
   groupPolicy: "open" | "disabled" | "allowlist";
   guildAllowlisted: boolean;

src/discord/monitor/message-handler.preflight.ts

@@ -328,9 +328,12 @@ export async function preflightDiscordMessage(
         } satisfies HistoryEntry)
       : undefined;
 
+  const threadOwnerId = threadChannel ? (threadChannel.ownerId ?? channelInfo?.ownerId) : undefined;
   const shouldRequireMention = resolveDiscordShouldRequireMention({
     isGuildMessage,
     isThread: Boolean(threadChannel),
+    botId,
+    threadOwnerId,
     channelConfig,
     guildInfo,
   });

src/discord/monitor/message-handler.process.test.ts

@@ -0,0 +1,123 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const reactMessageDiscord = vi.fn(async () => {});
+const removeReactionDiscord = vi.fn(async () => {});
+
+vi.mock("../send.js", () => ({
+  reactMessageDiscord: (...args: unknown[]) => reactMessageDiscord(...args),
+  removeReactionDiscord: (...args: unknown[]) => removeReactionDiscord(...args),
+}));
+
+vi.mock("../../auto-reply/reply/dispatch-from-config.js", () => ({
+  dispatchReplyFromConfig: vi.fn(async () => ({
+    queuedFinal: false,
+    counts: { final: 0, tool: 0, block: 0 },
+  })),
+}));
+
+vi.mock("../../auto-reply/reply/reply-dispatcher.js", () => ({
+  createReplyDispatcherWithTyping: vi.fn(() => ({
+    dispatcher: {},
+    replyOptions: {},
+    markDispatchIdle: vi.fn(),
+  })),
+}));
+
+import { processDiscordMessage } from "./message-handler.process.js";
+
+async function createBaseContext(overrides: Record<string, unknown> = {}) {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-discord-"));
+  const storePath = path.join(dir, "sessions.json");
+  return {
+    cfg: { messages: { ackReaction: "👀" }, session: { store: storePath } },
+    discordConfig: {},
+    accountId: "default",
+    token: "token",
+    runtime: { log: () => {}, error: () => {} },
+    guildHistories: new Map(),
+    historyLimit: 0,
+    mediaMaxBytes: 1024,
+    textLimit: 4000,
+    replyToMode: "off",
+    ackReactionScope: "group-mentions",
+    groupPolicy: "open",
+    data: { guild: { id: "g1", name: "Guild" } },
+    client: { rest: {} },
+    message: {
+      id: "m1",
+      channelId: "c1",
+      timestamp: new Date().toISOString(),
+      attachments: [],
+    },
+    author: {
+      id: "U1",
+      username: "alice",
+      discriminator: "0",
+      globalName: "Alice",
+    },
+    channelInfo: { name: "general" },
+    channelName: "general",
+    isGuildMessage: true,
+    isDirectMessage: false,
+    isGroupDm: false,
+    commandAuthorized: true,
+    baseText: "hi",
+    messageText: "hi",
+    wasMentioned: false,
+    shouldRequireMention: true,
+    canDetectMention: true,
+    effectiveWasMentioned: true,
+    shouldBypassMention: false,
+    threadChannel: null,
+    threadParentId: undefined,
+    threadParentName: undefined,
+    threadParentType: undefined,
+    threadName: undefined,
+    displayChannelSlug: "general",
+    guildInfo: null,
+    guildSlug: "guild",
+    channelConfig: null,
+    baseSessionKey: "agent:main:discord:guild:g1",
+    route: {
+      agentId: "main",
+      channel: "discord",
+      accountId: "default",
+      sessionKey: "agent:main:discord:guild:g1",
+      mainSessionKey: "agent:main:main",
+    },
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  reactMessageDiscord.mockClear();
+  removeReactionDiscord.mockClear();
+});
+
+describe("processDiscordMessage ack reactions", () => {
+  it("skips ack reactions for group-mentions when mentions are not required", async () => {
+    const ctx = await createBaseContext({
+      shouldRequireMention: false,
+      effectiveWasMentioned: false,
+    });
+
+    await processDiscordMessage(ctx as any);
+
+    expect(reactMessageDiscord).not.toHaveBeenCalled();
+  });
+
+  it("sends ack reactions for mention-gated guild messages when mentioned", async () => {
+    const ctx = await createBaseContext({
+      shouldRequireMention: true,
+      effectiveWasMentioned: true,
+    });
+
+    await processDiscordMessage(ctx as any);
+
+    expect(reactMessageDiscord).toHaveBeenCalledWith("c1", "m1", "👀", { rest: {} });
+  });
+});

src/discord/monitor/message-utils.ts

@@ -16,6 +16,7 @@ export type DiscordChannelInfo = {
   name?: string;
   topic?: string;
   parentId?: string;
+  ownerId?: string;
 };
 
 type DiscordSnapshotAuthor = {
@@ -69,11 +70,13 @@ export async function resolveDiscordChannelInfo(
     const name = "name" in channel ? (channel.name ?? undefined) : undefined;
     const topic = "topic" in channel ? (channel.topic ?? undefined) : undefined;
     const parentId = "parentId" in channel ? (channel.parentId ?? undefined) : undefined;
+    const ownerId = "ownerId" in channel ? (channel.ownerId ?? undefined) : undefined;
     const payload: DiscordChannelInfo = {
       type: channel.type,
       name,
       topic,
       parentId,
+      ownerId,
     };
     DISCORD_CHANNEL_INFO_CACHE.set(channelId, {
       value: payload,

src/discord/monitor/threading.ts

@@ -14,6 +14,7 @@ export type DiscordThreadChannel = {
   name?: string | null;
   parentId?: string | null;
   parent?: { id?: string; name?: string };
+  ownerId?: string | null;
 };
 
 export type DiscordThreadStarter = {
@@ -63,6 +64,7 @@ export function resolveDiscordThreadChannel(params: {
     name: channelInfo?.name ?? undefined,
     parentId: channelInfo?.parentId ?? undefined,
     parent: undefined,
+    ownerId: channelInfo?.ownerId ?? undefined,
   };
 }
 

src/gateway/protocol/schema/exec-approvals.ts

@@ -92,13 +92,13 @@ export const ExecApprovalRequestParamsSchema = Type.Object(
   {
     id: Type.Optional(NonEmptyString),
     command: NonEmptyString,
-    cwd: Type.Optional(Type.String()),
-    host: Type.Optional(Type.String()),
-    security: Type.Optional(Type.String()),
-    ask: Type.Optional(Type.String()),
-    agentId: Type.Optional(Type.String()),
-    resolvedPath: Type.Optional(Type.String()),
-    sessionKey: Type.Optional(Type.String()),
+    cwd: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    host: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    security: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    ask: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    agentId: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    resolvedPath: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    sessionKey: Type.Optional(Type.Union([Type.String(), Type.Null()])),
     timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
   },
   { additionalProperties: false },

src/gateway/server-methods/exec-approval.test.ts

@@ -36,16 +36,16 @@ describe("exec approval handlers", () => {
       expect(validateExecApprovalRequestParams(params)).toBe(true);
     });
 
-    // This documents the TypeBox/AJV behavior that caused the Discord exec bug:
-    // Type.Optional(Type.String()) does NOT accept null, only string or undefined.
-    it("rejects request with resolvedPath as null", () => {
+    // Fixed: null is now accepted (Type.Union([Type.String(), Type.Null()]))
+    // This matches the calling code in bash-tools.exec.ts which passes null.
+    it("accepts request with resolvedPath as null", () => {
       const params = {
         command: "echo hi",
         cwd: "/tmp",
         host: "node",
         resolvedPath: null,
       };
-      expect(validateExecApprovalRequestParams(params)).toBe(false);
+      expect(validateExecApprovalRequestParams(params)).toBe(true);
     });
   });
 

src/infra/heartbeat-runner.returns-default-unset.test.ts

@@ -793,4 +793,209 @@ describe("runHeartbeatOnce", () => {
       await fs.rm(tmpDir, { recursive: true, force: true });
     }
   });
+
+  it("skips heartbeat when HEARTBEAT.md is effectively empty (saves API calls)", async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-hb-"));
+    const storePath = path.join(tmpDir, "sessions.json");
+    const workspaceDir = path.join(tmpDir, "workspace");
+    const replySpy = vi.spyOn(replyModule, "getReplyFromConfig");
+    try {
+      await fs.mkdir(workspaceDir, { recursive: true });
+
+      // Create effectively empty HEARTBEAT.md (only header and comments)
+      await fs.writeFile(
+        path.join(workspaceDir, "HEARTBEAT.md"),
+        "# HEARTBEAT.md\n\n## Tasks\n\n",
+        "utf-8",
+      );
+
+      const cfg: ClawdbotConfig = {
+        agents: {
+          defaults: {
+            workspace: workspaceDir,
+            heartbeat: { every: "5m", target: "whatsapp" },
+          },
+        },
+        channels: { whatsapp: { allowFrom: ["*"] } },
+        session: { store: storePath },
+      };
+      const sessionKey = resolveMainSessionKey(cfg);
+
+      await fs.writeFile(
+        storePath,
+        JSON.stringify(
+          {
+            [sessionKey]: {
+              sessionId: "sid",
+              updatedAt: Date.now(),
+              lastChannel: "whatsapp",
+              lastTo: "+1555",
+            },
+          },
+          null,
+          2,
+        ),
+      );
+
+      const sendWhatsApp = vi.fn().mockResolvedValue({
+        messageId: "m1",
+        toJid: "jid",
+      });
+
+      const res = await runHeartbeatOnce({
+        cfg,
+        deps: {
+          sendWhatsApp,
+          getQueueSize: () => 0,
+          nowMs: () => 0,
+          webAuthExists: async () => true,
+          hasActiveWebListener: () => true,
+        },
+      });
+
+      // Should skip without making API call
+      expect(res.status).toBe("skipped");
+      if (res.status === "skipped") {
+        expect(res.reason).toBe("empty-heartbeat-file");
+      }
+      expect(replySpy).not.toHaveBeenCalled();
+      expect(sendWhatsApp).not.toHaveBeenCalled();
+    } finally {
+      replySpy.mockRestore();
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("runs heartbeat when HEARTBEAT.md has actionable content", async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-hb-"));
+    const storePath = path.join(tmpDir, "sessions.json");
+    const workspaceDir = path.join(tmpDir, "workspace");
+    const replySpy = vi.spyOn(replyModule, "getReplyFromConfig");
+    try {
+      await fs.mkdir(workspaceDir, { recursive: true });
+
+      // Create HEARTBEAT.md with actionable content
+      await fs.writeFile(
+        path.join(workspaceDir, "HEARTBEAT.md"),
+        "# HEARTBEAT.md\n\n- Check server logs\n- Review pending PRs\n",
+        "utf-8",
+      );
+
+      const cfg: ClawdbotConfig = {
+        agents: {
+          defaults: {
+            workspace: workspaceDir,
+            heartbeat: { every: "5m", target: "whatsapp" },
+          },
+        },
+        channels: { whatsapp: { allowFrom: ["*"] } },
+        session: { store: storePath },
+      };
+      const sessionKey = resolveMainSessionKey(cfg);
+
+      await fs.writeFile(
+        storePath,
+        JSON.stringify(
+          {
+            [sessionKey]: {
+              sessionId: "sid",
+              updatedAt: Date.now(),
+              lastChannel: "whatsapp",
+              lastTo: "+1555",
+            },
+          },
+          null,
+          2,
+        ),
+      );
+
+      replySpy.mockResolvedValue({ text: "Checked logs and PRs" });
+      const sendWhatsApp = vi.fn().mockResolvedValue({
+        messageId: "m1",
+        toJid: "jid",
+      });
+
+      const res = await runHeartbeatOnce({
+        cfg,
+        deps: {
+          sendWhatsApp,
+          getQueueSize: () => 0,
+          nowMs: () => 0,
+          webAuthExists: async () => true,
+          hasActiveWebListener: () => true,
+        },
+      });
+
+      // Should run and make API call
+      expect(res.status).toBe("ran");
+      expect(replySpy).toHaveBeenCalled();
+      expect(sendWhatsApp).toHaveBeenCalledTimes(1);
+    } finally {
+      replySpy.mockRestore();
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("runs heartbeat when HEARTBEAT.md does not exist (lets LLM decide)", async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-hb-"));
+    const storePath = path.join(tmpDir, "sessions.json");
+    const workspaceDir = path.join(tmpDir, "workspace");
+    const replySpy = vi.spyOn(replyModule, "getReplyFromConfig");
+    try {
+      await fs.mkdir(workspaceDir, { recursive: true });
+      // Don't create HEARTBEAT.md - it doesn't exist
+
+      const cfg: ClawdbotConfig = {
+        agents: {
+          defaults: {
+            workspace: workspaceDir,
+            heartbeat: { every: "5m", target: "whatsapp" },
+          },
+        },
+        channels: { whatsapp: { allowFrom: ["*"] } },
+        session: { store: storePath },
+      };
+      const sessionKey = resolveMainSessionKey(cfg);
+
+      await fs.writeFile(
+        storePath,
+        JSON.stringify(
+          {
+            [sessionKey]: {
+              sessionId: "sid",
+              updatedAt: Date.now(),
+              lastChannel: "whatsapp",
+              lastTo: "+1555",
+            },
+          },
+          null,
+          2,
+        ),
+      );
+
+      replySpy.mockResolvedValue({ text: "HEARTBEAT_OK" });
+      const sendWhatsApp = vi.fn().mockResolvedValue({
+        messageId: "m1",
+        toJid: "jid",
+      });
+
+      const res = await runHeartbeatOnce({
+        cfg,
+        deps: {
+          sendWhatsApp,
+          getQueueSize: () => 0,
+          nowMs: () => 0,
+          webAuthExists: async () => true,
+          hasActiveWebListener: () => true,
+        },
+      });
+
+      // Should run (not skip) - let LLM decide since file doesn't exist
+      expect(res.status).toBe("ran");
+      expect(replySpy).toHaveBeenCalled();
+    } finally {
+      replySpy.mockRestore();
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
 });

src/infra/heartbeat-runner.ts

@@ -1,9 +1,18 @@
-import { resolveAgentConfig, resolveDefaultAgentId } from "../agents/agent-scope.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  resolveAgentConfig,
+  resolveAgentWorkspaceDir,
+  resolveDefaultAgentId,
+} from "../agents/agent-scope.js";
 import { resolveUserTimezone } from "../agents/date-time.js";
 import { resolveEffectiveMessagesConfig } from "../agents/identity.js";
+import { DEFAULT_HEARTBEAT_FILENAME } from "../agents/workspace.js";
 import {
   DEFAULT_HEARTBEAT_ACK_MAX_CHARS,
   DEFAULT_HEARTBEAT_EVERY,
+  isHeartbeatContentEffectivelyEmpty,
   resolveHeartbeatPrompt as resolveHeartbeatPromptText,
   stripHeartbeatToken,
 } from "../auto-reply/heartbeat.js";
@@ -440,6 +449,25 @@ export async function runHeartbeatOnce(opts: {
     return { status: "skipped", reason: "requests-in-flight" };
   }
 
+  // Skip heartbeat if HEARTBEAT.md exists but has no actionable content.
+  // This saves API calls/costs when the file is effectively empty (only comments/headers).
+  const workspaceDir = resolveAgentWorkspaceDir(cfg, agentId);
+  const heartbeatFilePath = path.join(workspaceDir, DEFAULT_HEARTBEAT_FILENAME);
+  try {
+    const heartbeatFileContent = await fs.readFile(heartbeatFilePath, "utf-8");
+    if (isHeartbeatContentEffectivelyEmpty(heartbeatFileContent)) {
+      emitHeartbeatEvent({
+        status: "skipped",
+        reason: "empty-heartbeat-file",
+        durationMs: Date.now() - startedAt,
+      });
+      return { status: "skipped", reason: "empty-heartbeat-file" };
+    }
+  } catch {
+    // File doesn't exist or can't be read - proceed with heartbeat.
+    // The LLM prompt says "if it exists" so this is expected behavior.
+  }
+
   const { entry, sessionKey, storePath } = resolveHeartbeatSession(cfg, agentId, heartbeat);
   const previousUpdatedAt = entry?.updatedAt;
   const delivery = resolveHeartbeatDeliveryTarget({ cfg, entry, heartbeat });