bopodev-api 0.1.23 → 0.1.25

package/src/routes/agents.ts

@@ -6,7 +6,13 @@ import {
   getAdapterModels,
   runAdapterEnvironmentTest
 } from "bopodev-agent-sdk";
-import { AgentCreateRequestSchema, AgentUpdateRequestSchema } from "bopodev-contracts";
+import {
+  AGENT_ROLE_LABELS,
+  AgentCreateRequestSchema,
+  AgentRoleKeySchema,
+  AgentSchema,
+  AgentUpdateRequestSchema
+} from "bopodev-contracts";
 import {
   appendAuditEvent,
   createAgent,
@@ -18,7 +24,7 @@ import {
   updateAgent
 } from "bopodev-db";
 import type { AppContext } from "../context";
-import { sendError, sendOk } from "../http";
+import { sendError, sendOk, sendOkValidated } from "../http";
 import {
   normalizeRuntimeConfig,
   parseRuntimeConfigFromAgentRow,
@@ -33,6 +39,7 @@ import { assertRuntimeCwdForCompany, hasText, resolveDefaultRuntimeCwdForCompany
 import { requireCompanyScope } from "../middleware/company-scope";
 import { requireBoardRole, requirePermission } from "../middleware/request-actor";
 import { createGovernanceRealtimeEvent, serializeStoredApproval } from "../realtime/governance";
+import { publishAttentionSnapshot } from "../realtime/attention";
 import {
   publishOfficeOccupantForAgent,
   publishOfficeOccupantForApproval
@@ -84,6 +91,8 @@ const runtimePreflightSchema = z.object({
 const UPDATE_AGENT_ALLOWED_KEYS = new Set([
   "managerAgentId",
   "role",
+  "roleKey",
+  "title",
   "name",
   "providerType",
   "status",
@@ -129,6 +138,10 @@ function providerRequiresNamedModel(providerType: string) {
   return providerType !== "http" && providerType !== "shell";
 }
 
+const agentResponseSchema = AgentSchema.extend({
+  stateBlob: z.string().optional()
+});
+
 function ensureNamedRuntimeModel(providerType: string, runtimeModel: string | undefined) {
   if (!providerRequiresNamedModel(providerType)) {
     return true;
@@ -142,9 +155,11 @@ export function createAgentsRouter(ctx: AppContext) {
 
   router.get("/", async (req, res) => {
     const rows = await listAgents(ctx.db, req.companyId!);
-    return sendOk(
+    return sendOkValidated(
       res,
-      rows.map((row) => toAgentResponse(row as unknown as Record<string, unknown>))
+      agentResponseSchema.array(),
+      rows.map((row) => toAgentResponse(row as unknown as Record<string, unknown>)),
+      "agents.list"
     );
   });
 
@@ -155,6 +170,7 @@ export function createAgentsRouter(ctx: AppContext) {
         id: row.id,
         name: row.name,
         role: row.role,
+        roleKey: row.roleKey,
         status: row.status,
         canHireAgents: row.canHireAgents
       }))
@@ -170,8 +186,7 @@ export function createAgentsRouter(ctx: AppContext) {
     return sendOk(
       res,
       rows.map((row) => {
-        const normalizedRole = row.role.trim().toLowerCase();
-        const isLeadership = normalizedRole === "ceo" || Boolean(row.canHireAgents);
+        const isLeadership = row.roleKey === "ceo" || Boolean(row.canHireAgents);
         const issues: string[] = [];
         const hasBootstrapPrompt = hasText(row.bootstrapPrompt);
         if (isLeadership && !hasBootstrapPrompt) {
@@ -184,6 +199,7 @@ export function createAgentsRouter(ctx: AppContext) {
           agentId: row.id,
           name: row.name,
           role: row.role,
+          roleKey: row.roleKey,
           providerType: row.providerType,
           canHireAgents: Boolean(row.canHireAgents),
           isLeadership,
@@ -366,7 +382,8 @@ export function createAgentsRouter(ctx: AppContext) {
     const shouldRequestApproval = (parsed.data.requestApproval || req.actor?.type === "agent") && isApprovalRequired("hire_agent");
     if (shouldRequestApproval) {
       const duplicate = await findDuplicateHireRequest(ctx.db, req.companyId!, {
-        role: parsed.data.role,
+        role: parsed.data.role ?? "",
+        roleKey: parsed.data.roleKey ?? null,
         managerAgentId: parsed.data.managerAgentId ?? null
       });
       if (duplicate) {
@@ -397,6 +414,7 @@ export function createAgentsRouter(ctx: AppContext) {
           })
         );
         await publishOfficeOccupantForApproval(ctx.db, ctx.realtimeHub, req.companyId!, approvalId);
+        await publishAttentionSnapshot(ctx.db, ctx.realtimeHub, req.companyId!);
       }
       return sendOk(res, { queuedForApproval: true, approvalId });
     }
@@ -404,7 +422,9 @@ export function createAgentsRouter(ctx: AppContext) {
     const agent = await createAgent(ctx.db, {
       companyId: req.companyId!,
       managerAgentId: parsed.data.managerAgentId,
-      role: parsed.data.role,
+      role: resolveAgentRoleText(parsed.data.role, parsed.data.roleKey, parsed.data.title),
+      roleKey: normalizeRoleKey(parsed.data.roleKey),
+      title: normalizeTitle(parsed.data.title),
       name: parsed.data.name,
       providerType: parsed.data.providerType,
       heartbeatCron: parsed.data.heartbeatCron,
@@ -543,7 +563,16 @@ export function createAgentsRouter(ctx: AppContext) {
         companyId: req.companyId!,
         id: req.params.agentId,
         managerAgentId: parsed.data.managerAgentId,
-        role: parsed.data.role,
+        role:
+          parsed.data.role !== undefined || parsed.data.roleKey !== undefined || parsed.data.title !== undefined
+            ? resolveAgentRoleText(
+                parsed.data.role ?? existingAgent.role,
+                parsed.data.roleKey ?? existingAgent.roleKey,
+                parsed.data.title ?? existingAgent.title
+              )
+            : undefined,
+        roleKey: parsed.data.roleKey !== undefined ? normalizeRoleKey(parsed.data.roleKey) : undefined,
+        title: parsed.data.title !== undefined ? normalizeTitle(parsed.data.title) : undefined,
         name: parsed.data.name,
         providerType: parsed.data.providerType,
         status: parsed.data.status,
@@ -715,14 +744,15 @@ function enforceRuntimeCwdPolicy(companyId: string, runtime: ReturnType<typeof n
 async function findDuplicateHireRequest(
   db: AppContext["db"],
   companyId: string,
-  input: { role: string; managerAgentId: string | null }
+  input: { role: string; roleKey: string | null; managerAgentId: string | null }
 ) {
   const role = input.role.trim();
+  const roleKey = normalizeRoleKey(input.roleKey);
   const managerAgentId = input.managerAgentId ?? null;
   const agents = await listAgents(db, companyId);
   const existingAgent = agents.find(
     (agent) =>
-      agent.role === role &&
+      ((roleKey && agent.roleKey === roleKey) || (!roleKey && role.length > 0 && agent.role === role)) &&
       (agent.managerAgentId ?? null) === managerAgentId &&
       agent.status !== "terminated"
   );
@@ -732,6 +762,10 @@ async function findDuplicateHireRequest(
       return false;
     }
     const payload = parseApprovalPayload(approval.payloadJson);
+    const payloadRoleKey = normalizeRoleKey(payload.roleKey);
+    if (roleKey && payloadRoleKey) {
+      return payloadRoleKey === roleKey && (payload.managerAgentId ?? null) === managerAgentId;
+    }
     return payload.role === role && (payload.managerAgentId ?? null) === managerAgentId;
   });
   if (!existingAgent && !pendingApproval) {
@@ -743,11 +777,12 @@ async function findDuplicateHireRequest(
   };
 }
 
-function parseApprovalPayload(payloadJson: string): { role?: string; managerAgentId?: string | null } {
+function parseApprovalPayload(payloadJson: string): { role?: string; roleKey?: string | null; managerAgentId?: string | null } {
   try {
     const parsed = JSON.parse(payloadJson) as Record<string, unknown>;
     return {
       role: typeof parsed.role === "string" ? parsed.role : undefined,
+      roleKey: typeof parsed.roleKey === "string" ? parsed.roleKey : null,
       managerAgentId: typeof parsed.managerAgentId === "string" ? parsed.managerAgentId : null
     };
   } catch {
@@ -780,6 +815,40 @@ function providerSupportsSkillInjection(providerType: string) {
   return providerType === "codex" || providerType === "cursor" || providerType === "opencode" || providerType === "claude_code";
 }
 
+function normalizeRoleKey(input: string | null | undefined) {
+  const normalized = input?.trim().toLowerCase();
+  if (!normalized) {
+    return null;
+  }
+  const parsed = AgentRoleKeySchema.safeParse(normalized);
+  return parsed.success ? parsed.data : null;
+}
+
+function normalizeTitle(input: string | null | undefined) {
+  const normalized = input?.trim();
+  return normalized ? normalized : null;
+}
+
+function resolveAgentRoleText(
+  legacyRole: string | undefined,
+  roleKeyInput: string | null | undefined,
+  titleInput: string | null | undefined
+) {
+  const normalizedLegacy = legacyRole?.trim();
+  if (normalizedLegacy) {
+    return normalizedLegacy;
+  }
+  const normalizedTitle = normalizeTitle(titleInput);
+  if (normalizedTitle) {
+    return normalizedTitle;
+  }
+  const roleKey = normalizeRoleKey(roleKeyInput);
+  if (roleKey) {
+    return AGENT_ROLE_LABELS[roleKey];
+  }
+  return AGENT_ROLE_LABELS.general;
+}
+
 function resolveAuditActor(actor: { type: "board" | "member" | "agent"; id: string } | undefined) {
   if (!actor) {
     return { actorType: "human" as const, actorId: null as string | null };

package/src/routes/attention.ts

@@ -0,0 +1,112 @@
+import { Router } from "express";
+import { z } from "zod";
+import { sendError, sendOkValidated } from "../http";
+import { requireCompanyScope } from "../middleware/company-scope";
+import type { AppContext } from "../context";
+import {
+  clearBoardAttentionDismissed,
+  listBoardAttentionItems,
+  markBoardAttentionAcknowledged,
+  markBoardAttentionDismissed,
+  markBoardAttentionResolved,
+  markBoardAttentionSeen
+} from "../services/attention-service";
+import { BoardAttentionListResponseSchema } from "bopodev-contracts";
+import { createAttentionRealtimeEvent } from "../realtime/attention";
+
+const itemParamsSchema = z.object({
+  itemKey: z.string().min(1)
+});
+
+export function createAttentionRouter(ctx: AppContext) {
+  const router = Router();
+  router.use(requireCompanyScope);
+
+  // Canonical board action queue endpoint for Inbox and board attention UX.
+  router.get("/", async (req, res) => {
+    const actorId = req.actor?.id ?? "local-board";
+    const items = await listBoardAttentionItems(ctx.db, req.companyId!, actorId);
+    return sendOkValidated(res, BoardAttentionListResponseSchema, { actorId, items }, "attention.list");
+  });
+
+  router.post("/:itemKey/seen", async (req, res) => {
+    const parsed = itemParamsSchema.safeParse(req.params);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const actorId = req.actor?.id ?? "local-board";
+    await markBoardAttentionSeen(ctx.db, req.companyId!, actorId, parsed.data.itemKey);
+    await publishAttentionUpdate(ctx, req.companyId!, actorId, parsed.data.itemKey);
+    return sendOkValidated(res, z.object({ ok: z.literal(true) }), { ok: true }, "attention.seen");
+  });
+
+  router.post("/:itemKey/acknowledge", async (req, res) => {
+    const parsed = itemParamsSchema.safeParse(req.params);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const actorId = req.actor?.id ?? "local-board";
+    await markBoardAttentionAcknowledged(ctx.db, req.companyId!, actorId, parsed.data.itemKey);
+    await publishAttentionUpdate(ctx, req.companyId!, actorId, parsed.data.itemKey);
+    return sendOkValidated(res, z.object({ ok: z.literal(true) }), { ok: true }, "attention.acknowledge");
+  });
+
+  router.post("/:itemKey/dismiss", async (req, res) => {
+    const parsed = itemParamsSchema.safeParse(req.params);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const actorId = req.actor?.id ?? "local-board";
+    await markBoardAttentionDismissed(ctx.db, req.companyId!, actorId, parsed.data.itemKey);
+    await publishAttentionUpdate(ctx, req.companyId!, actorId, parsed.data.itemKey);
+    return sendOkValidated(res, z.object({ ok: z.literal(true) }), { ok: true }, "attention.dismiss");
+  });
+
+  router.post("/:itemKey/undismiss", async (req, res) => {
+    const parsed = itemParamsSchema.safeParse(req.params);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const actorId = req.actor?.id ?? "local-board";
+    await clearBoardAttentionDismissed(ctx.db, req.companyId!, actorId, parsed.data.itemKey);
+    await publishAttentionUpdate(ctx, req.companyId!, actorId, parsed.data.itemKey);
+    return sendOkValidated(res, z.object({ ok: z.literal(true) }), { ok: true }, "attention.undismiss");
+  });
+
+  router.post("/:itemKey/resolve", async (req, res) => {
+    const parsed = itemParamsSchema.safeParse(req.params);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const actorId = req.actor?.id ?? "local-board";
+    await markBoardAttentionResolved(ctx.db, req.companyId!, actorId, parsed.data.itemKey);
+    await publishAttentionResolve(ctx, req.companyId!, actorId, parsed.data.itemKey);
+    return sendOkValidated(res, z.object({ ok: z.literal(true) }), { ok: true }, "attention.resolve");
+  });
+
+  return router;
+}
+
+async function publishAttentionUpdate(ctx: AppContext, companyId: string, actorId: string, itemKey: string) {
+  const items = await listBoardAttentionItems(ctx.db, companyId, actorId);
+  const item = items.find((entry) => entry.key === itemKey);
+  if (!item) {
+    return;
+  }
+  ctx.realtimeHub?.publish(
+    createAttentionRealtimeEvent(companyId, {
+      type: "attention.updated",
+      item
+    })
+  );
+}
+
+async function publishAttentionResolve(ctx: AppContext, companyId: string, actorId: string, itemKey: string) {
+  await publishAttentionUpdate(ctx, companyId, actorId, itemKey);
+  ctx.realtimeHub?.publish(
+    createAttentionRealtimeEvent(companyId, {
+      type: "attention.resolved",
+      key: itemKey
+    })
+  );
+}

package/src/routes/companies.ts

@@ -2,9 +2,10 @@ import { mkdir } from "node:fs/promises";
 import type { NextFunction, Request, Response } from "express";
 import { Router } from "express";
 import { z } from "zod";
+import { CompanySchema } from "bopodev-contracts";
 import { createAgent, createCompany, deleteCompany, listCompanies, updateCompany } from "bopodev-db";
 import type { AppContext } from "../context";
-import { sendError, sendOk } from "../http";
+import { sendError, sendOk, sendOkValidated } from "../http";
 import { normalizeRuntimeConfig, resolveRuntimeModelForProvider, runtimeConfigToDb, runtimeConfigToStateBlobPatch } from "../lib/agent-config";
 import { buildDefaultCeoBootstrapPrompt } from "../lib/ceo-bootstrap-prompt";
 import { resolveOpencodeRuntimeModel } from "../lib/opencode-model";
@@ -37,14 +38,19 @@ export function createCompaniesRouter(ctx: AppContext) {
   const router = Router();
 
   router.get("/", async (req, res) => {
-    const companies = await listCompanies(ctx.db);
+    const companies = (await listCompanies(ctx.db)).map((company) => ({
+      ...company,
+      createdAt: company.createdAt instanceof Date ? company.createdAt.toISOString() : String(company.createdAt)
+    }));
     if (req.actor?.type === "board") {
-      return sendOk(res, companies);
+      return sendOkValidated(res, CompanySchema.array(), companies, "companies.list");
     }
     const visibleCompanyIds = new Set(req.actor?.companyIds ?? []);
-    return sendOk(
+    return sendOkValidated(
       res,
-      companies.filter((company) => visibleCompanyIds.has(company.id))
+      CompanySchema.array(),
+      companies.filter((company) => visibleCompanyIds.has(company.id)),
+      "companies.list.filtered"
     );
   });
 
@@ -91,6 +97,8 @@ export function createCompaniesRouter(ctx: AppContext) {
     await createAgent(ctx.db, {
       companyId: company.id,
       role: "CEO",
+      roleKey: "ceo",
+      title: "CEO",
       name: "CEO",
       providerType,
       heartbeatCron: "*/5 * * * *",

package/src/routes/goals.ts

@@ -1,11 +1,13 @@
 import { Router } from "express";
 import { z } from "zod";
+import { GoalSchema } from "bopodev-contracts";
 import { appendAuditEvent, createApprovalRequest, createGoal, deleteGoal, getApprovalRequest, listGoals, updateGoal } from "bopodev-db";
 import type { AppContext } from "../context";
-import { sendError, sendOk } from "../http";
+import { sendError, sendOk, sendOkValidated } from "../http";
 import { requireCompanyScope } from "../middleware/company-scope";
 import { requirePermission } from "../middleware/request-actor";
 import { createGovernanceRealtimeEvent, serializeStoredApproval } from "../realtime/governance";
+import { publishAttentionSnapshot } from "../realtime/attention";
 import { isApprovalRequired } from "../services/governance-service";
 
 const createGoalSchema = z.object({
@@ -33,7 +35,12 @@ export function createGoalsRouter(ctx: AppContext) {
   router.use(requireCompanyScope);
 
   router.get("/", async (req, res) => {
-    return sendOk(res, await listGoals(ctx.db, req.companyId!));
+    return sendOkValidated(
+      res,
+      GoalSchema.array(),
+      await listGoals(ctx.db, req.companyId!),
+      "goals.list"
+    );
   });
 
   router.post("/", async (req, res) => {
@@ -60,6 +67,7 @@ export function createGoalsRouter(ctx: AppContext) {
             approval: serializeStoredApproval(approval)
           })
         );
+        await publishAttentionSnapshot(ctx.db, ctx.realtimeHub, req.companyId!);
       }
       return sendOk(res, { queuedForApproval: true, approvalId });
     }

package/src/routes/governance.ts

@@ -15,6 +15,7 @@ import { sendError, sendOk } from "../http";
 import { requireCompanyScope } from "../middleware/company-scope";
 import { requirePermission } from "../middleware/request-actor";
 import { createGovernanceRealtimeEvent, serializeStoredApproval } from "../realtime/governance";
+import { publishAttentionSnapshot } from "../realtime/attention";
 import {
   publishOfficeOccupantForAgent,
   publishOfficeOccupantForApproval
@@ -34,6 +35,9 @@ export function createGovernanceRouter(ctx: AppContext) {
   const router = Router();
   router.use(requireCompanyScope);
 
+  // Deprecated compatibility shim:
+  // board queue consumers should use /attention as the canonical source.
+  // Keep this endpoint until all downstream consumers migrate.
   router.get("/approvals", async (req, res) => {
     const approvals = await listApprovalRequests(ctx.db, req.companyId!);
     return sendOk(
@@ -200,6 +204,7 @@ export function createGovernanceRouter(ctx: AppContext) {
           approval: serializeStoredApproval(approval)
         })
       );
+      await publishAttentionSnapshot(ctx.db, ctx.realtimeHub, req.companyId!);
       await publishOfficeOccupantForApproval(ctx.db, ctx.realtimeHub, req.companyId!, approval.id);
       if (approval.requestedByAgentId) {
         await publishOfficeOccupantForAgent(ctx.db, ctx.realtimeHub, req.companyId!, approval.requestedByAgentId);

package/src/routes/heartbeats.ts

@@ -1,12 +1,17 @@
 import { Router } from "express";
 import { z } from "zod";
 import { and, eq } from "drizzle-orm";
-import { agents, heartbeatRuns } from "bopodev-db";
+import { agents, heartbeatRuns, listHeartbeatQueueJobs } from "bopodev-db";
 import type { AppContext } from "../context";
 import { sendError, sendOk } from "../http";
 import { requireCompanyScope } from "../middleware/company-scope";
 import { requirePermission } from "../middleware/request-actor";
-import { runHeartbeatForAgent, runHeartbeatSweep, stopHeartbeatRun } from "../services/heartbeat-service";
+import {
+  findPendingProjectBudgetOverrideBlocksForAgent,
+  runHeartbeatSweep,
+  stopHeartbeatRun
+} from "../services/heartbeat-service";
+import { enqueueHeartbeatQueueJob, triggerHeartbeatQueueWorker } from "../services/heartbeat-queue-service";
 
 const runAgentSchema = z.object({
   agentId: z.string().min(1)
@@ -14,6 +19,12 @@ const runAgentSchema = z.object({
 const runIdParamsSchema = z.object({
   runId: z.string().min(1)
 });
+const queueQuerySchema = z.object({
+  status: z.enum(["pending", "running", "completed", "failed", "dead_letter", "canceled"]).optional(),
+  agentId: z.string().min(1).optional(),
+  jobType: z.enum(["manual", "scheduler", "resume", "redo", "comment_dispatch"]).optional(),
+  limit: z.coerce.number().int().min(1).max(1000).optional()
+});
 
 export function createHeartbeatRouter(ctx: AppContext) {
   const router = Router();
@@ -39,31 +50,37 @@ export function createHeartbeatRouter(ctx: AppContext) {
     if (agent.status === "paused" || agent.status === "terminated") {
       return sendError(res, `Agent is not invokable in status '${agent.status}'.`, 409);
     }
+    const blockedProjectIds = await findPendingProjectBudgetOverrideBlocksForAgent(
+      ctx.db,
+      req.companyId!,
+      parsed.data.agentId
+    );
+    if (blockedProjectIds.length > 0) {
+      return sendError(
+        res,
+        `Agent is blocked by pending project budget approval for project(s): ${blockedProjectIds.join(", ")}.`,
+        423
+      );
+    }
 
-    const runId = await runHeartbeatForAgent(ctx.db, req.companyId!, parsed.data.agentId, {
+    const job = await enqueueHeartbeatQueueJob(ctx.db, {
+      companyId: req.companyId!,
+      agentId: parsed.data.agentId,
+      jobType: "manual",
+      priority: 30,
+      idempotencyKey: req.requestId ? `manual:${parsed.data.agentId}:${req.requestId}` : null,
+      payload: {}
+    });
+    triggerHeartbeatQueueWorker(ctx.db, req.companyId!, {
       requestId: req.requestId,
-      trigger: "manual",
       realtimeHub: ctx.realtimeHub
     });
-    if (!runId) {
-      return sendError(res, "Heartbeat could not be started for this agent.", 409);
-    }
-    const [runRow] = await ctx.db
-      .select({ id: heartbeatRuns.id, status: heartbeatRuns.status, message: heartbeatRuns.message })
-      .from(heartbeatRuns)
-      .where(and(eq(heartbeatRuns.companyId, req.companyId!), eq(heartbeatRuns.id, runId)))
-      .limit(1);
-    const invokeStatus =
-      runRow?.status === "skipped" && String(runRow.message ?? "").includes("already in progress")
-        ? "skipped_overlap"
-        : runRow?.status === "skipped"
-          ? "skipped"
-          : "started";
     return sendOk(res, {
-      runId,
+      runId: null,
+      jobId: job.id,
       requestId: req.requestId,
-      status: invokeStatus,
-      message: runRow?.message ?? null
+      status: "queued",
+      message: "Heartbeat queued."
     });
   });
 
@@ -127,32 +144,32 @@ export function createHeartbeatRouter(ctx: AppContext) {
     if (agent.status === "paused" || agent.status === "terminated") {
       return { ok: false as const, statusCode: 409, message: `Agent is not invokable in status '${agent.status}'.` };
     }
-    const nextRunId = await runHeartbeatForAgent(ctx.db, input.companyId, run.agentId, {
+    const blockedProjectIds = await findPendingProjectBudgetOverrideBlocksForAgent(ctx.db, input.companyId, run.agentId);
+    if (blockedProjectIds.length > 0) {
+      return {
+        ok: false as const,
+        statusCode: 423,
+        message: `Agent is blocked by pending project budget approval for project(s): ${blockedProjectIds.join(", ")}.`
+      };
+    }
+    const job = await enqueueHeartbeatQueueJob(ctx.db, {
+      companyId: input.companyId,
+      agentId: run.agentId,
+      jobType: input.mode,
+      priority: 30,
+      idempotencyKey: input.requestId ? `${input.mode}:${run.agentId}:${run.id}:${input.requestId}` : null,
+      payload: { sourceRunId: run.id }
+    });
+    triggerHeartbeatQueueWorker(ctx.db, input.companyId, {
       requestId: input.requestId,
-      trigger: "manual",
-      realtimeHub: ctx.realtimeHub,
-      mode: input.mode,
-      sourceRunId: run.id
+      realtimeHub: ctx.realtimeHub
     });
-    if (!nextRunId) {
-      return { ok: false as const, statusCode: 409, message: "Heartbeat could not be started for this agent." };
-    }
-    const [runRow] = await ctx.db
-      .select({ id: heartbeatRuns.id, status: heartbeatRuns.status, message: heartbeatRuns.message })
-      .from(heartbeatRuns)
-      .where(and(eq(heartbeatRuns.companyId, input.companyId), eq(heartbeatRuns.id, nextRunId)))
-      .limit(1);
-    const invokeStatus =
-      runRow?.status === "skipped" && String(runRow.message ?? "").includes("already in progress")
-        ? "skipped_overlap"
-        : runRow?.status === "skipped"
-          ? "skipped"
-          : "started";
     return {
       ok: true as const,
-      runId: nextRunId,
-      status: invokeStatus,
-      message: runRow?.message ?? null
+      runId: null,
+      jobId: job.id,
+      status: "queued" as const,
+      message: "Heartbeat queued."
     };
   }
 
@@ -176,6 +193,7 @@ export function createHeartbeatRouter(ctx: AppContext) {
     }
     return sendOk(res, {
       runId: result.runId,
+      jobId: result.jobId,
       requestId: req.requestId,
       status: result.status,
       message: result.message
@@ -202,6 +220,7 @@ export function createHeartbeatRouter(ctx: AppContext) {
     }
     return sendOk(res, {
       runId: result.runId,
+      jobId: result.jobId,
       requestId: req.requestId,
       status: result.status,
       message: result.message
@@ -220,5 +239,24 @@ export function createHeartbeatRouter(ctx: AppContext) {
     return sendOk(res, { runIds, requestId: req.requestId });
   });
 
+  router.get("/queue", async (req, res) => {
+    requirePermission("heartbeats:run")(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const parsed = queueQuerySchema.safeParse(req.query);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const jobs = await listHeartbeatQueueJobs(ctx.db, {
+      companyId: req.companyId!,
+      status: parsed.data.status,
+      agentId: parsed.data.agentId,
+      jobType: parsed.data.jobType,
+      limit: parsed.data.limit
+    });
+    return sendOk(res, { items: jobs });
+  });
+
   return router;
 }