@poolzin/pool-bot 2026.2.23 → 2026.2.25

package/dist/infra/exec-approvals-analysis.js

@@ -1,20 +1,8 @@
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import { splitShellArgs } from "../utils/shell-argv.js";
-export const DEFAULT_SAFE_BINS = ["jq", "grep", "cut", "sort", "uniq", "head", "tail", "tr", "wc"];
-function expandHome(value) {
-    if (!value) {
-        return value;
-    }
-    if (value === "~") {
-        return os.homedir();
-    }
-    if (value.startsWith("~/")) {
-        return path.join(os.homedir(), value.slice(2));
-    }
-    return value;
-}
+import { expandHomePrefix } from "./home-dir.js";
+export const DEFAULT_SAFE_BINS = ["jq", "cut", "uniq", "head", "tail", "tr", "wc"];
 function isExecutableFile(filePath) {
     try {
         const stat = fs.statSync(filePath);
@@ -47,7 +35,7 @@ function parseFirstToken(command) {
     return match ? match[0] : null;
 }
 function resolveExecutablePath(rawExecutable, cwd, env) {
-    const expanded = rawExecutable.startsWith("~") ? expandHome(rawExecutable) : rawExecutable;
+    const expanded = rawExecutable.startsWith("~") ? expandHomePrefix(rawExecutable) : rawExecutable;
     if (expanded.includes("/") || expanded.includes("\\")) {
         if (path.isAbsolute(expanded)) {
             return isExecutableFile(expanded) ? expanded : undefined;
@@ -145,7 +133,7 @@ function matchesPattern(pattern, target) {
     if (!trimmed) {
         return false;
     }
-    const expanded = trimmed.startsWith("~") ? expandHome(trimmed) : trimmed;
+    const expanded = trimmed.startsWith("~") ? expandHomePrefix(trimmed) : trimmed;
     const hasWildcard = /[*?]/.test(expanded);
     let normalizedPattern = expanded;
     let normalizedTarget = target;
@@ -169,7 +157,7 @@ export function resolveAllowlistCandidatePath(resolution, cwd) {
     if (!raw) {
         return undefined;
     }
-    const expanded = raw.startsWith("~") ? expandHome(raw) : raw;
+    const expanded = raw.startsWith("~") ? expandHomePrefix(raw) : raw;
     if (!expanded.includes("/") && !expanded.includes("\\")) {
         return undefined;
     }
@@ -199,6 +187,45 @@ export function matchAllowlist(entries, resolution) {
     }
     return null;
 }
+/**
+ * Tokenizes a single argv entry into a normalized option/positional model.
+ * Consumers can share this model to keep argv parsing behavior consistent.
+ */
+export function parseExecArgvToken(raw) {
+    if (!raw) {
+        return { kind: "empty", raw };
+    }
+    if (raw === "--") {
+        return { kind: "terminator", raw };
+    }
+    if (raw === "-") {
+        return { kind: "stdin", raw };
+    }
+    if (!raw.startsWith("-")) {
+        return { kind: "positional", raw };
+    }
+    if (raw.startsWith("--")) {
+        const eqIndex = raw.indexOf("=");
+        if (eqIndex > 0) {
+            return {
+                kind: "option",
+                raw,
+                style: "long",
+                flag: raw.slice(0, eqIndex),
+                inlineValue: raw.slice(eqIndex + 1),
+            };
+        }
+        return { kind: "option", raw, style: "long", flag: raw };
+    }
+    const cluster = raw.slice(1);
+    return {
+        kind: "option",
+        raw,
+        style: "short-cluster",
+        cluster,
+        flags: cluster.split("").map((entry) => `-${entry}`),
+    };
+}
 const DISALLOWED_PIPELINE_TOKENS = new Set([">", "<", "`", "\n", "\r", "(", ")"]);
 const DOUBLE_QUOTE_ESCAPES = new Set(["\\", '"', "$", "`", "\n", "\r"]);
 const WINDOWS_UNSUPPORTED_TOKENS = new Set([

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

@@ -0,0 +1,269 @@
+import { parseExecArgvToken } from "./exec-approvals-analysis.js";
+function isPathLikeToken(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return false;
+    }
+    if (trimmed === "-") {
+        return false;
+    }
+    if (trimmed.startsWith("./") || trimmed.startsWith("../") || trimmed.startsWith("~")) {
+        return true;
+    }
+    if (trimmed.startsWith("/")) {
+        return true;
+    }
+    return /^[A-Za-z]:[\\/]/.test(trimmed);
+}
+function hasGlobToken(value) {
+    // Safe bins are stdin-only; globbing is both surprising and a historical bypass vector.
+    // Note: we still harden execution-time expansion separately.
+    return /[*?[\]]/.test(value);
+}
+const NO_FLAGS = new Set();
+const toFlagSet = (flags) => {
+    if (!flags || flags.length === 0) {
+        return NO_FLAGS;
+    }
+    return new Set(flags);
+};
+function compileSafeBinProfile(fixture) {
+    return {
+        minPositional: fixture.minPositional,
+        maxPositional: fixture.maxPositional,
+        valueFlags: toFlagSet(fixture.valueFlags),
+        blockedFlags: toFlagSet(fixture.blockedFlags),
+    };
+}
+function compileSafeBinProfiles(fixtures) {
+    return Object.fromEntries(Object.entries(fixtures).map(([name, fixture]) => [name, compileSafeBinProfile(fixture)]));
+}
+export const SAFE_BIN_GENERIC_PROFILE_FIXTURE = {};
+export const SAFE_BIN_PROFILE_FIXTURES = {
+    jq: {
+        maxPositional: 1,
+        valueFlags: [
+            "--arg",
+            "--argjson",
+            "--argstr",
+            "--argfile",
+            "--rawfile",
+            "--slurpfile",
+            "--from-file",
+            "--library-path",
+            "-L",
+            "-f",
+        ],
+        blockedFlags: [
+            "--argfile",
+            "--rawfile",
+            "--slurpfile",
+            "--from-file",
+            "--library-path",
+            "-L",
+            "-f",
+        ],
+    },
+    grep: {
+        maxPositional: 1,
+        valueFlags: [
+            "--regexp",
+            "--file",
+            "--max-count",
+            "--after-context",
+            "--before-context",
+            "--context",
+            "--devices",
+            "--directories",
+            "--binary-files",
+            "--exclude",
+            "--exclude-from",
+            "--include",
+            "--label",
+            "-e",
+            "-f",
+            "-m",
+            "-A",
+            "-B",
+            "-C",
+            "-D",
+            "-d",
+        ],
+        blockedFlags: [
+            "--file",
+            "--exclude-from",
+            "--dereference-recursive",
+            "--directories",
+            "--recursive",
+            "-f",
+            "-d",
+            "-r",
+            "-R",
+        ],
+    },
+    cut: {
+        maxPositional: 0,
+        valueFlags: [
+            "--bytes",
+            "--characters",
+            "--fields",
+            "--delimiter",
+            "--output-delimiter",
+            "-b",
+            "-c",
+            "-f",
+            "-d",
+        ],
+    },
+    sort: {
+        maxPositional: 0,
+        valueFlags: [
+            "--key",
+            "--field-separator",
+            "--buffer-size",
+            "--temporary-directory",
+            "--compress-program",
+            "--parallel",
+            "--batch-size",
+            "--random-source",
+            "--files0-from",
+            "--output",
+            "-k",
+            "-t",
+            "-S",
+            "-T",
+            "-o",
+        ],
+        blockedFlags: ["--files0-from", "--output", "-o"],
+    },
+    uniq: {
+        maxPositional: 0,
+        valueFlags: ["--skip-fields", "--skip-chars", "--check-chars", "--group", "-f", "-s", "-w"],
+    },
+    head: {
+        maxPositional: 0,
+        valueFlags: ["--lines", "--bytes", "-n", "-c"],
+    },
+    tail: {
+        maxPositional: 0,
+        valueFlags: [
+            "--lines",
+            "--bytes",
+            "--sleep-interval",
+            "--max-unchanged-stats",
+            "--pid",
+            "-n",
+            "-c",
+        ],
+    },
+    tr: {
+        minPositional: 1,
+        maxPositional: 2,
+    },
+    wc: {
+        maxPositional: 0,
+        valueFlags: ["--files0-from"],
+        blockedFlags: ["--files0-from"],
+    },
+};
+export const SAFE_BIN_GENERIC_PROFILE = compileSafeBinProfile(SAFE_BIN_GENERIC_PROFILE_FIXTURE);
+export const SAFE_BIN_PROFILES = compileSafeBinProfiles(SAFE_BIN_PROFILE_FIXTURES);
+function isSafeLiteralToken(value) {
+    if (!value || value === "-") {
+        return true;
+    }
+    return !hasGlobToken(value) && !isPathLikeToken(value);
+}
+function isInvalidValueToken(value) {
+    return !value || !isSafeLiteralToken(value);
+}
+function consumeLongOptionToken(args, index, flag, inlineValue, valueFlags, blockedFlags) {
+    if (blockedFlags.has(flag)) {
+        return -1;
+    }
+    if (inlineValue !== undefined) {
+        return isSafeLiteralToken(inlineValue) ? index + 1 : -1;
+    }
+    if (!valueFlags.has(flag)) {
+        return index + 1;
+    }
+    return isInvalidValueToken(args[index + 1]) ? -1 : index + 2;
+}
+function consumeShortOptionClusterToken(args, index, raw, cluster, flags, valueFlags, blockedFlags) {
+    for (let j = 0; j < flags.length; j += 1) {
+        const flag = flags[j];
+        if (blockedFlags.has(flag)) {
+            return -1;
+        }
+        if (!valueFlags.has(flag)) {
+            continue;
+        }
+        const inlineValue = cluster.slice(j + 1);
+        if (inlineValue) {
+            return isSafeLiteralToken(inlineValue) ? index + 1 : -1;
+        }
+        return isInvalidValueToken(args[index + 1]) ? -1 : index + 2;
+    }
+    return hasGlobToken(raw) ? -1 : index + 1;
+}
+function consumePositionalToken(token, positional) {
+    if (!isSafeLiteralToken(token)) {
+        return false;
+    }
+    positional.push(token);
+    return true;
+}
+function validatePositionalCount(positional, profile) {
+    const minPositional = profile.minPositional ?? 0;
+    if (positional.length < minPositional) {
+        return false;
+    }
+    return typeof profile.maxPositional !== "number" || positional.length <= profile.maxPositional;
+}
+export function validateSafeBinArgv(args, profile) {
+    const valueFlags = profile.valueFlags ?? NO_FLAGS;
+    const blockedFlags = profile.blockedFlags ?? NO_FLAGS;
+    const positional = [];
+    let i = 0;
+    while (i < args.length) {
+        const rawToken = args[i] ?? "";
+        const token = parseExecArgvToken(rawToken);
+        if (token.kind === "empty" || token.kind === "stdin") {
+            i += 1;
+            continue;
+        }
+        if (token.kind === "terminator") {
+            for (let j = i + 1; j < args.length; j += 1) {
+                const rest = args[j];
+                if (!rest || rest === "-") {
+                    continue;
+                }
+                if (!consumePositionalToken(rest, positional)) {
+                    return false;
+                }
+            }
+            break;
+        }
+        if (token.kind === "positional") {
+            if (!consumePositionalToken(token.raw, positional)) {
+                return false;
+            }
+            i += 1;
+            continue;
+        }
+        if (token.style === "long") {
+            const nextIndex = consumeLongOptionToken(args, i, token.flag, token.inlineValue, valueFlags, blockedFlags);
+            if (nextIndex < 0) {
+                return false;
+            }
+            i = nextIndex;
+            continue;
+        }
+        const nextIndex = consumeShortOptionClusterToken(args, i, token.raw, token.cluster, token.flags, valueFlags, blockedFlags);
+        if (nextIndex < 0) {
+            return false;
+        }
+        i = nextIndex;
+    }
+    return validatePositionalCount(positional, profile);
+}

package/dist/infra/fixed-window-rate-limit.js

@@ -0,0 +1,33 @@
+export function createFixedWindowRateLimiter(params) {
+    const maxRequests = Math.max(1, Math.floor(params.maxRequests));
+    const windowMs = Math.max(1, Math.floor(params.windowMs));
+    const now = params.now ?? Date.now;
+    let count = 0;
+    let windowStartMs = 0;
+    return {
+        consume() {
+            const nowMs = now();
+            if (nowMs - windowStartMs >= windowMs) {
+                windowStartMs = nowMs;
+                count = 0;
+            }
+            if (count >= maxRequests) {
+                return {
+                    allowed: false,
+                    retryAfterMs: Math.max(0, windowStartMs + windowMs - nowMs),
+                    remaining: 0,
+                };
+            }
+            count += 1;
+            return {
+                allowed: true,
+                retryAfterMs: 0,
+                remaining: Math.max(0, maxRequests - count),
+            };
+        },
+        reset() {
+            count = 0;
+            windowStartMs = 0;
+        },
+    };
+}

package/dist/infra/git-root.js

@@ -0,0 +1,61 @@
+import fs from "node:fs";
+import path from "node:path";
+export const DEFAULT_GIT_DISCOVERY_MAX_DEPTH = 12;
+function walkUpFrom(startDir, opts, resolveAtDir) {
+    let current = path.resolve(startDir);
+    const maxDepth = opts.maxDepth ?? DEFAULT_GIT_DISCOVERY_MAX_DEPTH;
+    for (let i = 0; i < maxDepth; i += 1) {
+        const resolved = resolveAtDir(current);
+        if (resolved !== null && resolved !== undefined) {
+            return resolved;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return null;
+}
+function hasGitMarker(repoRoot) {
+    const gitPath = path.join(repoRoot, ".git");
+    try {
+        const stat = fs.statSync(gitPath);
+        return stat.isDirectory() || stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function findGitRoot(startDir, opts = {}) {
+    // A `.git` file counts as a repo marker even if it is not a valid gitdir pointer.
+    return walkUpFrom(startDir, opts, (repoRoot) => (hasGitMarker(repoRoot) ? repoRoot : null));
+}
+function resolveGitDirFromMarker(repoRoot) {
+    const gitPath = path.join(repoRoot, ".git");
+    try {
+        const stat = fs.statSync(gitPath);
+        if (stat.isDirectory()) {
+            return gitPath;
+        }
+        if (!stat.isFile()) {
+            return null;
+        }
+        const raw = fs.readFileSync(gitPath, "utf-8");
+        const match = raw.match(/gitdir:\s*(.+)/i);
+        if (!match?.[1]) {
+            return null;
+        }
+        return path.resolve(repoRoot, match[1].trim());
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveGitHeadPath(startDir, opts = {}) {
+    // Stricter than findGitRoot: keep walking until a resolvable git dir is found.
+    return walkUpFrom(startDir, opts, (repoRoot) => {
+        const gitDir = resolveGitDirFromMarker(repoRoot);
+        return gitDir ? path.join(gitDir, "HEAD") : null;
+    });
+}

package/dist/infra/heartbeat-active-hours.js

@@ -1,5 +1,5 @@
 import { resolveUserTimezone } from "../agents/date-time.js";
-const ACTIVE_HOURS_TIME_PATTERN = /^([01]\d|2[0-3]|24):([0-5]\d)$/;
+const ACTIVE_HOURS_TIME_PATTERN = /^(?:([01]\d|2[0-3]):([0-5]\d)|24:00)$/;
 function resolveActiveHoursTimezone(cfg, raw) {
     const trimmed = raw?.trim();
     if (!trimmed || trimmed === "user") {
@@ -71,7 +71,7 @@ export function isWithinActiveHours(cfg, heartbeat, nowMs) {
         return true;
     }
     if (startMin === endMin) {
-        return true;
+        return false;
     }
     const timeZone = resolveActiveHoursTimezone(cfg, active.timezone);
     const currentMin = resolveMinutesInTimeZone(nowMs ?? Date.now(), timeZone);

package/dist/infra/heartbeat-reason.js

@@ -0,0 +1,40 @@
+function trimReason(reason) {
+    return typeof reason === "string" ? reason.trim() : "";
+}
+export function normalizeHeartbeatWakeReason(reason) {
+    const trimmed = trimReason(reason);
+    return trimmed.length > 0 ? trimmed : "requested";
+}
+export function resolveHeartbeatReasonKind(reason) {
+    const trimmed = trimReason(reason);
+    if (trimmed === "retry") {
+        return "retry";
+    }
+    if (trimmed === "interval") {
+        return "interval";
+    }
+    if (trimmed === "manual") {
+        return "manual";
+    }
+    if (trimmed === "exec-event") {
+        return "exec-event";
+    }
+    if (trimmed === "wake") {
+        return "wake";
+    }
+    if (trimmed.startsWith("cron:")) {
+        return "cron";
+    }
+    if (trimmed.startsWith("hook:")) {
+        return "hook";
+    }
+    return "other";
+}
+export function isHeartbeatEventDrivenReason(reason) {
+    const kind = resolveHeartbeatReasonKind(reason);
+    return kind === "exec-event" || kind === "cron" || kind === "wake" || kind === "hook";
+}
+export function isHeartbeatActionWakeReason(reason) {
+    const kind = resolveHeartbeatReasonKind(reason);
+    return kind === "manual" || kind === "exec-event" || kind === "hook";
+}

package/dist/infra/heartbeat-runner.js

@@ -17,10 +17,11 @@ 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 { formatErrorMessage, hasErrnoCode } 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 { resolveHeartbeatReasonKind } from "./heartbeat-reason.js";
 import { resolveHeartbeatVisibility } from "./heartbeat-visibility.js";
 import { requestHeartbeatNow, setHeartbeatWakeHandler, } from "./heartbeat-wake.js";
 import { deliverOutboundPayloads } from "./outbound/deliver.js";
@@ -322,6 +323,56 @@ function normalizeHeartbeatReply(payload, responsePrefix, ackMaxChars) {
     }
     return { shouldSkip: false, text: finalText, hasMedia };
 }
+function resolveHeartbeatReasonFlags(reason) {
+    const reasonKind = resolveHeartbeatReasonKind(reason);
+    return {
+        isExecEventReason: reasonKind === "exec-event",
+        isCronEventReason: reasonKind === "cron",
+        isWakeReason: reasonKind === "wake" || reasonKind === "hook",
+    };
+}
+async function resolveHeartbeatPreflight(params) {
+    const reasonFlags = resolveHeartbeatReasonFlags(params.reason);
+    const session = resolveHeartbeatSession(params.cfg, params.agentId, params.heartbeat, params.forcedSessionKey);
+    const pendingEventEntries = peekSystemEventEntries(session.sessionKey);
+    const hasTaggedCronEvents = pendingEventEntries.some((event) => event.contextKey?.startsWith("cron:"));
+    const shouldInspectPendingEvents = reasonFlags.isExecEventReason || reasonFlags.isCronEventReason || hasTaggedCronEvents;
+    const shouldBypassFileGates = reasonFlags.isExecEventReason ||
+        reasonFlags.isCronEventReason ||
+        reasonFlags.isWakeReason ||
+        hasTaggedCronEvents;
+    const basePreflight = {
+        ...reasonFlags,
+        session,
+        pendingEventEntries,
+        hasTaggedCronEvents,
+        shouldInspectPendingEvents,
+    };
+    if (shouldBypassFileGates) {
+        return basePreflight;
+    }
+    const workspaceDir = resolveAgentWorkspaceDir(params.cfg, params.agentId);
+    const heartbeatFilePath = path.join(workspaceDir, DEFAULT_HEARTBEAT_FILENAME);
+    try {
+        const heartbeatFileContent = await fs.readFile(heartbeatFilePath, "utf-8");
+        if (isHeartbeatContentEffectivelyEmpty(heartbeatFileContent)) {
+            return {
+                ...basePreflight,
+                skipReason: "empty-heartbeat-file",
+            };
+        }
+    }
+    catch (err) {
+        if (hasErrnoCode(err, "ENOENT")) {
+            // Missing HEARTBEAT.md is intentional in some setups (for example, when
+            // heartbeat instructions live outside the file), so keep the run active.
+            // The heartbeat prompt already says "if it exists".
+            return basePreflight;
+        }
+        // For other read errors, proceed with heartbeat as before.
+    }
+    return basePreflight;
+}
 export async function runHeartbeatOnce(opts) {
     const cfg = opts.cfg ?? loadConfig();
     const agentId = normalizeAgentId(opts.agentId ?? resolveDefaultAgentId(cfg));
@@ -343,34 +394,24 @@ export async function runHeartbeatOnce(opts) {
     if (queueSize > 0) {
         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).
-    // 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 &&
-            !isWakeReason) {
-            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.
+    // Preflight centralizes trigger classification, event inspection, and HEARTBEAT.md gating.
+    const preflight = await resolveHeartbeatPreflight({
+        cfg,
+        agentId,
+        heartbeat,
+        forcedSessionKey: opts.sessionKey,
+        reason: opts.reason,
+    });
+    if (preflight.skipReason) {
+        emitHeartbeatEvent({
+            status: "skipped",
+            reason: preflight.skipReason,
+            durationMs: Date.now() - startedAt,
+        });
+        return { status: "skipped", reason: preflight.skipReason };
     }
-    const { entry, sessionKey, storePath } = resolveHeartbeatSession(cfg, agentId, heartbeat, opts.sessionKey);
+    const { entry, sessionKey, storePath } = preflight.session;
+    const { isCronEventReason, pendingEventEntries } = preflight;
     const previousUpdatedAt = entry?.updatedAt;
     const delivery = resolveHeartbeatDeliveryTarget({ cfg, entry, heartbeat });
     const heartbeatAccountId = heartbeat?.accountId?.trim();
@@ -402,10 +443,7 @@ export async function runHeartbeatOnce(opts) {
     // Check if this is an exec event or cron event with pending system events.
     // 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 pendingEventEntries = peekSystemEventEntries(sessionKey);
-    const hasTaggedCronEvents = pendingEventEntries.some((event) => event.contextKey?.startsWith("cron:"));
-    const shouldInspectPendingEvents = isExecEvent || isCronEventReason || hasTaggedCronEvents;
+    const shouldInspectPendingEvents = preflight.shouldInspectPendingEvents;
     const pendingEvents = shouldInspectPendingEvents
         ? pendingEventEntries.map((event) => event.text)
         : [];
@@ -459,6 +497,7 @@ export async function runHeartbeatOnce(opts) {
             channel: delivery.channel,
             to: delivery.to,
             accountId: delivery.accountId,
+            threadId: delivery.threadId,
             payloads: [{ text: heartbeatOkText }],
             agentId,
             deps: opts.deps,
@@ -635,6 +674,7 @@ export async function runHeartbeatOnce(opts) {
             to: delivery.to,
             accountId: deliveryAccountId,
             agentId,
+            threadId: delivery.threadId,
             payloads: [
                 ...reasoningPayloads,
                 ...(shouldSkipMain