@vellumai/assistant 0.7.1 → 0.7.3

package/src/heartbeat/heartbeat-service.ts

@@ -2,21 +2,38 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { getConfig } from "../config/loader.js";
+import type { HeartbeatConfig } from "../config/schemas/heartbeat.js";
+import {
+  checkDiskPressureBackgroundGate,
+  diskPressureBackgroundSkipLogFields,
+  shouldLogDiskPressureBackgroundSkip,
+} from "../daemon/disk-pressure-background-gate.js";
 import type { HeartbeatAlert } from "../daemon/message-protocol.js";
 import { processMessage } from "../daemon/process-message.js";
 import { emitFeedEvent } from "../home/emit-feed-event.js";
 import { bootstrapConversation } from "../memory/conversation-bootstrap.js";
-import { getConversation } from "../memory/conversation-crud.js";
+import { getConversation, getMessages } from "../memory/conversation-crud.js";
 import { GENERATING_TITLE } from "../memory/conversation-title-service.js";
 import {
   GUARDIAN_PERSONA_TEMPLATE,
   resolveGuardianPersona,
 } from "../prompts/persona-resolver.js";
 import { isTemplateContent } from "../prompts/system-prompt.js";
+import { computeNextRunAt } from "../schedule/recurrence-engine.js";
 import { readTextFileSync } from "../util/fs.js";
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceDir, getWorkspacePromptPath } from "../util/platform.js";
 import { stripCommentLines } from "../util/strip-comment-lines.js";
+import {
+  completeHeartbeatRun,
+  countCompletedHeartbeatRuns,
+  insertPendingHeartbeatRun,
+  markStaleRunningAsError,
+  markStaleRunsAsMissed,
+  skipHeartbeatRun,
+  startHeartbeatRun,
+  supersedePendingRun,
+} from "./heartbeat-run-store.js";
 
 const log = getLogger("heartbeat-check");
 
@@ -27,8 +44,12 @@ const DEFAULT_CHECKLIST = `- Check in with yourself. Read NOW.md. Is it still ac
 - If you have a thought worth sharing, send it. A follow-up, a useful find, a check-in. Not every beat, but when it feels right.
 - If something has happened since your last journal entry, write one. Even a few sentences. The journal is how future-you stays connected.`;
 
+const EARLY_HEARTBEAT_THRESHOLD = 3;
 const REENGAGEMENT_COOLDOWN_MS = 18 * 60 * 60 * 1000; // 18 hours
 const HEARTBEAT_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+const HEARTBEAT_ALERT_MARKER = "HEARTBEAT_ALERT";
+const HEARTBEAT_OK_MARKER = "HEARTBEAT_OK";
+const HEARTBEAT_ALERT_SUMMARY_MAX_CHARS = 700;
 
 // Stripped-comment form of the guardian persona scaffold. Computed
 // once at module load because stripping comment lines is deterministic
@@ -81,6 +102,69 @@ function recordReengagementTimestamp(): void {
   }
 }
 
