@poolzin/pool-bot 2026.2.21 → 2026.2.22

package/dist/infra/exec-safe-bin-trust.js

@@ -0,0 +1,64 @@
+import path from "node:path";
+const DEFAULT_SAFE_BIN_TRUSTED_DIRS = [
+    "/bin",
+    "/usr/bin",
+    "/usr/local/bin",
+    "/opt/homebrew/bin",
+    "/opt/local/bin",
+    "/snap/bin",
+    "/run/current-system/sw/bin",
+];
+let trustedSafeBinCache = null;
+function normalizeTrustedDir(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return null;
+    }
+    return path.resolve(trimmed);
+}
+function buildTrustedSafeBinCacheKey(pathEnv, delimiter) {
+    return `${delimiter}\u0000${pathEnv}`;
+}
+export function buildTrustedSafeBinDirs(params = {}) {
+    const delimiter = params.delimiter ?? path.delimiter;
+    const pathEnv = params.pathEnv ?? "";
+    const baseDirs = params.baseDirs ?? DEFAULT_SAFE_BIN_TRUSTED_DIRS;
+    const trusted = new Set();
+    for (const entry of baseDirs) {
+        const normalized = normalizeTrustedDir(entry);
+        if (normalized) {
+            trusted.add(normalized);
+        }
+    }
+    const pathEntries = pathEnv
+        .split(delimiter)
+        .map((entry) => normalizeTrustedDir(entry))
+        .filter((entry) => Boolean(entry));
+    for (const entry of pathEntries) {
+        trusted.add(entry);
+    }
+    return trusted;
+}
+export function getTrustedSafeBinDirs(params = {}) {
+    const delimiter = params.delimiter ?? path.delimiter;
+    const pathEnv = params.pathEnv ?? process.env.PATH ?? process.env.Path ?? "";
+    const key = buildTrustedSafeBinCacheKey(pathEnv, delimiter);
+    if (!params.refresh && trustedSafeBinCache?.key === key) {
+        return trustedSafeBinCache.dirs;
+    }
+    const dirs = buildTrustedSafeBinDirs({
+        pathEnv,
+        delimiter,
+    });
+    trustedSafeBinCache = { key, dirs };
+    return dirs;
+}
+export function isTrustedSafeBinPath(params) {
+    const trustedDirs = params.trustedDirs ??
+        getTrustedSafeBinDirs({
+            pathEnv: params.pathEnv,
+            delimiter: params.delimiter,
+        });
+    const resolvedDir = path.dirname(path.resolve(params.resolvedPath));
+    return trustedDirs.has(resolvedDir);
+}

package/dist/infra/heartbeat-runner.js

@@ -1,128 +1,44 @@
 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 { appendCronStyleCurrentTimeLine } from "../agents/current-time.js";
 import { resolveEffectiveMessagesConfig } from "../agents/identity.js";
 import { DEFAULT_HEARTBEAT_FILENAME } from "../agents/workspace.js";
+import { resolveHeartbeatReplyPayload } from "../auto-reply/heartbeat-reply-payload.js";
 import { DEFAULT_HEARTBEAT_ACK_MAX_CHARS, DEFAULT_HEARTBEAT_EVERY, isHeartbeatContentEffectivelyEmpty, resolveHeartbeatPrompt as resolveHeartbeatPromptText, stripHeartbeatToken, } from "../auto-reply/heartbeat.js";
 import { getReplyFromConfig } from "../auto-reply/reply.js";
 import { HEARTBEAT_TOKEN } from "../auto-reply/tokens.js";
 import { getChannelPlugin } from "../channels/plugins/index.js";
 import { parseDurationMs } from "../cli/parse-duration.js";
 import { loadConfig } from "../config/config.js";
-import { canonicalizeMainSessionAlias, loadSessionStore, resolveAgentIdFromSessionKey, resolveAgentMainSessionKey, resolveStorePath, saveSessionStore, updateSessionStore, } from "../config/sessions.js";
+import { canonicalizeMainSessionAlias, loadSessionStore, resolveAgentIdFromSessionKey, resolveAgentMainSessionKey, resolveSessionFilePath, resolveStorePath, saveSessionStore, updateSessionStore, } from "../config/sessions.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
 import { getQueueSize } from "../process/command-queue.js";
 import { normalizeAgentId, toAgentStoreSessionKey } from "../routing/session-key.js";
 import { defaultRuntime } from "../runtime.js";
