bopodev-api 0.1.27 → 0.1.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bopodev-api",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "license": "MIT",
   "type": "module",
   "files": [
@@ -17,9 +17,9 @@
     "nanoid": "^5.1.5",
     "ws": "^8.19.0",
     "zod": "^4.1.5",
-    "bopodev-contracts": "0.1.27",
-    "bopodev-agent-sdk": "0.1.27",
-    "bopodev-db": "0.1.27"
+    "bopodev-agent-sdk": "0.1.28",
+    "bopodev-db": "0.1.28",
+    "bopodev-contracts": "0.1.28"
   },
   "devDependencies": {
     "@types/cors": "^2.8.19",

package/src/app.ts

@@ -1,8 +1,7 @@
 import cors from "cors";
 import express from "express";
 import type { NextFunction, Request, Response } from "express";
-import { sql } from "drizzle-orm";
-import { RepositoryValidationError } from "bopodev-db";
+import { RepositoryValidationError, sql } from "bopodev-db";
 import { nanoid } from "nanoid";
 import type { AppContext } from "./context";
 import { createAgentsRouter } from "./routes/agents";

package/src/lib/drainable-work.ts

@@ -0,0 +1,36 @@
+export type DrainableWorkTracker = {
+  beginShutdown: () => void;
+  isShuttingDown: () => boolean;
+  track: <T>(promise: Promise<T>) => Promise<T>;
+  drain: () => Promise<void>;
+  resetForTests: () => void;
+};
+
+export function createDrainableWorkTracker(): DrainableWorkTracker {
+  let shuttingDown = false;
+  const pending = new Set<Promise<unknown>>();
+
+  return {
+    beginShutdown() {
+      shuttingDown = true;
+    },
+    isShuttingDown() {
+      return shuttingDown;
+    },
+    track<T>(promise: Promise<T>) {
+      let tracked: Promise<T>;
+      tracked = promise.finally(() => {
+        pending.delete(tracked);
+      });
+      pending.add(tracked);
+      return tracked;
+    },
+    async drain() {
+      await Promise.allSettled([...pending]);
+    },
+    resetForTests() {
+      shuttingDown = false;
+      pending.clear();
+    }
+  };
+}

package/src/lib/workspace-policy.ts

@@ -1,6 +1,5 @@
-import { and, eq, inArray } from "drizzle-orm";
 import type { BopoDb } from "bopodev-db";
-import { projectWorkspaces, projects } from "bopodev-db";
+import { and, eq, inArray, projectWorkspaces, projects } from "bopodev-db";
 import {
   assertPathInsideCompanyWorkspaceRoot,
   isInsidePath,

package/src/realtime/office-space.ts

@@ -1,9 +1,11 @@
-import { and, desc, eq } from "drizzle-orm";
 import type { OfficeOccupant, RealtimeEventEnvelope, RealtimeMessage } from "bopodev-contracts";
 import { AGENT_ROLE_LABELS, AgentRoleKeySchema } from "bopodev-contracts";
 import {
+  and,
   agents,
   approvalRequests,
+  desc,
+  eq,
   getApprovalRequest,
   heartbeatRuns,
   issues,

package/src/routes/heartbeats.ts

@@ -1,7 +1,6 @@
 import { Router } from "express";
 import { z } from "zod";
-import { and, eq } from "drizzle-orm";
-import { agents, heartbeatRuns, listHeartbeatQueueJobs } from "bopodev-db";
+import { agents, and, eq, heartbeatRuns, listHeartbeatQueueJobs } from "bopodev-db";
 import type { AppContext } from "../context";
 import { sendError, sendOk } from "../http";
 import { requireCompanyScope } from "../middleware/company-scope";

package/src/routes/issues.ts

@@ -1,7 +1,6 @@
 import { Router } from "express";
 import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { basename, extname, join, resolve } from "node:path";
-import { and, desc, eq, inArray } from "drizzle-orm";
 import multer from "multer";
 import { z } from "zod";
 import { IssueDetailSchema, IssueSchema } from "bopodev-contracts";
@@ -9,15 +8,19 @@ import {
   addIssueAttachment,
   addIssueComment,
   agents,
+  and,
   appendActivity,
   appendAuditEvent,
   createIssue,
   deleteIssueAttachment,
   deleteIssueComment,
   deleteIssue,
+  desc,
+  eq,
   getIssue,
   heartbeatRuns,
   getIssueAttachment,
+  inArray,
   issues,
   listIssueAttachments,
   listIssueActivity,

package/src/server.ts

@@ -1,9 +1,8 @@
 import { createServer } from "node:http";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { sql } from "drizzle-orm";
 import { config as loadDotenv } from "dotenv";
-import { bootstrapDatabase, listCompanies, resolveDefaultDbPath } from "bopodev-db";
+import { bootstrapDatabase, listCompanies, resolveDefaultDbPath, sql } from "bopodev-db";
 import { checkRuntimeCommandHealth } from "bopodev-agent-sdk";
 import type { RuntimeCommandHealth } from "bopodev-agent-sdk";
 import { createApp } from "./app";
@@ -21,6 +20,8 @@ import {
 } from "./security/deployment-mode";
 import { ensureBuiltinPluginsRegistered } from "./services/plugin-runtime";
 import { ensureBuiltinTemplatesRegistered } from "./services/template-catalog";
+import { beginIssueCommentDispatchShutdown, waitForIssueCommentDispatchDrain } from "./services/comment-recipient-dispatch-service";
+import { beginHeartbeatQueueShutdown, waitForHeartbeatQueueDrain } from "./services/heartbeat-queue-service";
 import { createHeartbeatScheduler } from "./worker/scheduler";
 
 loadApiEnv();
@@ -32,6 +33,7 @@ async function main() {
   const publicBaseUrl = resolvePublicBaseUrl();
   validateDeploymentConfiguration(deploymentMode, allowedOrigins, allowedHostnames, publicBaseUrl);
   const dbPath = normalizeOptionalDbPath(process.env.BOPO_DB_PATH);
+  const usingExternalDatabase = Boolean(process.env.DATABASE_URL?.trim());
   const port = Number(process.env.PORT ?? 4020);
   const effectiveDbPath = dbPath ?? resolveDefaultDbPath();
   let db: Awaited<ReturnType<typeof bootstrapDatabase>>["db"];
@@ -41,17 +43,20 @@ async function main() {
     db = boot.db;
     dbClient = boot.client;
   } catch (error) {
-    if (isProbablyPgliteWasmAbort(error)) {
+    if (isProbablyDatabaseStartupError(error)) {
       // eslint-disable-next-line no-console
-      console.error(
-        "[startup] PGlite (embedded Postgres) failed during database bootstrap. This is unrelated to Codex or heartbeat prompt settings."
-      );
-      // eslint-disable-next-line no-console
-      console.error(`[startup] Data path in use: ${effectiveDbPath}`);
-      // eslint-disable-next-line no-console
-      console.error(
-        "[startup] Recovery: stop all API/node processes using this DB, back up the path above, delete the file/dir, then restart (schema will be recreated). Or set BOPO_DB_PATH to a fresh path. See docs/operations/troubleshooting.md (PGlite)."
-      );
+      console.error("[startup] Database bootstrap failed before the API could start.");
+      if (usingExternalDatabase) {
+        // eslint-disable-next-line no-console
+        console.error("[startup] Check DATABASE_URL connectivity, permissions, and migration state.");
+      } else {
+        // eslint-disable-next-line no-console
+        console.error(`[startup] Embedded Postgres data path: ${effectiveDbPath}`);
+        // eslint-disable-next-line no-console
+        console.error(
+          "[startup] Recovery: stop all API/node processes using this DB, back up the path above, delete the directory if it is corrupted, then restart. Or set BOPO_DB_PATH to a fresh path."
+        );
+      }
     }
     throw error;
   }
@@ -141,9 +146,9 @@ async function main() {
 
   const defaultCompanyId = process.env.BOPO_DEFAULT_COMPANY_ID;
   const schedulerCompanyId = await resolveSchedulerCompanyId(db, defaultCompanyId ?? null);
-  let stopScheduler: (() => void) | undefined;
+  let scheduler: ReturnType<typeof createHeartbeatScheduler> | undefined;
   if (schedulerCompanyId && shouldStartScheduler()) {
-    stopScheduler = createHeartbeatScheduler(db, schedulerCompanyId, realtimeHub);
+    scheduler = createHeartbeatScheduler(db, schedulerCompanyId, realtimeHub);
   } else if (schedulerCompanyId) {
     // eslint-disable-next-line no-console
     console.log("[startup] Scheduler disabled for this instance (BOPO_SCHEDULER_ROLE is follower/off).");
@@ -151,38 +156,50 @@ async function main() {
 
   let shutdownInFlight: Promise<void> | null = null;
   function shutdown(signal: string) {
+    const shutdownTimeoutMs = Number(process.env.BOPO_SHUTDOWN_TIMEOUT_MS ?? 15_000);
+    const forcedExit = setTimeout(() => {
+      // eslint-disable-next-line no-console
+      console.error(`[shutdown] timed out after ${shutdownTimeoutMs}ms; forcing exit.`);
+      process.exit(process.exitCode ?? 1);
+    }, shutdownTimeoutMs);
+    forcedExit.unref();
     shutdownInFlight ??= (async () => {
       // eslint-disable-next-line no-console
-      console.log(`[shutdown] ${signal} — closing realtime, HTTP server, and embedded DB…`);
-      stopScheduler?.();
+      console.log(`[shutdown] ${signal} — draining HTTP/background work before closing the embedded database…`);
+      beginHeartbeatQueueShutdown();
+      beginIssueCommentDispatchShutdown();
+      await Promise.allSettled([
+        scheduler?.stop() ?? Promise.resolve(),
+        new Promise<void>((resolve, reject) => {
+          server.close((err) => {
+            if (err) {
+              reject(err);
+              return;
+            }
+            resolve();
+          });
+        })
+      ]);
+      await Promise.allSettled([waitForHeartbeatQueueDrain(), waitForIssueCommentDispatchDrain()]);
       try {
         await realtimeHub.close();
       } catch (closeError) {
         // eslint-disable-next-line no-console
         console.error("[shutdown] realtime hub close error", closeError);
       }
-      await new Promise<void>((resolve, reject) => {
-        server.close((err) => {
-          if (err) {
-            reject(err);
-            return;
-          }
-          resolve();
-        });
-      });
       try {
-        await closePgliteClient(dbClient);
+        await closeDatabaseClient(dbClient);
       } catch (closeDbError) {
         // eslint-disable-next-line no-console
-        console.error("[shutdown] PGlite close error", closeDbError);
+        console.error("[shutdown] database close error", closeDbError);
       }
       // eslint-disable-next-line no-console
       console.log("[shutdown] clean exit");
-      process.exit(0);
+      process.exitCode = 0;
     })().catch((error) => {
       // eslint-disable-next-line no-console
       console.error("[shutdown] failed", error);
-      process.exit(1);
+      process.exitCode = 1;
     });
     return shutdownInFlight;
   }
@@ -193,7 +210,7 @@ async function main() {
 
 void main();
 
-async function closePgliteClient(client: unknown) {
+async function closeDatabaseClient(client: unknown) {
   if (!client || typeof client !== "object") {
     return;
   }
@@ -211,7 +228,7 @@ async function hasCodexAgentsConfigured(db: Awaited<ReturnType<typeof bootstrapD
     WHERE provider_type = 'codex'
     LIMIT 1
   `);
-  return (result.rows ?? []).length > 0;
+  return result.length > 0;
 }
 
 async function hasOpenCodeAgentsConfigured(db: Awaited<ReturnType<typeof bootstrapDatabase>>["db"]) {
@@ -221,7 +238,7 @@ async function hasOpenCodeAgentsConfigured(db: Awaited<ReturnType<typeof bootstr
     WHERE provider_type = 'opencode'
     LIMIT 1
   `);
-  return (result.rows ?? []).length > 0;
+  return result.length > 0;
 }
 
 async function resolveSchedulerCompanyId(
@@ -235,7 +252,7 @@ async function resolveSchedulerCompanyId(
       WHERE id = ${configuredCompanyId}
       LIMIT 1
     `);
-    if ((configured.rows ?? []).length > 0) {
+    if (configured.length > 0) {
       return configuredCompanyId;
     }
     // eslint-disable-next-line no-console
@@ -248,7 +265,7 @@ async function resolveSchedulerCompanyId(
     ORDER BY created_at ASC
     LIMIT 1
   `);
-  const id = fallback.rows?.[0]?.id;
+  const id = fallback[0]?.id;
   return typeof id === "string" && id.length > 0 ? id : null;
 }
 
@@ -337,14 +354,15 @@ function normalizeOptionalDbPath(value: string | undefined) {
   return normalized && normalized.length > 0 ? normalized : undefined;
 }
 
-function isProbablyPgliteWasmAbort(error: unknown): boolean {
+function isProbablyDatabaseStartupError(error: unknown): boolean {
   const message = error instanceof Error ? error.message : String(error);
   const cause = error instanceof Error ? error.cause : undefined;
   const causeMessage = cause instanceof Error ? cause.message : String(cause ?? "");
   return (
-    message.includes("Aborted") ||
-    causeMessage.includes("Aborted") ||
-    message.includes("pglite") ||
-    causeMessage.includes("RuntimeError")
+    message.includes("database") ||
+    message.includes("postgres") ||
+    message.includes("migration") ||
+    causeMessage.includes("postgres") ||
+    causeMessage.includes("connection")
   );
 }

package/src/services/attention-service.ts

@@ -1,7 +1,10 @@
-import { and, desc, eq, like } from "drizzle-orm";
 import {
+  and,
   issueComments,
   issues,
+  desc,
+  eq,
+  like,
   listApprovalRequests,
   listAttentionInboxStates,
   listHeartbeatRuns,

package/src/services/budget-service.ts

@@ -1,6 +1,5 @@
-import { and, eq, sql } from "drizzle-orm";
 import type { BopoDb } from "bopodev-db";
-import { agents, projects } from "bopodev-db";
+import { agents, and, eq, projects, sql } from "bopodev-db";
 
 export interface BudgetCheckResult {
   allowed: boolean;

package/src/services/comment-recipient-dispatch-service.ts

@@ -1,21 +1,38 @@
-import { and, desc, eq, inArray, like } from "drizzle-orm";
 import {
+  and,
   agents,
+  desc,
+  eq,
+  inArray,
   issueComments,
+  like,
   updateIssueCommentRecipients,
   type BopoDb
 } from "bopodev-db";
+import { createDrainableWorkTracker } from "../lib/drainable-work";
 import { parseIssueCommentRecipients, type PersistedCommentRecipient } from "../lib/comment-recipients";
 import type { RealtimeHub } from "../realtime/hub";
 import { enqueueHeartbeatQueueJob, triggerHeartbeatQueueWorker } from "./heartbeat-queue-service";
 
 const COMMENT_DISPATCH_SWEEP_LIMIT = 100;
 const activeCompanyDispatchRuns = new Set<string>();
+const commentDispatchTracker = createDrainableWorkTracker();
 
 export async function runIssueCommentDispatchSweep(
   db: BopoDb,
   companyId: string,
   options?: { requestId?: string; realtimeHub?: RealtimeHub; limit?: number }
+) {
+  if (commentDispatchTracker.isShuttingDown()) {
+    return;
+  }
+  return commentDispatchTracker.track(runIssueCommentDispatchSweepInternal(db, companyId, options));
+}
+
+async function runIssueCommentDispatchSweepInternal(
+  db: BopoDb,
+  companyId: string,
+  options?: { requestId?: string; realtimeHub?: RealtimeHub; limit?: number }
 ) {
   const rows = await db
     .select({
@@ -34,6 +51,9 @@ export async function runIssueCommentDispatchSweep(
     .limit(options?.limit ?? COMMENT_DISPATCH_SWEEP_LIMIT);
 
   for (const row of rows) {
+    if (commentDispatchTracker.isShuttingDown()) {
+      return;
+    }
     const recipients = parseIssueCommentRecipients(row.recipientsJson);
     if (!recipients.some((recipient) => recipient.deliveryStatus === "pending")) {
       continue;
@@ -60,11 +80,15 @@ export function triggerIssueCommentDispatchWorker(
   companyId: string,
   options?: { requestId?: string; realtimeHub?: RealtimeHub; limit?: number }
 ) {
-  if (activeCompanyDispatchRuns.has(companyId)) {
+  if (commentDispatchTracker.isShuttingDown() || activeCompanyDispatchRuns.has(companyId)) {
     return;
   }
   activeCompanyDispatchRuns.add(companyId);
   queueMicrotask(() => {
+    if (commentDispatchTracker.isShuttingDown()) {
+      activeCompanyDispatchRuns.delete(companyId);
+      return;
+    }
     void runIssueCommentDispatchSweep(db, companyId, options)
       .catch((error) => {
         // eslint-disable-next-line no-console
@@ -156,3 +180,16 @@ async function dispatchCommentRecipients(
   return dispatchedRecipients;
 }
 
+export function beginIssueCommentDispatchShutdown() {
+  commentDispatchTracker.beginShutdown();
+}
+
+export async function waitForIssueCommentDispatchDrain() {
+  await commentDispatchTracker.drain();
+}
+
+export function resetIssueCommentDispatchShutdownForTests() {
+  activeCompanyDispatchRuns.clear();
+  commentDispatchTracker.resetForTests();
+}
+

package/src/services/governance-service.ts

@@ -1,4 +1,3 @@
-import { and, eq } from "drizzle-orm";
 import { mkdir } from "node:fs/promises";
 import { z } from "zod";
 import {
@@ -10,6 +9,7 @@ import {
 } from "bopodev-contracts";
 import type { BopoDb } from "bopodev-db";
 import {
+  and,
   approvalRequests,
   agents,
   appendAuditEvent,
@@ -26,6 +26,7 @@ import {
   listProjectWorkspaces,
   listProjects,
   projects,
+  eq,
   updateProjectWorkspace,
   updatePluginConfig
 } from "bopodev-db";

package/src/services/heartbeat-queue-service.ts

@@ -1,6 +1,7 @@
-import { and, eq } from "drizzle-orm";
 import {
+  and,
   cancelHeartbeatJob,
+  eq,
   getHeartbeatRun,
   claimNextHeartbeatJob,
   enqueueHeartbeatJob,
@@ -11,6 +12,7 @@ import {
   updateIssueCommentRecipients,
   type BopoDb
 } from "bopodev-db";
+import { createDrainableWorkTracker } from "../lib/drainable-work";
 import { parseIssueCommentRecipients } from "../lib/comment-recipients";
 import type { RealtimeHub } from "../realtime/hub";
 import { runHeartbeatForAgent } from "./heartbeat-service";
@@ -30,6 +32,7 @@ type QueueJobPayload = {
 };
 
 const activeCompanyQueueWorkers = new Set<string>();
+const queueWorkTracker = createDrainableWorkTracker();
 
 export async function enqueueHeartbeatQueueJob(
   db: BopoDb,
@@ -61,11 +64,15 @@ export function triggerHeartbeatQueueWorker(
   companyId: string,
   options?: { requestId?: string; realtimeHub?: RealtimeHub; maxJobsPerSweep?: number }
 ) {
-  if (activeCompanyQueueWorkers.has(companyId)) {
+  if (queueWorkTracker.isShuttingDown() || activeCompanyQueueWorkers.has(companyId)) {
     return;
   }
   activeCompanyQueueWorkers.add(companyId);
   queueMicrotask(() => {
+    if (queueWorkTracker.isShuttingDown()) {
+      activeCompanyQueueWorkers.delete(companyId);
+      return;
+    }
     void runHeartbeatQueueSweep(db, companyId, options)
       .catch((error) => {
         // eslint-disable-next-line no-console
@@ -81,10 +88,21 @@ export async function runHeartbeatQueueSweep(
   db: BopoDb,
   companyId: string,
   options?: { requestId?: string; realtimeHub?: RealtimeHub; maxJobsPerSweep?: number }
+) {
+  if (queueWorkTracker.isShuttingDown()) {
+    return { processed: 0 };
+  }
+  return queueWorkTracker.track(runHeartbeatQueueSweepInternal(db, companyId, options));
+}
+
+async function runHeartbeatQueueSweepInternal(
+  db: BopoDb,
+  companyId: string,
+  options?: { requestId?: string; realtimeHub?: RealtimeHub; maxJobsPerSweep?: number }
 ) {
   const maxJobs = Math.max(1, Math.min(options?.maxJobsPerSweep ?? 50, 500));
   let processed = 0;
-  while (processed < maxJobs) {
+  while (processed < maxJobs && !queueWorkTracker.isShuttingDown()) {
     const job = await claimNextHeartbeatJob(db, companyId);
     if (!job) {
       break;
@@ -117,6 +135,19 @@ export async function runHeartbeatQueueSweep(
   return { processed };
 }
 
+export function beginHeartbeatQueueShutdown() {
+  queueWorkTracker.beginShutdown();
+}
+
+export async function waitForHeartbeatQueueDrain() {
+  await queueWorkTracker.drain();
+}
+
+export function resetHeartbeatQueueShutdownForTests() {
+  activeCompanyQueueWorkers.clear();
+  queueWorkTracker.resetForTests();
+}
+
 async function processHeartbeatQueueJob(
   db: BopoDb,
   input: {

package/src/services/heartbeat-service.ts

@@ -1,6 +1,5 @@
 import { mkdir, stat } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
-import { and, desc, eq, inArray, sql } from "drizzle-orm";
 import { nanoid } from "nanoid";
 import { resolveAdapter } from "bopodev-agent-sdk";
 import type { AdapterExecutionResult, AgentState, HeartbeatContext } from "bopodev-agent-sdk";
@@ -19,18 +18,24 @@ import {
 import type { BopoDb } from "bopodev-db";
 import {
   addIssueComment,
+  and,
   approvalRequests,
   agents,
   appendActivity,
   appendHeartbeatRunMessages,
+  auditEvents,
   companies,
   createApprovalRequest,
+  desc,
+  eq,
   goals,
   heartbeatRuns,
+  inArray,
   issueComments,
   issueAttachments,
   issues,
-  projects
+  projects,
+  sql
 } from "bopodev-db";
 import { appendAuditEvent, appendCost } from "bopodev-db";
 import { parseRuntimeConfigFromAgentRow } from "../lib/agent-config";
@@ -49,7 +54,7 @@ import {
   resolveAgentFallbackWorkspace
 } from "../lib/workspace-policy";
 import type { RealtimeHub } from "../realtime/hub";
-import { createHeartbeatRunsRealtimeEvent } from "../realtime/heartbeat-runs";
+import { createHeartbeatRunsRealtimeEvent, loadHeartbeatRunsRealtimeSnapshot } from "../realtime/heartbeat-runs";
 import { publishAttentionSnapshot } from "../realtime/attention";
 import { publishOfficeOccupantForAgent } from "../realtime/office-space";
 import { appendProjectBudgetUsage, checkAgentBudget, checkProjectBudget } from "./budget-service";
@@ -158,7 +163,7 @@ export async function claimIssuesForAgent(
     RETURNING i.id, i.project_id, i.parent_issue_id, i.title, i.body, i.status, i.priority, i.labels_json, i.tags_json;
   `);
 
-  return (result.rows ?? []) as Array<{
+  return result as unknown as Array<{
     id: string;
     project_id: string;
     parent_issue_id: string | null;
@@ -713,6 +718,8 @@ export async function runHeartbeatForAgent(
 
   let issueIds: string[] = [];
   let claimedIssueIds: string[] = [];
+  /** After transcript flush: remove DB row + audit noise for idle heartbeats with no issues. */
+  let discardIdleNoWorkRunAfterFlush = false;
   let executionWorkItemsForBudget: Array<{ issueId: string; projectId: string }> = [];
   let state: AgentState & {
     runtime?: {
@@ -1716,6 +1723,11 @@ export async function runHeartbeatForAgent(
         }
       }
     });
+    discardIdleNoWorkRunAfterFlush =
+      issueIds.length === 0 &&
+      !isCommentOrderWake &&
+      (terminalPresentation.completionReason === "no_assigned_work" ||
+        (isIdleNoWork && heartbeatIdlePolicy === "skip_adapter" && persistedRunStatus === "completed"));
   } catch (error) {
     const classified = classifyHeartbeatError(error);
     executionSummary =
@@ -1951,6 +1963,17 @@ export async function runHeartbeatForAgent(
     }
   } finally {
     await transcriptWriteQueue;
+    if (discardIdleNoWorkRunAfterFlush) {
+      try {
+        await purgeIdleNoWorkHeartbeatRun(db, companyId, runId);
+        if (options?.realtimeHub) {
+          options.realtimeHub.publish(await loadHeartbeatRunsRealtimeSnapshot(db, companyId));
+        }
+      } catch (purgeError) {
+        // eslint-disable-next-line no-console
+        console.error("[heartbeat] failed to purge idle no-work run", runId, purgeError);
+      }
+    }
     unregisterActiveHeartbeatRun(runId);
     try {
       await releaseClaimedIssues(db, companyId, claimedIssueIds);
@@ -1984,6 +2007,15 @@ export async function runHeartbeatForAgent(
   return runId;
 }
 
+async function purgeIdleNoWorkHeartbeatRun(db: BopoDb, companyId: string, runId: string) {
+  await db
+    .delete(auditEvents)
+    .where(
+      and(eq(auditEvents.companyId, companyId), eq(auditEvents.entityType, "heartbeat_run"), eq(auditEvents.entityId, runId))
+    );
+  await db.delete(heartbeatRuns).where(and(eq(heartbeatRuns.companyId, companyId), eq(heartbeatRuns.id, runId)));
+}
+
 async function insertStartedRunAtomic(
   db: BopoDb,
   input: { id: string; companyId: string; agentId: string; message: string }
@@ -1994,7 +2026,7 @@ async function insertStartedRunAtomic(
     ON CONFLICT DO NOTHING
     RETURNING id
   `);
-  return (result.rows ?? []).length > 0;
+  return result.length > 0;
 }
 
 async function recoverStaleHeartbeatRuns(
@@ -2138,7 +2170,7 @@ async function listLatestRunByAgent(db: BopoDb, companyId: string) {
     GROUP BY agent_id
   `);
   const latestRunByAgent = new Map<string, Date>();
-  for (const row of result.rows ?? []) {
+  for (const row of result as Array<Record<string, unknown>>) {
     const agentId = typeof row.agent_id === "string" ? row.agent_id : null;
     if (!agentId) {
       continue;

package/src/worker/scheduler.ts

@@ -4,6 +4,10 @@ import { runHeartbeatSweep } from "../services/heartbeat-service";
 import { runHeartbeatQueueSweep } from "../services/heartbeat-queue-service";
 import { runIssueCommentDispatchSweep } from "../services/comment-recipient-dispatch-service";
 
+export type HeartbeatSchedulerHandle = {
+  stop: () => Promise<void>;
+};
+
 export function createHeartbeatScheduler(db: BopoDb, companyId: string, realtimeHub?: RealtimeHub) {
   const heartbeatIntervalMs = Number(process.env.BOPO_HEARTBEAT_SWEEP_MS ?? 60_000);
   const queueIntervalMs = Number(process.env.BOPO_HEARTBEAT_QUEUE_SWEEP_MS ?? 2_000);
@@ -11,18 +15,22 @@ export function createHeartbeatScheduler(db: BopoDb, companyId: string, realtime
   let heartbeatRunning = false;
   let queueRunning = false;
   let commentDispatchRunning = false;
+  let heartbeatPromise: Promise<unknown> | null = null;
+  let queuePromise: Promise<unknown> | null = null;
+  let commentDispatchPromise: Promise<unknown> | null = null;
   const heartbeatTimer = setInterval(() => {
     if (heartbeatRunning) {
       return;
     }
     heartbeatRunning = true;
-    void runHeartbeatSweep(db, companyId, { realtimeHub })
+    heartbeatPromise = runHeartbeatSweep(db, companyId, { realtimeHub })
       .catch((error) => {
         // eslint-disable-next-line no-console
         console.error("[scheduler] heartbeat sweep failed", error);
       })
       .finally(() => {
         heartbeatRunning = false;
+        heartbeatPromise = null;
       });
   }, heartbeatIntervalMs);
   const queueTimer = setInterval(() => {
@@ -30,13 +38,14 @@ export function createHeartbeatScheduler(db: BopoDb, companyId: string, realtime
       return;
     }
     queueRunning = true;
-    void runHeartbeatQueueSweep(db, companyId, { realtimeHub })
+    queuePromise = runHeartbeatQueueSweep(db, companyId, { realtimeHub })
       .catch((error) => {
         // eslint-disable-next-line no-console
         console.error("[scheduler] queue sweep failed", error);
       })
       .finally(() => {
         queueRunning = false;
+        queuePromise = null;
       });
   }, queueIntervalMs);
   const commentDispatchTimer = setInterval(() => {
@@ -44,18 +53,25 @@ export function createHeartbeatScheduler(db: BopoDb, companyId: string, realtime
       return;
     }
     commentDispatchRunning = true;
-    void runIssueCommentDispatchSweep(db, companyId, { realtimeHub })
+    commentDispatchPromise = runIssueCommentDispatchSweep(db, companyId, { realtimeHub })
       .catch((error) => {
         // eslint-disable-next-line no-console
         console.error("[scheduler] comment dispatch sweep failed", error);
       })
       .finally(() => {
         commentDispatchRunning = false;
+        commentDispatchPromise = null;
       });
   }, commentDispatchIntervalMs);
-  return () => {
+  const stop = async () => {
     clearInterval(heartbeatTimer);
     clearInterval(queueTimer);
     clearInterval(commentDispatchTimer);
+    await Promise.allSettled(
+      [heartbeatPromise, queuePromise, commentDispatchPromise].filter(
+        (promise): promise is Promise<unknown> => promise !== null
+      )
+    );
   };
+  return { stop } satisfies HeartbeatSchedulerHandle;
 }