bopodev-api 0.1.28 → 0.1.29

package/src/server.ts

@@ -1,10 +1,5 @@
 import { createServer } from "node:http";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { config as loadDotenv } from "dotenv";
-import { bootstrapDatabase, listCompanies, resolveDefaultDbPath, sql } from "bopodev-db";
-import { checkRuntimeCommandHealth } from "bopodev-agent-sdk";
-import type { RuntimeCommandHealth } from "bopodev-agent-sdk";
+import { listCompanies } from "bopodev-db";
 import { createApp } from "./app";
 import { loadGovernanceRealtimeSnapshot } from "./realtime/governance";
 import { loadOfficeSpaceRealtimeSnapshot } from "./realtime/office-space";
@@ -12,7 +7,6 @@ import { loadHeartbeatRunsRealtimeSnapshot } from "./realtime/heartbeat-runs";
 import { loadAttentionRealtimeSnapshot } from "./realtime/attention";
 import { attachRealtimeHub } from "./realtime/hub";
 import {
-  isAuthenticatedMode,
   resolveAllowedHostnames,
   resolveAllowedOrigins,
   resolveDeploymentMode,
@@ -20,9 +14,18 @@ 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";
+import { bootstrapDatabaseWithStartupLogging } from "./startup/database";
+import { validateDeploymentConfiguration } from "./startup/deployment-validation";
+import { loadApiEnv, normalizeOptionalDbPath } from "./startup/env";
+import {
+  buildGetRuntimeHealth,
+  hasCodexAgentsConfigured,
+  hasOpenCodeAgentsConfigured,
+  runStartupRuntimePreflights
+} from "./startup/runtime-health";
+import { resolveSchedulerCompanyId, shouldStartScheduler } from "./startup/scheduler-config";
+import { attachGracefulShutdownHandlers } from "./shutdown/graceful-shutdown";
 
 loadApiEnv();
 
@@ -33,33 +36,8 @@ 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"];
-  let dbClient: Awaited<ReturnType<typeof bootstrapDatabase>>["client"];
-  try {
-    const boot = await bootstrapDatabase(dbPath);
-    db = boot.db;
-    dbClient = boot.client;
-  } catch (error) {
-    if (isProbablyDatabaseStartupError(error)) {
-      // eslint-disable-next-line no-console
-      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;
-  }
+  const { db, client: dbClient } = await bootstrapDatabaseWithStartupLogging(dbPath);
   const existingCompanies = await listCompanies(db);
   await ensureBuiltinPluginsRegistered(
     db,
@@ -79,54 +57,20 @@ async function main() {
   const openCodeHealthRequired =
     !skipOpenCodePreflight &&
     (process.env.BOPO_REQUIRE_OPENCODE_HEALTH === "1" || (await hasOpenCodeAgentsConfigured(db)));
-  const getRuntimeHealth = async () => {
-    const codex = codexHealthRequired
-      ? await checkRuntimeCommandHealth(codexCommand, {
-          timeoutMs: 5_000
-        })
-      : {
-          command: codexCommand,
-          available: skipCodexPreflight ? false : true,
-          exitCode: null,
-          elapsedMs: 0,
-          error: skipCodexPreflight
-            ? "Skipped by configuration: BOPO_SKIP_CODEX_PREFLIGHT=1."
-            : "Skipped: no Codex agents configured."
-        };
-    const opencode = openCodeHealthRequired
-      ? await checkRuntimeCommandHealth(openCodeCommand, {
-          timeoutMs: 5_000
-        })
-      : {
-          command: openCodeCommand,
-          available: skipOpenCodePreflight ? false : true,
-          exitCode: null,
-          elapsedMs: 0,
-          error: skipOpenCodePreflight
-            ? "Skipped by configuration: BOPO_SKIP_OPENCODE_PREFLIGHT=1."
-            : "Skipped: no OpenCode agents configured."
-        };
-    return {
-      codex,
-      opencode
-    };
-  };
-  if (codexHealthRequired) {
-    const startupCodexHealth = await checkRuntimeCommandHealth(codexCommand, {
-      timeoutMs: 5_000
-    });
-    if (!startupCodexHealth.available) {
-      emitCodexPreflightWarning(startupCodexHealth);
-    }
-  }
-  if (openCodeHealthRequired) {
-    const startupOpenCodeHealth = await checkRuntimeCommandHealth(openCodeCommand, {
-      timeoutMs: 5_000
-    });
-    if (!startupOpenCodeHealth.available) {
-      emitOpenCodePreflightWarning(startupOpenCodeHealth);
-    }
-  }
+  const getRuntimeHealth = buildGetRuntimeHealth({
+    codexCommand,
+    openCodeCommand,
+    skipCodexPreflight,
+    skipOpenCodePreflight,
+    codexHealthRequired,
+    openCodeHealthRequired
+  });
+  await runStartupRuntimePreflights({
+    codexHealthRequired,
+    openCodeHealthRequired,
+    codexCommand,
+    openCodeCommand
+  });
 
   const server = createServer();
   const realtimeHub = attachRealtimeHub(server, {
@@ -154,215 +98,12 @@ async function main() {
     console.log("[startup] Scheduler disabled for this instance (BOPO_SCHEDULER_ROLE is follower/off).");
   }
 
-  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} — 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);
-      }
-      try {
-        await closeDatabaseClient(dbClient);
-      } catch (closeDbError) {
-        // eslint-disable-next-line no-console
-        console.error("[shutdown] database close error", closeDbError);
-      }
-      // eslint-disable-next-line no-console
-      console.log("[shutdown] clean exit");
-      process.exitCode = 0;
-    })().catch((error) => {
-      // eslint-disable-next-line no-console
-      console.error("[shutdown] failed", error);
-      process.exitCode = 1;
-    });
-    return shutdownInFlight;
-  }
-
-  process.once("SIGINT", () => void shutdown("SIGINT"));
-  process.once("SIGTERM", () => void shutdown("SIGTERM"));
+  attachGracefulShutdownHandlers({
+    server,
+    realtimeHub,
+    dbClient,
+    scheduler
+  });
 }
 
 void main();