+import { escapeRegExp } from "../utils.js";
 import { formatErrorMessage } from "./errors.js";
+import { isWithinActiveHours } from "./heartbeat-active-hours.js";
+import { buildCronEventPrompt, isCronSystemEvent, isExecCompletionEvent, } from "./heartbeat-events-filter.js";
 import { emitHeartbeatEvent, resolveIndicatorType } from "./heartbeat-events.js";
 import { resolveHeartbeatVisibility } from "./heartbeat-visibility.js";
 import { requestHeartbeatNow, setHeartbeatWakeHandler, } from "./heartbeat-wake.js";
 import { deliverOutboundPayloads } from "./outbound/deliver.js";
 import { resolveHeartbeatDeliveryTarget, resolveHeartbeatSenderContext, } from "./outbound/targets.js";
-import { peekSystemEvents } from "./system-events.js";
+import { peekSystemEventEntries } from "./system-events.js";
 const log = createSubsystemLogger("gateway/heartbeat");
 let heartbeatsEnabled = true;
 export function setHeartbeatsEnabled(enabled) {
     heartbeatsEnabled = enabled;
 }
 const DEFAULT_HEARTBEAT_TARGET = "last";
-const ACTIVE_HOURS_TIME_PATTERN = /^([01]\d|2[0-3]|24):([0-5]\d)$/;
 // Prompt used when an async exec has completed and the result should be relayed to the user.
 // This overrides the standard heartbeat prompt to ensure the model responds with the exec result
 // instead of just "HEARTBEAT_OK".
 const EXEC_EVENT_PROMPT = "An async command you ran earlier has completed. The result is shown in the system messages above. " +
     "Please relay the command output to the user in a helpful way. If the command succeeded, share the relevant output. " +
     "If it failed, explain what went wrong.";
-// Prompt used when a scheduled cron job has fired and injected a system event.
-// This overrides the standard heartbeat prompt so the model relays the scheduled
-// reminder instead of responding with "HEARTBEAT_OK".
-const CRON_EVENT_PROMPT = "A scheduled reminder has been triggered. The reminder message is shown in the system messages above. " +
-    "Please relay this reminder to the user in a helpful and friendly way.";
-function resolveActiveHoursTimezone(cfg, raw) {
-    const trimmed = raw?.trim();
-    if (!trimmed || trimmed === "user") {
-        return resolveUserTimezone(cfg.agents?.defaults?.userTimezone);
-    }
-    if (trimmed === "local") {
-        const host = Intl.DateTimeFormat().resolvedOptions().timeZone;
-        return host?.trim() || "UTC";
-    }
-    try {
-        new Intl.DateTimeFormat("en-US", { timeZone: trimmed }).format(new Date());
-        return trimmed;
-    }
-    catch {
-        return resolveUserTimezone(cfg.agents?.defaults?.userTimezone);
-    }
-}
-function parseActiveHoursTime(opts, raw) {
-    if (!raw || !ACTIVE_HOURS_TIME_PATTERN.test(raw)) {
-        return null;
-    }
-    const [hourStr, minuteStr] = raw.split(":");
-    const hour = Number(hourStr);
-    const minute = Number(minuteStr);
-    if (!Number.isFinite(hour) || !Number.isFinite(minute)) {
-        return null;
-    }
-    if (hour === 24) {
-        if (!opts.allow24 || minute !== 0) {
-            return null;
-        }
-        return 24 * 60;
-    }
-    return hour * 60 + minute;
-}
-function resolveMinutesInTimeZone(nowMs, timeZone) {
-    try {
-        const parts = new Intl.DateTimeFormat("en-US", {
-            timeZone,
-            hour: "2-digit",
-            minute: "2-digit",
-            hourCycle: "h23",
-        }).formatToParts(new Date(nowMs));
-        const map = {};
-        for (const part of parts) {
-            if (part.type !== "literal") {
-                map[part.type] = part.value;
-            }
-        }
-        const hour = Number(map.hour);
-        const minute = Number(map.minute);
-        if (!Number.isFinite(hour) || !Number.isFinite(minute)) {
-            return null;
-        }
-        return hour * 60 + minute;
-    }
-    catch {
-        return null;
-    }
-}
-function isWithinActiveHours(cfg, heartbeat, nowMs) {
-    const active = heartbeat?.activeHours;
-    if (!active) {
-        return true;
-    }
-    const startMin = parseActiveHoursTime({ allow24: false }, active.start);
-    const endMin = parseActiveHoursTime({ allow24: true }, active.end);
-    if (startMin === null || endMin === null) {
-        return true;
-    }
-    if (startMin === endMin) {
-        return true;
-    }
-    const timeZone = resolveActiveHoursTimezone(cfg, active.timezone);
-    const currentMin = resolveMinutesInTimeZone(nowMs ?? Date.now(), timeZone);
-    if (currentMin === null) {
-        return true;
-    }
-    if (endMin > startMin) {
-        return currentMin >= startMin && currentMin < endMin;
-    }
-    return currentMin >= startMin || currentMin < endMin;
-}
+export { isCronSystemEvent };
 function hasExplicitHeartbeatAgents(cfg) {
     const list = cfg.agents?.list ?? [];
     return list.some((entry) => Boolean(entry?.heartbeat));
@@ -228,7 +144,7 @@ function resolveHeartbeatAckMaxChars(cfg, heartbeat) {
         cfg.agents?.defaults?.heartbeat?.ackMaxChars ??
         DEFAULT_HEARTBEAT_ACK_MAX_CHARS);
 }