+type HeartbeatDisposition = "alert" | "ok" | "unknown";
+
+function parseHeartbeatDisposition(text: string | null): HeartbeatDisposition {
+  if (!text) return "unknown";
+  const lines = text
+    .trim()
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  const lastLine = lines.at(-1);
+  if (lastLine === HEARTBEAT_ALERT_MARKER) return "alert";
+  if (lastLine === HEARTBEAT_OK_MARKER) return "ok";
+  return "unknown";
+}
+
+function stripHeartbeatDispositionMarkers(text: string): string {
+  return text
+    .replace(
+      new RegExp(
+        `(?:\\r?\\n)?\\s*(?:${HEARTBEAT_ALERT_MARKER}|${HEARTBEAT_OK_MARKER})\\s*$`,
+      ),
+      "",
+    )
+    .trim();
+}
+
+function truncateSummary(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, Math.max(0, maxChars - 3)).trimEnd()}...`;
+}
+
+function buildHeartbeatAlertSummary(text: string | null): string {
+  const summary = text ? stripHeartbeatDispositionMarkers(text) : "";
+  return truncateSummary(
+    summary || "Your assistant found something worth your attention.",
+    HEARTBEAT_ALERT_SUMMARY_MAX_CHARS,
+  );
+}
+
+function extractVisibleTextFromStoredMessageContent(raw: string): string {
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (typeof parsed === "string") return parsed;
+    if (!Array.isArray(parsed)) return "";
+    const texts: string[] = [];
+    for (const block of parsed) {
+      if (
+        block != null &&
+        typeof block === "object" &&
+        "type" in block &&
+        block.type === "text" &&
+        "text" in block &&
+        typeof block.text === "string"
+      ) {
+        texts.push(block.text);
+      }
+    }
+    return texts.join("\n").trim();
+  } catch {
+    return raw;
+  }
+}
+
 export interface HeartbeatDeps {
   alerter: (alert: HeartbeatAlert) => void;
   onConversationCreated?: (info: {
@@ -100,10 +184,20 @@ export class HeartbeatService {
   }
 
   private readonly deps: HeartbeatDeps;
-  private timer: ReturnType<typeof setInterval> | null = null;
+  private timer:
+    | ReturnType<typeof setInterval>
+    | ReturnType<typeof setTimeout>
+    | null = null;
   private activeRun: Promise<void> | null = null;
   private _lastRunAt: number | null = null;
   private _nextRunAt: number | null = null;
+  private cronMode = false;
+  private stopped = false;
+  private configEpoch = 0;
+  private _pendingRunId: string | null = null;
+  private _startupMissedCount = 0;
+  private _startupCrashedCount = 0;
+  private _hasRunStartupRecovery = false;
 
   constructor(deps: HeartbeatDeps) {
     this.deps = deps;
@@ -121,6 +215,7 @@ export class HeartbeatService {
   }
 
   start(): void {
+    this.stopped = false;
     const config = getConfig().heartbeat;
     if (!config.enabled) {
       log.info("Heartbeat disabled by config");
@@ -129,7 +224,61 @@ export class HeartbeatService {
     }
     if (this.timer) return;
 
-    log.info({ intervalMs: config.intervalMs }, "Heartbeat service started");
+    if (!this._hasRunStartupRecovery) {
+      this._hasRunStartupRecovery = true;
+      try {
+        this._startupMissedCount = markStaleRunsAsMissed();
+        this._startupCrashedCount = markStaleRunningAsError();
+      } catch (err) {
+        log.error({ err }, "Failed to recover stale heartbeat runs on startup");
+      }
+      if (this._startupMissedCount > 0 || this._startupCrashedCount > 0) {
+        log.info(
+          {
+            missedCount: this._startupMissedCount,
+            crashedCount: this._startupCrashedCount,
+          },
+          "Recovered stale heartbeat runs on startup",
+        );
+
+        if (!isDiskPressureBackgroundLocked("heartbeat-startup")) {
+          const total = this._startupMissedCount + this._startupCrashedCount;
+          const today = new Date().toISOString().split("T")[0];
+          void emitFeedEvent({
+            source: "assistant",
+            title: "Heartbeat Runs Missed",
+            summary: `${total} heartbeat run${
+              total > 1 ? "s were" : " was"
+            } missed while the assistant was offline.`,
+            dedupKey: `heartbeat:missed:${today}`,
+            priority: 55,
+            urgency: "high",
+          }).catch((err) => {
+            log.warn({ err }, "Failed to emit missed heartbeat feed event");
+          });
+        }
+      }
+    }
+
+    if (config.cronExpression != null) {
+      this.cronMode = true;
+      this.scheduleNextCronRun(config);
+    } else {
+      this.startIntervalMode(config);
+    }
+  }
+
+  private startIntervalMode(config: HeartbeatConfig): void {
+    this.cronMode = false;
+    if (this.timer) {
+      clearTimeout(this.timer as ReturnType<typeof setTimeout>);
+      clearInterval(this.timer as ReturnType<typeof setInterval>);
+      this.timer = null;
+    }
+    log.info(
+      { intervalMs: config.intervalMs },
+      "Heartbeat service started (interval mode)",
+    );
     this.scheduleNextRun(config.intervalMs);
     this.timer = setInterval(() => {
       this.runOnce().catch((err) => {
@@ -138,13 +287,69 @@ export class HeartbeatService {
     }, config.intervalMs);
   }
 
+  private scheduleNextCronRun(config: HeartbeatConfig): void {
+    if (this.stopped) return;
+    try {
+      const nextRunAt = computeNextRunAt({
+        syntax: "cron",
+        expression: config.cronExpression!,
+        timezone: config.timezone,
+      });
+      this._nextRunAt = nextRunAt;
+      if (this.timer) {
+        clearTimeout(this.timer as ReturnType<typeof setTimeout>);
+        clearInterval(this.timer as ReturnType<typeof setInterval>);
+        this.timer = null;
+      }
+      const MAX_TIMEOUT_MS = 24 * 60 * 60 * 1000; // 24 hours
+      const delayMs = Math.max(0, nextRunAt - Date.now());
+      const epoch = this.configEpoch;
+      if (delayMs > MAX_TIMEOUT_MS) {
+        // Re-evaluate after 24h — the actual cron time is still far away
+        this.timer = setTimeout(() => {
+          if (this.configEpoch === epoch) {
+            this.scheduleNextCronRun(getConfig().heartbeat);
+          }
+        }, MAX_TIMEOUT_MS);
+      } else {
+        this.timer = setTimeout(() => {
+          this.runOnce()
+            .catch((err) => log.error({ err }, "Cron heartbeat failed"))
+            .finally(() => {
+              if (this.configEpoch === epoch) {
+                this.scheduleNextCronRun(getConfig().heartbeat);
+              }
+            });
+        }, delayMs);
+      }
+      (this.timer as ReturnType<typeof setTimeout>).unref();
+      log.info(
+        { nextRunAt: new Date(nextRunAt).toISOString(), delayMs },
+        "Heartbeat cron run scheduled",
+      );
+    } catch (err) {
+      log.warn(
+        { err },
+        "Failed to compute next cron run, falling back to interval mode",
+      );
+      this.startIntervalMode(config);
+    }
+  }
+
   /** Restart the timer with the latest config (e.g. after settings change). */
   reconfigure(): void {
+    this.configEpoch++;
+    if (this._pendingRunId) {
+      supersedePendingRun(this._pendingRunId);
+      this._pendingRunId = null;
+    }
     if (this.timer) {
-      clearInterval(this.timer);
+      clearTimeout(this.timer as ReturnType<typeof setTimeout>);
+      clearInterval(this.timer as ReturnType<typeof setInterval>);
       this.timer = null;
     }
     this._nextRunAt = null;
+    this.cronMode = false;
     this.start();
   }
 
@@ -155,8 +360,15 @@ export class HeartbeatService {
    */
   resetTimer(): void {
     if (!this.timer) return;
+    if (this.cronMode) {
+      clearTimeout(this.timer as ReturnType<typeof setTimeout>);
+      clearInterval(this.timer as ReturnType<typeof setInterval>);
+      this.timer = null;
+      this.scheduleNextCronRun(getConfig().heartbeat);
+      return;
+    }
     const config = getConfig().heartbeat;
-    clearInterval(this.timer);
+    clearInterval(this.timer as ReturnType<typeof setInterval>);
     this.scheduleNextRun(config.intervalMs);
     this.timer = setInterval(() => {
       this.runOnce().catch((err) => {
@@ -166,10 +378,16 @@ export class HeartbeatService {
   }
 
   async stop(): Promise<void> {
+    this.stopped = true;
     if (this.timer) {
-      clearInterval(this.timer);
+      clearTimeout(this.timer as ReturnType<typeof setTimeout>);
+      clearInterval(this.timer as ReturnType<typeof setInterval>);
       this.timer = null;
     }
+    if (this._pendingRunId) {
+      supersedePendingRun(this._pendingRunId);
+      this._pendingRunId = null;
+    }
     this._nextRunAt = null;
     if (this.activeRun) {
       let timerId: ReturnType<typeof setTimeout>;
@@ -186,7 +404,26 @@ export class HeartbeatService {
    *  When `force` is true (e.g. manual "Run Now"), skip enabled & active-hours guards. */
   async runOnce({ force = false }: { force?: boolean } = {}): Promise<boolean> {
     const config = getConfig().heartbeat;
-    if (!force && !config.enabled) return false;
+
+    if (!force && isDiskPressureBackgroundLocked("heartbeat")) {
+      return false;
+    }
+
+    let runId: string | null;
+    let scheduledFor: number;
+    if (force) {
+      scheduledFor = Date.now();
+      runId = insertPendingHeartbeatRun(scheduledFor);
+    } else {
+      runId = this._pendingRunId;
+      scheduledFor = this._nextRunAt ?? Date.now();
+      this._pendingRunId = null;
+    }
+
+    if (!force && !config.enabled) {
+      if (runId) skipHeartbeatRun(runId, "disabled");
+      return false;
+    }
 
     // Active hours guard — only applied when both bounds are set.
     // The schema rejects configs where only one bound is provided.
@@ -195,7 +432,17 @@ export class HeartbeatService {
       config.activeHoursStart != null &&
       config.activeHoursEnd != null
     ) {
-      const hour = this.deps.getCurrentHour?.() ?? new Date().getHours();
+      let hour: number;
+      if (this.cronMode && config.timezone) {
+        const parts = new Intl.DateTimeFormat("en-US", {
+          timeZone: config.timezone,
+          hourCycle: "h23",
+          hour: "numeric",
+        }).formatToParts(new Date());
+        hour = Number(parts.find((p) => p.type === "hour")!.value);
+      } else {
+        hour = this.deps.getCurrentHour?.() ?? new Date().getHours();
+      }
       if (
         !isWithinActiveHours(
           hour,
@@ -211,7 +458,10 @@ export class HeartbeatService {
           },
           "Outside active hours, skipping",
         );
-        this.scheduleNextRun(config.intervalMs);
+        if (runId) skipHeartbeatRun(runId, "outside_active_hours");
+        if (!this.cronMode) {
+          this.scheduleNextRun(config.intervalMs);
+        }
         return false;
       }
     }
@@ -219,10 +469,14 @@ export class HeartbeatService {
     // Overlap prevention
     if (this.activeRun) {
       log.debug("Previous heartbeat run still active, skipping");
+      if (runId) skipHeartbeatRun(runId, "overlap");
       return false;
     }
 
-    const run = this.executeRun();
+    if (!runId) {
+      runId = insertPendingHeartbeatRun(scheduledFor);
+    }
+    const run = this.executeRun(runId, scheduledFor);
     this.activeRun = run;
     // Clear activeRun once executeRun finishes. On timeout, runOnce releases
     // activeRun separately (see catch block below) so future runs aren't
@@ -252,16 +506,39 @@ export class HeartbeatService {
       // Release activeRun so the overlap guard doesn't permanently block
       // future heartbeat runs when executeRun hangs past the timeout.
       this.activeRun = null;
+      const transitioned = runId
+        ? completeHeartbeatRun(runId, {
+            status: "timeout",
+            error: "Heartbeat execution exceeded the 30-minute timeout",
+          })
+        : false;
+      if (transitioned) {
+        const today = new Date().toISOString().split("T")[0];
+        void emitFeedEvent({
+          source: "assistant",
+          title: "Heartbeat Timed Out",
+          summary: "Heartbeat execution exceeded the 30-minute timeout.",
+          dedupKey: `heartbeat:timeout:${today}`,
+          priority: 55,
+          urgency: "high",
+        }).catch(() => {});
+      }
     } finally {
       clearTimeout(timerId);
       this._lastRunAt = Date.now();
-      this.scheduleNextRun(getConfig().heartbeat.intervalMs);
+      if (!this.cronMode) {
+        this.scheduleNextRun(getConfig().heartbeat.intervalMs);
+      }
     }
     return true;
   }
 
   private scheduleNextRun(intervalMs: number): void {
+    if (this._pendingRunId) {
+      supersedePendingRun(this._pendingRunId);
+    }
     this._nextRunAt = Date.now() + intervalMs;
+    this._pendingRunId = insertPendingHeartbeatRun(this._nextRunAt);
   }
 
   /**
@@ -383,19 +660,86 @@ export class HeartbeatService {
     }
   }
 
-  private async executeRun(): Promise<void> {
+  private getLatestAssistantMessage(
+    conversationId: string,
+  ): { id: string; text: string } | null {
+    try {
+      const messages = getMessages(conversationId);
+      for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i]!;
+        if (message.role !== "assistant") continue;
+        return {
+          id: message.id,
+          text: extractVisibleTextFromStoredMessageContent(message.content),
+        };
+      }
+    } catch (err) {
+      log.warn(
+        { err, conversationId },
+        "Failed to read heartbeat assistant message",
+      );
+    }
+    return null;
+  }
+
+  private async emitHeartbeatAlertNotification(params: {
+    runId: string;
+    conversationId: string;
+    messageId?: string;
+    conversationTitle: string;
+    summary: string;
+  }): Promise<void> {
+    const { emitNotificationSignal } =
+      await import("../notifications/emit-signal.js");
+
+    await emitNotificationSignal({
+      sourceEventName: "heartbeat.alert",
+      sourceChannel: "watcher",
+      sourceContextId: params.runId,
+      dedupeKey: `heartbeat:alert:${params.runId}`,
+      attentionHints: {
+        requiresAction: true,
+        urgency: "medium",
+        isAsyncBackground: true,
+        visibleInSourceNow: false,
+      },
+      contextPayload: {
+        title: "Heartbeat Alert",
+        summary: params.summary,
+        conversationTitle: params.conversationTitle,
+        conversationId: params.conversationId,
+        messageId: params.messageId,
+      },
+      routingIntent: "single_channel",
+      conversationAffinityHint: { vellum: params.conversationId },
+      conversationMetadata: {
+        source: "heartbeat",
+        groupId: "system:background",
+      },
+    });
+  }
+
+  private async executeRun(runId: string, scheduledFor: number): Promise<void> {
     log.info("Running heartbeat");
 
+    startHeartbeatRun(runId);
+
+    const latenessMs = Date.now() - scheduledFor;
+    const LATE_THRESHOLD_MS = 5 * 60 * 1000;
+
     // Credential health check — surface broken credentials proactively
     // before the LLM heartbeat prompt runs. Returns unhealthy provider
     // names so the prompt can instruct the LLM to skip those providers.
     const unhealthyProviders = await this.runCredentialHealthCheck();
 
+    let conversationId: string | undefined;
     try {
       const checklist = this.readChecklist();
+      const completedRunCount = countCompletedHeartbeatRuns();
       const { prompt, includedReengagement } = this.buildPrompt(
         checklist,
         unhealthyProviders,
+        completedRunCount,
       );
 
       const conversation = bootstrapConversation({
@@ -405,11 +749,7 @@ export class HeartbeatService {
         origin: "heartbeat",
         systemHint: "Heartbeat",
       });
-
-      this.deps.onConversationCreated?.({
-        conversationId: conversation.id,
-        title: "Heartbeat",
-      });
+      conversationId = conversation.id;
 
       await processMessage(conversation.id, prompt, undefined, {
         trustContext: {
@@ -425,50 +765,90 @@ export class HeartbeatService {
 
       log.info({ conversationId: conversation.id }, "Heartbeat completed");
 
-      let title = "Heartbeat";
-      try {
-        const row = getConversation(conversation.id);
-        if (row?.title && row.title !== GENERATING_TITLE) {
-          title = row.title;
+      const transitioned = completeHeartbeatRun(runId, {
+        status: "ok",
+        conversationId,
+      });
+
+      if (transitioned) {
+        let title = "Heartbeat";
+        try {
+          const row = getConversation(conversation.id);
+          if (row?.title && row.title !== GENERATING_TITLE) {
+            title = row.title;
+          }
+        } catch {
+          // Best-effort; fall back to generic title.
         }
-      } catch {
-        // Best-effort; fall back to generic title.
-      }
 
-      const today = new Date().toISOString().split("T")[0];
-      void emitFeedEvent({
-        source: "assistant",
-        title,
-        summary: "Periodic check completed. Tap to see details.",
-        dedupKey: `heartbeat:ok:${today}`,
-        priority: 30,
-      }).catch((err) => {
-        log.warn(
-          { err, conversationId: conversation.id },
-          "Failed to emit heartbeat feed event",
+        const assistantMessage = this.getLatestAssistantMessage(
+          conversation.id,
         );
-      });
+        const disposition = parseHeartbeatDisposition(
+          assistantMessage?.text ?? null,
+        );
+        if (disposition === "alert") {
+          this.deps.onConversationCreated?.({
+            conversationId: conversation.id,
+            title,
+          });
+          void this.emitHeartbeatAlertNotification({
+            runId,
+            conversationId: conversation.id,
+            messageId: assistantMessage?.id,
+            conversationTitle: title,
+            summary: buildHeartbeatAlertSummary(assistantMessage?.text ?? null),
+          }).catch((err) => {
+            log.warn(
+              { err, conversationId: conversation.id },
+              "Failed to emit heartbeat alert notification",
+            );
+          });
+        }
+
+        const today = new Date().toISOString().split("T")[0];
+        if (latenessMs > LATE_THRESHOLD_MS) {
+          const lateMinutes = Math.round(latenessMs / 60_000);
+          void emitFeedEvent({
+            source: "assistant",
+            title: "Heartbeat Ran Late",
+            summary: `Heartbeat ran ${lateMinutes} minutes late (scheduled for ${new Date(scheduledFor).toLocaleTimeString()}).`,
+            dedupKey: `heartbeat:late:${today}`,
+            priority: 45,
+            urgency: "medium",
+          }).catch(() => {});
+        }
+      }
     } catch (err) {
       log.error({ err }, "Heartbeat failed");
-      try {
-        this.deps.alerter({
-          type: "heartbeat_alert",
+
+      const transitioned = completeHeartbeatRun(runId, {
+        status: "error",
+        conversationId,
+        error: err instanceof Error ? err.message : String(err),
+      });
+
+      if (transitioned) {
+        try {
+          this.deps.alerter({
+            type: "heartbeat_alert",
+            title: "Heartbeat Failed",
+            body: err instanceof Error ? err.message : String(err),
+          });
+        } catch (alertErr) {
+          log.error({ alertErr }, "Failed to broadcast heartbeat alert");
+        }
+
+        const today = new Date().toISOString().split("T")[0];
+        void emitFeedEvent({
+          source: "assistant",
           title: "Heartbeat Failed",
-          body: err instanceof Error ? err.message : String(err),
-        });
-      } catch (alertErr) {
-        log.error({ alertErr }, "Failed to broadcast heartbeat alert");
+          summary: `Heartbeat check failed: ${(err instanceof Error ? err.message : String(err)).slice(0, 200)}`,
+          dedupKey: `heartbeat:fail:${today}`,
+          priority: 55,
+          urgency: "high",
+        }).catch(() => {});
       }
-
-      const today = new Date().toISOString().split("T")[0];
-      void emitFeedEvent({
-        source: "assistant",
-        title: "Heartbeat",
-        summary: "Heartbeat check failed. Check logs for details.",
-        dedupKey: `heartbeat:fail:${today}`,
-        priority: 55,
-        urgency: "medium",
-      }).catch(() => {});
     }
   }
 
@@ -483,6 +863,7 @@ export class HeartbeatService {
   buildPrompt(
     checklist: string,
     unhealthyProviders: string[] = [],
+    completedRunCount: number = Infinity,
   ): { prompt: string; includedReengagement: boolean } {
     let prompt = `You are running a periodic heartbeat check. Review the following checklist and take any necessary actions.
 