-
-async function closeDatabaseClient(client: unknown) {
-  if (!client || typeof client !== "object") {
-    return;
-  }
-  const closeFn = (client as { close?: unknown }).close;
-  if (typeof closeFn !== "function") {
-    return;
-  }
-  await (closeFn as () => Promise<void>)();
-}
-
-async function hasCodexAgentsConfigured(db: Awaited<ReturnType<typeof bootstrapDatabase>>["db"]) {
-  const result = await db.execute(sql`
-    SELECT id
-    FROM agents
-    WHERE provider_type = 'codex'
-    LIMIT 1
-  `);
-  return result.length > 0;
-}
-
-async function hasOpenCodeAgentsConfigured(db: Awaited<ReturnType<typeof bootstrapDatabase>>["db"]) {
-  const result = await db.execute(sql`
-    SELECT id
-    FROM agents
-    WHERE provider_type = 'opencode'
-    LIMIT 1
-  `);
-  return result.length > 0;
-}
-
-async function resolveSchedulerCompanyId(
-  db: Awaited<ReturnType<typeof bootstrapDatabase>>["db"],
-  configuredCompanyId: string | null
-) {
-  if (configuredCompanyId) {
-    const configured = await db.execute(sql`
-      SELECT id
-      FROM companies
-      WHERE id = ${configuredCompanyId}
-      LIMIT 1
-    `);
-    if (configured.length > 0) {
-      return configuredCompanyId;
-    }
-    // eslint-disable-next-line no-console
-    console.warn(`[startup] BOPO_DEFAULT_COMPANY_ID='${configuredCompanyId}' was not found; using first available company.`);
-  }
-
-  const fallback = await db.execute(sql`
-    SELECT id
-    FROM companies
-    ORDER BY created_at ASC
-    LIMIT 1
-  `);
-  const id = fallback[0]?.id;
-  return typeof id === "string" && id.length > 0 ? id : null;
-}
-
-function emitCodexPreflightWarning(health: RuntimeCommandHealth) {
-  const red = process.stderr.isTTY ? "\x1b[31m" : "";
-  const yellow = process.stderr.isTTY ? "\x1b[33m" : "";
-  const reset = process.stderr.isTTY ? "\x1b[0m" : "";
-  const symbol = `${red}✖${reset}`;
-  process.stderr.write(
-    `${symbol} ${yellow}Codex preflight failed${reset}: command '${health.command}' is unavailable.\n`
-  );
-  process.stderr.write(`  Install Codex CLI or set BOPO_SKIP_CODEX_PREFLIGHT=1 for local dev.\n`);
-  if (process.env.BOPO_VERBOSE_STARTUP_WARNINGS === "1") {
-    process.stderr.write(`  Details: ${JSON.stringify(health)}\n`);
-  }
-}
-
-function emitOpenCodePreflightWarning(health: RuntimeCommandHealth) {
-  const red = process.stderr.isTTY ? "\x1b[31m" : "";
-  const yellow = process.stderr.isTTY ? "\x1b[33m" : "";
-  const reset = process.stderr.isTTY ? "\x1b[0m" : "";
-  const symbol = `${red}✖${reset}`;
-  process.stderr.write(
-    `${symbol} ${yellow}OpenCode preflight failed${reset}: command '${health.command}' is unavailable.\n`
-  );
-  process.stderr.write(`  Install OpenCode CLI or set BOPO_SKIP_OPENCODE_PREFLIGHT=1 for local dev.\n`);
-  if (process.env.BOPO_VERBOSE_STARTUP_WARNINGS === "1") {
-    process.stderr.write(`  Details: ${JSON.stringify(health)}\n`);
-  }
-}
-
-function validateDeploymentConfiguration(
-  deploymentMode: ReturnType<typeof resolveDeploymentMode>,
-  allowedOrigins: string[],
-  allowedHostnames: string[],
-  publicBaseUrl: URL | null
-) {
-  if (deploymentMode === "authenticated_public" && !publicBaseUrl) {
-    throw new Error("BOPO_PUBLIC_BASE_URL is required in authenticated_public mode.");
-  }
-  if (isAuthenticatedMode(deploymentMode) && process.env.BOPO_AUTH_TOKEN_SECRET?.trim() === "") {
-    throw new Error("BOPO_AUTH_TOKEN_SECRET must not be empty when set.");
-  }
-  if (isAuthenticatedMode(deploymentMode) && !process.env.BOPO_AUTH_TOKEN_SECRET?.trim()) {
-    // eslint-disable-next-line no-console
-    console.warn(
-      "[startup] BOPO_AUTH_TOKEN_SECRET is not set. Authenticated modes will require BOPO_TRUST_ACTOR_HEADERS=1 behind a trusted proxy."
-    );
-  }
-  if (isAuthenticatedMode(deploymentMode) && process.env.BOPO_TRUST_ACTOR_HEADERS !== "1" && !process.env.BOPO_AUTH_TOKEN_SECRET?.trim()) {
-    throw new Error(
-      "Authenticated mode requires either BOPO_AUTH_TOKEN_SECRET (token identity) or BOPO_TRUST_ACTOR_HEADERS=1 (trusted proxy headers)."
-    );
-  }
-  if (isAuthenticatedMode(deploymentMode) && process.env.BOPO_ALLOW_LOCAL_BOARD_FALLBACK === "1") {
-    throw new Error("BOPO_ALLOW_LOCAL_BOARD_FALLBACK cannot be enabled in authenticated modes.");
-  }
-  // eslint-disable-next-line no-console
-  console.log(
-    `[startup] Deployment config: mode=${deploymentMode} origins=${allowedOrigins.join(",")} hosts=${allowedHostnames.join(",")}`
-  );
-}
-
-function shouldStartScheduler() {
-  const rawRole = (process.env.BOPO_SCHEDULER_ROLE ?? "auto").trim().toLowerCase();
-  if (rawRole === "off" || rawRole === "follower") {
-    return false;
-  }
-  if (rawRole === "leader" || rawRole === "auto") {
-    return true;
-  }
-  throw new Error(`Invalid BOPO_SCHEDULER_ROLE '${rawRole}'. Expected one of: auto, leader, follower, off.`);
-}
-
-function loadApiEnv() {
-  const sourceDir = dirname(fileURLToPath(import.meta.url));
-  const repoRoot = resolve(sourceDir, "../../../");
-  const candidates = [resolve(repoRoot, ".env.local"), resolve(repoRoot, ".env")];
-  for (const path of candidates) {
-    loadDotenv({ path, override: false, quiet: true });
-  }
-}
-
-function normalizeOptionalDbPath(value: string | undefined) {
-  const normalized = value?.trim();
-  return normalized && normalized.length > 0 ? normalized : undefined;
-}
-
-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("database") ||
-    message.includes("postgres") ||
-    message.includes("migration") ||
-    causeMessage.includes("postgres") ||
-    causeMessage.includes("connection")
-  );
-}