-function resolveHeartbeatSession(cfg, agentId, heartbeat) {
+function resolveHeartbeatSession(cfg, agentId, heartbeat, forcedSessionKey) {
     const sessionCfg = cfg.session;
     const scope = sessionCfg?.scope ?? "per-sender";
     const resolvedAgentId = normalizeAgentId(agentId ?? resolveDefaultAgentId(cfg));
@@ -242,6 +158,30 @@ function resolveHeartbeatSession(cfg, agentId, heartbeat) {
     if (scope === "global") {
         return { sessionKey: mainSessionKey, storePath, store, entry: mainEntry };
     }
+    const forced = forcedSessionKey?.trim();
+    if (forced) {
+        const forcedCandidate = toAgentStoreSessionKey({
+            agentId: resolvedAgentId,
+            requestKey: forced,
+            mainKey: cfg.session?.mainKey,
+        });
+        const forcedCanonical = canonicalizeMainSessionAlias({
+            cfg,
+            agentId: resolvedAgentId,
+            sessionKey: forcedCandidate,
+        });
+        if (forcedCanonical !== "global") {
+            const sessionAgentId = resolveAgentIdFromSessionKey(forcedCanonical);
+            if (sessionAgentId === normalizeAgentId(resolvedAgentId)) {
+                return {
+                    sessionKey: forcedCanonical,
+                    storePath,
+                    store,
+                    entry: store[forcedCanonical],
+                };
+            }
+        }
+    }
     const trimmed = heartbeat?.session?.trim() ?? "";
     if (!trimmed) {
         return { sessionKey: mainSessionKey, storePath, store, entry: mainEntry };
@@ -273,24 +213,6 @@ function resolveHeartbeatSession(cfg, agentId, heartbeat) {
     }
     return { sessionKey: mainSessionKey, storePath, store, entry: mainEntry };
 }
-function resolveHeartbeatReplyPayload(replyResult) {
-    if (!replyResult) {
-        return undefined;
-    }
-    if (!Array.isArray(replyResult)) {
-        return replyResult;
-    }
-    for (let idx = replyResult.length - 1; idx >= 0; idx -= 1) {
-        const payload = replyResult[idx];
-        if (!payload) {
-            continue;
-        }
-        if (payload.text || payload.mediaUrl || (payload.mediaUrls && payload.mediaUrls.length > 0)) {
-            return payload;
-        }
-    }
-    return undefined;
-}
 function resolveHeartbeatReasoningPayloads(replyResult) {
     const payloads = Array.isArray(replyResult) ? replyResult : replyResult ? [replyResult] : [];
     return payloads.filter((payload) => {
@@ -324,8 +246,65 @@ async function restoreHeartbeatUpdatedAt(params) {
         nextStore[sessionKey] = { ...nextEntry, updatedAt: resolvedUpdatedAt };
     });
 }
+/**
+ * Prune heartbeat transcript entries by truncating the file back to a previous size.
+ * This removes the user+assistant turns that were written during a HEARTBEAT_OK run,
+ * preventing context pollution from zero-information exchanges.
+ */
+async function pruneHeartbeatTranscript(params) {
+    const { transcriptPath, preHeartbeatSize } = params;
+    if (!transcriptPath || typeof preHeartbeatSize !== "number" || preHeartbeatSize < 0) {
+        return;
+    }
+    try {
+        const stat = await fs.stat(transcriptPath);
+        // Only truncate if the file has grown during the heartbeat run
+        if (stat.size > preHeartbeatSize) {
+            await fs.truncate(transcriptPath, preHeartbeatSize);
+        }
+    }
+    catch {
+        // File may not exist or may have been removed - ignore errors
+    }
+}
+/**
+ * Get the transcript file path and its current size before a heartbeat run.
+ * Returns undefined values if the session or transcript doesn't exist yet.
+ */
+async function captureTranscriptState(params) {
+    const { storePath, sessionKey, agentId } = params;
+    try {
+        const store = loadSessionStore(storePath);
+        const entry = store[sessionKey];
+        if (!entry?.sessionId) {
+            return {};
+        }
+        const transcriptPath = resolveSessionFilePath(entry.sessionId, entry, {
+            agentId,
+            sessionsDir: path.dirname(storePath),
+        });
+        const stat = await fs.stat(transcriptPath);
+        return { transcriptPath, preHeartbeatSize: stat.size };
+    }
+    catch {
+        // Session or transcript doesn't exist yet - nothing to prune
+        return {};
+    }
+}
+function stripLeadingHeartbeatResponsePrefix(text, responsePrefix) {
+    const normalizedPrefix = responsePrefix?.trim();
+    if (!normalizedPrefix) {
+        return text;
+    }
+    // Require a boundary after the configured prefix so short prefixes like "Hi"
+    // do not strip the beginning of normal words like "History".
+    const prefixPattern = new RegExp(`^${escapeRegExp(normalizedPrefix)}(?=$|\\s|[\\p{P}\\p{S}])\\s*`, "iu");
+    return text.replace(prefixPattern, "");
+}
 function normalizeHeartbeatReply(payload, responsePrefix, ackMaxChars) {
-    const stripped = stripHeartbeatToken(payload.text, {
+    const rawText = typeof payload.text === "string" ? payload.text : "";
+    const textForStrip = stripLeadingHeartbeatResponsePrefix(rawText, responsePrefix);
+    const stripped = stripHeartbeatToken(textForStrip, {
         mode: "heartbeat",
         maxAckChars: ackMaxChars,
     });
@@ -366,17 +345,19 @@ export async function runHeartbeatOnce(opts) {
     }
     // 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).
-    // EXCEPTION: Don't skip for exec events or cron events - they have pending system events
-    // to process regardless of HEARTBEAT.md content.
+    // EXCEPTION: Don't skip for exec events, cron events, or explicit wake requests -
+    // they have pending system events to process regardless of HEARTBEAT.md content.
     const isExecEventReason = opts.reason === "exec-event";
     const isCronEventReason = Boolean(opts.reason?.startsWith("cron:"));
+    const isWakeReason = opts.reason === "wake" || Boolean(opts.reason?.startsWith("hook:"));
     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) &&
             !isExecEventReason &&
-            !isCronEventReason) {
+            !isCronEventReason &&
+            !isWakeReason) {
             emitHeartbeatEvent({
                 status: "skipped",
                 reason: "empty-heartbeat-file",
@@ -389,7 +370,7 @@ export async function runHeartbeatOnce(opts) {
         // 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 { entry, sessionKey, storePath } = resolveHeartbeatSession(cfg, agentId, heartbeat, opts.sessionKey);
     const previousUpdatedAt = entry?.updatedAt;
     const delivery = resolveHeartbeatDeliveryTarget({ cfg, entry, heartbeat });
     const heartbeatAccountId = heartbeat?.accountId?.trim();
@@ -422,17 +403,25 @@ export async function runHeartbeatOnce(opts) {
     // If so, use a specialized prompt that instructs the model to relay the result
     // instead of the standard heartbeat prompt with "reply HEARTBEAT_OK".
     const isExecEvent = opts.reason === "exec-event";
-    const isCronEvent = Boolean(opts.reason?.startsWith("cron:"));
-    const pendingEvents = isExecEvent || isCronEvent ? peekSystemEvents(sessionKey) : [];
-    const hasExecCompletion = pendingEvents.some((evt) => evt.includes("Exec finished"));
-    const hasCronEvents = isCronEvent && pendingEvents.length > 0;
+    const pendingEventEntries = peekSystemEventEntries(sessionKey);
+    const hasTaggedCronEvents = pendingEventEntries.some((event) => event.contextKey?.startsWith("cron:"));
+    const shouldInspectPendingEvents = isExecEvent || isCronEventReason || hasTaggedCronEvents;
+    const pendingEvents = shouldInspectPendingEvents
+        ? pendingEventEntries.map((event) => event.text)
+        : [];
+    const cronEvents = pendingEventEntries
+        .filter((event) => (isCronEventReason || event.contextKey?.startsWith("cron:")) &&
+        isCronSystemEvent(event.text))
+        .map((event) => event.text);
+    const hasExecCompletion = pendingEvents.some(isExecCompletionEvent);
+    const hasCronEvents = cronEvents.length > 0;
     const prompt = hasExecCompletion
         ? EXEC_EVENT_PROMPT
         : hasCronEvents
-            ? CRON_EVENT_PROMPT
+            ? buildCronEventPrompt(cronEvents)
             : resolveHeartbeatPrompt(cfg, heartbeat);
     const ctx = {
-        Body: prompt,
+        Body: appendCronStyleCurrentTimeLine(prompt, cfg, startedAt),
         From: sender,
         To: sender,
         Provider: hasExecCompletion ? "exec-event" : hasCronEvents ? "cron-event" : "heartbeat",
@@ -471,12 +460,24 @@ export async function runHeartbeatOnce(opts) {
             to: delivery.to,
             accountId: delivery.accountId,
             payloads: [{ text: heartbeatOkText }],
+            agentId,
             deps: opts.deps,
         });
         return true;
     };
     try {
-        const replyResult = await getReplyFromConfig(ctx, { isHeartbeat: true }, cfg);
+        // Capture transcript state before the heartbeat run so we can prune if HEARTBEAT_OK
+        const transcriptState = await captureTranscriptState({
+            storePath,
+            sessionKey,
+            agentId,
+        });
+        const heartbeatModelOverride = heartbeat?.model?.trim() || undefined;
+        const suppressToolErrorWarnings = heartbeat?.suppressToolErrorWarnings === true;
+        const replyOpts = heartbeatModelOverride
+            ? { isHeartbeat: true, heartbeatModelOverride, suppressToolErrorWarnings }
+            : { isHeartbeat: true, suppressToolErrorWarnings };
+        const replyResult = await getReplyFromConfig(ctx, replyOpts, cfg);
         const replyPayload = resolveHeartbeatReplyPayload(replyResult);
         const includeReasoning = heartbeat?.includeReasoning === true;
         const reasoningPayloads = includeReasoning
@@ -489,6 +490,8 @@ export async function runHeartbeatOnce(opts) {
                 sessionKey,
                 updatedAt: previousUpdatedAt,
             });
+            // Prune the transcript to remove HEARTBEAT_OK turns
+            await pruneHeartbeatTranscript(transcriptState);
             const okSent = await maybeSendHeartbeatOk();
             emitHeartbeatEvent({
                 status: "ok-empty",
@@ -521,6 +524,8 @@ export async function runHeartbeatOnce(opts) {
                 sessionKey,
                 updatedAt: previousUpdatedAt,
             });
+            // Prune the transcript to remove HEARTBEAT_OK turns
+            await pruneHeartbeatTranscript(transcriptState);
             const okSent = await maybeSendHeartbeatOk();
             emitHeartbeatEvent({
                 status: "ok-token",
@@ -550,6 +555,8 @@ export async function runHeartbeatOnce(opts) {
                 sessionKey,
                 updatedAt: previousUpdatedAt,
             });
+            // Prune the transcript to remove duplicate heartbeat turns
+            await pruneHeartbeatTranscript(transcriptState);
             emitHeartbeatEvent({
                 status: "skipped",
                 reason: "duplicate",
@@ -627,6 +634,7 @@ export async function runHeartbeatOnce(opts) {
             channel: delivery.channel,
             to: delivery.to,
             accountId: deliveryAccountId,
+            agentId,
             payloads: [
                 ...reasoningPayloads,
                 ...(shouldSkipMain
@@ -699,6 +707,10 @@ export function startHeartbeatRunner(opts) {
         }
         return now + intervalMs;
     };
+    const advanceAgentSchedule = (agent, now) => {
+        agent.lastRunMs = now;
+        agent.nextDueMs = now + agent.intervalMs;
+    };
     const scheduleNext = () => {
         if (state.stopped) {
             return;
@@ -722,6 +734,7 @@ export function startHeartbeatRunner(opts) {
         }
         const delay = Math.max(0, nextDue - now);
         state.timer = setTimeout(() => {
+            state.timer = null;
             requestHeartbeatNow({ reason: "interval", coalesceMs: 0 });
         }, delay);
         state.timer.unref?.();
@@ -774,6 +787,12 @@ export function startHeartbeatRunner(opts) {
         scheduleNext();
     };
     const run = async (params) => {
+        if (state.stopped) {
+            return {
+                status: "skipped",
+                reason: "disabled",
+            };
+        }
         if (!heartbeatsEnabled) {
             return {
                 status: "skipped",
@@ -787,27 +806,73 @@ export function startHeartbeatRunner(opts) {
             };
         }
         const reason = params?.reason;
+        const requestedAgentId = params?.agentId ? normalizeAgentId(params.agentId) : undefined;
+        const requestedSessionKey = params?.sessionKey?.trim() || undefined;
         const isInterval = reason === "interval";
         const startedAt = Date.now();
         const now = startedAt;
         let ran = false;
+        if (requestedSessionKey || requestedAgentId) {
+            const targetAgentId = requestedAgentId ?? resolveAgentIdFromSessionKey(requestedSessionKey);
+            const targetAgent = state.agents.get(targetAgentId);
+            if (!targetAgent) {
+                scheduleNext();
+                return { status: "skipped", reason: "disabled" };
+            }
+            try {
+                const res = await runOnce({
+                    cfg: state.cfg,
+                    agentId: targetAgent.agentId,
+                    heartbeat: targetAgent.heartbeat,
+                    reason,
+                    sessionKey: requestedSessionKey,
+                    deps: { runtime: state.runtime },
+                });
+                if (res.status !== "skipped" || res.reason !== "disabled") {
+                    advanceAgentSchedule(targetAgent, now);
+                }
+                scheduleNext();
+                return res.status === "ran" ? { status: "ran", durationMs: Date.now() - startedAt } : res;
+            }
+            catch (err) {
+                const errMsg = formatErrorMessage(err);
+                log.error(`heartbeat runner: targeted runOnce threw unexpectedly: ${errMsg}`, {
+                    error: errMsg,
+                });
+                advanceAgentSchedule(targetAgent, now);
+                scheduleNext();
+                return { status: "failed", reason: errMsg };
+            }
+        }
         for (const agent of state.agents.values()) {
             if (isInterval && now < agent.nextDueMs) {
                 continue;
             }
-            const res = await runOnce({
-                cfg: state.cfg,
-                agentId: agent.agentId,
-                heartbeat: agent.heartbeat,
-                reason,
-                deps: { runtime: state.runtime },
-            });
+            let res;
+            try {
+                res = await runOnce({
+                    cfg: state.cfg,
+                    agentId: agent.agentId,
+                    heartbeat: agent.heartbeat,
+                    reason,
+                    deps: { runtime: state.runtime },
+                });
+            }
+            catch (err) {
+                // If runOnce throws (e.g. during session compaction), we must still
+                // advance the timer and call scheduleNext so heartbeats keep firing.
+                const errMsg = formatErrorMessage(err);
+                log.error(`heartbeat runner: runOnce threw unexpectedly: ${errMsg}`, { error: errMsg });
+                advanceAgentSchedule(agent, now);
+                continue;
+            }
             if (res.status === "skipped" && res.reason === "requests-in-flight") {
+                advanceAgentSchedule(agent, now);
+                scheduleNext();
                 return res;
             }
             if (res.status !== "skipped" || res.reason !== "disabled") {
-                agent.lastRunMs = now;
-                agent.nextDueMs = now + agent.intervalMs;
+                advanceAgentSchedule(agent, now);
             }
             if (res.status === "ran") {
                 ran = true;
@@ -819,11 +884,19 @@ export function startHeartbeatRunner(opts) {
         }
         return { status: "skipped", reason: isInterval ? "not-due" : "disabled" };
     };
-    setHeartbeatWakeHandler(async (params) => run({ reason: params.reason }));
+    const wakeHandler = async (params) => run({
+        reason: params.reason,
+        agentId: params.agentId,
+        sessionKey: params.sessionKey,
+    });
+    const disposeWakeHandler = setHeartbeatWakeHandler(wakeHandler);
     updateConfig(state.cfg);
     const cleanup = () => {
+        if (state.stopped) {
+            return;
+        }
         state.stopped = true;
-        setHeartbeatWakeHandler(null);
+        disposeWakeHandler();
         if (state.timer) {
             clearTimeout(state.timer);
         }