@@ -499,11 +880,20 @@ Do NOT attempt to use tools for these providers — they will fail. Skip any che
     }
 
     prompt += `\n\n<heartbeat-disposition>
+This heartbeat runs frequently. Do not manufacture a report just because it ran.
+If there is nothing genuinely useful, actionable, or interesting to surface, keep the response brief and end with HEARTBEAT_OK.
+If there is something worth interrupting the guardian for, write a concise guardian-facing note first: what happened, why it matters, and the recommended next step. Then end with HEARTBEAT_ALERT. That note may be used as notification copy.
 After completing your review, end your response with one of:
 - HEARTBEAT_OK — if everything looks good, no action needed
 - HEARTBEAT_ALERT — if you found issues that need attention (describe them before this marker)
 </heartbeat-disposition>`;
 
+    if (completedRunCount < EARLY_HEARTBEAT_THRESHOLD) {
+      prompt += `\n\n<early-heartbeat>
+This is one of your first heartbeats. Your user hasn't heard from you yet and may not know you're here. Find something genuinely useful to share — a follow-up from a recent conversation, something you noticed, or a quick check-in. Lean toward HEARTBEAT_ALERT this time. First impressions matter.
+</early-heartbeat>`;
+    }
+
     let includedReengagement = false;
     if (isShallowProfile() && isReengagementCooldownElapsed()) {
       includedReengagement = true;
@@ -514,6 +904,21 @@ After completing your review, end your response with one of:
   }
 }
 
+function isDiskPressureBackgroundLocked(logKey: string): boolean {
+  const diskPressureGate = checkDiskPressureBackgroundGate("background-work");
+  if (diskPressureGate.action === "allow") return false;
+  if (shouldLogDiskPressureBackgroundSkip(logKey)) {
+    log.warn(
+      {
+        source: "heartbeat",
+        ...diskPressureBackgroundSkipLogFields(diskPressureGate),
+      },
+      "Heartbeat skipped during disk pressure cleanup mode",
+    );
+  }
+  return true;
+}
+
 /**
  * Check if the given hour falls within the active window.
  * Handles overnight windows (e.g. start=22, end=6).