package/src/services/company-export-service.ts

@@ -0,0 +1,63 @@
+import type { BopoDb } from "bopodev-db";
+import { getCompany, listAgents, listGoals, listIssues, listProjects } from "bopodev-db";
+
+function serializeValue(value: unknown): unknown {
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    return serializeRow(value as Record<string, unknown>);
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => serializeValue(entry));
+  }
+  return value;
+}
+
+function serializeRow<T extends Record<string, unknown>>(row: T): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, val] of Object.entries(row)) {
+    out[key] = serializeValue(val);
+  }
+  return out;
+}
+
+/** Strip agent fields that commonly hold secrets or session state for shareable exports. */
+function scrubAgentRow(agent: Record<string, unknown>) {
+  const base = serializeRow(agent);
+  return {
+    ...base,
+    runtimeEnvJson: "{}",
+    bootstrapPrompt: null,
+    stateBlob: "{}",
+    runtimeCommand: null,
+    runtimeArgsJson: "[]"
+  };
+}
+
+/**
+ * Portable company snapshot for backup, templates, or handoff (secrets and agent session state redacted).
+ */
+export async function buildCompanyPortabilityExport(db: BopoDb, companyId: string) {
+  const company = await getCompany(db, companyId);
+  if (!company) {
+    return null;
+  }
+
+  const [projects, goals, issues, agents] = await Promise.all([
+    listProjects(db, companyId),
+    listGoals(db, companyId),
+    listIssues(db, companyId),
+    listAgents(db, companyId)
+  ]);
+
+  return {
+    exportedAt: new Date().toISOString(),
+    formatVersion: 1,
+    company: serializeRow(company as unknown as Record<string, unknown>),
+    projects: projects.map((p) => serializeRow(p as unknown as Record<string, unknown>)),
+    goals: goals.map((g) => serializeRow(g as unknown as Record<string, unknown>)),
+    issues: issues.map((issue) => serializeRow(issue as unknown as Record<string, unknown>)),
+    agents: agents.map((agent) => scrubAgentRow(agent as unknown as Record<string, unknown>))
+  };
+}

package/src/services/governance-service.ts

@@ -94,6 +94,7 @@ const hireAgentPayloadSchema = AgentCreateRequestSchema.extend({
 const activateGoalPayloadSchema = z.object({
   projectId: z.string().optional(),
   parentGoalId: z.string().optional(),
+  ownerAgentId: z.string().optional(),
   level: z.enum(["company", "project", "agent"]),
   title: z.string().min(1),
   description: z.string().optional()
@@ -372,6 +373,7 @@ async function applyApprovalAction(db: BopoDb, companyId: string, action: string
       companyId,
       projectId: parsed.data.projectId,
       parentGoalId: parsed.data.parentGoalId,
+      ownerAgentId: parsed.data.ownerAgentId,
       level: parsed.data.level,
       title: parsed.data.title,
       description: parsed.data.description
@@ -784,7 +786,8 @@ function buildAgentStartupTaskBody(companyId: string, agentId: string) {
     `   - \`${agentOperatingFolder}/HEARTBEAT.md\``,
     `   - \`${agentOperatingFolder}/SOUL.md\``,
     `   - \`${agentOperatingFolder}/TOOLS.md\``,
-    `3. Update your own agent runtime config via \`PUT /agents/:agentId\` and set \`runtimeConfig.bootstrapPrompt\` to reference \`${agentOperatingFolder}/AGENTS.md\` as your primary guide.`,
+    "3. Each heartbeat already includes your operating directory via `$BOPODEV_AGENT_OPERATING_DIR` and directs you to AGENTS.md and related files there when they exist.",
+    "   You do not need to save file paths into `bootstrapPrompt` for operating docs—use `PUT /agents/:agentId` `bootstrapPrompt` only for optional extra standing instructions.",
     "4. Post an issue comment summarizing completed setup artifacts.",
     "",
     "Safety checks:",

package/src/services/heartbeat-service/active-runs.ts

@@ -0,0 +1,15 @@
+import type { ActiveHeartbeatRun } from "./types";
+
+const activeHeartbeatRuns = new Map<string, ActiveHeartbeatRun>();
+
+export function registerActiveHeartbeatRun(runId: string, run: ActiveHeartbeatRun) {
+  activeHeartbeatRuns.set(runId, run);
+}
+
+export function unregisterActiveHeartbeatRun(runId: string) {
+  activeHeartbeatRuns.delete(runId);
+}
+
+export function getActiveHeartbeatRun(runId: string) {
+  return activeHeartbeatRuns.get(runId);
+}

package/src/services/heartbeat-service/budget-override.ts

@@ -0,0 +1,46 @@
+import { and, eq, inArray, approvalRequests, issues } from "bopodev-db";
+import type { BopoDb } from "bopodev-db";
+
+export async function findPendingProjectBudgetOverrideBlocksForAgent(
+  db: BopoDb,
+  companyId: string,
+  agentId: string
+) {
+  const assignedRows = await db
+    .select({ projectId: issues.projectId })
+    .from(issues)
+    .where(
+      and(
+        eq(issues.companyId, companyId),
+        eq(issues.assigneeAgentId, agentId),
+        inArray(issues.status, ["todo", "in_progress"])
+      )
+    );
+  const assignedProjectIds = new Set(assignedRows.map((row) => row.projectId));
+  if (assignedProjectIds.size === 0) {
+    return [] as string[];
+  }
+  const pendingOverrides = await db
+    .select({ payloadJson: approvalRequests.payloadJson })
+    .from(approvalRequests)
+    .where(
+      and(
+        eq(approvalRequests.companyId, companyId),
+        eq(approvalRequests.action, "override_budget"),
+        eq(approvalRequests.status, "pending")
+      )
+    );
+  const blockedProjectIds = new Set<string>();
+  for (const approval of pendingOverrides) {
+    try {
+      const payload = JSON.parse(approval.payloadJson) as Record<string, unknown>;
+      const projectId = typeof payload.projectId === "string" ? payload.projectId.trim() : "";
+      if (projectId && assignedProjectIds.has(projectId)) {
+        blockedProjectIds.add(projectId);
+      }
+    } catch {
+      // Ignore malformed payloads to keep enforcement resilient.
+    }
+  }
+  return Array.from(blockedProjectIds);
+}

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

@@ -0,0 +1,61 @@
+import { and, eq, inArray, issues, sql } from "bopodev-db";
+import type { BopoDb } from "bopodev-db";
+
+export async function claimIssuesForAgent(
+  db: BopoDb,
+  companyId: string,
+  agentId: string,
+  heartbeatRunId: string,
+  maxItems = 5
+) {
+  const result = await db.execute(sql`
+    WITH candidate AS (
+      SELECT id
+      FROM issues
+      WHERE company_id = ${companyId}
+        AND assignee_agent_id = ${agentId}
+        AND status IN ('todo', 'in_progress')
+        AND is_claimed = false
+      ORDER BY
+        CASE priority
+          WHEN 'urgent' THEN 0
+          WHEN 'high' THEN 1
+          WHEN 'medium' THEN 2
+          WHEN 'low' THEN 3
+          ELSE 4
+        END ASC,
+        updated_at ASC
+      LIMIT ${maxItems}
+      FOR UPDATE SKIP LOCKED
+    )
+    UPDATE issues i
+    SET is_claimed = true,
+        claimed_by_heartbeat_run_id = ${heartbeatRunId},
+        updated_at = CURRENT_TIMESTAMP
+    FROM candidate c
+    WHERE i.id = c.id
+    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 as unknown as Array<{
+    id: string;
+    project_id: string;
+    parent_issue_id: string | null;
+    title: string;
+    body: string | null;
+    status: string;
+    priority: string;
+    labels_json: string;
+    tags_json: string;
+  }>;
+}
+
+export async function releaseClaimedIssues(db: BopoDb, companyId: string, issueIds: string[]) {
+  if (issueIds.length === 0) {
+    return;
+  }
+  await db
+    .update(issues)
+    .set({ isClaimed: false, claimedByHeartbeatRunId: null, updatedAt: new Date() })
+    .where(and(eq(issues.companyId, companyId), inArray(issues.id, issueIds)));
+}

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

@@ -0,0 +1,58 @@
+export function isHeartbeatDue(cronExpression: string, lastRunAt: Date | null, now: Date) {
+  const normalizedNow = truncateToMinute(now);
+  if (!matchesCronExpression(cronExpression, normalizedNow)) {
+    return false;
+  }
+  if (!lastRunAt) {
+    return true;
+  }
+  return truncateToMinute(lastRunAt).getTime() !== normalizedNow.getTime();
+}
+
+function truncateToMinute(date: Date) {
+  const clone = new Date(date);
+  clone.setSeconds(0, 0);
+  return clone;
+}
+
+function matchesCronExpression(expression: string, date: Date) {
+  const parts = expression.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    return false;
+  }
+
+  const [minute, hour, dayOfMonth, month, dayOfWeek] = parts as [string, string, string, string, string];
+  return (
+    matchesCronField(minute, date.getMinutes(), 0, 59) &&
+    matchesCronField(hour, date.getHours(), 0, 23) &&
+    matchesCronField(dayOfMonth, date.getDate(), 1, 31) &&
+    matchesCronField(month, date.getMonth() + 1, 1, 12) &&
+    matchesCronField(dayOfWeek, date.getDay(), 0, 6)
+  );
+}
+
+function matchesCronField(field: string, value: number, min: number, max: number) {
+  return field.split(",").some((part) => matchesCronPart(part.trim(), value, min, max));
+}
+
+function matchesCronPart(part: string, value: number, min: number, max: number): boolean {
+  if (part === "*") {
+    return true;
+  }
+
+  const stepMatch = part.match(/^\*\/(\d+)$/);
+  if (stepMatch) {
+    const step = Number(stepMatch[1]);
+    return Number.isInteger(step) && step > 0 ? (value - min) % step === 0 : false;
+  }
+
+  const rangeMatch = part.match(/^(\d+)-(\d+)$/);
+  if (rangeMatch) {
+    const start = Number(rangeMatch[1]);
+    const end = Number(rangeMatch[2]);
+    return start <= value && value <= end;
+  }
+
+  const exact = Number(part);
+  return Number.isInteger(exact) && exact >= min && exact <= max && exact === value;
+}

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

@@ -0,0 +1,28 @@
+import type { RealtimeHub } from "../../realtime/hub";
+import { createHeartbeatRunsRealtimeEvent } from "../../realtime/heartbeat-runs";
+
+export function publishHeartbeatRunStatus(
+  realtimeHub: RealtimeHub | undefined,
+  input: {
+    companyId: string;
+    runId: string;
+    status: "started" | "completed" | "failed" | "skipped";
+    message?: string | null;
+    startedAt?: Date;
+    finishedAt?: Date;
+  }
+) {
+  if (!realtimeHub) {
+    return;
+  }
+  realtimeHub.publish(
+    createHeartbeatRunsRealtimeEvent(input.companyId, {
+      type: "run.status.updated",
+      runId: input.runId,
+      status: input.status,
+      message: input.message ?? null,
+      startedAt: input.startedAt?.toISOString(),
+      finishedAt: input.finishedAt?.toISOString() ?? null
+    })
+  );
+}